create-prisma-php-app 5.0.0-alpha.30 → 5.0.0-alpha.32

package/dist/.github/copilot-instructions.md

@@ -2,12 +2,23 @@
 
 ## Source Of Truth
 
+- Use `./prisma-php.json` as the single source of truth for which optional Prisma PHP features are enabled in the current app and which framework-managed scaffolds should exist.
 - For Prisma PHP applications, treat `node_modules/prisma-php/dist/docs/index.md` as the entry point for the installed framework version.
+- Treat `node_modules/prisma-php/dist/docs` as framework reference docs that teach AI how Prisma PHP works. The presence of a page in that docs folder does not mean the current workspace has that feature enabled.
 - Read the matching doc in `node_modules/prisma-php/dist/docs` before generating or editing framework-specific Prisma PHP code.
 - Expect `AGENTS.md` in the project root and keep it aligned with the installed Prisma PHP docs contract.
-- In the Prisma PHP package source repo, keep `AGENTS.md`, `.github/copilot-instructions.md`, and `dist/docs` aligned so the published docs remain correct after install.
+- In the Prisma PHP package source repo, keep `AGENTS.md`, `.github/copilot-instructions.md`, any `.github/instructions/**/*.instructions.md`, and `dist/docs` aligned so the published docs remain correct after install.
 - Do not assume installed consumer apps also ship a root `.github/copilot-instructions.md` unless the generator explicitly creates one.
+- If `.github/instructions/**/*.instructions.md` exists, treat those files as workspace-local task instructions for third-party libraries, component systems, icon packs, and other implementation-specific rules.
+- Before generating or editing code, inspect `.github/instructions/` and read any `*.instructions.md` files that match the current task, named library, target files, or implementation surface.
 - Keep every `dist/docs/*.md` page AI-discoverable on its own: the frontmatter description and opening section should clearly say when agents should read that file and which adjacent docs to consult next.
+- When a task maps to an optional feature such as `backendOnly`, `swaggerDocs`, `typescript`, `websocket`, or `mcp`, inspect `./prisma-php.json` first, then read the matching docs page to learn the implementation contract.
+
+## Workspace Task Instructions
+
+- Treat `.github/instructions/**/*.instructions.md` as an optional task-specific extension of the Prisma PHP docs contract.
+- Use those instruction files when the task mentions a library, pattern, or file surface they cover, such as a PHPXUI component library, `ppicons`, or another workspace-specific integration.
+- Keep `./prisma-php.json` as the source of truth for Prisma PHP feature flags and generated scaffolds; use `.github/instructions/**/*.instructions.md` to refine task-specific implementation details and prefer the most specific matching instruction when more than one applies.
 
 ## Project Structure Recommendations
 

package/dist/AGENTS.md

@@ -6,26 +6,36 @@ This AGENTS.md belongs in the root of a Prisma PHP application.
 
 Treat `./node_modules/prisma-php/dist/docs/index.md` as the entry point for Prisma PHP guidance, then read the matching document in `./node_modules/prisma-php/dist/docs` before generating, editing, reviewing, or documenting framework-specific behavior.
 
+Treat the installed docs as framework knowledge. They explain what Prisma PHP can do and how to do it. Do not treat the presence of a page in `./node_modules/prisma-php/dist/docs` as proof that the current app has that feature enabled.
+
 Do not guess framework behavior from Laravel, Next.js, React, Vue, Livewire, Alpine, Symfony, Socket.IO, or generic PHP habits. Prisma PHP's installed docs in `./node_modules/prisma-php/dist/docs` and the current project files are the source of truth.
 
+If `.github/instructions/**/*.instructions.md` exists, treat those files as workspace-local task instructions. Inspect `.github/instructions/` before deciding how to implement the task, then read any instruction files whose name, described scope, target files, or library focus matches the current work, such as PHPXUI or `ppicons`.
+
 ## Documentation source of truth
 
 For Prisma PHP projects, use this order first:
 
 1. the user's explicit request
 2. `./prisma-php.json`
-3. the relevant installed document in `./node_modules/prisma-php/dist/docs`
-4. `./AGENTS.md`
-5. project-local conventions and existing app files
-6. Prisma PHP core internals in `vendor/tsnc/prisma-php/src` only when the docs still leave a gap
-7. general framework knowledge as the last fallback
+3. the relevant `.github/instructions/**/*.instructions.md` files for the current task, library, or target files
+4. the relevant installed document in `./node_modules/prisma-php/dist/docs`
+5. `./AGENTS.md`
+6. project-local conventions and existing app files
+7. Prisma PHP core internals in `vendor/tsnc/prisma-php/src` only when the docs still leave a gap
+8. general framework knowledge as the last fallback
 
 Important rules:
 
+- use `./prisma-php.json` as the single source of truth for current-project feature flags and framework-managed scaffolds
+- if `.github/instructions/**/*.instructions.md` exists, inspect `.github/instructions/` and read the files that match the current task, named library, or target files before generating code
+- treat `.github/instructions/**/*.instructions.md` as workspace-local guidance for third-party libraries, design systems, icon packs, and other implementation-specific rules
 - treat `./node_modules/prisma-php/dist/docs` as the single documentation source of truth for the installed Prisma PHP version
+- treat the docs inventory as a framework reference set for AI routing, not as a statement that every optional Prisma PHP feature is enabled in the current app
 - expect `./AGENTS.md` at the project root
 - when the installed docs and a habit from another framework conflict, follow Prisma PHP
-- when updating Prisma PHP package/docs sources, keep `AGENTS.md` and `dist/docs` aligned for consumer apps; if the Prisma PHP package source repo also maintains `.github/copilot-instructions.md`, keep that source-repo file aligned there too
+- when a workspace instruction file and the general Prisma PHP docs both apply, follow both; keep `./prisma-php.json` as the source of truth for feature enablement and prefer the most specific matching instruction for library- or file-scoped implementation details
+- when updating Prisma PHP package/docs sources, keep `AGENTS.md` and `dist/docs` aligned for consumer apps; if the Prisma PHP package source repo also maintains `.github/copilot-instructions.md` or `.github/instructions/**/*.instructions.md`, keep those source-repo files aligned there too
 
 ## Installed docs location
 
@@ -47,10 +57,29 @@ The project root should also include:
 AGENTS.md
 ```
 
+When present, task-scoped workspace instructions live in:
+
+```txt
+.github/instructions
+```
+
 ## Required doc-routing map
 
 Before generating code, examples, instructions, or reviews, choose the documentation file based on the task.
 
+Use the docs router to learn how Prisma PHP implements a task. Use `./prisma-php.json` to decide whether the current app enables the relevant optional feature. When `.github/instructions/` exists, inspect that directory first and read any `*.instructions.md` files that match the task before routing into the Prisma PHP docs.
+
+### Read workspace instruction files first for these tasks
+
+- **Third-party UI, icon, component, or design-system work such as PHPXUI, `ppicons`, or similar workspace-specific integrations**  
+  Read the matching `.github/instructions/**/*.instructions.md` file first
+
+- **Tasks that target files, folders, or conventions covered by a workspace instruction file**  
+  Read the most specific matching `.github/instructions/**/*.instructions.md` file first
+
+- **Library-specific refactors, reviews, or implementations where the workspace provides a dedicated instruction file**  
+  Read that instruction file first, then read the matching Prisma PHP docs page for framework behavior
+
 ### Read these docs first for these tasks
 
 - **Framework orientation, repo-wide guidance, or the high-level AI quick start**  
@@ -131,7 +160,7 @@ Before generating code, examples, instructions, or reviews, choose the documenta
 - **First-time project installation or app creation flow**  
   Read `installation.md`
 
-## Docs inventory in this repo
+## Framework docs inventory in this repo
 
 The current Prisma PHP docs shipped here include:
 
@@ -162,6 +191,10 @@ The current Prisma PHP docs shipped here include:
 - `validator.md`
 - `websocket.md`
 
+This inventory exists to help AI find the right Prisma PHP guidance quickly. It is not a feature inventory for the current app.
+
+When a task depends on optional capabilities such as `backendOnly`, `swaggerDocs`, `typescript`, `websocket`, or `mcp`, inspect `./prisma-php.json` before assuming the generated scaffold exists.
+
 When adding or reviewing AI guidance, do not stop at older docs only. Make sure the guidance also covers `backend-only.md`, `email.md`, `env.md`, `get-started-ia.md`, `mcp.md`, `swagger-docs.md`, `typescript.md`, and `websocket.md`, plus newer behavior documented in `fetching-data.md` and `metadata-and-og-images.md`.
 
 ## Framework-generated files
@@ -394,12 +427,13 @@ In a consumer app, also verify `backendOnly` in `prisma-php.json`:
 Use this workflow unless the user asks for something narrower.
 
 1. read `./prisma-php.json`
-2. read the relevant installed doc from `./node_modules/prisma-php/dist/docs`
-3. inspect `./AGENTS.md` for project-level Prisma PHP guidance
-4. inspect nearby project files that match the route, feature, or component being changed
-5. inspect `vendor/tsnc/prisma-php/src` only if the docs do not answer the task
+2. inspect `.github/instructions/` and read any relevant `*.instructions.md` files when that directory exists
+3. read the relevant installed doc from `./node_modules/prisma-php/dist/docs`
+4. inspect `./AGENTS.md` for project-level Prisma PHP guidance
+5. inspect nearby project files that match the route, feature, or component being changed
+6. inspect `vendor/tsnc/prisma-php/src` only if the docs and matching workspace instructions do not answer the task
 
-Do not jump directly into framework internals if the current docs already answer the task.
+Do not jump directly into framework internals if the current docs and matching workspace instruction files already answer the task.
 
 ## Authentication rules
 

package/package.json

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