prisma-php 0.0.10 → 0.0.11

package/dist/docs/get-started-ia.md

@@ -0,0 +1,480 @@
+---
+title: AI Integration
+description: Build chat, assistant, and streamed AI features in Prisma PHP with PulsePoint, pp.fetchFunction(...), PP\Validator, and MCP when you need agent-facing tools.
+related:
+  title: Related docs
+  description: Read the core Prisma PHP docs that support provider-backed AI UIs, streaming, and agent tooling.
+  links:
+    - /docs/env
+    - /docs/fetch-function
+    - /docs/php-validator
+    - /docs/pulsepoint
+    - /docs/prisma-php-ai-mcp
+    - /docs/websocket-chat-app
+---
+
+Prisma PHP is a good fit for AI features, but the right Prisma PHP pattern depends on what you are actually building.
+
+For a normal user-facing chat box, assistant panel, prompt form, streamed summary, or similar page-local AI feature, the recommended Prisma PHP approach is:
+
+1. render the UI in `index.php`
+2. keep browser-side interactivity in **PulsePoint**
+3. call backend PHP with **`pp.fetchFunction(...)`**
+4. mark callable PHP functions with **`#[Exposed]`**
+5. validate and normalize incoming data with **`PP\Validator`**
+6. stream incremental output by **yielding** from PHP when the provider supports streaming
+
+That keeps the **frontend reactive** while keeping the **AI call, validation, secrets, and business logic on the PHP side**.
+
+Do **not** default to `route.php` for page-local chat or assistant UI just because AI is involved. In Prisma PHP, `route.php` is still useful, but it is the better fit for standalone APIs, webhooks, third-party integrations, or endpoints that must exist independently of the current page.
+
+If the real goal is to expose **agent-callable tools** instead of a user chat interface, read `mcp.md` and the official `prisma-php-ai-mcp` docs. MCP is about serving tools to agents; it is not the default answer for a page-local chat box.
+
+## The default AI architecture in Prisma PHP
+
+When the user is building a normal AI feature inside a Prisma PHP app, AI should usually prefer this stack:
+
+1. `index.php` for the route UI
+2. PulsePoint for browser-side state
+3. `pp.fetchFunction(...)` for frontend-to-PHP RPC
+4. `#[Exposed]` for callable PHP functions
+5. `PP\Validator` for server-side validation
+6. streamed `yield` responses for incremental assistant output
+
+This is the right default for:
+
+- single-user chat pages
+- assistant sidebars
+- prompt forms
+- streamed summaries
+- content generation tools
+- classification or extraction actions
+- AI-backed search or suggestion panels
+- route-local progress logs
+
+Reserve `route.php` for cases where the endpoint must be called without the page, and reserve websocket-based transport for cases where you need true server push, multi-user realtime chat, or presence-style features.
+
+## Pick the right AI surface
+
+Prisma PHP has three different AI-related surfaces, and they should not be mixed up.
+
+### 1. User-facing AI in a page
+
+Use this when a human is interacting with a Prisma PHP page.
+
+Default stack:
+
+- `index.php`
+- PulsePoint
+- `pp.fetchFunction(...)`
+- `#[Exposed]`
+- `PP\Validator`
+
+This is the default for chat, prompt forms, streamed output, inline assistants, or route-local AI actions.
+
+### 2. Standalone AI endpoint
+
+Use `route.php` when the request should exist independently of the rendered page.
+
+Examples:
+
+- webhooks
+- provider callbacks
+- public JSON APIs
+- integration endpoints
+- non-UI automation calls
+
+### 3. Agent-facing tools
+
+Use MCP when an external agent should call business actions in your app.
+
+Read:
+
+- `mcp.md`
+- official `prisma-php-ai-mcp`
+- official `ai-tools`
+
+### Quick rule of thumb
+
+- user chat box on a page -> `index.php` + PulsePoint + `pp.fetchFunction(...)`
+- endpoint with no page dependency -> `route.php`
+- tools for agents -> MCP
+
+## Install an AI client
+
+Prisma PHP is intentionally unopinionated about AI providers. You can use OpenAI, Anthropic, Groq, or another PHP SDK that fits your application.
+
+For OpenAI-compatible providers, a common starting point is:
+
+```bash package="composer"
+composer require openai-php/client
+```
+
+Use the provider package that matches your model host, but keep the Prisma PHP architecture the same: the browser calls PHP, and PHP talks to the model provider.
+
+## Configure secrets in `.env`
+
+Keep provider secrets on the server side.
+
+Example:
+
+```dotenv
+OPENAI_API_KEY="sk-..."
+OPENAI_MODEL="gpt-4o-mini"
+```
+
+Do **not** push provider API keys into PulsePoint state or browser-side JavaScript.
+When reading these values in PHP, prefer `PP\Env` over raw `getenv()` so defaults and typed access stay consistent with Prisma PHP's env helper.
+
+## Recommended non-streaming chat pattern
+
+For a simple AI response, keep the entire route in `index.php`, expose one PHP function, validate the prompt on the PHP side, and call the provider there.
+
+```php filename="src/app/chat/index.php"
+<?php
+
+use PP\Attributes\Exposed;
+use PP\Env;
+use PP\MainLayout;
+use PP\Rule;
+use PP\Validator;
+
+MainLayout::$title = 'AI Chat';
+MainLayout::$description = 'Chat with a provider from Prisma PHP using PulsePoint and pp.fetchFunction(...).';
+
+#[Exposed]
+function sendChatMessage($data)
+{
+    $message = Validator::string($data->message ?? '');
+    $result = Validator::withRules(
+        $message,
+        Rule::required()->min(1)->max(4000)
+    );
+
+    if ($result !== true) {
+        return [
+            'success' => false,
+            'errors' => [
+                'message' => $result,
+            ],
+        ];
+    }
+
+    $client = \OpenAI::client(Env::string('OPENAI_API_KEY', ''));
+    $model = Env::string('OPENAI_MODEL', 'gpt-4o-mini');
+
+    $response = $client->chat()->create([
+        'model' => $model,
+        'messages' => [
+            ['role' => 'system', 'content' => 'You are a helpful Prisma PHP assistant.'],
+            ['role' => 'user', 'content' => $message],
+        ],
+    ]);
+
+    return [
+        'success' => true,
+        'errors' => [],
+        'assistant' => [
+            'role' => 'assistant',
+            'content' => trim($response->choices[0]->message->content ?? ''),
+        ],
+    ];
+}
+?>
+
+<section pp-component="chat-page">
+    <header>
+        <h1>AI Chat</h1>
+        <p>Send a prompt from PulsePoint and keep the provider call in PHP.</p>
+    </header>
+
+    <div>
+        <template pp-for="(item, index) in messages">
+            <article key="{`${item.role}-${index}`}">
+                <strong>{item.role}</strong>
+                <p>{item.content}</p>
+            </article>
+        </template>
+    </div>
+
+    <form onsubmit="event.preventDefault(); submitMessage()">
+        <textarea value="{draft}" oninput="setDraft(event.target.value)"></textarea>
+        <p hidden="{!error}">{error}</p>
+        <button type="submit" disabled="{loading}">Send</button>
+    </form>
+
+    <script>
+        const [draft, setDraft] = pp.state('');
+        const [messages, setMessages] = pp.state([]);
+        const [error, setError] = pp.state('');
+        const [loading, setLoading] = pp.state(false);
+
+        async function submitMessage() {
+            const text = draft.trim();
+
+            if (!text || loading) {
+                return;
+            }
+
+            setError('');
+            setDraft('');
+            setMessages((current) => [...current, { role: 'user', content: text }]);
+            setLoading(true);
+
+            try {
+                const response = await pp.fetchFunction('sendChatMessage', { message: text });
+
+                if (!response.success) {
+                    setError(response.errors?.message ?? 'Message failed.');
+                    return;
+                }
+
+                setMessages((current) => [...current, response.assistant]);
+            } catch (error) {
+                setError(error.message || 'Request failed.');
+            } finally {
+                setLoading(false);
+            }
+        }
+    </script>
+</section>
+```
+
+Why this pattern is preferred:
+
+- the route UI stays in `index.php`
+- PulsePoint owns the browser state
+- the provider call stays in PHP
+- secrets stay on the server
+- `Validator` remains the authoritative validation layer
+- the route avoids extra endpoint boilerplate when the action belongs to the page
+
+## Recommended streaming chat pattern
+
+For streamed assistant output, keep the same architecture and change only the backend response shape: make the exposed PHP function **yield** chunks.
+
+That gives you incremental SSE delivery through `pp.fetchFunction(...)` without hand-writing a separate transport layer for normal assistant output.
+
+```php filename="src/app/chat/index.php"
+<?php
+
+use PP\Attributes\Exposed;
+use PP\Env;
+use PP\Rule;
+use PP\Validator;
+
+#[Exposed]
+function streamChatMessage($data)
+{
+    $message = Validator::string($data->message ?? '');
+    $result = Validator::withRules(
+        $message,
+        Rule::required()->min(1)->max(4000)
+    );
+
+    if ($result !== true) {
+        yield [
+            'type' => 'error',
+            'message' => $result,
+        ];
+        return;
+    }
+
+    $client = \OpenAI::client(Env::string('OPENAI_API_KEY', ''));
+    $model = Env::string('OPENAI_MODEL', 'gpt-4o-mini');
+
+    $stream = $client->chat()->createStreamed([
+        'model' => $model,
+        'messages' => [
+            ['role' => 'system', 'content' => 'You are a helpful Prisma PHP assistant.'],
+            ['role' => 'user', 'content' => $message],
+        ],
+    ]);
+
+    foreach ($stream as $response) {
+        $delta = $response->choices[0]->delta->content ?? '';
+
+        if ($delta !== '') {
+            yield [
+                'type' => 'chunk',
+                'chunk' => $delta,
+            ];
+        }
+    }
+}
+```
+
+If your provider uses a different streaming API, keep the Prisma PHP shape the same:
+
+1. validate in PHP first
+2. start the provider stream in PHP
+3. loop over provider deltas
+4. yield strings or arrays back to the client
+
+### Client-side streaming with PulsePoint
+
+```html
+<script>
+    const [draft, setDraft] = pp.state('');
+    const [messages, setMessages] = pp.state([]);
+    const [error, setError] = pp.state('');
+    const [streaming, setStreaming] = pp.state(false);
+
+    async function sendStream() {
+        const text = draft.trim();
+
+        if (!text || streaming) {
+            return;
+        }
+
+        setError('');
+        setDraft('');
+        setStreaming(true);
+        setMessages((current) => [
+            ...current,
+            { role: 'user', content: text },
+            { role: 'assistant', content: '' },
+        ]);
+
+        try {
+            await pp.fetchFunction(
+                'streamChatMessage',
+                { message: text },
+                {
+                    onStream(data) {
+                        if (data.type === 'error') {
+                            setError(data.message || 'Invalid message.');
+                            return;
+                        }
+
+                        const delta = data.chunk || '';
+
+                        if (delta === '') {
+                            return;
+                        }
+
+                        setMessages((current) => {
+                            if (current.length === 0) {
+                                return current;
+                            }
+
+                            const next = current.slice();
+                            const last = next[next.length - 1];
+
+                            next[next.length - 1] = {
+                                ...last,
+                                content: `${last.content}${delta}`,
+                            };
+
+                            return next;
+                        });
+                    },
+                    onStreamError(error) {
+                        setError(error.message || 'Stream failed.');
+                    },
+                }
+            );
+        } finally {
+            setStreaming(false);
+        }
+    }
+</script>
+```
+
+Important streaming rule:
+
+- do not wait for one final JSON object to render the reply
+- update the UI from `onStream`
+- use `onStreamError` and `onStreamComplete` for stream lifecycle handling
+
+For the current SSE behavior and low-level streaming helpers, read `fetching-data.md`.
+
+## Validate everything on the PHP side
+
+When building AI features, do not trust browser-side checks as the final source of truth.
+
+Use this split:
+
+- PulsePoint for local UX state
+- `pp.fetchFunction(...)` for calling PHP
+- `PP\Validator` for sanitization and casting
+- `Validator::withRules(...)` for business rules
+- structured return values for expected validation failures
+
+Good server-side validation targets include:
+
+- prompt text
+- prompt length
+- selected model name
+- message arrays or prior history
+- temperature or option values
+- tool selection input
+- database IDs tied to retrieval or conversation threads
+
+If you are sending prior messages or advanced options back to PHP, validate those values before they are stored, queried against the database, or forwarded to the provider.
+
+## Conversation state and persistence
+
+For small page-local chat flows, PulsePoint can hold the visible message list while PHP handles the provider call.
+
+When you need durable chat history or retrieval-backed context:
+
+- load and store conversation records on the PHP side
+- use Prisma ORM from PHP, not from the browser
+- validate inbound message payloads before persistence
+- shape the final provider request in PHP, not in client-side JavaScript
+
+That keeps the conversation contract authoritative on the server.
+
+## SSE vs websocket vs MCP
+
+These three features solve different problems.
+
+### Use streamed `pp.fetchFunction(...)` when
+
+- the user triggered a request from the current page
+- the assistant response should appear incrementally
+- the page owns the request lifecycle
+- normal request-response semantics are still correct
+
+This is the default for AI text streaming.
+
+### Use websocket when
+
+- the server must push updates without a fresh page request
+- multiple users must see shared realtime changes
+- you need presence, rooms, or bidirectional messaging
+
+Read `websocket.md` when that is the actual requirement.
+
+### Use MCP when
+
+- an external agent needs callable tools
+- the goal is tool exposure, not page-local chat UI
+- you want agent workflows to query your app or database
+
+Read `mcp.md` when that is the actual requirement.
+
+## When `route.php` is still correct
+
+`route.php` still makes sense for AI-related work when:
+
+- the endpoint must be called from outside the current page
+- the request is an integration or webhook
+- you are exposing a standalone API
+- the response is not part of a page-local interactive workflow
+
+For example, provider webhooks, background callbacks, or public machine-facing AI endpoints are reasonable `route.php` use cases.
+
+What should change is the **default assumption**: a chat screen inside a Prisma PHP page should usually start with `index.php` + PulsePoint + `pp.fetchFunction(...)`, not with a separate endpoint first.
+
+## Good to know
+
+- Prisma PHP is unopinionated about AI SDK choice.
+- For page-local AI UI, keep the browser reactive and keep the provider call in PHP.
+- Use `#[Exposed]` for any PHP function called from `pp.fetchFunction(...)`.
+- Use `PP\Validator` as the default validation layer for AI request payloads.
+- Stream assistant replies by yielding from PHP and consuming chunks with `onStream`.
+- Prefer `route.php` only when the endpoint must exist independently of the page.
+- Use websocket for true server push or multi-user realtime behavior.
+- Use MCP for agent-facing tools, not as the default transport for a page-local chat box.

package/dist/docs/index.md

@@ -1,14 +1,16 @@
 ---
 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._/}
+{/_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 environment variables, `.env`, `PP\Env`, `Env::get(...)`, `Env::string(...)`, `Env::bool(...)`, `Env::int(...)`, or runtime configuration, read `env.md` first, then verify the official env docs: `env` and `env-file`. 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._/}
 
 Welcome to the Prisma PHP documentation!
 
@@ -26,6 +28,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 +114,13 @@ Do not confuse the route-file pattern with the `ImportComponent` partial pattern
 ### Read this doc when you need
 
 - **project setup or file placement** → `project-structure.md`
+- **CLI project creation, starter kits, create-prisma-php-app flags, or project update commands** → `commands.md`
+- **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`
+- **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 +132,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,6 +144,8 @@ 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 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
@@ -143,11 +154,44 @@ 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.
+
+## 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`.