caspian-utils 0.0.7 → 0.0.9

package/dist/docs/commands.md

@@ -1,9 +1,9 @@
 ---
 title: Commands
-description: Use the Caspian CLI reference to scaffold projects, generate code, and update framework files without confusing first-time setup with existing-project maintenance.
+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.
 related:
   title: Related docs
-  description: Start with installation for new apps, then use the routing and structure guides to place generated files correctly.
+  description: Start with installation for new apps, then use database and structure docs when commands affect schema, generated ORM files, or project layout.
   links:
     - /docs/installation
     - /docs/database
@@ -12,108 +12,281 @@ related:
     - /docs/index
 ---
 
-This page summarizes the main Caspian CLI workflows for creating projects, generating code, and updating an existing app.
+This page documents the current Caspian command families used with this workspace and the surrounding docs toolchain.
 
 ## Overview
 
-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 the scaffold and project-update commands below as external `npx` workflows rather than project-local executables.
+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.
 
-Use Caspian CLI commands for three main tasks:
+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`.
 
-- Create a new application.
-- Generate code from your Prisma schema.
-- Update framework-managed project files.
+Use these command families for different tasks:
 
-Before running update commands, review `caspian.config.json` because it controls overwrite 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. |
 
-## Project Creation
+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 the interactive scaffold when starting a new Caspian app:
+## Supported Flags
+
+The scaffold CLI exposes these feature flags:
+
+| 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. |
+
+Add `-y` to most create or update examples below when you want the same flow to run without prompts.
+
+## Create a New Project
+
+### Interactive create
 
 ```bash
-npx create-caspian-app@latest
+npx create-caspian-app my-app
 ```
 
-You can also create a project with starter-kit flags:
+Use when you want the normal interactive scaffold flow. The CLI can prompt for project name and feature toggles.
+
+### Non-interactive create
 
 ```bash
-npx create-caspian-app my-app --starter-kit=fullstack
+npx create-caspian-app my-app -y
 ```
 
-For a custom source setup, the CLI also supports a custom starter flow:
+Use when you already know the desired feature flags or when automation should avoid prompts.
+
+Without extra flags, the non-interactive default behaves like this:
+
+- `backendOnly: false`
+- `tailwindcss: false`
+- `typescript: false`
+- `mcp: false`
+- `prisma: false`
+
+## Backend-only Create 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.
+
+| 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. |
+
+You can append `-y` to any backend-only example above.
+
+### Accepted but not recommended in backend-only mode
 
 ```bash
-npx create-caspian-app my-tool --starter-kit=custom ...
+npx create-caspian-app my-app --backend-only --tailwindcss
+npx create-caspian-app my-app --backend-only --typescript
+npx create-caspian-app my-app --backend-only --tailwindcss --typescript
 ```
 
-After scaffolding, use `routing.md` to understand how Caspian maps `src/app` folders to URLs.
+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.
 
-## Installation Flags
+## Full-stack and Frontend-enabled Create Combinations
 
-Common scaffold flags include:
+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.
 
-- `--backend-only` for API-only projects without frontend assets
-- `--tailwindcss` to install Tailwind CSS support
-- `--typescript` to add TypeScript support and any scaffold-specific TypeScript build/config files
-- `--mcp` to initialize a Model Context Protocol server for AI agents
-- `--prisma` to initialize Prisma ORM support
+| 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. |
 
-## Code Generation
+You can append `-y` to any frontend-enabled example above.
 
-When your Prisma schema changes in this workspace, regenerate the client with the local Prisma CLI:
+## Starter Kit Commands
+
+### List available starter kits
 
 ```bash
-npx prisma generate
+npx create-caspian-app --list-starter-kits
 ```
 
-This flow regenerates the Prisma client defined by `generator client` in `prisma/schema.prisma`. In the current workspace, that generator uses `prisma-client-js`.
+Use when you want to inspect the built-in starter kit catalog before creating a project.
+
+### Built-in starter kits
+
+The current command reference includes these built-in starter kits:
 
-This workspace already includes an app-owned Python database layer in `src/lib/prisma/`, so reuse that package for Python-side database access instead of creating a second helper.
+| 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. |
 
-See `database.md` for the full Prisma workflow, including `.env`, `prisma.config.ts`, migrations, and async usage patterns.
+If you want frontend TypeScript, add `--typescript` explicitly rather than assuming it is implied by a starter kit preset.
 
-## Update Project
+Append `-y` to any starter kit example when you want the same preset without prompts.
 
-Use the project update command for existing Caspian apps:
+### Starter kit overrides
+
+```bash
+npx create-caspian-app my-app --starter-kit=basic --prisma
+npx create-caspian-app my-app --starter-kit=fullstack --typescript
+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.
+
+### Custom starter kit source
+
+```bash
+npx create-caspian-app my-app --starter-kit=custom --starter-kit-source=https://github.com/user/repo
+```
+
+You can combine extra flags with the custom source:
+
+```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.
+
+## Update an Existing Project
+
+The updater wrapper recognizes the `update project` family:
 
 ```bash
 npx casp update project
 ```
 
-This command updates framework-managed project files and can overwrite entry points, styles, or configuration files if they are not protected. The `casp` binary is not bundled locally in this workspace, so verify the external CLI package before automating this command.
+Use this only inside an existing Caspian project that already has `caspian.config.json` in the current directory.
+
+### Update to latest
 
-## Configuration
+```bash
+npx casp update project
+```
+
+Use when you want the normal refresh to the latest framework-managed files.
+
+### Update to a specific tag
+
+```bash
+npx casp update project @v4-alpha
+```
+
+Use when you want a prerelease or named tag instead of the latest stable release.
+
+### Update to a specific version
+
+```bash
+npx casp update project @1.2.3
+npx casp update project 1.2.3
+```
+
+Use when you want a deterministic pinned version.
+
+### Non-interactive update
+
+```bash
+npx casp update project -y
+npx casp update project @v4-alpha -y
+npx casp update project @1.2.3 -y
+npx casp update project 1.2.3 -y
+```
+
+Use when automation, CI, or scripted maintenance should skip confirmation prompts.
+
+### Update safety notes
+
+The update flow is config-aware. Review `caspian.config.json` before running it, especially these areas:
+
+- feature flags such as backend-only, Tailwind, TypeScript, MCP, and Prisma
+- `componentScanDirs`
+- `excludeFiles`, which protects customized files from overwrite
+
+If you exclude a file, the updater preserves it, but you are responsible for merging future framework changes into that file manually.
+
+## 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
+
+```bash
+npx prisma migrate dev
+
+# Only when seed flow or prisma/seed.ts depends on the new schema:
+npx prisma generate
+npx prisma db seed
+
+npx ppy generate
+```
 
-The CLI reads `caspian.config.json` to decide how it should interact with the project.
+Use this order:
 
-Important configuration areas include:
+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.
 
-- Project identity and root path
-- Feature toggles such as backend-only, Tailwind, MCP, Prisma, and TypeScript
-- Component scan directories
-- `excludeFiles` rules for protecting local changes during updates
+Do not manually create or edit these generated files:
 
-## `excludeFiles` Strategy
+- `src/lib/prisma/__init__.py`
+- `src/lib/prisma/db.py`
+- `src/lib/prisma/models.py`
+- `settings/prisma-schema.json`
 
-Use `excludeFiles` in `caspian.config.json` to prevent the update command from overwriting files you have customized.
+`npx ppy generate` owns those files. Treat `src/lib/prisma/` as the app's generated Python database layer, not as a manual editing surface.
 
-This is useful for protecting:
+See [database.md](./database.md) for the full schema, migration, seed, and async usage guide.
 
-- Stylesheets
-- Configuration files
-- Entry-point files
-- Other locally modified framework-managed files
+## Practical Recommendation Matrix
 
-If you exclude a file, it will be preserved during updates, but you may need to merge future framework changes into that file manually.
+| 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` |
+| 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` |
 
 ## AI Routing Notes
 
 If an AI agent is deciding which command flow to use, apply these rules first.
 
-- Use `npx create-caspian-app@latest` when the user is creating a new project.
-- Use `npx casp update project` only for an existing Caspian project.
-- Read `caspian.config.json` before running update commands.
-- Use `npx prisma generate` after Prisma schema changes in this workspace.
-- Check `database.md` when the task involves Prisma setup, schema updates, or the current workspace's schema, migration, and seed tooling.
-- Check [routing.md](./routing.md) before generating or modifying route folders under `src/app/`.
-- Check [project-structure.md](./project-structure.md) before placing generated files into the project.
+- Use `npx create-caspian-app ...` only when the user is creating a new Caspian project.
+- Use `npx casp update project ...` only when the user is already inside an existing Caspian project.
+- 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.
+- 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.
+- Read [routing.md](./routing.md) before generating or modifying route folders under `src/app/`.
+- Read [project-structure.md](./project-structure.md) before placing generated files into the project.

package/dist/docs/database.md

@@ -22,9 +22,10 @@ The standard Prisma flow in Caspian is:
 
 1. Define models in `prisma/schema.prisma`.
 2. Configure `DATABASE_URL` in `.env`.
-3. Run `npx prisma generate` after schema changes.
-4. Use the generated client from Node-side tooling such as `prisma/seed.ts`.
-5. Reuse the shared Python database layer in `src/lib/prisma/` when Python route or RPC code needs database access.
+3. Run `npx prisma migrate dev` after schema changes so the development database and migration history stay aligned.
+4. If the change requires seed data, run `npx prisma generate` and then `npx prisma db seed`.
+5. Run `npx ppy generate` so the Python ORM classes stay aligned with the updated schema.
+6. Reuse the shared Python database layer in `src/lib/prisma/` when Python route or RPC code needs database access, and never hand-edit generated ORM classes.
 
 Use this workflow instead of writing raw SQL first. Drop to raw SQL only when a query cannot be expressed clearly with the generated client.
 
@@ -99,22 +100,30 @@ model Post {
 }
 ```
 
-After changing the schema, run `npx prisma generate` so the generated Node Prisma client stays in sync with the schema. If the Python layer in `src/lib/prisma/` depends on the updated shape, regenerate or refresh that application-owned code too.
+After changing the schema, use this order in the current workspace:
+
+1. Run `npx prisma migrate dev`.
+2. If seed data or the seed script needs the new schema, run `npx prisma generate` and then `npx prisma db seed`.
+3. Run `npx ppy generate` to refresh the generated Python ORM classes.
+
+Do not hand-edit generated Prisma or Python ORM output. Treat `prisma/schema.prisma` as the source of truth and regenerate from it.
 
 ## Command Reference
 
 Use these commands for the normal Prisma lifecycle in Caspian:
 
-- `npx prisma generate` compiles `schema.prisma` into the generated Prisma client. Run this after every schema change.
-- `npx prisma migrate dev` creates and applies a development migration.
+- `npx prisma migrate dev` creates and applies a development migration. This is the first command to run after changing `prisma/schema.prisma`.
+- `npx prisma generate` compiles `schema.prisma` into the generated Node Prisma client. Run it before `npx prisma db seed` when the updated seed flow depends on the new schema.
+- `npx prisma db seed` runs the configured seeding script.
+- `npx ppy generate` regenerates the Python ORM classes used by the app. Use this after every schema change.
 - `npx prisma migrate deploy` applies pending migrations in deployment environments.
 - `npx prisma db push` syncs schema changes without creating a migration file, which is useful for prototyping.
-- `npx prisma db seed` runs the configured seeding script.
 - `npx prisma studio` opens the Prisma data browser.
 
 Default rule:
 
-- Use `npx prisma generate` every time the schema changes.
+- When `prisma/schema.prisma` changes, use this order: `npx prisma migrate dev`; if seeding is involved, run `npx prisma generate` and `npx prisma db seed`; then run `npx ppy generate`.
+- Never hand-edit generated Prisma or Python ORM classes, and never replace `npx ppy generate` with a manual class update.
 - Use migrations for tracked application changes.
 - Use `db push` only when you intentionally want a faster, migration-free prototype loop.
 
@@ -142,7 +151,7 @@ After `npx prisma generate`, Prisma writes the generated JavaScript client into
 
 This workspace already includes an app-owned async Python database package that exports `prisma`, `PrismaClient`, generated models, and helper types.
 
-If Python route or RPC code needs database access, import from `src.lib.prisma` and keep that import path explicit in application code.
+If Python route or RPC code needs database access, import from `src.lib.prisma` and keep that import path explicit in application code. Refresh generated classes with `npx ppy generate` instead of editing them manually.
 
 ## Python Route Usage
 
@@ -306,8 +315,9 @@ Use raw SQL sparingly. Prefer the generated Prisma API when the query can be exp
 
 ## Recommended Project Rules
 
-- Keep the schema in `prisma/schema.prisma` and regenerate the client after changes.
+- Keep the schema in `prisma/schema.prisma` and follow the required regeneration order after changes: `npx prisma migrate dev`, optional seed flow, then `npx ppy generate`.
 - Reuse `src/lib/prisma/` for Python-side database access instead of creating a second bridge.
+- Never hand-edit generated Prisma or Python ORM classes.
 - Keep reusable database helpers in `src/lib/`, and keep route-specific orchestration in `src/app/`.
 - Use `await` with Prisma operations.
 - Convert Prisma objects to template-safe dictionaries when rendering HTML.
@@ -320,7 +330,10 @@ If an AI agent is working on a Caspian app with Prisma enabled, apply these rule
 
 - Treat Prisma as the default ORM and persistence layer.
 - Read `prisma/schema.prisma` before proposing model, relation, or field changes.
-- Run `npx prisma generate` after schema changes.
+- When `prisma/schema.prisma` changes, run `npx prisma migrate dev` first.
+- If the schema change requires seed data, run `npx prisma generate` and then `npx prisma db seed`.
+- Run `npx ppy generate` after schema changes to refresh the Python ORM classes.
+- Never hand-edit generated Prisma or Python ORM classes.
 - Read `prisma.config.ts` and `prisma/seed.ts` when you need the current workspace's Prisma tooling examples.
 - Reuse the existing `src/lib/prisma/` package when the Python app needs database access.
 - Put reusable database helpers in `src/lib/`; keep route and RPC orchestration in `src/app/`.

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, generation, updates, and config-aware maintenance
+- `commands.md` - Main Caspian CLI workflows for project creation, starter kits, updates, and Prisma or ORM-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.7",
+  "version": "0.0.9",
   "description": "Caspian tooling",
   "main": "index.js",
   "scripts": {