organizations 0.6.0 → 0.7.1

data/README.md

@@ -114,7 +114,7 @@ config.user_class = "Account"   # set BEFORE the models are first referenced (in
 Done. Your app now has full organizations / teams support.
 
 > [!IMPORTANT]
-> **Bring Your Own UI (BYOU):** This gem provides all the building blocks — models, controllers, routes, helpers, and mailers — but intentionally **does not ship with views**. Views are too context-dependent (Tailwind vs Bootstrap, dark mode, your app's design system) to be one-size-fits-all. Run `rails g organizations:views` to copy the Tailwind reference views into `app/views/organizations/` and retheme them — they're yours. The copies use the `heroicon` helper (add `gem "heroicons"`, or swap the icon calls for your own set), and the organization page's owner-only Danger Zone renders only if you provide `app/views/shared/_danger_zone.html.erb` (copy the full-featured one from the dummy). For a complete working example (including the verified-joining screens the generator deliberately doesn't cover), check out the demo app in [`test/dummy`](test/dummy/).
+> **Bring Your Own UI (BYOU):** This gem provides all the building blocks — models, controllers, routes, helpers, and mailers — but intentionally **does not ship with views**. Views are too context-dependent (Tailwind vs Bootstrap, dark mode, your app's design system) to be one-size-fits-all. Run `rails g organizations:views` to copy the Tailwind reference views into `app/views/organizations/` and retheme them — they're yours. The copies use the `heroicon` helper (add `gem "heroicons"`, or swap the icon calls for your own set), and the organization page's owner-only Danger Zone renders only if you provide `app/views/shared/_danger_zone.html.erb` (copy the full-featured one from the dummy). For the verified-joining screens, run `rails g organizations:join` (see "Generate the join and access screens"). For a complete working example, check out the demo app in [`test/dummy`](test/dummy/).
 
 > [!NOTE]
 > This gem uses the term "organization", but the concept is the same as "team", "workspace", or "account". It's essentially just an umbrella under which users / members are organized. This gem works for all those use cases, in the same way. Just use whichever term fits your product best in your UI.
@@ -284,6 +284,96 @@ org.import_allowlist!(["ana@gmail.com", "luis@yahoo.es"], source: "csv_2026-07")
 # nothing without inbox access. The entry is claimed on join.
 ```
 
+### Domain authority: prove that the organization controls the domain
+
+An emailed code proves that one person controls one inbox. It does not prove that the organization may claim the whole domain: a student with an `@university.edu` inbox is not the university. Before you let untrusted organizers enroll domains themselves, require a proof of control per organization and turn on `require_verified_domains`:
+
+```ruby
+config.require_verified_domains = true   # default: false (unverified domains work as before)
+```
+
+The proof is a DNS TXT record with an unpredictable token. The token belongs to one claim: one organization and one exact domain.
+
+```ruby
+domain = org.add_domain!("acme.com")
+domain.start_verification!                 # new token; the challenge stays open 7 days
+domain.verification_record_name            # => "_organizations-verification.acme.com"
+domain.verification_record_value           # => "organizations-verification=Qm9…"
+# The organization's admin publishes that TXT record, then:
+domain.verify!                             # => domain
+# On failure it raises Organizations::DomainVerificationFailed, and
+# error.reason is :not_started, :expired, :changed, :record_not_found or :lookup_failed.
+```
+
+Or record an approval by a platform operator who checked the claim another way. A member of the claiming organization cannot approve its own claim (`NotAuthorized`); deciding who is platform staff is your app's job:
+
+```ruby
+domain.verify_by_operator!(operator: staff_user, note: "Registrar record checked, ticket 4411")
+domain.verification_method   # => "operator"; domain.verified_by => staff_user
+```
+
+Later:
+
+```ruby
+domain.verified?                 # proven and not revoked
+domain.revoke_verification!(reason: "domain sold")   # stops new domain-backed admissions; members stay
+domain.recheck_verification!     # re-reads the TXT record and revokes when it is gone (schedule it if you like)
+domain.start_verification!       # a new challenge: rotates the token and clears an earlier verification
+Organizations::Domain.verified   # scope
+```
+
+The rules:
+
+- **A verification does not expire on its own.** The 7-day TTL is for the open challenge only. Domains change hands: schedule `recheck_verification!` (for DNS proofs) or review operator approvals, and revoke what no longer holds.
+- **Authority columns are privileged.** Only the methods above write `verified_at`, `verification_method`, `verified_by_id` and `verification_revoked_at`. Never let request params reach them: permit only `domain` and `join_policy` in your admin forms, and authorize who may call `verify!` and `verify_by_operator!`.
+- **A proof belongs to one claim.** Moving a domain row to another organization, changing its domain, or copying it (`dup`) clears the proof. A revocation stays until a new proof succeeds, also after `start_verification!`.
+- **Exact domains only.** No subdomain or suffix authority, and no global exclusivity: two departments can each prove their own claim of the same domain.
+- **Changing `domain.domain` clears the verification and the token.** Start again.
+- **Every domain path checks the same rule** (`Organizations::Domain.joinable`): the emailed challenge, the confirmed-account-email shortcut, domain-restricted join codes and `JoinFlow`. It checks again at admission: a domain (or allowlist entry) removed, revoked or blocked while a code was in flight admits nobody. An admin can still approve such a pending request by hand.
+- **A revoked domain never admits**, also with `require_verified_domains` off. Existing members stay.
+- **Existing domains start unverified.** Nothing is grandfathered. Verify them before you turn on `require_verified_domains`.
+- **Invitations, plain codes and allowlists stay separate grants.** They do not depend on domain authority.
+- Rate-limit the endpoint that calls `verify!`, and tell joiners which organization will see their address before they submit it.
+
+Configuration:
+
+```ruby
+config.domain_verification_record_prefix = "_myapp-verification"   # your brand in the DNS label
+config.domain_verification_ttl = 7.days        # how long a challenge stays open
+config.domain_verification_timeout = 5         # seconds for the built-in Resolv lookup
+config.domain_txt_resolver = ->(name) { MyDns.txt(name) }           # custom lookup, returns [String]
+```
+
+**Blocking public email providers (opt-in).** A preset ships with the gem:
+
+```ruby
+config.blocked_email_domains = Organizations::PUBLIC_EMAIL_DOMAINS   # default: []
+```
+
+A blocked domain cannot be enrolled, and an existing row for it stops admitting. People with those addresses can still join by invitation, code or allowlist. The list is defence in depth, not proof of authority and not an authorization boundary: an unlisted provider is not trusted because it is unlisted.
+
+### Sign-up domain policies: none, suggest, auto-join
+
+Each domain has a `join_policy` for people who sign up with a confirmed account email at that domain. The policy acts only while the domain is verified, and only when the account email is confirmed (Devise `:confirmable` or similar) and `trust_confirmed_account_email` is on:
+
+| `join_policy` | What happens |
+|---|---|
+| `"none"` (default) | Nothing. The explicit join flows work as before. |
+| `"suggest"` | The organization appears in `user.suggested_organizations`. The user still chooses to join. |
+| `"auto_join"` | The user joins after sign-up, or right after confirming the email, through the membership gate (`on_member_joining` can veto). |
+
+```ruby
+org.add_domain!("acme.com", join_policy: :suggest)
+domain.update!(join_policy: :auto_join)
+domain.effective_join_policy           # => :none until the domain is verified
+
+current_user.suggested_organizations   # verified "suggest" or "auto_join" domains, minus orgs they are in
+org.join_with_account_email!(current_user)   # the "Join" button for a suggestion
+current_user.join_organizations_by_domain!   # what auto-join runs; idempotent, returns memberships
+```
+
+Auto-join runs in an `after_commit` on the user when `confirmed_at` changes, and never breaks a sign-up: a veto or an already-claimed email skips that organization and logs it. Changing the email of an account that stays confirmed does not trigger it, because nothing proved the new address. The trigger reads the changes of the last save in the transaction, so set `confirmed_at` in that save (Devise does). With Devise `:reconfirmable`, confirming the new address updates `confirmed_at` and triggers it.
+
 ### Cohorts without the gem knowing (`membership_metadata`)
 
 Every join instrument (domain, code, allowlist entry, invitation) carries a `membership_metadata` hash that's merged onto memberships it creates. The gem never interprets it — it's your cohort/segmentation channel:
@@ -321,6 +411,8 @@ result.membership / result.join_request
 @state.status          # :member | :verifying | :pending | :entry
 @state.resend_seconds  # cooldown for the "resend code" button, derived from config
 @state.error_message   # localized message of a just-failed action
+@state.member? / verifying? / pending? / entry?   # the same states as predicates
+@state.challenge       # the join request whose emailed code is in flight
 
 # Which entry forms to show — the org's actual instruments decide:
 org.accepts_domain_joining?  # email form (domains or unclaimed allowlist entries)
@@ -328,14 +420,41 @@ org.accepts_code_joining?    # code form (at least one actually-redeemable code)
 org.accepts_join_requests?   # anything at all
 ```
 
-**Reference UI to copy:** the demo app ships a complete verified-joining implementation — the four-state join screen ([`test/dummy/app/controllers/joins_controller.rb`](test/dummy/app/controllers/joins_controller.rb) + [view](test/dummy/app/views/joins/show.html.erb)) and the org-admin Access surface (domains/codes/allowlist + request queue, [`access_controller.rb`](test/dummy/app/controllers/access_controller.rb)). Copy them into your app and retheme; their headers carry the production checklist.
+### Generate the join and access screens
+
+```bash
+rails g organizations:join                 # join screen + access screen + routes
+rails g organizations:join --skip-access   # the join screen only
+rails g organizations:join --skip-routes   # add the routes yourself
+```
+
+The generator copies host-owned controllers and views (Tailwind, like `organizations:views`) and adds one routes block. Run it again later without `--skip-access` and it adds only the access routes. The engine itself adds no join route, so nothing changes in your app until you run it.
+
+| Screen | URL | What it does |
+|---|---|---|
+| `OrganizationJoinsController` | `GET/POST/DELETE /orgs/:organization_id/join` (`organization_join_path`) | The four `JoinState` states at one URL: a code, a work email and its 6-digit code, or a plain request; withdraw a pending request |
+| `OrganizationAccessController` | `/orgs/:organization_id/access` (`organization_access_path`) | Pending requests (approve, reject), email domains (DNS verification, sign-up policy), join codes (create, revoke), the allowlist (import, remove) |
+
+The generated code already follows the safety rules. Keep them when you edit it:
+
+- **A signed-in user is required** (`config.authenticate_user_method`). The join screen takes the organization from the URL and never changes the session's current organization.
+- **Only POST and DELETE change data**, under Rails' CSRF protection. A `?code=…` link fills in the form; it never joins and never spends a use, also after a sign-in redirect.
+- **Inputs are cut to a fixed length**, and allowlist imports to 1,000 addresses; invalid addresses are skipped and counted.
+- **Unknown, revoked, expired and foreign codes share one message** (`JoinFlow` does that).
+- **The access screen is URL-scoped** with `OrganizationScoped`: it needs `invite_members`, domain changes also need `manage_settings`, and every lookup is scoped to the URL's organization. Unknown organizations, strangers and members without the permission all get the same 404.
+- **Rate limits** on joining, on the screen, and on DNS checks. They need Rails 7.2+ and a cache store that every server process shares (Redis, Solid Cache): the null and memory stores do not enforce them across processes. On Rails 7.1, use Rack::Attack.
+- **A sent code or a pending request redirects** (303), as Turbo expects. Failures render with 422.
+- **The signed-in user comes from `config.current_user_method`**, the same as the rest of the gem.
+- **A disclosure partial** (`organization_joins/_disclosure.html.erb`) tells joiners who will see their name and email before they submit. Edit its text to match your privacy policy.
+
+The templates are the gem's demo app ([`test/dummy`](test/dummy/)), byte for byte, and its HTTP test suite covers them. Two things to know: the join screen shows an organization's name to any signed-in user who has its id (use UUID primary keys or a handle finder for private tenants), and the generator does not check for controllers with the same names in your app (Thor asks before it overwrites a file). When your `routes.rb` has no `routes.draw do` line to insert after, the generator prints the routes for you to add.
 
 ### Rate limiting your join endpoints
 
-The gem deliberately ships no join routes/controllers, so it cannot rate-limit them for you — and **code redemption and code verification are enumeration surfaces**. With Rails' built-in [`rate_limit`](https://api.rubyonrails.org/classes/ActionController/RateLimiting.html):
+The engine adds no join routes, so the rate limits live in your controllers — and **code redemption and code verification are enumeration surfaces**. `rails g organizations:join` adds these limits; for your own controllers, use Rails' built-in [`rate_limit`](https://api.rubyonrails.org/classes/ActionController/RateLimiting.html):
 
 ```ruby
-class JoinsController < ApplicationController
+class OrganizationJoinsController < ApplicationController
   # Joining/redeeming: per-user, generous but bounded
   rate_limit to: 10, within: 1.hour, by: -> { current_user.id }, only: :create
   # Public landings (if any are unauthenticated): per-IP against slug/code enumeration
@@ -349,6 +468,7 @@ Layer them per surface: the gem already throttles **per request** (60s resend in
 
 - Codes are stored as **SHA-256 digests only** (peppered by row id), compared in constant time, single-use, expire after `verification_code_ttl` (15 min default), capped at `verification_max_attempts` (5) with resend throttles.
 - Emails are normalized before the uniqueness check (case, whitespace, and `+tag` plus-addressing collapse — override via `config.verification_email_normalizer`).
+- An emailed code proves one inbox, never the whole domain. Domain authority (DNS TXT or operator approval) is a separate proof per organization; turn on `require_verified_domains` before untrusted self-service enrollment (see "Domain authority").
 - Domain matching is **exact** and evasion-hardened: `acme.com.evil.com`, `evilacme.com`, multi-`@` shapes never match; subdomains are separate domains on purpose (they often mean different cohorts).
 - BYO-UI as always: the gem ships models/APIs/mailers and state; **you must rate-limit your join/redemption/verification endpoints** (see above).
 - Hard member caps belong in **`on_member_joining`** (the strict membership gate) — the `on_join_request_*` after-callbacks are error-isolated and cannot veto. Take `ctx.organization.lock!` inside the gate when the cap must hold under concurrent joins (see "Limit seats per plan").
@@ -363,7 +483,7 @@ config.on_verification_delivery_failed do |ctx|
 end
 ```
 
-Upgrading an existing install: `rails g organizations:upgrade && rails db:migrate` (additive only).
+Upgrading an existing install: `rails g organizations:upgrade && rails db:migrate` (additive only). The generator adds only the migrations your app does not have yet (it asks the database when it can, and reads `db/migrate` otherwise), so run it after every upgrade of the gem. For a squashed migration history, name the steps: `rails g organizations:upgrade --steps add_personal_organizations`.
 
 ## Why this gem exists
 
@@ -395,8 +515,8 @@ Laravel has Jetstream with a `--teams` flag. Django has `django-organizations`.
 
 `organizations` gives you the complete `User → Membership → Organization` pattern with scoped invitations, hierarchical roles, and the ability to switch between organizations – all in a single, well-tested gem that works with your existing Devise setup. What previously took 1.5 months now takes 3 days.
 
-> ![NOTE]
-> This gem handles organization membership and org-level permissions (who can invite members, who can manage billing). For per-record authorization ("can user X edit document Y"), use [Pundit](https://github.com/varvet/pundit) or [CanCanCan](https://github.com/CanCanCommunity/cancancan) alongside this gem.
+> [!NOTE]
+> This gem handles organization membership and org-level permissions (who can invite members, who can manage billing), plus optional per-record grants for members who should see only some records (see "Scoped resource grants"). For general per-record policies ("users can edit their own posts"), use [Pundit](https://github.com/varvet/pundit) or [CanCanCan](https://github.com/CanCanCommunity/cancancan) alongside this gem.
 
 ## The complete API
 
@@ -409,6 +529,7 @@ When you add `has_organizations` to your User model, you get:
 user.organizations                      # All organizations user belongs to
 user.memberships                        # All memberships (with roles)
 user.owned_organizations                # Organizations where user is owner
+user.personal_organization              # Their personal organization, or nil (never creates one)
 user.pending_organization_invitations   # Invitations waiting to be accepted
 
 # Current organization context
@@ -439,6 +560,10 @@ user.is_viewer_of?(org)                 # "Is user a viewer of this org?"
 user.is_at_least?(:admin, in: org)      # "Is user at least an admin in this org?"
 user.role_in(org)                       # => :admin
 
+# Domain policies (see "Sign-up domain policies")
+user.suggested_organizations            # Organizations to offer, from verified domains
+user.join_organizations_by_domain!      # Join every verified auto_join domain (runs on its own)
+
 # Actions
 user.create_organization!("Acme")            # Positional arg
 user.create_organization!(name: "Acme")      # Keyword arg (both work)
@@ -446,6 +571,10 @@ user.leave_organization!(org)
 user.leave_current_organization!             # Leave the active org
 user.send_organization_invite_to!(email)                     # Invite to current org
 user.send_organization_invite_to!(email, organization: org)  # Invite to specific org
+user.create_personal_organization!           # Create it, or return the existing one
+
+# Account deletion
+user.account_deletion_plan                   # What user.destroy would do (changes nothing)
 ```
 
 ### Organization methods
@@ -460,6 +589,7 @@ org.pending_invitations         # Invitations not yet accepted
 
 # Queries
 org.owner                       # User who owns this org
+org.owner_membership            # The owner's Membership
 org.admins                      # Users with admin role or higher
 org.has_member?(user)           # "Does org have this user as a member?"
 org.has_any_members?            # "Does org have any members?"
@@ -467,16 +597,28 @@ org.member_count                # Number of members
 
 # Class methods / Scopes
 Organizations::Organization.with_member(user)  # Find all orgs where user is a member
+Organizations::Organization.personal           # Personal organizations
+Organizations::Organization.not_personal       # Every other organization
+Organizations::Organization.backfill_personal_owners!(mapping, dry_run: true)
+
+# Personal organizations
+org.personal?                   # "Is this someone's personal organization?"
+org.personal_owner              # The user it belongs to
+org.convert_to_shared!          # Stop being personal (needed before a transfer)
 
 # Actions
-org.add_member!(user, role: :member)
-org.remove_member!(user)
-org.change_role_of!(user, to: :admin)
+# Pass the acting user (removed_by:, changed_by:) so the role rule is checked;
+# without one, or with a user who is not a member, nothing is checked.
+org.add_member!(user, role: :member)            # no actor: never checked, authorize it yourself
+org.remove_member!(user, removed_by: current_user)
+org.change_role_of!(user, to: :admin, changed_by: current_user)
 org.transfer_ownership_to!(other_user)
 
 # Invitations (inviter must be a member with :invite_members permission)
 org.send_invite_to!(email)                  # Auto-infers invited_by from Current.user
 org.send_invite_to!(email, invited_by: user) # Explicit inviter
+org.send_invite_to!(email, invited_by: user, grants: { record => %i[read] })  # With scoped grants
+org.grants                                  # Every grant of every membership
 
 # Scopes
 org.memberships.owners          # Memberships with owner role
@@ -490,7 +632,7 @@ Organizations::Organization.create_with_owner!(owner: admin, name: "Acme Corp")
 
 # Verified joining
 org.domains / org.join_codes / org.allowlist_entries / org.join_requests
-org.add_domain!("acme.com", membership_metadata: {})
+org.add_domain!("acme.com", membership_metadata: {}, join_policy: :none)
 org.generate_join_code!(label:, requires_verified_domain_email:, auto_approve:, expires_at:, max_uses:)
 org.import_allowlist!(emails, source:, membership_metadata: {})
 org.approve_join_request!(req, approved_by:) / org.reject_join_request!(req, rejected_by:, reason:)
@@ -503,6 +645,14 @@ org.join_codes.active           # SQL twin of code.active?
 # The join kit (controller/view layer — see "Verified joining")
 Organizations::JoinFlow.attempt(user:, organization:, code:, email:, verification_code:, message:)
 Organizations::JoinState.for(user:, organization:, result:)
+# rails g organizations:join  → OrganizationJoinsController + OrganizationAccessController + routes
+
+# Domain authority (see "Domain authority")
+domain.start_verification! / domain.verify! / domain.verify_by_operator!(operator:, note:)
+domain.verification_record_name / domain.verification_record_value
+domain.verified? / domain.revoked? / domain.joinable? / domain.effective_join_policy
+domain.revoke_verification!(reason:) / domain.recheck_verification!
+Organizations::Domain.verified / Organizations::Domain.joinable / Organizations::Domain.with_join_policy(:suggest)
 
 # Housekeeping
 Organizations::JoinRequest.purge_stale!(older_than: 12.months)  # GDPR sweep: old decided/expired requests
@@ -522,13 +672,29 @@ membership.invited_by           # User who invited them (if any)
 # Permission checks
 membership.has_permission_to?(:invite_members)   # => true/false
 membership.permissions                           # => [:view_members, :invite_members, ...]
+membership.role_sym                              # => :admin
+membership.owner? / admin? / member? / viewer?   # Exact role
+membership.verified?                             # Joined with a proven email (verified joining)
 
 # Role hierarchy checks
 membership.is_at_least?(:member)    # => true (if member, admin, or owner)
+membership.can_assign_role?(:admin) # => true (if admin or owner: roles at or below their own)
+membership.compare_role(other)      # => -1 (higher), 0, 1 (lower)
+membership.authorize_role_change!(:admin, changed_by: current_user)  # Raises NotAuthorized when a member actor outranks or lacks the roles' permissions (does not check :edit_member_roles; nil or non-member actors pass: authorize them yourself)
 
 # Role changes
-membership.promote_to!(:admin)      # Change role to admin
-membership.demote_to!(:member)      # Change role to member
+membership.promote_to!(:admin, changed_by: current_user)  # Change role to admin
+membership.demote_to!(:member, changed_by: current_user)  # Change role to member
+
+# Scoped resource grants (see "Scoped resource grants")
+membership.grants                                         # Its grants
+membership.grant!(record, capabilities: %i[read], granted_by: current_user)
+membership.revoke_grant!(record, revoked_by: current_user)
+membership.can?(:read, record) / membership.capabilities_for(record)
+membership.granted?(record) / membership.grant_for(record)
+membership.limited_by_grants?                             # Role below config.full_resource_access_role
+membership.visible(relation, capability: nil) / membership.granted_ids(Model, capability: nil)
+Organizations::Membership.with_grant_on(record)           # Memberships granted this record
 ```
 
 ### Invitation methods
@@ -542,11 +708,75 @@ invitation.from                 # Alias for invited_by
 invitation.pending?             # => true (not yet accepted)
 invitation.accepted?            # => true (has accepted_at)
 invitation.expired?             # => true (past expires_at)
+invitation.status               # => :pending, :accepted or :expired
+invitation.for_email?(email)    # Case-insensitive match
+invitation.acceptance_url       # Link for your own mailer (honors the engine mount path)
+invitation.acceptance_url(base_url: "https://app.example.com")   # In jobs/mailers without URL defaults
+
+# Grants the membership gets on acceptance
+invitation.grants
+invitation.grant!(record, capabilities: %i[read])
 
 # Actions
 invitation.accept!              # Accept (auto-infers Current.user)
 invitation.accept!(user)        # Accept with explicit user
-invitation.resend!              # Send invitation email again
+invitation.resend!(resent_by: current_user)   # Send invitation email again
+invitation.revoke!(revoked_by: current_user)  # Delete it, so the link stops working
+```
+
+### Verified-joining records
+
+```ruby
+# Organizations::JoinRequest
+request.pending? / approved? / rejected? / withdrawn? / expired? / decided?
+request.effective_status            # => :pending, :approved, :rejected, :withdrawn or :expired
+request.email_verified?
+request.start_email_verification!(email: "j.doe@acme.com")
+request.verify_email_code!("492817")   # => Membership (or the request, when approval is manual)
+request.approve!(decided_by: admin)    # => Membership. Records the actor; checking that it may decide is your job
+request.reject!(rejected_by: admin, reason: "unknown")
+request.withdraw!                      # The user cancels it. Check that the caller owns the request
+user.pending_join_request_for(org)     # The user's open request, or nil
+
+# Organizations::JoinCode
+code.code / code.display_code          # "7FHK2MPX" / "7FHK-2MPX"
+code.active? / revoked? / expired? / exhausted? / code.status
+code.redeem!(user: user)               # Same as JoinCode.redeem(code.code, user:)
+code.revoke!
+
+# Organizations::Domain
+domain.matches_email?("j.doe@acme.com")   # Exact domain match
+domain.blocked?                           # Listed in config.blocked_email_domains
+domain.verification_expired?              # The open DNS challenge passed its TTL
+# (verification methods: see "Domain authority")
+
+# Organizations::AllowlistEntry
+entry.claimed? / entry.claim!(user)
+
+# Organizations::Grant (see "Scoped resource grants")
+grant.capabilities / grant.allows?(:read) / grant.resource / grant.grantable
+# grant.allows? reads the stored list only. To authorize, ask membership.can?(capability, record):
+# it also applies the role ceiling and the organization check.
+```
+
+### Roles
+
+```ruby
+Organizations::Roles.hierarchy                  # => [:owner, :admin, :member, :viewer] (custom roles included)
+Organizations::Roles.valid_role?(:admin)        # => true
+Organizations::Roles.permissions_for(:member)   # => [:view_organization, ...]
+Organizations::Roles.has_permission?(:admin, :invite_members)  # => true
+Organizations::Roles.at_least?(:owner, :admin)  # => true
+Organizations::Roles.compare(:admin, :member)   # => -1 (higher), 0, 1 (lower)
+Organizations::Roles.higher_role(:member) / lower_role(:member)  # => :admin / :viewer
+Organizations::Roles.can_assign?(:admin, :member)                # the role rule (see "Customize roles")
+Organizations::Roles.assignment_refusal(:member, :admin)         # => :outranks, :lacks_permissions or nil
+```
+
+### User housekeeping
+
+```ruby
+user.clear_organization_cache!   # Forget the memoized current organization and membership
 ```
 
 ## Controller helpers
@@ -596,6 +826,7 @@ redirect_to_no_organization!(alert: "...", notice: "...")         # Redirect and
 # Organization creation helper
 create_organization_and_switch!(current_user, name: "Acme")       # Create and set context in one call
 create_organization_with_context!(current_user, name: "Acme")     # Backward-compatible alias
+self.current_organization = org                                  # Set the session's organization (no membership check; prefer switch_to_organization!)
 
 # Authorization
 require_organization!                               # Redirect if no active org
@@ -698,6 +929,32 @@ The helper returns:
 }
 ```
 
+### All view helpers
+
+```ruby
+organization_switcher_data                          # See "Organization switcher"
+organization_invitation_badge(user)                 # See "Invitation badge"
+
+organization_role_label(:admin, organization: org)  # => "Admin" (I18n; the organization selects its vocabulary)
+organization_role_info(:admin, organization: org)   # => { role: :admin, label: "Admin", color: :blue }
+organization_invitation_status(invitation)          # => :pending, :accepted or :expired
+organization_invitation_status_label(invitation)    # => "Pending"
+organization_invitation_status_info(invitation)     # => { status:, label:, color: }
+organization_members_data(org)                      # => [{ id:, membership_id:, name:, email:, role:, role_label:, role_info:, joined_at:, is_owner: }]
+organization_invitations_data(org)                  # => [{ id:, email:, role:, role_label:, invited_by:, invited_by_name:, status:, status_info:, expires_at:, created_at: }]
+
+can_manage_organization?(user, org)     # manage_settings
+can_invite_members?(user, org)          # invite_members
+can_view_billing?(user, org)            # view_billing
+can_manage_billing?(user, org)          # manage_billing
+can_remove_member?(user, membership)    # remove_members, and the role rule
+can_change_member_role?(user, membership)  # edit_member_roles, and the role rule
+can_transfer_ownership?(user, org)      # transfer_ownership
+can_delete_organization?(user, org)     # delete_organization
+```
+
+Inside engine views, the host app's route helpers work without `main_app.` (the engine delegates unknown `*_path` and `*_url` helpers to the host).
+
 ### Invitation badge
 
 ```ruby
@@ -739,7 +996,124 @@ authorize! :destroy, @project  # "Can they delete THIS specific project?"
 | **Based on** | Role in Membership | Policy classes / Ability rules |
 | **Example** | "Admins can invite members" | "Users can edit their own posts" |
 
-**Most B2B apps need both.** Use `organizations` for org membership and capabilities. Use Pundit/CanCanCan for fine-grained resource authorization. They're complementary, not competing.
+**Most B2B apps need both.** Use `organizations` for org membership and capabilities. Use Pundit/CanCanCan for fine-grained resource authorization. They're complementary, not competing. Between the two sits one common case the gem covers: **some members see only some records** (an accountant who handles three of a firm's clients, a contractor on one project). See "Scoped resource grants".
+
+### Scoped resource grants
+
+A grant gives one membership access to one record of your app, with a list of capabilities. Members whose role ranks below `config.full_resource_access_role` (`:admin` by default) see only the records granted to them. Admins and the owner see everything through their role. **The role stays the ceiling:** a member can use a granted capability only when the role also has it as a permission. A grant narrows; it never widens.
+
+It is optional. Add the table, then mark the models you grant:
+
+```bash
+rails g organizations:grants   # check the type of grantable_id, then:
+rails db:migrate
+```
+
+Capabilities are checked against the role's permissions, so give your roles the capabilities they may use on granted records (custom roles work too):
+
+```ruby
+# A block that redefines a built-in role defines only the built-in roles it
+# lists, so list all four: these are the defaults plus the capabilities.
+config.roles do
+  role :viewer do
+    can :view_organization
+    can :view_members
+    can :read
+  end
+  role :client, inherits: :viewer do   # a narrow custom role
+    can :comment
+  end
+  role :member, inherits: :viewer do
+    can :create_resources
+    can :edit_own_resources
+    can :delete_own_resources
+    can :comment
+    can :edit
+  end
+  role :admin, inherits: :member do
+    can :invite_members
+    can :remove_members
+    can :edit_member_roles
+    can :manage_settings
+    can :view_billing
+  end
+  role :owner, inherits: :admin do
+    can :manage_billing
+    can :transfer_ownership
+    can :delete_organization
+  end
+end
+```
+
+```ruby
+class Project < ApplicationRecord
+  include Organizations::Grantable   # project.organization_grants, Project.visible_to(membership)
+end
+```
+
+```ruby
+membership = org.memberships.find_by!(user: contractor)
+
+membership.grant!(project, capabilities: %i[read edit], granted_by: current_user)
+membership.grant!(project, capabilities: %i[read])      # again: replaces the capabilities
+membership.grant!(project, capabilities: [])            # no capabilities: removes the grant
+membership.revoke_grant!(project, revoked_by: current_user)
+
+membership.can?(:edit, project)        # grant lists it AND the role has the :edit permission
+membership.capabilities_for(project)   # => #<Set: {:read}>
+membership.granted?(project)
+membership.grant_for(project)          # => #<Organizations::Grant capabilities: ["read"]>
+membership.limited_by_grants?          # => true for a member, false for an admin
+
+Project.visible_to(membership)                     # what they may see
+Project.visible_to(membership, capability: :edit)  # …and edit
+membership.visible(Project.active)                 # the same, for any relation
+membership.granted_ids(Project, capability: :edit) # just the ids
+
+org.memberships.with_grant_on(project)  # who was granted this project
+org.grants                              # every grant in the organization
+Organizations::Grant.for_resource(project)
+```
+
+Records that are not ActiveRecord models (rows read through another library, ids from an API) work by type and id:
+
+```ruby
+entity = Organizations::Resource.new("Ledger::Entity", entity_id)
+membership.grant!(entity, capabilities: %w[read draft])
+membership.granted_ids("Ledger::Entity")   # => [entity_id, ...]
+```
+
+Any object with an `id` also works; its class name is the type.
+
+**Invitations carry grants.** The grants move to the membership when the invitation is accepted (also when the invitee was already a member):
+
+```ruby
+org.send_invite_to!("client@example.com", invited_by: current_user, role: :client,
+                    grants: { project => %i[read comment], other_project => %i[read] })
+current_user.send_organization_invite_to!(email, role: :client, grants: { project => %i[read] })
+invitation.grant!(project, capabilities: %i[read])   # add one later
+```
+
+The rules:
+
+- **Who may grant.** `granted_by:` (or `revoked_by:`, or the inviter) must be a member: it needs `config.grant_management_permission` (`:edit_member_roles` by default), it may act only on members whose role ranks at or below its own, and, when grants limit it too, it may give only access it has on that record. An account that is not a member is refused. A nil actor (a console, a job, your own authorization) is not checked.
+- **The role is the ceiling everywhere.** `can?`, `capabilities_for`, `granted_ids` and `visible_to` all count only capabilities that the grant lists and the role has. A grant that lists none of the role's capabilities gives nothing.
+- **Organizations stay apart.** For a model with `organization_id`, `visible_to` returns only the membership's organization's records (admins included), `can?` is false for another organization's record (also through `Organizations::Resource`, which reads its `organization_id`), and `grant!` raises `ArgumentError`. A record moved to another organization loses its access.
+- **Invitation grants are checked twice:** when they are attached, and again at acceptance against the inviter as it is then and the membership that receives them (an existing member may hold a higher role). A grant that fails the second check is dropped and logged. Grants cannot be added to an accepted invitation, and a reissued expired invitation carries only the new grants.
+- **Ids must fit the column.** `grantable_id` has your primary key type by default. An id it would change (`"42-a"` in an integer column) raises `ArgumentError`. For resources with other key types, make the column `:string` (or `:uuid`) in the generated migration before you migrate.
+- **Capability names.** Any name by default. To catch typos, list them: `config.grant_capabilities = %i[read edit comment]`.
+- **Removing a member removes their grants.** Deleting a `Grantable` record removes its grants. Changing a role keeps the grants: a member promoted to admin sees everything, and sees only the granted records again after a demotion.
+- **Concurrent grants converge** on one row per membership and record (unique index).
+- **Deleting an account** keeps the grants it gave to members (they were valid then) and deletes the grants it attached to pending invitations. A grant whose capabilities `config.grant_capabilities` no longer allows is dropped at acceptance, not fatal.
+- **Performance.** `can?` runs one query per record unless the grants are loaded: `memberships.includes(:grants)` or `membership.grants.load` before you check a list. `granted_ids` and `visible_to` load the membership's grants of that type and filter them in Ruby (the capability lists are JSON), then query with `WHERE id IN (...)`. That suits hundreds of grants per member; for far more, keep your own index of granted ids.
+
+Configuration:
+
+```ruby
+config.full_resource_access_role = :admin           # roles at or above see every record; nil = grants limit every role
+config.grant_capabilities = nil                     # or a list of allowed names
+config.grant_management_permission = :edit_member_roles
+```
 
 ### Built-in roles
 
@@ -751,6 +1125,10 @@ owner > admin > member > viewer
 
 Each role inherits all permissions from roles below it.
 
+A role acts only on roles at or below its own in `Roles.hierarchy`. That covers invitations (the invited role), role changes (both the old and the new role), removals (the removed member's role) and invitation management (revoking or resending an invitation for a role). Below admin, a role must also hold every permission of the role it acts on, because two custom roles with the same parent are ranked only by definition order. So a custom role with `invite_members`, `edit_member_roles` and `remove_members` cannot invite, promote, demote or remove an admin, cannot hand out a sibling role with powers it lacks, and cannot touch an admin's invitation. Admins and the owner keep the rank rule alone, and the owner keeps its own rules.
+
+The check applies to the member passed as `invited_by:`, `changed_by:`, `removed_by:`, `revoked_by:` or `resent_by:`. The engine controllers always pass the current user. A nil actor, or one who is not a member of the organization, is not checked, so pass the acting user whenever you call these methods from your own code. A few paths take no actor and are never checked: `add_member!`, `approve_join_request!`, `Invitation#accept!` (the invitation was checked when it was sent) and direct `Membership` writes. A refusal raises `Organizations::NotAuthorized`, which the engine controllers answer through `config.unauthorized_handler` like any failed permission guard (an alert, or a 403 over JSON, by default). `membership.can_assign_role?(role)` tells you which roles to offer in a role picker, as the generated views do.
+
 ### Default permissions
 
 | Permission | viewer | member | admin | owner |
@@ -826,7 +1204,8 @@ require_organization_role!(:client)        # clients and everyone above them
 ```
 
 - A custom role gets its own permissions plus its parent's (the parent's defaults when the block does not redefine a built-in parent).
-- A custom role without `inherits:` sits at the bottom of the hierarchy. Two custom roles with the same parent stack in the order you define them, the first one highest.
+- A custom role without `inherits:` sits at the bottom of the hierarchy, below viewer. Two custom roles with the same parent stack in the order you define them, the first one highest.
+- Because a role acts only on roles at or below its own, a custom role without `inherits:` that can `invite_members` can invite only to its own role: inviting with the default `member` role raises `NotAuthorized`. Give such a role the parent it should invite to, for example `role :recruiter, inherits: :member do can :invite_members end`.
 - A block that only adds custom roles keeps the built-in roles' default permissions; a block that redefines a built-in role defines the built-in roles it lists, as before.
 - A custom role ranks below admin: it inherits from `member`, `viewer` or another custom role, never from `admin` or `owner`, so it never outranks the people who can assign it. A custom role also cannot grant a permission that the owner role has and the admin role lacks (`manage_billing`, `transfer_ownership`, `delete_organization` by default), because admins can assign it. A role name is lowercase letters, digits and underscores; a parent must be a built-in role or a custom role defined above it. Both are checked when the configuration loads.
 - Memberships, invitations, `default_invitation_role`, `add_member!`, promotions and demotions, `by_role_hierarchy` and every permission helper accept custom roles. The generated views list them in the role pickers.
@@ -992,7 +1371,7 @@ Expired invitations can be resent:
 
 ```ruby
 invitation.expired?   # => true
-invitation.resend!    # Generates new token, resets expiry, sends email
+invitation.resend!(resent_by: current_user)  # Generates new token, resets expiry, sends email
 ```
 
 ### Accepted invitations
@@ -1119,6 +1498,93 @@ Organizations.configure do |config|
 end
 ```
 
+### Personal organizations
+
+An auto-created organization is an ordinary organization: nothing in the database says that it is the user's own workspace. `user.organizations.first` is not a personal-workspace lookup. Turn on `record_personal_organizations` to keep a persistent link from the user to the one organization that is theirs:
+
+```ruby
+Organizations.configure do |config|
+  config.always_create_personal_organization_for_each_user = true
+  config.record_personal_organizations = true   # default: false
+end
+```
+
+```ruby
+user.personal_organization               # => the organization, or nil. Never creates anything.
+user.create_personal_organization!       # creates it, or returns the existing one
+user.create_personal_organization!("Ana's space")
+
+org.personal?                            # => true
+org.personal_owner                       # => the user
+Organizations::Organization.personal     # every personal organization
+Organizations::Organization.not_personal # every other organization
+```
+
+The rules:
+
+- The link is `organizations.personal_owner_id`, with a unique index. A user has at most one personal organization.
+- The personal owner is also the owner membership. The gem writes both together, and `create_with_owner!` and `create_organization!` refuse a `personal_owner` who is not the new owner. `org.transfer_ownership_to!` raises `CannotTransferPersonalOrganization` for a personal organization: call `org.convert_to_shared!` first.
+- A personal organization can have other members. To keep it owner-only, veto joins in the membership gate, which covers every join path:
+
+  ```ruby
+  config.on_member_joining do |ctx|
+    raise Organizations::MembershipVetoed, "This is a personal workspace." if ctx.organization.personal?
+  end
+  ```
+
+- Sign-up provisioning logs a failure and keeps the user, as before. `user.create_personal_organization!` is the repair path: it is idempotent, and concurrent calls converge on one organization.
+- An invited sign-up that skips auto-creation (see "Pattern 4: Hybrid Onboarding") gets no personal organization.
+- Existing organizations stay unclassified after the upgrade. The gem never guesses from a name, a member count or the oldest organization. To link organizations that you have reviewed, pass the mapping:
+
+  ```ruby
+  report = Organizations::Organization.backfill_personal_owners!({ user => org, other_user.id => other_org.id }, dry_run: true)
+  report.assignments  # => [[user_id, organization_id], ...]
+  report.unchanged    # pairs that are already linked
+  report.conflicts    # => [{ user_id:, organization_id:, reason: :not_the_owner }, ...]
+  Organizations::Organization.backfill_personal_owners!(mapping)  # writes nothing when any pair conflicts
+  ```
+
+  Conflict reasons: `:organization_not_found`, `:not_the_owner`, `:organization_personal_for_another_user`, `:user_has_another_personal_organization`, `:organization_mapped_twice`, `:user_mapped_twice`. The write runs in its own savepoint: a conflict found at write time (a concurrent provisioning) rolls back every assignment and comes back in the report.
+
+A personal organization tells you who probably pays. Billing and entitlements stay with your app.
+
+## Deleting user accounts
+
+By default a user who owns an organization cannot be deleted: `user.destroy` returns false with an error, and `user.destroy!` raises `ActiveRecord::RecordNotDestroyed`. Transfer ownership or delete those organizations first. The gem cannot cancel subscriptions or call external services for you, so run those steps in your own account-closure workflow, after the deletion commits.
+
+Preview what a deletion would do. Nothing changes, and nothing is locked: the plan is a preview for a confirmation screen, and only `user.destroy` decides.
+
+```ruby
+plan = user.account_deletion_plan
+plan.allowed?                  # => false
+plan.blockers                  # => [#<struct organization=#<Organization "Acme">, reason=:owns_organization_with_members>]
+plan.organizations_to_destroy  # organizations deleted with the account
+plan.memberships_to_remove     # the user's other memberships, removed with the account
+plan.to_h                      # ids and symbols, for an audit log or a confirmation screen
+user.account_deletion_plan(policy: :destroy_personal_organization)  # preview another policy
+```
+
+Apps with personal organizations can let a user delete their account together with their personal organization:
+
+```ruby
+config.account_deletion_policy = :destroy_personal_organization   # default: :prevent
+```
+
+| The user owns… | `:prevent` | `:destroy_personal_organization` |
+|---|---|---|
+| nothing | deleted | deleted |
+| their personal organization, as its only member | blocked (`:personal_organization`) | deleted with the organization |
+| their personal organization, with other members | blocked (`:personal_organization_with_members`) | blocked |
+| another organization, as its only member | blocked (`:owns_organization`) | blocked |
+| another organization, with other members | blocked (`:owns_organization_with_members`) | blocked |
+
+What the gem guarantees:
+
+- It checks the complete owned set before it deletes anything. One blocker blocks the whole deletion.
+- The organization deletion and the user deletion are one transaction, with its own savepoint, also inside a transaction of yours. A host `before_destroy` veto on the organization, or any later failure, rolls back everything, and the veto message is on `user.errors`.
+- The guard locks the user row and then the owned organization rows. A concurrent join or organization creation for that user, a join or transfer in an owned organization, and an ownership transfer to that user (`transfer_ownership_to!` locks the new owner's row) wait for the deletion, or finish first and are seen by it.
+- The user's other memberships are deleted (`dependent: :destroy`), as before. Invitations they sent, join requests they decided, join codes they created and allowlist entries they claimed keep the record and lose the user reference.
+
 ## User Onboarding Patterns
 
 The `always_create_personal_organization_for_each_user` setting controls how new users get their first organization. This is one of the most important decisions when integrating the gem.
@@ -1286,6 +1752,10 @@ Full configuration options:
 # config/initializers/organizations.rb
 Organizations.configure do |config|
   # === Authentication ===
+  # Class name of your user model (default: "User"). Set it before the gem's
+  # models load (initializers are fine).
+  config.user_class = "User"
+
   # Method that returns the current user (default: :current_user)
   config.current_user_method = :current_user
 
@@ -1299,6 +1769,14 @@ Organizations.configure do |config|
   # Name for auto-created organizations
   config.default_organization_name = ->(user) { "Personal" }
 
+  # Record the auto-created organization as user.personal_organization (default: false)
+  config.record_personal_organizations = false
+
+  # What deleting a user who owns organizations does (default: :prevent).
+  # :destroy_personal_organization also deletes their personal organization
+  # when they are its only member. See "Deleting user accounts".
+  config.account_deletion_policy = :prevent
+
   # === Invitations ===
   # How long invitations are valid
   config.invitation_expiry = 7.days
@@ -1306,6 +1784,39 @@ Organizations.configure do |config|
   # Custom mailer for invitations
   config.invitation_mailer = "Organizations::InvitationMailer"
 
+  # Role of invited members when the inviter names none (default: :member)
+  config.default_invitation_role = :member
+
+  # === Verified joining ===
+  # A custom mailer needs code_email(join_request, plaintext_code) returning a
+  # message (the gem calls .deliver_later). The plaintext code exists only in
+  # that call: never store or log it.
+  config.verification_mailer = "Organizations::VerificationMailer"
+  config.verification_code_ttl = 15.minutes          # emailed codes always expire
+  config.verification_max_attempts = 5               # wrong codes per challenge
+  config.verification_resend_interval = 60.seconds   # between code sends
+  config.verification_max_sends = 5                  # code sends per join request
+  config.verification_email_normalizer = nil         # nil = downcase, strip, drop +tag; or ->(email) { ... }
+  config.trust_confirmed_account_email = true        # confirmed account email = proof of inbox (join_with_account_email!)
+  config.join_request_expiry = 30.days               # nil = pending requests never expire
+  config.join_code_generator = nil                   # nil = 8 characters without lookalikes; or -> { ... }
+
+  # === Scoped resource grants (see "Scoped resource grants") ===
+  config.full_resource_access_role = :admin           # nil = grants limit every role
+  config.grant_capabilities = nil                     # or %i[read edit ...]
+  config.grant_management_permission = :edit_member_roles
+
+  # === Vocabulary (see "Vocabulary") ===
+  config.vocabulary = nil                             # or :classroom, or ->(organization) { ... }
+
+  # === Domain authority (see "Domain authority") ===
+  config.require_verified_domains = false             # admit only through verified domains
+  config.domain_verification_record_prefix = "_organizations-verification"
+  config.domain_verification_ttl = 7.days
+  config.domain_verification_timeout = 5              # seconds
+  config.domain_txt_resolver = nil                    # nil = Resolv; or ->(name) { [String] }
+  config.blocked_email_domains = []                   # e.g. Organizations::PUBLIC_EMAIL_DOMAINS
+
   # === Limits ===
   # Maximum organizations a user can own (nil = unlimited)
   config.max_organizations_per_user = nil
@@ -1347,12 +1858,19 @@ Organizations.configure do |config|
   config.no_organization_alert = "Please create an organization first."
   config.no_organization_notice = "Please create or join an organization to continue."
 
+  # === Session ===
+  # Session key that stores the current organization id
+  config.session_key = :current_organization_id
+
   # === Organizations Controller ===
   # Additional params to permit when creating/updating organizations
   # Use this to add custom fields like support_email, billing_email, logo
   config.additional_organization_params = [:support_email]
 
   # === Engine Controllers ===
+  # Engine route groups to draw (nil = all). See "Installation".
+  config.engine_routes = { except: [:organizations] }
+
   # Base controller for authenticated routes (default: ::ApplicationController)
   config.parent_controller = "::ApplicationController"
 
@@ -1367,6 +1885,9 @@ Organizations.configure do |config|
   config.authenticated_controller_layout = "dashboard"
   config.public_controller_layout = "devise"
 
+  # Host helper modules for the public (invitation) pages
+  config.public_controller_helpers = ["ApplicationHelper"]
+
   # === Handlers ===
   # Called when authorization fails
   config.on_unauthorized do |context|
@@ -1389,7 +1910,12 @@ Organizations.configure do |config|
   end
 
   config.on_member_invited do |ctx|
-    # ctx.organization, ctx.invitation, ctx.invited_by
+    # ctx.organization, ctx.invitation, ctx.invited_by (strict: raise to veto)
+  end
+
+  config.on_member_joining do |ctx|
+    # THE membership gate (strict): raise Organizations::MembershipVetoed to veto
+    # ctx.organization, ctx.user, ctx.role, ctx.joined_via, ctx.invitation / ctx.join_request
   end
 
   config.on_member_joined do |ctx|
@@ -1407,6 +1933,11 @@ Organizations.configure do |config|
   config.on_ownership_transferred do |ctx|
     # ctx.organization, ctx.old_owner, ctx.new_owner
   end
+
+  config.on_join_request_created { |ctx| }    # ctx.organization, ctx.user, ctx.join_request
+  config.on_join_request_approved { |ctx| }   # …, ctx.membership, ctx.decided_by (nil when automatic)
+  config.on_join_request_rejected { |ctx| }   # …, ctx.decided_by
+  config.on_verification_delivery_failed { |ctx| }   # ctx.metadata["error_class"], ["error_message"]
 end
 ```
 
@@ -1641,7 +2172,7 @@ ActiveSupport.on_load(:organizations_membership) do
 end
 ```
 
-**Why load hooks and not `class_eval` in an initializer:** the gem's model classes are reload-safe under Zeitwerk (they reload in development), and an initializer runs ONCE — a bare `class_eval` patch evaporates on the first code reload, and a hand-rolled `to_prepare` block is one shared basket where a single bad constant silently kills every extension after it. Load hooks re-fire per model on every reload ([ActiveSupport::LazyLoadHooks](https://api.rubyonrails.org/classes/ActiveSupport/LazyLoadHooks.html)). One hook per model: `:organizations_organization`, `:organizations_membership`, `:organizations_invitation`, `:organizations_domain`, `:organizations_join_code`, `:organizations_allowlist_entry`, `:organizations_join_request`, plus `:organizations_application_controller` and `:organizations_public_controller` for the engine controllers.
+**Why load hooks and not `class_eval` in an initializer:** the gem's model classes are reload-safe under Zeitwerk (they reload in development), and an initializer runs ONCE — a bare `class_eval` patch evaporates on the first code reload, and a hand-rolled `to_prepare` block is one shared basket where a single bad constant silently kills every extension after it. Load hooks re-fire per model on every reload ([ActiveSupport::LazyLoadHooks](https://api.rubyonrails.org/classes/ActiveSupport/LazyLoadHooks.html)). One hook per model: `:organizations_organization`, `:organizations_membership`, `:organizations_invitation`, `:organizations_domain`, `:organizations_join_code`, `:organizations_allowlist_entry`, `:organizations_join_request`, `:organizations_grant`, plus `:organizations_application_controller` and `:organizations_public_controller` for the engine controllers.
 
 For the common public-controller case — host layouts on the invitation-acceptance pages need your app's helper modules (the public controller inherits `ActionController::Base`, not your `ApplicationController`) — use the declarative option instead:
 
@@ -1676,7 +2207,44 @@ class Portal::BaseController < ApplicationController
 end
 ```
 
-You get `current_scoped_organization` / `current_scoped_membership` (also as view helpers), and a configurable not-found posture: the default raises `ActionController::RoutingError`, so **unknown orgs, strangers, and under-role members are indistinguishable** — no existence oracle, the right stance for customer-facing portals. Set `self.organization_not_found_behavior = :forbidden` for internal tools where a 403 is fine. Both addressing modes coexist in one app — the concern never touches the session context.
+Gate actions by permission instead of rank with `require_organization_permission :invite_members` (custom roles included; it takes `only:`/`except:` like any `before_action`). You get `current_scoped_organization` / `current_scoped_membership` (also as view helpers), and a configurable not-found posture: the default raises `ActionController::RoutingError`, so **unknown orgs, strangers, and under-role members are indistinguishable** — no existence oracle, the right stance for customer-facing portals. Set `self.organization_not_found_behavior = :forbidden` for internal tools where a 403 is fine. Both addressing modes coexist in one app — the concern never touches the session context.
+
+### URL handles (slugs)
+
+`OrganizationScoped` finds organizations by id unless you give it a finder. To address them by a handle such as `/org/acme/admin`, add the column yourself; the gem ships no slug schema:
+
+```ruby
+# db/migrate/xxx_add_handle_to_organizations.rb
+class AddHandleToOrganizations < ActiveRecord::Migration[8.1]
+  def change
+    add_column :organizations_organizations, :handle, :string
+    add_index :organizations_organizations, :handle, unique: true   # the database decides uniqueness
+  end
+end
+```
+
+```ruby
+# app/models/concerns/organization_handle.rb (register it with the :organizations_organization load hook)
+module OrganizationHandle
+  extend ActiveSupport::Concern
+  RESERVED = %w[admin api new settings join access].freeze   # paths your app uses
+
+  included do
+    before_validation { self.handle = handle.to_s.strip.downcase.presence }
+    validates :handle, format: { with: /\A[a-z0-9][a-z0-9-]{1,38}[a-z0-9]\z/ }, exclusion: { in: RESERVED }, allow_nil: true
+  end
+end
+```
+
+```ruby
+self.organization_param  = :handle
+self.organization_finder = ->(handle) { Organizations::Organization.find_by(handle: handle.to_s.downcase) }
+```
+
+- **Backfill populated installs before you require the column.** Generate a handle from the name, and on a collision add a suffix (`acme`, `acme-2`). The unique index catches the last race: rescue `ActiveRecord::RecordNotUnique` and try the next suffix.
+- **Do not override `to_param` globally.** The engine's routes find organizations by id, and every generated URL would break. Pass the handle explicitly in your own routes: `portal_path(handle: org.handle)`.
+- **Renames break old links.** Keep the old handle in a lookup table and redirect, or freeze handles after creation.
+- An existing slug gem (FriendlyId and others) works too: point `organization_finder` at its finder.
 
 ## Internationalization (i18n)
 
@@ -1692,7 +2260,83 @@ en:
       join_code_invalid: "Hmm, that code doesn't work."
 ```
 
-Two deliberate boundaries: developer-facing errors (`ArgumentError`, `ConfigurationError`) stay English, and custom roles defined via `config.roles` fall back to `humanize` unless you add a matching `organizations.roles.<name>` key.
+Two deliberate boundaries: developer-facing errors (`ArgumentError`, `ConfigurationError`) stay English, and custom roles defined via `config.roles` fall back to `humanize` unless you add a matching `organizations.roles.<name>` key. For wording that differs per organization, see "Vocabulary" below.
+
+### Vocabulary: different words for different organizations
+
+A school calls its members students; a library calls them patrons. For one wording everywhere, override the ordinary keys as shown above. For organizations that need different wording, select a vocabulary:
+
+```ruby
+# One vocabulary for the whole app
+config.vocabulary = :classroom
+
+# Or one per organization, from your own data (called only with an organization)
+config.vocabulary = ->(organization) { organization.metadata["vocabulary"] }
+```
+
+Then add only the keys that differ, under `organizations.vocabularies.<name>`:
+
+```yaml
+# config/locales/en.yml
+en:
+  organizations:
+    vocabularies:
+      classroom:
+        roles:
+          member: "Student"
+          admin: "Teacher"
+        mailers:
+          invitation:
+            # A full sentence, not a noun inserted into an English sentence:
+            # other languages need their own word order.
+            subject: "%{inviter} added you to the class %{organization}"
+      library:
+        roles:
+          member: "Patron"
+```
+
+Pass the organization record:
+
+```ruby
+Organizations.t("roles.member", organization: school)    # => "Student"
+Organizations.t("roles.member", organization: library)   # => "Patron"
+Organizations.t("roles.owner", organization: school)     # => "Owner" (missing in the vocabulary: the ordinary key)
+Organizations.t("roles.member")                          # => "Member" (no organization: the resolver is not called)
+organization_role_label(:member, organization: school)   # view helper => "Student"
+```
+
+The rules:
+
+- **Lookup order:** when the vocabulary has the key, in the current locale or one of its I18n fallbacks, it wins. Otherwise the call is exactly the ordinary one: the `organizations.*` key with your overrides, then the caller's `default:` (Symbol defaults keep the `organizations.` scope). A resolver that returns `nil` selects the ordinary keys. Calls with an Array of keys or a custom `scope:` skip the vocabulary.
+- **A vocabulary entry is a complete translation.** Its interpolation variables must be supplied, and a plural entry needs every form your locale uses; I18n raises on a gap there instead of falling back to the ordinary key.
+- **`%{organization}`** interpolates the record's name. Only an `Organizations::Organization` record (or a subclass) selects a vocabulary; a String, a presenter or `nil` stays a plain interpolation value, as before.
+- **A vocabulary name is one label** (letters, digits, underscores). A resolver that raises or returns another name selects the ordinary wording and logs a warning. When the name comes from data that organization admins can edit, check it against your list of vocabularies.
+- **Count, interpolation and locale work as in I18n.** For plurals, give the vocabulary key `one:`/`other:` (and the other forms your locales need):
+
+  ```ruby
+  Organizations.t("members_count", organization: school, count: 3)   # => "3 students"
+  ```
+
+- **The organization is always explicit.** The gem never reads it from the session or a thread-global. Its own controllers, models and mailers pass the organization they act on, so two organizations rendered in one request, or interleaved jobs, never share wording.
+- **Mailers and background jobs:** pass the organization and set the locale, as with any I18n call:
+
+  ```ruby
+  I18n.with_locale(user.locale) do
+    Organizations.t(:"mailers.invitation.subject", organization: invitation.organization, inviter: inviter.name)
+  end
+  ```
+
+- **`_html` keys** in your own views go through the Rails `t` helper (it escapes interpolations). Get the lookup chain from the gem:
+
+  ```erb
+  <% primary, *fallbacks = Organizations.i18n_keys(:"mailers.invitation.invited_by_html", organization: @organization) %>
+  <%= t(primary, default: fallbacks, inviter: @inviter_name, organization: @organization.name) %>
+  ```
+
+- **Display text only.** Calling an admin a teacher changes no stored role name, permission or authorization.
+- **Custom mailers and copied mailer views** that pass `organization: @organization.name` keep working, with the ordinary wording. Pass the record (`organization: @organization`) to get the vocabulary.
+- **Views copied before 0.7.0** print `role.capitalize`. To adopt vocabularies, change those calls to `organization_role_label(role, organization: the_organization)`, as the current `rails g organizations:views` templates do.
+- **Join codes keep one generic message.** The invalid-code and exhausted-code errors ignore the vocabulary, so a code's message never reveals which organization it belongs to.
 
 ## Database schema
 
@@ -1708,6 +2352,7 @@ organizations_organizations
   - name (string, required)
   - memberships_count (integer, counter cache, default: 0)
   - metadata (jsonb, default: {})
+  - personal_owner_id (foreign key to users, nullable, unique; ON DELETE SET NULL)
   - created_at / updated_at
 ```
 
@@ -1751,6 +2396,23 @@ organizations_invitations
   partial unique index: [organization_id, lower(email)] where accepted_at is null
 ```
 
+### organizations_grants (optional, `rails g organizations:grants`)
+
+```sql
+organizations_grants
+  - id
+  - membership_id (foreign key, nullable; ON DELETE CASCADE)
+  - invitation_id (foreign key, nullable; ON DELETE CASCADE) — exactly one of the two (check constraint)
+  - grantable_type (string) / grantable_id (the app's key type by default)
+  - capabilities (jsonb array, at least one)
+  - granted_by_id (foreign key to users, nullable; ON DELETE SET NULL)
+  - created_at / updated_at
+
+  unique index: [membership_id, grantable_type, grantable_id]
+  unique index: [invitation_id, grantable_type, grantable_id]
+  index: [grantable_type, grantable_id]
+```
+
 ### organizations_domains
 
 ```sql
@@ -1758,6 +2420,11 @@ organizations_domains
   - id, organization_id (foreign key)
   - domain (string, required — stored lowercased, no leading '@')
   - membership_metadata / metadata (jsonb, default: {})
+  - join_policy (string, default: 'none': none|suggest|auto_join)
+  - verification_token (string, nullable) / verification_started_at (datetime)
+  - verified_at (datetime) / verification_method (string: dns_txt|operator)
+  - verified_by_id (foreign key to users, nullable; ON DELETE SET NULL)
+  - verification_revoked_at (datetime)
   - created_at / updated_at
 
   unique index: [organization_id, domain]; index: [domain] (email → candidate orgs)
@@ -1949,16 +2616,6 @@ current_organization  # Returns cached (subsequent calls)
 current_organization  # Returns cached
 ```
 
-### Bulk operations
-
-For bulk invitations (coming in roadmap), the gem will support skipping per-record callbacks:
-
-```ruby
-# Future API
-org.bulk_invite!(emails, skip_callbacks: true)
-# Fires on_bulk_invited once instead of on_member_invited N times
-```
-
 ## Data integrity
 
 The gem handles concurrent access and race conditions to ensure data consistency.
@@ -2023,7 +2680,7 @@ user.leave_organization!(org)
 
 **Role changes:**
 ```ruby
-membership.promote_to!(:admin)
+membership.promote_to!(:admin, changed_by: current_user)
 
 # Internally:
 # 1. Lock membership row
@@ -2160,9 +2817,23 @@ Afterwards: `has_organizations` on `User`, move your model code into an extensio
 git clone https://github.com/rameerez/organizations
 cd organizations
 bin/setup
-bundle exec rake test
+bundle exec rake            # the test suite and RuboCop, as CI runs them
+
+# Against each supported Rails version (Appraisal)
+bundle exec appraisal install
+bundle exec appraisal rails-7.2 rake
+bundle exec appraisal rails-8.1 rake
+
+# The demo app and its HTTP suite (it is also the source of the generator templates)
+cd test/dummy
+bundle install
+bin/rails tailwindcss:build
+bin/rails db:test:prepare
+bin/rails test
 ```
 
+CI runs the suite on Ruby 3.3, 3.4 and 4.0 against Rails 7.2 and 8.1, once against PostgreSQL, plus RuboCop and the demo app's suite.
+
 ## Contributing
 
 Bug reports and pull requests are welcome on GitHub at https://github.com/rameerez/organizations. Our code of conduct is: just be nice and make your mom proud of what you do and post online.