docs(migration): CASL + organizations migration guide for downstream projects #3227
Description
Description
Comprehensive migration guide for downstream projects updating from the pre-orgs stack to the orgs-enabled stack.
Must cover
- Breaking changes: exhaustive list (routes, policies, JWT payload, auth responses, new dependencies)
- Step by step: ordered instructions to migrate a downstream project
- CASL migration: before/after for each module's policy file, with examples
- DB migration: how to run the migration script on existing data
- Vue frontend: removal of meta.roles, setup of @casl/vue, ability consumption
- Role model: platform admin (god mode) vs org roles (owner/admin/member)
- Security checklist:
- Every route has a policy
- No route bypasses CASL
- 403 tested for unauthorized access
- Ownership verified via CASL conditions
- Org isolation verified (no cross-org data leak)
- Platform admin access verified
- Config options: how to toggle B2B/B2C mode
- Rollback plan: steps to revert if needed
- Update README.md: document new organizations module, updated architecture
- Update CLAUDE.md: add organizations module conventions, CASL patterns, migration system
Acceptance criteria
- Guide is clear enough for a developer unfamiliar with the changes
- All breaking changes documented
- Security checklist included
- README.md updated
- CLAUDE.md updated
- Tested on at least one downstream project