prisma-php 0.0.12 → 0.0.13

package/.github/copilot-instructions.md

@@ -5,9 +5,19 @@
 - 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.
-- When updating Prisma PHP package/docs sources in this repo, keep `AGENTS.md`, `.github/copilot-instructions.md`, and `dist/docs` aligned so the published docs remain correct after install.
+- 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.

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

@@ -92,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
@@ -112,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
@@ -130,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
@@ -148,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
@@ -168,13 +168,13 @@ When this flag is enabled, Prisma PHP should keep frontend TypeScript in the roo
 
 Read `typescript.md` for the TypeScript-specific workflow.
 
-### Use this when
+#### 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
@@ -186,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
@@ -204,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
@@ -222,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
@@ -242,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
@@ -256,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
@@ -268,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
@@ -314,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
@@ -324,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
@@ -334,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
@@ -350,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
@@ -368,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
@@ -401,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
 ```
 

package/dist/docs/index.md

@@ -12,7 +12,7 @@ related:
 
 Use this page as the routing entry point for the local Prisma PHP docs. If a task involves choosing which Prisma PHP guide to read before generating framework-specific code, start here and then jump to the matching page in `node_modules/prisma-php/dist/docs`.
 
-Before generating framework-specific code, read `prisma-php.json` first, then the matching local docs page. For auth read `authentication.md`; for env read `env.md`; for uploads read `file-manager.md`; for email read `email.md`; for websocket read `websocket.md`; for MCP read `mcp.md`; for ORM read `prisma-php-orm.md`; for reactive UI read `pulsepoint.md`; for validation read `validator.md`; for data loading read `fetching-data.md`; and for route or layout structure read `layouts-and-pages.md`.
+Before generating framework-specific code, read `prisma-php.json` first, then the matching local docs page. For auth read `authentication.md`; for env read `env.md`; for runtime bootstrap and request protection read `bootstrap-runtime.md`; for uploads read `file-manager.md`; for email read `email.md`; for websocket read `websocket.md`; for MCP read `mcp.md`; for ORM read `prisma-php-orm.md`; for reactive UI read `pulsepoint.md`; for validation read `validator.md`; for data loading read `fetching-data.md`; and for route or layout structure read `layouts-and-pages.md`.
 
 Welcome to the Prisma PHP documentation!
 
@@ -36,8 +36,9 @@ Use this order:
 
 1. Read `./prisma-php.json` first.
 2. Read the relevant local docs in `node_modules/prisma-php/dist/docs`.
-3. Inspect local project files.
-4. Inspect `vendor/tsnc/prisma-php/src` only when framework internals are necessary.
+3. Read `bootstrap-runtime.md` when runtime init, cookies, request routing, or function-call protection matter.
+4. Inspect local project files.
+5. Inspect `vendor/tsnc/prisma-php/src` only when framework internals are necessary.
 
 ### Default interactive pattern
 
@@ -116,12 +117,13 @@ Do not confuse the route-file pattern with the `ImportComponent` partial pattern
 ### Read this doc when you need
 
 - **project setup or file placement** → `project-structure.md`
-- **CLI project creation, starter kits, create-prisma-php-app flags, or project update commands** → `commands.md`
+- **CLI project creation, starter kits, create-prisma-php-app flags, project update commands, or generated `package.json` scripts** → `commands.md`
 - **backend-only Prisma PHP usage, API-first projects, `backendOnly`, CORS, separate frontend clients, or choosing `route.php` as the default route file** → `backend-only.md`
 - **pages, layouts, route creation, nested routes, or PulsePoint-aware `index.php` and `layout.php` structure** → `layouts-and-pages.md`
 - **PHPX components, props, children, fragments, icons, buttons, accordions, or component composition** → `components.md`
 - **frontend TypeScript tooling, the `typescript` flag, the `ts/` directory, `ts/main.ts`, npm packages, or registered browser helpers used from template expressions and PulsePoint scripts** → `typescript.md`
 - **environment variables, `.env`, `PP\Env`, `Env::get(...)`, `Env::string(...)`, `Env::bool(...)`, `Env::int(...)`, or runtime configuration** → `env.md`
+- **bootstrap, request initialization, `FUNCTION_CALL_SECRET`, `prisma_php_csrf`, `pp_local_store_key`, route resolution, or runtime init order** → `bootstrap-runtime.md`
 - **file uploads, `multipart/form-data`, `$_FILES`, `PP\FileManager\UploadFile`, rename/delete flows, file replacement, allowed file types, upload size rules, or file manager pages** → `file-manager.md`
 - **AI integration, provider SDKs, chat UIs, streamed assistant responses, or deciding between page-local AI features, websocket, and MCP** → `get-started-ia.md`
 - **SMTP setup, `.env` mail variables, `PP\PHPMailer\Mailer`, HTML email, text email, recipients, reply-to, CC, BCC, or attachments** → `email.md`
@@ -149,6 +151,7 @@ Do not confuse the route-file pattern with the `ImportComponent` partial pattern
 - do not create, edit, or maintain `files-list.json`; Prisma PHP generates route listings automatically
 - when the project is API-first or backend-only, read `backend-only.md`, inspect `backendOnly` in `prisma-php.json`, and default to `route.php` for normal route behavior
 - when reading runtime configuration, `.env`, or feature flags, read `env.md` first and prefer `PP\Env` typed helpers over repeated manual parsing
+- when the task involves request bootstrap, cookie setup, route resolution, or function-call security, read `bootstrap-runtime.md` before reasoning from generic PHP request habits
 - when building interactive frontend behavior, prefer the documented PulsePoint pattern with browser-side reactive state and `pp.fetchFunction(...)` for server calls; treat this as the default unless the user explicitly asks for a PHP-only interaction pattern
 - when the task involves frontend TypeScript tooling or registered browser helpers, read `typescript.md`, keep reusable module code in `ts/`, and call the registered globals from PulsePoint component scripts instead of placing `import` or `export` inside inline route scripts
 - when building PulsePoint inside `index.php` or `layout.php`, read `layouts-and-pages.md` together with `pulsepoint.md`, use one parent route root, put `pp-component` on that root, and keep the `<script>` inside it as the last child
@@ -158,6 +161,7 @@ Do not confuse the route-file pattern with the `ImportComponent` partial pattern
 - when building backend validation logic, read `validator.md` first, then use the route-specific docs for the request entry point
 - when using `pp.fetchFunction(...)`, expose the PHP function explicitly with `#[Exposed]`
 - when changing feature flags, update `prisma-php.json` first, then follow the documented update workflow
+- when package scripts matter, read `commands.md`, prefer `npm run dev` for ordinary local development, prefer `npm run build` for intentional production-style asset builds, and do not default to lower-level Tailwind or TypeScript scripts after routine file changes
 - when the task involves OpenAPI or Swagger generation, read `swagger-docs.md`, inspect `swaggerDocs` in `prisma-php.json`, and keep the generated spec path and config file aligned with the Prisma PHP workflow
 - when building reusable PHPX components, read `components.md` first
 - when building file-upload flows, file listings, rename/delete actions, or a file manager screen, read `file-manager.md` first and keep the implementation aligned with Prisma PHP’s documented File Manager model
@@ -191,6 +195,8 @@ Use `typescript.md` as the local AI guide for:
 - installing npm packages for frontend utilities
 - using registered helpers from template expressions and PulsePoint scripts while keeping inline component scripts as plain JavaScript
 
+For ordinary local work in a TypeScript-enabled app, prefer `npm run dev` instead of defaulting to `npm run ts:watch` directly.
+
 ## Env
 
 Prisma PHP includes a documented environment helper centered on `PP\Env`, which reads already-loaded runtime values and exposes typed accessors for strings, booleans, and integers.
@@ -291,9 +297,9 @@ Use `authentication.md` as the local AI-awareness guide for:
 
 - `AuthConfig.php`
 - public-default vs private-default route strategy
-- `Auth::signIn(...)`
-- `Auth::signOut(...)`
-- `refreshUserSession(...)`
+- `Auth::getInstance()->signIn(...)`
+- `Auth::getInstance()->signOut(...)`
+- `Auth::getInstance()->refreshUserSession(...)`
 - route-level RBAC
 - function-level protection with `#[Exposed(allowedRoles: [...])]`
 - credential authentication

package/dist/docs/installation.md

@@ -35,3 +35,7 @@ npx create-prisma-php-app@latest my-app
 cd my-app
 npm run dev
 ```
+
+For ordinary Prisma PHP local development, `npm run dev` is the main entry point.
+
+Do not default to running lower-level generated scripts such as Tailwind or TypeScript watchers one by one unless you intentionally need to isolate part of the toolchain.

package/dist/docs/layouts-and-pages.md

@@ -160,21 +160,27 @@ For example, to create a root layout:
 <?php
 
 use PP\MainLayout;
+
+MainLayout::$title = !empty(MainLayout::$title) ? MainLayout::$title : 'Create Prisma PHP App';
+MainLayout::$description = !empty(MainLayout::$description) ? MainLayout::$description : 'Generated by create Prisma PHP App';
+
 ?>
 
-<!DOCTYPE html>
 <html lang="en">
+
 <head>
-    <meta charset="UTF-8">
-    <meta name="viewport" content="width=device-width, initial-scale=1.0">
-    <title><?= htmlspecialchars(MainLayout::$title ?: 'My Prisma PHP App') ?></title>
-    <meta name="description" content="<?= htmlspecialchars(MainLayout::$description ?: 'Default application description') ?>">
+    <!-- Dynamic Meta Tags -->
+    <link rel="icon" href="/favicon.ico" type="image/x-icon" sizes="16x16" />
+    <!-- Dynamic Header Scripts -->
+    <link href="/css/styles.css" rel="stylesheet" /> 
+    <script type="module" src="/js/main.js"></script>
 </head>
-<body>
-    <main>
-        <?= MainLayout::$children; ?>
-    </main>
+
+<body pp-spa="true" style="opacity:0;pointer-events:none;user-select:none;transition:opacity .18s ease-out;">
+    <?= MainLayout::$children; ?>
+    <!-- Dynamic Footer Scripts -->
 </body>
+
 </html>
 ```
 

package/dist/docs/mcp.md

@@ -330,6 +330,10 @@ php src/Lib/MCP/mcp-server.php
 
 The official docs also note that some Prisma PHP setups start MCP during `npm run dev`. AI should inspect local scripts before assuming that behavior in a specific project.
 
+That means AI should not default to telling users to run `npm run mcp` after ordinary application changes.
+
+Use the dedicated MCP runtime command only when you intentionally need to start or debug MCP separately from the normal development flow.
+
 If the defaults are unchanged, the endpoint is:
 
 ```txt

package/dist/docs/metadata-and-og-images.md

@@ -24,7 +24,7 @@ If a task involves page titles, descriptions, custom meta tags, favicon files, i
 Before generating Prisma PHP metadata code, use this order:
 
 1. Use `MainLayout::$title` and `MainLayout::$description` for document metadata.
-2. Use `MainLayout::addCustomMetaData(...)` for extra meta tags.
+2. Use `MainLayout::addCustomMetadata(...)` for extra meta tags.
 3. Keep visible headings separate from document metadata when the UI text needs to differ.
 4. Use the documented `favicon`, `icon`, and `apple-icon` file conventions instead of inventing generated metadata modules.
 5. Read `layouts-and-pages.md` when the task also changes route or layout structure.
@@ -40,11 +40,11 @@ Prisma PHP uses this to manage head scripts, footer scripts, and custom metadata
 ```php filename="src/app/products/index.php"
 <?php
 
-use Lib\MainLayout;
+use PP\MainLayout;
 
 MainLayout::$title = "My Awesome Page";
 MainLayout::$description = "This is a description of my awesome page";
-MainLayout::addCustomMetaData("author", "John Doe");
+MainLayout::addCustomMetadata("author", "John Doe");
 ?>
 ```
 
@@ -52,7 +52,7 @@ In this model:
 
 - `MainLayout::$title` sets the page title
 - `MainLayout::$description` sets the page description
-- `MainLayout::addCustomMetaData(...)` adds additional metadata such as `author` or other `<meta>` values
+- `MainLayout::addCustomMetadata(...)` adds additional metadata such as `author` or other `<meta>` values
 
 ## Heading text vs document metadata
 
@@ -63,7 +63,7 @@ This is a better pattern than relying on a local `$title` variable alone:
 ```php filename="src/app/dashboard/index.php"
 <?php
 
-use Lib\MainLayout;
+use PP\MainLayout;
 
 MainLayout::$title = "Dashboard";
 MainLayout::$description = "View account stats, recent activity, and important actions.";
@@ -85,8 +85,8 @@ The docs show metadata being generated from request parameters:
 ```php filename="src/app/product/index.php"
 <?php
 
-use Lib\MainLayout;
-use Lib\Request;
+use PP\MainLayout;
+use PP\Request;
 
 $productName = Request::$params->productName ?? '';
 $productDescription = Request::$params->productDescription ?? '';
@@ -107,7 +107,7 @@ That means this pattern is correct:
 ```php filename="src/app/about/index.php"
 <?php
 
-use Lib\MainLayout;
+use PP\MainLayout;
 
 MainLayout::$title = "About Us";
 MainLayout::$description = "Learn more about our company.";
@@ -126,22 +126,28 @@ Your root `layout.php` can read from `MainLayout` so page-level metadata set in
 ```php filename="src/app/layout.php"
 <?php
 
-use Lib\MainLayout;
+use PP\MainLayout;
+
+MainLayout::$title = !empty(MainLayout::$title) ? MainLayout::$title : 'Create Prisma PHP App';
+MainLayout::$description = !empty(MainLayout::$description) ? MainLayout::$description : 'Generated by create Prisma PHP App';
+
 ?>
 
-<!DOCTYPE html>
 <html lang="en">
+
 <head>
-    <meta charset="UTF-8">
-    <meta name="viewport" content="width=device-width, initial-scale=1.0">
-    <title><?= htmlspecialchars(MainLayout::$title ?: "My Prisma PHP App") ?></title>
-    <meta name="description" content="<?= htmlspecialchars(MainLayout::$description ?: "Default application description") ?>">
+    <!-- Dynamic Meta Tags -->
+    <link rel="icon" href="/favicon.ico" type="image/x-icon" sizes="16x16" />
+    <!-- Dynamic Header Scripts -->
+    <link href="/css/styles.css" rel="stylesheet" /> 
+    <script type="module" src="/js/main.js"></script>
 </head>
-<body>
-    <main>
-        <?= MainLayout::$children; ?>
-    </main>
+
+<body pp-spa="true" style="opacity:0;pointer-events:none;user-select:none;transition:opacity .18s ease-out;">
+    <?= MainLayout::$children; ?>
+    <!-- Dynamic Footer Scripts -->
 </body>
+
 </html>
 ```
 
@@ -149,17 +155,17 @@ This lets route files control SEO metadata while the root layout stays responsib
 
 ## Adding custom metadata
 
-You can attach additional custom metadata through `MainLayout::addCustomMetaData(...)`.
+You can attach additional custom metadata through `MainLayout::addCustomMetadata(...)`.
 
 ```php filename="src/app/blog/index.php"
 <?php
 
-use Lib\MainLayout;
+use PP\MainLayout;
 
 MainLayout::$title = "Blog";
 MainLayout::$description = "Latest articles and product updates.";
-MainLayout::addCustomMetaData("keywords", "blog, updates, articles");
-MainLayout::addCustomMetaData("author", "Prisma PHP Team");
+MainLayout::addCustomMetadata("keywords", "blog, updates, articles");
+MainLayout::addCustomMetadata("author", "Prisma PHP Team");
 ?>
 ```
 
@@ -184,7 +190,7 @@ Example:
 ```php filename="src/app/index.php"
 <?php
 
-use Lib\MainLayout;
+use PP\MainLayout;
 
 MainLayout::addHeadScript('<script src="head-script.js"></script>');
 MainLayout::addFooterScript('<script src="footer-script.js"></script>');
@@ -195,9 +201,11 @@ This is not metadata in the strict SEO sense, but it is part of the same page-he
 
 ## Favicon, icon, and apple-icon
 
-Prisma PHP also documents file conventions for application icons.
+For the current generated Prisma PHP scaffold, the verified built-in icon pattern is the standard favicon link in the root layout.
+
+If you use additional icon assets such as `icon` or `apple-icon`, treat them as application assets and wire the matching `<link>` tags explicitly unless your project adds a higher-level convention.
 
-The docs say that `favicon`, `icon`, and `apple-icon` files let you define icons that appear in places such as:
+Those assets can still be used for places such as:
 
 - browser tabs
 - phone home screens
@@ -213,40 +221,40 @@ The provided Prisma PHP icon docs mention image-file based usage such as:
 
 ### Where to place them
 
-The docs say to place a `favicon`, `icon`, or `apple-icon` file within your `/app` directory, and specifically state that the favicon image must be located at the **top level** of `/app`.
+In generated Prisma PHP projects, place `favicon.ico` in the public web root. In the default scaffold that file lives at `public/favicon.ico` and is served at `/favicon.ico`.
 
 ## `favicon.ico`
 
-For the favicon, the docs say to add a `favicon.ico` image file to the root `/app` route segment. They also note that the favicon link tag is already included in the `<head>` of `layout.php`, so the normal step is simply to replace the existing `favicon.ico` file with your own.
+For the favicon, the generated layout already includes a standard link tag, so the normal step is simply to replace the existing `public/favicon.ico` file with your own.
 
 The documented link tag is:
 
 ```php
-<link rel="icon" href="<?= Request::baseUrl?>/favicon.ico" type="image/x-icon" sizes="16x16">
+<link rel="icon" href="/favicon.ico" type="image/x-icon" sizes="16x16" />
 ```
 
-This means Prisma PHP already expects the favicon in the standard project location and wires it into the layout automatically.
+This means Prisma PHP already expects the favicon in the public web root and wires it into the layout automatically.
 
-## Automatic head integration
+## Head integration
 
-The icon docs say Prisma PHP evaluates these icon files and **automatically adds the appropriate tags to your app’s `<head>` element**.
+In the current scaffold, the verified automatic head integration is the built-in favicon link already present in the root layout.
 
-That is the Prisma PHP equivalent of file-convention-based icon metadata.
+This metadata page does not claim automatic `icon` or `apple-icon` tag generation because that behavior is not demonstrated by the current local scaffold or runtime sources.
 
 ## Metadata and icons in a full page example
 
 ```php filename="src/app/products/[slug]/index.php"
 <?php
 
-use Lib\MainLayout;
+use PP\MainLayout;
 use PP\Request;
 
 $slug = Request::$dynamicParams['slug'] ?? 'product';
 
 MainLayout::$title = "Product: " . ucfirst((string) $slug);
 MainLayout::$description = "View product details for " . ucfirst((string) $slug) . ".";
-MainLayout::addCustomMetaData("author", "Prisma PHP");
-MainLayout::addCustomMetaData("keywords", "product, ecommerce, details");
+MainLayout::addCustomMetadata("author", "Prisma PHP");
+MainLayout::addCustomMetadata("keywords", "product, ecommerce, details");
 ?>
 
 <section>
@@ -263,10 +271,10 @@ If you are coming from Next.js, the closest mapping is:
 
 | Next.js idea                      | Prisma PHP equivalent                                                                  |
 | --------------------------------- | -------------------------------------------------------------------------------------- |
-| `export const metadata = { ... }` | `MainLayout::$title`, `MainLayout::$description`, `MainLayout::addCustomMetaData(...)` |
+| `export const metadata = { ... }` | `MainLayout::$title`, `MainLayout::$description`, `MainLayout::addCustomMetadata(...)` |
 | `generateMetadata()`              | dynamic metadata set at runtime in the PHP route file                                  |
-| `favicon.ico` in app conventions  | `favicon.ico` in the app root with built-in layout support                             |
-| file-based icon conventions       | Prisma PHP `favicon`, `icon`, `apple-icon` file conventions                            |
+| `favicon.ico` in app conventions  | `public/favicon.ico` served at `/favicon.ico` with built-in layout support             |
+| file-based icon conventions       | application-managed icon assets and explicit `<link>` tags when needed                 |
 | generated OG image files          | not documented on the provided Prisma PHP metadata pages                               |
 
 The main difference is that Prisma PHP’s documented system is **layout-class driven** for metadata and **file-convention driven** for icons, rather than based on exported metadata objects or generated route modules.
@@ -276,7 +284,7 @@ The main difference is that Prisma PHP’s documented system is **layout-class d
 The Next.js page title includes OG images, but the provided Prisma PHP docs you linked focus on:
 
 - dynamic page metadata through `MainLayout`
-- icon file conventions such as `favicon`, `icon`, and `apple-icon`
+- favicon support in the generated layout and optional additional icon assets when the app explicitly links them
 
 Because those pages do not document a dedicated Prisma PHP Open Graph image generation system, this page does **not** invent one. If your framework later adds a specific OG image convention, that would belong here.
 
@@ -284,9 +292,9 @@ Because those pages do not document a dedicated Prisma PHP Open Graph image gene
 
 - Prisma PHP uses `MainLayout` for dynamic metadata management.
 - `MainLayout::$title` and `MainLayout::$description` are the main documented page metadata properties.
-- `MainLayout::addCustomMetaData(...)` adds custom metadata such as `author`.
+- `MainLayout::addCustomMetadata(...)` adds custom metadata such as `author`.
 - Metadata should be set before any HTML output.
 - `MainLayout::addHeadScript(...)` and `MainLayout::addFooterScript(...)` can inject scripts into the page shell.
-- Prisma PHP supports `favicon`, `icon`, and `apple-icon` file conventions.
-- `favicon.ico` belongs at the top level of the app directory.
-- Prisma PHP automatically adds the appropriate icon tags to the document head.
+- the generated Prisma PHP scaffold includes built-in favicon support through the root layout.
+- `favicon.ico` belongs in the public web root and is served as `/favicon.ico` in the default scaffold.
+- additional icon assets should be linked explicitly unless your app adds its own higher-level icon convention.

package/dist/docs/project-structure.md

@@ -18,6 +18,8 @@ If a task involves file placement, feature flags, route creation, or overall Pri
 
 For AI-assisted work, treat `node_modules/prisma-php/dist/docs` as the installed Prisma PHP docs location for the active project version, and keep `AGENTS.md` in the project root aligned with that docs set.
 
+For installed consumer apps, treat root `AGENTS.md` as the documented workspace instruction file. If the Prisma PHP package source repo also contains `.github/copilot-instructions.md`, treat that as package-maintainer guidance rather than a second consumer-app instruction file.
+
 ## AI rule: read the structure docs first
 
 Before generating Prisma PHP files or folders, use this order:
@@ -25,9 +27,10 @@ Before generating Prisma PHP files or folders, use this order:
 1. Read `prisma-php.json`.
 2. Read the matching installed doc in `node_modules/prisma-php/dist/docs`.
 3. Read `AGENTS.md` for project-specific Prisma PHP rules.
-4. Decide whether the task belongs in `src/app`, `src/Lib`, `prisma`, `public`, `settings`, or the installed docs path.
-5. Create routes from the route tree instead of editing `files-list.json`.
-6. Use `layouts-and-pages.md`, `route-handlers.md`, or `components.md` once the file location is known.
+4. When runtime bootstrap, request initialization, cookies, or function-call protection matter, read `bootstrap-runtime.md`.
+5. Decide whether the task belongs in `src/app`, `src/Lib`, `prisma`, `public`, `settings`, or the installed docs path.
+6. Create routes from the route tree instead of editing `files-list.json`.
+7. Use `layouts-and-pages.md`, `route-handlers.md`, or `components.md` once the file location is known.
 
 ## Folder and file conventions
 
@@ -61,7 +64,7 @@ These files are typically used to configure the app, manage dependencies, and de
 | File                   | Purpose                                                        |
 | ---------------------- | -------------------------------------------------------------- |
 | `composer.json`        | PHP dependencies and autoloading                               |
-| `package.json`         | Frontend tooling and development scripts when used             |
+| `package.json`         | Frontend tooling and framework-managed scripts when used       |
 | `.env`                 | Environment variables                                          |
 | `AGENTS.md`            | Project-root AI guidance aligned with the installed docs set   |
 | `prisma/schema.prisma` | Main Prisma schema file                                        |
@@ -90,6 +93,15 @@ Typical values include:
 
 If an AI agent is working on the project, it should inspect `prisma-php.json` before deciding whether Tailwind CSS, TypeScript, Prisma ORM, Swagger docs, MCP, or websocket-related code should be generated.
 
+When package-script behavior matters, inspect `package.json` and read `commands.md` before suggesting how local tooling should be started.
+
+For normal project work, Prisma PHP usually expects:
+
+- `npm run dev` as the top-level local development entry point
+- `npm run build` as the top-level production-style asset build entry point
+
+Do not default to lower-level scripts such as Tailwind, TypeScript, WebSocket, or MCP commands after routine code changes unless you intentionally need to isolate that part of the workflow.
+
 For backend-only API projects, read `backend-only.md`.
 
 For Swagger and OpenAPI generation, read `swagger-docs.md`.
@@ -120,6 +132,8 @@ Only prefer a more PHP-only interaction pattern when the user explicitly asks fo
 
 Some files in a Prisma PHP project are framework-managed and should not be manually maintained as part of normal route work.
 
+That same idea applies to generated package scripts in `package.json`: they are part of the framework-managed project workflow, so AI should not treat every lower-level script as the default thing the user needs to run after each change.
+
 ### `files-list.json`
 
 Prisma PHP automatically generates the route list in `files-list.json`.

package/dist/docs/route-handlers.md

@@ -151,7 +151,7 @@ In Prisma PHP, a common pattern is to guard the HTTP method at the top of the fi
 <?php
 
 use PP\Request;
-use PP\Header\Boom;
+use PP\Headers\Boom;
 use Lib\Prisma\Classes\Prisma;
 
 if (!Request::$isGet) {
@@ -235,7 +235,7 @@ You can also use `route.php` for form submissions or API-style POST endpoints.
 use PP\Request;
 use PP\Rule;
 use PP\Validator;
-use PP\Header\Boom;
+use PP\Headers\Boom;
 
 if (!Request::$isPost) {
     Boom::methodNotAllowed()->toResponse();

package/dist/docs/swagger-docs.md

@@ -34,10 +34,14 @@ Before enabling or regenerating Swagger docs, use this order:
 
 1. Inspect `prisma-php.json` for `swaggerDocs` and `backendOnly`.
 2. Read `backend-only.md`, `route-handlers.md`, and `prisma-php-orm.md` as needed for the surrounding API workflow.
-3. Use `npm run create-swagger-docs` for the documented generation flow.
+3. Use `npm run create-swagger-docs` for the documented on-demand generation flow.
 4. Inspect `settings/prisma-schema-config.json` before changing output paths or generation modes.
 5. Do not treat Swagger generation as a substitute for ORM migrations or route implementation.
 
+Unlike generated Tailwind or TypeScript build/watch scripts, Swagger generation is not the normal framework-managed step that runs as part of everyday `npm run dev` or `npm run build` work.
+
+AI agents should treat `npm run create-swagger-docs` as an explicit documentation or contract-generation action and run it only when Swagger output actually needs to be created or refreshed.
+
 ## When Swagger docs are worth enabling
 
 Enable Swagger docs when you need a stable machine-readable contract for the API.
@@ -80,6 +84,10 @@ That JSON file is the handoff point for tools such as:
 
 Prisma PHP's Swagger workflow supports generating documentation for models from `schema.prisma`.
 
+Use this command intentionally when your OpenAPI output needs to be updated.
+
+Do not confuse it with framework-managed development scripts such as `npm run dev` or asset build orchestration through `npm run build`.
+
 ```bash package="npm"
 npm run create-swagger-docs
 npm run create-swagger-docs Order
@@ -135,7 +143,7 @@ For API-oriented Prisma PHP work, a practical Swagger workflow is:
 
 1. update `schema.prisma`
 2. run the normal ORM workflow when the schema changed
-3. regenerate Swagger docs
+3. regenerate Swagger docs only when the contract output needs to be refreshed
 4. inspect `src/app/swagger-docs/apis/pphp-swagger.json`
 5. regenerate external clients if the contract changed
 

package/dist/docs/typescript.md

@@ -75,6 +75,13 @@ npx pp update project -y
 
 For broader project refresh guidance, read `upgrading.md`.
 
+After TypeScript scaffolding exists, ordinary local work should still start from the framework-managed entry points:
+
+- `npm run dev` for normal development
+- `npm run build` when you intentionally want a production-style asset build
+
+Do not default to `npm run ts:watch` or `npm run ts:build` after routine TypeScript edits unless you intentionally need to isolate the frontend bundle step.
+
 ## The `ts/` directory
 
 For organization and reuse, keep frontend TypeScript logic in the root `ts/` directory.

package/dist/docs/upgrading.md

@@ -47,6 +47,17 @@ npx pp update project -y
 
 This ensures the update process applies the correct files, dependencies, and project structure for the features you selected.
 
+For feature flags such as `tailwindcss`, `typescript`, `websocket`, and `mcp`, the updater's job is to refresh the generated files and scripts that the framework expects.
+
+After that, AI agents should not default to telling users to manually run each feature-specific package script one by one.
+
+For ordinary local verification after an update, prefer:
+
+- `npm run dev` for the normal development workflow
+- `npm run build` when you intentionally want a production-style asset build
+
+Use lower-level scripts such as Tailwind, TypeScript, WebSocket, or MCP commands only when isolating a specific part of the toolchain, debugging, or running a feature-specific workflow on purpose.
+
 If the feature you are enabling is API-focused, read `backend-only.md` for `backendOnly` usage and `swagger-docs.md` for `swaggerDocs` generation workflow details.
 
 ## Typical upgrade flow
@@ -155,7 +166,7 @@ After updating your project, verify the following:
 
 - Your enabled features in `prisma-php.json` match the current project requirements.
 - Dependencies installed correctly.
-- Local development still runs as expected.
+- Local development still runs as expected, normally through `npm run dev` rather than individual watcher scripts.
 - Any custom files listed in `excludeFiles` were preserved.
 - Database and generated ORM classes are in sync if schema changes were included.
 

package/dist/docs/websocket.md

@@ -84,6 +84,10 @@ The broader Prisma PHP project structure docs also show a development helper tha
 
 - `settings/restart-websocket.ts`
 
+Some Prisma PHP setups also wire websocket restart behavior into `npm run dev`.
+
+AI should inspect the current `package.json` before telling users to run `npm run websocket` manually, and should prefer the normal development flow unless websocket startup needs to be isolated or debugged on purpose.
+
 Important casing rule:
 
 The official page may show lowercase path examples such as `src/lib/websocket`, but Prisma PHP project structure docs use `src/Lib`, and this repo's guidance expects application libraries under `src/Lib`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "prisma-php",
-  "version": "0.0.12",
+  "version": "0.0.13",
   "description": "Prisma PHP tooling",
   "main": "index.js",
   "scripts": {