caspian-utils 0.0.12 → 0.0.14

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
-```
-
-Use when you want the workspace's app-owned FastMCP server only.
+This is also the workflow to use after the user chooses to enable or disable an optional feature in `caspian.config.json`.
 
-### 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.
+Use when the user explicitly wants the local BrowserSync plus PostCSS development stack.
 
-### Inspect the local MCP config directly
+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.
 
-```powershell
-.venv\Scripts\fastmcp.exe inspect src/lib/mcp/fastmcp.json
-```
+### Build generated assets for deployment
 
-Use when you are debugging the nested FastMCP config or checking which tools the current MCP server exposes.
-
-### 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
+
+- 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.
 
-## 2. Supported Flags And Options
+## 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.
 
@@ -649,7 +651,7 @@ Auth example:
 
 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/components.md

@@ -18,12 +18,14 @@ Import them into a template with an `@import` comment, then render them with JSX
 
 For the current workspace, component tooling scans Python files under the paths listed in `caspian.config.json`. Right now that means `src/`, so `src/components/` is the clean default location for reusable UI, even though any scanned path under `src/` can work.
 
+As the app grows, treat `src/components/` as the default home for reusable application UI. Keep route-owned markup in `src/app/`, and keep non-UI helpers or services in `src/lib/`.
+
 ## Mental Model
 
 - Use a Python component when you want a reusable server-rendered UI building block.
 - Return an HTML string directly for small presentational components.
 - 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/`, and move reusable UI into components.
+- Keep page-level workflows in `src/app/`, move reusable UI into `src/components/`, and keep helpers, services, validators, and adapters in `src/lib/`.
 
 ## Basic Component
 

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,8 +40,8 @@ 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
+- `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
@@ -49,7 +51,7 @@ The packaged Caspian docs distributed by the current toolchain also live here:
 - `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
-- `project-structure.md` - Default Caspian layout and where routes, templates, shared code, and database files belong
+- `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 Awareness Notes
 
@@ -59,11 +61,16 @@ 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. As the app grows, standardize on `src/app/` for route-owned files, `src/components/` for reusable rendered UI, and `src/lib/` for reusable non-UI support code such as services, validators, adapters, and shared helpers.
+9. 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" -->`.
+10. Prefer local docs before generating code, commands, or migration guidance.
+11. Check `node_modules/caspian-utils/dist/docs/` for packaged Caspian docs when local docs need more detail.
+12. 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,6 +86,12 @@ 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:
@@ -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

@@ -21,16 +21,21 @@ This page explains the default layout of a Caspian application, where Caspian co
 
 Caspian uses a lean project layout that keeps application code in `src`, database files in `prisma`, static assets in `public`, configuration in `caspian.config.json`, and framework internals in the installed package.
 
+As an app grows, keep reusable rendered UI in `src/components/`, keep reusable non-UI support code in `src/lib/`, and keep route-owned files in `src/app/`. That split keeps page composition separate from shared component and service code.
+
 In that layout, the default stack is Python components for reusable UI, PulsePoint in templates for reactive browser behavior, RPC for browser-triggered server calls, and `casp.validate` for input validation at route and action boundaries.
 
 For public pages that can safely reuse rendered HTML, Caspian also supports route-level page caching through `casp.cache_handler`.
 
 Before an AI agent decides which Caspian features are available in a workspace, it should read `./caspian.config.json` almost immediately. That file is the feature gate for project capabilities such as `backendOnly`, `tailwindcss`, `mcp`, `prisma`, `typescript`, and `componentScanDirs`.
 
+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.
-- `src/components/` contains reusable Python components and optional same-name HTML templates.
+- `src/` contains routes, page templates, styles, reusable components, and shared libraries.
+- `src/components/` contains reusable application UI components and optional same-name HTML templates.
+- `src/lib/` contains reusable non-UI code such as helpers, services, validators, adapters, and shared support modules.
 - `src/lib/auth/auth_config.py` contains auth-specific configuration for the app.
 - `src/lib/mcp/` contains the app-owned FastMCP server and nested FastMCP config when MCP is enabled.
 - `prisma/` contains the Prisma schema and seed scripts.
@@ -81,6 +86,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/`
@@ -101,6 +108,8 @@ See `routing.md` for the full App Router-style rules for dynamic segments, route
 
 Use this folder for reusable UI components that should be imported into route templates or other component templates.
 
+As the app grows, default to `src/components/` for application-level UI that will be shared across routes or features. Keep page-only markup close to the route in `src/app/`, but move shared cards, forms, shells, navigation, and other reusable visual building blocks into `src/components/`.
+
 The common Caspian pattern is a Python file such as `Button.py` with `@component`, optionally paired with a same-name HTML file such as `Button.html` when the component has richer markup or PulsePoint behavior.
 
 One Python file can also export multiple related `@component` functions. When that happens, import those tags from that exact file path in HTML, for example `<!-- @import { Breadcrumb, BreadcrumbItem, BreadcrumbList } from "../components/Breadcrumb.py" -->`, instead of assuming each tag has its own sibling `.py` file.
@@ -113,7 +122,9 @@ This workspace's component tooling scans `src/` based on `caspian.config.json`,
 
 ### `src/lib/`
 
-Use this folder for shared helpers, reusable validators, RPC-facing service wrappers, reusable UI utilities, and app-level support code.
+Use this folder for shared helpers, reusable validators, RPC-facing service wrappers, data-access helpers, formatting utilities, and other app-level support code that is not itself a reusable rendered component.
+
+If the code is primarily rendered UI that will be imported as a component tag, prefer `src/components/`. If the code is a helper, service, adapter, validator, or other non-visual support module, prefer `src/lib/`.
 
 This workspace already includes an app-owned Python database layer under `src/lib/prisma/`. Reuse that package for Python-side data access and keep any additional shared database helpers in `src/lib/`.
 
@@ -133,13 +144,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 +184,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 +192,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 +242,21 @@ 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/`.
+- 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/`.
 - 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.
+- 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.
 - 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.12",
+  "version": "0.0.14",
   "description": "Caspian tooling",
   "main": "index.js",
   "scripts": {