Appearance
Source:
AGENTS.md. Edit it there; this page is generated at build time.
Reviewly — working notes for agents
CLAUDE.mdis 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:e2eCommands
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 migrationsTailwind 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 underRelationManagers/. - Shield permissions are frozen into
database/seeders/ShieldSeeder.php. A new resource is invisible to everyone — includingsuper_admin— until its permissions are generated (shield:generate --all --panel=admin) and the seeder's hardcoded list is updated. pint.jsonexcludesapp/Policies, so run Pint project-wide rather than on changed paths. The policies are Shield output, rewritten wholesale byshield:generate, so formatting them would only be undone; excluding them is what makespint --testcapable of gating anything. Hand-edit a policy and it stops being checked — if that ever becomes normal, the exclusion is the thing to revisit.