caspian-utils 0.0.11 → 0.0.13

package/dist/docs/auth.md

@@ -3,7 +3,7 @@ title: Authentication
 description: Manage session-backed authentication in Caspian with `casp.auth`, `AuthSettings`, the global `auth` object, centralized `auth_config.py`, page decorators, RPC protection, role-based routes, and optional Google or GitHub OAuth providers.
 related:
   title: Related docs
-    description: Use the fetch-data guide when sign-in 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.
+  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/fetch-data
     - /docs/state
@@ -50,6 +50,7 @@ from casp.auth import (
 
 - Define app-wide auth behavior in `build_auth_settings()` and apply it once at startup with `configure_auth(...)`.
 - Use `auth.sign_in(...)` and `auth.sign_out(...)` instead of setting or clearing session keys directly.
+- Prefer `pp.rpc(...)` plus `@rpc(require_auth=True)` for signout buttons or menus rendered in pages or components. Use a dedicated signout route only when you need a plain HTML form POST or a no-JavaScript fallback.
 - Use `@require_auth`, `@require_role`, and `@guest_only` for page access rules.
 - Use `@rpc(require_auth=True, allowed_roles=[...])` for browser-triggered actions that need protection.
 - Use `StateManager` only for transient auth-adjacent request state; keep the authenticated session itself owned by `casp.auth`.
@@ -112,12 +113,52 @@ Important behavior from the current implementation:
 - `default_token_validity` is parsed by the installed auth runtime with the format `^\d+(s|m|h|d)$`. Use values such as `30m`, `1h`, or `7d`.
 - `token_auto_refresh` only changes behavior when the request lifecycle calls `auth.refresh_session()`. In the installed `auth.py`, the flag alone does not refresh expiry by itself.
 - The framework `AuthSettings` dataclass defaults `is_all_routes_private=True`, but the project example above explicitly changes that to `False`.
+- In generated app-owned config like this workspace, `src/lib/auth/auth_config.py` starts with `is_all_routes_private=False`, so routes are public by default until the app chooses stricter route protection.
 - `public_routes`, `auth_routes`, `private_routes`, and `role_based_routes` are exact path matches in the installed `Auth` methods.
 - `private_routes` matters only when `is_all_routes_private=False`.
 - `role_based_routes` currently expects `PATH -> [ROLES]`, not role names keyed to paths the other way around.
 - `role_identifier` defaults to `role`, and the current `auth.sign_in(...)` flow also normalizes `userRole` into `role` when possible.
 - `api_auth_prefix` defaults to `/api/auth` and should stay centralized here rather than being hard-coded across routes.
 
+## Choosing Public vs Private Route Mode
+
+Make this decision at app setup time in `src/lib/auth/auth_config.py`.
+
+- In the default app-owned starter pattern used in this workspace, routes start public because `is_all_routes_private=False` in `src/lib/auth/auth_config.py`.
+- If the application has only a few public pages and most routes require auth, set `is_all_routes_private=True` and list the exceptions in `public_routes`.
+- If the application has many public pages and only a few protected areas, keep `is_all_routes_private=False` and list only the protected routes in `private_routes`.
+- In the current runtime, `auth_routes=["/signin", "/signup"]` stays public by default, and most apps do not need to change it unless the user explicitly asks for different auth routes.
+- In all-private mode, the default `public_routes=["/"]` keeps the home page public unless you change that list.
+- `token_auto_refresh=True` does not make routes private. It only enables sliding-session refresh when the request lifecycle calls `auth.refresh_session()`.
+- You do not need to modify Caspian core files for this decision. Keep the policy in `src/lib/auth/auth_config.py`.
+- If you customize `src/lib/auth/auth_config.py`, add it to `excludeFiles` in `caspian.config.json` so update commands do not overwrite your local auth policy.
+
+Example all-private setup with a few public exceptions:
+
+```python
+return AuthSettings(
+    default_token_validity="1h",
+    token_auto_refresh=False,
+    is_all_routes_private=True,
+    public_routes=["/", "/pricing", "/about"],
+    auth_routes=["/signin", "/signup"],
+    private_routes=[],
+)
+```
+
+Example mixed app with many public routes and only a few protected areas:
+
+```python
+return AuthSettings(
+    default_token_validity="1h",
+    token_auto_refresh=False,
+    is_all_routes_private=False,
+    public_routes=["/"],
+    auth_routes=["/signin", "/signup"],
+    private_routes=["/dashboard", "/settings", "/billing"],
+)
+```
+
 ## Environment Variables
 
 The installed auth code reads several values from `.env` when explicit values are not passed.
@@ -414,16 +455,58 @@ src/
             signup/
                 index.py
                 index.html
-        signout/
-            index.py
+            signout/
+                index.py
         dashboard/
             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, and protect private destinations with `require_auth()` or central route policy.
+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.
+
+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.
+
+```html
+<div>
+    <button onclick="signout()">
+        Sign out
+    </button>
+
+    <script>
+        async function signout() {
+            await pp.rpc("signout");
+        }
+    </script>
+</div>
+```
+
+```python
+from casp.auth import auth
+from casp.rpc import rpc
+
+
+@rpc(require_auth=True)
+def signout():
+    return auth.sign_out()
+```
+
+Fallback signout pattern: dedicated route.
+
+Use this when you need a plain HTML form POST, a no-JavaScript fallback, or a full-route signout endpoint.
+
+HTML:
+
+```html
+<form action="/signout" method="post">
+    <button type="submit">
+        <span>Log Out</span>
+    </button>
+</form>
+```
 
-Simple signout route example:
+Route: `src/app/(auth)/signout/index.py`
 
 ```python
 from casp.auth import auth, require_auth
@@ -659,11 +742,17 @@ Validate and authenticate close to the input boundary.
 Common placement patterns are:
 
 - put centralized policy in `src/lib/auth/auth_config.py`
+- decide public-vs-private route mode at app start in `src/lib/auth/auth_config.py` instead of scattering route privacy logic across route files
+- use `is_all_routes_private=True` only when most routes should require auth; otherwise keep `is_all_routes_private=False` and maintain `private_routes`
+- keep public exceptions in `public_routes`, and leave `auth_routes=["/signin", "/signup"]` alone unless the app explicitly needs different auth endpoints
 - call `configure_auth(build_auth_settings())` during startup
-- keep sign-in, signup, signout, and reset-password handlers in the owning route backend under `src/app/**/index.py`
+- keep sign-in, signup, and reset-password handlers in the owning route backend under `src/app/**/index.py`
+- prefer signout through `pp.rpc("signout")` with `@rpc(require_auth=True)` when the trigger lives in page or component UI
+- use a dedicated signout route only for no-JavaScript, form-post, or full-navigation edge cases
 - use `@rpc()` for browser-triggered auth actions and page decorators for full-route protection
 - use `Validate` and `Rule` from `casp.validate` before password checks, user lookup, persistence, or external provider flows
 - keep reusable auth helpers in `src/lib/auth/`
+- protect customized auth policy files from updater overwrite with `excludeFiles` in `caspian.config.json`
 
 For browser-triggered auth forms, pair this page with `fetch-data.md`. For credential and form validation, pair it with `validation.md`.
 
@@ -673,15 +762,22 @@ If an AI agent is deciding how to handle auth in Caspian, apply these rules firs
 
 - Treat `casp.auth` as the default authentication layer.
 - Centralize route visibility, redirects, and RBAC policy in `src/lib/auth/auth_config.py`.
+- 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 like this workspace, 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.
 - 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.
+- Prefer `pp.rpc("signout")` plus `@rpc(require_auth=True)` for logout buttons or menus in pages and components.
+- Use a dedicated `/signout` route only for plain HTML form POST, no-JavaScript fallback, or other full-navigation edge cases.
+- Do not treat `token_auto_refresh` as a route-privacy switch. In the current app it only affects sliding-session refresh if `auth.refresh_session()` is called.
 - Use `@require_auth`, `@require_role`, and `@guest_only` for page-level access rules.
 - Use `@rpc(require_auth=True, allowed_roles=[...])` for protected browser-triggered actions.
 - Keep `SessionMiddleware` outermost so auth, CSRF, and RPC handlers can read `request.session`.
 - Use [state.md](./state.md) only for transient auth-adjacent request state, not as the auth session store.
 - Align `SESSION_LIFETIME_HOURS` with `default_token_validity` unless you intentionally want different cookie and auth-payload expiry windows.
 - Prefer exact route strings in `public_routes`, `auth_routes`, `private_routes`, and `role_based_routes`.
+- Protect customized `src/lib/auth/auth_config.py` from updater overwrite by adding it to `excludeFiles` in `caspian.config.json`.
 - Keep auth secrets and OAuth provider credentials in `.env`.
 - Set `AUTH_COOKIE_NAME` explicitly so the session middleware cookie name and auth settings stay aligned.
 - Use `.venv/Lib/site-packages/casp/auth.py` only when the task is about framework auth internals or debugging installed behavior.

package/dist/docs/commands.md

@@ -19,7 +19,7 @@ This page documents the current Caspian command families used with this workspac
 
 The current workspace includes a local `prisma` binary, but it does not include local `create-caspian-app`, `casp`, or `ppy` binaries under `node_modules/.bin`. Treat project creation, project update, and Python ORM generation as external `npx` workflows rather than project-local executables.
 
-The current workspace also includes a local MCP run path through `npm run mcp`, which starts the app-owned FastMCP server via `settings/restart-mcp.ts`.
+The current workspace `package.json` defines `projectName`, `tailwind`, `tailwind:build`, `browserSync`, `browserSync:build`, `dev`, and `build`. It does not currently define `npm run mcp` because `caspian.config.json` has `mcp: false`.
 
 Examples below use `npx create-caspian-app` for readability. If you want to force the latest published scaffold package explicitly, you can use `npx create-caspian-app@latest` instead.
 
@@ -32,7 +32,9 @@ This updated reference includes the newer updater behavior and the current scaff
 - Windows-safe execution that resolves `npx.cmd` on Win32
 - scaffold behavior that reuses an existing `.venv` instead of recreating it every time
 
-Before running update commands, read `caspian.config.json` because it controls feature flags and `excludeFiles` overwrite protection. In the current workspace that config shows `backendOnly: false`, `tailwindcss: true`, `mcp: true`, `prisma: true`, `typescript: false`, and `componentScanDirs: ["src"]`.
+Before running update commands, read `caspian.config.json` because it controls feature flags and `excludeFiles` overwrite protection. In the current workspace that config shows `backendOnly: false`, `tailwindcss: true`, `mcp: false`, `prisma: true`, `typescript: false`, and `componentScanDirs: ["src"]`.
+
+Treat `caspian.config.json` as the single source of truth for optional feature enablement. Use feature-specific docs, files, or commands only after the matching flag is confirmed as enabled.
 
 ## 1. Main Command Families
 
@@ -69,37 +71,27 @@ npx casp update project
 
 Use when you are inside an existing Caspian project and want to refresh framework-managed files using the project's `caspian.config.json`.
 
-### Run the local MCP server
-
-```bash
-npm run mcp
-```
+This is also the workflow to use after the user chooses to enable or disable an optional feature in `caspian.config.json`.
 
-Use when you want the workspace's app-owned FastMCP server only.
-
-### Run the full local stack including MCP
+### Run the full local stack
 
 ```bash
 npm run dev
 ```
 
-Use when you want BrowserSync, Tailwind, the Python app server, and MCP together.
-
-### Inspect the local MCP config directly
+Use when the user explicitly wants the local BrowserSync plus PostCSS development stack.
 
-```powershell
-.venv\Scripts\fastmcp.exe inspect src/lib/mcp/fastmcp.json
-```
+In this workspace, `npm run dev` is a long-running command that can regenerate framework-owned outputs such as `public/css/styles.css`, `settings/component-map.json`, `settings/files-list.json`, `__pycache__/`, and `.pyc` files.
 
-Use when you are debugging the nested FastMCP config or checking which tools the current MCP server exposes.
+### Build generated assets for deployment
 
-### Run FastMCP directly with the nested config
-
-```powershell
-.venv\Scripts\fastmcp.exe run src/lib/mcp/fastmcp.json --no-banner
+```bash
+npm run build
 ```
 
-Use when you want the raw FastMCP path without the npm wrapper.
+Use when preparing deployment or when the user explicitly asks for a build.
+
+Do not use `npm run build` as the default validation step for routine route, feature, or documentation edits.
 
 ### Regenerate ORM after schema changes
 
@@ -115,9 +107,19 @@ npx ppy generate
 
 Use when `prisma/schema.prisma` changes and you need migrations, seed flow, and the generated Python ORM layer to stay aligned.
 
-Because this workspace keeps `fastmcp.json` under `src/lib/mcp/`, plain `fastmcp run` from the project root does not auto-detect the config. Use `npm run mcp` or pass the explicit config path.
+## 2. Script Guardrails
 
-## 2. Supported Flags And Options
+- Before using an optional feature, confirm its flag in `caspian.config.json`.
+- If the flag is false and the user wants that feature, ask first, then update `caspian.config.json` and run `npx casp update project` before assuming feature-managed files or scripts exist.
+- Do not run `package.json` scripts by default just because source files changed.
+- Treat `npm run dev` and `npm run build` as opt-in workflows.
+- Use `npm run dev` only when the user explicitly asks to start the local stack or the task truly needs that running workflow.
+- Use `npm run build` only for deployment prep or an explicit build request.
+- Treat `public/css/styles.css`, `settings/component-map.json`, `settings/files-list.json`, `__pycache__/`, and `.pyc` files as generated outputs when a script intentionally runs.
+- Analyze `settings/component-map.json` and `settings/files-list.json` when needed, but do not hand-edit them. `settings/component-map.ts` and `settings/files-list.ts` regenerate them during the intentional dev and build flows.
+- Do not edit `__pycache__/` directories or `.pyc` files, and do not leave them in the final diff.
+
+## 3. Supported Flags And Options
 
 ### For `create-caspian-app`
 
@@ -147,9 +149,9 @@ Because this workspace keeps `fastmcp.json` under `src/lib/mcp/`, plain `fastmcp
 
 The updater throws an error if conflicting version sources are provided.
 
-## 3. Create Command Combinations
+## 4. Create Command Combinations
 
-### 3.1 Base create command
+### 4.1 Base create command
 
 #### Interactive create
 
@@ -175,7 +177,7 @@ In skip-prompt mode, the default feature values are:
 - `mcp: false`
 - `prisma: false`
 
-### 3.2 Backend-only combinations
+### 4.2 Backend-only combinations
 
 In backend-only mode, the main meaningful toggles are `--mcp` and `--prisma`. Frontend-oriented flags may still appear in raw CLI args, but they are not part of the normal backend-only feature flow.
 
@@ -225,7 +227,7 @@ npx create-caspian-app my-app --backend-only --tailwindcss --typescript
 
 These flags can be present in raw CLI args, but backend-only mode removes frontend assets and disables the normal TypeScript and frontend path, so they are not practical combinations.
 
-### 3.3 Full-stack combinations
+### 4.3 Full-stack combinations
 
 These apply when `--backend-only` is not used.
 
@@ -373,7 +375,7 @@ npx create-caspian-app my-app --tailwindcss --typescript --mcp --prisma -y
 
 Use when you want the most complete default full-stack configuration.
 
-## 4. Starter Kit Command Combinations
+## 5. Starter Kit Command Combinations
 
 ### Built-in starter kits
 
@@ -471,7 +473,7 @@ npx create-caspian-app my-app --starter-kit=custom --starter-kit-source=https://
 
 Use when the scaffold should come from an external Git repository. The CLI clones the repository, removes `.git`, and updates project config for the new project.
 
-## 5. Update Command Combinations
+## 6. Update Command Combinations
 
 The updater recognizes only the `update project` command family. Anything outside that family is rejected by the wrapper.
 
@@ -545,7 +547,7 @@ npx casp update project --version=1.2.3 -y
 
 Use for automated pinned upgrades.
 
-## 6. Invalid Or Conflicting Update Cases
+## 7. Invalid Or Conflicting Update Cases
 
 These cases matter because the newer updater parsing is stricter.
 
@@ -575,7 +577,7 @@ npx casp update project 1.2.3 --version 2.0.0
 
 Result: parsing error because more than one version source was provided.
 
-## 7. Prisma And Python ORM Regeneration
+## 8. Prisma And Python ORM Regeneration
 
 The create and update commands above are not the whole maintenance story for this workspace. When `prisma/schema.prisma` changes, follow the ORM flow below so the TypeScript Prisma client, database state, and Python ORM layer stay aligned.
 
@@ -608,7 +610,7 @@ Do not manually create or edit these generated files:
 
 See [database.md](./database.md) for the full schema, migration, seed, and async usage guide.
 
-## 8. Practical Recommendation Matrix
+## 9. Practical Recommendation Matrix
 
 | Goal | Recommended command |
 | --- | --- |
@@ -623,7 +625,7 @@ See [database.md](./database.md) for the full schema, migration, seed, and async
 | Update current project to an exact version | `npx casp update project --version 1.2.3 -y` |
 | Regenerate Python ORM after schema changes | `npx prisma migrate dev` then optional seed commands, then `npx ppy generate` |
 
-## 9. Configuration Notes
+## 10. Configuration Notes
 
 The CLI reads `caspian.config.json` to decide how it should interact with the project.
 
@@ -643,9 +645,13 @@ This is useful for protecting:
 - entry-point files
 - other locally modified framework-managed files
 
+Auth example:
+
+- add `./src/lib/auth/auth_config.py` to `excludeFiles` when you customize route privacy policy, public-route exceptions, redirects, or other app-specific auth settings there
+
 If you exclude a file, the updater preserves it, but you are responsible for merging future framework changes into that file manually.
 
-## 10. Operational Notes
+## 11. Operational Notes
 
 1. On Windows, the updater resolves `npx.cmd` instead of plain `npx`, which makes execution more reliable on Win32.
 2. The updater still requires `caspian.config.json` in the current directory before running an update.

package/dist/docs/database.md

@@ -16,6 +16,8 @@ This page documents the Prisma workflow present in this workspace.
 
 This repo currently uses Prisma for schema management, migrations, and seed tooling on the Node side. The local `prisma/schema.prisma` uses `generator client { provider = "prisma-client-js" }`, `prisma.config.ts` seeds through `tsx prisma/seed.ts`, and this workspace already includes an app-owned Python database layer under `src/lib/prisma/`. If Python routes or RPC actions need database access, reuse that package instead of creating another helper.
 
+Treat `caspian.config.json` as the single source of truth for whether Prisma is enabled in a workspace. If `prisma` is false and the user wants Prisma, ask first, then update `caspian.config.json` and run `npx casp update project` before assuming Prisma-managed files exist.
+
 ## Overview
 
 The standard Prisma flow in Caspian is:

package/dist/docs/fetch-data.md

@@ -20,7 +20,7 @@ This page explains how data fetching works in Caspian. Use route functions for i
 
 Treat RPC as the default way for browser code to talk to Python in Caspian. 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. In this workspace, MCP tool definitions live under `src/lib/mcp/` and are documented in `mcp.md`.
+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`. In this workspace, `mcp: false`, so do not assume those files exist.
 
 ## Overview
 
@@ -73,7 +73,7 @@ Notes:
 - 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()`.
 - Keep reusable database or API clients under `src/lib/`; keep route-specific orchestration in `src/app/`.
 
-If the data source is Prisma, see `database.md` for the current workspace's schema, migration, and generation workflow. This scaffold does not generate Python-side Prisma helpers under `src/lib/` by default.
+If the data source is Prisma, confirm `caspian.config.json` has `prisma: true`, then see `database.md` for the current workspace's schema, migration, and generation workflow. In this workspace, Prisma is enabled and the app-owned Python database layer lives under `src/lib/prisma/`.
 
 ## Interactive Data With RPC
 

package/dist/docs/index.md

@@ -16,6 +16,8 @@ This directory contains the local Caspian documentation set for quick reference
 
 Before making feature, tooling, or file-placement decisions in a Caspian workspace, read `./caspian.config.json` almost immediately. That file is the project feature gate and tells you which capabilities are enabled, such as Prisma, MCP, TypeScript, Tailwind, backend-only mode, and component scan directories.
 
+Treat `caspian.config.json` as the single source of truth for optional feature enablement. Use feature-specific docs only after the matching flag is confirmed as enabled. If a feature is disabled and the user wants it, ask whether they want to enable it first, then follow the update workflow in `commands.md`.
+
 ## Default Stack
 
 When generating or editing a Caspian app, treat these as the default choices unless the task explicitly requires something else:
@@ -38,9 +40,9 @@ The packaged Caspian docs distributed by the current toolchain also live here:
 
 - `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
-- `mcp.md` - Workspace FastMCP server layout, nested config path, local launch flow, and MCP-specific AI routing rules
-- `database.md` - Prisma schema, migration, seed, and client-generation workflow for the current workspace, plus Python-side helper caveats
-- `auth.md` - Session-backed authentication with `casp.auth`, centralized `auth_config.py`, decorators, RBAC, and OAuth provider helpers
+- `mcp.md` - MCP-specific layout, launch flow, and AI routing rules for workspaces where `caspian.config.json` enables MCP
+- `database.md` - Prisma schema, migration, seed, and client-generation workflow for workspaces 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
 - `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
@@ -59,11 +61,15 @@ 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. Use it to confirm which project capabilities are enabled and which directories or tooling rules apply.
-3. Read `database.md` for Prisma setup and ORM usage, `mcp.md` for the current FastMCP server layout and local run flow, `auth.md` for session auth and route protection, `components.md` for reusable UI authoring, `pulsepoint.md` for browser-side reactive runtime behavior, `fetch-data.md` for data flows, `state.md` for transient request-scoped state, `cache.md` for page caching, and `validation.md` for input boundaries.
-4. For authored component, route, and layout HTML files, generate exactly one top-level lowercase HTML element. Think React-style single parent wrapper: keep any owned PulsePoint logic in a plain `<script>` inside that root, do not handwrite `pp-component="..."` or `type="text/pp"` because Caspian injects those runtime attributes automatically, and treat `<!-- @import ... -->` comments as file-level directives that belong above the authored root element instead of inside `<div>`, `<section>`, or `<html>`. When several component tags come from one Python file, import them from that exact file path, for example `<!-- @import { Breadcrumb, BreadcrumbItem, BreadcrumbList } from "../components/Breadcrumb.py" -->`.
-5. Prefer local docs before generating code, commands, or migration guidance.
-6. Check `node_modules/caspian-utils/dist/docs/` for packaged Caspian docs when local docs need more detail.
-7. Only fall back to upstream documentation when local and packaged markdown do not cover the topic.
+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. Read `commands.md` before running any `package.json` script. In this workspace, npm scripts are opt-in operational commands, not default validation steps. Do not run them unless the user explicitly asks, the task genuinely requires that exact script, or deployment preparation needs `npm run build`.
+5. Treat generated outputs such as `public/css/styles.css`, `settings/component-map.json`, `settings/files-list.json`, `__pycache__/`, and `.pyc` files as framework-managed artifacts when the local stack is intentionally running. They are not authored source files and should not be kept in the final diff unless the task explicitly requires them.
+6. Analyze `settings/component-map.json` and `settings/files-list.json` when you need the current generated view of components or routes, but do not hand-edit them. The framework regenerates them through `settings/component-map.ts` and `settings/files-list.ts` when the dev or build pipeline intentionally runs.
+7. Read `database.md` only when `caspian.config.json` enables Prisma, read `mcp.md` only when `caspian.config.json` enables MCP, and use `auth.md`, `components.md`, `pulsepoint.md`, `fetch-data.md`, `state.md`, `cache.md`, and `validation.md` as the next routing docs for those non-flagged concerns.
+8. For authored component, route, and layout HTML files, generate exactly one top-level lowercase HTML element. Think React-style single parent wrapper: keep any owned PulsePoint logic in a plain `<script>` inside that root, do not handwrite `pp-component="..."` or `type="text/pp"` because Caspian injects those runtime attributes automatically, and treat `<!-- @import ... -->` comments as file-level directives that belong above the authored root element instead of inside `<div>`, `<section>`, or `<html>`. When several component tags come from one Python file, import them from that exact file path, for example `<!-- @import { Breadcrumb, BreadcrumbItem, BreadcrumbList } from "../components/Breadcrumb.py" -->`.
+9. Prefer local docs before generating code, commands, or migration guidance.
+10. Check `node_modules/caspian-utils/dist/docs/` for packaged Caspian docs when local docs need more detail.
+11. Only fall back to upstream documentation when local and packaged markdown do not cover the topic.
 
 ## Maintenance
 

package/dist/docs/installation.md

@@ -56,6 +56,10 @@ The interactive wizard walks through the main project options, including:
 - Feature toggles such as backend-only mode, Tailwind CSS, Prisma, MCP, and TypeScript
 - Other scaffold options exposed by the current CLI version
 
+After scaffold, read `caspian.config.json` and treat it as the single source of truth for which optional features are enabled in that project. Use feature-specific docs only after the matching flag is confirmed as enabled.
+
+If a feature is disabled and the user wants it later, ask whether they want to enable it first, then update `caspian.config.json` and run `npx casp update project` so framework-managed files align with the new feature set.
+
 If the project enables MCP, use `mcp.md` after scaffold to place the app-owned FastMCP server and config files correctly for the current workspace conventions.
 
 ## Recommended VS Code Setup
@@ -82,13 +86,19 @@ npm run dev
 
 In this workspace, `npm run dev` is backed by BrowserSync plus PostCSS watchers, not a Vite dev server.
 
+For AI agents and other automated helpers, this is an opt-in local-stack command, not a default validation step. Do not run `package.json` scripts just because a route, feature, or doc changed.
+
+If `npm run dev` is intentionally running, let that stack own generated outputs such as `public/css/styles.css`, `settings/component-map.json`, `settings/files-list.json`, `__pycache__/`, and `.pyc` files. Use `npm run build` only for deployment prep or when the user explicitly asks for a build.
+
+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 framework refreshes them from `settings/component-map.ts` and `settings/files-list.ts`.
+
 ## After Setup
 
 Once the project is scaffolded:
 
 - Read `database.md` when the app includes Prisma ORM support or needs database changes.
 - Read `mcp.md` when the app includes MCP support or needs FastMCP server, config, or launch-flow changes.
-- Read `auth.md` before wiring session config, sign-in or signout routes, route guards, or OAuth providers.
+- Read `auth.md` before choosing public-vs-private route mode, wiring session config, sign-in or signout flows, route guards, or OAuth providers.
 - Read `pulsepoint.md` before generating interactive frontend behavior.
 - Read `fetch-data.md` before adding browser-triggered reads, writes, uploads, or streams.
 - Read `validation.md` before handling forms, auth input, or RPC payloads.
@@ -102,6 +112,9 @@ If an AI agent is reading this page, treat it as the source for new-project inst
 - Use this workflow when the user is creating a Caspian app from scratch.
 - Do not use existing-project migration or update commands unless the project already exists.
 - After scaffold, default to PulsePoint for interactive UI, RPC for browser-to-server data flow, and `casp.validate` for validation.
+- Treat `package.json` scripts as opt-in commands after scaffold. Do not auto-run `npm run dev` or `npm run build` for ordinary source edits.
+- Read `caspian.config.json` after scaffold and treat it as the single source of truth for optional features before using feature-specific docs.
+- If an optional feature is disabled and the user wants it, ask first, then update `caspian.config.json` and use `npx casp update project` before assuming the framework-managed files exist.
 - If MCP is enabled, read [mcp.md](./mcp.md) before editing FastMCP files or assuming where the server config should live.
 - Once the app exists, check [routing.md](./routing.md) before creating or changing routes under `src/app/`.
 - Check [index.md](./index.md) first when deciding which local doc to follow.

package/dist/docs/mcp.md

@@ -1,9 +1,9 @@
 ---
 title: MCP
-description: Use the workspace FastMCP setup through src/lib/mcp/mcp_server.py, src/lib/mcp/fastmcp.json, and settings/restart-mcp.ts, with npm-driven startup and explicit manual paths when running FastMCP directly.
+description: Check `caspian.config.json` first. When it enables MCP, this page becomes the relevant guide for reviewing, fixing, launching, and extending the workspace MCP feature.
 related:
   title: Related docs
-  description: Start with project structure for file placement, then use commands for local run flows and index for documentation routing.
+  description: Start with project structure for file placement, then use commands for feature enablement and local run flows, and index for documentation routing.
   links:
     - /docs/project-structure
     - /docs/commands
@@ -11,92 +11,65 @@ related:
     - /docs/index
 ---
 
-This page documents the Model Context Protocol workflow present in this workspace.
+This page documents the Model Context Protocol workflow for Caspian workspaces.
 
-The current repo enables MCP in `caspian.config.json`, keeps the app-owned FastMCP server at `src/lib/mcp/mcp_server.py`, keeps the FastMCP config at `src/lib/mcp/fastmcp.json`, and starts it through `npm run mcp`, which runs `settings/restart-mcp.ts`.
+Treat `caspian.config.json` as the single source of truth for whether MCP is enabled. If `caspian.config.json` confirms `"mcp": true`, this page is relevant, the MCP-specific files in the workspace are the correct files to analyze, and the feature can be reviewed, fixed, launched, or extended here.
 
-## Overview
+If `caspian.config.json` has `"mcp": false`, treat this page as reference material only. Do not assume `src/lib/mcp/**`, `settings/restart-mcp.ts`, or MCP-related npm scripts exist until the user chooses to enable MCP and the update workflow has run.
 
-Use these rules as the default MCP workflow in this workspace:
+## Enablement Workflow
 
-1. Read `caspian.config.json` and confirm `mcp: true` before assuming MCP files should exist or be started.
-2. Edit `src/lib/mcp/mcp_server.py` when changing FastMCP tools, server instructions, or server-owned helper logic.
-3. Edit `src/lib/mcp/fastmcp.json` when changing the transport, host, port, path, or server entrypoint.
-4. Edit `settings/restart-mcp.ts` when changing discovery order, environment overrides, or MCP log filtering.
-5. Use `npm run mcp` as the normal local launch flow.
+1. Read `caspian.config.json` and confirm `mcp: true` before assuming MCP files or scripts should exist.
+2. If `mcp` is false and the user wants MCP, ask for confirmation first.
+3. After the user confirms, update `caspian.config.json` and run `npx casp update project` so framework-managed MCP files align with the new feature set.
+4. After the update, inspect the actual `package.json`, `src/lib/mcp/`, and any launcher files that the workspace now contains.
 
-## Current Workspace Layout
+## MCP-Enabled Workspace Layout
 
-- `src/lib/mcp/mcp_server.py` defines `mcp = FastMCP(...)` and the current workspace tools.
-- `src/lib/mcp/fastmcp.json` points to `src/lib/mcp/mcp_server.py` and configures `streamable-http` on `127.0.0.1:5101/mcp`.
-- `settings/restart-mcp.ts` is the npm-facing launcher. It resolves MCP config paths, starts FastMCP, and trims noisy banner or warning output down to essential lines.
-- `package.json` defines `npm run mcp` as `tsx settings/restart-mcp.ts` and includes `mcp` in `npm run dev`.
-- `caspian.config.json` is the feature gate. If `mcp` is false, the MCP runner exits cleanly without starting a server.
+When `caspian.config.json` has `mcp: true`, these are the main MCP surfaces to inspect:
 
-## Current Tools
+- `src/lib/mcp/mcp_server.py` for the app-owned FastMCP server, tool definitions, instructions, and MCP-specific helper logic.
+- `src/lib/mcp/fastmcp.json` for the default FastMCP config, transport, host, port, path, and server entrypoint.
+- `settings/restart-mcp.ts` for workspace-specific launcher logic, discovery order, environment overrides, or log filtering when that file is present.
+- `package.json` for the actual MCP-related scripts that the current workspace defines.
 
-The app-owned MCP server currently exposes these read-only tools:
+If these files exist in the workspace, they are the right files to analyze when reviewing or fixing MCP behavior.
 
-- `project_info` returns the project name, root path, version metadata, browser sync target, feature flags, and component scan directories.
-- `workspace_files` returns the generated workspace file list, optionally filtered to `all`, `app`, or `public`.
-- `component_inventory` returns the latest generated component map from `settings/component-map.json`.
+## What To Review
 
-Add or change tools in `src/lib/mcp/mcp_server.py`.
+When `mcp: true` and an MCP issue needs investigation, inspect the files in this order:
 
-## Running The Server
+1. `caspian.config.json` to confirm the feature is enabled.
+2. `package.json` to see which MCP scripts the workspace actually exposes.
+3. `src/lib/mcp/mcp_server.py` for tool implementation and server behavior.
+4. `src/lib/mcp/fastmcp.json` for config and entrypoint details.
+5. `settings/restart-mcp.ts` when the workspace includes it and launcher behavior is part of the issue.
 
-### Preferred local commands
+## Running MCP
 
-```bash
-npm run mcp
-npm run dev
-```
-
-Use `npm run mcp` when you want the MCP server only. Use `npm run dev` when you want BrowserSync, Tailwind, the Python app server, and MCP together.
-
-### Direct FastMCP commands
+Only when `caspian.config.json` has `mcp: true` and the relevant files or scripts exist:
 
-On this Windows workspace, the direct FastMCP commands are:
+- Use the workspace-defined `npm run mcp` command when `package.json` provides it.
+- Use `npm run dev` only if the workspace wires MCP into the full local stack and the user explicitly wants that full stack running.
+- Use direct FastMCP commands against `src/lib/mcp/fastmcp.json` when that config file exists, for example:
 
 ```powershell
 .venv\Scripts\fastmcp.exe inspect src/lib/mcp/fastmcp.json
 .venv\Scripts\fastmcp.exe run src/lib/mcp/fastmcp.json --no-banner
 ```
 
-Because the config file lives under `src/lib/mcp/`, plain `fastmcp run` from the project root does not auto-detect it. Use `npm run mcp` or pass the explicit config path.
-
-## Config And Discovery Rules
-
-`settings/restart-mcp.ts` currently resolves MCP server specs in this order:
+Because script names and launcher wiring can vary by workspace version, always confirm the actual scripts in `package.json` instead of assuming them from docs alone.
 
-1. `MCP_SERVER_SPEC`
-2. `src/lib/mcp/fastmcp.json`
-3. `fastmcp.json`
-4. `mcp.json`
+## Current Workspace Status
 
-The runner also forwards these optional overrides to FastMCP:
-
-- `MCP_TRANSPORT`
-- `MCP_HOST`
-- `MCP_PORT`
-- `MCP_PATH`
-- `MCP_LOG_LEVEL`
-
-Keep the `source.path` value in `src/lib/mcp/fastmcp.json` root-relative as `src/lib/mcp/mcp_server.py`. Do not shorten it to `mcp_server.py` unless the launch working directory changes too, because FastMCP resolves that path from the current working directory.
+- `caspian.config.json` currently has `mcp: false`.
+- `package.json` does not currently define `npm run mcp`.
+- The current repo tree should not be treated as if `src/lib/mcp/**` is guaranteed to exist.
 
 ## AI Routing Notes
 
-If an AI tool is working on MCP in this workspace, use this order:
-
-1. Read `caspian.config.json` to confirm `mcp: true`.
-2. Read `node_modules/caspian-utils/dist/docs/mcp.md` for the current workspace MCP rules.
-3. Read `src/lib/mcp/mcp_server.py` for tool definitions and server instructions.
-4. Read `src/lib/mcp/fastmcp.json` for transport and entrypoint configuration.
-5. Read `settings/restart-mcp.ts` and `package.json` for local start behavior.
-
-Default placement rules:
-
-- Put app-owned FastMCP tools in `src/lib/mcp/mcp_server.py`.
-- Keep the default FastMCP config in `src/lib/mcp/fastmcp.json`.
-- Keep npm-facing launch behavior in `settings/restart-mcp.ts`.
-- If the MCP file layout changes, update this page, `AGENTS.md`, `.github/copilot-instructions.md`, and any workspace runner logic together.
+1. Read `caspian.config.json` first.
+2. If `mcp` is false, do not infer MCP files, scripts, or launch flow from generic Caspian examples.
+3. If the user wants MCP while it is disabled, ask first, then update `caspian.config.json` and use `npx casp update project` before continuing.
+4. If `mcp` is true, this page becomes the relevant MCP guide and the MCP-specific files in the workspace become the correct analysis surface.
+5. Inspect the actual generated files and scripts in the workspace before editing or starting anything.

package/dist/docs/project-structure.md

@@ -27,6 +27,8 @@ For public pages that can safely reuse rendered HTML, Caspian also supports rout
 
 Before an AI agent decides which Caspian features are available in a workspace, it should read `./caspian.config.json` almost immediately. That file is the feature gate for project capabilities such as `backendOnly`, `tailwindcss`, `mcp`, `prisma`, `typescript`, and `componentScanDirs`.
 
+Treat `caspian.config.json` as the single source of truth for optional feature enablement. Use feature-specific files and docs only after the matching flag is confirmed as enabled. If a feature is disabled and the user wants it, ask first, then update `caspian.config.json` and follow the update workflow in `commands.md`.
+
 ## Top-Level Areas
 
 - `src/` contains routes, page templates, styles, and shared libraries.
@@ -81,6 +83,8 @@ my-app/
         docs/
 ```
 
+Optional directories such as `src/lib/mcp/` appear only when the relevant feature flag is enabled in `caspian.config.json`.
+
 ## Directory Breakdown
 
 ### `src/`
@@ -133,13 +137,15 @@ Use this folder for authentication-specific project code. The main auth configur
 
 Use this folder for app-owned Model Context Protocol server files.
 
-In the current workspace:
+When `caspian.config.json` has `mcp: true`:
 
 - `src/lib/mcp/mcp_server.py` defines `mcp = FastMCP(...)` and the current tool set.
-- `src/lib/mcp/fastmcp.json` is the default FastMCP config used by `npm run mcp`.
+- `src/lib/mcp/fastmcp.json` is the default FastMCP config file for any workspace-defined MCP launcher, such as `npm run mcp` when that script exists.
 
 Keep MCP tool definitions here instead of placing them in route files, `main.py`, or framework internals.
 
+In the current workspace, `mcp: false`, so do not assume this folder exists until the feature is enabled and the update workflow has run.
+
 ### `prisma/`
 
 This folder contains your database model definitions in `schema.prisma` and any seed logic such as `seed.ts`.
@@ -171,7 +177,7 @@ The core feature configuration file for the application.
 
 AI agents should read this file before making almost any feature-level decision. Use it to confirm which capabilities are enabled, which code generation paths make sense, and which directories should be scanned for components or other project assets.
 
-In the current workspace, `caspian.config.json` shows `backendOnly: false`, `tailwindcss: true`, `mcp: true`, `prisma: true`, `typescript: false`, and `componentScanDirs: ["src"]`.
+In the current workspace, `caspian.config.json` shows `backendOnly: false`, `tailwindcss: true`, `mcp: false`, `prisma: true`, `typescript: false`, and `componentScanDirs: ["src"]`.
 
 ### `src/lib/auth/auth_config.py`
 
@@ -179,11 +185,11 @@ The project auth configuration file. Use this path when changing authentication
 
 ### `src/lib/mcp/mcp_server.py`
 
-The app-owned FastMCP server module for this workspace. It exports the `mcp` server instance and should be the default place for workspace MCP tools.
+When `caspian.config.json` has `mcp: true`, this is the app-owned FastMCP server module. It exports the `mcp` server instance and should be the default place for workspace MCP tools.
 
 ### `src/lib/mcp/fastmcp.json`
 
-The default FastMCP config file for this workspace.
+When `caspian.config.json` has `mcp: true`, this is the default FastMCP config file for the workspace.
 
 Because this file is nested under `src/lib/mcp/`, direct FastMCP commands should pass the explicit path, for example `fastmcp run src/lib/mcp/fastmcp.json`, unless the launch working directory changes.
 
@@ -229,14 +235,19 @@ The packaged Caspian documentation location distributed with the current toolcha
 If an AI agent is deciding where to make changes, use these rules first.
 
 - Read `caspian.config.json` almost immediately before making feature, tooling, or file-placement decisions. It tells you which Caspian features are enabled in the current workspace.
+- Treat `caspian.config.json` as the single source of truth for optional feature enablement. Use feature-specific docs and file paths only when the matching flag is enabled.
+- If an optional feature is disabled and the user wants it, ask first, then update `caspian.config.json` and use `npx casp update project` before assuming feature-managed files exist.
+- Treat `package.json` scripts as opt-in operations. Do not run `npm run dev` or `npm run build` unless the user explicitly asks, the task genuinely requires that exact script, or deployment prep needs `npm run build`.
+- Treat `__pycache__/` directories, `.pyc` files, `public/css/styles.css`, `settings/component-map.json`, and `settings/files-list.json` as generated artifacts when the local stack is intentionally running. They are not authored source files.
+- Inspect `settings/component-map.json` and `settings/files-list.json` when you need the generated component or route inventory, but do not hand-edit them. The workspace regenerates them from `settings/component-map.ts` and `settings/files-list.ts`.
 - Put route templates and route-specific backend logic in `src/app/`.
 - 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.
-- Use [mcp.md](./mcp.md) when the task involves FastMCP tool definitions, nested config discovery, or local MCP commands.
+- 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.
 - Put shared helpers and reusable libraries in `src/lib/`.
-- Put app-owned FastMCP code in `src/lib/mcp/`.
+- 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 `casp.cache_handler` when a route's first-render HTML should be reused safely across requests.

package/package.json

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