feat: implement exception handling system with error context and policies

AGENTS.md

@@ -0,0 +1,33 @@
+# Repository Guidelines
+
+## Project Structure & Module Organization
+- `src/` layers PHP code (`Application`, `Domain`, `Framework`, `Infrastructure`); create new classes under the matching namespace and keep adapters in Infrastructure.
+- `resources/` stores Vite-managed frontend code (`resources/js`, `resources/css`), while build artifacts belong in `public/assets` under the `public/` web root.
+- `tests/` mirrors the PHP namespaces and houses Playwright suites in `tests/e2e`; share fixtures and stubs through `tests/Support`.
+- Operational docs and tooling sit in `docs/`, `docker/`, and `deployment/`; update those paths whenever runtime behaviour changes.
+
+## Build, Test & Development Commands
+- `make up` / `make down` manage the Docker stack; add `make logs` when you need container output.
+- `npm run dev` starts Vite locally, and `npm run build` produces optimized bundles into `public/assets`.
+- `make test` drives the full Pest suite; use `make test-unit`, `make test-domain`, or `make test-coverage` for focused runs.
+- JavaScript and browser checks run via `npm run test`, `npm run test:e2e`, and `npm run test:coverage`.
+- Quality gates: `make phpstan`, `make cs` (dry run), `make cs-fix` (auto-fix), plus `npm run lint:js` and `npm run format`.
+
+## Coding Style & Naming Conventions
+- Follow PSR-12 with strict types; prefer constructor injection and suffix integrations with their role (`MailerAdapter`, `RedisCache`).
+- Keep PHP objects immutable unless Domain logic requires mutation; colocate interfaces with their consuming layer.
+- Use 4-space indents in PHP and Prettier defaults for TypeScript; name frontend components in PascalCase and utilities in camelCase.
+
+## Testing Guidelines
+- Add Pest specs beside the feature namespace with expressive names (`it_handles_invalid_tokens`); keep builders in `tests/Support`.
+- Mock external services through `tests/__mocks__`; rely on Pest datasets for edge cases.
+- Sync Playwright specs with UX changes, reuse `tests/e2e/fixtures`, and review reports via `playwright show-report`.
+
+## Commit & Pull Request Guidelines
+- Use Conventional Commits (`fix:`, `feat:`, optional scope) to match history.
+- PRs must outline the change, list executed checks, and link issues; attach screenshots for UI work or config diffs for ops updates.
+- Confirm CI covers Pest, Jest, Playwright, PHPStan, and php-cs-fixer before requesting review.
+
+## Security & Configuration Tips
+- Never commit `.env` or secrets; follow `ENV_SETUP.md` and store deployment credentials in Vault.
+- Run `make security-check` ahead of releases and reflect infrastructure changes in `docs/deployment/`.