caspian-utils 0.0.9 → 0.0.10

package/dist/docs/commands.md

@@ -1,6 +1,6 @@
 ---
 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.
@@ -18,56 +18,119 @@ 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`.
+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.
 
-Use these command families for different tasks:
+This updated reference includes the newer updater behavior and the current scaffold behavior:
 
-| 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. |
+- 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: false`, `prisma: true`, `typescript: false`, and `componentScanDirs: ["src"]`.
+
+## 1. Main Command Families
+
+### Create a new project
+
+```bash
+npx create-caspian-app my-app
+```
 
-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).
+Use when you want to scaffold a new Caspian project from scratch.
 
-## Supported Flags
+### Create a project from a starter kit
 
-The scaffold CLI exposes these feature flags:
+```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`.
+
+### 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.
+
+## 2. Supported Flags And Options
+
+### 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 +138,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
+```
+
+Use when you want a simple backend project without frontend assets.
+
+#### 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
+```
 
-You can append `-y` to any backend-only example above.
+Use when you want a backend or API project with database tooling.
 
-### Accepted but not recommended in backend-only mode
+#### 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 +186,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 to inspect the built-in starter kit catalog before creating a project.
+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 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
+
+```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
 
-| 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=fullstack
+npx create-caspian-app my-app --starter-kit=fullstack -y
+```
 
-If you want frontend TypeScript, add `--typescript` explicitly rather than assuming it is implied by a starter kit preset.
+Use when you want the built-in full-stack preset.
 
-Append `-y` to any starter kit example when you want the same preset without prompts.
+Preset features:
 
-### Starter kit overrides
+- `backendOnly = false`
+- `tailwindcss = true`
+- `prisma = true`
+- `mcp = false`
+
+#### 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 +417,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
+```
+
+Result: parsing error because more than one version source was provided.
 
-## Prisma and Python ORM Regeneration
+## 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 +558,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 +571,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 +625,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/index.md

@@ -36,7 +36,7 @@ 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
 - `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

package/package.json

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