prisma-php 0.0.10 → 0.0.12

package/dist/docs/index.md

@@ -1,14 +1,18 @@
 ---
 title: Prisma PHP Docs
-description: Welcome to the Prisma PHP Documentation.
+description: Prisma PHP documentation with AI-aware routing to the right local docs before framework-specific code generation.
 related:
   title: Next Steps
   description: Create your first Prisma PHP application and learn the core framework features.
   links:
     - /docs/get-started
+    - /docs/commands
+    - /docs/get-started-ia
 ---
 
-{/_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 email sending, SMTP config, `.env` mail variables, `PP\PHPMailer\Mailer`, HTML or text bodies, recipients, reply-to, or attachments, read `email.md` first, then verify the official Email docs: `email-get-started`. For websocket support, Ratchet setup, `IoServer`, `HttpServer`, `WsServer`, `ConnectionManager`, connection lifecycle methods, browser `WebSocket`, or realtime UI flows, read `websocket.md` first, then verify the official websocket docs: `websocket-get-started` and `websocket-chat-app`. For MCP support, `#[McpTool]`, `#[Schema]`, `PhpMcp\Server\Server`, `StreamableHttpServerTransport`, or `src/Lib/MCP/mcp-server.php`, read `mcp.md` first, then verify the official MCP docs: `prisma-php-ai-mcp` and `ai-tools`. 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 normal PulsePoint-aware route files such as `index.php` and nested `layout.php`, keep PHP first, then one parent HTML element that acts as the route-view boundary; when PulsePoint logic is present, put `pp-component` on that root and keep the `<script>` as the last child inside it. For imported partial components rendered with `ImportComponent::render(...)`, keep exactly one root element and place any component-local `<script>` inside that root; Prisma PHP injects `pp-component` on the imported root automatically. Do not confuse the route-file pattern with the imported-partial pattern. 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._/}
+Use this page as the routing entry point for the local Prisma PHP docs. If a task involves choosing which Prisma PHP guide to read before generating framework-specific code, start here and then jump to the matching page in `node_modules/prisma-php/dist/docs`.
+
+Before generating framework-specific code, read `prisma-php.json` first, then the matching local docs page. For auth read `authentication.md`; for env read `env.md`; for uploads read `file-manager.md`; for email read `email.md`; for websocket read `websocket.md`; for MCP read `mcp.md`; for ORM read `prisma-php-orm.md`; for reactive UI read `pulsepoint.md`; for validation read `validator.md`; for data loading read `fetching-data.md`; and for route or layout structure read `layouts-and-pages.md`.
 
 Welcome to the Prisma PHP documentation!
 
@@ -26,6 +30,8 @@ Whether you're building an internal dashboard, a content-rich platform, or a cus
 
 If you are using AI-assisted development, do not guess framework behavior from other ecosystems.
 
+Every major page in `dist/docs` is intended to be AI-routable on its own. When a task clearly matches one of those pages, read that file before generating Prisma PHP code.
+
 Use this order:
 
 1. Read `./prisma-php.json` first.
@@ -110,9 +116,14 @@ Do not confuse the route-file pattern with the `ImportComponent` partial pattern
 ### Read this doc when you need
 
 - **project setup or file placement** → `project-structure.md`
+- **CLI project creation, starter kits, create-prisma-php-app flags, or project update commands** → `commands.md`
+- **backend-only Prisma PHP usage, API-first projects, `backendOnly`, CORS, separate frontend clients, or choosing `route.php` as the default route file** → `backend-only.md`
 - **pages, layouts, route creation, nested routes, or PulsePoint-aware `index.php` and `layout.php` structure** → `layouts-and-pages.md`
 - **PHPX components, props, children, fragments, icons, buttons, accordions, or component composition** → `components.md`
+- **frontend TypeScript tooling, the `typescript` flag, the `ts/` directory, `ts/main.ts`, npm packages, or registered browser helpers used from template expressions and PulsePoint scripts** → `typescript.md`
+- **environment variables, `.env`, `PP\Env`, `Env::get(...)`, `Env::string(...)`, `Env::bool(...)`, `Env::int(...)`, or runtime configuration** → `env.md`
 - **file uploads, `multipart/form-data`, `$_FILES`, `PP\FileManager\UploadFile`, rename/delete flows, file replacement, allowed file types, upload size rules, or file manager pages** → `file-manager.md`
+- **AI integration, provider SDKs, chat UIs, streamed assistant responses, or deciding between page-local AI features, websocket, and MCP** → `get-started-ia.md`
 - **SMTP setup, `.env` mail variables, `PP\PHPMailer\Mailer`, HTML email, text email, recipients, reply-to, CC, BCC, or attachments** → `email.md`
 - **Ratchet websocket setup, `IoServer`, `HttpServer`, `WsServer`, `ConnectionManager`, browser `WebSocket`, or realtime messaging** → `websocket.md`
 - **MCP server setup, `#[McpTool]`, `#[Schema]`, `PhpMcp\Server\Server`, `StreamableHttpServerTransport`, AI tool endpoints, or `src/Lib/MCP/mcp-server.php`** → `mcp.md`
@@ -124,6 +135,7 @@ Do not confuse the route-file pattern with the `ImportComponent` partial pattern
 - **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`
+- **Swagger or OpenAPI generation, `swaggerDocs`, `pphp-swagger.json`, `create-swagger-docs`, or `settings/prisma-schema-config.json`** → `swagger-docs.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`
@@ -135,7 +147,10 @@ Do not confuse the route-file pattern with the `ImportComponent` partial pattern
 - 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 the project is API-first or backend-only, read `backend-only.md`, inspect `backendOnly` in `prisma-php.json`, and default to `route.php` for normal route behavior
+- when reading runtime configuration, `.env`, or feature flags, read `env.md` first and prefer `PP\Env` typed helpers over repeated manual parsing
 - when building interactive frontend behavior, prefer the documented PulsePoint pattern with browser-side reactive state and `pp.fetchFunction(...)` for server calls; treat this as the default unless the user explicitly asks for a PHP-only interaction pattern
+- when the task involves frontend TypeScript tooling or registered browser helpers, read `typescript.md`, keep reusable module code in `ts/`, and call the registered globals from PulsePoint component scripts instead of placing `import` or `export` inside inline route scripts
 - when building PulsePoint inside `index.php` or `layout.php`, read `layouts-and-pages.md` together with `pulsepoint.md`, use one parent route root, put `pp-component` on that root, and keep the `<script>` inside it as the last child
 - when importing a PHP partial with `ImportComponent`, require exactly one root element and keep any partial-local `<script>` inside that root because Prisma PHP attaches serialized props and a stable `pp-component` attribute to that imported root
 - do not leave a PulsePoint `<script>` as a sibling outside the route root
@@ -143,11 +158,56 @@ Do not confuse the route-file pattern with the `ImportComponent` partial pattern
 - when building backend validation logic, read `validator.md` first, then use the route-specific docs for the request entry point
 - when using `pp.fetchFunction(...)`, expose the PHP function explicitly with `#[Exposed]`
 - when changing feature flags, update `prisma-php.json` first, then follow the documented update workflow
+- when the task involves OpenAPI or Swagger generation, read `swagger-docs.md`, inspect `swaggerDocs` in `prisma-php.json`, and keep the generated spec path and config file aligned with the Prisma PHP workflow
 - when building reusable PHPX components, read `components.md` first
 - when building file-upload flows, file listings, rename/delete actions, or a file manager screen, read `file-manager.md` first and keep the implementation aligned with Prisma PHP’s documented File Manager model
 - when building MCP tools or server integrations, read `mcp.md` first, inspect `prisma-php.json`, and keep the implementation aligned with Prisma PHP's documented `src/Lib/MCP` server and attribute-based discovery 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
 
+## AI Integration
+
+Prisma PHP supports both provider-backed AI features inside normal pages and agent-facing MCP tooling, but those are different workflows.
+
+For a normal chat UI, assistant panel, streamed summary, or other page-local AI feature, the default pattern is:
+
+- render the route with `index.php`
+- keep browser-side state in PulsePoint
+- call PHP with `pp.fetchFunction(...)`
+- expose callable PHP with `#[Exposed]`
+- validate payloads with `PP\Validator`
+- yield streamed chunks from PHP when incremental output is needed
+
+Use `get-started-ia.md` as the local AI guide for provider-backed chat, streaming, and the boundary between page-local AI, websocket, and MCP tooling.
+
+## TypeScript
+
+Prisma PHP can use a Vite-backed TypeScript workflow when the `typescript` feature flag is enabled in `prisma-php.json`.
+
+Use `typescript.md` as the local AI guide for:
+
+- enabling TypeScript in new or existing projects
+- organizing frontend modules in `ts/`
+- registering browser helpers in `ts/main.ts`
+- installing npm packages for frontend utilities
+- using registered helpers from template expressions and PulsePoint scripts while keeping inline component scripts as plain JavaScript
+
+## Env
+
+Prisma PHP includes a documented environment helper centered on `PP\Env`, which reads already-loaded runtime values and exposes typed accessors for strings, booleans, and integers.
+
+Use `env.md` as the local AI-awareness guide for:
+
+- `.env` and runtime configuration boundaries
+- `PP\Env`
+- `Env::get(...)`, `Env::string(...)`, `Env::bool(...)`, and `Env::int(...)`
+- app names, timezones, host and port settings, feature flags, and numeric limits
+- provider keys, SMTP settings, and other server-only configuration values
+
+After reading `env.md`, verify the matching official docs at:
+
+1. `env`
+2. `env-file` when the task is specifically about `.env` file contents or placement
+
 ## File Manager
 
 Prisma PHP includes a documented File Manager model for uploads and file operations based on standard PHP uploads plus `PP\FileManager\UploadFile`.

package/dist/docs/installation.md

@@ -1,10 +1,29 @@
 ---
 title: Installation
-description: Learn how to create a new Prisma PHP application with the `create-prisma-php-app` CLI and start building locally.
+description: Learn how to create a new Prisma PHP application so AI agents can use the first-time setup flow instead of existing-project update commands.
+related:
+  title: Related docs
+  description: Read the full command reference and the existing-project update workflow.
+  links:
+    - /docs/commands
+    - /docs/upgrading
 ---
 
 Create a new Prisma PHP app and run it locally.
 
+For the full create and update command reference, read `commands.md`.
+
+If a task involves first-time Prisma PHP app creation, starter project bootstrap, or local setup, AI agents should read this page first and keep new-project setup separate from existing-project update workflows.
+
+## AI rule: use installation only for first-time setup
+
+Before suggesting Prisma PHP installation steps, use this order:
+
+1. Use `create-prisma-php-app` only when the application does not exist yet.
+2. Read `commands.md` for feature flags, starter kits, and non-interactive creation options.
+3. Inspect the generated `prisma-php.json` after creation before generating feature-specific code.
+4. Use `upgrading.md` for existing projects instead of treating installation like an update workflow.
+
 ## Quick start
 
 1. Create a new Prisma PHP app.
@@ -12,7 +31,7 @@ Create a new Prisma PHP app and run it locally.
 3. Start the local development environment.
 
 ```bash package="npm"
-npx create-prisma-php-app@latest
+npx create-prisma-php-app@latest my-app
 cd my-app
 npm run dev
 ```

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

@@ -1,6 +1,6 @@
 ---
 title: Layouts and Pages
-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.
+description: Learn how AI agents should create pages and layouts in Prisma PHP, choose the correct route files, 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 and PulsePoint documentation.
@@ -17,6 +17,18 @@ related:
 
 Prisma PHP uses **file-system based routing**, meaning you can use folders and files to define routes. This page explains how to create pages and layouts, how to choose the correct route file, and how to keep PulsePoint-aware route files structurally consistent.
 
+If a task involves pages, layouts, route folders, dynamic routes, or choosing between `index.php` and `route.php`, AI agents should read this page first and keep route-file structure aligned with the installed Prisma PHP version.
+
+## AI rule: read the route docs first
+
+Before generating Prisma PHP route files, use this order:
+
+1. Read `prisma-php.json`.
+2. Decide whether the project is full-stack or backend-only.
+3. Use `index.php` for rendered pages, `route.php` for direct handlers, and `layout.php` for shared subtree UI.
+4. Keep PulsePoint-aware route files to one parent root element with the `<script>` inside it.
+5. Do not edit `files-list.json`; Prisma PHP derives route metadata from the route tree.
+
 ## Important route generation note
 
 In Prisma PHP, routes are created from folders and special files inside `src/app`.

package/dist/docs/mcp.md

@@ -5,6 +5,7 @@ related:
   title: Related docs
   description: Read the official Prisma PHP MCP docs before generating or editing MCP server code.
   links:
+    - /docs/env
     - /docs/prisma-php-ai-mcp
     - /docs/ai-tools
     - /docs/project-structure
@@ -33,6 +34,7 @@ Do not assume another framework's agent or tool abstractions apply directly.
 ## Read this doc when you need
 
 - **MCP server bootstrap, `PhpMcp\Server\Server`, `StreamableHttpServerTransport`, `MCP_HOST`, `MCP_PORT`, or endpoint URL construction** -> official `prisma-php-ai-mcp`
+- **typed environment access for `MCP_*` values or `.env` loading boundaries** -> `env.md` plus `mcp.md`
 - **authoring tool classes with `#[McpTool]` and typed input validation with `#[Schema]`** -> official `ai-tools` plus `mcp.md`
 - **where MCP files belong in a Prisma PHP project** -> `project-structure.md` plus `mcp.md`
 - **feature flags and scaffolding for MCP support** -> `upgrading.md` plus `mcp.md`
@@ -46,7 +48,7 @@ Prisma PHP documents MCP around a dedicated PHP server entry point that auto-dis
 That means AI should preserve this model by default:
 
 - a PHP server built with `PhpMcp\Server\Server`
-- server metadata from environment variables
+- server metadata from environment variables resolved through `PP\Env`
 - attribute-based discovery of tool classes annotated with `#[McpTool]`
 - `StreamableHttpServerTransport` for the HTTP endpoint
 - domain-specific tool classes under `src/Lib/MCP`
@@ -114,6 +116,7 @@ AI should preserve these settings:
 Behavior notes:
 
 - `.env` loading is optional and happens from `DOCUMENT_PATH/.env`
+- typed runtime reads happen through `PP\Env`, whose implementation lives in `vendor/tsnc/prisma-php/src/Env.php`
 - the path prefix is trimmed with `trim(..., '/')`, so the effective route becomes `/<prefix>`
 - the final endpoint URL resolves to `http://{host}:{port}/{prefix}`
 - enabling `MCP_JSON_RESPONSE` can help with browser-based debugging and the Inspector

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

@@ -1,6 +1,6 @@
 ---
 title: Metadata and Icons
-description: Learn how to manage page metadata and application icons in Prisma PHP.
+description: Learn how AI agents should manage page metadata and application icons in Prisma PHP with `MainLayout` and the documented icon file conventions.
 related:
   title: API Reference
   description: Learn more about metadata and icon file conventions in Prisma PHP.
@@ -15,13 +15,25 @@ This page explains how to manage metadata in Prisma PHP and how icon file conven
 
 For better SEO, treat `MainLayout::$title` and `MainLayout::$description` as the primary way to set page metadata. A local `$title` variable only affects rendered page content unless you also assign the document metadata through `MainLayout`.
 
-Prisma PHP’s metadata system is centered on the `MainLayout` class rather than Next.js exports like `metadata`, `generateMetadata`, or generated `opengraph-image.tsx`. The provided Prisma PHP docs describe dynamic page metadata and icon file conventions, but they do **not** document a dedicated Next.js-style generated Open Graph image pipeline on these pages. citeturn0view0turn1view0
+Prisma PHP’s metadata system is centered on the `MainLayout` class rather than Next.js exports like `metadata`, `generateMetadata`, or generated `opengraph-image.tsx`. The provided Prisma PHP docs describe dynamic page metadata and icon file conventions, but they do **not** document a dedicated Next.js-style generated Open Graph image pipeline on these pages.
+
+If a task involves page titles, descriptions, custom meta tags, favicon files, icon files, or SEO metadata, AI agents should read this page first and keep metadata aligned with `MainLayout` and the documented icon conventions.
+
+## AI rule: read the metadata docs first
+
+Before generating Prisma PHP metadata code, use this order:
+
+1. Use `MainLayout::$title` and `MainLayout::$description` for document metadata.
+2. Use `MainLayout::addCustomMetaData(...)` for extra meta tags.
+3. Keep visible headings separate from document metadata when the UI text needs to differ.
+4. Use the documented `favicon`, `icon`, and `apple-icon` file conventions instead of inventing generated metadata modules.
+5. Read `layouts-and-pages.md` when the task also changes route or layout structure.
 
 ## Metadata in Prisma PHP
 
 Prisma PHP lets you update metadata dynamically through the `MainLayout` class.
 
-The docs say this is used to manage head scripts, footer scripts, and custom metadata for each page. citeturn0view0
+Prisma PHP uses this to manage head scripts, footer scripts, and custom metadata for each page.
 
 ### Basic metadata example
 
@@ -40,7 +52,7 @@ In this model:
 
 - `MainLayout::$title` sets the page title
 - `MainLayout::$description` sets the page description
-- `MainLayout::addCustomMetaData(...)` adds additional metadata such as `author` or other `<meta>` values citeturn0view0
+- `MainLayout::addCustomMetaData(...)` adds additional metadata such as `author` or other `<meta>` values
 
 ## Heading text vs document metadata
 
@@ -84,11 +96,11 @@ MainLayout::$description = $productDescription;
 ?>
 ```
 
-This is the closest Prisma PHP equivalent to route-aware or dynamic metadata generation. citeturn0view0
+This is the closest Prisma PHP equivalent to route-aware or dynamic metadata generation.
 
 ## Important placement rule
 
-The Prisma PHP docs explicitly note that metadata should be set **at the top of the PHP file before any HTML output** so it can render correctly inside the document `<head>`. citeturn0view0
+The Prisma PHP docs explicitly note that metadata should be set **at the top of the PHP file before any HTML output** so it can render correctly inside the document `<head>`.
 
 That means this pattern is correct:
 
@@ -165,7 +177,7 @@ The docs also describe metadata-related layout hooks for scripts.
 You can inject scripts into the document head or footer with:
 
 - `MainLayout::addHeadScript(...)`
-- `MainLayout::addFooterScript(...)` citeturn0view0
+- `MainLayout::addFooterScript(...)`
 
 Example:
 
@@ -189,7 +201,7 @@ The docs say that `favicon`, `icon`, and `apple-icon` files let you define icons
 
 - browser tabs
 - phone home screens
-- search engine results citeturn1view0
+- search engine results
 
 ### Supported icon files
 
@@ -197,15 +209,15 @@ The provided Prisma PHP icon docs mention image-file based usage such as:
 
 - `.ico`
 - `.jpg`
-- `.png` citeturn1view0
+- `.png`
 
 ### Where to place them
 
-The docs say to place a `favicon`, `icon`, or `apple-icon` file within your `/app` directory, and specifically state that the favicon image must be located at the **top level** of `/app`. citeturn1view0
+The docs say to place a `favicon`, `icon`, or `apple-icon` file within your `/app` directory, and specifically state that the favicon image must be located at the **top level** of `/app`.
 
 ## `favicon.ico`
 
-For the favicon, the docs say to add a `favicon.ico` image file to the root `/app` route segment. They also note that the favicon link tag is already included in the `<head>` of `layout.php`, so the normal step is simply to replace the existing `favicon.ico` file with your own. citeturn1view0
+For the favicon, the docs say to add a `favicon.ico` image file to the root `/app` route segment. They also note that the favicon link tag is already included in the `<head>` of `layout.php`, so the normal step is simply to replace the existing `favicon.ico` file with your own.
 
 The documented link tag is:
 
@@ -213,11 +225,11 @@ The documented link tag is:
 <link rel="icon" href="<?= Request::baseUrl?>/favicon.ico" type="image/x-icon" sizes="16x16">
 ```
 
-This means Prisma PHP already expects the favicon in the standard project location and wires it into the layout automatically. citeturn1view0
+This means Prisma PHP already expects the favicon in the standard project location and wires it into the layout automatically.
 
 ## Automatic head integration
 
-The icon docs say Prisma PHP evaluates these icon files and **automatically adds the appropriate tags to your app’s `<head>` element**. citeturn1view0
+The icon docs say Prisma PHP evaluates these icon files and **automatically adds the appropriate tags to your app’s `<head>` element**.
 
 That is the Prisma PHP equivalent of file-convention-based icon metadata.
 
@@ -257,24 +269,24 @@ If you are coming from Next.js, the closest mapping is:
 | file-based icon conventions       | Prisma PHP `favicon`, `icon`, `apple-icon` file conventions                            |
 | generated OG image files          | not documented on the provided Prisma PHP metadata pages                               |
 
-The main difference is that Prisma PHP’s documented system is **layout-class driven** for metadata and **file-convention driven** for icons, rather than based on exported metadata objects or generated route modules. citeturn0view0turn1view0
+The main difference is that Prisma PHP’s documented system is **layout-class driven** for metadata and **file-convention driven** for icons, rather than based on exported metadata objects or generated route modules.
 
 ## About Open Graph images
 
 The Next.js page title includes OG images, but the provided Prisma PHP docs you linked focus on:
 
 - dynamic page metadata through `MainLayout`
-- icon file conventions such as `favicon`, `icon`, and `apple-icon` citeturn0view0turn1view0
+- icon file conventions such as `favicon`, `icon`, and `apple-icon`
 
 Because those pages do not document a dedicated Prisma PHP Open Graph image generation system, this page does **not** invent one. If your framework later adds a specific OG image convention, that would belong here.
 
 ## Good to know
 
-- Prisma PHP uses `MainLayout` for dynamic metadata management. citeturn0view0
+- Prisma PHP uses `MainLayout` for dynamic metadata management.
 - `MainLayout::$title` and `MainLayout::$description` are the main documented page metadata properties.
-- `MainLayout::addCustomMetaData(...)` adds custom metadata such as `author`. citeturn0view0
-- Metadata should be set before any HTML output. citeturn0view0
-- `MainLayout::addHeadScript(...)` and `MainLayout::addFooterScript(...)` can inject scripts into the page shell. citeturn0view0
-- Prisma PHP supports `favicon`, `icon`, and `apple-icon` file conventions. citeturn1view0
-- `favicon.ico` belongs at the top level of the app directory. citeturn1view0
-- Prisma PHP automatically adds the appropriate icon tags to the document head. citeturn1view0
+- `MainLayout::addCustomMetaData(...)` adds custom metadata such as `author`.
+- Metadata should be set before any HTML output.
+- `MainLayout::addHeadScript(...)` and `MainLayout::addFooterScript(...)` can inject scripts into the page shell.
+- Prisma PHP supports `favicon`, `icon`, and `apple-icon` file conventions.
+- `favicon.ico` belongs at the top level of the app directory.
+- Prisma PHP automatically adds the appropriate icon tags to the document head.

package/dist/docs/prisma-php-orm.md

@@ -1,6 +1,6 @@
 ---
 title: Prisma PHP ORM
-description: Learn how Prisma PHP ORM works, how to configure it, how to migrate your database, and how to generate the PHP ORM classes correctly.
+description: Learn how Prisma PHP ORM works so AI agents can choose the correct configuration, migration, and PHP class generation workflow.
 related:
   title: Related docs
   description: Read the official Prisma PHP ORM docs before generating code or running ORM commands.
@@ -15,6 +15,8 @@ Prisma PHP ORM gives Prisma PHP applications a schema-first, Prisma-style data l
 
 It uses your Prisma schema, Prisma migrations, and generated PHP classes so your application can query the database through the documented Prisma PHP API.
 
+If a task involves `schema.prisma`, migrations, generated Prisma PHP classes, `npx prisma ...`, or `npx ppo generate`, AI agents should read this page first and keep the workflow aligned with the installed Prisma PHP docs.
+
 ## ORM result shape rule
 
 Prisma PHP ORM query results should be treated as model-shaped objects returned by the generated Prisma PHP classes that follow `prisma/schema.prisma`.
@@ -75,7 +77,7 @@ Use this order:
 
 For Prisma PHP ORM tasks, AI should read:
 
-- `06-prisma-php-orm.md`
+- `prisma-php-orm.md`
 - the official Prisma PHP ORM docs for the installed version
 - `schema.prisma`
 - `prisma.config.ts`
@@ -196,24 +198,26 @@ Use this flow:
 6. when the user is using SQLite, prefer saving the database file inside the local `./prisma` directory
 7. for the normal local setup, use:
 
-```env
-DATABASE_URL="file:./prisma/dev.db"
-```
+  ```env
+  DATABASE_URL="file:./prisma/dev.db"
+  ```
 
-8. confirm the resolved path points to a valid project-local SQLite file such as `./prisma/dev.db`
-9. do not point the SQLite file at an unrelated root-level location when the project is using the standard Prisma PHP layout
-10. if the `./prisma` directory is the intended storage location, the SQLite database file should be created and saved there
-11. if the SQLite database file is missing, invalid, or not initialized yet, run:
+Then continue with these checks:
 
-```bash
-npx prisma migrate dev
-```
+- confirm the resolved path points to a valid project-local SQLite file such as `./prisma/dev.db`
+- do not point the SQLite file at an unrelated root-level location when the project is using the standard Prisma PHP layout
+- if the `./prisma` directory is the intended storage location, the SQLite database file should be created and saved there
+- if the SQLite database file is missing, invalid, or not initialized yet, run:
 
-12. after migration succeeds, run:
+  ```bash
+  npx prisma migrate dev
+  ```
 
-```bash
-npx ppo generate
-```
+- after migration succeeds, run:
+
+  ```bash
+  npx ppo generate
+  ```
 
 Important SQLite rule:
 

package/dist/docs/project-structure.md

@@ -1,11 +1,34 @@
 ---
 title: Project structure and organization
 nav_title: Project Structure
-description: Learn the folder and file conventions in Prisma PHP, and how to organize your project.
+description: Learn the folder and file conventions in Prisma PHP, including the installed docs path and project-root AGENTS.md, so AI agents can place features in the right files and folders.
+related:
+    title: Related docs
+    description: Use the routing, handler, component, and TypeScript docs once you know where a change belongs.
+    links:
+        - /docs/pages-and-layouts
+        - /docs/route-php
+        - /docs/import-component
+        - /docs/typescript
 ---
 
 This page provides an overview of the folder and file conventions in **Prisma PHP**, and recommendations for organizing your project. It follows the Prisma PHP routing model and mirrors the mental model of a Next.js App Router style project structure, adapted to how Prisma PHP actually works.
 
+If a task involves file placement, feature flags, route creation, or overall Prisma PHP app organization, AI agents should read this page first and use it as the directory-level source of truth before generating files.
+
+For AI-assisted work, treat `node_modules/prisma-php/dist/docs` as the installed Prisma PHP docs location for the active project version, and keep `AGENTS.md` in the project root aligned with that docs set.
+
+## AI rule: read the structure docs first
+
+Before generating Prisma PHP files or folders, use this order:
+
+1. Read `prisma-php.json`.
+2. Read the matching installed doc in `node_modules/prisma-php/dist/docs`.
+3. Read `AGENTS.md` for project-specific Prisma PHP rules.
+4. Decide whether the task belongs in `src/app`, `src/Lib`, `prisma`, `public`, `settings`, or the installed docs path.
+5. Create routes from the route tree instead of editing `files-list.json`.
+6. Use `layouts-and-pages.md`, `route-handlers.md`, or `components.md` once the file location is known.
+
 ## Folder and file conventions
 
 ### Top-level folders
@@ -16,10 +39,21 @@ Top-level folders are used to organize your application's source code, configura
 | ---------- | ----------------------------------------------------------------------------- |
 | `src/app`  | File-system based routing, pages, layouts, loading states, and route handlers |
 | `src/Lib`  | Application libraries, generated Prisma classes, auth, middleware, utilities  |
+| `ts`       | Frontend TypeScript modules and Vite entry files when `typescript` is enabled |
 | `public`   | Public web root, static files, CSS, JS, favicon, and public entry point       |
 | `prisma`   | Prisma schema, migrations, and seed scripts                                   |
 | `settings` | Project configuration such as paths, BrowserSync, and related setup           |
 
+### Installed framework docs
+
+Prisma PHP installs its framework docs inside `node_modules/prisma-php/dist/docs`.
+
+AI agents should treat that installed docs directory as the single source of truth for framework behavior in the active project version.
+
+| Path                                | Purpose                                                              |
+| ----------------------------------- | -------------------------------------------------------------------- |
+| `node_modules/prisma-php/dist/docs` | Installed Prisma PHP docs for the current project version and AI use |
+
 ### Top-level files
 
 These files are typically used to configure the app, manage dependencies, and define environment values.
@@ -29,6 +63,7 @@ These files are typically used to configure the app, manage dependencies, and de
 | `composer.json`        | PHP dependencies and autoloading                               |
 | `package.json`         | Frontend tooling and development scripts when used             |
 | `.env`                 | Environment variables                                          |
+| `AGENTS.md`            | Project-root AI guidance aligned with the installed docs set   |
 | `prisma/schema.prisma` | Main Prisma schema file                                        |
 | `public/index.php`     | Public entry point                                             |
 | `bootstrap.php`        | Application bootstrap and middleware registration when present |
@@ -55,6 +90,12 @@ Typical values include:
 
 If an AI agent is working on the project, it should inspect `prisma-php.json` before deciding whether Tailwind CSS, TypeScript, Prisma ORM, Swagger docs, MCP, or websocket-related code should be generated.
 
+For backend-only API projects, read `backend-only.md`.
+
+For Swagger and OpenAPI generation, read `swagger-docs.md`.
+
+For TypeScript frontend tooling, the root `ts/` directory, `ts/main.ts`, and npm-backed browser utilities, read `typescript.md`.
+
 ### Full-stack vs backend-only routing decision
 
 One of the most important capability flags is `backendOnly`.
@@ -222,6 +263,10 @@ Redirects are handled with `Request::redirect()`, which sends an HTTP `Location`
 
 ```txt
 prisma-php-project/
+├── node_modules/
+│   └── prisma-php/
+│       └── dist/
+│           └── docs/
 ├── prisma/
 │   ├── migrations/
 │   ├── schema.prisma
@@ -273,6 +318,7 @@ prisma-php-project/
 ├── composer.json
 ├── package.json
 ├── prisma-php.json
+├── AGENTS.md
 └── .env
 ```
 

package/dist/docs/pulsepoint.md

@@ -1,9 +1,22 @@
-# PulsePoint Runtime Guide
+---
+title: PulsePoint Runtime Guide
+description: Learn how AI agents should use the current PulsePoint runtime contract, component script rules, and supported directives in Prisma PHP.
+related:
+  title: Related docs
+  description: Read the route, component, data-fetching, and TypeScript docs alongside the PulsePoint runtime contract.
+  links:
+    - /docs/pages-and-layouts
+    - /docs/import-component
+    - /docs/fetch-function
+    - /docs/typescript
+---
 
 ## Purpose
 
 This file describes the PulsePoint runtime that is actually implemented in the current TypeScript source of this repo. Treat it as the working contract for AI-generated code.
 
+If a task involves `pp.state`, `pp.effect`, `pp-ref`, `pp-spread`, route-root scripts, imported partial runtime behavior, or current `pp-component` semantics, AI agents should read this page first and keep generated code aligned with the runtime implemented in this repo.
+
 Do not assume React, Vue, Svelte, JSX, or older PulsePoint docs.
 
 ## Runtime shape

package/dist/docs/route-handlers.md

@@ -1,7 +1,7 @@
 ---
 title: Route Handlers
 nav_title: Route Handlers
-description: Learn how to use route handlers in Prisma PHP with `route.php`.
+description: Learn how AI agents should use route handlers in Prisma PHP with `route.php` for API-style and no-view routes.
 related:
   title: API Reference
   description: Learn more about route handlers in Prisma PHP.
@@ -18,6 +18,18 @@ Route Handlers in Prisma PHP let you create custom request handlers for a given
 
 A `route.php` file bypasses the standard view rendering flow and acts as a direct entry point for a specific URL path. This makes it useful for APIs, form submissions, AJAX endpoints, JSON responses, and route-specific server logic.
 
+If a task involves API-style endpoints, JSON responses, form-processing handlers, webhooks, or machine-facing routes, AI agents should read this page first and keep `route.php` separate from normal page routes.
+
+## AI rule: read the route-handler docs first
+
+Before generating Prisma PHP `route.php` files, use this order:
+
+1. Read `prisma-php.json` and confirm whether the project is backend-only.
+2. Use `route.php` only for direct handler or no-view routes.
+3. Read from `Request::$params` and validate with `PP\Validator`.
+4. Return structured JSON or `Boom` responses for expected failures.
+5. Use `index.php` plus `pp.fetchFunction(...)` instead when the behavior belongs to a rendered page.
+
 ## `route.php` vs `index.php`
 
 Prisma PHP has a clear separation between page routes and direct handlers:
@@ -25,7 +37,7 @@ Prisma PHP has a clear separation between page routes and direct handlers:
 - `index.php` is the UI entry point for a route segment and should be used for rendered HTML routes.
 - `route.php` is the direct handler entry point for a route segment and should be used for API-style or no-view routes.
 
-The official `index.php` doc explicitly states that `index.php` is for rendering UI and that if you need to return JSON data, like an API, or handle form processing without a view, you should use `route.php` instead. The `route.php` doc describes it as bypassing standard view rendering to build APIs, handle form submissions, or manage complex logic. citeturn1view0turn0view0
+The official `index.php` doc explicitly states that `index.php` is for rendering UI and that if you need to return JSON data, like an API, or handle form processing without a view, you should use `route.php` instead. The `route.php` doc describes it as bypassing standard view rendering to build APIs, handle form submissions, or manage complex logic.
 
 In practice, that leads to this rule:
 
@@ -35,6 +47,10 @@ In practice, that leads to this rule:
 - if the user asks for an API route, use `route.php`
 - if the user asks for a normal page route, use `index.php`
 
+For project-level backend-only guidance, separate frontend consumption, and CORS setup, read `backend-only.md`.
+
+For Prisma PHP OpenAPI generation and Swagger workflow details, read `swagger-docs.md`.
+
 For the provided project config:
 
 ```json