caspian-utils 0.0.9 → 0.0.11

package/dist/docs/commands.md

@@ -1,12 +1,13 @@
 ---
 title: Commands
-description: Use this Caspian CLI reference to choose the right create, starter-kit, update, and Prisma-to-Python ORM regeneration flow for the current workspace.
+description: Use the current Caspian CLI reference to choose the right scaffold, starter-kit, update, and Prisma regeneration workflow for the current workspace.
 related:
   title: Related docs
-  description: Start with installation for new apps, then use database and structure docs when commands affect schema, generated ORM files, or project layout.
+  description: Start with installation for new apps, then use database, MCP, and structure docs when commands affect schema, server tooling, generated ORM files, or project layout.
   links:
     - /docs/installation
     - /docs/database
+    - /docs/mcp
     - /docs/routing
     - /docs/project-structure
     - /docs/index
@@ -18,56 +19,155 @@ 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.
 
-Examples below use the bare package name for readability. If you want to force the latest published scaffold package, you can add `@latest`, for example `npx create-caspian-app@latest my-app`.
+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`.
 
-Use these command families for different tasks:
+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.
 
-| Task | Command | When to use |
-| --- | --- | --- |
-| Create a new project | `npx create-caspian-app my-app` | First-time scaffold for a brand new Caspian app. |
-| Update an existing project | `npx casp update project` | Refresh framework-managed files inside an existing Caspian project. |
-| Create from a starter kit | `npx create-caspian-app my-app --starter-kit=fullstack` | Start from a built-in or custom template instead of the default scaffold. |
-| List starter kits | `npx create-caspian-app --list-starter-kits` | Inspect the starter catalog before choosing a preset. |
-| Regenerate ORM after schema change | `npx prisma migrate dev` then optional seed commands, then `npx ppy generate` | Keep Prisma migrations, seed flow, and generated Python ORM files aligned after `prisma/schema.prisma` changes. |
+This updated reference includes the newer updater behavior and the current scaffold behavior:
+
+- positional version or tag values such as `beta` or `1.2.3`
+- named options such as `--tag beta`, `--tag=beta`, `--version 1.2.3`, and `--version=1.2.3`
+- conflict detection when more than one version source is provided
+- PowerShell-safe tagging syntax with `--tag beta`
+- 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"]`.
+
+## 1. Main Command Families
+
+### Create a new project
+
+```bash
+npx create-caspian-app my-app
+```
+
+Use when you want to scaffold a new Caspian project from scratch.
+
+### Create a project from a starter kit
+
+```bash
+npx create-caspian-app my-app --starter-kit=fullstack
+npx create-caspian-app my-app --starter-kit=custom --starter-kit-source=https://github.com/user/repo
+```
+
+Use when you want a preset structure instead of the blank default scaffold.
+
+### List available starter kits
+
+```bash
+npx create-caspian-app --list-starter-kits
+```
+
+Use when you want to inspect the built-in starter kits before choosing one.
+
+### Update an existing project
+
+```bash
+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.
+
+### Run the full local stack including MCP
+
+```bash
+npm run dev
+```
+
+Use when you want BrowserSync, Tailwind, the Python app server, and MCP together.
+
+### Inspect the local MCP config directly
+
+```powershell
+.venv\Scripts\fastmcp.exe inspect src/lib/mcp/fastmcp.json
+```
+
+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
+```
+
+Use when you want the raw FastMCP path without the npm wrapper.
+
+### Regenerate ORM after schema changes
+
+```bash
+npx prisma migrate dev
+
+# If the change requires refreshed seed data:
+npx prisma generate
+npx prisma db seed
+
+npx ppy generate
+```
+
+Use when `prisma/schema.prisma` changes and you need migrations, seed flow, and the generated Python ORM layer to stay aligned.
 
-Before running `npx casp update project`, read `caspian.config.json` because it controls feature flags and `excludeFiles` overwrite protection. Before running Prisma or `ppy` commands, read [database.md](./database.md).
+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.
 
-## Supported Flags
+## 2. Supported Flags And Options
 
-The scaffold CLI exposes these feature flags:
+### For `create-caspian-app`
 
 | Flag | Meaning | When to use |
 | --- | --- | --- |
-| `-y` | Non-interactive mode | Use in CI, automation, or scripted setup. |
-| `--backend-only` | Backend-only project | Use for APIs, services, or apps with no browser UI. |
-| `--tailwindcss` | Enable Tailwind CSS | Use for frontend or full-stack styling. |
-| `--typescript` | Enable TypeScript frontend tooling | Use when you want frontend TypeScript assets. |
-| `--mcp` | Enable MCP support | Use when the app needs Model Context Protocol support. |
-| `--prisma` | Enable Prisma setup | Use when the app needs schema, migration, and ORM tooling. |
-| `--starter-kit=<kit>` | Use a built-in or named starter kit | Use to bootstrap from a preset instead of the default scaffold. |
-| `--starter-kit-source=<url>` | Pull a starter kit from a Git source | Use when the starter kit lives in an external repository. |
+| `-y` | Non-interactive mode | Use in scripts, CI, or when you want to skip prompts. |
+| `--backend-only` | Backend-only project | Use for APIs or services without frontend assets. |
+| `--tailwindcss` | Enable Tailwind CSS | Use for frontend or full-stack UI styling. |
+| `--typescript` | Enable TypeScript frontend tooling | Use when you want the scaffold's TypeScript frontend path. |
+| `--mcp` | Enable MCP support | Use when the project needs Model Context Protocol support. |
+| `--prisma` | Enable Prisma-related setup | Use when the project needs ORM and database tooling. |
+| `--starter-kit=<kit>` | Select a starter kit | Use when you want a built-in preset or named kit. |
+| `--starter-kit-source=<url>` | External starter kit source | Use when the starter kit lives in a Git repository. |
+| `--list-starter-kits` | List built-in starter kits | Use when you want to inspect the starter catalog before scaffold. |
+
+### For `npx casp update project`
+
+| Option | Meaning | When to use |
+| --- | --- | --- |
+| `-y` | Non-interactive mode | Use for automated updates without prompts. |
+| positional tag | Example: `beta` | Use for a quick tag or channel update. |
+| positional version | Example: `1.2.3` | Use for exact version pinning. |
+| `--tag <value>` | Named tag option | Use especially in PowerShell or other shells where explicit spacing is safer. |
+| `--tag=<value>` | Inline named tag option | Same as above in inline syntax. |
+| `--version <value>` | Named version option | Use for explicit version selection. |
+| `--version=<value>` | Inline named version option | Same as above in inline syntax. |
+
+The updater throws an error if conflicting version sources are provided.
 
-Add `-y` to most create or update examples below when you want the same flow to run without prompts.
+## 3. Create Command Combinations
 
-## Create a New Project
+### 3.1 Base create command
 
-### Interactive create
+#### Interactive create
 
 ```bash
 npx create-caspian-app my-app
 ```
 
-Use when you want the normal interactive scaffold flow. The CLI can prompt for project name and feature toggles.
+Use when you want the standard guided setup.
 
-### Non-interactive create
+#### Non-interactive create
 
 ```bash
 npx create-caspian-app my-app -y
 ```
 
-Use when you already know the desired feature flags or when automation should avoid prompts.
+Use when you want a quick scaffold without prompts.
 
-Without extra flags, the non-interactive default behaves like this:
+In skip-prompt mode, the default feature values are:
 
 - `backendOnly: false`
 - `tailwindcss: false`
@@ -75,20 +175,47 @@ Without extra flags, the non-interactive default behaves like this:
 - `mcp: false`
 - `prisma: false`
 
-## Backend-only Create Combinations
+### 3.2 Backend-only combinations
 
-When `--backend-only` is enabled, the meaningful feature toggles are `--mcp` and `--prisma`. Frontend-oriented flags are not part of the normal backend-only prompt flow.
+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.
 
-| Goal | Example command | When to use |
-| --- | --- | --- |
-| Minimal backend-only | `npx create-caspian-app my-app --backend-only` | Simple API or service without frontend assets. |
-| Backend-only + MCP | `npx create-caspian-app my-app --backend-only --mcp` | Backend service plus MCP support. |
-| Backend-only + Prisma | `npx create-caspian-app my-app --backend-only --prisma` | API or service with database and ORM support. |
-| Backend-only + MCP + Prisma | `npx create-caspian-app my-app --backend-only --mcp --prisma` | Full backend-only setup with both integrations. |
+#### Minimal backend-only
+
+```bash
+npx create-caspian-app my-app --backend-only
+npx create-caspian-app my-app --backend-only -y
+```
 
-You can append `-y` to any backend-only example above.
+Use when you want a simple backend project without frontend assets.
 
-### Accepted but not recommended in backend-only mode
+#### Backend-only plus MCP
+
+```bash
+npx create-caspian-app my-app --backend-only --mcp
+npx create-caspian-app my-app --backend-only --mcp -y
+```
+
+Use when you want a backend service with MCP enabled.
+
+#### Backend-only plus Prisma
+
+```bash
+npx create-caspian-app my-app --backend-only --prisma
+npx create-caspian-app my-app --backend-only --prisma -y
+```
+
+Use when you want a backend or API project with database tooling.
+
+#### Backend-only plus MCP plus Prisma
+
+```bash
+npx create-caspian-app my-app --backend-only --mcp --prisma
+npx create-caspian-app my-app --backend-only --mcp --prisma -y
+```
+
+Use when you want the fullest backend-only setup.
+
+#### Accepted but usually not useful for backend-only mode
 
 ```bash
 npx create-caspian-app my-app --backend-only --tailwindcss
@@ -96,59 +223,229 @@ npx create-caspian-app my-app --backend-only --typescript
 npx create-caspian-app my-app --backend-only --tailwindcss --typescript
 ```
 
-Avoid them in normal use. Backend-only mode strips frontend assets, so Tailwind and frontend TypeScript flags do not have a practical effect in the resulting scaffold.
+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.
 
-## Full-stack and Frontend-enabled Create Combinations
+### 3.3 Full-stack combinations
 
-When `--backend-only` is not used, the feature flags `--tailwindcss`, `--typescript`, `--mcp`, and `--prisma` can be combined in any subset. The table below lists the common command matrix.
+These apply when `--backend-only` is not used.
 
-| Flags | Example command | When to use |
-| --- | --- | --- |
-| none | `npx create-caspian-app my-app` | Default full-stack scaffold. |
-| `--tailwindcss` | `npx create-caspian-app my-app --tailwindcss` | Styled frontend with Tailwind. |
-| `--typescript` | `npx create-caspian-app my-app --typescript` | Frontend TypeScript assets. |
-| `--mcp` | `npx create-caspian-app my-app --mcp` | Full-stack app with MCP support. |
-| `--prisma` | `npx create-caspian-app my-app --prisma` | Full-stack app with Prisma support. |
-| `--tailwindcss --typescript` | `npx create-caspian-app my-app --tailwindcss --typescript` | Styled frontend with TypeScript. |
-| `--tailwindcss --mcp` | `npx create-caspian-app my-app --tailwindcss --mcp` | Styled UI plus MCP support. |
-| `--tailwindcss --prisma` | `npx create-caspian-app my-app --tailwindcss --prisma` | Styled UI plus database tooling. |
-| `--typescript --mcp` | `npx create-caspian-app my-app --typescript --mcp` | Frontend TypeScript plus MCP. |
-| `--typescript --prisma` | `npx create-caspian-app my-app --typescript --prisma` | Frontend TypeScript plus Prisma. |
-| `--mcp --prisma` | `npx create-caspian-app my-app --mcp --prisma` | Both major backend integrations without forcing frontend styling choices. |
-| `--tailwindcss --typescript --mcp` | `npx create-caspian-app my-app --tailwindcss --typescript --mcp` | Rich frontend plus MCP. |
-| `--tailwindcss --typescript --prisma` | `npx create-caspian-app my-app --tailwindcss --typescript --prisma` | Rich frontend plus Prisma. |
-| `--tailwindcss --mcp --prisma` | `npx create-caspian-app my-app --tailwindcss --mcp --prisma` | Styled UI plus both major integrations. |
-| `--typescript --mcp --prisma` | `npx create-caspian-app my-app --typescript --mcp --prisma` | Frontend TypeScript plus both major integrations. |
-| `--tailwindcss --typescript --mcp --prisma` | `npx create-caspian-app my-app --tailwindcss --typescript --mcp --prisma` | Most feature-complete default full-stack setup. |
-
-You can append `-y` to any frontend-enabled example above.
-
-## Starter Kit Commands
+#### Minimal full-stack
 
-### List available starter kits
+```bash
+npx create-caspian-app my-app
+npx create-caspian-app my-app -y
+```
+
+Use when you want the default scaffold and will add features later.
+
+#### Full-stack plus Tailwind CSS
 
 ```bash
-npx create-caspian-app --list-starter-kits
+npx create-caspian-app my-app --tailwindcss
+npx create-caspian-app my-app --tailwindcss -y
+```
+
+Use when you want Tailwind-based UI styling.
+
+#### Full-stack plus TypeScript
+
+```bash
+npx create-caspian-app my-app --typescript
+npx create-caspian-app my-app --typescript -y
 ```
 
-Use when you want to inspect the built-in starter kit catalog before creating a project.
+Use when you want the scaffold's TypeScript frontend tooling.
+
+#### Full-stack plus MCP
+
+```bash
+npx create-caspian-app my-app --mcp
+npx create-caspian-app my-app --mcp -y
+```
+
+Use when you want MCP support in a full-stack app.
+
+#### Full-stack plus Prisma
+
+```bash
+npx create-caspian-app my-app --prisma
+npx create-caspian-app my-app --prisma -y
+```
+
+Use when you want ORM and database support.
+
+#### Full-stack plus Tailwind plus TypeScript
+
+```bash
+npx create-caspian-app my-app --tailwindcss --typescript
+npx create-caspian-app my-app --tailwindcss --typescript -y
+```
+
+Use when you want the typical richer frontend setup.
+
+#### Full-stack plus Tailwind plus MCP
+
+```bash
+npx create-caspian-app my-app --tailwindcss --mcp
+npx create-caspian-app my-app --tailwindcss --mcp -y
+```
+
+Use when you want styled UI plus MCP.
+
+#### Full-stack plus Tailwind plus Prisma
+
+```bash
+npx create-caspian-app my-app --tailwindcss --prisma
+npx create-caspian-app my-app --tailwindcss --prisma -y
+```
+
+Use when you want styled UI plus database tooling.
+
+#### Full-stack plus TypeScript plus MCP
+
+```bash
+npx create-caspian-app my-app --typescript --mcp
+npx create-caspian-app my-app --typescript --mcp -y
+```
+
+Use when you want TypeScript assets plus MCP.
+
+#### Full-stack plus TypeScript plus Prisma
+
+```bash
+npx create-caspian-app my-app --typescript --prisma
+npx create-caspian-app my-app --typescript --prisma -y
+```
+
+Use when you want TypeScript assets plus database tooling.
+
+#### Full-stack plus MCP plus Prisma
+
+```bash
+npx create-caspian-app my-app --mcp --prisma
+npx create-caspian-app my-app --mcp --prisma -y
+```
+
+Use when you want both integration layers without forcing frontend preferences.
+
+#### Full-stack plus Tailwind plus TypeScript plus MCP
+
+```bash
+npx create-caspian-app my-app --tailwindcss --typescript --mcp
+npx create-caspian-app my-app --tailwindcss --typescript --mcp -y
+```
+
+Use when you want a rich frontend plus MCP.
+
+#### Full-stack plus Tailwind plus TypeScript plus Prisma
+
+```bash
+npx create-caspian-app my-app --tailwindcss --typescript --prisma
+npx create-caspian-app my-app --tailwindcss --typescript --prisma -y
+```
+
+Use when you want a rich frontend plus database tooling.
+
+#### Full-stack plus Tailwind plus MCP plus Prisma
+
+```bash
+npx create-caspian-app my-app --tailwindcss --mcp --prisma
+npx create-caspian-app my-app --tailwindcss --mcp --prisma -y
+```
+
+Use when you want styled UI and both integrations.
+
+#### Full-stack plus TypeScript plus MCP plus Prisma
+
+```bash
+npx create-caspian-app my-app --typescript --mcp --prisma
+npx create-caspian-app my-app --typescript --mcp --prisma -y
+```
+
+Use when you want TypeScript assets plus both integrations.
+
+#### Full-stack plus Tailwind plus TypeScript plus MCP plus Prisma
+
+```bash
+npx create-caspian-app my-app --tailwindcss --typescript --mcp --prisma
+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
 
 ### Built-in starter kits
 
-The current command reference includes these built-in starter kits:
+#### Basic starter kit
 
-| Starter kit | Example command | Preset features | When to use |
-| --- | --- | --- | --- |
-| `basic` | `npx create-caspian-app my-app --starter-kit=basic` | `backendOnly=true`, `tailwindcss=false`, `prisma=false`, `mcp=false` | Minimal backend-oriented scaffold. |
-| `fullstack` | `npx create-caspian-app my-app --starter-kit=fullstack` | `backendOnly=false`, `tailwindcss=true`, `prisma=true`, `mcp=false` | Complete full-stack web app preset. |
-| `api` | `npx create-caspian-app my-app --starter-kit=api` | `backendOnly=true`, `tailwindcss=false`, `prisma=true`, `mcp=false` | Backend API preset with Prisma. |
-| `realtime` | `npx create-caspian-app my-app --starter-kit=realtime` | `backendOnly=false`, `tailwindcss=true`, `prisma=true`, `mcp=true` | Realtime-oriented preset with both UI and integration support. |
+```bash
+npx create-caspian-app my-app --starter-kit=basic
+npx create-caspian-app my-app --starter-kit=basic -y
+```
+
+Use when you want the minimal backend preset.
+
+Preset features:
+
+- `backendOnly = true`
+- `tailwindcss = false`
+- `prisma = false`
+- `mcp = false`
+
+#### Fullstack starter kit
+
+```bash
+npx create-caspian-app my-app --starter-kit=fullstack
+npx create-caspian-app my-app --starter-kit=fullstack -y
+```
+
+Use when you want the built-in full-stack preset.
 
-If you want frontend TypeScript, add `--typescript` explicitly rather than assuming it is implied by a starter kit preset.
+Preset features:
 
-Append `-y` to any starter kit example when you want the same preset without prompts.
+- `backendOnly = false`
+- `tailwindcss = true`
+- `prisma = true`
+- `mcp = false`
 
-### Starter kit overrides
+#### API starter kit
+
+```bash
+npx create-caspian-app my-app --starter-kit=api
+npx create-caspian-app my-app --starter-kit=api -y
+```
+
+Use when you want a backend API preset with ORM and database support.
+
+Preset features:
+
+- `backendOnly = true`
+- `tailwindcss = false`
+- `prisma = true`
+- `mcp = false`
+
+#### Realtime starter kit
+
+```bash
+npx create-caspian-app my-app --starter-kit=realtime
+npx create-caspian-app my-app --starter-kit=realtime -y
+```
+
+Use when you want the built-in realtime preset.
+
+Preset features:
+
+- `backendOnly = false`
+- `tailwindcss = true`
+- `prisma = true`
+- `mcp = true`
+
+### Starter kit with feature overrides
+
+Starter kit defaults can still be overridden by explicit feature flags because the CLI reapplies raw args after loading starter kit defaults.
+
+Examples:
 
 ```bash
 npx create-caspian-app my-app --starter-kit=basic --prisma
@@ -157,83 +454,132 @@ npx create-caspian-app my-app --starter-kit=api --mcp
 npx create-caspian-app my-app --starter-kit=realtime --backend-only
 ```
 
-Use overrides when a starter kit is close to the target app but you need to force one or more feature flags.
+Use when a starter kit is close to what you want but still needs a few forced overrides.
 
 ### Custom starter kit source
 
 ```bash
 npx create-caspian-app my-app --starter-kit=custom --starter-kit-source=https://github.com/user/repo
+npx create-caspian-app my-app --starter-kit=custom --starter-kit-source=https://github.com/user/repo -y
 ```
 
-You can combine extra flags with the custom source:
+You can combine feature overrides too:
 
 ```bash
 npx create-caspian-app my-app --starter-kit=custom --starter-kit-source=https://github.com/user/repo --typescript --prisma
 ```
 
-Use this flow when the scaffold should come from an external repository instead of a built-in preset.
+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.
 
-## Update an Existing Project
+## 5. Update Command Combinations
 
-The updater wrapper recognizes the `update project` family:
+The updater recognizes only the `update project` command family. Anything outside that family is rejected by the wrapper.
+
+### Update to latest
 
 ```bash
 npx casp update project
 ```
 
-Use this only inside an existing Caspian project that already has `caspian.config.json` in the current directory.
+Use when you want the newest release and do not need a pinned tag or version.
 
-### Update to latest
+### Update to a specific tag using positional syntax
 
 ```bash
-npx casp update project
+npx casp update project beta
 ```
 
-Use when you want the normal refresh to the latest framework-managed files.
+Use when you want a named release channel such as `beta`.
 
-### Update to a specific tag
+### Update to a specific version using positional syntax
 
 ```bash
-npx casp update project @v4-alpha
+npx casp update project 1.2.3
 ```
 
-Use when you want a prerelease or named tag instead of the latest stable release.
+Use when you want an exact version.
 
-### Update to a specific version
+### Update using named tag option
 
 ```bash
-npx casp update project @1.2.3
-npx casp update project 1.2.3
+npx casp update project --tag beta
+npx casp update project --tag=beta
+```
+
+Use when you want clearer syntax or PowerShell-safe argument parsing.
+
+### Update using named version option
+
+```bash
+npx casp update project --version 1.2.3
+npx casp update project --version=1.2.3
 ```
 
-Use when you want a deterministic pinned version.
+Use when you want explicit version selection with named syntax.
 
-### Non-interactive update
+### Non-interactive latest update
 
 ```bash
 npx casp update project -y
-npx casp update project @v4-alpha -y
-npx casp update project @1.2.3 -y
+```
+
+Use for scripted or CI updates to latest.
+
+### Non-interactive tagged update
+
+```bash
+npx casp update project beta -y
+npx casp update project --tag beta -y
+npx casp update project --tag=beta -y
+```
+
+Use for scripted or shell-safe tag-based upgrades.
+
+### Non-interactive versioned update
+
+```bash
 npx casp update project 1.2.3 -y
+npx casp update project --version 1.2.3 -y
+npx casp update project --version=1.2.3 -y
 ```
 
-Use when automation, CI, or scripted maintenance should skip confirmation prompts.
+Use for automated pinned upgrades.
 
-### Update safety notes
+## 6. Invalid Or Conflicting Update Cases
 
-The update flow is config-aware. Review `caspian.config.json` before running it, especially these areas:
+These cases matter because the newer updater parsing is stricter.
 
-- feature flags such as backend-only, Tailwind, TypeScript, MCP, and Prisma
-- `componentScanDirs`
-- `excludeFiles`, which protects customized files from overwrite
+### Missing value
 
-If you exclude a file, the updater preserves it, but you are responsible for merging future framework changes into that file manually.
+```bash
+npx casp update project --tag
+npx casp update project --version
+```
+
+Result: parsing error because the option is missing its value.
+
+### Too many positional arguments
+
+```bash
+npx casp update project beta extra
+```
+
+Result: parsing error because `update project` accepts at most one extra positional version or tag value.
+
+### Conflicting version sources
+
+```bash
+npx casp update project beta --tag latest
+npx casp update project 1.2.3 --version 2.0.0
+```
 
-## Prisma and Python ORM Regeneration
+Result: parsing error because more than one version source was provided.
+
+## 7. 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.
 
-### Required order after `prisma/schema.prisma` changes
+### Required order after schema changes
 
 ```bash
 npx prisma migrate dev
@@ -249,7 +595,7 @@ Use this order:
 
 1. Run `npx prisma migrate dev` first so migrations and the development database stay aligned.
 2. If `prisma/seed.ts` or seed data depends on the new schema, run `npx prisma generate` and then `npx prisma db seed`.
-3. Run `npx ppy generate` last so the Python ORM layer matches the updated Prisma schema.
+3. Run `npx ppy generate` last so the generated Python ORM layer matches the updated Prisma schema.
 
 Do not manually create or edit these generated files:
 
@@ -262,19 +608,50 @@ Do not manually create or edit these generated files:
 
 See [database.md](./database.md) for the full schema, migration, seed, and async usage guide.
 
-## Practical Recommendation Matrix
+## 8. Practical Recommendation Matrix
 
 | Goal | Recommended command |
 | --- | --- |
-| Minimal backend without database | `npx create-caspian-app my-app --backend-only -y` |
-| Small API or service with Prisma | `npx create-caspian-app my-app --backend-only --prisma -y` |
-| Full-stack app with styled UI and Prisma | `npx create-caspian-app my-app --tailwindcss --prisma -y` |
-| Rich full-stack app with TypeScript, Tailwind, and Prisma | `npx create-caspian-app my-app --tailwindcss --typescript --prisma -y` |
+| Minimal backend service | `npx create-caspian-app my-app --backend-only -y` |
+| Backend API with database support | `npx create-caspian-app my-app --backend-only --prisma -y` |
+| Full-stack app with styled UI and database support | `npx create-caspian-app my-app --tailwindcss --prisma -y` |
+| Full-stack app with richer frontend tooling and Prisma | `npx create-caspian-app my-app --tailwindcss --typescript --prisma -y` |
 | Full-stack app with everything enabled | `npx create-caspian-app my-app --tailwindcss --typescript --mcp --prisma -y` |
 | Realtime preset | `npx create-caspian-app my-app --starter-kit=realtime -y` |
 | Update current project to latest | `npx casp update project` |
-| Update current project in automation | `npx casp update project -y` |
-| Update current project to an exact version | `npx casp update project @1.2.3 -y` |
+| Update current project to beta safely in PowerShell | `npx casp update project --tag beta` |
+| 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
+
+The CLI reads `caspian.config.json` to decide how it should interact with the project.
+
+Important configuration areas include:
+
+- project identity and root path
+- feature toggles such as backend-only, Tailwind, MCP, Prisma, and TypeScript
+- component scan directories
+- `excludeFiles`, which protects customized files from overwrite during updates
+
+Use `excludeFiles` in `caspian.config.json` to prevent the update command from overwriting files you have customized.
+
+This is useful for protecting:
+
+- stylesheets
+- configuration files
+- entry-point files
+- other locally modified framework-managed files
+
+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
+
+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.
+3. The creator reuses an existing `.venv` if one is already present instead of recreating it every time.
+4. Starter kits still support later overrides via explicit CLI flags.
+5. Frontend-oriented flags are only fully meaningful when `backendOnly` is false.
 
 ## AI Routing Notes
 
@@ -285,6 +662,7 @@ If an AI agent is deciding which command flow to use, apply these rules first.
 - Add `-y` when the user wants automation, CI, or a no-prompt flow.
 - Treat `--tailwindcss` and `--typescript` as frontend-oriented flags. They are not meaningful in normal backend-only scaffolds.
 - Treat starter kit defaults as a base layer that can be overridden by explicit flags.
+- Read `caspian.config.json` before running update commands.
 - When `prisma/schema.prisma` changes, run `npx prisma migrate dev` first, then any required seed refresh, then `npx ppy generate`.
 - Never hand-edit generated Python ORM files under `src/lib/prisma/` or `settings/prisma-schema.json`.
 - Read [database.md](./database.md) before generating Prisma schema, migration, seed, or ORM guidance.

package/dist/docs/fetch-data.md

@@ -3,9 +3,10 @@ title: Fetch Data
 description: Fetch first-render and interactive data in Caspian with async route functions, `@rpc()` actions, `pp.rpc()`, streaming, and uploads, with RPC as the default browser-to-server data path.
 related:
   title: Related docs
-  description: Use the routing guide to place route logic correctly, then use the auth guide for protected actions, the state guide for transient request-scoped mutation state, the cache guide for reusable first-render HTML, and the PulsePoint runtime guide for client-side `pp.rpc()` details.
+  description: Use the routing guide to place route logic correctly, then use the auth guide for protected actions, the MCP guide for AI-facing tools, the state guide for transient request-scoped mutation state, the cache guide for reusable first-render HTML, and the PulsePoint runtime guide for client-side `pp.rpc()` details.
   links:
     - /docs/auth
+    - /docs/mcp
     - /docs/state
     - /docs/database
     - /docs/cache
@@ -19,6 +20,8 @@ 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`.
+
 ## Overview
 
 Caspian has two main data-loading paths:

package/dist/docs/index.md

@@ -7,6 +7,7 @@ related:
   links:
     - /docs/installation
     - /docs/commands
+    - /docs/mcp
     - /docs/project-structure
     - /docs/components
 ---
@@ -36,7 +37,8 @@ The packaged Caspian docs distributed by the current toolchain also live here:
 ## Available Documents
 
 - `installation.md` - First-time setup flow for creating a new Caspian application
-- `commands.md` - Main Caspian CLI workflows for project creation, starter kits, updates, and Prisma or ORM-aware maintenance
+- `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
 - `components.md` - Create reusable Python components, template-backed UI, JSX-style imports, and the single-parent root rule for component HTML files
@@ -57,7 +59,7 @@ 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, `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.
+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.

package/dist/docs/installation.md

@@ -3,8 +3,10 @@ title: Installation
 description: Learn how to create a new Caspian application so AI agents use the first-time setup flow instead of assuming an existing project is already in place.
 related:
   title: Related docs
-  description: Continue with the routing and structure guides after scaffold so the new app follows Caspian conventions.
+  description: Continue with the routing, structure, and MCP guides after scaffold so the new app follows Caspian conventions and keeps optional FastMCP files in the right place.
   links:
+    - /docs/commands
+    - /docs/mcp
     - /docs/routing
     - /docs/project-structure
     - /docs/index
@@ -54,6 +56,8 @@ 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
 
+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
 
 For the best development experience, use these VS Code extensions:
@@ -83,6 +87,7 @@ In this workspace, `npm run dev` is backed by BrowserSync plus PostCSS watchers,
 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 `pulsepoint.md` before generating interactive frontend behavior.
 - Read `fetch-data.md` before adding browser-triggered reads, writes, uploads, or streams.
@@ -97,5 +102,6 @@ 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.
+- 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

@@ -0,0 +1,102 @@
+---
+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.
+related:
+  title: Related docs
+  description: Start with project structure for file placement, then use commands for local run flows and index for documentation routing.
+  links:
+    - /docs/project-structure
+    - /docs/commands
+    - /docs/fetch-data
+    - /docs/index
+---
+
+This page documents the Model Context Protocol workflow present in this workspace.
+
+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`.
+
+## Overview
+
+Use these rules as the default MCP workflow in this workspace:
+
+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.
+
+## Current 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.
+
+## Current Tools
+
+The app-owned MCP server currently exposes these read-only tools:
+
+- `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`.
+
+Add or change tools in `src/lib/mcp/mcp_server.py`.
+
+## Running The Server
+
+### Preferred local commands
+
+```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
+
+On this Windows workspace, the direct FastMCP commands are:
+
+```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:
+
+1. `MCP_SERVER_SPEC`
+2. `src/lib/mcp/fastmcp.json`
+3. `fastmcp.json`
+4. `mcp.json`
+
+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.
+
+## 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.

package/dist/docs/project-structure.md

@@ -1,13 +1,14 @@
 ---
 title: Project Structure
-description: Understand the default Caspian project layout so AI agents place routes, reusable components, PulsePoint templates, RPC actions, validation helpers, auth code, configuration, and database changes in the correct directories.
+description: Understand the default Caspian project layout so AI agents place routes, reusable components, PulsePoint templates, RPC actions, validation helpers, auth code, MCP files, configuration, and database changes in the correct directories.
 related:
   title: Related docs
-  description: Start with installation for new apps, then use the component guide for reusable UI, the auth guide for bootstrap and session wiring, the routing guide to map URLs correctly, and the cache guide when route HTML should be reused safely.
+  description: Start with installation for new apps, then use the component guide for reusable UI, the auth guide for bootstrap and session wiring, the MCP guide for server layout, the routing guide to map URLs correctly, and the cache guide when route HTML should be reused safely.
   links:
     - /docs/installation
     - /docs/components
     - /docs/auth
+    - /docs/mcp
     - /docs/routing
     - /docs/cache
     - /docs/database
@@ -31,6 +32,7 @@ Before an AI agent decides which Caspian features are available in a workspace,
 - `src/` contains routes, page templates, styles, and shared libraries.
 - `src/components/` contains reusable Python components and optional same-name HTML templates.
 - `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.
 - `public/` contains static assets served directly.
 - `main.py` is the application entry point.
@@ -62,6 +64,9 @@ my-app/
     lib/
       auth/
         auth_config.py
+      mcp/
+        fastmcp.json
+        mcp_server.py
       prisma/
         __init__.py
         db.py
@@ -112,6 +117,8 @@ Use this folder for shared helpers, reusable validators, RPC-facing service wrap
 
 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/`.
 
+When MCP is enabled in the current workspace, this folder also contains the app-owned FastMCP server under `src/lib/mcp/`.
+
 ### Shared Database Helpers
 
 If your Python routes or RPC actions need reusable database access code, keep that helper layer under `src/lib/` and extend the existing `src/lib/prisma/` package.
@@ -122,6 +129,17 @@ In this workspace, Prisma schema and seed files live under `prisma/`, while the
 
 Use this folder for authentication-specific project code. The main auth configuration file lives at `src/lib/auth/auth_config.py`.
 
+### `src/lib/mcp/`
+
+Use this folder for app-owned Model Context Protocol server files.
+
+In the current workspace:
+
+- `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`.
+
+Keep MCP tool definitions here instead of placing them in route files, `main.py`, or framework internals.
+
 ### `prisma/`
 
 This folder contains your database model definitions in `schema.prisma` and any seed logic such as `seed.ts`.
@@ -153,12 +171,22 @@ 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: false`, `prisma: true`, `typescript: false`, and `componentScanDirs: ["src"]`.
+In the current workspace, `caspian.config.json` shows `backendOnly: false`, `tailwindcss: true`, `mcp: true`, `prisma: true`, `typescript: false`, and `componentScanDirs: ["src"]`.
 
 ### `src/lib/auth/auth_config.py`
 
 The project auth configuration file. Use this path when changing authentication behavior.
 
+### `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.
+
+### `src/lib/mcp/fastmcp.json`
+
+The default FastMCP config file for this 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.
+
 ### `src/app/layout.html`
 
 The root layout shared across pages.
@@ -204,9 +232,11 @@ If an AI agent is deciding where to make changes, use these rules first.
 - 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.
 - 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/`.
 - 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.9",
+  "version": "0.0.11",
   "description": "Caspian tooling",
   "main": "index.js",
   "scripts": {