prisma-php 0.0.11 → 0.0.13

package/.github/copilot-instructions.md

@@ -2,11 +2,22 @@
 
 ## Source Of Truth
 
-- Treat `dist/docs/index.md` as the entry point for Prisma PHP guidance in this repo.
-- Read the matching doc in `dist/docs` before generating or editing framework-specific Prisma PHP code.
-- When updating AI guidance in this repo, keep `AGENTS.md`, `.github/copilot-instructions.md`, and `dist/docs` aligned.
+- For Prisma PHP applications, treat `node_modules/prisma-php/dist/docs/index.md` as the entry point for the installed framework version.
+- Read the matching doc in `node_modules/prisma-php/dist/docs` before generating or editing framework-specific Prisma PHP code.
+- Expect `AGENTS.md` in the project root and keep it aligned with the installed Prisma PHP docs contract.
+- In the Prisma PHP package source repo, keep `AGENTS.md`, `.github/copilot-instructions.md`, and `dist/docs` aligned so the published docs remain correct after install.
+- Do not assume installed consumer apps also ship a root `.github/copilot-instructions.md` unless the generator explicitly creates one.
 - Keep every `dist/docs/*.md` page AI-discoverable on its own: the frontmatter description and opening section should clearly say when agents should read that file and which adjacent docs to consult next.
 
+## Framework-Managed Package Scripts
+
+- Prisma PHP can generate `package.json` scripts for BrowserSync, Tailwind, TypeScript, WebSocket, MCP, Swagger docs, and related helpers.
+- Prefer `npm run dev` for ordinary local development and `npm run build` for ordinary production-style asset builds.
+- Do not default to telling users to run `npm run tailwind`, `npm run tailwind:build`, `npm run ts:watch`, or `npm run ts:build` after routine file changes, because those are usually orchestrated through the generated top-level scripts.
+- Use `npm run websocket` or `npm run mcp` only when isolating local runtime startup, debugging, or when the project's scripts show those services are not already covered by the normal development flow.
+- Use `npm run create-swagger-docs` only when Swagger or OpenAPI output must be intentionally generated or refreshed.
+- When package-script behavior matters, read `dist/docs/commands.md` first and inspect the actual `package.json` in the target project before assuming which scripts exist.
+
 ## Route File Conventions
 
 - For PulsePoint-aware `index.php` and nested `layout.php`, keep file order as PHP first, then one parent HTML element; keep the PulsePoint `<script>` as the last child inside that same root element.
@@ -17,26 +28,32 @@
 ## Component Boundary Rules
 
 - Distinguish PHPX class components from `ImportComponent` partials.
-- `ImportComponent` partials must output exactly one root element because Prisma PHP attaches serialized props and a stable `pp-component` attribute to that root.
+- `ImportComponent` partials must output exactly one root element because Prisma PHP uses that root as the imported component boundary and serializes props there.
 - Do not manually add `pp-component` inside `ImportComponent` partial source; Prisma PHP injects it there. For normal PulsePoint-aware route files, add `pp-component` to the single root element yourself.
 
 ## Relevant Docs
 
 - Project structure and feature placement: `dist/docs/project-structure.md`
 - CLI project creation and update commands: `dist/docs/commands.md`
+- First-time project installation and local setup: `dist/docs/installation.md`
+- Existing-project upgrades and feature refreshes: `dist/docs/upgrading.md`
+- TypeScript frontend tooling, the `typescript` flag, and `ts/main.ts` registration: `dist/docs/typescript.md`
 - Backend-only API usage and `backendOnly`: `dist/docs/backend-only.md`
 - Route and layout structure: `dist/docs/layouts-and-pages.md`
 - AI integration, provider-backed chat, streaming, and MCP boundary: `dist/docs/get-started-ia.md`
 - Data loading, `#[Exposed]`, and SSE streaming: `dist/docs/fetching-data.md`
 - PulsePoint runtime rules: `dist/docs/pulsepoint.md`
 - Component and `ImportComponent` rules: `dist/docs/components.md`
+- Cache behavior and `CacheHandler`: `dist/docs/caching.md`
 - Validation rules: `dist/docs/validator.md`
+- Prisma ORM schema, migrations, and generated PHP classes: `dist/docs/prisma-php-orm.md`
 - Environment variables and `PP\Env` usage: `dist/docs/env.md`
 - File uploads and file manager behavior: `dist/docs/file-manager.md`
 - Email and SMTP workflows: `dist/docs/email.md`
 - WebSocket and realtime behavior: `dist/docs/websocket.md`
 - MCP server and tool rules: `dist/docs/mcp.md`
 - Authentication: `dist/docs/authentication.md`
+- Error handling, expected failures, and route error files: `dist/docs/error-handling.md`
 - Metadata and icons: `dist/docs/metadata-and-og-images.md`
 - API-style handlers and webhooks: `dist/docs/route-handlers.md`
 - Swagger/OpenAPI generation and `swaggerDocs`: `dist/docs/swagger-docs.md`

package/dist/docs/authentication.md

@@ -33,7 +33,7 @@ Do not assume another framework’s auth abstractions apply directly.
 
 ## Read this doc when you need
 
-- **route privacy defaults, `AuthConfig.php`, JWT session lifecycle, `Auth::signIn(...)`, `Auth::signOut(...)`, `refreshUserSession(...)`, route RBAC, or provider overview** → official `auth-get-started`
+- **route privacy defaults, `AuthConfig.php`, JWT session lifecycle, `Auth::getInstance()->signIn(...)`, `Auth::getInstance()->signOut(...)`, `Auth::getInstance()->refreshUserSession(...)`, route RBAC, or provider overview** → official `auth-get-started`
 - **email/password registration, login, password hashing, CSRF-aware credential flow, or user/role schema design** → official `credentials`
 - **social login, provider credentials, callback route handling, account linking, or OAuth account schema** → official `state-manager-auth`
 
@@ -45,9 +45,9 @@ The official docs describe these major concepts:
 
 - `AuthConfig.php` is the central place for defining route protection strategy and role-based route rules
 - sessions are managed through Prisma PHP auth helpers rather than ad hoc cookie code
-- `Auth::signIn(...)` creates the session payload
-- `Auth::signOut(...)` ends the session and can redirect
-- `refreshUserSession(...)` updates the active session payload when user permissions or profile data change
+- `Auth::getInstance()->signIn(...)` creates the session payload
+- `Auth::getInstance()->signOut(...)` ends the session and can redirect
+- `Auth::getInstance()->refreshUserSession(...)` updates the active session payload when user permissions or profile data change
 - route-level RBAC and function-level access control are separate but complementary concerns
 
 ## Security strategy
@@ -88,24 +88,24 @@ Mental model:
 
 ### Sign in
 
-Use `Auth::signIn(...)` after credentials or provider identity are validated.
+Use `Auth::getInstance()->signIn(...)` after credentials or provider identity are validated.
 
 The session payload should contain the user data your app needs for identity and authorization decisions, commonly including:
 
 - `id`
 - `role`
 
-Do not invent a separate session writer when the framework already documents `Auth::signIn(...)`.
+Do not invent a separate session writer when the framework already documents `Auth::getInstance()->signIn(...)`.
 
 ### Sign out
 
-Use `Auth::signOut(...)` to destroy the session and invalidate the client cookie.
+Use `Auth::getInstance()->signOut(...)` to destroy the session and invalidate the client cookie.
 
 When the flow needs a post-logout redirect, use the documented redirect argument instead of custom manual cookie clearing.
 
 ### Live session refresh
 
-Use `refreshUserSession(...)` when a currently signed-in user’s auth payload must change immediately, such as:
+Use `Auth::getInstance()->refreshUserSession(...)` when a currently signed-in user’s auth payload must change immediately, such as:
 
 - role promotion or demotion
 - profile data updates included in the auth payload
@@ -157,7 +157,7 @@ When backend functions are protected with `#[Exposed(allowedRoles: [...])]`, kee
 
 The credentials docs describe the classic email/password flow as a full-stack Prisma PHP pattern where backend logic and form UI can live together in route files.
 
-### Schema expectations
+### Provider schema expectations
 
 For credentials auth, the docs show a user model with fields such as:
 
@@ -185,7 +185,7 @@ The documented login flow uses:
 - a route such as `src/app/auth/login/index.php`
 - a user lookup through Prisma ORM
 - `password_verify(...)` for password comparison
-- `Auth::signIn(...)` with the session payload
+- `Auth::getInstance()->signIn(...)` with the session payload
 - a redirect after successful sign-in
 
 ### Validation rule

package/dist/docs/backend-only.md

@@ -95,7 +95,7 @@ For backend-only apps, the default route file should stay explicit and small:
 <?php
 
 use Lib\Prisma\Classes\Prisma;
-use PP\Header\Boom;
+use PP\Headers\Boom;
 use PP\Request;
 
 if (!Request::$isGet) {

package/dist/docs/bootstrap-runtime.md

@@ -0,0 +1,145 @@
+---
+title: Bootstrap and Runtime
+description: Learn how Prisma PHP bootstraps requests, initializes runtime helpers, resolves routes, and protects function calls with cookies and FUNCTION_CALL_SECRET.
+related:
+  title: Related docs
+  description: Use env for configuration, fetching-data for exposed functions, and error-handling for runtime failures.
+  links:
+    - /docs/env
+    - /docs/fetching-data
+    - /docs/error-handling
+    - /docs/project-structure
+---
+
+This page explains the Prisma PHP runtime bootstrap flow used by the current project scaffold.
+
+If a task involves request initialization, route resolution, local-store callbacks, `FUNCTION_CALL_SECRET`, `prisma_php_csrf`, or the order in which Prisma PHP runtime helpers are initialized, AI agents should read this page first and keep generated code aligned with `bootstrap.php`.
+
+## AI rule: read the bootstrap docs first
+
+Before changing runtime bootstrap behavior, use this order:
+
+1. Read `prisma-php.json`.
+2. Read `env.md` for runtime configuration values.
+3. Read this page for init order, request protection, and route resolution.
+4. Read `fetching-data.md` when the task also involves `#[Exposed]` functions or streamed responses.
+5. Inspect `bootstrap.php` only when the docs still leave a gap.
+
+## Runtime init order
+
+The current Prisma PHP bootstrap initializes the runtime in this order:
+
+1. `date_default_timezone_set(Env::string('APP_TIMEZONE', 'UTC'))`
+2. `PrismaPHPSettings::init()`
+3. `Request::init()`
+4. `StateManager::init()`
+5. `MainLayout::init()`
+6. `ErrorHandler::registerHandlers()`
+7. set the `pp_local_store_key` cookie from `PrismaPHPSettings::$localStoreKey`
+8. create or validate the `prisma_php_csrf` cookie
+9. resolve the current route, included content file, and active layouts
+10. run auth checks and fatal-error checks
+
+When AI changes bootstrap-sensitive code, preserve that ordering unless the task is explicitly about changing the framework runtime.
+
+## What `PrismaPHPSettings::init()` loads
+
+The runtime reads Prisma PHP project settings from these files:
+
+- `prisma-php.json`
+- `settings/files-list.json`
+- `settings/class-imports.json`
+- `settings/request-data.json`
+
+It also derives the local storage callback key from `LOCALSTORE_KEY` in the environment, normalized to a lowercase underscore-separated value.
+
+## Request initialization
+
+`Request::init()` normalizes the current request into the Prisma PHP request model.
+
+That initialization populates:
+
+- HTTP method flags such as `Request::$isGet`, `Request::$isPost`, and `Request::$isDelete`
+- unified request parameters through `Request::$params`
+- dynamic route parameters through `Request::$dynamicParams`
+- local storage values through `Request::$localStorage`
+- request metadata such as `Request::$uri`, `Request::$pathname`, `Request::$documentUrl`, and `Request::$requestedWith`
+
+Do not invent a second request abstraction when the task already fits the current `PP\Request` model.
+
+## Route resolution and layout collection
+
+The bootstrap resolves the active content file from the incoming request URI and then collects matching layouts.
+
+Important runtime rules:
+
+- `AuthMiddleware::handle($pathname)` runs during route resolution
+- grouped routes and dynamic routes are resolved before falling back to root precedence
+- the root layout is collected first when it exists
+- nested layouts are collected from the route tree
+- `files-list.json` is read by the runtime, but consumer-app code should not edit it manually
+
+For route creation or route placement, continue using `project-structure.md`, `layouts-and-pages.md`, and `route-handlers.md`.
+
+## Local store callback contract
+
+Prisma PHP reserves a browser callback channel for local storage synchronization.
+
+The runtime sets a `pp_local_store_key` cookie using `PrismaPHPSettings::$localStoreKey`.
+
+When the incoming `HTTP_X_PP_FUNCTION` header matches that local store key, Prisma PHP treats the request as a local-store callback and validates the CSRF token before returning JSON.
+
+Do not replace that flow with a custom local storage callback protocol unless the task is explicitly about changing the framework runtime.
+
+## Function-call CSRF contract
+
+Prisma PHP protects callback-style requests with a CSRF token signed by `FUNCTION_CALL_SECRET`.
+
+### `FUNCTION_CALL_SECRET`
+
+`FUNCTION_CALL_SECRET` is required for CSRF protection.
+
+If it is missing, bootstrap throws a runtime exception instead of silently disabling protection.
+
+### `prisma_php_csrf`
+
+The runtime stores the CSRF token in the `prisma_php_csrf` cookie.
+
+The token format is:
+
+- `nonce.signature`
+
+The signature is an HMAC-SHA256 hash of the nonce using `FUNCTION_CALL_SECRET`.
+
+If the cookie is missing or invalid, bootstrap generates a new token.
+
+### Validation rules
+
+Protected callback-style requests must send an `X-CSRF-TOKEN` header that exactly matches the `prisma_php_csrf` cookie.
+
+Validation fails when:
+
+- the secret is missing
+- the header is missing
+- the cookie is missing
+- the header and cookie do not match
+- the cookie format is invalid
+- the HMAC signature does not validate
+
+For these failures, bootstrap returns a JSON error response instead of allowing the callback to continue.
+
+## Runtime guidance for AI agents
+
+- when changing `.env` values related to runtime behavior, read `env.md` first
+- when working on `#[Exposed]` functions, fetch callbacks, or streams, combine this page with `fetching-data.md`
+- when the task touches route selection, layout wrapping, or route file choice, combine this page with `project-structure.md` and `layouts-and-pages.md`
+- when runtime failures are expected, combine this page with `error-handling.md`
+- do not remove or bypass `FUNCTION_CALL_SECRET`, `prisma_php_csrf`, or `pp_local_store_key` unless the task explicitly changes the security model
+
+## Good to know
+
+- Prisma PHP bootstrap initializes `MainLayout` before route files are rendered
+- Prisma PHP bootstrap initializes `ErrorHandler` before runtime inclusion continues
+- `PP\Request` is the normalized request source of truth
+- `pp_local_store_key` and `prisma_php_csrf` are runtime cookies managed by bootstrap
+- `FUNCTION_CALL_SECRET` is required for callback CSRF protection

package/dist/docs/commands.md

@@ -7,6 +7,7 @@ related:
   links:
     - /docs/installation
     - /docs/upgrading
+    - /docs/typescript
 ---
 
 This guide explains what each Prisma PHP CLI command does, when to use it, and how the create and update workflows fit together.
@@ -91,13 +92,13 @@ This flag enables non-interactive mode.
 
 Instead of stopping for terminal prompts, the CLI proceeds with the provided flags and default values.
 
-### Use this when
+#### When to use `-y`
 
 - running automation or CI
 - scaffolding quickly without prompts
 - generating predictable output from scripts
 
-### Example
+#### `-y` example
 
 ```bash package="npm"
 npx create-prisma-php-app my-app -y
@@ -111,13 +112,13 @@ Creates a backend-only project.
 
 This is appropriate for API-first or server-only applications where the project should center on handler-style routes instead of the usual full-stack page flow.
 
-### Use this when
+#### When to use `--backend-only`
 
 - building REST APIs
 - creating server-only services
 - building a backend for a separate frontend client
 
-### Example
+#### `--backend-only` example
 
 ```bash package="npm"
 npx create-prisma-php-app my-app --backend-only
@@ -129,13 +130,13 @@ Enables Swagger and OpenAPI documentation support.
 
 This prepares the project for API schema generation and API documentation workflows.
 
-### Use this when
+#### When to use `--swagger-docs`
 
 - documenting API endpoints
 - sharing API contracts with frontend or third-party consumers
 - generating OpenAPI-based tooling from the project
 
-### Example
+#### `--swagger-docs` example
 
 ```bash package="npm"
 npx create-prisma-php-app my-app --backend-only --swagger-docs
@@ -147,13 +148,13 @@ Enables Tailwind CSS support.
 
 This prepares frontend styling with Tailwind-related files and scripts.
 
-### Use this when
+#### When to use `--tailwindcss`
 
 - building dashboards or admin panels
 - creating a styled full-stack UI
 - starting a project that should use utility-first CSS from day one
 
-### Example
+#### `--tailwindcss` example
 
 ```bash package="npm"
 npx create-prisma-php-app my-app --tailwindcss
@@ -163,13 +164,17 @@ npx create-prisma-php-app my-app --tailwindcss
 
 Enables TypeScript support for the frontend toolchain.
 
-### Use this when
+When this flag is enabled, Prisma PHP should keep frontend TypeScript in the root `ts/` directory, register browser helpers from `ts/main.ts`, and use those registered globals from template expressions and PulsePoint component scripts.
+
+Read `typescript.md` for the TypeScript-specific workflow.
+
+#### When to use `--typescript`
 
 - you want typed frontend code
 - you want stronger editor tooling for frontend work
 - your project will include frontend TypeScript assets
 
-### Example
+#### `--typescript` example
 
 ```bash package="npm"
 npx create-prisma-php-app my-app --typescript
@@ -181,13 +186,13 @@ Enables WebSocket support.
 
 This prepares the project for real-time server and client workflows.
 
-### Use this when
+#### When to use `--websocket`
 
 - building chat systems
 - creating live dashboards
 - sending notifications or push-style realtime updates
 
-### Example
+#### `--websocket` example
 
 ```bash package="npm"
 npx create-prisma-php-app my-app --websocket
@@ -199,13 +204,13 @@ Enables MCP support.
 
 This prepares the project for Model Context Protocol server and tool workflows.
 
-### Use this when
+#### When to use `--mcp`
 
 - integrating AI tooling
 - exposing tools through MCP
 - building model-connected workflows
 
-### Example
+#### `--mcp` example
 
 ```bash package="npm"
 npx create-prisma-php-app my-app --mcp
@@ -217,13 +222,13 @@ Enables Prisma ORM support.
 
 This prepares the project for database-backed development and ORM generation workflows.
 
-### Use this when
+#### When to use `--prisma`
 
 - your project needs a database
 - you want Prisma ORM available from the start
 - you are building CRUD apps, APIs, dashboards, or content systems
 
-### Example
+#### `--prisma` example
 
 ```bash package="npm"
 npx create-prisma-php-app my-app --prisma
@@ -237,7 +242,7 @@ Shows the starter kits available in the installed CLI version.
 
 Use this before choosing a starter if you want to inspect the currently supported templates.
 
-### Example
+#### `--list-starter-kits` example
 
 ```bash package="npm"
 npx create-prisma-php-app --list-starter-kits
@@ -251,7 +256,7 @@ Starter kits provide opinionated starting points so you do not have to assemble
 
 The exact built-in starter kit names depend on the installed CLI version, so `--list-starter-kits` is the safest way to confirm the current list.
 
-### Example
+#### `--starter-kit=<kit>` example
 
 ```bash package="npm"
 npx create-prisma-php-app my-app --starter-kit=basic
@@ -263,7 +268,7 @@ Uses a custom external starter kit source.
 
 This is intended for custom or team-managed boilerplates and is typically paired with `--starter-kit=custom`.
 
-### Example
+#### `--starter-kit-source=<url>` example
 
 ```bash package="npm"
 npx create-prisma-php-app my-app --starter-kit=custom --starter-kit-source=https://github.com/user/repo
@@ -309,7 +314,7 @@ Use this when the project already exists and you want to regenerate or refresh f
 
 If you are enabling or changing features on an existing project, update `prisma-php.json` first, then run `npx pp update project`.
 
-### Example
+#### `npx pp update project` example
 
 ```bash package="npm"
 npx pp update project
@@ -319,7 +324,7 @@ npx pp update project
 
 Refreshes the current project using the latest published version of `create-prisma-php-app`.
 
-### Example
+#### `npx pp update project @latest` example
 
 ```bash package="npm"
 npx pp update project @latest
@@ -329,13 +334,13 @@ npx pp update project @latest
 
 Refreshes the project using a tagged prerelease such as an alpha build.
 
-### Use this when
+#### When to use `npx pp update project @v5-alpha`
 
 - testing prerelease framework changes
 - validating upcoming CLI behavior
 - trying an experimental version on an existing project
 
-### Example
+#### `npx pp update project @v5-alpha` example
 
 ```bash package="npm"
 npx pp update project @v5-alpha
@@ -345,13 +350,13 @@ npx pp update project @v5-alpha
 
 Refreshes the project using a fixed package version.
 
-### Use this when
+#### When to use `npx pp update project @1.2.3`
 
 - you need reproducible updates
 - you want to stay on a known working version
 - you want strict version control over generator behavior
 
-### Example
+#### `npx pp update project @1.2.3` example
 
 ```bash package="npm"
 npx pp update project @1.2.3
@@ -363,13 +368,13 @@ Runs the update in non-interactive mode.
 
 This skips the confirmation prompt and proceeds directly.
 
-### Use this when
+#### When to use `npx pp update project -y`
 
 - running scripted updates
 - using CI or automation
 - updating from AI-driven workflows
 
-### Example
+#### `npx pp update project -y` example
 
 ```bash package="npm"
 npx pp update project -y
@@ -396,6 +401,135 @@ It is not a substitute for Prisma ORM schema migration commands.
 
 If your database schema changed, use the Prisma ORM workflow documented in `prisma-php-orm.md` and `upgrading.md`.
 
+## Prisma PHP Node Script Execution Guide
+
+This section documents the generated Node script surface in Prisma PHP apps.
+
+For normal Prisma PHP work, prefer the top-level entry points:
+
+- `npm run dev` during development
+- `npm run build` when you intentionally want a production-style asset build
+
+Prisma PHP wires feature-specific scripts such as Tailwind, TypeScript, WebSocket, and MCP into those top-level commands when the matching feature is enabled.
+
+That means AI agents should not default to telling users to run `npm run tailwind`, `npm run tailwind:build`, `npm run ts:watch`, or `npm run ts:build` after ordinary file changes. Those lower-level scripts are mainly useful when isolating one part of the toolchain, debugging, or running a feature-specific workflow on purpose.
+
+### Script table
+
+| Command | Type | What it does | When it exists | Use case |
+| --- | --- | --- | --- | --- |
+| `npm run projectName` | npm script | Runs `tsx settings/project-name.ts` so project name metadata stays aligned with the generated app setup. | Always added to generated `package.json`. | Internal setup step used before the main dev pipeline. |
+| `npm run browserSync` | npm script | Runs `tsx settings/bs-config.ts` to start BrowserSync with the generated project config. | Always added. | Local development server and live reload. |
+| `npm run browserSync:build` | npm script | Runs `tsx settings/build.ts` as the build-oriented BrowserSync step. | Always added. | Included in the normal build pipeline. |
+| `npm run dev` | npm script | Runs `npm-run-all projectName -p browserSync ...` and adds feature-specific watch processes when those features are enabled. | Always added, but the parallel subtasks depend on enabled features. | Main local development command. |
+| `npm run build` | npm script | Runs `npm-run-all ...` with build-oriented tasks such as `browserSync:build`, and optionally Tailwind and TypeScript build steps. | Always added, but included subtasks depend on enabled features. | Main build command for preparing project assets. |
+| `npm run tailwind` | npm script | Runs `postcss src/app/globals.css -o public/css/styles.css --watch`. | Only when `tailwindcss` is enabled. | Feature-specific CSS watch mode when you need to isolate styling work. |
+| `npm run tailwind:build` | npm script | Runs `postcss src/app/globals.css -o public/css/styles.css`. | Only when `tailwindcss` is enabled. | Feature-specific CSS build step, usually reached through `npm run build`. |
+| `npm run ts:watch` | npm script | Runs `vite build --watch`. | Only when `typescript` is enabled and the project is not backend-only. | Feature-specific frontend TypeScript watch mode. |
+| `npm run ts:build` | npm script | Runs `vite build`. | Only when `typescript` is enabled and the project is not backend-only. | Feature-specific frontend bundle step, usually reached through `npm run build`. |
+| `npm run websocket` | npm script | Runs `tsx settings/restart-websocket.ts`. | Only when `websocket` is enabled. | Start or restart the WebSocket runtime in projects that use realtime features. |
+| `npm run mcp` | npm script | Runs `tsx settings/restart-mcp.ts`. | Only when `mcp` is enabled. | Start or restart the MCP runtime in projects that expose MCP tools. |
+| `npm run create-swagger-docs` | npm script | Runs the Prisma PHP Swagger docs generation flow and can optionally receive model names. | Only when `swaggerDocs` is enabled. | Generate or refresh Swagger and OpenAPI output. |
+| `npx create-prisma-php-app <project-name>` | npx command | Creates a Prisma PHP project, installs dependencies, writes files, and saves the selected feature flags. | Available from the create CLI. | Scaffold a new project. |
+| `npx create-prisma-php-app --list-starter-kits` | npx command | Prints the starter kits supported by the installed CLI version. | Always available in the create CLI. | Inspect available templates before choosing one. |
+| `npx pp update project` | npx command | Reads `prisma-php.json` in the current app and refreshes the project using that saved configuration. | Available from the update CLI. | Refresh an existing project after saving feature changes or when updating framework-managed files. |
+| `npx pp update project @latest` | npx command | Updates the current project using the latest published generator version. | Available from the update CLI. | Move an existing project to the newest published generator behavior. |
+| `npx pp update project @v5-alpha` | npx command | Updates the current project using a tagged prerelease version such as an alpha build. | Available from the update CLI. | Test prerelease generator changes. |
+| `npx pp update project @1.2.3` | npx command | Updates the current project using a fixed package version. | Available from the update CLI. | Use a pinned generator version for reproducible updates. |
+| `npx pp update project -y` | npx command | Runs the update flow in non-interactive mode. | Available from the update CLI. | CI, scripts, or AI-driven update workflows. |
+
+## How `npm run dev` is composed
+
+`npm run dev` is generated around this base shape:
+
+- `npm-run-all projectName -p browserSync ...conditional-watchers`
+
+Possible parallel watchers added to `dev` are:
+
+- `tailwind`
+- `ts:watch`
+- `websocket`
+- `mcp`
+
+That means:
+
+- the base dev flow always includes `projectName` and `browserSync`
+- Tailwind projects also run `tailwind`
+- TypeScript frontend projects also run `ts:watch`
+- WebSocket projects also run `websocket`
+- MCP projects also run `mcp`
+
+### Example `dev` combinations
+
+| Project features | Resulting dev command shape |
+| --- | --- |
+| Minimal project | `npm-run-all projectName -p browserSync` |
+| Tailwind only | `npm-run-all projectName -p browserSync tailwind` |
+| Tailwind + TypeScript | `npm-run-all projectName -p browserSync tailwind ts:watch` |
+| Tailwind + TypeScript + WebSocket + MCP | `npm-run-all projectName -p browserSync tailwind ts:watch websocket mcp` |
+
+## How `npm run build` is composed
+
+`npm run build` is generated from:
+
+- base: `browserSync:build`
+- plus `tailwind:build` when Tailwind is enabled
+- plus `ts:build` when TypeScript is enabled and the project is not backend-only
+
+### Example `build` combinations
+
+| Project features | Resulting build command shape |
+| --- | --- |
+| Minimal project | `npm-run-all browserSync:build` |
+| Tailwind only | `npm-run-all tailwind:build browserSync:build` |
+| Tailwind + TypeScript | `npm-run-all ts:build tailwind:build browserSync:build` |
+| TypeScript only | `npm-run-all ts:build browserSync:build` |
+
+## Common execution examples
+
+### Development
+
+```bash package="npm"
+npm run dev
+npm run browserSync
+npm run tailwind
+npm run ts:watch
+npm run websocket
+npm run mcp
+```
+
+### Build
+
+```bash package="npm"
+npm run build
+npm run browserSync:build
+npm run tailwind:build
+npm run ts:build
+npm run create-swagger-docs
+```
+
+### Project scaffolding and update
+
+```bash package="npm"
+npx create-prisma-php-app my-app
+npx create-prisma-php-app my-app --tailwindcss --typescript --prisma
+npx create-prisma-php-app --list-starter-kits
+
+npx pp update project
+npx pp update project @latest
+npx pp update project @v5-alpha
+npx pp update project @1.2.3
+npx pp update project -y
+```
+
+## Execution notes
+
+- `npm run tailwind`, `npm run tailwind:build`, `npm run ts:watch`, `npm run ts:build`, `npm run websocket`, `npm run mcp`, and `npm run create-swagger-docs` are conditional scripts. They only exist when the matching feature was enabled for the project.
+- For ordinary Prisma PHP development, start with `npm run dev` instead of manually running each watcher one by one.
+- For ordinary build preparation, start with `npm run build` instead of manually running `tailwind:build` or `ts:build` unless you intentionally want to isolate those steps.
+- `npx pp update project` rebuilds the update command from the saved `prisma-php.json` configuration, so you do not need to retype every feature flag.
+- `npx pp update project` is a project refresh command, not an ORM migration shortcut.
+
 ## Recommended mental model
 
 ### Use create when

package/dist/docs/components.md

@@ -238,7 +238,7 @@ Typical shape:
 
 namespace Lib\Components;
 
-use Lib\PHPX\PHPX;
+use PP\PHPX\PHPX;
 
 class ClassName extends PHPX
 {

package/dist/docs/fetching-data.md

@@ -429,7 +429,7 @@ If you need explicit control over raw SSE event metadata, Prisma PHP also includ
 Core locations in Prisma PHP:
 
 ```txt
-vendor/tsnc/prisma-php/src/SSE.php
+vendor/tsnc/prisma-php/src/Streaming/SSE.php
 vendor/tsnc/prisma-php/src/Streaming/ServerSentEvent.php
 ```