<!-- AUTOGENERATED SNAPSHOT for backend-php: refresh from the canonical workspace with `node scripts/sync-ai-workflow.mjs --write`. -->

# Developer AI Workflow

This directory is the canonical source of truth for the repository's developer-facing AI workflow.

## Goals

- Keep Codex, AI Assistant, Junie, and Copilot aligned from one maintained source.
- Make assistant metadata deterministic so the generated files can be rewritten safely and checked in CI.
- Preserve the current mirror-repo workflow for `backend-php` and `front-end-vue`.
- Keep all changes in this workflow scoped to developer tooling and documentation. Runtime OpenAI features stay out of scope.

## Supported Assistants

- `Codex`: local environments and actions under `.codex/environments`.
- `AI Assistant`: generated guidance under `.aiassistant/rules`.
- `Junie`: generated project guidance under `.junie/guidelines.md`.
- `Copilot`: standardized issue-dispatch workflow content under `.github/workflows/copilot.yml`.

## Global Rules

1. Change only `.ai-workflow/workflow.md` and `.ai-workflow/manifest.json` when updating the developer AI workflow.
2. Regenerate all derived files with `node scripts/sync-ai-workflow.mjs --write`.
3. Validate drift with `node scripts/sync-ai-workflow.mjs --check`.
4. Generated assistant files are not hand-edited.
5. Unsupported surfaces stay unsupported until they have a real owner and a real config.
6. `front-end-vue/.ai/mcp/mcp.json` is intentionally unsupported and should not be recreated until there is an actual MCP integration to maintain.

## Command Matrix

### `backend-php`

- Setup: use the existing setup scripts in `backend-php/scripts`.
- Run: start the API stack with `traefik`, `redis`, `mysql-debug`, `php1`, and `caddy`.
- Debug: tail `php1` logs.
- PHP verification: always run backend validation in the `php1` container.
- Unit tests: `docker compose exec -T php1 sh -lc "cd /var/www/html && composer test:unit"`.
- Integration tests: `docker compose exec -T php1 sh -lc "cd /var/www/html && composer test:integration"`.
- API tests: `docker compose exec -T php1 sh -lc "cd /var/www/html && composer test:api"`.

### `front-end-vue`

- Setup: `npm ci` and `npx playwright install`.
- Run: `npm run dev`.
- Unit tests: `npm run test:unit` with Vitest.
- Browser smoke: `npm run test:e2e:smoke`.
- Browser full suite: `npm run test:e2e:ci`.
- Debug: `npx playwright test --debug`.
- Browser validation is Playwright-first. WebdriverIO and Appium are not part of the supported workflow.

### `automation`

- Setup: `npm ci` and `npx playwright install`.
- Run: `npx playwright test --ui`.
- Browser tests: `npx playwright test`.
- Debug: `npx playwright test --debug`.

## Mirror Repos And Sync

- `backend-php` mirrors to `C:\Users\2jepp\PhpstormProjects\api`.
- `front-end-vue` mirrors to `C:\Users\2jepp\WebstormProjects\pleno-vue`.
- Supported metadata directories that must stay mirrored are `.codex`, `.aiassistant`, `.junie`, `.github`, generated `.ai-workflow`, and `scripts/sync-ai-workflow.mjs`.
- Cache and build directories remain excluded from the watcher.
- The mirror repos receive generated snapshots of `.ai-workflow` and `scripts/sync-ai-workflow.mjs` so their local CI can run `--check` without depending on the combined workspace root.

## Generated Outputs

- Root Codex environment for combined backend and frontend entrypoints.
- Backend and frontend Codex environments.
- Backend and frontend AI Assistant guidance.
- Backend and frontend Junie guidance.
- Backend Copilot dispatcher workflow.
- Backend and frontend snapshot copies of `.ai-workflow` plus `scripts/sync-ai-workflow.mjs` for mirrored repositories.