account_authz 0.1.0

data/app/models/concerns/account_authz/member.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module AccountAuthz
+  module Member
+    extend ActiveSupport::Concern
+
+    included do
+      has_many :account_authz_assignments, as: :member, class_name: "AccountAuthz::Assignment", dependent: :destroy
+      has_many :account_authz_roles, through: :account_authz_assignments, source: :role
+    end
+
+    def assign_role(role)
+      account_authz_assignments.find_or_create_by(role: role)
+    end
+
+    def revoke_role(role)
+      account_authz_assignments.where(role: role).destroy_all
+    end
+
+    def capabilities(account_id: nil)
+      roles = account_id ? account_authz_roles.where(account_id: account_id) : account_authz_roles
+      roles.flat_map(&:capabilities).uniq.map(&:to_sym)
+    end
+
+    def can?(capability, account_id: nil)
+      AccountAuthz.can?(capabilities(account_id: account_id), capability)
+    end
+
+    def approved_metrics(account_id: nil)
+      AccountAuthz.approved_metrics(capabilities(account_id: account_id))
+    end
+  end
+end

data/app/policies/account_authz/application_policy.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module AccountAuthz
+  class ApplicationPolicy
+    attr_reader :member, :record
+
+    def initialize(member, record)
+      @member = member
+      @record = record
+    end
+
+    def can?(capability)
+      Current.account_id.present? && member.can?(capability, account_id: Current.account_id)
+    end
+  end
+end

data/app/views/account_authz/invitations/new.html.erb

@@ -0,0 +1,10 @@
+<%= ui_page(max_width: :md) do %>
+  <%= ui_form_page(title: "Invite", back_url: members_path, subtitle: "Members") %>
+  <%= ui_panel do %>
+    <%= ui_form(action: invitations_path) do %>
+      <%= ui_form_field(attribute: "invitation[name]", label: "Name", required: true) %>
+      <%= ui_form_field(attribute: "invitation[email]", label: "Email", type: :email, required: true) %>
+      <%= ui_button(label: "Invite") %>
+    <% end %>
+  <% end %>
+<% end %>

data/app/views/account_authz/members/_team.html.erb

@@ -0,0 +1,84 @@
+<%
+  account = AccountAuthz::AccountId.from(account)
+  chosen = selection[:member_id].presence
+  members = AccountAuthz.members_source.members(account)
+  held_roles = AccountAuthz::Assignment.where(member: members.to_a, role: AccountAuthz::Role.in_account(account)).includes(:role)
+    .group_by(&:member_id).transform_values { |assignments| assignments.map(&:role) }
+  invitations = AccountAuthz.members_source.invitations(account)
+%>
+
+<%= ui_section(title: "Team") do %>
+  <%= ui_data_table(
+        items: members.map { |member| {member_id: member.id, name: member.name, email: member.email, roles: held_roles.fetch(member.id, []).map(&:name).join(", ").presence || "None"} },
+        columns: [Keystone::Ui::Column.new(:name, "Name"), Keystone::Ui::Column.new(:email, "Email", mobile_hidden: true), Keystone::Ui::Column.new(:roles, "Roles")],
+        empty_message: "No members yet"
+      ) do |table| %>
+    <% table.link(:name) { |row| "?member_id=#{row[:member_id]}" } %>
+  <% end %>
+<% end %>
+
+<% person_chosen = chosen && members.find { |member| member.id.to_s == chosen.to_s } %>
+<% if person_chosen %>
+  <%
+    reach = AccountAuthz::Reach.new(AccountAuthz::ActingMember.for(person: person, account: account), account_id: account)
+    last_manager = AccountAuthz::LastManager.new(account_id: account)
+    held = AccountAuthz::Assignment.where(member: person_chosen, role: AccountAuthz::Role.in_account(account)).includes(:role).map(&:role)
+    within_reach = AccountAuthz::Role.in_account(account).select { |role| reach.includes_role?(role) }
+  %>
+  <%= ui_section(title: person_chosen.name, subtitle: person_chosen.email) do %>
+    <%= ui_panel do %>
+      <div style="display: flex; flex-wrap: wrap; gap: 0.5rem;">
+        <% (held & within_reach).reject { |role| last_manager.lost_by_taking?(person_chosen, role) }.each do |role| %>
+          <%= ui_form(action: submit_urls[:take_role], method: :patch) do %>
+            <%= hidden_field_tag :member_id, person_chosen.id, id: nil %>
+            <%= hidden_field_tag :role_id, role.id, id: nil %>
+            <%= ui_button(label: "Take #{role.name}", variant: :danger, size: :sm) %>
+          <% end %>
+        <% end %>
+        <% (within_reach - held).each do |role| %>
+          <%= ui_form(action: submit_urls[:give_role], method: :patch) do %>
+            <%= hidden_field_tag :member_id, person_chosen.id, id: nil %>
+            <%= hidden_field_tag :role_id, role.id, id: nil %>
+            <%= ui_button(label: "Give #{role.name}", variant: :secondary, size: :sm) %>
+          <% end %>
+        <% end %>
+      </div>
+
+      <% if AccountAuthz.members_source.removable?(person_chosen) && !last_manager.lost_by_removing?(person_chosen) %>
+        <%= ui_form(action: submit_urls[:remove], method: :patch) do %>
+          <%= hidden_field_tag :member_id, person_chosen.id, id: nil %>
+          <%= ui_button(label: "Remove from team", variant: :danger, size: :sm) %>
+        <% end %>
+      <% end %>
+    <% end %>
+  <% end %>
+<% end %>
+
+<%= ui_section(title: "Invite") do %>
+  <%= ui_panel do %>
+    <%= ui_form(action: submit_urls[:invite], method: :patch) do %>
+      <%= ui_form_field(attribute: "name", label: "Name", required: true) %>
+      <%= ui_form_field(attribute: "email", label: "Email", type: :email, required: true) %>
+      <%= ui_button(label: "Invite") %>
+    <% end %>
+  <% end %>
+<% end %>
+
+<%= ui_section(title: "Invited") do %>
+  <%= ui_data_table(
+        items: invitations.map { |invitation| {invitation_id: invitation.id, name: invitation.name, email: invitation.email} },
+        columns: [Keystone::Ui::Column.new(:name, "Name"), Keystone::Ui::Column.new(:email, "Email", mobile_hidden: true)],
+        empty_message: "No invitations"
+      ) do |table| %>
+    <% table.actions do |row| %>
+      <%= ui_form(action: submit_urls[:resend], method: :patch) do %>
+        <%= hidden_field_tag :invitation_id, row[:invitation_id], id: nil %>
+        <%= ui_button(label: "Send again", variant: :secondary, size: :sm) %>
+      <% end %>
+      <%= ui_form(action: submit_urls[:cancel], method: :patch) do %>
+        <%= hidden_field_tag :invitation_id, row[:invitation_id], id: nil %>
+        <%= ui_button(label: "Cancel", variant: :danger, size: :sm) %>
+      <% end %>
+    <% end %>
+  <% end %>
+<% end %>

data/app/views/account_authz/members/index.html.erb

@@ -0,0 +1,59 @@
+<%= ui_page(max_width: :lg) do %>
+  <%= ui_page_header(title: "Members") do |header| %>
+    <% if can?(AccountAuthz.roles_capability) %>
+      <% header.action do %>
+        <%= ui_button(label: "Roles", href: roles_path, variant: :secondary) %>
+      <% end %>
+    <% end %>
+  <% end %>
+
+  <% if can?(AccountAuthz.roles_capability) %>
+    <%= ui_mobile_actions do %>
+      <%= link_to "Roles", roles_path %>
+    <% end %>
+  <% end %>
+
+  <%= ui_section(title: "Team", action: {label: "Invite", href: new_invitation_path}) do %>
+    <%
+      member_columns = [
+        Keystone::Ui::Column.new(:name, "Name"),
+        Keystone::Ui::Column.new(:email, "Email", mobile_hidden: true),
+        Keystone::Ui::Column.new(:roles, "Roles")
+      ]
+      member_rows = @members.map do |member|
+        held = @held_roles.fetch(member.id, [])
+        {
+          member: member,
+          name: member.name,
+          email: member.email,
+          roles: held.any? ? held.map(&:name).join(", ") : "None"
+        }
+      end
+    %>
+    <%= ui_data_table(items: member_rows, columns: member_columns, empty_message: "No members yet") do |table| %>
+      <% table.link(:name) { |row| member_path(row[:member]) } %>
+    <% end %>
+  <% end %>
+
+  <%= ui_section(title: "Invited") do %>
+    <%
+      invitation_columns = [
+        Keystone::Ui::Column.new(:name, "Name"),
+        Keystone::Ui::Column.new(:email, "Email", mobile_hidden: true)
+      ]
+      invitation_rows = @invitations.map do |invitation|
+        { invitation: invitation, name: invitation.name, email: invitation.email }
+      end
+    %>
+    <%= ui_data_table(items: invitation_rows, columns: invitation_columns, empty_message: "No invitations") do |table| %>
+      <% table.actions do |row| %>
+        <%= ui_form(action: resend_invitation_path(row[:invitation])) do %>
+          <%= ui_button(label: "Send again", variant: :secondary, size: :sm) %>
+        <% end %>
+        <%= ui_form(action: invitation_path(row[:invitation]), method: :delete) do %>
+          <%= ui_button(label: "Cancel", variant: :danger, size: :sm) %>
+        <% end %>
+      <% end %>
+    <% end %>
+  <% end %>
+<% end %>

data/app/views/account_authz/members/show.html.erb

@@ -0,0 +1,38 @@
+<%= ui_page(max_width: :lg) do %>
+  <%= ui_show_page(title: @member.name, back_url: members_path, subtitle: @member.email) %>
+  <%= ui_section(title: "Roles") do %>
+    <%= ui_panel do %>
+      <% if @held.any? %>
+        <div style="display: flex; flex-wrap: wrap; gap: 0.5rem;">
+          <% @held.each do |role| %>
+            <%= ui_badge(label: role.name, variant: :info) %>
+          <% end %>
+        </div>
+      <% end %>
+    <% end %>
+
+    <% if @reach.includes_roles?(@held) %>
+      <%= ui_panel do %>
+        <div style="display: flex; flex-wrap: wrap; gap: 0.5rem;">
+          <% (@held & @roles).reject { |role| @last_manager.lost_by_taking?(@member, role) }.each do |role| %>
+            <%= ui_form(action: member_role_path(@member, role), method: :delete) do %>
+              <%= ui_button(label: "Take #{role.name}", variant: :danger, size: :sm) %>
+            <% end %>
+          <% end %>
+          <% (@roles - @held).each do |role| %>
+            <%= ui_form(action: member_roles_path(@member)) do %>
+              <%= hidden_field_tag :role_id, role.id, id: nil %>
+              <%= ui_button(label: "Give #{role.name}", variant: :secondary, size: :sm) %>
+            <% end %>
+          <% end %>
+        </div>
+      <% end %>
+
+      <% if AccountAuthz.members_source.removable?(@member) && !@last_manager.lost_by_removing?(@member) %>
+        <%= ui_form(action: member_path(@member), method: :delete) do %>
+          <%= ui_button(label: "Remove from team", variant: :danger, size: :sm) %>
+        <% end %>
+      <% end %>
+    <% end %>
+  <% end %>
+<% end %>

data/app/views/account_authz/roles/_form.html.erb

@@ -0,0 +1,16 @@
+<% held = Array(role.capabilities).map(&:to_s) %>
+<%= ui_panel do %>
+  <%= ui_form(action: url, method: form_method) do %>
+    <%= hidden_field_tag "role[capabilities][]", "", id: nil %>
+    <%= ui_form_field(attribute: "role[name]", label: "Name", value: role.name, errors: role.errors.full_messages_for(:name)) %>
+    <%= ui_form_field(attribute: "role[rank]", label: "Rank", type: :number, min: 0, value: role.rank, hint: "A member manages members and roles ranked below their highest role.") %>
+    <%= ui_section(title: "Capabilities", spacing: :sm) do %>
+      <%= ui_grid(cols: { default: 1, sm: 2 }, gap: :sm) do %>
+        <% AccountAuthz.capabilities.each do |capability| %>
+          <%= ui_checkbox_row(name: "role[capabilities][]", value: capability.to_s, label: capability.to_s, checked: held.include?(capability.to_s)) %>
+        <% end %>
+      <% end %>
+    <% end %>
+    <%= ui_button(label: "Save") %>
+  <% end %>
+<% end %>

data/app/views/account_authz/roles/edit.html.erb

@@ -0,0 +1,4 @@
+<%= ui_page(max_width: :md) do %>
+  <%= ui_form_page(title: "Edit role", back_url: roles_path) %>
+  <%= render "form", role: @role, url: role_path(@role), form_method: :patch %>
+<% end %>

data/app/views/account_authz/roles/index.html.erb

@@ -0,0 +1,21 @@
+<%= ui_page(max_width: :lg) do %>
+  <%= ui_button(label: "Members", href: members_path, variant: :secondary, size: :sm) %>
+  <%= ui_section(title: "Roles", action: { label: "New role", href: new_role_path }) do %>
+    <% rows = @roles.map { |role| { role: role, name: role.name, capabilities: Array(role.capabilities).size } } %>
+    <%= ui_data_table(items: rows, columns: [{ name: "Name" }, { capabilities: "Capabilities" }], empty_message: "No roles yet") do |table| %>
+      <% table.link(:name) { |row| edit_role_path(row[:role]) } %>
+    <% end %>
+  <% end %>
+  <% if AccountAuthz.templates.defaults.any? %>
+    <%= ui_section(title: "Templates") do %>
+      <%= ui_grid(cols: { default: 1, sm: 2 }, gap: :sm) do %>
+        <% AccountAuthz.templates.defaults.each do |template| %>
+          <%= ui_form(action: roles_path) do %>
+            <%= hidden_field_tag :template, template.name, id: nil %>
+            <%= ui_button(label: "Add #{template.role_name}", variant: :secondary, size: :sm) %>
+          <% end %>
+        <% end %>
+      <% end %>
+    <% end %>
+  <% end %>
+<% end %>

data/app/views/account_authz/roles/new.html.erb

@@ -0,0 +1,4 @@
+<%= ui_page(max_width: :md) do %>
+  <%= ui_form_page(title: "New role", back_url: roles_path) %>
+  <%= render "form", role: @role, url: roles_path, form_method: :post %>
+<% end %>

data/config/locales/en.yml

@@ -0,0 +1,10 @@
+en:
+  account_authz:
+    refusals:
+      role_out_of_reach: "You can only give or take roles ranked below your own."
+      member_out_of_reach: "You can only change members ranked below you."
+      last_manager: "Someone else needs to be able to manage members first."
+      not_removable: "This member can't be removed from the account."
+      capabilities_out_of_reach: "You can only give a role capabilities you have yourself."
+      rank_out_of_reach: "You can only set a rank up to your own."
+      role_edit_out_of_reach: "You can only change roles ranked below your own."

data/config/routes.rb

@@ -0,0 +1,9 @@
+AccountAuthz::Engine.routes.draw do
+  resources :members, only: [ :index, :show, :destroy ] do
+    resources :roles, only: [ :create, :destroy ], controller: "member_roles"
+  end
+  resources :roles, only: [ :index, :new, :create, :edit, :update ]
+  resources :invitations, only: [ :new, :create, :destroy ] do
+    post :resend, on: :member
+  end
+end

data/db/migrate/20260607000001_create_citizen_roles.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+class CreateCitizenRoles < ActiveRecord::Migration[8.1]
+  def change
+    create_table :citizen_roles do |t|
+      t.bigint :account_id, null: false
+      t.string :name, null: false
+      t.json :capabilities, null: false, default: []
+
+      t.timestamps
+    end
+
+    add_index :citizen_roles, :account_id
+  end
+end

data/db/migrate/20260607000002_create_citizen_assignments.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+class CreateCitizenAssignments < ActiveRecord::Migration[8.1]
+  def change
+    create_table :citizen_assignments do |t|
+      t.references :member, polymorphic: true, null: false
+      t.references :role, null: false
+
+      t.timestamps
+    end
+
+    add_index :citizen_assignments, %i[member_type member_id role_id], unique: true,
+      name: "index_citizen_assignments_unique"
+  end
+end

data/db/migrate/20260916000001_add_rank_to_citizen_roles.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+class AddRankToCitizenRoles < ActiveRecord::Migration[8.1]
+  def change
+    add_column :citizen_roles, :rank, :integer, null: false, default: 0
+  end
+end

data/db/migrate/20260921220000_rename_citizen_tables_to_account_authz.rb

@@ -0,0 +1,9 @@
+class RenameCitizenTablesToAccountAuthz < ActiveRecord::Migration[8.1]
+  def change
+    rename_table :citizen_roles, :account_authz_roles
+    rename_table :citizen_assignments, :account_authz_assignments
+    rename_index :account_authz_assignments,
+      "index_citizen_assignments_unique",
+      "index_account_authz_assignments_unique"
+  end
+end

data/lib/account_authz/catalog.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module AccountAuthz
+  class Catalog
+    attr_reader :permissions, :metrics
+
+    def initialize
+      @permissions = []
+      @metrics = []
+    end
+
+    def permission(key)
+      @permissions << key
+    end
+
+    def metric(key)
+      @metrics << key
+    end
+
+    def capabilities
+      permissions + metrics
+    end
+  end
+end

data/lib/account_authz/engine.rb

@@ -0,0 +1,7 @@
+require "keystone_ui"
+
+module AccountAuthz
+  class Engine < ::Rails::Engine
+    isolate_namespace AccountAuthz
+  end
+end

data/lib/account_authz/reference/guide.md

@@ -0,0 +1,227 @@
+## AccountAuthz
+
+> **DO NOT** explore the account_authz gem source code. This reference is the complete
+> user-facing API, embedded verbatim into every account_authz local so their guidance
+> never drifts. Keep it the single source of truth.
+
+AccountAuthz is capability-based authorization for multi-tenant Rails apps:
+**capabilities are code, roles are data, Pundit enforces.** The app declares a
+fixed catalog of capabilities in code; accounts manage roles (data) that bundle
+those capabilities; AccountAuthz resolves what a member may do (`can?`) and which
+metrics they may see (`approved_metrics`), and plugs into Pundit for enforcement.
+It is a mountable Rails engine.
+
+### What it offers
+
+**Catalog (code).** Declare the fixed set of capabilities — `permission` and
+`metric` keys — the software supports:
+
+```ruby
+AccountAuthz.catalog do
+  permission :view_fulfillment
+  metric :revenue
+  metric :deals
+end
+
+AccountAuthz.catalog.permissions   # => [:view_fulfillment]
+AccountAuthz.catalog.metrics       # => [:revenue, :deals]
+AccountAuthz.capabilities          # => [:view_fulfillment, :revenue, :deals]
+AccountAuthz.reset!                # clears the catalog and templates (mainly for tests)
+```
+
+**Resolution.** Decide from a member's granted capabilities:
+
+```ruby
+AccountAuthz.can?(grants, :view_fulfillment)   # => true/false (grants.include?)
+AccountAuthz.approved_metrics(grants)          # => catalog metrics ∩ grants
+```
+
+**Roles (data).** `AccountAuthz::Role` is account-scoped: `account_id`, `name`
+(required), and `capabilities` (a JSON array). A role's capabilities must be a
+subset of `AccountAuthz.capabilities` — unknown keys fail validation.
+
+```ruby
+AccountAuthz::Role.in_account(account_id)                              # scope
+AccountAuthz::Role.create!(account_id:, name:, capabilities: %w[...])  # blank add
+AccountAuthz::Role.from_template(account_id:, template: :sales)        # one-click add
+```
+
+**Templates + seeding.** Templates are seed *data* for roles; capabilities stay
+code:
+
+```ruby
+AccountAuthz.templates do
+  template :sales, capabilities: %w[view_fulfillment revenue], default: true
+end
+
+AccountAuthz.templates.find(:sales)          # => the Template
+AccountAuthz.templates.defaults              # => templates flagged default: true
+AccountAuthz.seed_default_roles(account_id)  # one role per default template (idempotent)
+```
+
+**Members.** Include `AccountAuthz::Member` in the record that represents a person
+*inside one account* — an account membership, not the person. A role belongs to
+one account, so holding it on the membership means it can only apply where the
+person belongs and it goes when the membership goes. Where an app has no such
+record, the person can hold roles and every check passes `account_id:`, which
+scopes resolution to one account (nil = all roles):
+
+```ruby
+member.assign_role(role)
+member.revoke_role(role)
+member.account_authz_roles
+member.capabilities(account_id: 1)        # union of role capabilities (symbols)
+member.can?(:view_fulfillment, account_id: 1)
+member.approved_metrics(account_id: 1)
+```
+
+**Pundit bridge.** Policies inherit `AccountAuthz::ApplicationPolicy` —
+`initialize(member, record)` with `#can?(capability)` delegating to
+`member.can?` within `AccountAuthz::Current.account_id`, and denying when no current
+account is set. Controllers include `AccountAuthz::Authorization` (which mixes in
+`Pundit::Authorization` and exposes a `can?` helper). `AccountAuthz::Current.account_id`
+scopes per-request resolution.
+
+**Members page (engine).** Mount the engine and a member who holds the members
+capability in the current account sees each member's name, email and roles in
+that account, with a button to give each of the account's roles the member does
+not hold and to take away each one they do. It lists the account's invitations
+still waiting for an answer, each with a button to send it again and one to
+cancel it. The page also invites a person by name and email, and removes a member from the account, which first takes away
+every role they held in it. Anyone else, or a request with no current account,
+gets 403. Only the current account's members and roles can be changed.
+
+```ruby
+mount AccountAuthz::Engine => "/account_authz"   # members page at /account_authz/members
+
+AccountAuthz.members_source = AccountMembers
+AccountAuthz.members_capability = :manage_team   # default :manage_members
+
+class AccountMembers
+  def self.members(account_id) = Membership.where(account_id: account_id)
+  def self.invite(account_id:, name:, email:, invited_by:) = Invitation.send_to(account_id, name, email, invited_by)
+  def self.invitations(account_id) = Invitation.where(account_id: account_id)
+  def self.resend_invitation(invitation) = invitation.send_again
+  def self.cancel_invitation(invitation) = invitation.destroy!
+  def self.removable?(member) = !member.owner?
+  def self.remove(member) = member.destroy!
+end
+```
+
+The source's `members(account_id)` returns the account's members as a relation that responds to `find`, `invite` sends the app's own invitation, `invitations(account_id)` returns the ones still waiting as a relation that responds to `find`, `resend_invitation` sends one again, `cancel_invitation` withdraws one, `removable?` says whether a member may be removed at all (such as the account owner), and `remove` takes the member off the account; each responds to `name` and `email`. A source may also answer `member_for(account_id:, person:)`, which gives back the membership a signed-in person holds in that account — needed when a host app hands the person rather than their membership, and left out when the two are the same thing
+and includes `AccountAuthz::Member`. Engine controllers inherit the host's
+`ApplicationController`, so the host's sign-in, `current_member` and
+`AccountAuthz::Current.account_id` apply. The page renders with keystone_ui inside the
+layout the host's `ApplicationController` uses, so the host loads keystone_ui's
+styles. Route helpers in that layout, such as `root_path`, reach the host's own
+routes without a `main_app.` prefix.
+
+**Role pages (engine).** The members page links to them with a Roles link
+shown only to people who hold the roles capability, and the roles page links
+back to the members page, so an app needs one navigation entry for both. At `/account_authz/roles`, a member who holds the roles
+capability in the current account lists that account's roles, creates a role
+with a name and chosen capabilities, adds a role from each default template,
+and renames a role or changes its capabilities. Anyone else, or a request with
+no current account, gets 403, and another account's roles cannot be changed.
+
+```ruby
+AccountAuthz.roles_capability = :manage_team   # default :manage_roles
+```
+
+**Ranks (who may manage whom).** Each role has an integer `rank` (default 0),
+set on the role form. A manager gives or takes only roles ranked below their
+highest role in the account, and changes only members whose highest role ranks
+below it. A manager holding a role at the account's top rank reaches every
+member and role. The members page shows only the changes the viewer may make,
+and a refused change sent directly gets 403. `AccountAuthz::Reach` answers the same
+questions for host code:
+
+```ruby
+reach = AccountAuthz::Reach.new(current_member, account_id: account.id)
+reach.includes_member?(member)   # => true/false
+reach.includes_role?(role)       # => true/false
+```
+
+**Keeping a member manager.** An account always keeps at least one member who
+holds the members capability. Taking away that member's last members role,
+removing that member, or unticking the members capability on the only role
+anyone holds it through is refused with 403, and the members page hides those
+buttons. `AccountAuthz::LastManager` answers the same questions for host code:
+
+```ruby
+last_manager = AccountAuthz::LastManager.new(account_id: account.id)
+last_manager.lost_by_taking?(member, role)          # => true/false
+last_manager.lost_by_removing?(member)              # => true/false
+last_manager.lost_by_changing?(role, capabilities)  # => true/false
+```
+
+**Editor limits.** On the role pages an editor can only create or add roles
+with capabilities they hold themselves, including roles added from a template,
+can only set a rank up to their own highest role, and can only change roles
+ranked below their own unless they hold the account's top rank.
+`reach.includes_capabilities?(capabilities)` and `reach.includes_rank?(rank)`
+answer the same questions for host code.
+
+**Refused changes.** When a manager tries a change their rank or the last
+manager rule does not allow, account_authz sends them back to the page they came from
+with a flash alert saying why, and changes nothing. The host's layout shows the
+flash. Reword a message under `account_authz.refusals` in the app's locale files:
+
+```yaml
+en:
+  account_authz:
+    refusals:
+      role_out_of_reach: "You can only give or take roles ranked below your own."
+      member_out_of_reach: "You can only change members ranked below you."
+      last_manager: "Someone else needs to be able to manage members first."
+      not_removable: "This member can't be removed from the account."
+      capabilities_out_of_reach: "You can only give a role capabilities you have yourself."
+      rank_out_of_reach: "You can only set a rank up to your own."
+      role_edit_out_of_reach: "You can only change roles ranked below your own."
+```
+
+A request from someone without the page's capability still gets 403.
+
+### Install
+
+AccountAuthz is a Rails engine; install it correctly with the engine flow — not a
+plain `gem install`:
+
+1. Add the gem (git source until it is on RubyGems), then `bundle install`:
+   ```ruby
+   gem "account_authz", github: "DYB-Development/account_authz", branch: "main"
+   ```
+2. Install and run the engine's migrations — this creates the `account_authz_roles`
+   and `account_authz_assignments` tables:
+   ```bash
+   bin/rails account_authz:install:migrations
+   bin/rails db:migrate
+   ```
+3. Declare the capability catalog in code (e.g. `config/initializers/account_authz.rb`)
+   with `AccountAuthz.catalog do … end`.
+4. Include `AccountAuthz::Member` in the host's member/role-holding model.
+5. Include `AccountAuthz::Authorization` in `ApplicationController`, and set
+   `AccountAuthz::Current.account_id` per request (e.g. a `before_action`).
+6. Optional: declare templates with `AccountAuthz.templates`, and call
+   `AccountAuthz.seed_default_roles(account_id)` when provisioning a new account.
+
+7. Optional: mount `AccountAuthz::Engine` and set `AccountAuthz.members_source` to serve
+   the members page.
+
+AccountAuthz owns no role *storage* beyond its own tables. The host signs members in,
+sets the current account, and supplies the members the members page lists.
+
+### AccountAuthz conventions
+
+- **A member is a person inside one account.** Include `AccountAuthz::Member` in the
+  membership record rather than the person, so roles cannot outlive the
+  membership or reach an account the person never joined.
+- **Capabilities are code, roles are data.** Define capability keys only in the
+  catalog; never persist capability *definitions* as data, and never hardcode
+  role *records* in code (seed them from templates instead).
+- A role's `capabilities` must be a subset of the catalog — adding an unknown key
+  is a validation error, by design.
+- Resolution is grant-based: `can?` tests membership in the union of the
+  member's role capabilities, optionally scoped by `account_id`.
+- Enforce through Pundit policies via `can?(capability)`; don't re-derive
+  permissions ad hoc in controllers or views.

data/lib/account_authz/reference.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module AccountAuthz
+  # Single source of truth for account_authz's user-facing API, read by the
+  # the_local companion subagents so their guidance never drifts from the docs.
+  module Reference
+    DIR = File.expand_path("reference", __dir__)
+
+    def self.content
+      read("guide.md")
+    end
+
+    def self.read(name)
+      File.read(File.join(DIR, name)).chomp
+    end
+  end
+end