From 1e57fc10463dbd1e429c8529e42a53e781483f7a Mon Sep 17 00:00:00 2001 From: Codex Agent Date: Thu, 1 Jan 2026 14:03:37 +0100 Subject: [PATCH] Update agent docs and artisan command list --- AGENTS.md | 66 +++++++++++++++++++++++++++++++++++----------- docs/agents/ops.md | 16 +++++++++++ 2 files changed, 67 insertions(+), 15 deletions(-) create mode 100644 docs/agents/ops.md diff --git a/AGENTS.md b/AGENTS.md index 21e7928..df3bf46 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -24,20 +24,21 @@ This repository hosts a multi-tenant event photo platform (Laravel 12, PHP 8.3, - Keep this AGENTS.md authoritative. If per-agent docs diverge, update this file and link the rationale. ## Tools & Permissions -- Languages/Frameworks: PHP 8.3 (Laravel 12), TypeScript/JavaScript (React 19/Vite 7/Tailwind 4), Filament 4. -- Dev Commands: composer, npm, vite, artisan, PHPUnit, Pint/ESLint, Docker/Compose (for dev). +- Languages/Frameworks: PHP 8.2+ (Laravel 12), TypeScript/JavaScript (React 19/Vite 7/Tailwind 4), Filament 4. +- Dev Commands: composer, npm, vite, artisan, PHPUnit, Pint/ESLint, Docker/Compose (for dev), Playwright, Vitest, TypeScript. -- Libraries: simplesoftwareio/simple-qrcode for server-side QR generation; Paddle API client (custom service) for payments; dompdf for PDF generation; spatie/laravel-translatable for i18n. -- Payment Systems: Paddle (subscriptions and one-time payments), RevenueCat (mobile app subscriptions). +- Libraries: simplesoftwareio/simple-qrcode for server-side QR generation; Paddle API client (custom service) for payments; dompdf for PDF generation; spatie/laravel-translatable for i18n; minishlink/web-push for web push; firebase/php-jwt for JWT; Sentry (Laravel + Vite); Stripe (PHP + JS); Tamagui (design system); i18next (frontend i18n); vite-plugin-pwa for PWA builds. +- Payment Systems: Paddle (subscriptions and one-time payments), RevenueCat (mobile app subscriptions), Stripe (legacy/integration use). - PWA Technologies: React 19, Vite 7, Capacitor (iOS), Trusted Web Activity (Android), Service Workers, Background Sync. ## Repo Structure (high-level) -- docs/prp/ — split PRP (authoritative). Start at docs/prp/README.md. +- docs/archive/prp/ — split PRP (authoritative). Start at docs/archive/prp/README.md. - docs/process/changes/ — session change logs. - docs/process/todo/ — prioritized backlog items (replaces single TODO.md file). - resources/js/guest/ — Guest PWA source (React 19, offline-first, installable). - resources/js/admin/ — Tenant Admin PWA source (React 19, Capacitor/TWA ready). -- fotospiel_prp.md — legacy monolithic PRP (historical reference; do not edit). +- resources/js/pages/ — Inertia pages (React). +- docs/archive/README.md — historical PRP context. ## Standard Workflows - Coding tasks (Codegen Agent): @@ -53,11 +54,46 @@ This repository hosts a multi-tenant event photo platform (Laravel 12, PHP 8.3, - Tag with semantic version; generate changelog from commits/PRs; ensure legal pages and migration notes are updated. ## Developer Utilities -- Artisan commands: - - media:backfill-thumbnails — generate thumbnails for existing photos. - - tenant:add-dummy — create a demo tenant and admin user (see --help for options). - - tenant:attach-demo-event — attach an existing demo event to a tenant. -- Public APIs for Guest PWA: stats/photos endpoints with ETag; likes; uploads; see docs/prp/03-api.md. +### Artisan commands + +#### Billing & Packages +- package:check-status — check event package status. +- packages:migrate-legacy — migrate legacy package purchases. +- paddle:sync-packages — sync packages with Paddle (push/pull/queue/dry-run). +- coupons:export — export coupon redemptions. +- checkout:send-reminders — send abandoned checkout reminders (dry-run supported). + +#### Tenant Operations +- tenant:attach-demo-event — attach an existing demo event to a tenant. +- tenant:backfill-invitations — backfill invitations (supports tenant filtering). +- tenant:notifications:retry — retry tenant notification delivery. +- tenants:retention-scan — tenant retention scanning. + +#### Demo & Seeds +- demo:seed-switcher — seed demo switcher tenants (supports cleanup and sample photos). + +#### Guest Engagement +- guest:feedback-reminders — send guest feedback reminders. + +#### Storage & Exports +- storage:monitor — storage monitor. +- storage:check-upload-queues — upload queue health checks. +- storage:archive-pending — dispatch storage archiving. +- exports:purge — purge expired data exports. +- media:backfill-thumbnails — generate thumbnails for existing photos. + +#### Photobooth +- photobooth:ingest — ingest photobooth uploads. +- photobooth:cleanup-expired — deactivate expired photobooth accounts. + +#### Content & Assets +- fonts:sync-google — sync Google Fonts to public storage. +- help:sync — sync help center content. + +#### Metrics & Misc +- metrics:package-limits — inspect/reset package limit metrics (routes/console.php). +- inspire — inspiring quote (routes/console.php). +- Public APIs for Guest PWA: stats/photos endpoints with ETag; likes; uploads; see docs/archive/prp/03-api.md. - Payment Integration: Paddle webhooks, RevenueCat mobile subscriptions. ## PWA Architecture @@ -78,9 +114,9 @@ This repository hosts a multi-tenant event photo platform (Laravel 12, PHP 8.3, ## References - ADR-0006: Tenant Admin PWA architecture decision. -- docs/prp/06-tenant-admin-pwa.md: Detailed PWA specifications. -- docs/prp/07-guest-pwa.md: Guest PWA requirements and features. -- docs/prp/08-billing.md: Payment system architecture. +- docs/archive/prp/06-tenant-admin-pwa.md: Detailed PWA specifications. +- docs/archive/prp/07-guest-pwa.md: Guest PWA requirements and features. +- docs/archive/prp/08-billing.md: Payment system architecture. === @@ -226,7 +262,7 @@ protected function isAccessible(User $user, ?string $path = null): bool ## Inertia Core -- Inertia.js components should be placed in the `resources/js/Pages` directory unless specified differently in the JS bundler (vite.config.js). +- Inertia.js components should be placed in the `resources/js/pages` directory unless specified differently in the JS bundler (vite.config.js). - Use `Inertia::render()` for server-side routing instead of traditional Blade views. - Use `search-docs` for accurate guidance on all things Inertia. diff --git a/docs/agents/ops.md b/docs/agents/ops.md new file mode 100644 index 0000000..8473cf4 --- /dev/null +++ b/docs/agents/ops.md @@ -0,0 +1,16 @@ +# Ops Agent Operating Guide + +## Mission & Scope +- Automate CI/CD, releases, issue hygiene, and repo maintenance tasks. +- Follow repository guardrails in `AGENTS.md` and keep operational work auditable. + +## Tooling Checklist +- **bd (beads)**: Use for issue creation, updates, and sync workflows. +- **Git hygiene**: Keep changes scoped; avoid touching unrelated files. +- **Laravel Boost MCP**: Prefer structured tooling for routes, DB reads, logs, and URLs. + +## Operational Notes +- Never change production infrastructure or data without explicit human approval. +- For releases: use semantic version tags, generate a changelog, and ensure legal pages and migration notes are current. +- For issue hygiene: import `docs/process/todo/` items into issues and avoid duplicates. +- When ending a session, follow the Landing the Plane checklist in `AGENTS.md`.