create-prisma-php-app 5.0.0-alpha.2 → 5.0.0-alpha.3

package/dist/AGENTS.md

@@ -131,6 +131,43 @@ Before generating code, choose the documentation file based on the task.
 - **General doc entry point and framework orientation**  
   Read `index.md`
 
+## Default interactive UI and fetching rule
+
+For normal full-stack Prisma PHP work, assume the user wants the **PulsePoint-first** approach unless they explicitly ask otherwise.
+
+Default interaction stack:
+
+1. render route UI with `index.php`
+2. keep browser-side interactivity in **PulsePoint**
+3. call backend PHP from the frontend with **`pp.fetchFunction(...)`**
+4. mark callable PHP functions or methods with **`#[Exposed]`**
+5. validate and normalize input on the PHP side with **`PP\Validator`**
+
+Treat this as the default for:
+
+- search
+- filters
+- pagination
+- quick edit flows
+- toggles
+- dialogs and drawers
+- inline validation
+- route-local CRUD actions
+- dashboard interactions
+- similar reactive page behavior
+
+Do **not** default to:
+
+- a PHP-only interaction style
+- ad hoc `fetch('/api/...')` patterns
+- extra `route.php` files for page-local interactions that already fit `pp.fetchFunction(...)`
+
+Choose a more PHP-only pattern only when:
+
+- the user explicitly asks for PHP-only behavior
+- the task is clearly non-reactive
+- the task is a standalone API, webhook, integration endpoint, or public JSON handler
+
 ## Default workflow for AI agents
 
 Use this workflow unless the user asks for something narrower:
@@ -151,9 +188,9 @@ When the task is about creating or editing a route, do not guess.
 
 Important: creating a route means creating or updating the correct folder and route file under `src/app`. It does **not** mean editing generated route metadata. In particular, never update `files-list.json` by hand.
 
-- Use `index.php` for rendered UI and normal page routes
+- Use `index.php` for rendered UI and normal page routes, and default to PulsePoint plus `pp.fetchFunction(...)` for interactive behavior inside those routes unless the user explicitly asks for PHP-only behavior
 - Use `layout.php` for shared UI that wraps route subtrees
-- Use `route.php` for direct handlers such as JSON endpoints, API-style routes, AJAX handlers, form-processing endpoints, webhooks, or other no-view server logic
+- Use `route.php` for direct handlers such as JSON endpoints, API-style routes, AJAX handlers, form-processing endpoints, webhooks, or other no-view server logic; do not default to `route.php` for normal route-local interactions that fit PulsePoint plus `pp.fetchFunction(...)`
 - Use `not-found.php` for route-specific not-found UI
 - Use `error.php` for route or app-level error UI
 

package/dist/README.md

@@ -2,11 +2,11 @@
 
 Prisma PHP is a modern full-stack PHP framework that combines native PHP, PulsePoint reactivity, PHPX components, and a Prisma-inspired ORM into one cohesive developer experience.
 
-Build modern, reactive interfaces with a server-first mental model, type-safe data access, and a project structure designed for real applications.
+Build reactive interfaces with a server-first mental model, structured routing, type-safe data access, and a project layout designed for real applications.
 
 ## Getting Started
 
-First, create a new Prisma PHP project:
+Create a new Prisma PHP project:
 
 ```bash
 npx create-prisma-php-app@latest my-app
@@ -18,7 +18,7 @@ Start the development server:
 npm run dev
 ```
 
-Open your local app in the browser after the dev server starts.
+Open the local app in your browser after the dev server starts.
 
 ## Prerequisites
 
@@ -36,10 +36,12 @@ If you are using XAMPP on Windows, enabling `extension=zip` in `php.ini` is reco
 Prisma PHP brings together the core pieces needed to build full-stack PHP apps:
 
 - **Native PHP + modern reactivity** with PulsePoint
-- **PHPX component system** inspired by JSX and React
+- **PHPX component system** for reusable UI composition
 - **Prisma PHP ORM** for schema-first, type-safe database access
+- **Built-in authentication patterns** for sessions, route protection, RBAC, credentials auth, and provider login
+- **File-based routing** with clear route file conventions
 - **CLI scaffolding** for new apps, starter kits, and optional features
-- **Flexible deployment options** for traditional hosting, CI/CD, and containerized setups
+- **Flexible deployment options** for local development and production workflows
 
 ## Common Create Commands
 
@@ -61,136 +63,151 @@ Use a starter kit:
 npx create-prisma-php-app my-app --starter-kit=fullstack
 ```
 
-Other documented flags include:
+Other documented flags may include capabilities such as WebSocket support, MCP support, backend-only mode, Swagger docs, and Prisma integration depending on the installed version.
 
-- `--websocket`
-- `--mcp`
-- `--backend-only`
-- `--swagger-docs`
-- `--docker`
+## Documentation
 
-## Project Structure
+Prisma PHP ships with local documentation for the installed project version.
 
-A generated Prisma PHP project typically includes folders like these:
+The installed docs live here:
 
-```text
-prisma-php-project/
-├── prisma/            # schema, migrations, seed files
-├── public/            # public entry point and assets
-├── settings/          # project configuration
-├── src/               # application source code
-├── package.json       # frontend/dev scripts
-├── composer.json      # PHP dependencies
-└── prisma-php.json    # Prisma PHP project capability manifest
+```txt
+node_modules/prisma-php/dist/docs
 ```
 
+Treat these installed docs as the primary documentation source for the current project version.
+
+You can also explore the public docs site:
+
+```txt
+https://prismaphp.tsnc.tech/
+```
+
+## AI Quick Start
+
+If you are using AI-assisted development in a Prisma PHP project:
+
+1. Read `./prisma-php.json` first.
+2. Read the installed docs in `node_modules/prisma-php/dist/docs`.
+3. Read `AGENTS.md` for task-routing rules, framework constraints, and code-generation guidance.
+4. Inspect `vendor/tsnc/prisma-php/src` only when the docs do not answer the task.
+
+### Default interactive UI rule
+
+In Prisma PHP, AI should treat **PulsePoint as the default frontend interactivity model**.
+
+For normal full-stack page work:
+
+- render the page with `index.php`
+- manage browser-side state and UI behavior with **PulsePoint**
+- call PHP from the frontend with **`pp.fetchFunction(...)`**
+- expose callable PHP functions with **`#[Exposed]`**
+- validate incoming data on the PHP side with **`PP\Validator`**
+
+Do **not** default to PHP-only refresh cycles, handcrafted `fetch('/api/...')` patterns, or extra `route.php` handlers for normal interactive page behavior when PulsePoint plus `pp.fetchFunction(...)` already fits the task.
+
+Only prefer a more PHP-only interaction style when the **user explicitly asks for PHP-only behavior**, or when the task is clearly non-reactive.
+
 ## Project Capability Manifest
 
 Prisma PHP uses `prisma-php.json` at the repository root as the source of truth for enabled framework features and local environment configuration.
 
-Tools, scripts, and AI agents should inspect this file before making decisions about:
+Use it to verify capabilities such as:
 
-- frontend tooling
+- Tailwind CSS support
 - backend-only mode
-- Prisma ORM usage
-- Tailwind CSS availability
+- Prisma ORM support
 - Swagger docs
-- Websocket support
+- WebSocket support
 - MCP support
 - TypeScript support
-- local development paths and BrowserSync config
-
-A typical file looks like this:
-
-```json
-{
-  "projectName": "test-latest",
-  "projectRootPath": "C:\\xampp\\htdocs\\projects\\prisma-php\\test\\test-latest",
-  "phpEnvironment": "XAMPP",
-  "phpRootPathExe": "C:\\xampp\\php\\php.exe",
-  "bsTarget": "http://localhost/projects/prisma-php/test/test-latest/",
-  "bsPathRewrite": {
-    "^/": "/projects/prisma-php/test/test-latest/"
-  },
-  "backendOnly": false,
-  "swaggerDocs": false,
-  "tailwindcss": true,
-  "websocket": false,
-  "mcp": false,
-  "prisma": false,
-  "typescript": false,
-  "version": "4.4.9",
-  "componentScanDirs": ["src", "vendor/tsnc/prisma-php/src"],
-  "excludeFiles": []
-}
-```
+- local development paths and BrowserSync settings
 
-## AI Agent Guidance
+Do not assume a feature is enabled unless `prisma-php.json` confirms it.
 
-If you are using AI-assisted development in this project:
+## Documentation Map
 
-- treat `prisma-php.json` as the capability manifest for the current app
-- do not assume Tailwind CSS, Prisma ORM, MCP, Swagger, TypeScript, or websocket support is enabled unless the file says so
-- read the installed Prisma PHP docs for the current version before changing routing, layouts, middleware, or framework-specific behavior
-- use `prisma-php.json` together with the installed docs to make safer decisions
+Use these docs as the main entry points for common work:
 
-## PHPX and Reactivity
+- `index.md` for the general documentation entry point
+- `project-structure.md` for project structure, route placement, and file conventions
+- `layouts-and-pages.md` for pages, layouts, nested routes, and dynamic routes
+- `components.md` for PHPX components, props, children, fragments, icons, buttons, and composition
+- `fetching-data.md` for `pp.fetchFunction(...)`, `#[Exposed]`, and interactive backend flows
+- `prisma-php-orm.md` for Prisma ORM, `schema.prisma`, migrations, and generated PHP classes
+- `authentication.md` for auth strategy, sessions, RBAC, credentials auth, and provider flows
+- `file-manager.md` for uploads, `multipart/form-data`, `$_FILES`, and `PP\FileManager\UploadFile`
+- `route-handlers.md` for `route.php`, JSON responses, and direct server handlers
+- `error-handling.md` for expected errors, `error.php`, `not-found.php`, and validation failures
+- `caching.md` for cache behavior and `CacheHandler`
+- `metadata-and-og-images.md` for metadata, title, description, icons, and head behavior
+- `pulsepoint.md` for PulsePoint runtime usage and reactivity patterns
+- `upgrading.md` for feature enablement and project update workflows
 
-Prisma PHP uses **PHPX**, a template system inspired by JSX and React, but designed for `.php` files. Combined with **PulsePoint**, it gives you interactive UI behavior without adopting a full JavaScript framework mental model.
+## Recommended Development Approach
 
-You can keep your application logic in PHP while using browser-resident state for fast UI updates.
+When working in Prisma PHP:
 
-## ORM
+- prefer the installed Prisma PHP docs over assumptions from other frameworks
+- use `AGENTS.md` as the strict AI operating guide
+- inspect nearby project files before generating new framework-specific code
+- inspect framework internals only when the installed docs are not enough
 
-Prisma PHP ORM is a schema-first database toolkit for PHP. You define your models in `schema.prisma`, generate a typed PHP client, and use expressive query methods such as:
+## Route and File Conventions
 
-- `findMany`
-- `findFirst`
-- `findUnique`
-- `create`
-- `update`
-- `delete`
-- `upsert`
+Prisma PHP uses file-based routing with special route files such as:
 
-It also includes CLI support for workflows like:
+- `index.php` for rendered UI routes
+- `layout.php` for shared UI wrappers
+- `route.php` for direct handlers such as JSON or API-style endpoints
+- `loading.php` for loading UI
+- `not-found.php` for route-level not-found UI
+- `error.php` for route-level or app-level error UI
 
-- `migrate`
-- `generate`
-- `push`
-- `reset`
+For task-specific route decision rules and framework generation rules, read `AGENTS.md`.
 
-## Deployment
+## PulsePoint and Frontend Reactivity
 
-Prisma PHP supports multiple deployment styles:
+Prisma PHP uses PulsePoint for browser-side reactivity, and AI should assume this is the **default choice** for interactive UI behavior in full-stack routes.
 
-- **Traditional deployment** using ZIP/FTP to shared hosting environments such as cPanel
-- **CI/CD deployment** with GitHub Actions
-- **Docker deployment** for containerized environments
+When working with runtime features such as:
 
-A common production flow is:
+- `pp.state`
+- `pp.effect`
+- `pp.ref`
+- `pp-for`
+- `pp-spread`
+- `pp-ref`
 
-```bash
-npm run build
-```
+read the installed Prisma PHP docs for the current version first, then consult:
 
-Then upload or deploy the built project using your preferred hosting workflow.
+```txt
+https://pulsepoint.tsnc.tech/llms
+```
 
-## Learn More
+## Project Structure
 
-To learn more about Prisma PHP, explore the official resources:
+A generated Prisma PHP project typically includes folders like these:
 
-- Website: [https://prismaphp.tsnc.tech](https://prismaphp.tsnc.tech)
-- Documentation: [https://prismaphp.tsnc.tech/docs](https://prismaphp.tsnc.tech/docs)
+```text
+prisma-php-project/
+├── prisma/            # schema, migrations, seed files
+├── public/            # public entry point and assets
+├── settings/          # project configuration
+├── src/               # application source code
+├── package.json       # frontend/dev scripts
+├── composer.json      # PHP dependencies
+└── prisma-php.json    # Prisma PHP project capability manifest
+```
 
-## Ecosystem
+## Updating Existing Projects
 
-Prisma PHP is part of a broader ecosystem that includes:
+When enabling features or syncing framework-managed project files:
 
-- PulsePoint
-- PHPX UI
-- PP Icons
+1. Update `prisma-php.json` first.
+2. Read `upgrading.md` in the installed docs.
+3. Run the documented project update workflow for the current version.
 
-## Notes
+## Learn More
 
-- For the best PHPX development experience in VS Code, install the **PHPX Tag Support** extension.
-- If PowerShell blocks local scripts during `npm run dev`, check your Windows execution policy.
+Start with the installed docs for the current project version, use the topic-specific markdown guides for focused work, and rely on `AGENTS.md` when strict AI generation rules are needed.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-prisma-php-app",
-  "version": "5.0.0-alpha.2",
+  "version": "5.0.0-alpha.3",
   "description": "Prisma-PHP: A Revolutionary Library Bridging PHP with Prisma ORM",
   "main": "dist/index.js",
   "type": "module",