Skip to content

Source: AGENTS.md. Edit it there; this page is generated at build time.

Reviewly — working notes for agents ​

CLAUDE.md is a byte-identical copy of this file. Edit both, or neither.

Laravel 13 + Filament 4 affiliate content site. README.md covers setup, commands and deployment; CONTEXT.md defines the domain vocabulary (Product, Review, Merchant, Affiliate Link…). Read CONTEXT.md before naming anything.

The one thing that will waste your time ​

php on PATH is not this project's interpreter. Use the Homebrew 8.4 build:

sh
/opt/homebrew/opt/php@8.4/bin/php artisan …

The npm scripts take it through an override:

sh
E2E_PHP=/opt/homebrew/opt/php@8.4/bin/php npm run test:e2e

Commands ​

sh
/opt/homebrew/opt/php@8.4/bin/php artisan test   # Pest, ~8s
npm run test:e2e                                 # Playwright, 103 specs, ~60s
npm run docs:screenshots                         # rewrites docs/admin-guide/img/
npm run docs:pdf                                 # rewrites docs/admin-guide/admin-guide.pdf
npm run build                                    # Vite — required after new Tailwind classes
/opt/homebrew/opt/php@8.4/bin/php vendor/bin/pint --test   # exits 0 on a clean tree
/opt/homebrew/opt/php@8.4/bin/php scripts/check-migration-safety.php   # what CI asks of a PR's migrations

Tailwind is compiled at build time, not scanned live. New utility classes in a Blade file do not exist until npm run build runs.

Verify in a browser, not by reading the source ​

Filament assumptions are wrong more often than they are right — lazy relation managers, deferred filters, asterisks appended to required-field labels, modal button labels. Several were wrong this repo's whole history until someone actually looked. tests/e2e/README.md records the ones already learned; add to it when you find the next.

tests/Feature/AdminFormSchemaTest.php scans every admin class for Filament imports that do not resolve. Filament 4 moved several components (Section went from Filament\Forms\Components to Filament\Schemas\Components), and a bad import fails silently at runtime — the button just opens nothing.

Testing layers ​

Pest asserts at the HTTP layer and cannot see anything Livewire or Alpine does after the page lands. Behaviour that needs a real browser goes in tests/e2e/. The browser suite runs against a throwaway database/e2e.sqlite and never touches the developer's .env or database.

The admin guide ​

docs/admin-guide/README.md is the single source of copy for every admin screen. npm run docs:pdf renders it into a ~60-page A4 manual for non-technical staff. Edit the Markdown, never the PDF, and rerun docs:screenshots first if a screen changed.

Migrations stay safe against the previous release ​

Rollback is a symlink flip back to the previous release directory. It restores code and never schema — so a release whose migration drops something the previous release still reads cannot be rolled back at all. The pre-migration dump becomes the only way out, and restoring it loses every write since the deploy.

So: no dropColumn, dropTable, renameColumn or the raw-SQL equivalent in the same release as the code change that makes it safe. The additive migration and the code that stops reading the old column ship together; the drop ships in the release after.

scripts/check-migration-safety.php enforces this on every PR. It reads only the up() of migrations the PR touches — down() drops what up() added, in almost every migration here, so a whole-file scan would flag the lot and be switched off within a week. When the drop is the point, say so in the migration itself and the check stands down:

php
// destructive-migration: v1.3.0 stopped reading `network`; this is the contract half.

MySQL has no transactional DDL, so a migration that fails halfway leaves the schema partly changed with nothing to undo it. Small, single-purpose migrations are worth more here than they look.

What CI runs ​

.github/workflows/ci.yml, on every PR to main or release/** and every push to them: Pint project-wide, Pest, the config:cache / route:cache / view:cache trio against a production env (the one class of error that otherwise fails only at deploy time), a clean-working-tree check because shield:generate runs inside the suite, npm ci && npm run build with Playwright behind it, the migration rule above, and admin-guide PDF drift.

Both PHP jobs build assets first. Pest needs them as much as the browser does: every public page renders through @vite, which throws with no manifest, and public/build is gitignored — so a clean checkout fails 75 tests that pass on any machine that has ever run npm run build.

PHP is pinned to 8.5, to match the server. 8.4.1 is the floor: 18 locked runtime packages require php >=8.4.1, so composer install fails on 8.3. Node comes from package.json's engines. php on PATH is the correct interpreter there. The Homebrew path above is a local-Mac workaround and must never reach a workflow or the server.

Branches and releases ​

PRs target release/v1, not main. main only moves when release/v1 is merged into it for a release, and a tag must be on main or the deploy refuses it. If a change needs anything done by hand in production (a root command on the box, a setting, a check after the deploy), add it under Next release in docs/releases/README.md in the same PR. The person tagging reads only that file.

Conventions ​

  • Match the surrounding code's comment density and naming. Comments explain why, not what.
  • Filament resources live in app/Filament/Resources/<Model>s/, with relation managers under RelationManagers/.
  • Shield permissions are frozen into database/seeders/ShieldSeeder.php. A new resource is invisible to everyone — including super_admin — until its permissions are generated (shield:generate --all --panel=admin) and the seeder's hardcoded list is updated.
  • pint.json excludes app/Policies, so run Pint project-wide rather than on changed paths. The policies are Shield output, rewritten wholesale by shield:generate, so formatting them would only be undone; excluding them is what makes pint --test capable of gating anything. Hand-edit a policy and it stops being checked — if that ever becomes normal, the exclusion is the thing to revisit.