create-prisma-php-app 5.0.0-alpha.8 → 5.0.0

package/dist/AGENTS.md

@@ -2,89 +2,116 @@
 
 # Prisma PHP AI Agent Rules
 
-Before generating, editing, or reviewing Prisma PHP code, read the installed Prisma PHP docs for the current project version, read the project manifest, and only inspect framework internals when the docs do not answer the task.
+This AGENTS.md belongs in the root of a Prisma PHP application.
 
-Do not guess framework behavior from Laravel, Next.js, React, Vue, Livewire, Alpine, or generic PHP habits. The installed Prisma PHP docs and the local project configuration are the source of truth.
+Treat `./node_modules/prisma-php/dist/docs/index.md` as the entry point for Prisma PHP guidance, then read the matching document in `./node_modules/prisma-php/dist/docs` before generating, editing, reviewing, or documenting framework-specific behavior.
 
-## Source of truth priority
+Treat the installed docs as framework knowledge. They explain what Prisma PHP can do and how to do it. Do not treat the presence of a page in `./node_modules/prisma-php/dist/docs` as proof that the current app has that feature enabled.
 
-Use this order of truth when working in a Prisma PHP project:
+Do not guess framework behavior from Laravel, Next.js, React, Vue, Livewire, Alpine, Symfony, Socket.IO, or generic PHP habits. Prisma PHP's installed docs in `./node_modules/prisma-php/dist/docs` and the current project files are the source of truth.
 
-1. The user’s explicit request
+If `.github/instructions/**/*.instructions.md` exists, treat those files as workspace-local task instructions. Inspect `.github/instructions/` before deciding how to implement the task, then read any instruction files whose name, described scope, target files, or library focus matches the current work, such as PHPXUI or `ppicons`.
+
+## Documentation source of truth
+
+For Prisma PHP projects, use this order first:
+
+1. the user's explicit request
 2. `./prisma-php.json`
-3. Installed Prisma PHP docs in `node_modules/prisma-php/dist/docs`
-4. Project-local conventions and existing project files
-5. Prisma PHP core internals in `vendor/tsnc/prisma-php/src`
-6. General framework knowledge
+3. the relevant `.github/instructions/**/*.instructions.md` files for the current task, library, or target files
+4. the relevant installed document in `./node_modules/prisma-php/dist/docs`
+5. `./AGENTS.md`
+6. project-local conventions and existing app files
+7. Prisma PHP core internals in `vendor/tsnc/prisma-php/src` only when the docs still leave a gap
+8. general framework knowledge as the last fallback
 
-If a documented Prisma PHP rule conflicts with a habit from another framework, follow Prisma PHP.
+Important rules:
+
+- use `./prisma-php.json` as the single source of truth for current-project feature flags and framework-managed scaffolds
+- if `.github/instructions/**/*.instructions.md` exists, inspect `.github/instructions/` and read the files that match the current task, named library, or target files before generating code
+- treat `.github/instructions/**/*.instructions.md` as workspace-local guidance for third-party libraries, design systems, icon packs, and other implementation-specific rules
+- treat `./node_modules/prisma-php/dist/docs` as the single documentation source of truth for the installed Prisma PHP version
+- treat the docs inventory as a framework reference set for AI routing, not as a statement that every optional Prisma PHP feature is enabled in the current app
+- expect `./AGENTS.md` at the project root
+- when the installed docs and a habit from another framework conflict, follow Prisma PHP
+- when a workspace instruction file and the general Prisma PHP docs both apply, follow both; keep `./prisma-php.json` as the source of truth for feature enablement and prefer the most specific matching instruction for library- or file-scoped implementation details
+- in consumer apps, use `./node_modules/prisma-php/dist/docs` as the installed docs location; do not assume a root-level `./dist/docs` directory exists
+- when updating Prisma PHP package/docs sources in the Prisma PHP package source repo, keep the source-repo `AGENTS.md` and source-repo `dist/docs` aligned; if that repo also maintains `.github/copilot-instructions.md` or `.github/instructions/**/*.instructions.md`, keep those source-repo files aligned there too
+
+## Runtime lookup for AI
+
+Use this map only after `prisma-php.json`, matching workspace instructions, installed docs, and current project files do not answer the task.
+
+| Need to verify | Runtime/source file |
+| --- | --- |
+| route root scoping, HTML fragment parsing, component tag compilation, prop casing | `vendor/tsnc/prisma-php/src/PHPX/TemplateCompiler.php` |
+| PHPX class composition, `getMergeClasses(...)`, and frontend `twMerge(...)` expression generation | `vendor/tsnc/prisma-php/src/PHPX/PHPX.php`, `vendor/tsnc/prisma-php/src/PHPX/TwMerge.php` |
+| imported PHP partial execution, one-root enforcement, prop serialization, imported `#[Exposed]` functions | `vendor/tsnc/prisma-php/src/ImportComponent.php` |
+| metadata, custom head tags, dynamic head/footer scripts | `vendor/tsnc/prisma-php/src/MainLayout.php` |
+| route and component maps | `vendor/tsnc/prisma-php/src/PrismaPHPSettings.php`, `settings/files-list.json`, `settings/component-map.json` |
+| request data, dynamic params, redirects, RPC/navigation wire detection (`$isRpc`, `$isNavigation`, `$isWire`) | `vendor/tsnc/prisma-php/src/Request.php` |
+| CSRF cookie family (`pp_csrf`, `pp_csrf_<port>`), token issuing and validation | `vendor/tsnc/prisma-php/src/Security/Csrf.php` |
+| exposed functions | `vendor/tsnc/prisma-php/src/Attributes/Exposed.php`, `vendor/tsnc/prisma-php/src/Attributes/ExposedRegistry.php` |
+| validation | `vendor/tsnc/prisma-php/src/Validator.php`, `vendor/tsnc/prisma-php/src/Rule.php` |
+| env values | `vendor/tsnc/prisma-php/src/Env.php` |
+| uploads, email, streaming | `vendor/tsnc/prisma-php/src/FileManager/UploadFile.php`, `vendor/tsnc/prisma-php/src/PHPMailer/Mailer.php`, `vendor/tsnc/prisma-php/src/Streaming/SSE.php` |
 
 ## Installed docs location
 
-The installed Prisma PHP documentation for the active project lives in:
+In Prisma PHP applications, the installed docs live in:
 
 ```txt
 node_modules/prisma-php/dist/docs
 ```
 
-AI agents must treat this directory as the primary documentation source for Prisma PHP behavior, routing, file conventions, features, helpers, and usage patterns for the installed version.
-
-Before writing framework-specific code, inspect the relevant documentation files in this directory.
-
-## Read `prisma-php.json` first
-
-Before generating code or making framework decisions, read:
+The current docs entry point for the installed version is:
 
 ```txt
-./prisma-php.json
+node_modules/prisma-php/dist/docs/index.md
 ```
 
-Treat it as the capability manifest for the current app.
-
-Use it to verify whether the project has features such as:
+The project root should also include:
 
-- `tailwindcss`
-- `backendOnly`
-- `swaggerDocs`
-- `websocket`
-- `mcp`
-- `prisma`
-- `typescript`
+```txt
+AGENTS.md
+```
 
-Also use it to confirm environment-specific project details such as:
+When present, task-scoped workspace instructions live in:
 
-- project root path
-- PHP executable path
-- BrowserSync target and path rewrite rules
-- component scan directories
-- excluded files
+```txt
+.github/instructions
+```
 
-Do not assume a feature is enabled unless it is present and enabled in `prisma-php.json`.
+## Required doc-routing map
 
-## Framework-managed generated files
+Before generating code, examples, instructions, or reviews, choose the documentation file based on the task.
 
-Prisma PHP automatically generates and maintains certain framework files.
+Use the docs router to learn how Prisma PHP implements a task. Use `./prisma-php.json` to decide whether the current app enables the relevant optional feature. When `.github/instructions/` exists, inspect that directory first and read any `*.instructions.md` files that match the task before routing into the Prisma PHP docs.
 
-### `files-list.json`
+### Read workspace instruction files first for these tasks
 
-Do **not** create, edit, reorder, or manually maintain `files-list.json`.
+- **Third-party UI, icon, component, or design-system work such as PHPXUI, `ppicons`, or similar workspace-specific integrations**  
+  Read the matching `.github/instructions/**/*.instructions.md` file first
 
-Treat `files-list.json` as a **framework-generated file** for route discovery and internal bookkeeping. When creating, renaming, or removing routes, make the change in the actual route folders and route files under `src/app` and let Prisma PHP regenerate `files-list.json` automatically.
+- **Tasks that target files, folders, or conventions covered by a workspace instruction file**  
+  Read the most specific matching `.github/instructions/**/*.instructions.md` file first
 
-If a route task appears to require editing `files-list.json`, that is almost certainly the wrong approach. The correct workflow is:
+- **Library-specific refactors, reviews, or implementations where the workspace provides a dedicated instruction file**  
+  Read that instruction file first, then read the matching Prisma PHP docs page for framework behavior
 
-1. create or update the route folder/file in `src/app`
-2. do **not** touch `files-list.json`
-3. let Prisma PHP regenerate framework-managed route metadata
+### Read these docs first for these tasks
 
-## Required doc-routing map
+- **Framework orientation, repo-wide guidance, or the high-level AI quick start**  
+  Read `index.md`
 
-Before generating code, choose the documentation file based on the task.
+- **Project setup, folder placement, route file choice, feature placement, or overall file conventions**  
+  Read `project-structure.md`
 
-### Read these docs first for these tasks
+- **CLI project creation, starter kits, feature flags, or `npx pp update project` usage**  
+  Read `commands.md`
 
-- **Project setup, folder placement, route file choice, or overall file conventions**  
-  Read `project-structure.md`
+- **Backend-only Prisma PHP usage, API-first projects, `backendOnly`, separate frontend consumers, or CORS setup for API routes**  
+  Read `backend-only.md`
 
 - **Creating a page, layout, nested route, dynamic route, or normal UI route**  
   Read `layouts-and-pages.md`
@@ -92,15 +119,45 @@ Before generating code, choose the documentation file based on the task.
 - **Creating, editing, composing, or reviewing PHPX components, props, children, fragments, icons, buttons, accordions, or component file placement**  
   Read `components.md`
 
-- **File uploads, `multipart/form-data`, `$_FILES`, `PP\FileManager\UploadFile`, rename flows, delete flows, allowed file types, upload size rules, or file manager UI behavior**  
-  Read `file-manager.md`, then verify the official File Manager docs at `get-started-file`
+- **Tailwind utility class composition, `getMergeClasses(...)`, `PP\PHPX\TwMerge`, or frontend `twMerge(...)` usage**  
+  Confirm `tailwindcss` in `prisma-php.json`, then read `components.md` for PHPX emission, `typescript.md` for app-level helper registration, and `layouts-and-pages.md` for route examples
 
-- **Authentication strategy, `AuthConfig.php`, route privacy model, sign-in, sign-out, JWT session lifecycle, `refreshUserSession`, RBAC, credentials auth, OAuth, social login, or auth state manager usage**  
-  Read `authentication.md`, then verify the matching official docs in this order: `auth-get-started`, `credentials`, and `state-manager-auth`
+- **TypeScript frontend tooling, the `typescript` feature flag, the root `ts/` directory, `ts/main.ts`, npm packages, or registered browser helpers used from template expressions and PulsePoint scripts**  
+  Read `typescript.md`, then use `pulsepoint.md`, `layouts-and-pages.md`, or `components.md` for the affected component boundary
 
-- **Loading data, calling backend logic from the frontend, `pp.fetchFunction(...)`, `#[Exposed]`, or interactive backend validation**  
+- **Loading data, calling backend logic from the frontend, `pp.rpc(...)`, `#[Exposed]`, route-local mutations, streaming responses, or interactive backend validation**  
   Read `fetching-data.md`
 
+- **AI integration, provider SDKs, chat UIs, streamed assistant output, or deciding between page-local assistant UI, websocket, and MCP tools**  
+  Read `get-started-ia.md`, then use `fetching-data.md`, `validator.md`, `websocket.md`, or `mcp.md` as needed
+
+- **PulsePoint runtime behavior such as `pp.state`, `pp.effect`, `pp-for`, `pp-spread`, `pp-style`, `pp-ref`, context, portals, controlled form values, or keyed diffing**
+  Read `pulsepoint.md`
+
+- **Validation, sanitization, `PP\Validator`, `PP\Rule`, field validation, form validation, live validation, or request validation rules**  
+  Read `validator.md`, then apply the relevant local guidance from `fetching-data.md`, `error-handling.md`, and `route-handlers.md`
+
+- **Environment variables, `.env`, `PP\Env`, `Env::get`, `Env::string`, `Env::bool`, `Env::int`, feature flags, host and port config, or runtime bootstrap settings**  
+  Read `env.md`, then verify the official env docs at `env` and `env-file`
+
+- **Bootstrap flow, request initialization, `FUNCTION_CALL_SECRET`, `pp_csrf`, route resolution, or runtime init order**  
+  Read `bootstrap-runtime.md`, then use `env.md`, `fetching-data.md`, or `error-handling.md` as needed
+
+- **File uploads, `multipart/form-data`, `$_FILES`, `PP\FileManager\UploadFile`, rename flows, replace flows, delete flows, allowed file types, upload size rules, or file manager UI behavior**  
+  Read `file-manager.md`, then verify the official File Manager docs and, when internals matter, the core upload file at `vendor/tsnc/prisma-php/src/FileManager/UploadFile.php`
+
+- **SMTP setup, `.env` mail variables, `PP\PHPMailer\Mailer`, HTML bodies, plain-text bodies, recipients, reply-to, CC, BCC, or attachments**  
+  Read `email.md`, then verify the official email docs at `email-get-started`
+
+- **Named sockets, `pp.socket(...)`, `SocketRegistry`, `Socket`, `SocketPool`, the Ratchet socket server, or realtime route behavior**  
+  Read `websocket.md`, then verify the official websocket docs in this order: `websocket-get-started`, `websocket-chat-app`
+
+- **MCP support, `#[McpTool]`, `#[Schema]`, `PhpMcp\Server\Server`, `StreamableHttpServerTransport`, AI tool endpoints, or `src/Lib/MCP/mcp-server.php`**  
+  Read `mcp.md`, then verify the official MCP docs in this order: `prisma-php-ai-mcp`, `ai-tools`
+
+- **Authentication strategy, `AuthConfig.php`, route privacy model, sign-in, sign-out, JWT session lifecycle, `refreshUserSession`, RBAC, credentials auth, OAuth, social login, or auth state manager usage**  
+  Read `authentication.md`, then verify the matching official docs in this order: `auth-get-started`, `credentials`, `state-manager-auth`
+
 - **Cache behavior, route caching, invalidation, or `CacheHandler`**  
   Read `caching.md`
 
@@ -110,17 +167,17 @@ Before generating code, choose the documentation file based on the task.
 - **Expected errors, uncaught exceptions, `error.php`, `not-found.php`, `ErrorHandler`, or validation failures as expected errors**  
   Read `error-handling.md`
 
-- **Metadata, title, description, head scripts, favicon, icon, or `MainLayout` metadata behavior**  
+- **Metadata, title, description, custom head tags, favicon, icon, apple icon, or `MainLayout` metadata behavior**  
   Read `metadata-and-og-images.md`
 
-- **API-style routes, JSON responses, handlers, form-processing endpoints, `route.php`, or request validation in handlers**  
+- **API-style routes, JSON responses, handlers, webhooks, form-processing endpoints, `route.php`, or request validation in handlers**  
   Read `route-handlers.md`
 
-- **PulsePoint runtime behavior such as `pp.state`, `pp.effect`, `pp.ref`, `pp-for`, `pp-spread`, or `pp-ref`**  
-  Read `pulsepoint.md`
+- **Swagger or OpenAPI generation, `swaggerDocs`, generated per-model swagger docs, `create-swagger-docs`, or `settings/prisma-schema-config.json`**  
+  Read `swagger-docs.md`
 
-- **Sanitization, `PP\Validator`, `PP\Rule`, field validation, form validation, live validation, or backend validation rules**  
-  Read the official Validator docs at `https://prismaphp.tsnc.tech/docs/php-validator`, then apply the relevant local guidance from `fetching-data.md`, `error-handling.md`, and `route-handlers.md`
+- **Writing or running app tests, PHPUnit, the root `tests/` directory, `npm run test`, or verifying a change with the test suite**  
+  Read `testing.md`, then the project's `tests/README.md`
 
 - **Upgrading Prisma PHP, enabling features, syncing framework-managed project files, or running project updates**  
   Read `upgrading.md`
@@ -128,20 +185,151 @@ Before generating code, choose the documentation file based on the task.
 - **First-time project installation or app creation flow**  
   Read `installation.md`
 
-- **General doc entry point and framework orientation**  
-  Read `index.md`
+## Framework docs inventory in this repo
+
+The current Prisma PHP docs shipped here include:
+
+- `authentication.md`
+- `backend-only.md`
+- `bootstrap-runtime.md`
+- `caching.md`
+- `commands.md`
+- `components.md`
+- `email.md`
+- `env.md`
+- `error-handling.md`
+- `fetching-data.md`
+- `file-manager.md`
+- `get-started-ia.md`
+- `index.md`
+- `installation.md`
+- `layouts-and-pages.md`
+- `mcp.md`
+- `metadata-and-og-images.md`
+- `prisma-php-orm.md`
+- `project-structure.md`
+- `pulsepoint.md`
+- `route-handlers.md`
+- `swagger-docs.md`
+- `testing.md`
+- `typescript.md`
+- `upgrading.md`
+- `validator.md`
+- `websocket.md`
+
+This inventory exists to help AI find the right Prisma PHP guidance quickly. It is not a feature inventory for the current app.
+
+When a task depends on optional capabilities such as `backendOnly`, `swaggerDocs`, `typescript`, `websocket`, or `mcp`, inspect `./prisma-php.json` before assuming the generated scaffold exists.
+
+When adding or reviewing AI guidance, do not stop at older docs only. Make sure the guidance also covers `backend-only.md`, `email.md`, `env.md`, `get-started-ia.md`, `mcp.md`, `swagger-docs.md`, `typescript.md`, and `websocket.md`, plus newer behavior documented in `fetching-data.md`, `metadata-and-og-images.md`, and `testing.md`.
+
+## Framework-generated files
+
+Prisma PHP automatically generates and maintains certain framework files in consumer apps.
+
+### `files-list.json`
+
+Do **not** create, edit, reorder, or manually maintain `files-list.json`.
+
+Treat `files-list.json` as a framework-generated file for route discovery and internal bookkeeping. When creating, renaming, or removing routes in a Prisma PHP app, make the change in the actual route folders and route files under `src/app` and let Prisma PHP regenerate `files-list.json` automatically.
+
+If a route task appears to require editing `files-list.json`, that is almost certainly the wrong approach.
+
+## Reusable project organization
+
+When organizing a growing Prisma PHP app, keep route code and reusable code separated.
+
+- keep `src/app` focused on the route tree, route-local layouts, pages, handlers, and route-scoped partials
+- prefer `src/Components` for reusable application UI components shared across multiple routes or layouts
+- keep reusable non-UI code such as services, auth, middleware, Prisma classes, and helper libraries in `src/Lib`
+- treat route-private folders such as `src/app/<route>/_components` as an implementation detail for files that stay owned by that route only
+- treat generated libraries such as `src/Lib/PHPXUI` and `src/Lib/PPIcons` as library-specific surfaces governed by their manifests and matching `.github/instructions/**/*.instructions.md` files
+- if a partial starts in `src/app` but becomes shared across the app, promote it into `src/Components`
+- do **not** default to creating `src/app/<route>/_components` for app-owned section components such as `HeroSection`, `FormSection`, or `SidebarSection`; prefer `src/Components` unless the user explicitly wants route-local colocation and the files are truly private to that route
+- do **not** default to placing app-wide reusable components under `src/app` unless the user explicitly wants route-local colocation
+
+## HTML-first component tag contract
+
+Class-based PHPX components and generated icon components are consumed with HTML-first `x-` tags from `settings/component-map.json`, such as `<x-alert>` and `<x-search />`.
 
-## Default interactive UI and fetching rule
+Important rules:
+
+- use the `tagName` entries in `settings/component-map.json` as the supported runtime contract
+- inspect `settings/component-map.json` instead of inventing `x-` tag names from PHP class names
+- document, review, and generate component and icon markup with the current `x-` tag shape
+- keep examples aligned with the current runtime instead of carrying alternate tag-shape guidance
+
+## Component attribute and prop contract
+
+Component attributes in Prisma PHP template markup should be authored in kebab-case. The runtime maps kebab-case attribute names to camelCase prop and public property names when hydrating PHPX components and PulsePoint component boundaries.
+
+Examples:
+
+```html
+<x-button as-child="true" />
+<x-dialog-content close-on-escape-key="true" />
+<x-calendar selected-date="{selectedDate}" on-date-select="{setSelectedDate}" />
+```
+
+Important rules:
+
+- use kebab-case for component attribute names in documentation, examples, reviews, and generated code
+- expect `as-child` to hydrate `asChild`, `close-on-escape-key` to hydrate `closeOnEscapeKey`, and `selected-date` to hydrate `selectedDate`
+- use mustache values such as `selected-date="{selectedDate}"` and `on-date-select="{setSelectedDate}"` when a component prop must receive PulsePoint state or callbacks
+- write component examples as HTML-first Prisma PHP markup using the current `x-` tag contract
+- do not document component props with camelCase template attributes when writing new Prisma PHP markup
+
+## Framework-managed package scripts
+
+Prisma PHP can generate `package.json` scripts for BrowserSync, Tailwind, TypeScript, WebSocket, MCP, Swagger docs, and related project helpers.
+
+AI agents should follow this default rule:
+
+- prefer `npm run dev` for ordinary local development
+- prefer `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 framework-managed 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 a task involves package scripts, read `commands.md` first and inspect the current `package.json` before assuming which feature scripts exist.
+
+## BrowserSync URL source of truth
+
+When AI needs to test or confirm whether a page route, exposed function request, proxy-backed response, or local server workflow is working, check `./settings/bs-config.json` first.
+
+Important rules:
+
+- use `./settings/bs-config.json` as the source of truth for the active BrowserSync URLs in this app
+- do **not** assume the proxy remains on the default `http://localhost:5090`; if that port is already in use, Prisma PHP may use a different port
+- confirm the current `local`, `external`, `ui`, and `uiExternal` values in `./settings/bs-config.json` before suggesting a browser URL, route test URL, or BrowserSync UI URL
+- when frontend console logs, network errors, or terminal output suggest the app is being tested through the wrong URL or proxy port, re-check `./settings/bs-config.json` before changing app code
+
+## CLI command alignment
+
+When a task involves Prisma PHP CLI usage, keep the command guidance aligned with `commands.md`.
+
+- for new apps, prefer `npx create-prisma-php-app <project-name>` as the default recommended create command
+- for existing apps, prefer `npx pp update project` after saving feature changes in `prisma-php.json`
+- when an existing app needs a specific release channel or pinned update version, prefer `npx pp update project --tag <value>` or `npx pp update project --tag=<value>`
+- use `--tag <value>` or `--tag=<value>` for release-channel or pinned-version updates
+- do **not** use `npx pp update project` as a substitute for Prisma ORM migration commands
+
+## Default interactive UI and data-flow rule
 
-For normal full-stack Prisma PHP work, assume the user wants the **PulsePoint-first** approach unless they explicitly ask otherwise.
+For normal full-stack Prisma PHP work, assume the user wants the PulsePoint-first approach unless they explicitly ask otherwise.
+
+PulsePoint is the primary JavaScript authoring model for frontend work in Prisma PHP. For normal page behavior, keep the client logic inside a plain inline `<script>` within the route or imported-partial root, let Prisma PHP scope and execute it, and prefer `pp.rpc(...)` over ad hoc endpoints.
 
 Default interaction stack:
 
 1. render route UI with `index.php`
-2. keep browser-side interactivity in **PulsePoint**
-3. call backend PHP from the frontend with **`pp.fetchFunction(...)`**
-4. mark callable PHP functions or methods with **`#[Exposed]`**
-5. validate and normalize input on the PHP side with **`PP\Validator`**
+2. keep browser-side interactivity in PulsePoint
+3. call backend PHP from the frontend with `pp.rpc(...)`
+4. mark callable PHP functions or methods with `#[Exposed]`
+5. validate and normalize input on the PHP side with `PP\Validator`
+6. use `pp.socket(...)` (named sockets) only when the flow is genuinely long-lived and bidirectional — chat, presence, live feeds
+
+`pp.rpc(...)` is the runtime RPC API. Framework-level RPC failures (unknown function, auth, roles, CSRF, origin, rate limit, server error) arrive as HTTP error statuses with an `{"error": "..."}` body and **reject** the `pp.rpc(...)` promise, so wrap calls in `try/catch` when the UI reacts to failures. Routine, expected validation feedback should still be returned as structured data (`success`, `errors`, normalized values), not thrown.
 
 Treat this as the default for:
 
@@ -154,54 +342,183 @@ Treat this as the default for:
 - inline validation
 - route-local CRUD actions
 - dashboard interactions
+- streaming assistants
+- progress logs
 - similar reactive page behavior
 
 Do **not** default to:
 
 - a PHP-only interaction style
+- plain browser-DOM wiring when PulsePoint state, bindings, and native `on*` handlers already fit the task
 - ad hoc `fetch('/api/...')` patterns
-- extra `route.php` files for page-local interactions that already fit `pp.fetchFunction(...)`
+- extra `route.php` files for page-local interactions that already fit `pp.rpc(...)`
+- a separate Node realtime or tool server when the documented Prisma PHP runtime already fits the task
 
-Choose a more PHP-only pattern only when:
+Choose a more PHP-only or handler-only pattern only when:
 
-- the user explicitly asks for PHP-only behavior
+- the user explicitly asks for it
 - the task is clearly non-reactive
 - the task is a standalone API, webhook, integration endpoint, or public JSON handler
 
-## Default workflow for AI agents
+## Route structure rule AI must not get wrong
+
+There are two related structure rules, and AI must not mix their responsibilities.
+
+### Normal route files such as `index.php` and nested `layout.php`
+
+Use this pattern:
+
+1. PHP first
+2. one parent HTML element as the route boundary
+3. place the visible page or layout content inside that boundary
+4. when PulsePoint is present, let Prisma PHP inject the route or layout `pp-component` scope on that root automatically
+5. keep one `<script>` block as the last child of that boundary root
+
+Also follow these route-file rules:
+
+- `index.php` and nested `layout.php` must render a single parent HTML element
+- use that single parent element as the route boundary; if the visible content should stay inside a semantic element such as `<main>`, `<section>`, or `<article>`, wrap it in a neutral parent such as `<div>`
+- for normal pages and nested layouts, do **not** manually author `pp-component` on that root; Prisma PHP adds it automatically
+- author a plain `<script>` tag inside that root when PulsePoint logic is needed and do **not** put any `type` attribute on it — the runtime only recognizes untyped component scripts
+- keep the `<script>` as the last child of the route boundary, usually as a sibling of the visible content container instead of nesting it inside the semantic content element by default
+- do **not** leave the `<script>` outside the route boundary
+- write PulsePoint state, derived values, and functions directly at the top level of that script; do **not** wrap them in `DOMContentLoaded`, an IIFE, manual `pp.mount()` calls, or custom scoping helpers
+- only the root `layout.php` should define `<html>`, `<head>`, and `<body>`
+- when PulsePoint is present in a root `layout.php`, keep `MainLayout::$children` and any `<script>` inside one clear wrapper
+
+Example:
+
+```php
+<?php
+
+use PP\MainLayout;
 
-Use this workflow unless the user asks for something narrower:
+MainLayout::$title = 'Todos';
+MainLayout::$description = 'Track tasks and view the current item count.';
+?>
+
+<div>
+    <section>
+        <h1>Todos</h1>
+        <p>Count: {count}</p>
+    </section>
+
+    <script>
+        const [count, setCount] = pp.state(0);
+    </script>
+</div>
+```
+
+### Imported partials rendered with `ImportComponent::render(...)`
+
+Use this pattern:
+
+1. PHP first
+2. exactly one parent root element
+3. keep any component-local `<script>` inside that root element
+
+Example:
+
+```php
+<?php
+
+// PHP code
+
+?>
+
+<div>
+    <h2>Search</h2>
+    <input value="{query}" />
+    <script>
+        console.log('Search component ready');
+    </script>
+</div>
+```
 
-1. Read `./prisma-php.json`
-2. Read the relevant installed doc from `node_modules/prisma-php/dist/docs`
-3. Inspect nearby project files that match the route, feature, or component being changed
-4. If the task is component-related, read `components.md` before generating PHPX component code
-5. If the task is upload- or file-manager-related, read `file-manager.md` before generating upload, rename, delete, or file-listing code
-6. Generate code using Prisma PHP conventions
-7. Inspect `vendor/tsnc/prisma-php/src` only if framework internals are required
+Do not:
 
-Do not jump directly into framework internals if the installed docs already answer the task.
+- put a sibling `<script>` next to a route root or imported partial root
+- manually add `pp-component` inside imported partial source
+- add any `type` attribute to route or imported-partial component scripts
+- wrap imported-partial PulsePoint code in `DOMContentLoaded`, an IIFE, manual `pp.mount()` calls, or custom auto-execute helpers
+
+## Metadata rules
+
+For document metadata, prefer `MainLayout::$title` and `MainLayout::$description`.
+
+Important metadata rules:
+
+- a local `$title` variable only affects rendered page content unless you also assign metadata through `MainLayout`
+- use `MainLayout::addCustomMetadata(...)` for additional `<meta>` values when needed
+- keep visible headings separate from document metadata when the UI text and SEO title must differ
+- read `metadata-and-og-images.md` or `layouts-and-pages.md` before inventing Next.js-style metadata exports or Open Graph image workflows
+
+## Streaming and SSE rules
+
+Prisma PHP supports streaming through `pp.rpc(...)` when an exposed function yields values.
+
+Default streaming rules:
+
+- prefer an exposed generator that simply yields strings or arrays
+- let Prisma PHP handle the SSE response automatically for normal `pp.rpc(...)` streaming
+- on the client, put stream UI updates in `onStream`, `onStreamError`, and `onStreamComplete`
+- do not wait for a final JSON payload when the response is streamed
+
+Current parsing rules AI should know:
+
+- Prisma PHP sends streamed payloads as SSE `data:` lines
+- the built-in `pp.rpc(...)` stream parser currently forwards only `data:` lines to `onStream`
+- `event:`, `id:`, and `retry:` may be emitted by low-level SSE helpers, but the built-in stream callback currently ignores them
+- prefer JSON values or single-line strings for streamed chunks instead of multi-line text blobs
+
+Low-level helpers exist when manual SSE control is required:
+
+- `PP\Streaming\SSE`
+- `PP\Streaming\ServerSentEvent`
+
+Core locations documented for those helpers are:
+
+```txt
+vendor/tsnc/prisma-php/src/Streaming/SSE.php
+vendor/tsnc/prisma-php/src/Streaming/ServerSentEvent.php
+```
 
 ## Route file decision rules
 
 When the task is about creating or editing a route, do not guess.
 
-Important: creating a route means creating or updating the correct folder and route file under `src/app`. It does **not** mean editing generated route metadata. In particular, never update `files-list.json` by hand.
+Important: creating a route means creating or updating the correct folder and route file under `src/app`. It does **not** mean editing generated route metadata.
+
+- use `index.php` for rendered UI and normal page routes
+- use `layout.php` for shared UI that wraps route subtrees
+- use `route.php` for direct handlers such as JSON endpoints, API-style routes, AJAX handlers, form-processing endpoints, and webhooks
+- use `not-found.php` for route-specific not-found UI
+- use `error.php` for route or app-level error UI
+- use `loading.php` when the task is specifically about a loading UI state for a route subtree
 
-- Use `index.php` for rendered UI and normal page routes, and default to PulsePoint plus `pp.fetchFunction(...)` for interactive behavior inside those routes unless the user explicitly asks for PHP-only behavior
-- Use `layout.php` for shared UI that wraps route subtrees
-- Use `route.php` for direct handlers such as JSON endpoints, API-style routes, AJAX handlers, form-processing endpoints, webhooks, or other no-view server logic; do not default to `route.php` for normal route-local interactions that fit PulsePoint plus `pp.fetchFunction(...)`
-- Use `not-found.php` for route-specific not-found UI
-- Use `error.php` for route or app-level error UI
+For normal route-local interactivity, prefer `index.php` plus PulsePoint and `pp.rpc(...)` over inventing extra handlers.
 
-Also verify `backendOnly` in `prisma-php.json`:
+In a consumer app, also verify `backendOnly` in `prisma-php.json`:
 
 - if `backendOnly` is `false`, normal routes should usually be implemented with `index.php`
 - if `backendOnly` is `true`, route behavior will usually center on `route.php`
 
+## Default workflow for AI agents
+
+Use this workflow unless the user asks for something narrower.
+
+1. read `./prisma-php.json`
+2. inspect `.github/instructions/` and read any relevant `*.instructions.md` files when that directory exists
+3. read the relevant installed doc from `./node_modules/prisma-php/dist/docs`
+4. inspect `./AGENTS.md` for project-level Prisma PHP guidance
+5. inspect nearby project files that match the route, feature, or component being changed
+6. inspect `vendor/tsnc/prisma-php/src` only if the docs and matching workspace instructions do not answer the task
+
+Do not jump directly into framework internals if the current docs and matching workspace instruction files already answer the task.
+
 ## Authentication rules
 
-When the task involves auth, do not guess from Laravel, NextAuth, generic JWT packages, or ad hoc middleware habits.
+When the task involves auth, do not guess from Laravel, generic JWT packages, or ad hoc middleware habits.
 
 Use this auth decision flow:
 
@@ -210,15 +527,24 @@ Use this auth decision flow:
 3. inspect `src/Lib/Auth/AuthConfig.php` when present
 4. inspect the current auth-related routes under `src/app`
 5. inspect Prisma models that support auth before generating registration, login, or provider code
-6. keep route protection, function protection, and session lifecycle aligned with Prisma PHP’s documented auth model
+6. keep route protection, function protection, and session lifecycle aligned with Prisma PHP's documented auth model
 
 Important auth rules:
 
+- the auth classes are app-owned files under `src/Lib/Auth` in the `Lib\Auth` namespace — write `use Lib\Auth\Auth;` and `use Lib\Auth\AuthConfig;`, never `PP\Auth\...`
 - route privacy strategy is configured from `AuthConfig.php`
 - Prisma PHP supports both public-default and private-default route protection strategies
-- sign users in with `Auth::signIn(...)`
-- sign users out with `Auth::signOut(...)`
-- use `refreshUserSession(...)` when current-session auth payloads must be updated after role or profile changes
+- Prisma PHP defaults to public routes, so keep the public-default strategy when the app will expose many public pages
+- choose the route privacy strategy early, ideally before creating most routes in a new app or route subtree
+- if the app will have only a few public entry points and most routes should require login, switch to the private-default strategy
+- when choosing private-default routing, enable both `AuthConfig::IS_ALL_ROUTES_PRIVATE` and `AuthConfig::IS_TOKEN_AUTO_REFRESH`
+- when `IS_ALL_ROUTES_PRIVATE` is `true`, keep public exceptions in `AuthConfig::$publicRoutes`; home remains public by default because it starts as `['/']`
+- keep `AuthConfig::$authRoutes` public by default unless the user explicitly wants a different auth route allowlist
+- there is no need to modify other Prisma PHP core files to enable private-default routing
+- if `src/Lib/Auth/AuthConfig.php` was customized, protect it from future project updates by adding `./src/Lib/Auth/AuthConfig.php` to `excludeFiles` in `prisma-php.json`
+- sign users in with `Auth::getInstance()->signIn(...)`
+- sign users out with `Auth::getInstance()->signOut(...)`
+- use `Auth::getInstance()->refreshUserSession(...)` when current-session auth payloads must be updated after role or profile changes
 - use role-based route protection in auth config for page access control
 - use `#[Exposed(allowedRoles: [...])]` for function-level access control when frontend code calls PHP directly
 - for credentials auth, model the schema first, then generate ORM classes before writing auth flows
@@ -233,7 +559,7 @@ Use this file-manager decision flow:
 1. read `file-manager.md`
 2. verify the official File Manager docs for the installed version
 3. decide whether the task belongs in a rendered page with `index.php` or a direct handler with `route.php`
-4. confirm the upload destination directory is outside `src/app`
+4. use `./public/uploads` as the default local public upload directory and treat it as publicly accessible
 5. use `PP\FileManager\UploadFile` when the task matches the documented upload workflow
 6. use `PP\Validator` for non-file request values such as rename targets, labels, or filters
 7. return structured messages for expected upload failures such as invalid size, invalid type, partial upload, or missing file
@@ -243,9 +569,116 @@ Important file-manager rules:
 - do **not** omit `enctype="multipart/form-data"` on upload forms
 - do **not** forget the `[]` suffix when generating multiple-file inputs
 - do **not** place uploaded files inside `src/app`
+- use `PUBLIC_PATH . '/uploads/'` or the equivalent absolute `./public/uploads` path for local public uploads
+- treat files saved in `./public/uploads` as publicly accessible from the app's public web root
+- keep `./settings/bs-config.ts` aligned with `const PUBLIC_IGNORE_DIRS = ["uploads"];` so local upload mutations do not trigger BrowserSync reloads
+- do **not** document or generate legacy local upload destinations such as `DOCUMENT_PATH . '/uploads/'`, a project-root `/uploads`, or `src/uploads`
 - do **not** assume HTML size hints replace `php.ini` upload limits
 - do **not** invent undocumented storage abstractions when `UploadFile` already fits the task
-- for upload, rename, replace, delete, and file-listing tasks, read `file-manager.md` first
+
+## Email rules
+
+When the task involves email, read `email.md` first.
+
+Prisma PHP email follows the documented `PP\PHPMailer\Mailer` model backed by PHPMailer. Do not replace it with raw `mail()`, undocumented wrappers, or habits copied from another mail framework.
+
+Use this email workflow:
+
+1. read `email.md`
+2. inspect `.env` for SMTP and sender values in the target app
+3. inspect the route, exposed function, or handler that sends the email
+4. inspect the HTML body or attachment source when present
+5. inspect framework internals only when the docs and current app code still leave a gap
+
+The documented core mailer file is:
+
+```txt
+vendor/tsnc/prisma-php/src/PHPMailer/Mailer.php
+```
+
+Important email rules:
+
+- keep SMTP credentials and sender defaults in `.env`, not in route files
+- the documented env vars are `SMTP_HOST`, `SMTP_USERNAME`, `SMTP_PASSWORD`, `SMTP_ENCRYPTION`, `SMTP_PORT`, `MAIL_FROM`, and `MAIL_FROM_NAME`
+- validate user-provided email fields before calling the mailer
+- prefer the documented fluent API such as `to(...)`, `subject(...)`, `html(...)`, `text(...)`, `attach(...)`, and `send()`
+- use `raw()` only when low-level PHPMailer access is genuinely needed
+
+## Env rules
+
+When the task involves `.env`, `PP\Env`, feature flags, ports, host names, timezones, API keys, numeric limits, or other runtime configuration values, read `env.md` first.
+
+Use this env workflow:
+
+1. read `env.md`
+2. inspect `.env` or the deployment environment when the task depends on actual values
+3. inspect the bootstrap or server entry file that loads or consumes the environment
+4. inspect the feature-specific doc such as `email.md`, `mcp.md`, `websocket.md`, `get-started-ia.md`, or `prisma-php-orm.md` when the env values belong to that feature
+5. inspect `vendor/tsnc/prisma-php/src/Env.php` only if the docs do not answer the task
+
+Important env rules:
+
+- prefer `PP\Env` over repeated ad hoc `getenv()` parsing in documented Prisma PHP code paths
+- use `Env::string(...)`, `Env::bool(...)`, and `Env::int(...)` for typed access with defaults
+- use `Env::get(...)` when raw nullable string access is actually needed
+- remember that `PP\Env` reads values from `getenv()`, `$_ENV`, and `$_SERVER`; it does not parse `.env` by itself
+- keep secrets and deployment-specific settings in `.env` or the real runtime environment, not hardcoded in route files or components
+
+## WebSocket rules
+
+When the task involves realtime messaging, presence, live dashboards, chat, `pp.socket(...)`, or `Ratchet`, read `websocket.md` first.
+
+Prisma PHP realtime support is built on **named sockets**: `pp.socket(name, args, handlers)` in the browser, and a Ratchet-based server under `src/Lib/Websocket` that dispatches each connection to a handler registered with `SocketRegistry`. Do not replace that default with Socket.IO, a separate Node server, raw `new WebSocket(...)` wiring, or an unrelated hosted realtime service unless the user explicitly asks for a different architecture.
+
+Use this websocket workflow:
+
+1. read `websocket.md`
+2. inspect whether websocket support is enabled in `prisma-php.json` in the target app
+3. inspect `src/Lib/Websocket`, especially `sockets.php` for the registered socket names
+4. inspect the route script that calls `pp.socket(...)`
+5. inspect `settings/restart-websocket.ts` when local restart behavior matters
+6. inspect framework internals only when the docs do not answer the task
+
+Important websocket rules:
+
+- connect from the browser with `pp.socket(name, args, handlers)`; do **not** generate raw `new WebSocket(...)` wiring for app realtime work
+- register server handlers with `SocketRegistry::register(...)` in `src/Lib/Websocket/sockets.php`; socket names are unique application-wide
+- do not put socket handlers in route files — route files are not loaded by the socket server process
+- keep the wire contract intact: one endpoint (`/__pulsepoint/ws`), the function named in the `name` query parameter, arguments as the connection's first JSON frame, one JSON value per frame in either direction, and `{"error": "..."}` (that key alone) reserved for failures
+- use `src/Lib/Websocket/websocket-server.php` as the source of truth for startup behavior
+- use `src/Lib/Websocket/ConnectionManager.php` as the wire and lifecycle boundary (handshake security, argument frame, dispatch, limits)
+- use `SocketPool` for broadcasts; keep authenticated and guest traffic in separate pools
+- declare auth with `requireAuth` / `allowedRoles` at registration; the handshake is verified against the JWT auth cookie before the handler runs
+- a `Socket::send(...)` that returns `false` means the browser is gone — stop sending, it is not an error
+- preserve documented env vars and defaults: `WS_NAME`, `WS_VERSION`, `WS_HOST`, `WS_PORT`, `WS_VERBOSE`, `APP_TIMEZONE`, `MAX_WEBSOCKET_CONNECTIONS`, `MAX_WEBSOCKET_MESSAGE_BYTES`, `MAX_WEBSOCKET_MESSAGES_PER_WINDOW`, `WEBSOCKET_RATE_WINDOW_SECONDS`, `WEBSOCKET_IDLE_TIMEOUT_SECONDS`, `WEBSOCKET_ALLOWED_ORIGINS`
+- preserve CLI overrides through `--host=...`, `--port=...`, and `--verbose=...`
+- preserve the documented casing `src/Lib/Websocket`
+- in development, `settings/bs-config.ts` proxies `/__pulsepoint/ws` from the BrowserSync origin to the Ratchet server, so `pp.socket(...)` needs no `url` option; pass `url` only outside that proxy
+- for existing apps, enable `websocket` in `prisma-php.json` and run `npx pp update project -y` before inventing manual scaffolding
+
+## MCP rules
+
+When the task involves Model Context Protocol support, read `mcp.md` first.
+
+Prisma PHP MCP support follows the documented `PhpMcp\Server` model with attribute-based tool discovery. Do not replace it with custom REST endpoints pretending to be MCP, hand-rolled JSON-RPC parsing, or unrelated agent abstractions when the documented Prisma PHP stack already fits the task.
+
+Use this MCP workflow:
+
+1. read `mcp.md`
+2. inspect whether MCP support is enabled in `prisma-php.json` in the target app
+3. inspect `src/Lib/MCP`
+4. inspect tool classes and the services they call
+5. inspect auth, ORM, and env configuration when tools read protected or database-backed data
+6. inspect framework internals only when the docs do not answer the task
+
+Important MCP rules:
+
+- use `src/Lib/MCP/mcp-server.php` as the source of truth for startup behavior
+- preserve attribute-based discovery with `#[McpTool]` and `#[Schema]`
+- preserve the documented discovery model built around scanning the source tree instead of manually wiring every tool class by default
+- preserve the documented casing `src/Lib/MCP`
+- preserve documented env vars and defaults: `MCP_NAME`, `MCP_VERSION`, `MCP_HOST`, `MCP_PORT`, `MCP_PATH_PREFIX`, `MCP_JSON_RESPONSE`, `APP_TIMEZONE`
+- for existing apps, enable `mcp` in `prisma-php.json` and run `npx pp update project -y` before inventing manual scaffolding
 
 ## Prisma ORM workflow rules
 
@@ -262,51 +695,59 @@ Use this ORM decision flow:
 7. after schema synchronization, run `npx ppo generate`
 8. only then write or update PHP code that depends on the generated Prisma classes
 
-Important rules:
+Important ORM rules:
 
 - do **not** use `npx pp update project -y` as the normal fix for Prisma ORM schema changes
 - use `npx prisma migrate dev` for the normal development migration workflow
 - use `npx prisma migrate deploy` for production or CI/CD migration application
 - use `npx prisma db push` only for explicit prototyping or no-migration database sync
 - do **not** treat `npx ppo generate` as a migration step
-- `npx ppo generate` should run the first time generated PHP ORM classes are needed and whenever `schema.prisma` changes
-- if the task mentions Prisma ORM, `schema.prisma`, migrations, generated classes, SQLite, MySQL, or PostgreSQL, read `prisma-php-orm.md` first
 
 ## Validation rules
 
-When a task involves user input, form handling, search params, JSON payloads, `pp.fetchFunction(...)`, or `route.php` bodies, do not trust raw values.
+When a task involves user input, form handling, search params, JSON payloads, `pp.rpc(...)`, `route.php` bodies, or tool parameters, do not trust raw values.
 
 Default Prisma PHP validation rules:
 
-- use **`PP\Validator`** as the backend validation and normalization layer
-- prefer the **`Rule` builder** for rule-based validation
+- use `PP\Validator` as the backend validation and normalization layer
+- prefer the `Rule` builder for rule-based validation
+- start `Rule` builders with `Rule::required()`, `Rule::optional()`, or `Rule::make()`
+- chain rule methods such as `->min(...)`, `->max(...)`, `->email()`, and `->regex(...)` on that builder instance
+- do **not** generate static calls such as `Rule::max(80)`; for optional constrained fields use `Rule::optional()->max(80)` or `Rule::make()->max(80)`
 - validate in PHP even when the frontend already performs local checks
 - return structured validation results for expected failures
 - do not treat routine invalid input as an uncaught exception
 - in reactive flows, use PulsePoint for local state and `Validator` for authoritative server validation
 
+When internals matter, the documented Prisma PHP core validator location is:
+
+```txt
+vendor/tsnc/prisma-php/src/Validator.php
+vendor/tsnc/prisma-php/src/Rule.php
+```
+
 ## PulsePoint rules
 
 When a task involves reactive frontend behavior, read `pulsepoint.md` first.
 
 Also follow these rules:
 
+- treat PulsePoint as the primary JavaScript authoring model for normal full-stack frontend work
+- keep page and imported-partial client logic inside the boundary's plain `<script>` tag instead of building extra DOM-ready or self-executing wrappers
+- prefer `pp.rpc(...)` over ad hoc `fetch('/api/...')` calls for page-local PHP interactions
+- reserve plain browser JavaScript outside PulsePoint for external libraries, low-level browser APIs, and reusable helpers in `ts/`
 - do not invent undocumented PulsePoint helpers or directives
 - do not write React, Vue, Alpine, or Livewire syntax and call it PulsePoint
 - keep backend concerns separate from PulsePoint runtime concerns
 - prefer simple documented runtime primitives over abstractions copied from other ecosystems
-
-## Reactive frontend + server-call rule
-
-For frontend interactivity in Prisma PHP, prefer the documented Prisma PHP pattern:
-
-- use **PulsePoint** for reactive browser state and UI behavior
-- use **`pp.fetchFunction(...)`** for page-local or component-local server calls
-- expose callable PHP functions with **`#[Exposed]`**
-
-Do not default to handcrafted `fetch('/api/...')` calls, ad hoc AJAX endpoints, or extra `route.php` files when the task is a normal reactive UI interaction that fits `pp.fetchFunction(...)`.
-
-Use `route.php` when the user explicitly needs an API-style endpoint, webhook, JSON route, or handler that should exist independently of the current page.
+- do not treat app-registered helpers such as `twMerge(...)` as PulsePoint built-ins; route those tasks through the Tailwind-enabled Prisma PHP docs after checking feature flags
+- use `pp-style` whenever inline CSS contains `{...}` interpolation or any other template-driven/reactive value, and reserve plain `style` for fully static inline CSS
+- do **not** generate reactive inline CSS inside a plain `style` attribute such as `style="width: {progress}%";` use `pp-style="width: {progress}%";` instead so source markup stays editor-friendly
+- use `pp-spread="{...attrs}"` for dynamic attribute objects and omit nullish values from those objects
+- use `pp-for` only on `<template>` with `item in items` or `(item, index) in items`
+- use plain `key` for keyed diffing; do not invent `pp-key`
+- use `pp.ref(...)`, `pp-ref`, `pp.portal(...)`, `pp.createContext(...)`, `Context.Provider`, and `pp.context(...)` according to `pulsepoint.md`
+- use `value`, `defaultvalue`, and `defaultchecked` form bindings according to `pulsepoint.md`; do not author internal `data-pp-*` form attributes
 
 ## Component rules
 
@@ -315,94 +756,51 @@ When the task involves Prisma PHPX components, reusable UI elements, props, chil
 Also follow these rules:
 
 - do not assume React, Vue, Blade, or generic templating component behavior maps directly to Prisma PHPX
+- use HTML-first `x-` tags such as `<x-button>` and `<x-search />` when generating template markup for class-based components
+- use kebab-case component attributes and rely on the runtime to hydrate camelCase PHPX properties and PulsePoint props
 - keep component file names and class names aligned
 - preserve documented PHPX patterns for `$props`, `$children`, `$class`, and `getAttributes(...)`
+- in Tailwind-enabled apps, use `getMergeClasses(...)` and `PP\PHPX\TwMerge::merge(...)` as emitters of frontend `twMerge(...)` expressions instead of finalizing Tailwind class conflicts in PHP
+- when a route or imported partial needs direct Tailwind-aware class composition, treat `twMerge(...)` as an app-level browser helper available only when `tailwindcss` is enabled
 - follow documented component placement and grouping conventions before inspecting framework internals
-- use `vendor/tsnc/prisma-php/src` only when the installed docs and `components.md` do not answer the task
-
-## Prisma PHP XML syntax rules
-
-Prisma PHP uses XML-style syntax for PHPX and template markup.
-
-AI agents must follow strict XML rules when generating tags and attributes.
-
-### Closing tags
-
-All tags must be properly closed.
-
-Correct:
-
-```xml
-<hr />
-<input type="text" />
-<div></div>
-```
-
-Incorrect:
-
-```xml
-<hr>
-<input type="text">
-```
-
-### Attributes
-
-All attributes must use double quotes.
-
-Correct:
-
-```xml
-<input id="email" />
-<input required="true" />
-```
-
-Incorrect:
-
-```xml
-<input id=email />
-<input required />
-```
-
-### Boolean attributes
-
-Boolean attributes must be explicit.
-
-Correct:
-
-```xml
-<input disabled="true" />
-<option selected="true">Admin</option>
-```
-
-Incorrect:
-
-```xml
-<input disabled />
-<option selected>Admin</option>
-```
-
-Do not output permissive HTML shorthand in Prisma PHP UI files.
 
 ## When to inspect framework internals
 
-Prisma PHP core Composer package files live in:
+Inspect framework internals only when the docs and current files do not answer the task.
+
+Useful app-mode core locations include:
 
 ```txt
 vendor/tsnc/prisma-php/src
+vendor/tsnc/prisma-php/src/PHPX/PHPX.php
+vendor/tsnc/prisma-php/src/PHPX/TwMerge.php
+vendor/tsnc/prisma-php/src/PHPX/TemplateCompiler.php
+vendor/tsnc/prisma-php/src/ImportComponent.php
+vendor/tsnc/prisma-php/src/MainLayout.php
+vendor/tsnc/prisma-php/src/PrismaPHPSettings.php
+vendor/tsnc/prisma-php/src/Request.php
+vendor/tsnc/prisma-php/src/Attributes/Exposed.php
+vendor/tsnc/prisma-php/src/Attributes/ExposedRegistry.php
+vendor/tsnc/prisma-php/src/Env.php
+vendor/tsnc/prisma-php/src/Rule.php
+vendor/tsnc/prisma-php/src/PHPMailer/Mailer.php
+vendor/tsnc/prisma-php/src/FileManager/UploadFile.php
+vendor/tsnc/prisma-php/src/Validator.php
+vendor/tsnc/prisma-php/src/Streaming/SSE.php
+vendor/tsnc/prisma-php/src/Streaming/ServerSentEvent.php
 ```
 
-Inspect this directory only when the task depends on framework internals not already answered by the installed docs.
-
-Use it when the task involves:
+Use framework internals when the task involves:
 
 - confirming namespaces, classes, or helper names
 - understanding how a core class behaves internally
-- verifying available attributes such as `#[Exposed]`
+- verifying available attributes such as `#[Exposed]`, `#[McpTool]`, or `#[Schema]`
 - checking PHPX compiler or template compiler behavior
 - tracing PulsePoint integration points inside Prisma PHP
-- debugging framework-level issues that are not explained by the docs
+- confirming mailer, SSE, websocket, or MCP runtime behavior not already clear from the docs
+- debugging framework-level issues that are not explained by the current docs
 
-For ordinary app work, prefer the installed docs and local project files first.
+For ordinary app or docs work, prefer the current docs and local project files first.
 
 ## Upgrade and feature-enable workflow
 
@@ -410,20 +808,17 @@ If the task involves enabling a feature, syncing framework-managed files, or upd
 
 Important rules:
 
-- update `prisma-php.json` before assuming a feature is active
+- update `prisma-php.json` before assuming a feature is active in a consumer app
 - do not assume Tailwind, Prisma, Swagger, WebSocket, MCP, or TypeScript support is enabled unless `prisma-php.json` says so
+- keep customized framework-managed files such as `src/Lib/Auth/AuthConfig.php` in `excludeFiles` when you need project updates to preserve them
 - after changing feature flags, follow the documented project update flow
-- for AI-driven or scripted updates, prefer:
-
-```bash
-npx pp update project -y
-```
+- for AI-driven or scripted updates, prefer `npx pp update project -y`
 
-This command is for project updates and framework-managed file refreshes. It is not the default ORM migration command.
+That command is for project updates and framework-managed file refreshes. It is not the default ORM migration command.
 
 ## Final operating rule
 
-When Prisma PHP behavior is documented locally, read the relevant installed doc first and follow it.
+When Prisma PHP behavior is documented locally, read the relevant current doc first and follow it.
 
 Do not guess.