Kickoff Laravel Package

Getting Started

• Pin your toolchain first. 1.39 requires PHP 8.5+ for Kickoff itself and for generated apps, and generated apps pin Node 26 (.nvmrc, engines.node). If you're on PHP 8.4, stay on 1.38 — don't do a half-upgrade where Kickoff runs on 8.5 but the app can't.
• Upgrading an existing app is a checklist, not a composer update: run the kickoff-patch skill, re-publish media-manager-views, set QUEUE_CONNECTION=redis and add the scheduler cron in production, and rename CACHE_DRIVER → CACHE_STORE.
• Look first at: bin/deploy, bin/backup-db, routes/console.php, config/trustedproxy.php, Admin > Settings > Mail, and the new guardrail tests (RouteSmokeTest, DeployParityTest, FluxIconsExistTest, ContentSecurityPolicyTest). Those tests encode what the package expects from your app — read them before customising.
• First use case: scaffold, then migrate:fresh --seed to get a working login, then php artisan optimize and the test suite before touching anything. optimize is a real canary here — it's how the broken <x-input-otp> component in the 2FA screen surfaced.

Implementation Patterns

• Deploy through bin/deploy only. It now runs under set -Eeuo pipefail, does a checked git state, npm build, optimize, a health check on /up and /, and an honest rollback. Add your own steps as separate scripts invoked from the deploy path rather than editing it inline, so DeployParityTest keeps meaning something.
• Operations run isolated: operations --isolated. This is the supported invocation.
• Backups are cron + exit codes. bin/backup-db verifies the archive and exits non-zero when GPG fails. Alert on exit status, not on log scraping, or you'll only learn about a broken archive at restore time.
• Scheduling lives in routes/console.php alongside data:purge, package pruning and the Horizon snapshot. Add tasks there and ship a single schedule:run cron in production.
• Register listeners explicitly. Event registration is now withEvents(discover: false) — listeners register once, but auto-discovery is off. New listeners go in the same explicit list, not in a class you expect Laravel to find.
• Roles and seeding: self-registered users get the default role, and AccessControlSeeder is additive so re-running is safe. Prefer extending it (or adding a seeder after it) over editing it.
• SSO buttons render on the real auth views. The unverified-email path claims the account and revokes the old credentials rather than handing the session over — that's a deliberate behaviour you should document for whoever handles support.
• Mail tracking is a settings toggle under Admin > Settings > Mail — no code change needed to enable/disable open and click tracking.
• Treat "settings" as ops-affecting. Saving settings restarts workers, so gate that permission like a deploy action, not a user preference.

Gotchas and Tips

• CACHE_DRIVER was ignored entirely before this release. If cache behaviour has felt inexplicable, that's why. Rename it to CACHE_STORE in .env, .env.example and every secret store.
• operations --force never existed. Any script calling it silently did nothing. Grep your ops scripts for --force and fix the call sites.
• CSP is composed from the origins Kickoff views load. Any new font CDN, analytics tag, embed or third-party script gets blocked with only a browser-console message. Add the origin and pin it with ContentSecurityPolicyTest.
• Docker services bind to 127.0.0.1. Fine locally; for CI or remote access use a compose override rather than editing the shipped file, so upgrades stay clean.
• No wildcard trusted proxies in production. Behind a load balancer without config/trustedproxy.php configured you'll see mixed content, redirect loops, and rate limiting that collapses every client into a single IP.
• Webhooks refuse private/metadata hosts and sign the exact bytes. A webhook pointed at localhost for local testing will be rejected — use a public tunnel. Verify the signature against the raw request body, never a decoded/re-encoded array.
• The SSO claim path revokes credentials. Users who signed up with an unverified email will be surprised; expect tickets and put it in your release notes to end users.
• Secrets are excluded from the audit trail, and 2FA columns are hidden from serialization. Don't build reporting on password/remember-token/2FA changes from the audit log, and read 2FA values from model attributes rather than JSON.
• Strict Eloquent is non-production only (lazy loading, discarded attributes). Keep it enabled in CI and tests so N+1s and accidentally-discarded attributes fail there instead of in production; the architecture DB rule is now enforceable — enable it.
• #[Url] perPage is clamped server-side. Don't rely on arbitrary query values and don't re-implement the clamp in JavaScript or the two will disagree.
• Bulk actions now explain skips. Surface the returned reasons in the UI, otherwise admins read "some users skipped" as a failure.
• migrate:fresh --seed yields a login but is destructive. Make sure no deploy or patch script can reach it outside a local environment.
• Media manager views are published. Re-publish after the upgrade or you'll pair stale views with new expectations and chase phantom bugs.
• Most upgrade friction here is env/config drift, not code. kickoff-patch plus the four guardrail tests is the fastest way to find it.