Getting Started

Treat v10.0.0 as a major upgrade: start by reviewing your composer.json constraints, then run a clean composer update in a branch and verify Laravel, Filament, Livewire, Stripe, Socialstream/Socialite, and spatie/laravel-permission compatibility before merging.
First places to inspect: panel providers for the new grouped app/admin navigation, the setup wizard/onboarding flow for account/team creation, OAuth/API configuration toggles, and Docker/CI files affected by the toolchain and Filament theme asset changes.
First day-to-day use case: register or adjust grouped navigation for your app/admin panels, then exercise the guided account/team setup flow with OAuth and API configuration left opt-in.

Implementation Patterns

Use the grouped navigation as the default organization model for panel resources/pages. Keep app-facing and admin-facing navigation in separate panels or clearly separated groups so discoverability improvements are preserved as you add resources.
Wire the setup wizard into first-login or team-creation flows rather than forcing it globally. Make OAuth and API configuration optional so existing users and local development do not depend on external credentials.
For account/team onboarding, keep wizard steps idempotent and resumable. Persist progress or derive completion from existing account/team state so users can leave and return without duplicate records.
When extending panels, prefer Filament navigation groups, labels, and sort configuration over custom menus. This keeps upgrades predictable and lets the package’s grouping behavior continue to work.
In Docker-based frontend builds, ensure the Filament theme assets are built as part of the image pipeline. Do not assume prebuilt assets from the host are present in production containers.
Update CI actions deliberately. If checkout/cache/Docker actions changed, verify cache keys, build contexts, and artifact paths in the same pull request as the dependency upgrades.
Keep Guzzle on 7.x and spatie/laravel-permission on 7.x unless the Socialstream/Socialite and roles-permissions constraints change. Use Composer’s platform/constraint handling rather than overriding transitive requirements.

This is a major release. Do not merge dependency changes without regression-testing authentication, OAuth callbacks, team/account setup, role/permission checks, Stripe flows, and Filament panel rendering.
Guzzle 8 is intentionally not supported yet because Socialstream/Socialite do not support it. Avoid forcing Guzzle 8 in root constraints or CI; it will create brittle installs.
spatie/laravel-permission is intentionally pinned to 7.x due to roles-permissions requirements. Check migrations, cache reset commands, and permission seeders after upgrading.
OAuth and API setup are opt-in. Missing provider credentials should disable or skip those wizard steps cleanly rather than breaking onboarding.
After upgrading Filament/Livewire, clear and rebuild caches/assets: config cache, route cache, view cache, and frontend assets. Filament theme changes are easy to miss in Docker if assets are not rebuilt in the image.
If navigation groups look wrong, check panel provider registration, resource $navigationGroup values, and sort orders before adding custom menu code.
Debug setup wizard failures by logging each step transition and validating account/team state after every submit. Most issues will be stale state, missing optional config, or permissions rather than the wizard UI itself.
Use Filament’s optimization commands in deployment pipelines, but run them after asset builds and config injection. Verify the optimized build in a staging container that matches production.