prisma-php 0.0.1 → 0.0.3

package/dist/docs/{01-getting-started/authentication.md → authentication.md}

@@ -193,6 +193,7 @@ The documented login flow uses:
 When generating credentials auth, do not trust raw request data.
 
 For backend validation and normalization, default to Prisma PHP’s validation layer rather than browser-only checks. In this docs set, that means using the documented validation guidance alongside `PP\Validator`-style server validation patterns from the rest of the local docs.
+Read `validator.md` before generating credential validation, registration validation, or auth-related request normalization.
 
 ## Social authentication
 

package/dist/docs/{01-getting-started/error-handling.md → error-handling.md}

@@ -6,6 +6,7 @@ related:
   description: Learn more about the features mentioned on this page by reading the Prisma PHP docs.
   links:
     - /docs/error-handler
+    - /docs/php-validator
     - /docs/route-php
     - /docs/index-php
     - /docs/pages-and-layouts
@@ -62,6 +63,8 @@ In Prisma PHP, the recommended pattern is generally:
 - return a structured response or message
 - avoid letting routine validation failures become fatal exceptions
 
+Read `validator.md` for the detailed local guidance on helper selection, rule syntax, and `Validator::withRules(...)` behavior.
+
 ### Form or direct function example
 
 ```php filename="src/app/contact/index.php"

package/dist/docs/{01-getting-started/fetching-data.md → fetching-data.md}

@@ -6,6 +6,7 @@ related:
   description: Learn more about the features mentioned in this page by reading the Prisma PHP docs.
   links:
     - /docs/fetch-function
+    - /docs/php-validator
     - /docs/index-php
     - /docs/route-php
     - /docs/pages-and-layouts
@@ -18,6 +19,38 @@ Prisma PHP has a different mental model from Next.js. Instead of focusing on Rea
 When using `pp.fetchFunction(...)`, the PHP function must be explicitly exposed with `#[Exposed]`. Functions are private by default, so a non-exposed function cannot be called from the client.
 
 For validation, the default backend pattern should be **`PP\Validator`**. Use it to sanitize, cast, and validate values inside exposed functions and route handlers. This keeps the browser reactive while keeping the authoritative validation on the server.
+Read `validator.md` alongside this page when you need the detailed helper list, rule syntax options, or the `Validator::withRules(...)` return contract.
+
+## Default AI decision rule
+
+For **normal interactive full-stack Prisma PHP work**, AI should default to this stack:
+
+1. render the route with `index.php`
+2. use **PulsePoint** for browser-side state and reactive UI behavior
+3. use **`pp.fetchFunction(...)`** for frontend-to-PHP calls
+4. mark callable PHP functions with **`#[Exposed]`**
+5. use **`PP\Validator`** for authoritative backend validation and normalization
+
+This should be the default for cases such as:
+
+- live search
+- filters
+- pagination controls
+- quick edit dialogs
+- inline validation
+- toggles and status changes
+- modal-based mutations
+- optimistic-feeling dashboard interactions
+- route-local CRUD actions that belong to the current page
+
+Do **not** default to a more PHP-only interaction style for those cases unless the **user explicitly asks for PHP-only behavior**.
+
+A more PHP-only pattern is reasonable when:
+
+- the user explicitly asks for plain PHP, classic form submission, or no PulsePoint
+- the route is intentionally non-reactive
+- the task is a standalone API, webhook, integration endpoint, or public JSON route
+- the behavior must exist independently of the current page
 
 ## Validation is a server concern
 
@@ -49,6 +82,7 @@ For reactive UI work, the best Prisma PHP pattern is usually:
 4. return a structured object for the UI to render
 
 The official Validator docs recommend the **`Rule` builder** for most rule-based validation because it is easier to discover, easier to refactor, and less error-prone than raw pipe strings.
+`validator.md` is the local source of truth for how this docs set expects AI to apply that guidance.
 
 ## Recommended pattern for reactive Prisma PHP UIs
 
@@ -59,9 +93,9 @@ For normal interactive UI work in Prisma PHP, the default approach should be:
 3. call PHP from the frontend with `pp.fetchFunction(...)`
 4. expose callable functions with `#[Exposed]`
 
-This is the preferred pattern for live search, inline validation, toggles, quick edits, filtering, lightweight mutations, and similar route-local interactions.
+This is the preferred pattern for live search, inline validation, toggles, quick edits, filtering, lightweight mutations, pagination, modal workflows, and similar route-local interactions.
 
-Do **not** default to building extra `route.php` endpoints for every interactive action when `pp.fetchFunction(...)` is the better fit. Reserve `route.php` for explicit API-style endpoints, webhooks, JSON handlers, or routes that must be called independently of the page.
+Do **not** default to building extra `route.php` endpoints for every interactive action when `pp.fetchFunction(...)` is the better fit. Also do **not** default to a PHP-only interaction model for normal reactive page behavior unless the user explicitly asks for that style. Reserve `route.php` for explicit API-style endpoints, webhooks, JSON handlers, or routes that must be called independently of the page.
 
 ## Fetching data in Prisma PHP
 
@@ -617,7 +651,7 @@ When fetching data from Prisma PHP:
 - every function called through `pp.fetchFunction(...)` must use `#[Exposed]`
 - return structured validation results instead of relying on thrown exceptions for routine failures
 - use `Exposed` options to enforce auth, roles, or rate limits
-- prefer `route.php` for dedicated public or integration-facing endpoints
+- prefer `route.php` for dedicated public or integration-facing endpoints, not as the default answer for normal page-local interactivity
 - keep sensitive database access on the server side
 
 Because Prisma PHP runs the data logic in PHP, database credentials and internal query logic stay on the server.
@@ -634,4 +668,4 @@ Because Prisma PHP runs the data logic in PHP, database credentials and internal
 - `abortPrevious: true` helps cancel stale requests.
 - file uploads can be handled automatically without manual `FormData` in many cases.
 - `Exposed` can be used to declare authentication, allowed roles, and rate limits for callable functions.
-- for full-stack routes, load page data in `index.php` and use direct function invocation for interactive updates.
+- for full-stack routes, load page data in `index.php` and use PulsePoint plus direct function invocation for interactive updates unless the user explicitly asks for a PHP-only flow.

package/dist/docs/{01-getting-started/file-manager.md → file-manager.md}

@@ -15,6 +15,7 @@ related:
 Prisma PHP file handling should follow the documented **File Manager** model and standard PHP upload rules, not assumptions copied from Laravel storage disks, Symfony upload abstractions, Livewire temporary uploads, or custom Node-style multipart pipelines.
 
 If a task involves file uploads, upload forms, `$_FILES`, upload size limits, allowed file types, renaming, deleting, replacing files, or building a file manager UI, AI agents should read the relevant Prisma PHP File Manager docs first and keep the implementation aligned with the installed Prisma PHP version.
+When the task also involves validating rename fields, labels, descriptions, or other non-file inputs, read `validator.md` alongside this page.
 
 ## AI rule: read the File Manager docs first
 
@@ -32,7 +33,7 @@ Do not assume another framework's storage abstraction applies directly.
 ## Read this doc when you need
 
 - **basic upload form setup, `multipart/form-data`, or raw `$_FILES` behavior** → official `get-started-file`
-- **upload validation and normalization for names or request values** → official `php-validator` plus local validation guidance in `fetching-data.md`, `error-handling.md`, and `route-handlers.md`
+- **upload validation and normalization for names or request values** → `validator.md` first, then official `php-validator`, plus local validation guidance in `fetching-data.md`, `error-handling.md`, and `route-handlers.md`
 - **a rendered upload page or full-stack file manager screen** → `index.php` plus `layouts-and-pages.md`
 - **a standalone upload endpoint, webhook-like file receiver, or direct JSON upload handler** → `route.php` plus `route-handlers.md`
 - **local dev reload issues caused by uploaded files changing on disk** → inspect `./settings/bs-config.ts` and exclude the upload directory from BrowserSync tracking
@@ -210,6 +211,7 @@ For file manager pages and upload-related actions, keep these concerns separate:
 - use route pages or route handlers according to the documented `index.php` versus `route.php` split
 
 Do not use filename cleanup as a substitute for validating other request data.
+For the full local validation contract, read `validator.md`.
 
 ## Organization guidance
 
@@ -277,7 +279,7 @@ When the user asks for upload or file-manager functionality, AI should usually f
 4. choose the upload destination directory
 5. if local reload becomes noisy, exclude the upload directory in `./settings/bs-config.ts`
 6. use `UploadFile` for upload, rename, update, and delete operations when it fits the documented workflow
-7. use `PP\Validator` for rename fields or other non-file request values
+7. read `validator.md`, then use `PP\Validator` for rename fields or other non-file request values
 8. return structured messages for expected failures
 9. inspect Prisma PHP internals only if the docs and local project usage are not enough
 

package/dist/docs/index.md

@@ -8,7 +8,7 @@ related:
     - /docs/get-started
 ---
 
-{/_AI agent hint: Prisma PHP uses local installed docs as the source of truth for the active project version. Before generating framework-specific code, read `prisma-php.json` first, then read the relevant docs from `node_modules/prisma-php/dist/docs`. For PulsePoint runtime behavior specifically, read `pulsepoint.md` before generating reactive UI code. For Prisma ORM work, read `prisma-php-orm.md` before choosing provider checks, schema workflow, migration commands, or ORM generation commands. Route creation is file-based from `src/app`; Prisma PHP auto-generates route listings such as `files-list.json`, so AI agents must not create, edit, or maintain that file manually._/}
+{/_ AI agent hint: Prisma PHP uses local installed docs as the source of truth for the active project version. Before generating framework-specific code, read `prisma-php.json` first, then read the relevant docs from `node_modules/prisma-php/dist/docs`. For authentication, read `authentication.md` first, then verify the official auth docs: `auth-get-started`, `credentials`, and `state-manager-auth`. For file uploads, `multipart/form-data`, `$_FILES`, `PP\FileManager\UploadFile`, rename/delete flows, or file manager screens, read `file-manager.md` first, then verify the official File Manager docs: `get-started-file`. For ORM work, read `prisma-php-orm.md` before choosing schema, migration, or generation commands. For PulsePoint runtime behavior specifically, read `pulsepoint.md` before generating reactive UI code. For normal interactive full-stack page work, default to PulsePoint plus `pp.fetchFunction(...)` unless the user explicitly asks for a PHP-only interaction style. For backend validation, sanitization, `Validator`, `Rule`, `pp.fetchFunction(...)` validation flows, or request validation in `route.php`, read `validator.md` first, then use `fetching-data.md`, `error-handling.md`, and `route-handlers.md` for context-specific patterns, then consult the official Validator docs. `PP\Validator` is a Prisma PHP core class located in `vendor/tsnc/prisma-php/src/Validator.php`. Route creation is file-based from `src/app`; Prisma PHP auto-generates route listings such as `files-list.json`, so AI agents must not create, edit, or maintain that file manually. _/}
 
 Welcome to the Prisma PHP documentation!
 
@@ -33,143 +33,99 @@ Use this order:
 3. Inspect local project files.
 4. Inspect `vendor/tsnc/prisma-php/src` only when framework internals are necessary.
 
+### Default interactive pattern
+
+For typical full-stack Prisma PHP work, AI should assume this default:
+
+1. render route UI in `index.php`
+2. keep browser-side interactivity in **PulsePoint**
+3. call PHP from the frontend with **`pp.fetchFunction(...)`**
+4. expose callable functions with **`#[Exposed]`**
+5. validate and normalize incoming values in PHP with **`PP\Validator`**
+
+Do **not** default to PHP-only interaction flows for normal reactive UI work unless the user explicitly asks for that style.
+
 ### Read this doc when you need
 
 - **project setup or file placement** → `project-structure.md`
-- **pages, layouts, route creation, nested routes** → `layouts-and-pages.md`
-- **`pp.fetchFunction(...)`, `#[Exposed]`, page data loading** → `fetching-data.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`
+- **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`
+- **authentication strategy, `AuthConfig.php`, sign-in, sign-out, route privacy model, RBAC, credentials auth, social login, or auth state manager usage** → `authentication.md`
+- **validation, sanitization, casting, `PP\Validator`, `Rule`, or `Validator::withRules(...)`** → `validator.md`
+- **`pp.fetchFunction(...)`, `#[Exposed]`, page data loading, interactive validation with `Validator`** → `fetching-data.md`
 - **cache behavior and `CacheHandler`** → `caching.md`
-- **Prisma ORM setup, database provider checks, `.env` validation, SQLite database path checks, schema workflow, migration flow, `npx prisma migrate dev`, `npx ppo generate`, and Prisma query patterns** → `prisma-php-orm.md`
-- **error handling, `error.php`, `not-found.php`** → `error-handling.md`
+- **ORM, `schema.prisma`, database provider, migrations, generated PHP classes, `prisma.config.ts`, `.env` `DATABASE_URL`, or Prisma CLI workflow** → `prisma-php-orm.md`
+- **error handling, `error.php`, `not-found.php`, expected validation errors** → `error-handling.md`
 - **metadata, title, description, favicon, icons** → `metadata-and-og-images.md`
-- **API-style endpoints and `route.php`** → `route-handlers.md`
+- **API-style endpoints, `route.php`, request validation with `Validator`** → `route-handlers.md`
 - **PulsePoint runtime APIs such as `pp.state`, `pp.effect`, `pp.ref`, `pp-for`, `pp-ref`, `pp-spread`** → `pulsepoint.md`
-- **updating the project structure, installing enabled framework features, or refreshing project-managed files** → `upgrading.md`
+- **updating the project or enabling features** → `upgrading.md`
+- **first-time project creation** → `installation.md`
 
 ### Important AI rules
 
 - treat `node_modules/prisma-php/dist/docs` as the primary documentation source for the installed version
 - do not assume Laravel, Symfony, React, Vue, Alpine, Livewire, or Next.js behavior maps directly
-- do not guess routing, file conventions, request helpers, reactive syntax, or ORM workflow when local docs already define them
+- do not guess routing, file conventions, request helpers, component APIs, reactive syntax, or auth behavior when local docs already define them
 - create routes by adding folders and route files under `src/app`
 - do not create, edit, or maintain `files-list.json`; Prisma PHP generates route listings automatically
-- when building interactive frontend behavior, prefer the documented PulsePoint pattern with browser-side reactive state and `pp.fetchFunction(...)` for server calls
+- 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 building PulsePoint inside `index.php` or `layout.php`, read `layouts-and-pages.md` together with `pulsepoint.md`, use PHP then HTML then one `<script>` block, and keep route content inside a single parent HTML element
+- 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]`
-- for Prisma ORM work, confirm the configured database provider first before choosing setup or migration commands
-- for SQLite projects, read `.env`, confirm `DATABASE_URL` exists, resolve the SQLite database file path, and treat a missing, invalid, or not-yet-created SQLite database file as a signal to run `npx prisma migrate dev` before relying on generated ORM classes
-- for MySQL and PostgreSQL projects, run `npx prisma migrate dev` during first setup and whenever `schema.prisma` changes
-- after first ORM setup, and after any `schema.prisma` change, run `npx ppo generate` so the generated PHP classes match the database structure
-- do not treat `npx ppo generate` as a migration step or as proof that the database is already synced
-- do not use `npx pp update project -y` as a replacement for Prisma migration or ORM class generation; that command is for updating the project structure, dependencies, and enabled framework features
-- when changing feature flags in `prisma-php.json`, follow the documented project update workflow
-- for AI-driven project updates, prefer the documented non-interactive command: `npx pp update project -y`
-
-## Important PHPX and XML syntax rules
-
-Prisma PHP uses **XML-style syntax** for PHPX and framework template markup.
-
-This means AI agents and developers should not write tags using permissive HTML shorthand. Prisma PHP markup should be treated as **strict XML**, where tags and attributes must follow explicit closing and quoting rules.
-
-### 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 required="true" />
-<input id="input" />
-```
-
-Incorrect:
-
-```xml
-<input required />
-<input id=input />
-```
+- when changing feature flags, update `prisma-php.json` first, then follow the documented update 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
+- when building auth flows, protection rules, or login/register pages, read `authentication.md` first and keep the implementation aligned with Prisma PHP’s documented auth model
 
-### Boolean attributes
+## File Manager
 
-Do not use shorthand boolean attributes in Prisma PHP markup. Write them explicitly.
+Prisma PHP includes a documented File Manager model for uploads and file operations based on standard PHP uploads plus `PP\FileManager\UploadFile`.
 
-Correct:
+Use `file-manager.md` as the local AI-awareness guide for:
 
-```xml
-<input disabled="true" />
-<option selected="true">Admin</option>
-```
+- upload forms with `multipart/form-data`
+- `$_FILES` handling
+- `PP\FileManager\UploadFile`
+- upload size and type restrictions
+- rename, replace, and delete flows
+- choosing between a rendered upload page and a direct upload handler
+- validating non-file request values with `PP\Validator`
 
-Incorrect:
+After reading `file-manager.md`, read `validator.md` when non-file request values are involved, then verify the matching official docs at:
 
-```xml
-<input disabled />
-<option selected>Admin</option>
-```
+1. `get-started-file`
+2. `php-validator` when auxiliary request validation is needed
+3. `route-php` or `pages-and-layouts` depending on whether the task is a direct handler or a full-stack page
 
-### AI rule
+## Authentication
 
-When generating Prisma PHP markup, always treat it as **strict XML**, not permissive HTML and not JSX shorthand.
+Prisma PHP includes a documented authentication model centered on sessions, route protection strategy, RBAC, and provider-based sign-in flows.
 
-## How to use the docs
+Use `authentication.md` as the local AI-awareness guide for:
 
-The docs are organized into multiple sections so you can learn Prisma PHP progressively:
+- `AuthConfig.php`
+- public-default vs private-default route strategy
+- `Auth::signIn(...)`
+- `Auth::signOut(...)`
+- `refreshUserSession(...)`
+- route-level RBAC
+- function-level protection with `#[Exposed(allowedRoles: [...])]`
+- credential authentication
+- social authentication
 
-- [Get Started](/docs): Learn the fundamentals, project structure, commands, tools, environment setup, routing, file conventions, HTML attributes, JavaScript usage, class usage, and authentication.
-- [Starter Kits](/docs): Learn how installation works, how starter kits are structured, and how to create your own.
-- [PHPX](/docs): Learn the component model and how to build reusable UI with PHP-first syntax.
-- [ORM](/docs): Learn Prisma config, database setup, CLI usage, seeding, relations, reading, writing, filtering, aggregates, raw queries, transactions, and field selection.
-- [API](/docs): Learn the API features and Swagger docs support.
-- [AI](/docs): Learn the AI-related features, MCP support, and framework rules.
-- [Additional Features](/docs): Explore file manager, pagination, debug tooling, websocket support, and email.
-- [PulsePoint Runtime Rules](./pulsepoint): Learn the approved PulsePoint runtime surface, directives, refs, effects, and frontend reactive patterns AI should follow.
+After reading `authentication.md`, verify the matching official docs in this order:
 
-Use the sidebar to navigate through sections, or search with the command palette (`Ctrl+K`) to quickly find a page.
+1. `auth-get-started`
+2. `credentials`
+3. `state-manager-auth`
 
-## Core framework areas
+## Routing and file conventions
 
-Prisma PHP brings together a few major parts of the stack:
+Prisma PHP uses file-based routing.
 
-- **Native PHP application model**: Build with PHP-first conventions instead of shifting your app architecture around JavaScript tooling.
-- **PulsePoint reactivity**: Use browser-resident state and reactive UI patterns directly in your pages.
-- **Prisma ORM**: Query your database with a type-safe developer experience.
-- **PHPX UI approach**: Build reusable components with HTML-like syntax and server-rendered ergonomics.
-- **Routing and file conventions**: Follow Next.js-style routing concepts adapted for Prisma PHP.
-
-This combination lets you keep your backend and frontend closer together, with less transformation and less glue code between server data and interactive UI.
-
-## Routing and application structure
-
-Prisma PHP includes a documented routing system with dedicated pages for:
-
-- Routing Fundamentals
-- Defining Routes
-- Pages and Layouts
-- Redirects
-- Route Groups
-- Private Folders
-- Dynamic Routes
-- Middleware
-
-It also defines file conventions such as:
+Important files include:
 
 - `index.php`
 - `layout.php`
@@ -183,61 +139,19 @@ Routes are created from the `src/app` folder structure and route files. AI agent
 
 If you are changing route behavior or navigation patterns, read the routing documentation first.
 
-## Data, ORM, and reactivity
+## Data and reactivity
 
 One of Prisma PHP’s core ideas is keeping data flow simple across the stack:
 
-- query data with Prisma ORM in PHP
-- render full-stack UI directly from route files
-- use PulsePoint for frontend reactivity
-- use `pp.fetchFunction(...)` for reactive frontend-to-server calls
-- expose callable PHP functions with `#[Exposed]`
+- Query data with Prisma ORM in PHP
+- Render full-stack UI directly from route files
+- Use PulsePoint for frontend reactivity
+- Use `pp.fetchFunction(...)` for reactive frontend-to-server calls
+- Expose callable PHP functions with `#[Exposed]`
+- Validate incoming request data with `PP\Validator`
 
 This makes it easier to build interactive applications without maintaining separate DTO layers, excessive transformation code, or client-heavy hydration logic.
 
-When a task specifically involves PulsePoint runtime behavior such as `pp.state`, `pp.effect`, `pp.ref`, `pp-for`, `pp-spread`, or `pp-ref`, read `pulsepoint.md` before generating code.
-
-When a task involves Prisma ORM setup or schema changes, read `prisma-php-orm.md` first. That document should be the source of truth for:
-
-- confirming whether the project is using SQLite, MySQL, PostgreSQL, or another configured provider
-- reading `.env` and validating `DATABASE_URL` before making ORM setup assumptions
-- resolving the correct database setup path for the configured provider
-- understanding when to run `npx prisma migrate dev`
-- understanding when to run `npx ppo generate`
-- avoiding the mistake of treating generated PHP classes as proof that the database is already initialized
-- avoiding the mistake of treating project update commands as ORM sync commands
-
-When a task involves frontend interaction that needs server data or mutations, prefer the documented Prisma PHP pattern of PulsePoint reactive state plus `pp.fetchFunction(...)` before inventing custom endpoint flows.
-
-## Pre-requisite knowledge
-
-Our documentation assumes some familiarity with web development. Before getting started, it helps if you are comfortable with:
-
-- PHP
-- HTML
-- CSS
-- JavaScript
-- Databases and basic ORM concepts
-
-Familiarity with reactive UI concepts is also useful when working with PulsePoint-powered interfaces.
-
-## Documentation philosophy
-
-Prisma PHP evolves quickly, and framework behavior may differ across versions.
-
-If you are an AI coding agent or working with generated code:
-
-- do not rely on assumptions from other PHP frameworks
-- do not assume Laravel, Symfony, or Next.js behavior maps directly
-- do not guess file conventions, routing behavior, or Prisma workflow
-- always read the relevant local documentation for the installed version before making changes
-- always read `pulsepoint.md` before generating PulsePoint-specific reactive UI code
-- always read `prisma-php-orm.md` before making database-provider, `.env`, migration, or ORM generation decisions
-- always follow Prisma PHP XML-style syntax rules when generating PHPX or template markup
-- never manually maintain framework-generated route listing files such as `files-list.json`
-
-The installed documentation should be treated as the source of truth.
-
-## Join the community
+When Prisma ORM data is loaded in `index.php`, treat normal query results as the model-shaped objects returned by the generated Prisma PHP classes that follow `prisma/schema.prisma`.
 
-If you want to explore Prisma PHP further, start with the official documentation, check the GitHub repository, and follow the broader ecosystem around PulsePoint, PHPX UI, and related tooling.
+Do not introduce defensive serializer layers by default just to make normal ORM results usable. Use `PP\Validator` for incoming payload validation, sanitization, casting, and rule-based checks. Only add a presentation mapper when you intentionally need a client-facing shape, such as flattening included relations, hiding sensitive fields, or formatting values for display.

package/dist/docs/{01-getting-started/layouts-and-pages.md → layouts-and-pages.md}

@@ -1,9 +1,9 @@
 ---
 title: Layouts and Pages
-description: Learn how to create your first pages and layouts in Prisma PHP, and structure routes using the framework's file conventions.
+description: Learn how to create your first pages and layouts in Prisma PHP, structure routes with the framework's file conventions, and keep PulsePoint-aware route files predictable.
 related:
   title: API Reference
-  description: Learn more about the features mentioned in this page by reading the Prisma PHP routing documentation.
+  description: Learn more about the features mentioned in this page by reading the Prisma PHP routing and PulsePoint documentation.
   links:
     - /docs/pages-and-layouts
     - /docs/defining-routes
@@ -11,6 +11,7 @@ related:
     - /docs/private-folders
     - /docs/dynamic-route
     - /docs/index-php
+    - /docs/pulsepoint
     - /docs/route-php
 ---
 
@@ -28,7 +29,7 @@ When adding a page or nested route, create the correct folder and add the proper
 
 Prisma PHP has two important route entry files, and they serve different purposes.
 
-- `index.php` is the **UI entry point** for a route. Use it when the route should render HTML or a normal full-stack page.
+- `index.php` is the **UI entry point** for a route. Use it when the route should render HTML or a normal full-stack page. In full-stack projects, this is also the default home for route-local PulsePoint-driven interactivity.
 - `route.php` is the **direct handler entry point** for a route. Use it when the route should behave like an API endpoint, JSON endpoint, AJAX handler, form-processing endpoint, or other no-view server handler.
 
 A helpful project-level rule comes from `prisma-php.json`:
@@ -44,7 +45,56 @@ For the example project configuration below, `backendOnly` is `false`, so the de
 }
 ```
 
-If the user asks for a **route or page**, prefer `index.php`. If the user asks for an **API route**, direct handler, JSON endpoint, webhook, or AJAX route, prefer `route.php`.
+If the user asks for a **route or page**, prefer `index.php`. If the user asks for an **API route**, direct handler, JSON endpoint, webhook, or AJAX route, prefer `route.php`. Do not default to a PHP-only interaction style for normal page behavior when PulsePoint inside `index.php` is the better fit.
+
+## PulsePoint-aware file structure for `index.php` and `layout.php`
+
+For normal interactive full-stack routes, the default Prisma PHP mental model should be:
+
+1. page UI in `index.php`
+2. browser-side state in PulsePoint
+3. route-local server calls through `pp.fetchFunction(...)`
+4. backend validation through `PP\Validator`
+
+Only shift to a more PHP-only pattern when the user explicitly asks for it or when the route is intentionally non-reactive.
+
+When `index.php` or `layout.php` includes PulsePoint, keep the file in this order:
+
+1. PHP
+2. HTML
+3. SCRIPT
+
+In practice, that means:
+
+- put imports, server-side queries, request access, helper functions, and exposed PHP functions in the top PHP block
+- render the route markup after the PHP block
+- place one PulsePoint `<script>` block at the bottom of the file
+
+For the HTML portion, keep a **single parent HTML tag** around the route content, similar to React's single-root component rule.
+
+- In `index.php`, wrap the page UI in one parent element such as `<main>`, `<section>`, or `<article>`.
+- In nested `layout.php`, wrap the shared layout UI and `<?= MainLayout::$children; ?>` in one parent element.
+- The root `layout.php` is the document shell and is the only layout that should contain `<html>` and `<body>`. Inside `<body>`, keep one clear wrapper around `<?= MainLayout::$children; ?>` when PulsePoint behavior is present.
+
+Example PulsePoint page structure:
+
+```php filename="src/app/dashboard/index.php"
+<?php
+
+$title = 'Dashboard';
+?>
+<section class="dashboard-page">
+        <h1><?= htmlspecialchars($title); ?></h1>
+        <p>Count: {count}</p>
+        <button onclick="setCount(count + 1)">Increment</button>
+</section>
+
+<script>
+    const [count, setCount] = pp.state(0);
+</script>
+```
+
+This order keeps server logic, rendered markup, and client reactivity easy to scan for both humans and AI tools.
 
 ## Creating a page
 
@@ -88,6 +138,7 @@ For example, to create a root layout:
 ```
 
 The root layout is defined at the top level of your app directory and wraps the content for the entire application.
+If this root layout uses PulsePoint, keep the same file order: PHP first, then the document HTML, then a single `<script>` block near the end of `<body>`.
 
 ## Creating a nested route
 
@@ -159,6 +210,7 @@ src/app/
 ```
 
 If you combine both layouts, the root layout wraps the blog layout, and the blog layout wraps both `src/app/blog/index.php` and `src/app/blog/[slug]/index.php`.
+Nested layouts should behave like single-root route views: one parent element should wrap the shared layout UI and `MainLayout::$children;`.
 
 ## Creating a dynamic segment
 
@@ -283,6 +335,8 @@ echo json_encode([
 - If a user asks for an API route or direct handler, prefer `route.php`.
 - The root layout is required and should contain the global HTML document structure.
 - Only the root layout should contain `<html>` and `<body>` tags.
+- When `index.php` or `layout.php` uses PulsePoint, structure the file as PHP, then HTML, then one `<script>` block.
+- `index.php` and nested `layout.php` should render one parent HTML element; only the root layout should contain `<html>` and `<body>`.
 - Layouts can be nested by placing `layout.php` files inside route folders.
 - Dynamic route parameters are available through `Request::$dynamicParams`.
 - Route groups let you organize routes and assign different layouts without affecting the URL.

package/dist/docs/{01-getting-started/prisma-php-orm.md → prisma-php-orm.md}

@@ -39,6 +39,7 @@ vendor/tsnc/prisma-php/src/Validator.php
 ```
 
 `Validator` is the server-side validation layer for user input. It is not the ORM result layer.
+For the full local validation contract, helper overview, and rule patterns, read `validator.md`.
 
 Use this split:
 

package/dist/docs/{01-getting-started/project-structure.md → project-structure.md}

@@ -59,13 +59,22 @@ If an AI agent is working on the project, it should inspect `prisma-php.json` be
 
 One of the most important capability flags is `backendOnly`.
 
-- When `backendOnly` is `false`, the project is a **full-stack Prisma PHP app**. In that mode, normal route UI should be implemented with `index.php`.
+- When `backendOnly` is `false`, the project is a **full-stack Prisma PHP app**. In that mode, normal route UI should be implemented with `index.php`, and interactive page behavior should usually be implemented with PulsePoint plus `pp.fetchFunction(...)`.
 - When `backendOnly` is `true`, the project is a **backend-only Prisma PHP app**. In that mode, route behavior will usually center on direct handlers such as `route.php`.
-- If a `route.php` file exists at a route segment, it acts as the direct handler entry point for that route and should be treated as the API-style or no-view path for that segment.
+- If a `route.php` file exists at a route segment, it acts as the direct handler entry point for that route and should be treated as the API-style or no-view path for that segment, not as the default destination for ordinary route-local interactivity.
 - In full-stack projects, if the user asks for a normal route or page, prefer `index.php`. If the user asks for an API route, JSON endpoint, form-processing endpoint, AJAX endpoint, or direct handler, prefer `route.php`.
 
 This helps AI and contributors choose the correct file without guessing based on other frameworks.
 
+For AI-assisted generation, the default full-stack route pattern should be:
+
+1. render page UI in `index.php`
+2. keep browser interactivity in PulsePoint
+3. use `pp.fetchFunction(...)` for frontend-to-PHP calls that belong to the page
+4. use `route.php` only when the behavior must exist as a standalone handler or API-style endpoint
+
+Only prefer a more PHP-only interaction pattern when the user explicitly asks for it.
+
 ### Framework-managed generated files
 
 Some files in a Prisma PHP project are framework-managed and should not be manually maintained as part of normal route work.

package/dist/docs/{01-getting-started/pulsepoint.md → pulsepoint.md}

@@ -42,9 +42,13 @@ When PulsePoint is used inside a Prisma PHP application, the default full-stack
 - `#[Exposed]` on PHP functions or methods that the frontend should be allowed to call
 - `PP\Validator` on the PHP side for authoritative input validation and normalization
 
-Do not invent parallel client/server patterns when the built-in Prisma PHP RPC flow already fits the task. In typical Prisma PHP page work, prefer PulsePoint plus `pp.fetchFunction(...)` over ad hoc API wiring.
+For normal interactive Prisma PHP page work, AI should treat this as the **default implementation path**, not as an optional enhancement. Choose a more PHP-only interaction style only when the user explicitly asks for it or when the route is intentionally non-reactive.
 
-Use `route.php` only when you explicitly need a standalone endpoint such as a webhook, public JSON route, external integration endpoint, or other no-view handler.
+Do not invent parallel client/server patterns when the built-in Prisma PHP RPC flow already fits the task. In typical Prisma PHP page work, prefer PulsePoint plus `pp.fetchFunction(...)` over ad hoc API wiring, manual JSON fetch boilerplate, or PHP-only interaction patterns that the user did not request.
+
+If the PulsePoint code lives inside Prisma PHP `index.php` or `layout.php`, also follow the route-file structure rules from `layouts-and-pages.md`: PHP first, HTML second, one `<script>` block last, and a single parent HTML element for normal route content.
+
+Use `route.php` only when you explicitly need a standalone endpoint such as a webhook, public JSON route, external integration endpoint, or other no-view handler. Do not move normal route-local interactivity into `route.php` by default.
 
 ## Validation boundary
 
@@ -139,7 +143,9 @@ If any assumption conflicts with the official PulsePoint docs, follow the PulseP
 
 ## File layout rules
 
-For PulsePoint runtime code, keep a predictable layout:
+For PulsePoint runtime code, keep a predictable layout.
+
+### Standalone runtime snippet order
 
 1. HTML markup first
 2. One `<script>` block at the bottom
@@ -161,10 +167,43 @@ Example:
 </script>
 ```
 
+### Prisma PHP route file order
+
+When PulsePoint is used inside Prisma PHP `index.php` or `layout.php` files, keep this order:
+
+1. PHP
+2. HTML
+3. SCRIPT
+
+Example:
+
+```php filename="src/app/dashboard/index.php"
+<?php
+
+$title = "Dashboard";
+?>
+<section class="dashboard-page">
+  <h1><?= htmlspecialchars($title); ?></h1>
+  <p>Count: {count}</p>
+  <button onclick="setCount(count + 1)">Increment</button>
+</section>
+
+<script>
+  const [count, setCount] = pp.state(0);
+</script>
+```
+
+Additional Prisma PHP route rules:
+
+- `index.php` and nested `layout.php` should render a single parent HTML element.
+- Treat them like single-root route views; do not emit multiple sibling root nodes for normal PulsePoint pages.
+- The root `layout.php` is the only file that should define `<html>`, `<head>`, and `<body>`.
+- When the root layout uses PulsePoint, keep the script block near the end of `<body>` and keep `MainLayout::$children;` inside one clear wrapper element.
+
 Rules:
 
-- Use **exactly one** `<script>` block per page or component unless the project explicitly requires something else.
-- Place the script block **after** the markup.
+- Use **exactly one** `<script>` block per page, layout, or component unless the project explicitly requires something else.
+- Place the script block **after** the markup. In Prisma PHP route files, that means after the HTML section.
 - JavaScript should only reference data that already exists when the script runs.
 - Do not scatter PulsePoint runtime logic across multiple disconnected script blocks unless the docs or project structure explicitly requires it.
 
@@ -410,6 +449,7 @@ When a user asks for PulsePoint code, the AI should:
 3. Separate frontend PulsePoint behavior from backend implementation details.
 4. Avoid claiming a PulsePoint feature exists unless the docs support it.
 5. Prefer working examples that are ready to paste into a project.
+6. If the code lives in `index.php` or `layout.php`, use PHP, then HTML, then one `<script>` block, and keep a single parent HTML element for route content.
 
 A good PulsePoint answer should feel:
 

package/dist/docs/{01-getting-started/route-handlers.md → route-handlers.md}

@@ -7,6 +7,7 @@ related:
   description: Learn more about route handlers in Prisma PHP.
   links:
     - /docs/route-php
+    - /docs/php-validator
     - /docs/index-php
     - /docs/pages-and-layouts
 ---
@@ -109,6 +110,7 @@ A good handler pattern is:
 5. return structured JSON for expected validation failures
 
 This keeps the handler consistent whether the request came from a form, a `fetch()` call, or another client.
+For the full local validation guidance, read `validator.md` alongside this page.
 
 ## Request Helper
 

package/dist/docs/validator.md

@@ -0,0 +1,293 @@
+---
+title: Validator
+description: Learn how Prisma PHP validation works so AI agents can sanitize, cast, and validate request data with PP\Validator and the documented Rule workflow instead of inventing custom validation patterns.
+related:
+  title: Related docs
+  description: Read the official Prisma PHP Validator docs before generating or editing validation code.
+  links:
+    - /docs/php-validator
+    - /docs/fetch-function
+    - /docs/route-php
+    - /docs/error-handler
+---
+
+Prisma PHP validation should follow the documented `PP\Validator` model, not assumptions copied from Laravel FormRequest, Symfony Validator, Joi, Yup, Zod, or ad hoc request-wrapper patterns.
+
+If a task involves sanitization, casting, validation rules, `Rule`, `Validator::withRules(...)`, request normalization, or expected validation failures, AI agents should read the relevant Prisma PHP Validator docs first and keep the implementation aligned with the installed Prisma PHP version.
+
+## AI rule: read the Validator docs first
+
+Before generating, editing, or reviewing validation code, use this order:
+
+1. Read `./prisma-php.json`.
+2. Read the installed local docs in `node_modules/prisma-php/dist/docs`.
+3. Read this `validator.md` file.
+4. Inspect the current `index.php`, `layout.php`, exposed function, or `route.php` that receives the data.
+5. Inspect the payload shape and expected response contract.
+6. Inspect Prisma PHP core internals only when the docs do not answer the task.
+
+Do not assume another framework's validation lifecycle applies directly.
+
+## Read this doc when you need
+
+- **sanitization, casting, normalization, `PP\Validator`, `Rule`, or `Validator::withRules(...)`** → `validator.md`
+- **interactive validation with `pp.fetchFunction(...)` inside page routes** → `fetching-data.md` plus `validator.md`
+- **request validation in `route.php`** → `route-handlers.md` plus `validator.md`
+- **expected validation failures and response shaping** → `error-handling.md` plus `validator.md`
+- **credentials, registration, login, or auth form validation** → `authentication.md` plus `validator.md`
+- **rename fields, labels, or other non-file request values in upload flows** → `file-manager.md` plus `validator.md`
+
+## Core validation model AI should follow
+
+The official Prisma PHP Validator docs describe `PP\Validator` as the central server-side validation layer.
+
+Use this split:
+
+- use **PulsePoint** or browser-side logic for local UX only
+- use **`PP\Validator`** on the PHP side for authoritative sanitization, casting, and validation
+- use **`PP\Rule`** when business constraints must be checked declaratively
+- return structured failures for expected validation problems instead of treating them like crashes
+
+`Validator` is not the ORM result layer, not a frontend schema runtime, and not a replacement for route or function structure.
+
+## Exact core file location
+
+The Prisma PHP core `Validator` class lives here:
+
+```txt
+vendor/tsnc/prisma-php/src/Validator.php
+```
+
+When AI needs to inspect framework internals because the docs do not fully answer a validation task, this is the exact core file to review.
+
+## Identity and string helpers
+
+The official docs describe these common helpers:
+
+- `string($value, bool $escapeHtml = true): string`
+- `email($value): ?string`
+- `url($value): ?string`
+- `ip($value): ?string`
+- `uuid($value): ?string`
+- `ulid($value): ?string`
+- `cuid($value): ?string`
+- `cuid2($value): ?string`
+- `emojis(string $content): string`
+
+Use these helpers when the goal is to normalize or validate a single incoming value before applying additional rules.
+
+## Number and utility helpers
+
+The official docs also describe:
+
+- `int($value): ?int`
+- `float($value): ?float`
+- `bigInt($value): ?BigInteger`
+- `decimal($value, int $scale = 30): ?BigDecimal`
+- `bytes($value): ?string`
+- `boolean($value): ?bool`
+- `json($value): string`
+- `enum($value, array $allowed): bool`
+- `enumClass($value, string $class)`
+- `date($value, string $format = "Y-m-d"): ?string`
+- `dateTime($value, string $format = "Y-m-d H:i:s"): ?string`
+
+Important behavior to remember:
+
+- many helper methods return `null` when the value is invalid
+- `enum(...)` checks membership against a simple allowed array
+- `json(...)` accepts JSON strings or safely encodes arrays
+- `boolean(...)` performs smart casting for values such as `"true"`, `"1"`, `"on"`, and `"yes"`
+
+## Rule-based validation
+
+The main rule-based entry point is:
+
+```php
+Validator::withRules($value, string|Rule|array $rules, $confirm = null)
+```
+
+Return contract:
+
+- `true` when all rules pass
+- `string` when the first rule fails
+
+Always use a strict success check:
+
+```php
+if ($result === true) {
+    // valid
+}
+```
+
+## Recommended rule syntax
+
+The official docs support three rule styles.
+
+### 1. Rule builder, recommended
+
+This is the preferred style for most application code because it is easier to discover, safer to refactor, and clearer in reviews.
+
+```php
+use PP\Rule;
+
+$rules = Rule::required()
+    ->min(3)
+    ->max(50)
+    ->startsWith('J');
+```
+
+### 2. Pipe string syntax
+
+Useful for small inline rules or dynamic rules loaded from config.
+
+```php
+$rules = 'required|min:3|max:50';
+```
+
+### 3. Array syntax
+
+Useful when rules need to be appended conditionally.
+
+```php
+$rules = ['required', 'min:8'];
+$rules[] = 'confirmed';
+```
+
+## Common documented rules
+
+The official docs list rules such as:
+
+- `required`
+- `min:n`
+- `max:n`
+- `size:n`
+- `between:min,max`
+- `email`
+- `url`
+- `ip`
+- `uuid`
+- `ulid`
+- `cuid`
+- `int`
+- `float`
+- `boolean`
+- `startsWith:value`
+- `endsWith:value`
+- `confirmed`
+- `in:a,b,c`
+- `notIn:a,b,c`
+- `date:format`
+- `dateFormat:format`
+- `before:date`
+- `after:date`
+- `json`
+- `timezone`
+- `regex:pattern`
+- `digits:n`
+- `digitsBetween:min,max`
+- `extensions:jpg,png`
+- `mimes:image/jpeg,image/png`
+- `file`
+
+AI should not invent undocumented rule names when these already cover the common Prisma PHP validation workflow.
+
+## Recommended example patterns
+
+### Basic casting and validation
+
+```php
+<?php
+
+use PP\Validator;
+
+$name = Validator::string($_POST['name'] ?? '');
+$age = Validator::int($_POST['age'] ?? null);
+$email = Validator::email($_POST['email'] ?? '');
+
+if ($email === null) {
+    return [
+        'success' => false,
+        'errors' => [
+            'email' => 'A valid email address is required.',
+        ],
+    ];
+}
+```
+
+### Rule builder, recommended
+
+```php
+<?php
+
+use PP\Rule;
+use PP\Validator;
+
+$username = Validator::string($_POST['username'] ?? '');
+
+$result = Validator::withRules(
+    $username,
+    Rule::required()->min(3)->max(50)
+);
+
+if ($result !== true) {
+    return [
+        'success' => false,
+        'errors' => [
+            'username' => $result,
+        ],
+    ];
+}
+```
+
+### Confirmation rule
+
+```php
+<?php
+
+use PP\Validator;
+
+$password = Validator::string($_POST['password'] ?? '', false);
+$confirm = Validator::string($_POST['password_confirmation'] ?? '', false);
+
+$result = Validator::withRules($password, ['required', 'min:8', 'confirmed'], $confirm);
+```
+
+## Operational notes
+
+- use `=== true` when checking `Validator::withRules(...)`
+- use the third parameter for `confirmed` comparisons
+- pass full regex patterns with delimiters when using `regex`
+- use array syntax when rules depend on runtime conditions
+- apply validation before database writes, auth state changes, uploads, or other side effects
+
+## Validation boundary
+
+Keep these concerns separate:
+
+- use **browser-side checks** for immediate feedback only
+- use **`PP\Validator`** for authoritative backend validation
+- use **`error-handling.md`** patterns for expected validation failures
+- use **`fetching-data.md`** or **`route-handlers.md`** based on where the request enters PHP
+
+Do not treat browser validation, HTML attributes, or frontend checks as the final source of truth.
+
+## AI rules for validation work
+
+- read the official Validator docs before generating validation code
+- do not guess validation APIs from Laravel, Symfony, Joi, Yup, Zod, or other ecosystems
+- prefer `PP\Validator` for sanitization, casting, and helper-based validation
+- prefer the `Rule` builder for most rule-based validation
+- do not assume `Validator::withRules(...)` throws exceptions for normal failures
+- return structured validation results for expected user-input errors
+- inspect `vendor/tsnc/prisma-php/src/Validator.php` only when the docs and current code are not enough
+
+## Suggested file name
+
+Use this file name:
+
+```txt
+validator.md
+```
+
+It is clear, consistent with the existing local docs set, and easy for AI agents to discover alongside files such as `authentication.md`, `file-manager.md`, and `route-handlers.md`.

package/package.json

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

package/dist/docs/01-getting-started/index.md

@@ -1,142 +0,0 @@
----
-title: Prisma PHP Docs
-description: Welcome to the Prisma PHP Documentation.
-related:
-  title: Next Steps
-  description: Create your first Prisma PHP application and learn the core framework features.
-  links:
-    - /docs/get-started
----
-
-{/_ AI agent hint: Prisma PHP uses local installed docs as the source of truth for the active project version. Before generating framework-specific code, read `prisma-php.json` first, then read the relevant docs from `node_modules/prisma-php/dist/docs`. For authentication, read `authentication.md` first, then verify the official auth docs: `auth-get-started`, `credentials`, and `state-manager-auth`. For file uploads, `multipart/form-data`, `$_FILES`, `PP\FileManager\UploadFile`, rename/delete flows, or file manager screens, read `file-manager.md` first, then verify the official File Manager docs: `get-started-file`. For ORM work, read `prisma-php-orm.md` before choosing schema, migration, or generation commands. For PulsePoint runtime behavior specifically, read `pulsepoint.md` before generating reactive UI code. For backend validation, sanitization, `Validator`, `Rule`, `pp.fetchFunction(...)` validation flows, or request validation in `route.php`, read `fetching-data.md`, `error-handling.md`, and `route-handlers.md`, then consult the official Validator docs. `PP\Validator` is a Prisma PHP core class located in `vendor/tsnc/prisma-php/src/Validator.php`. Route creation is file-based from `src/app`; Prisma PHP auto-generates route listings such as `files-list.json`, so AI agents must not create, edit, or maintain that file manually. _/}
-
-Welcome to the Prisma PHP documentation!
-
-## What is Prisma PHP?
-
-Prisma PHP is a full-stack PHP framework for building modern, reactive web applications.
-
-You use native PHP to build your application, Prisma ORM for type-safe data access, and PulsePoint to add reactive browser state without the usual API glue or hydration-heavy workflow.
-
-It is designed to give you a server-first development model with modern UI interactivity, reusable PHPX components, Next.js-style routing concepts adapted for Prisma PHP, and CLI tooling.
-
-Whether you're building an internal dashboard, a content-rich platform, or a custom product, Prisma PHP helps you move fast while keeping your stack cohesive and expressive.
-
-## AI quick start
-
-If you are using AI-assisted development, do not guess framework behavior from other ecosystems.
-
-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.
-
-### Read this doc when you need
-
-- **project setup or file placement** → `project-structure.md`
-- **pages, layouts, route creation, nested routes** → `layouts-and-pages.md`
-- **PHPX components, props, children, fragments, icons, buttons, accordions, or component composition** → `components.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`
-- **authentication strategy, `AuthConfig.php`, sign-in, sign-out, route privacy model, RBAC, credentials auth, social login, or auth state manager usage** → `authentication.md`
-- **`pp.fetchFunction(...)`, `#[Exposed]`, page data loading, interactive validation with `Validator`** → `fetching-data.md`
-- **cache behavior and `CacheHandler`** → `caching.md`
-- **ORM, `schema.prisma`, database provider, migrations, generated PHP classes, `prisma.config.ts`, `.env` `DATABASE_URL`, or Prisma CLI workflow** → `prisma-php-orm.md`
-- **error handling, `error.php`, `not-found.php`, expected validation errors** → `error-handling.md`
-- **metadata, title, description, favicon, icons** → `metadata-and-og-images.md`
-- **API-style endpoints, `route.php`, request validation with `Validator`** → `route-handlers.md`
-- **PulsePoint runtime APIs such as `pp.state`, `pp.effect`, `pp.ref`, `pp-for`, `pp-ref`, `pp-spread`** → `pulsepoint.md`
-- **updating the project or enabling features** → `upgrading.md`
-- **first-time project creation** → `installation.md`
-
-### Important AI rules
-
-- treat `node_modules/prisma-php/dist/docs` as the primary documentation source for the installed version
-- do not assume Laravel, Symfony, React, Vue, Alpine, Livewire, or Next.js behavior maps directly
-- do not guess routing, file conventions, request helpers, component APIs, reactive syntax, or auth behavior when local docs already define them
-- create routes by adding folders and route files under `src/app`
-- do not create, edit, or maintain `files-list.json`; Prisma PHP generates route listings automatically
-- when building interactive frontend behavior, prefer the documented PulsePoint pattern with browser-side reactive state and `pp.fetchFunction(...)` for server calls
-- 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 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
-- when building auth flows, protection rules, or login/register pages, read `authentication.md` first and keep the implementation aligned with Prisma PHP’s documented auth model
-
-## File Manager
-
-Prisma PHP includes a documented File Manager model for uploads and file operations based on standard PHP uploads plus `PP\FileManager\UploadFile`.
-
-Use `file-manager.md` as the local AI-awareness guide for:
-
-- upload forms with `multipart/form-data`
-- `$_FILES` handling
-- `PP\FileManager\UploadFile`
-- upload size and type restrictions
-- rename, replace, and delete flows
-- choosing between a rendered upload page and a direct upload handler
-- validating non-file request values with `PP\Validator`
-
-After reading `file-manager.md`, verify the matching official docs at:
-
-1. `get-started-file`
-2. `php-validator` when auxiliary request validation is needed
-3. `route-php` or `pages-and-layouts` depending on whether the task is a direct handler or a full-stack page
-
-## Authentication
-
-Prisma PHP includes a documented authentication model centered on sessions, route protection strategy, RBAC, and provider-based sign-in flows.
-
-Use `authentication.md` as the local AI-awareness guide for:
-
-- `AuthConfig.php`
-- public-default vs private-default route strategy
-- `Auth::signIn(...)`
-- `Auth::signOut(...)`
-- `refreshUserSession(...)`
-- route-level RBAC
-- function-level protection with `#[Exposed(allowedRoles: [...])]`
-- credential authentication
-- social authentication
-
-After reading `authentication.md`, verify the matching official docs in this order:
-
-1. `auth-get-started`
-2. `credentials`
-3. `state-manager-auth`
-
-## Routing and file conventions
-
-Prisma PHP uses file-based routing.
-
-Important files include:
-
-- `index.php`
-- `layout.php`
-- `loading.php`
-- `route.php`
-- `not-found.php`
-- `error.php`
-- metadata files and icons
-
-Routes are created from the `src/app` folder structure and route files. AI agents should not try to register routes manually in framework-generated route list files.
-
-If you are changing route behavior or navigation patterns, read the routing documentation first.
-
-## Data and reactivity
-
-One of Prisma PHP’s core ideas is keeping data flow simple across the stack:
-
-- Query data with Prisma ORM in PHP
-- Render full-stack UI directly from route files
-- Use PulsePoint for frontend reactivity
-- Use `pp.fetchFunction(...)` for reactive frontend-to-server calls
-- Expose callable PHP functions with `#[Exposed]`
-- Validate incoming request data with `PP\Validator`
-
-This makes it easier to build interactive applications without maintaining separate DTO layers, excessive transformation code, or client-heavy hydration logic.
-
-When Prisma ORM data is loaded in `index.php`, treat normal query results as the model-shaped objects returned by the generated Prisma PHP classes that follow `prisma/schema.prisma`.
-
-Do not introduce defensive serializer layers by default just to make normal ORM results usable. Use `PP\Validator` for incoming payload validation, sanitization, casting, and rule-based checks. Only add a presentation mapper when you intentionally need a client-facing shape, such as flattening included relations, hiding sensitive fields, or formatting values for display.