prisma-php 0.0.8 → 0.0.10

package/.github/copilot-instructions.md

@@ -4,6 +4,7 @@
 
 - Treat `dist/docs/index.md` as the entry point for Prisma PHP guidance in this repo.
 - Read the matching doc in `dist/docs` before generating or editing framework-specific Prisma PHP code.
+- When updating AI guidance in this repo, keep `AGENTS.md`, `.github/copilot-instructions.md`, and `dist/docs` aligned.
 
 ## Route File Conventions
 
@@ -20,6 +21,16 @@
 
 ## Relevant Docs
 
+- Project structure and feature placement: `dist/docs/project-structure.md`
 - Route and layout structure: `dist/docs/layouts-and-pages.md`
+- Data loading, `#[Exposed]`, and SSE streaming: `dist/docs/fetching-data.md`
 - PulsePoint runtime rules: `dist/docs/pulsepoint.md`
-- Component and `ImportComponent` rules: `dist/docs/components.md`
+- Component and `ImportComponent` rules: `dist/docs/components.md`
+- Validation rules: `dist/docs/validator.md`
+- File uploads and file manager behavior: `dist/docs/file-manager.md`
+- Email and SMTP workflows: `dist/docs/email.md`
+- WebSocket and realtime behavior: `dist/docs/websocket.md`
+- MCP server and tool rules: `dist/docs/mcp.md`
+- Authentication: `dist/docs/authentication.md`
+- Metadata and icons: `dist/docs/metadata-and-og-images.md`
+- API-style handlers and webhooks: `dist/docs/route-handlers.md`

package/dist/docs/email.md

@@ -0,0 +1,189 @@
+---
+title: Email
+description: Learn how Prisma PHP email works so AI agents can configure SMTP with .env and send mail with PP\PHPMailer\Mailer using the documented fluent API instead of inventing custom mail abstractions.
+related:
+  title: Related docs
+  description: Read the official Prisma PHP email docs before generating or editing mail flows.
+  links:
+    - /docs/email-get-started
+    - /docs/env-file
+    - /docs/php-validator
+    - /docs/fetch-function
+    - /docs/route-php
+---
+
+Prisma PHP email sending should follow the documented `PP\PHPMailer\Mailer` model backed by PHPMailer, not assumptions copied from Laravel Mail, Symfony Mailer, Nodemailer, or ad hoc `mail()` wrappers.
+
+If a task involves SMTP configuration, contact forms, transactional email, HTML bodies, plain-text fallbacks, reply-to, CC, BCC, attachments, or mailer troubleshooting, AI agents should read the relevant Prisma PHP email docs first and keep the implementation aligned with the installed version.
+
+## AI rule: read the Email docs first
+
+Before generating, editing, or reviewing email-related 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 `email.md` file.
+4. Inspect the current `.env` file for SMTP and sender values.
+5. Inspect the route, exposed function, or handler that sends the email.
+6. Inspect the HTML body or template shape and attachment sources when present.
+7. Inspect Prisma PHP core internals only when the docs do not answer the task.
+
+Do not assume another framework's mailer abstraction applies directly.
+
+## Read this doc when you need
+
+- **SMTP setup, `.env` mail variables, `PP\PHPMailer\Mailer`, `sendEmail`, HTML email, text email, `from`, `to`, `cc`, `bcc`, `replyTo`, or attachments** → official `email-get-started`
+- **contact forms or page-local email sends via PulsePoint** → `fetching-data.md` plus `email.md`
+- **direct POST handlers or handler-only email routes** → `route-handlers.md` plus `email.md`
+- **validation of recipient, sender, or contact-form input** → `validator.md` plus `email.md`
+- **uploaded files used as email attachments** → `file-manager.md` plus `email.md`
+
+## Core email model AI should follow
+
+The Prisma PHP mailer is a PHPMailer wrapper with a fluent API.
+
+The constructor initializes a `PHPMailer` instance, forces `UTF-8`, configures SMTP transport from `.env`, and applies a default sender when `MAIL_FROM` is present and valid.
+
+AI should preserve that model instead of replacing it with undocumented helpers or raw `mail()` calls.
+
+## Exact core file location
+
+The Prisma PHP core `Mailer` class lives here:
+
+```txt
+vendor/tsnc/prisma-php/src/PHPMailer/Mailer.php
+```
+
+When AI needs to inspect framework internals because the docs do not fully answer an email task, this is the exact core file to review.
+
+## `.env` variables AI should expect
+
+The current `Mailer` implementation reads these environment values:
+
+```dotenv
+SMTP_HOST=smtp.example.com
+SMTP_USERNAME=you@example.com
+SMTP_PASSWORD=your-app-password
+SMTP_ENCRYPTION=tls
+SMTP_PORT=587
+MAIL_FROM=no-reply@example.com
+MAIL_FROM_NAME="Prisma PHP App"
+```
+
+Behavior notes:
+
+- `SMTP_HOST` defaults to `localhost`
+- `SMTP_USERNAME` defaults to an empty string
+- `SMTP_PASSWORD` defaults to an empty string
+- `SMTP_ENCRYPTION` defaults to `PHPMailer::ENCRYPTION_STARTTLS`, which resolves to `tls`
+- `SMTP_PORT` defaults to `587`
+- `MAIL_FROM` is optional, but when it is present it must be a valid email address
+- `MAIL_FROM_NAME` is optional
+
+AI should update `.env` whenever email support is introduced and should not hardcode SMTP credentials in route files or components.
+
+## Public fluent methods AI should know
+
+The current `Mailer` class exposes:
+
+- `from(string $email, ?string $name = null)`
+- `to(string $email, ?string $name = null)`
+- `cc(string $email, ?string $name = null)`
+- `bcc(string $email, ?string $name = null)`
+- `replyTo(string $email, ?string $name = null)`
+- `subject(string $subject)`
+- `html(string $html, ?string $altText = null)`
+- `text(string $text)`
+- `attach(string $path, ?string $name = null)`
+- `attachMany(array $attachments)`
+- `send(): bool`
+- `raw(): PHPMailer`
+
+Do not invent undocumented convenience methods when this fluent surface already covers the normal workflow.
+
+## Address validation and failure behavior
+
+The `Mailer` class validates email addresses with `PP\Validator::email(...)`.
+
+Important behavior:
+
+- `from`, `to`, `cc`, `bcc`, and `replyTo` throw a PHPMailer `Exception` when the email is invalid
+- `attach` throws when the file does not exist
+- `attachMany` accepts either plain file paths or arrays shaped like `['path' => '...', 'name' => '...']`
+- `send()` returns `true` on success and throws an `Exception` on failure
+
+For incoming form data, still validate and normalize request fields before calling the mailer. Do not depend on mailer exceptions as the only user-input validation layer.
+
+## Message lifecycle
+
+`Mailer` tracks whether the current message has been modified.
+
+On the first mutating call, it clears prior recipients, attachments, subject, and bodies so a reused `Mailer` instance starts from a clean message state. After `send()`, it clears the message state again on both success and failure.
+
+AI should not assume recipients or attachments persist safely across separate sends on the same instance.
+
+## HTML and text bodies
+
+Use `html()` for HTML messages.
+
+Important behavior:
+
+- `html()` sets `isHTML(true)`
+- `AltBody` is generated automatically from the HTML when no explicit plain-text alternative is supplied
+- line breaks are preserved from common tags such as `<br>`, `</p>`, and `</div>` before tags are stripped
+
+Use `text()` for plain-text-only email.
+
+## Recommended example pattern
+
+```php
+<?php
+
+use PP\PHPMailer\Mailer;
+use PP\Validator;
+
+$recipient = Validator::email($_POST['email'] ?? '');
+
+if ($recipient === null) {
+    return [
+        'success' => false,
+        'message' => 'A valid email address is required.',
+    ];
+}
+
+$body = <<<HTML
+    <h1>Welcome</h1>
+    <p>Your account is ready.</p>
+HTML;
+
+$mailer = new Mailer();
+
+$mailer->to($recipient)
+    ->subject('Welcome to Prisma PHP')
+    ->html($body, "Welcome\n\nYour account is ready.")
+    ->send();
+```
+
+## Advanced configuration
+
+Use `raw()` only when the documented fluent API is not enough and a low-level PHPMailer setting must be adjusted.
+
+That is the correct escape hatch for:
+
+- embedded images
+- custom headers
+- SMTP options
+- low-level PHPMailer features not wrapped by `Mailer`
+
+Do not start with `raw()` when the fluent API already matches the task.
+
+## AI rules for email tasks
+
+- read `email.md` before generating email-related code
+- inspect `.env` and add the required mail variables when email support is introduced
+- prefer `PP\PHPMailer\Mailer` over raw `mail()` or custom SMTP wrappers
+- keep SMTP credentials and sender defaults in `.env`, not in route files
+- validate user-provided email fields before calling the mailer
+- use `html()` for HTML email and provide a custom plain-text alternative when the fallback copy matters
+- check attachment paths before sending or let the documented exception surface a missing file clearly
+- inspect `vendor/tsnc/prisma-php/src/PHPMailer/Mailer.php` only when the docs and current app code do not answer the task

package/dist/docs/fetching-data.md

@@ -1,6 +1,6 @@
 ---
 title: Fetching Data
-description: Learn how to fetch data in Prisma PHP using `pp.fetchFunction`, `#[Exposed]`, page handlers, and route handlers.
+description: Learn how to fetch and stream data in Prisma PHP using `pp.fetchFunction`, `#[Exposed]`, page handlers, SSE responses, and route handlers.
 related:
   title: API Reference
   description: Learn more about the features mentioned in this page by reading the Prisma PHP docs.
@@ -12,15 +12,17 @@ related:
     - /docs/pages-and-layouts
 ---
 
-This page will walk you through how you can fetch data in Prisma PHP, when to use `pp.fetchFunction(...)`, when to use `index.php`, when to use `route.php`, and how to validate incoming data correctly on the PHP side.
+This page will walk you through how you can fetch and stream data in Prisma PHP, when to use `pp.fetchFunction(...)`, when to use `index.php`, when to use `route.php`, and how to validate incoming data correctly on the PHP side.
 
-Prisma PHP has a different mental model from Next.js. Instead of focusing on React Server Components, Suspense streaming, and client data libraries, Prisma PHP gives you direct function invocation from the frontend to PHP, plus file-based routing for page UI and direct route handlers.
+Prisma PHP has a different mental model from Next.js. Instead of focusing on React Server Components, Suspense-driven HTML streaming, and client data libraries, Prisma PHP gives you direct function invocation from the frontend to PHP, plus file-based routing for page UI and direct route handlers.
 
 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.
 
+Prisma PHP can also stream incremental chunks back through `pp.fetchFunction(...)` when an exposed function **yields** values. Prisma PHP handles the SSE response for you, which makes this a good fit for long-running actions, progressive assistant output, status logs, and similar incremental UI updates.
+
 ## Default AI decision rule
 
 For **normal interactive full-stack Prisma PHP work**, AI should default to this stack:
@@ -93,7 +95,7 @@ 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, pagination, modal workflows, and similar route-local interactions.
+This is the preferred pattern for live search, inline validation, toggles, quick edits, filtering, lightweight mutations, pagination, modal workflows, streaming assistants, progress logs, 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. 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.
 
@@ -113,7 +115,7 @@ Use this rule of thumb:
 - use `pp.fetchFunction(...)` when frontend interactivity should call backend PHP directly without creating a dedicated route file
 - use `route.php` when you need a direct API-style endpoint, JSON handler, webhook, or no-view request path
 
-In a full-stack Prisma PHP project, normal page data is usually loaded in `index.php`, and interactive frontend updates are commonly handled with `pp.fetchFunction(...)`.
+In a full-stack Prisma PHP project, normal page data is usually loaded in `index.php`, and interactive frontend updates are commonly handled with `pp.fetchFunction(...)`. That same fetch path can also deliver incremental SSE chunks when the response is streamed.
 
 ## Fetching data in `index.php`
 
@@ -333,6 +335,164 @@ This is useful for search inputs, streaming responses, uploads, and other rapid
 
 As with every `pp.fetchFunction(...)` call, `searchUsers` must be decorated with `#[Exposed]` on the PHP side.
 
+### What the promise resolves to
+
+Normal `pp.fetchFunction(...)` calls resolve with the parsed backend result.
+
+There are three important response modes:
+
+- JSON or JSON-compatible response: the promise resolves with the parsed value
+- redirect response: Prisma PHP handles the redirect and returns a small redirect object
+- generator or `text/event-stream` response: Prisma PHP reads the stream incrementally and the promise resolves after the stream finishes, usually with no final JSON payload
+
+When you expect a stream, put your UI updates inside `onStream`, `onStreamError`, and `onStreamComplete` instead of waiting for a final response object.
+
+## Streaming responses with SSE
+
+Prisma PHP supports incremental streaming through **Server-Sent Events** when `pp.fetchFunction(...)` receives a streaming response.
+
+The current runtime already sends these request headers for `pp.fetchFunction(...)`:
+
+- `Accept: application/json, text/event-stream`
+- `X-PP-Function: ...`
+- the normal Prisma PHP AJAX and wire-request headers
+
+That means a normal fetch function can return JSON for short requests or a stream for long-running work, progressive generation, status logs, or assistant-style responses.
+
+### Simple server-side pattern
+
+For normal `pp.fetchFunction(...)` streaming, you usually do **not** need to manually create `SSE` or `ServerSentEvent` objects.
+
+The simplest pattern is:
+
+1. mark the function with `#[Exposed]`
+2. make the function yield plain strings or arrays
+3. let Prisma PHP handle the SSE response automatically
+
+That is the pattern to prefer for chat responses, AI output, progress updates, and incremental UI messages.
+
+```php filename="src/app/assistant/index.php"
+<?php
+
+use PP\Attributes\Exposed;
+use PP\Validator;
+
+#[Exposed]
+function streamSummary($data)
+{
+    $topic = Validator::string(trim((string)($data->topic ?? '')));
+
+    if ($topic === '') {
+        yield ['error' => true, 'chunk' => 'Topic is required.'];
+        return;
+    }
+
+    yield ['chunk' => 'Reading docs...'];
+    yield ['chunk' => 'Collecting facts...'];
+    yield ['chunk' => 'Writing summary...'];
+
+    foreach (['Point one. ', 'Point two. ', 'Point three.'] as $delta) {
+        yield ['chunk' => $delta];
+    }
+}
+```
+
+For AI streaming specifically, the common pattern is even simpler: as the provider returns text deltas, just yield them.
+
+```php filename="src/app/chat/index.php"
+<?php
+
+use PP\Attributes\Exposed;
+
+#[Exposed]
+function aiSendMessageStream($data)
+{
+    foreach ($aiClient->streamReply($data->message ?? '') as $delta) {
+        if ($delta !== '') {
+            yield ['chunk' => $delta];
+        }
+    }
+}
+```
+
+Prisma PHP handles the rest of the streaming response.
+
+### Low-level helpers when you need manual control
+
+If you need explicit control over raw SSE event metadata, Prisma PHP also includes these streaming helpers:
+
+- `PP\Streaming\SSE`
+- `PP\Streaming\ServerSentEvent`
+
+Core locations in Prisma PHP:
+
+```txt
+vendor/tsnc/prisma-php/src/SSE.php
+vendor/tsnc/prisma-php/src/Streaming/ServerSentEvent.php
+```
+
+`SSE` wraps a `Generator`, sets the default SSE headers, and flushes each yielded item.
+`ServerSentEvent` lets you send `data`, plus optional `event`, `id`, and `retry` metadata for each chunk.
+
+By default, the low-level `SSE` helper sends these response headers:
+
+- `Content-Type: text/event-stream`
+- `Cache-Control: no-cache`
+- `Connection: keep-alive`
+- `X-Accel-Buffering: no`
+
+### Client-side usage with `pp.fetchFunction(...)`
+
+```html
+<script>
+    const [streamText, setStreamText] = pp.state('');
+    const [streamDone, setStreamDone] = pp.state(false);
+
+    async function loadSummary() {
+        let buffer = '';
+
+        setStreamText('');
+        setStreamDone(false);
+
+        await pp.fetchFunction(
+            'streamSummary',
+            { topic: 'Prisma PHP streaming' },
+            {
+                onStream(data) {
+                    if (data.error) {
+                        setStreamText(data.chunk || 'Stream failed.');
+                        return;
+                    }
+
+                    const delta = data.chunk || '';
+                    buffer += delta;
+                    setStreamText(buffer);
+                },
+                onStreamComplete() {
+                    setStreamDone(true);
+                },
+                onStreamError(error) {
+                    setStreamText(`Stream failed: ${error.message}`);
+                },
+            }
+        );
+    }
+</script>
+```
+
+### Current stream parsing rules
+
+When an exposed function yields, Prisma PHP sends the streamed payload as SSE `data:` lines. The current `pp.fetchFunction(...)` stream parser reads those SSE lines one at a time and only forwards `data:` lines to `onStream`.
+
+That means:
+
+- JSON-looking chunks such as objects, arrays, booleans, `null`, numbers, and quoted strings are parsed into JavaScript values
+- plain text chunks stay as strings
+- `event:`, `id:`, and `retry:` can be emitted by `ServerSentEvent`, but the built-in `pp.fetchFunction(...)` stream callback currently ignores them
+- because the current encoder writes one `data:` line per event, prefer JSON values or single-line strings instead of multi-line text blobs
+
+If your client logic depends on named events, event IDs, or retry hints, use a lower-level SSE client instead of relying on the default `pp.fetchFunction(...)` chunk parser alone.
+
 ## File upload support
 
 Prisma PHP’s fetch function automatically switches to multipart handling when the payload contains a `File` or `FileList`.
@@ -359,6 +519,8 @@ That means you do not need to manually build `FormData` for many common upload f
 <button onclick="uploadAvatar()">Upload</button>
 ```
 
+When you pass `onUploadProgress`, Prisma PHP switches to an **XMLHttpRequest** upload path so the browser can report progress. That upload-progress path is meant for normal request-response uploads; it is not the same code path as SSE chunk streaming.
+
 ## Request cancellation
 
 For fast-changing inputs such as live search, Prisma PHP can automatically cancel stale requests by using `abortPrevious: true`.
@@ -467,6 +629,7 @@ This is a better fit for:
 - external integrations
 - webhooks
 - standalone JSON endpoints
+- standalone SSE endpoints that should exist independently of the current page
 - routes that should be called outside the current page context
 - API-style request handlers
 
@@ -612,7 +775,7 @@ echo json_encode([
 
 ## Loading states
 
-Unlike Next.js, Prisma PHP’s data-fetching story here is not centered on React Suspense or streaming server components.
+Unlike Next.js, Prisma PHP’s data-fetching story here is not centered on React Suspense, page HTML streaming, or streaming server components. Prisma PHP can stream request results over SSE, but that is a separate request-response mechanism rather than a page-rendering model.
 
 Instead, loading behavior is typically handled in the UI with:
 
@@ -621,7 +784,7 @@ Instead, loading behavior is typically handled in the UI with:
 - route-level `loading.php`
 - custom interactive state patterns
 
-For interactive fetches, you usually manage loading state yourself:
+For interactive fetches and streamed calls, you usually manage loading state yourself:
 
 ```html
 <script>
@@ -662,10 +825,13 @@ Because Prisma PHP runs the data logic in PHP, database credentials and internal
 - `index.php` is the UI entry point for page rendering.
 - `route.php` is the direct handler entry point for API-style routes.
 - `pp.fetchFunction(...)` only works for functions that are explicitly marked with `#[Exposed]`.
-- `pp.fetchFunction(...)` automatically serializes and parses data.
+- `pp.fetchFunction(...)` automatically serializes request data, parses normal JSON responses, and can consume SSE `data:` chunks.
 - `Validator` is the default PHP validation layer for reactive requests and backend handlers.
 - prefer `Validator::withRules(...)` with `Rule` for rule-based validation.
 - `abortPrevious: true` helps cancel stale requests.
+- streamed `pp.fetchFunction(...)` calls usually resolve after the stream completes, so render stream output from `onStream` callbacks rather than expecting one final JSON object.
+- the built-in stream parser currently reads `data:` lines only; `event`, `id`, and `retry` metadata are not surfaced to `onStream`.
 - file uploads can be handled automatically without manual `FormData` in many cases.
+- `onUploadProgress` switches the request to an XHR upload path so progress events can be reported.
 - `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 PulsePoint plus direct function invocation for interactive updates unless the user explicitly asks for a PHP-only flow.

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 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 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 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!
 
@@ -113,6 +113,9 @@ Do not confuse the route-file pattern with the `ImportComponent` partial pattern
 - **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`
+- **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`
 - **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`
@@ -142,6 +145,7 @@ Do not confuse the route-file pattern with the `ImportComponent` partial pattern
 - 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 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
 
 ## File Manager
@@ -164,6 +168,61 @@ After reading `file-manager.md`, read `validator.md` when non-file request value
 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
 
+## Email
+
+Prisma PHP includes a documented email workflow centered on `PP\PHPMailer\Mailer`, SMTP configuration in `.env`, and PHPMailer-backed message delivery.
+
+Use `email.md` as the local AI-awareness guide for:
+
+- SMTP setup and sender defaults in `.env`
+- `PP\PHPMailer\Mailer`
+- HTML and plain-text email composition
+- recipients, reply-to, CC, and BCC
+- attachments and attachment arrays
+- low-level PHPMailer access through `raw()` when necessary
+
+After reading `email.md`, verify the matching official docs at:
+
+1. `email-get-started`
+
+## WebSocket
+
+Prisma PHP includes a documented websocket workflow centered on a Ratchet-based PHP server, a `ConnectionManager` class under `src/Lib/Websocket`, and the browser `WebSocket` API for realtime client connections.
+
+Use `websocket.md` as the local AI-awareness guide for:
+
+- enabling websocket support in `prisma-php.json`
+- the update workflow that scaffolds websocket support into an existing project
+- `src/Lib/Websocket/websocket-server.php`
+- `src/Lib/Websocket/ConnectionManager.php`
+- Ratchet server setup with `IoServer`, `HttpServer`, and `WsServer`
+- connection lifecycle methods such as `onOpen`, `onMessage`, `onClose`, and `onError`
+- native browser websocket clients and route-local realtime UI behavior
+
+After reading `websocket.md`, verify the matching official docs in this order:
+
+1. `websocket-get-started`
+2. `websocket-chat-app`
+
+## MCP
+
+Prisma PHP includes a documented MCP workflow centered on a `PhpMcp\Server` HTTP entry under `src/Lib/MCP`, attribute-based tool discovery with `#[McpTool]`, and `StreamableHttpServerTransport` for agent integrations.
+
+Use `mcp.md` as the local AI-awareness guide for:
+
+- enabling MCP support in `prisma-php.json`
+- the update workflow that scaffolds MCP support into an existing project
+- `src/Lib/MCP/mcp-server.php`
+- tool classes such as `src/Lib/MCP/WeatherTools.php`
+- `#[McpTool]` and `#[Schema]`
+- `StreamableHttpServerTransport`, JSON response debugging, and Inspector-based debugging
+- auth and Prisma access inside tool methods
+
+After reading `mcp.md`, verify the matching official docs in this order:
+
+1. `prisma-php-ai-mcp`
+2. `ai-tools`
+
 ## Authentication
 
 Prisma PHP includes a documented authentication model centered on sessions, route protection strategy, RBAC, and provider-based sign-in flows.