account_authz 0.1.2 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 349b6e1097c3f9cd3f4211488f800e5132418138e0785573f2810dde8e87287d
-  data.tar.gz: 9cf6c1e7593dc3bd6e814df1df72d5f0caa488bd868407cf3098e6f189a3950d
+  metadata.gz: 2a6d242a905644ec6879015808f39da3e4b74d95768602bd45dccd36568cb818
+  data.tar.gz: 535257175b0c79d2a1606d07ac9d1926849e22886d35aec0a4dddf8c894cde70
 SHA512:
-  metadata.gz: 02b2a2acf869db601b2cf5470565ef64920543c01c027f21575b22d5e16d98f1ac8e679d9759d9f9f0698f17ee65acc719bd01a147a428ca087aec4d0620e6fa
-  data.tar.gz: 403e200dd7e81b20319415fbce054f10dd4cbfa9327faa7ddccf399c042fd91c70c03f16f7ecb18269cc86315a56087d942b161127776f6224c68a5361d75ea6
+  metadata.gz: db728919480a0a9624bcc39fbab70fef43005076e964dc0f9d7367a37b63d61fbcb0272fbe241c26f592309b4d26a3bfa6fffccb0d9d90c25b051d9cb7a39f53
+  data.tar.gz: 54f0e3b29af7748fd4b93ece0ff5bea6f90e16718a6bd3e0e8a5bc125bd133a483ccb4f8ba672a404d8b057a434e357c669bdf73cfeffe9f7a11f4955209a441

data/app/controllers/account_authz/members_controller.rb

@@ -9,7 +9,7 @@ module AccountAuthz
     end
 
     def show
-      @member = AccountAuthz.members_source.members(Current.account_id).find(params[:id])
+      @member = AccountAuthz.find_member(Current.account_id, params[:id])
       @held = Assignment.where(member: @member, role: Role.in_account(Current.account_id)).includes(:role).map(&:role)
       @reach = reach
       @last_manager = LastManager.new(account_id: Current.account_id)

data/app/controllers/account_authz/roles_controller.rb

@@ -26,11 +26,11 @@ module AccountAuthz
     end
 
     def edit
-      @role = Role.in_account(Current.account_id).find(params[:id])
+      @role = Role.in_account(Current.account_id).find_by_public_code!(params[:id])
     end
 
     def update
-      role = Role.in_account(Current.account_id).find(params[:id])
+      role = Role.in_account(Current.account_id).find_by_public_code!(params[:id])
       return refuse(:role_edit_out_of_reach, back_to: roles_path) unless reach.includes_role?(role)
       return refuse(:rank_out_of_reach, back_to: edit_role_path(role)) if role_params.key?(:rank) && !reach.includes_rank?(role_params[:rank])
       return refuse(:capabilities_out_of_reach, back_to: edit_role_path(role)) unless reach.includes_capabilities?(Array(role_params[:capabilities]) - role.capabilities)

data/app/models/account_authz/cancel_invitation.rb

@@ -17,7 +17,7 @@ module AccountAuthz
     private
 
     def invitation
-      AccountAuthz.members_source.invitations(@account).find(@values[:invitation_id])
+      AccountAuthz.find_invitation(@account, @values[:invitation_id])
     end
   end
 end

data/app/models/account_authz/give_role.rb

@@ -24,11 +24,11 @@ module AccountAuthz
     end
 
     def member
-      @member ||= AccountAuthz.members_source.members(@account).find(@values[:member_id])
+      @member ||= AccountAuthz.find_member(@account, @values[:member_id])
     end
 
     def role
-      @role ||= Role.in_account(@account).find(@values[:role_id])
+      @role ||= Role.in_account(@account).find_by_public_code!(@values[:role_id])
     end
   end
 end

data/app/models/account_authz/remove_member.rb

@@ -28,7 +28,7 @@ module AccountAuthz
     end
 
     def member
-      @member ||= AccountAuthz.members_source.members(@account).find(@values[:member_id])
+      @member ||= AccountAuthz.find_member(@account, @values[:member_id])
     end
   end
 end

data/app/models/account_authz/resend_invitation.rb

@@ -17,7 +17,7 @@ module AccountAuthz
     private
 
     def invitation
-      AccountAuthz.members_source.invitations(@account).find(@values[:invitation_id])
+      AccountAuthz.find_invitation(@account, @values[:invitation_id])
     end
   end
 end

data/app/models/account_authz/role.rb

@@ -2,6 +2,7 @@
 
 module AccountAuthz
   class Role < ApplicationRecord
+    has_public_code
     validates :name, presence: true
     validate :capabilities_within_catalog
     after_save { Current.capabilities = {} }

data/app/models/account_authz/take_role.rb

@@ -25,11 +25,11 @@ module AccountAuthz
     end
 
     def member
-      @member ||= AccountAuthz.members_source.members(@account).find(@values[:member_id])
+      @member ||= AccountAuthz.find_member(@account, @values[:member_id])
     end
 
     def role
-      @role ||= Role.in_account(@account).find(@values[:role_id])
+      @role ||= Role.in_account(@account).find_by_public_code!(@values[:role_id])
     end
   end
 end

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

@@ -9,7 +9,7 @@
 
 <%= 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"} },
+        items: members.map { |member| {member_id: member.to_param, 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| %>
@@ -17,7 +17,13 @@
   <% end %>
 <% end %>
 
-<% person_chosen = chosen && members.find { |member| member.id.to_s == chosen.to_s } %>
+<%
+  person_chosen = begin
+    chosen && AccountAuthz.find_member(account, chosen)
+  rescue ActiveRecord::RecordNotFound
+    nil
+  end
+%>
 <% if person_chosen %>
   <%
     reach = AccountAuthz::Reach.new(AccountAuthz::ActingMember.for(person: person, account: account), account_id: account)
@@ -30,15 +36,15 @@
       <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 %>
+            <%= hidden_field_tag :member_id, person_chosen.to_param, id: nil %>
+            <%= hidden_field_tag :role_id, role.to_param, 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 %>
+            <%= hidden_field_tag :member_id, person_chosen.to_param, id: nil %>
+            <%= hidden_field_tag :role_id, role.to_param, id: nil %>
             <%= ui_button(label: "Give #{role.name}", variant: :secondary, size: :sm) %>
           <% end %>
         <% end %>
@@ -46,7 +52,7 @@
 
       <% 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 %>
+          <%= hidden_field_tag :member_id, person_chosen.to_param, id: nil %>
           <%= ui_button(label: "Remove from team", variant: :danger, size: :sm) %>
         <% end %>
       <% end %>
@@ -66,7 +72,7 @@
 
 <%= ui_section(title: "Invited") do %>
   <%= ui_data_table(
-        items: invitations.map { |invitation| {invitation_id: invitation.id, name: invitation.name, email: invitation.email} },
+        items: invitations.map { |invitation| {invitation_id: invitation.to_param, 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| %>

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

@@ -21,7 +21,7 @@
           <% end %>
           <% (@roles - @held).each do |role| %>
             <%= ui_form(action: member_roles_path(@member)) do %>
-              <%= hidden_field_tag :role_id, role.id, id: nil %>
+              <%= hidden_field_tag :role_id, role.to_param, id: nil %>
               <%= ui_button(label: "Give #{role.name}", variant: :secondary, size: :sm) %>
             <% end %>
           <% end %>

data/db/migrate/20261012230000_add_public_code_to_account_authz_roles.rb

@@ -0,0 +1,17 @@
+class AddPublicCodeToAccountAuthzRoles < ActiveRecord::Migration[8.1]
+  class Record < ActiveRecord::Base
+    self.table_name = "account_authz_roles"
+  end
+
+  def up
+    add_column :account_authz_roles, :public_code, :string
+    Record.reset_column_information
+    Record.find_each { |record| record.update_columns(public_code: PublicCode.generate) }
+    change_column_null :account_authz_roles, :public_code, false
+    add_index :account_authz_roles, :public_code, unique: true
+  end
+
+  def down
+    remove_column :account_authz_roles, :public_code
+  end
+end

data/lib/account_authz/reference/guide.md

@@ -116,6 +116,17 @@ 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.
 
+**Addresses.** Every role carries a random code from the public_code gem, and
+the role pages and the Give and Take buttons address a role by it, so a
+numbered role address is not found. Members and invitations are addressed by
+whatever `to_param` the host's records give. A source that also answers
+`member(account_id, address)` and `invitation(account_id, address)` is asked for
+the member or invitation at an address, which is how an app whose members carry
+codes, or whose invitations are addressed by a token, has them found. A source
+that answers neither has them found with `find` on `members(account_id)` and
+`invitations(account_id)`, by id. Role assignments still point at members and
+roles by id.
+
 **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

data/lib/account_authz/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module AccountAuthz
-  VERSION = "0.1.2"
+  VERSION = "0.2.0"
 end

data/lib/account_authz.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require "public_code"
 require_relative "account_authz/version"
 require_relative "account_authz/engine"
 require_relative "account_authz/catalog"
@@ -38,6 +39,18 @@ module AccountAuthz
             .map { |template| Role.from_template(account_id: account_id, template: template.name) }
   end
 
+  def self.find_member(account_id, address)
+    return members_source.member(account_id, address) if members_source.respond_to?(:member)
+
+    members_source.members(account_id).find(address)
+  end
+
+  def self.find_invitation(account_id, address)
+    return members_source.invitation(account_id, address) if members_source.respond_to?(:invitation)
+
+    members_source.invitations(account_id).find(address)
+  end
+
   def self.reset!
     @catalog = nil
     @templates = nil

data/the_local/agents/account_authz-develop.md

@@ -1,6 +1,6 @@
 ---
 name: account_authz-develop
-description: Use PROACTIVELY for declaring capabilities (permissions and metrics), defining role templates, seeding an account's default roles, creating roles, ranking roles so a manager can change only members and roles below them, assigning or revoking a member's roles, checking whether one member may change another member's roles, checking whether an editor may create or edit a role with a given rank and capabilities, checking whether taking a role, removing a member, or changing a role's capabilities would leave an account with nobody who can manage its members, checking whether a member can do something, filtering which metrics a member may see, writing Pundit policies that gate actions on a capability, choosing which members the members page lists, how it invites a person to an account, which invitations it shows as still waiting for an answer, how it sends one again and cancels one, and how it removes a member from an account, and which capability lets a member open it to invite, send an invitation again, cancel one, remove a member, and give and take roles, choosing which capability lets a member open the role pages to create and edit roles, which viewers see the links between the members page and the role pages, and showing or rewording the message a manager sees when the members page or role pages refuse a change — MUST BE USED instead of hand-rolling role checks, permission flags, role hierarchies, limits on the rank or capabilities an editor may give a role, last-admin checks, role management screens, member invite, waiting invitation or removal screens, refusal messages, or ad hoc authorization in controllers and views.
+description: Use PROACTIVELY for declaring capabilities (permissions and metrics), defining role templates, seeding an account's default roles, creating roles, ranking roles so a manager can change only members and roles below them, assigning or revoking a member's roles, checking whether one member may change another member's roles, checking whether an editor may create or edit a role with a given rank and capabilities, checking whether taking a role, removing a member, or changing a role's capabilities would leave an account with nobody who can manage its members, checking whether a member can do something, filtering which metrics a member may see, writing Pundit policies that gate actions on a capability, choosing which members the members page lists, how it finds a member or an invitation addressed by a code or token, how it invites a person to an account, which invitations it shows as still waiting for an answer, how it sends one again and cancels one, and how it removes a member from an account, and which capability lets a member open it to invite, send an invitation again, cancel one, remove a member, and give and take roles, choosing which capability lets a member open the role pages to create and edit roles, which viewers see the links between the members page and the role pages, and showing or rewording the message a manager sees when the members page or role pages refuse a change — MUST BE USED instead of hand-rolling role checks, permission flags, role hierarchies, limits on the rank or capabilities an editor may give a role, last-admin checks, role management screens, member invite, waiting invitation or removal screens, refusal messages, or ad hoc authorization in controllers and views.
 tools: Read, Write, Edit, Grep
 scope: authorization — capability catalog, roles, and Pundit enforcement in multi-tenant Rails apps
 ---
@@ -9,7 +9,7 @@ You implement authorization in a host app that already has account_authz install
 
 ## What account_authz is
 
-AccountAuthz is capability-based authorization for multi-tenant Rails apps. The app declares a fixed list of capability keys in code, each account holds roles as records that bundle a subset of those keys, and a member's access is the union of the capabilities of the roles assigned to them. A member is a person's membership in one account, not the person, so a person who belongs to three accounts is three members, and an app with no membership record lets the person hold roles directly instead. Each role also has an integer rank, and a manager may change only members and roles ranked below the manager's highest role in the account. On account_authz's role pages, an editor may give a role only capabilities the editor holds and a rank no higher than the editor's own. AccountAuthz's members page and role pages refuse a change that would leave an account with nobody holding a role that grants the members capability. When they refuse a change for rank, for capabilities the editor does not hold, for the last member manager, or because a member may not be removed, they change nothing and send the manager back with a flash alert saying why. Fire this local when code needs to declare a capability, create, seed or rank roles, assign roles to a member, answer "may this member do X", answer "may this manager change this member or hand out this role", answer "may this editor create or edit this role with this rank and these capabilities", answer "would this change leave the account with no member manager", pick which metrics a member may see, write a policy that authorizes an action, decide who the members page lists, how it invites a person, which invitations it shows as still waiting and how it sends one again or cancels one, how it removes members, and who may open it, decide who may open the role pages to create and edit roles, or show or reword the message a refused change shows.
+AccountAuthz is capability-based authorization for multi-tenant Rails apps. The app declares a fixed list of capability keys in code, each account holds roles as records that bundle a subset of those keys, and a member's access is the union of the capabilities of the roles assigned to them. A member is a person's membership in one account, not the person, so a person who belongs to three accounts is three members, and an app with no membership record lets the person hold roles directly instead. Each role also has an integer rank, and a manager may change only members and roles ranked below the manager's highest role in the account. On account_authz's role pages, an editor may give a role only capabilities the editor holds and a rank no higher than the editor's own. AccountAuthz's members page and role pages refuse a change that would leave an account with nobody holding a role that grants the members capability. When they refuse a change for rank, for capabilities the editor does not hold, for the last member manager, or because a member may not be removed, they change nothing and send the manager back with a flash alert saying why. Fire this local when code needs to declare a capability, create, seed or rank roles, assign roles to a member, answer "may this member do X", answer "may this manager change this member or hand out this role", answer "may this editor create or edit this role with this rank and these capabilities", answer "would this change leave the account with no member manager", pick which metrics a member may see, write a policy that authorizes an action, decide who the members page lists, how it finds a member or invitation by address, how it invites a person, which invitations it shows as still waiting and how it sends one again or cancels one, how it removes members, and who may open it, decide who may open the role pages to create and edit roles, or show or reword the message a refused change shows.
 
 ## Interface
 
@@ -34,7 +34,7 @@ AccountAuthz is capability-based authorization for multi-tenant Rails apps. The
 - `member.can?` — `member.can?(capability, account_id: nil)` returns true when that union includes `capability`.
 - `member.approved_metrics` — `member.approved_metrics(account_id: nil)` returns the catalog metrics the member holds.
 - `AccountAuthz::ApplicationPolicy` — the base class for Pundit policies, taking `(member, record)`, exposing `member` and `record`, and providing `can?(capability)`.
-- `AccountAuthz.members_source` — `AccountAuthz.members_source = AccountMembers` sets the object the members page uses to list an account's members, invite a person, list the invitations still waiting for an answer, send one of those again, cancel one, ask whether a member may be removed, and remove a member, and it has no default.
+- `AccountAuthz.members_source` — `AccountAuthz.members_source = AccountMembers` sets the object the members page uses to list an account's members, find one member or invitation by its address, invite a person, list the invitations still waiting for an answer, send one of those again, cancel one, ask whether a member may be removed, and remove a member, and it has no default.
 - `AccountAuthz.members_capability` — `AccountAuthz.members_capability = :key` sets the capability a member needs in the current account to open the members page and invite, send an invitation again, cancel one, remove a member, or give or take roles on it, and it defaults to `:manage_members`.
 - `AccountAuthz.roles_capability` — `AccountAuthz.roles_capability = :key` sets the capability a member needs in the current account to open the role pages and create or edit roles on them, and it defaults to `:manage_roles`.
 - `AccountAuthz::Reach` — `AccountAuthz::Reach.new(manager, account_id:)` answers which members and roles `manager` may change in one account, and which ranks and capabilities `manager` may give a role there.
@@ -101,7 +101,7 @@ AccountAuthz is capability-based authorization for multi-tenant Rails apps. The
 
    A role grants the members capability when its capabilities include the key `AccountAuthz.members_capability` returns at the moment of the call. Every holder of such a role in the account counts, whether or not the members source returns them. A member who holds two such roles is not lost by taking one of them. Pass `lost_by_changing?` the role's complete new list of capability keys, as strings or symbols, not only the keys being removed. `lost_by_changing?` returns true even when nobody holds that role, as long as nobody holds another role in the account that grants the members capability. When nobody in the account holds a role granting the members capability, `lost_by_taking?` and `lost_by_removing?` return true for every member and role. A `LastManager` reads which of the account's roles grant the members capability once, so build a new one after a role's capabilities change. It checks only the account it was built for, and it checks neither rank, capabilities the editor holds, nor `removable?`, so combine it with `AccountAuthz::Reach` when one member changes another member or a role. Giving a role and creating a role are never refused by it.
 
-9. **Resolve access with the account id.** Pass the current account's id: `member.can?(:view_fulfillment, account_id: account_id)` and `member.approved_metrics(account_id: account_id)`. Omitting `account_id` resolves against every role the member holds, whatever account it belongs to. When the member is a membership that holds only its own account's roles, the answer is the same either way, but pass it anyway. When the person holds roles directly, omitting it counts their roles in every account. Pass capabilities as symbols, because `member.capabilities` returns symbols and a string never matches. When the grants are already in hand, use `AccountAuthz.can?(grants, :key)` and `AccountAuthz.approved_metrics(grants)` instead of querying again. Rank never affects `can?` or `approved_metrics`.
+9. **Resolve access with the account id.** Pass the current account's id: `member.can?(:view_fulfillment, account_id: account_id)` and `member.approved_metrics(account_id: account_id)`. Omitting `account_id` resolves against every role the member holds, whatever account it belongs to. When the member is a membership that holds only its own account's roles, the answer is the same either way, but pass it anyway. When the person holds roles directly, omitting it counts their roles in every account. Pass capabilities as symbols, because `member.capabilities` returns symbols and a string never matches. When the grants are already in hand, use `AccountAuthz.can?(grants, :key)` and `AccountAuthz.approved_metrics(grants)` instead of querying again. Rank never affects `can?` or `approved_metrics`. A member's capabilities in an account are read once per request and reused, and `assign_role`, `revoke_role` and saving a role clear what was read, so a role changed in the database any other way during the request is not seen until the next request.
 
 10. **Gate actions with policies.** Write each policy in `app/policies/` as a subclass of `AccountAuthz::ApplicationPolicy`, and define one query method per action it authorizes, because the base class defines none:
 
@@ -115,7 +115,9 @@ AccountAuthz is capability-based authorization for multi-tenant Rails apps. The
 
     The base class defines no `Scope`, so a policy used with `policy_scope` needs its own. The `member` a policy receives is the object Pundit passes as its user, and it must be an instance of the host's role-holding model. The base `can?(capability)` checks only the roles the member holds in the current request's account, and it returns false when no current account is set, so the request must set the current account before any policy runs. The controller `can?` helper follows the same rule.
 
-11. **Configure the members page, if the host serves it.** The page opens with a `Members` heading, which carries a `Roles` link to the roles page only when the viewer holds the roles capability in the current account. Under the heading is an invite form holding a required `Name` field, a required `Email` field and an `Invite` button, shown to every member who can open the page. Below it, the page lists each invitation the source says is still waiting for an answer, showing its name, its email, an `Invited` badge, a `Send again` button and a `Cancel` button, all shown to every member who can open the page. Below those, the page lists each member's name, email, and the names of the roles they hold in the current account. For each member the viewer reaches, it shows a button to take away each held role the viewer reaches, a button to give each of the current account's roles the viewer reaches that the member does not hold, and a `Remove` button when the source says that member may be removed. It leaves out a take button when `lost_by_taking?` is true for that member and role, and the `Remove` button when `lost_by_removing?` is true for that member. A member the viewer does not reach is listed with no buttons. The invite form and every button return to the page. The page creates no roles, so an account with no roles shows no give buttons. The members page and the role pages are drawn inside the layout the host's `ApplicationController` uses, so nothing in this step or the next changes how they look.
+11. **Configure the members pages, if the host serves them.** The members page opens with a `Members` heading, which carries a `Roles` link to the roles page only when the viewer holds the roles capability in the current account. Below it, a `Team` section with an `Invite` link lists each member's name, email, and the names of the roles they hold in the current account, or `None`, and each name opens that member's page. Below that, an `Invited` section lists each invitation the source says is still waiting for an answer, with its name, its email, a `Send again` button and a `Cancel` button, shown to every member who can open the page. The `Invite` link opens an invite page holding a required `Name` field, a required `Email` field and an `Invite` button. A member's page shows the member's name and email, a link back to the members page, and the roles they hold in the current account. When the viewer reaches the member, it also shows a `Take <role>` button for each held role the viewer reaches, a `Give <role>` button for each of the current account's roles the viewer reaches that the member does not hold, and a `Remove from team` button when the source says that member may be removed. It leaves out a take button when `lost_by_taking?` is true for that member and role, and the `Remove from team` button when `lost_by_removing?` is true for that member. A member the viewer does not reach is shown with no buttons. The invite form and every button return to the members page. The pages create no roles, so an account with no roles shows no give buttons. The members pages and the role pages are drawn inside the layout the host's `ApplicationController` uses, so nothing in this step or the next changes how they look.
+
+    Each member's page and each button for a member is addressed by the member's `to_param`, and each invitation button by the invitation's `to_param`, so whatever those return is the address account_authz later looks the record up by. Each `Give` and `Take` button addresses its role by the role's code, not its id.
 
     Write the source as an object with these seven methods, and a class with class methods works:
 
@@ -162,17 +164,39 @@ AccountAuthz is capability-based authorization for multi-tenant Rails apps. The
 
     Ask the developer what each of the seven methods does, because each depends on how the host stores which members belong to an account and how it invites people to one:
 
-    - `members(account_id)` returns the account's members. It must return a query that looks a record up by id with `find`, such as an Active Record relation, because giving or taking a role and removing a member find the member through it. Each record it returns must respond to `name` and `email` and be an instance of the host's role-holding model. A membership model often has neither, so ask the developer how it answers them, such as from the person record it belongs to. It is called with the current account's id on each page load, each give or take, and each removal.
-    - `invite(account_id:, name:, email:, invited_by:)` receives the current account's id, the name and email typed into the form, and the signed-in member who sent it. AccountAuthz sends no email, stores no invitation, and gives the invited person no role, so `invite` does what the host's invitation needs and the host builds the flow for accepting one. What `invite` stores is what `invitations` then lists. AccountAuthz does not check the name or email, so `invite` decides what to do with a blank, malformed, or already used email. Rank does not limit inviting. AccountAuthz ignores what `invite` returns and does not catch an error it raises.
-    - `invitations(account_id)` returns the account's invitations that are still waiting for an answer. It must return a query that looks a record up by id with `find`, such as an Active Record relation, because sending an invitation again and cancelling one find it through it. Each record it returns must respond to `name` and `email` and be routable by id. AccountAuthz filters nothing out of it, so an invitation the host has already accepted or expired stays on the page with both buttons until `invitations` stops returning it. It is called with the current account's id on each page load, each send again, and each cancel.
-    - `resend_invitation(invitation)` receives one invitation found through `invitations` and sends it again. AccountAuthz sends nothing itself and records nothing about the send. AccountAuthz ignores what it returns and does not catch an error it raises.
-    - `cancel_invitation(invitation)` withdraws one invitation found through `invitations`, so that `invitations` no longer returns it. Ask the developer whether cancelling destroys the record or marks it withdrawn, because account_authz only stops listing what `invitations` stops returning. AccountAuthz ignores what it returns and does not catch an error it raises.
-    - `removable?(member)` returns false for a member nobody may remove, such as the account owner. It receives only the member, not the manager removing them. It is called for each member the viewer reaches on every page load, and again on each removal.
+    - `members(account_id)` returns the account's members. Each record it returns must respond to `name` and `email` and be an instance of the host's role-holding model. A membership model often has neither, so ask the developer how it answers them, such as from the person record it belongs to. It is called with the current account's id on each load of the members page. When the source does not answer `member`, it must return a query that looks a record up with `find`, such as an Active Record relation, because the member's page, giving or taking a role, and removing a member find the member with `find` on it.
+    - `invite(account_id:, name:, email:, invited_by:)` receives the current account's id, the name and email typed into the form, and the signed-in member who sent it. AccountAuthz sends no email, stores no invitation, and gives the invited person no role, so `invite` does what the host's invitation needs and the host builds the flow for accepting one. What `invite` stores is what `invitations` then lists. AccountAuthz does not check the name or email, and passes `nil` for one a request leaves out, so `invite` decides what to do with a missing, blank, malformed, or already used email. Rank does not limit inviting. AccountAuthz ignores what `invite` returns and does not catch an error it raises.
+    - `invitations(account_id)` returns the account's invitations that are still waiting for an answer. Each record it returns must respond to `name`, `email` and `to_param`. AccountAuthz filters nothing out of it, so an invitation the host has already accepted or expired stays on the page with both buttons until `invitations` stops returning it. It is called with the current account's id on each load of the members page. When the source does not answer `invitation`, it must return a query that looks a record up with `find`, such as an Active Record relation, because sending an invitation again and cancelling one find it with `find` on it.
+    - `resend_invitation(invitation)` receives one invitation found by its address and sends it again. AccountAuthz sends nothing itself and records nothing about the send. AccountAuthz ignores what it returns and does not catch an error it raises.
+    - `cancel_invitation(invitation)` withdraws one invitation found by its address, so that `invitations` no longer returns it. Ask the developer whether cancelling destroys the record or marks it withdrawn, because account_authz only stops listing what `invitations` stops returning. AccountAuthz ignores what it returns and does not catch an error it raises.
+    - `removable?(member)` returns false for a member nobody may remove, such as the account owner. It receives only the member, not the manager removing them. It is called on each load of the page of a member the viewer reaches, and again on each removal.
     - `remove(member)` takes the member off the account, so that `members` no longer returns them. Before it runs, account_authz takes away every role the member holds in the current account and leaves their roles in other accounts alone. When the member is a membership, `remove` normally destroys it, and that deletes nothing in any other account. When the person holds roles directly, destroying the record also deletes their roles in every other account, and the page checks for a remaining member manager only in the current account, so ask the developer whether `remove` destroys the person or only detaches them from the account. Taking away the roles and calling `remove` run in one database transaction, so a `remove` that raises leaves the roles in place when the host's records share account_authz's database.
 
-    A give, take or removal for a member `members` does not return raises `ActiveRecord::RecordNotFound`. A give or take for a role outside the current account also raises `ActiveRecord::RecordNotFound` when the viewer reaches the member. A give or take for a member or role the viewer does not reach changes nothing and returns to the members page with a refusal message. So does a take when `lost_by_taking?` is true for that member and role. A removal does the same when the viewer does not reach the member, when `removable?` returns false, or when `lost_by_removing?` is true for that member. Step 13 lists which message each refusal shows. Sending again or cancelling an invitation `invitations` does not return raises `ActiveRecord::RecordNotFound`. Neither rank nor the last member manager limits the invitation buttons, so every member who can open the page may invite a person and send again or cancel any invitation the account is waiting on. An invite request that leaves out the name or the email fails with an error rather than a refusal message, because account_authz relies on the form requiring both. With no source set, every request to the page, the invite form and the buttons from a member who holds the capability raises an error.
+    The source may also answer three more methods. Ask the developer whether the host needs each one:
+
+    ```ruby
+    class AccountMembers
+      def self.member(account_id, address)
+        Membership.where(account_id: account_id).find_by!(code: address)
+      end
+
+      def self.invitation(account_id, address)
+        MembershipInvitation.waiting.where(account_id: account_id).find_by!(token: address)
+      end
+
+      def self.member_for(account_id:, person:)
+        Membership.find_by(account_id: account_id, person: person)
+      end
+    end
+    ```
+
+    - `member(account_id, address)` returns the member of that account at the address its `to_param` gives. Add it when members are addressed by a code or anything else `find` on `members` does not look up. When the source answers it, the member's page, giving or taking a role, and removing a member find the member only through it. AccountAuthz does not check that the record it returns belongs to the account, so it must return only a member of that account. It must raise `ActiveRecord::RecordNotFound` when no member is at the address, because account_authz does not handle `nil`.
+    - `invitation(account_id, address)` returns the waiting invitation of that account at the address its `to_param` gives. Add it when invitations are addressed by a token or anything else `find` on `invitations` does not look up. When the source answers it, sending an invitation again and cancelling one find the invitation only through it. AccountAuthz does not check that the record it returns belongs to the account or is still waiting, so it must return only such an invitation. It must raise `ActiveRecord::RecordNotFound` when no invitation is at the address, because account_authz does not handle `nil`.
+    - `member_for(account_id:, person:)` returns the membership the signed-in member holds in that account, or `nil`. Add it only when the host's signed-in member is the person rather than the membership that includes `AccountAuthz::Member`. When the source answers it, a give, take or removal measures the viewer's reach from the membership it returns, and from the signed-in member when it returns `nil`. The capability check that opens the pages, the buttons a member's page shows, and the `invited_by:` passed to `invite` still use the signed-in member as it is.
+
+    A member's page, give, take or removal for an address the member lookup does not find raises `ActiveRecord::RecordNotFound`. A give or take for a role address that is not the code of a role in the current account also raises `ActiveRecord::RecordNotFound` when the viewer reaches the member, and so does a role's id. A give or take for a member or role the viewer does not reach changes nothing and returns to the members page with a refusal message. So does a take when `lost_by_taking?` is true for that member and role. A removal does the same when the viewer does not reach the member, when `removable?` returns false, or when `lost_by_removing?` is true for that member. Step 13 lists which message each refusal shows. Sending again or cancelling an invitation at an address the invitation lookup does not find raises `ActiveRecord::RecordNotFound`. Neither rank nor the last member manager limits inviting or the invitation buttons, so every member who can open the members page may invite a person and send again or cancel any invitation the account is waiting on. An invite request that sends neither a name nor an email fails with an error rather than a refusal message. With no source set, every request to the members pages, the invite form and the buttons from a member who holds the capability raises an error, apart from opening the invite page.
 
-    Ask the developer which capability opens the page: the default `:manage_members`, or a key the app already uses for managing its team. The same capability is required to invite, send an invitation again, cancel one, remove a member, and give or take a role. Set it as a symbol, because a string never matches a member's capabilities. Declare that key in the catalog as a permission, because otherwise no role can grant it and every request to the page gets 403. A request with no signed-in member or no current account also gets 403.
+    Ask the developer which capability opens the members page, a member's page and the invite page: the default `:manage_members`, or a key the app already uses for managing its team. The same capability is required to invite, send an invitation again, cancel one, remove a member, and give or take a role. Set it as a symbol, because a string never matches a member's capabilities. Declare that key in the catalog as a permission, because otherwise no role can grant it and every request to those pages gets 403. A request with no signed-in member or no current account also gets 403.
 
     Tell the developer that the page refuses only the change that removes the last holder of a role granting the members capability. While another member still holds such a role, a manager at the account's top rank can take such a role from, or remove, any member `removable?` allows, including themselves.
 
@@ -182,7 +206,7 @@ AccountAuthz is capability-based authorization for multi-tenant Rails apps. The
     AccountAuthz.roles_capability = :manage_team
     ```
 
-    Ask the developer which capability opens the role pages: the default `:manage_roles`, or a key the app already uses for managing its team. It may be the same key as the members capability. Set it as a symbol, and declare it in the catalog as a permission, because otherwise no role can grant it and every request to the role pages gets 403. A request with no signed-in member or no current account also gets 403. Opening or saving the edit form for a role outside the current account raises `ActiveRecord::RecordNotFound`.
+    Ask the developer which capability opens the role pages: the default `:manage_roles`, or a key the app already uses for managing its team. It may be the same key as the members capability. Set it as a symbol, and declare it in the catalog as a permission, because otherwise no role can grant it and every request to the role pages gets 403. A request with no signed-in member or no current account also gets 403. Every role gets a random code when it is created, and the role pages address a role by that code, so a link to a role's edit form built from its id is not found. Opening or saving the edit form at an address that is not the code of a role in the current account raises `ActiveRecord::RecordNotFound`.
 
     The role pages limit what the editor, the member saving a form or pressing a template button, may do, using the same rules as `includes_role?`, `includes_rank?` and `includes_capabilities?` in step 7:
 

data/the_local/agents/account_authz-info.md

@@ -1,6 +1,6 @@
 ---
 name: account_authz-info
-description: Use to learn what account_authz offers — its capability catalog, account roles and ranks, members as account memberships, reach limits on who may manage whom, the rule that every account keeps a member manager, the members and role pages with their invitations and refusal messages, and Pundit enforcement.
+description: Use to learn what account_authz offers — its capability catalog, account roles and ranks, members as account memberships, reach limits on who may manage whom, the rule that every account keeps a member manager, the members, member, invite and role pages and the team section with their invitations and refusal messages, how roles, members and invitations are addressed, and Pundit enforcement.
 tools: Read
 scope: authorization — capability catalog, roles, and Pundit enforcement in multi-tenant Rails apps
 ---
@@ -23,20 +23,21 @@ bundling of those actions into roles is decided by each account. It is a Rails
 engine that stores roles and role assignments in its own tables, and it enforces
 through Pundit.
 
-It ships two sets of pages, drawn with keystone_ui inside the host's own layout.
-The role pages let a manager list, create and edit the account's roles, including
-each role's rank, limited to capabilities the manager holds, ranks up to their
-own, and roles ranked below them. The members page lets a manager invite a
-person, remove a member, and give a member a role or take one away, with removing
-and role changes limited to the members and roles ranked below the manager. It
-also lists the invitations still waiting for an answer, each with a button to
-send it again and one to cancel it. The members page links to the role pages and
-the role pages link back, so the host's navigation needs one link to reach both.
-Both sets of pages refuse any change that would leave the account with no member
-able to manage members, and tell the manager why a change was refused. The host
-app signs people in, sets which account a request belongs to, supplies the
-members and the waiting invitations the members page lists, sends the
-invitations, sends them again, cancels them, and carries out the removals.
+It ships pages drawn with keystone_ui inside the host's own layout. The role
+pages let a manager list, create and edit the account's roles, including each
+role's rank, limited to capabilities the manager holds, ranks up to their own,
+and roles ranked below them. The members page lists the account's members and
+the invitations still waiting for an answer, with a button to send each
+invitation again and one to cancel it, and an Invite button that opens a page
+for inviting a person. Each member's name opens a member page, where a manager
+gives the member a role, takes one away, or removes the member, limited to the
+members and roles ranked below the manager. The members page links to the role
+pages and the role pages link back, so the host's navigation needs one link to
+reach both. Every page refuses any change that would leave the account with no
+member able to manage members, and tells the manager why a change was refused.
+The host app signs people in, sets which account a request belongs to, supplies
+the members and the waiting invitations, sends the invitations, sends them
+again, cancels them, and carries out the removals.
 
 ## Interface
 
@@ -53,8 +54,10 @@ two locals:
   - asking whether a manager's rank reaches a member or a role, whether an editor
     may put a set of capabilities or a rank on a role, and whether a change would
     remove the account's last member manager;
-  - configuring the members page, including how it invites, lists the waiting
-    invitations, sends one again, cancels one and removes, and the role pages;
+  - configuring the members source the members pages read from, including how it
+    invites, lists the waiting invitations, sends one again, cancels one,
+    removes, and finds a member or an invitation at an address;
+  - configuring the role pages;
   - rewording the refusal messages.
 
 ## How to use it
@@ -62,14 +65,17 @@ two locals:
 Decide which of the two you need, then go there.
 
 - AccountAuthz is not yet in the app, a model or controller is not yet connected to
-  it, the engine is not yet mounted, or the migration that adds ranks has not
-  been installed after an update: use **account_authz-install**.
+  it, or the engine is not yet mounted: use **account_authz-install**.
+- An update added a migration, such as the one that adds ranks or the one that
+  gives every role a code, and it has not been installed: use
+  **account_authz-install**.
 - You are choosing which of the host's models holds roles: use
   **account_authz-install**.
 - AccountAuthz is connected and you are adding a capability, a role, a template, or a
   check on an action: use **account_authz-develop**.
-- AccountAuthz is connected and you are setting up the members page, its invitations
-  and removals, or the role pages: use **account_authz-develop**.
+- AccountAuthz is connected and you are setting up the members pages, their
+  invitations and removals, how members and invitations are found by address,
+  or the role pages: use **account_authz-develop**.
 - AccountAuthz is connected and you are adding a check in the host's own screens on
   who may manage whom, on which capabilities and ranks an editor may set, or on
   keeping a member manager, or changing the wording of a refusal message: use
@@ -85,6 +91,14 @@ Decide which of the two you need, then go there.
 - **Role** — a named set of capabilities belonging to one account, stored as
   data. A role with no name, or naming a capability the catalog does not
   contain, fails validation.
+- **Role code** — a random code every role carries, given when the role is
+  created. Roles made before the code existed get one when the migration that
+  adds it runs.
+- **Address** — what a page link or a submitted form uses to name a record. A
+  role is addressed by its code, so an address that names a role by its number
+  is not found. A member or an invitation is addressed by whatever address the
+  host's record gives, which is its number unless the host's model says
+  otherwise. Role assignments still point at members and roles by number.
 - **Rank** — a whole number on each role, 0 unless set, where a higher number
   ranks higher. Ranks compare only within one account.
 - **Template** — a role definition written in code, used to create a role in an
@@ -157,66 +171,80 @@ Decide which of the two you need, then go there.
   the button does not check whether the account already has a role of that name.
 - **Members page** — the engine's page for the current account's members. It
   lists each member's name, email and the roles they hold in that account only,
-  under a form for inviting a person. Between that form and the members it lists
-  the account's invitations still waiting. Beside the page title is a Roles link
-  to the role pages, shown only to a viewer who holds the roles capability in the
-  current account. Beside each member the viewer reaches is a Give button for
-  every role within reach the member does not hold, and a Take button for every
-  role within reach they do. It also shows a Remove button when the host says
-  that member may be removed. A Take or Remove button that would break the last
-  member manager rule is not shown. A member outside the viewer's reach shows no
-  buttons.
+  and each name opens that member's member page. Beside the list is an Invite
+  button that opens the invite page. Below the members it lists the account's
+  waiting invitations. Beside the page title is a Roles link to the role pages,
+  shown only to a viewer who holds the roles capability in the current account.
+- **Member page** — the engine's page for one member of the current account,
+  showing their name, email and the roles they hold there. When the viewer
+  reaches the member, it shows a Give button for every role within reach the
+  member does not hold, and a Take button for every role within reach they do.
+  It also shows a Remove button when the host says that member may be removed. A
+  Take or Remove button that would break the last member manager rule is not
+  shown. A member outside the viewer's reach shows no buttons.
 - **Giving and taking** — assigning a role to a member, or removing one, from the
-  members page. Only members and roles of the current account, and within the
-  viewer's reach, can be given or taken, and either action returns to the
-  members page.
-- **Inviting** — sending an invitation from the members page with a name and an
+  member page or the team section. Only members and roles of the current
+  account, and within the viewer's reach, can be given or taken, and from the
+  member page either action returns to the members page.
+- **Inviting** — sending an invitation from the invite page with a name and an
   email, both required. AccountAuthz passes the current account, the name, the email
   and the inviting member to the host. The host sends its own invitation and
   decides when the person becomes a member. Rank does not limit inviting, and the
   action returns to the members page.
 - **Waiting invitation** — an invitation the host says is still waiting for an
-  answer. Each one shows the name and email it was sent to, an Invited badge, a
-  Send again button and a Cancel button. Sending again asks the host to send that
-  invitation once more, and cancelling asks the host to withdraw it. Only the
-  current account's waiting invitations can be sent again or cancelled, rank does
-  not limit either, and both actions return to the members page.
-- **Removing** — taking a member off the current account from the members page.
-  AccountAuthz first takes away every role the member holds in the current account,
-  then asks the host to remove the member, both in one database transaction.
-  Roles the member holds in other accounts are left as they are. The member must
-  be within the viewer's reach, and the host decides whether a member may be
-  removed at all, such as refusing the account owner. A top-rank manager reaches
-  themselves, so they can remove themselves unless the host refuses it or they
-  are the last member manager.
+  answer. Each one shows the name and email it was sent to, a Send again button
+  and a Cancel button. Sending again asks the host to send that invitation once
+  more, and cancelling asks the host to withdraw it. Only the current account's
+  waiting invitations can be sent again or cancelled, rank does not limit
+  either, and both actions return to the members page.
+- **Removing** — taking a member off the current account from the member page or
+  the team section. AccountAuthz first takes away every role the member holds in the
+  current account, then asks the host to remove the member, both in one database
+  transaction. Roles the member holds in other accounts are left as they are.
+  The member must be within the viewer's reach, and the host decides whether a
+  member may be removed at all, such as refusing the account owner. A top-rank
+  manager reaches themselves, so they can remove themselves unless the host
+  refuses it or they are the last member manager.
+- **Team section** — the members list, the chosen member's Give, Take and Remove
+  buttons, an invite form and the waiting invitations, drawn as sections with no
+  page heading of its own so the host can place them inside one of its own
+  pages. Choosing a member's name adds that member's address to the page's own
+  link. The host gives the section the person, the account, the chosen member
+  and the address each form submits to, and handles what is submitted there.
 - **Host layout** — every engine page is built from keystone_ui components and
   shown inside the layout the host's own controllers use, so the host loads
   keystone_ui's styles. Links in that layout to the host's own pages work on the
   engine pages without change.
-- **Members source** — what the host supplies for the members page. It lists
-  which members belong to an account, sends an invitation, lists the invitations
-  still waiting, sends one again, cancels one, says whether a member may be
-  removed, and removes a member.
+- **Members source** — what the host supplies for the members pages and the team
+  section. It lists which members belong to an account, sends an invitation,
+  lists the invitations still waiting, sends one again, cancels one, says
+  whether a member may be removed, and removes a member. It may also find the
+  member at an address and the invitation at an address, which is how an app
+  whose members carry codes, or whose invitations are addressed by a token, has
+  them found. A source that does neither has members and invitations found by
+  number within the lists it gives.
 - **Members capability** — the capability a person needs to open the members
-  page and to invite, send an invitation again, cancel one, remove, give or take
-  roles there, `manage_members` unless the app names another.
+  page, the member page and the invite page, and to invite, send an invitation
+  again, cancel one, remove, give or take roles there, `manage_members` unless
+  the app names another.
 - **Roles capability** — the capability a person needs to open the role pages and
   to create or change roles there, `manage_roles` unless the app names another.
 - **Forbidden** — a person without the page's capability, or a request with no
   current account, gets a forbidden response from any engine page. Another
   account's roles, members and waiting invitations cannot be read or changed from
-  these pages.
+  these pages, and an address naming one is not found.
 - **Refusal message** — what a manager sees when they may use the page but not
   make a particular change. AccountAuthz changes nothing and sends them back with a
   flash alert saying why. Seven reasons have a message: a role outside the
   manager's reach to give or take, a member outside the manager's reach, a
   member the host says may not be removed, a change that breaks the last member
   manager rule, a capability the editor does not hold, a rank above the editor's
-  own, and a role the editor may not change. A give, take or removal returns to
-  the members page. Adding from a template, and saving a role the editor may not
-  change, return to the role list. A refused new role returns to an empty new
-  role form, and any other refused edit returns to the role's edit form showing
-  the role as it was saved. The message shows only when the host's layout renders
-  flash alerts, and the app can reword each one in its locale files.
+  own, and a role the editor may not change. A give, take or removal from the
+  member page returns to the members page. Adding from a template, and saving a
+  role the editor may not change, return to the role list. A refused new role
+  returns to an empty new role form, and any other refused edit returns to the
+  role's edit form showing the role as it was saved. The message shows only when
+  the host's layout renders flash alerts, and the app can reword each one in its
+  locale files.
 - The rule the gem follows: capabilities are code, roles are data, and Pundit
   enforces.

data/the_local/agents/account_authz-install.md

@@ -11,12 +11,12 @@ You follow the steps below exactly, in order, and invent none. Where a step says
 A Rails engine for capability-based authorization in multi-tenant apps, hooked in when a host needs account-scoped roles enforced through Pundit.
 
 ## Interface
-- `gem "account_authz"` — adds the engine to the host's Gemfile, and brings in `rails`, `pundit` and `keystone_ui` as dependencies.
-- `bin/rails account_authz:install:migrations` — copies the engine's three migrations into the host's `db/migrate/`.
+- `gem "account_authz"` — adds the engine to the host's Gemfile, brings in `rails`, `pundit`, `public_code` and `keystone_ui` as dependencies, and holds `json` below version 3.
+- `bin/rails account_authz:install:migrations` — copies the engine's six migrations into the host's `db/migrate/`.
 - `AccountAuthz::Member` — a model concern included in the host model that holds roles, normally the record for a person inside one account, giving it role assignments.
 - `AccountAuthz::Authorization` — a controller concern that includes `Pundit::Authorization` and adds a `can?(capability)` helper to controllers and views.
 - `AccountAuthz::Current.account_id` — the per-request account that the `can?` helper scopes its answer to.
-- `mount AccountAuthz::Engine` — a line in the host's `config/routes.rb` that serves two sets of pages for the current account. The members page lists each member with their name, email and roles, gives or takes away roles ranked below the viewer's own, invites a person by name and email, lists the invitations still waiting with a button to send each again and one to cancel it, and removes a member from the account. The role pages list the account's roles, create a role, add a role from a default template, and change a role's name, rank or capabilities, limited to roles ranked below the viewer unless the viewer holds the top rank, ranks up to the viewer's own and capabilities the viewer holds. The members page links to the roles page for a viewer who holds the roles capability, and the roles page links back to the members page. All of them are built from keystone_ui components and shown inside the host's own layout.
+- `mount AccountAuthz::Engine` — a line in the host's `config/routes.rb` that serves the members pages and the role pages for the current account. The members page lists each member with their name, email and roles, links each name to that member's page, opens an invite page that invites a person by name and email, and lists the invitations still waiting with a button to send each again and one to cancel it. A member's page shows the roles they hold, gives or takes away roles ranked below the viewer's own, and removes the member from the account. The role pages list the account's roles, create a role, add a role from a default template, and change a role's name, rank or capabilities, limited to roles ranked below the viewer unless the viewer holds the top rank, ranks up to the viewer's own and capabilities the viewer holds. The members page links to the roles page for a viewer who holds the roles capability, and the roles page links back to the members page. All of them are built from keystone_ui components and shown inside the host's own layout.
 
 ## How to use it
 1. Confirm the host runs Ruby 3.2 or later and Rails 7.1 or later.
@@ -24,13 +24,14 @@ A Rails engine for capability-based authorization in multi-tenant apps, hooked i
    - RubyGems: `gem "account_authz"`
    - Git: `gem "account_authz", github: "DYB-Development/account_authz", branch: "main"`
 
-   Add the chosen line to `Gemfile`, then run `bundle install`. This updates `Gemfile.lock`.
-3. Run `bin/rails account_authz:install:migrations`. It copies three files into `db/migrate/`, named `<timestamp>_create_account_authz_roles.account_authz.rb`, `<timestamp>_create_account_authz_assignments.account_authz.rb` and `<timestamp>_add_rank_to_account_authz_roles.account_authz.rb`.
-   - `account_authz_roles` has `account_id` (bigint, required, indexed), `name` (string, required), `capabilities` (json, default empty array), and `rank` (integer, required, default 0).
+   Add the chosen line to `Gemfile`, then run `bundle install`. This updates `Gemfile.lock`. account_authz requires `json` below version 3, so if the host's `Gemfile.lock` holds `json` 3 or later, `bundle install` fails to resolve. In that case, tell the developer and ask whether to run `bundle update json`.
+3. Run `bin/rails account_authz:install:migrations`. It copies six files into `db/migrate/`, each named `<timestamp>_<name>.account_authz.rb`, with these names in this order: `create_citizen_roles`, `create_citizen_assignments`, `add_rank_to_citizen_roles`, `rename_citizen_tables_to_account_authz`, `rename_citizen_member_index` and `add_public_code_to_account_authz_roles`. The first five create two tables under older names and rename them, so after all six run the host has these two tables.
+   - `account_authz_roles` has `account_id` (bigint, required, indexed), `name` (string, required), `capabilities` (json, default empty array), `rank` (integer, required, default 0), and `public_code` (string, required, unique index).
    - `account_authz_assignments` has a polymorphic `member` reference, a `role` reference, and a unique index on member and role together.
    - Neither table has a foreign key to an accounts table, so the host needs no account model for the migrations to run.
    - AccountAuthz stores no invitations of its own, so no table is copied for them.
-4. Open the three copied files. They declare `ActiveRecord::Migration[8.1]`. If the host runs a Rails version older than 8.1, change `[8.1]` in all three files to the host's Rails version, such as `[7.2]`.
+   - The last migration gives every role that already exists a code. It needs no setup in the host, because the `public_code` gem is loaded with account_authz.
+4. Open the six copied files. They declare `ActiveRecord::Migration[8.1]`. If the host runs a Rails version older than 8.1, change `[8.1]` in all six files to the host's Rails version, such as `[7.2]`.
 5. Run `bin/rails db:migrate`. This updates `db/schema.rb` or `db/structure.sql`.
 6. Choose the model that holds roles. A role belongs to one account, so the model to include `AccountAuthz::Member` in is the record for a person inside one account, such as `Membership`, not the person record, such as `User`.
    - Look in `app/models/` for a model that joins a person to an account. If there is one, confirm with the developer that it is the record to use.
@@ -40,29 +41,33 @@ A Rails engine for capability-based authorization in multi-tenant apps, hooked i
 8. `AccountAuthz::Authorization` calls `current_member` on the controller, and its `can?` helper returns `false` when that returns `nil`. Check whether `ApplicationController` already defines `current_member`. If it does not, ask the developer how the member record for the signed-in request is found, and define `current_member` in `ApplicationController` to return that record. With a membership model, that is the signed-in person's membership in the current account from step 10, so `current_member` must look it up after the current account is set.
 9. Pundit passes `pundit_user` to every policy, and `pundit_user` returns `current_user` unless the host overrides it. If the model from step 6 is not the model `current_user` returns, define `pundit_user` in `ApplicationController` to return `current_member`.
 10. Ask the developer how the current account is found for a request, such as from the subdomain, the signed-in user, or a URL parameter. Add a `before_action` to `ApplicationController` that sets `AccountAuthz::Current.account_id` to that account's integer id. Rails resets it at the end of every request.
-11. Ask the developer whether they want account_authz's pages. The one mount serves both the members page and the role pages, so the host gets both or neither. If they do not want them, skip this step and steps 12 and 13. If they do, ask which path to serve them under, offering `/account_authz`, and add `mount AccountAuthz::Engine => "/account_authz"` with that path to `config/routes.rb`. The members page is then at that path followed by `/members`, and the roles page at that path followed by `/roles`.
+11. Ask the developer whether they want account_authz's pages. The one mount serves both the members pages and the role pages, so the host gets both or neither. If they do not want them, skip this step and steps 12 and 13. If they do, ask which path to serve them under, offering `/account_authz`, and add `mount AccountAuthz::Engine => "/account_authz"` with that path to `config/routes.rb`. The members page is then at that path followed by `/members`, and the roles page at that path followed by `/roles`.
     - The engine's controllers inherit the host's `ApplicationController`, so the sign-in, `current_member`, current account and CSRF protection from the host apply to every page and every form on them.
-    - The pages render inside the layout the host's `ApplicationController` uses, such as `app/views/layouts/application.html.erb`. Route helpers in that layout, such as `root_path`, reach the host's own routes on the pages without a `main_app.` prefix, so the layout needs no change for them.
+    - The pages render inside the layout the host's `ApplicationController` uses, such as `app/views/layouts/application.html.erb`. Route helpers in that layout, such as `root_path`, reach the host's own routes on the pages without a `main_app.` prefix. The exception is a helper whose name the engine also defines: `members_path`, `member_path`, `member_roles_path`, `member_role_path`, `roles_path`, `new_role_path`, `edit_role_path`, `role_path`, `invitations_path`, `new_invitation_path`, `invitation_path` and `resend_invitation_path`, and their `_url` forms. On the engine's pages these reach the engine's routes. Check whether the layout calls any of them. If it does, tell the developer and change each call to start with `main_app.`, such as `main_app.members_path`.
     - The pages are built from keystone_ui components and ship no stylesheet of their own, so that layout must load keystone_ui's styles. Check whether the host already loads them. If it does not and the host has a keystone_ui install local, hand that step to it. Otherwise ask the developer how the host loads keystone_ui's styles before continuing.
     - A change a manager may not make sends them back to a page with a flash alert saying why, and the engine's pages do not show flash messages themselves. Check whether that layout renders `flash[:alert]`. If it does not, tell the developer that refused changes will return to the page with no message, and ask where in the layout to render the alert.
     - The members page shows a `Roles` link only to a viewer who holds the roles capability in the current account, and the roles page shows a `Members` link to every viewer. A member who holds the roles capability but not the members capability gets a 403 response on the members page, so that member reaches the roles page only through a link straight to it. Ask the developer whether the host's navigation should link to the members page, the roles page, or both, and where to put each link.
     - A request with no current account gets a 403 response on every page and every form.
-12. Check the members page against these facts, and tell the developer about any that the host does not meet.
-    - A member who does not hold the members capability in the current account gets a 403 response, whether they load the page, give or take a role, invite a person, send an invitation again, cancel one, or remove a member. The capability is `manage_members` unless the develop local changes it.
-    - Every member record the page lists must respond to `name` and `email` and include `AccountAuthz::Member`. If the model from step 6 lacks `name` or `email`, as a membership model often does, ask the developer how it should answer them, such as from the person record it belongs to, before continuing.
-    - Every waiting invitation the page lists must respond to `name` and `email`, and must be findable by its id among the current account's invitations. It needs no account_authz concern and no account_authz table.
+12. Check the members pages against these facts, and tell the developer about any that the host does not meet.
+    - A member who does not hold the members capability in the current account gets a 403 response, whether they load the members page, a member's page or the invite page, give or take a role, invite a person, send an invitation again, cancel one, or remove a member. The capability is `manage_members` unless the develop local changes it.
+    - Every member record the members page lists must respond to `name` and `email` and include `AccountAuthz::Member`. If the model from step 6 lacks `name` or `email`, as a membership model often does, ask the developer how it should answer them, such as from the person record it belongs to, before continuing.
+    - Each member's name links to their page at an address made from the record's `to_param`, which is its id unless the model changes it. That address must find the same record among the current account's members, either by `find` or through a member lookup the develop local configures.
+    - Every waiting invitation the members page lists must respond to `name` and `email`. Its `Send again` and `Cancel` buttons send the record's `to_param`, which must find the same invitation among the current account's invitations, either by `find` or through an invitation lookup the develop local configures. An invitation needs no account_authz concern and no account_authz table.
     - The engine sends no email and stores no invitation. Inviting a person, sending an invitation again, and cancelling one each call the host's own code, and accepting an invitation is the host's own flow.
-    - The invite form has a required `Name` field, a required `Email` field and an `Invite` button, and the engine does not validate either value, so the host's invite decides what to do with one it rejects.
+    - The members page's `Invite` link opens the invite page, which has a required `Name` field, a required `Email` field and an `Invite` button. The engine does not validate either value, so the host's invite decides what to do with one it rejects. Inviting, sending again and cancelling each return to the members page.
+    - A member's page shows a `Take <role>` button for each role they hold and a `Give <role>` button for each role they do not hold, both only for roles ranked below the viewer's own, and a `Remove from team` button. Each returns to the members page.
+    - Roles are addressed by their code, not their id, so a link or form that names a role by its number gets a not-found error.
     - Giving or taking a role, removing a member, sending an invitation again and cancelling one find the record only among the current account's members, roles or invitations, so a record from another account raises a not-found error, which Rails answers with a 404 response outside development.
     - A refused give, take or removal changes nothing and returns to the members page with a flash alert naming the reason, drawn from these four: `You can only give or take roles ranked below your own.`, `You can only change members ranked below you.`, `Someone else needs to be able to manage members first.` and `This member can't be removed from the account.`
     - Sending an invitation again and cancelling one are not limited by rank, so every viewer who holds the members capability may do both to every waiting invitation.
-    - The account always keeps at least one member who holds the members capability, so a `Take <role>` or `Remove` button is left out when that member is the only way anyone in the current account holds it.
+    - The account always keeps at least one member who holds the members capability, so a `Take <role>` or `Remove from team` button is left out when that member is the only way anyone in the current account holds it.
     - Every role starts at rank 0, so until ranks are set, every viewer who holds a role reaches every member and every role. Tell the developer this, and that a role's rank is set on the role form.
     - Removing a member takes away every role they hold in the current account and then calls the host's remove, both in one database transaction.
-    - The page does not know which records to list, which invitations are waiting, how to invite a person, how to send an invitation again, how to cancel one, which members cannot be removed, or how to remove one until the develop local configures that. Until then, a request from a member who holds the members capability raises an error on the page, on every button and on the invite form.
+    - The members pages do not know which records to list, which invitations are waiting, how to invite a person, how to send an invitation again, how to cancel one, which members cannot be removed, or how to remove one until the develop local configures that. Until then, a request from a member who holds the members capability raises an error on the members page, on a member's page, on every button and on the invite form.
 13. Check the role pages against these facts, and tell the developer about any that the host does not meet.
     - A member who does not hold the roles capability in the current account gets a 403 response on every role page and form. The capability is `manage_roles` unless the develop local changes it.
     - The roles page lists each role in the current account by name with its number of capabilities, and each name links to that role's edit form. A `New role` link opens the form for a new role.
+    - A role's edit form is addressed by the role's code, so an address that names the role by its number gets a not-found error.
     - The new and edit forms take a name, a rank as a number field with a minimum of 0, and a checkbox for each capability in the catalog, and saving returns to the roles page. Until the develop local declares the catalog, the forms show no checkboxes.
     - The roles page shows an `Add <template>` button for each default template, which creates that role in the current account at rank 0. The section is left out until the develop local declares a default template.
     - A refused create or save changes nothing and returns to the form or the roles page with a flash alert naming the reason, drawn from these four: `You can only change roles ranked below your own.`, `You can only set a rank up to your own.`, `You can only give a role capabilities you have yourself.` and `Someone else needs to be able to manage members first.`
@@ -70,11 +75,12 @@ A Rails engine for capability-based authorization in multi-tenant apps, hooked i
     - Saving a role with a blank name raises a validation error, which Rails answers with a 422 response outside development.
 
 ## Conventions
-- After step 5, confirm the schema file contains both `account_authz_roles` and `account_authz_assignments`, and that `account_authz_roles` has a `rank` column.
+- After step 5, confirm the schema file contains both `account_authz_roles` and `account_authz_assignments`, that `account_authz_roles` has a `rank` column and a `public_code` column, and that no table named `citizen_roles` or `citizen_assignments` remains.
 - After step 10, confirm the host boots with `bin/rails runner 'puts AccountAuthz::Current.account_id.inspect'`, which prints `nil` outside a request.
-- After step 11, confirm `bin/rails routes` lists the mount and, under the routes for `AccountAuthz::Engine`, a `GET` route for `members`, a `DELETE` route for `members/:id`, a `POST` route for `members/:member_id/roles`, a `DELETE` route for `members/:member_id/roles/:id`, a `POST` route for `invitations`, a `POST` route for `invitations/:id/resend`, a `DELETE` route for `invitations/:id`, `GET` routes for `roles`, `roles/new` and `roles/:id/edit`, a `POST` route for `roles`, and `PATCH` and `PUT` routes for `roles/:id`.
-- After step 12, once the develop local has configured the members page, load it as a member who holds the members capability and confirm it shows the invite form and any waiting invitations inside the host's layout with keystone_ui's styles applied.
-- After step 13, load the roles page as a member who holds the roles capability and confirm it shows inside the host's layout with keystone_ui's styles applied.
-- After updating the account_authz gem, run `bin/rails account_authz:install:migrations` again, then `bin/rails db:migrate`. The task copies only migrations the host does not already have. A host that installed account_authz before ranks existed gets the rank migration this way, and every existing role gets rank 0.
-- Declaring capabilities, declaring templates, seeding roles for a new account, giving the first member the members or roles capability, writing policies, checking reach in host code, checking in host code whether a change would leave the account with no member who holds the members capability, configuring which members and which waiting invitations the members page lists, how it invites a person, sends an invitation again and cancels one, which members cannot be removed and how it removes one, configuring which capabilities open the pages, and rewording the refusal messages are out of scope for this local. Hand that work to the account_authz-develop local.
-- The members page and the role pages are the only screens account_authz adds. Deleting a role is not offered on them, and a screen for it belongs to the host. Sending an invitation and accepting one also belong to the host.
+- After step 11, confirm `bin/rails routes` lists the mount and, under the routes for `AccountAuthz::Engine`, `GET` routes for `members` and `members/:id`, a `DELETE` route for `members/:id`, a `POST` route for `members/:member_id/roles`, a `DELETE` route for `members/:member_id/roles/:id`, a `GET` route for `invitations/new`, a `POST` route for `invitations`, a `POST` route for `invitations/:id/resend`, a `DELETE` route for `invitations/:id`, `GET` routes for `roles`, `roles/new` and `roles/:id/edit`, a `POST` route for `roles`, and `PATCH` and `PUT` routes for `roles/:id`.
+- After step 12, once the develop local has configured the members pages, load the members page as a member who holds the members capability and confirm it shows the members and any waiting invitations inside the host's layout with keystone_ui's styles applied. Then open a member's page from their name and the invite page from `Invite`, and confirm both load.
+- After step 13, load the roles page as a member who holds the roles capability, confirm it shows inside the host's layout with keystone_ui's styles applied, and open a role's edit form from its name.
+- After updating the account_authz gem, run `bin/rails account_authz:install:migrations` again, then `bin/rails db:migrate`. The task copies only migrations the host does not already have. A host that installed account_authz before ranks existed gets the rank migration this way, and every existing role gets rank 0. A host that installed it before role codes existed gets the code migration this way, and every existing role gets a code. Apply step 4 to every newly copied file.
+- After updating the account_authz gem to the version that addresses roles by code, search the host for links or forms that name a role by its id on the engine's routes, such as `edit_role_path(role.id)` or a `role_id` field holding `role.id`, and tell the developer about each one, because those now get a not-found error.
+- Declaring capabilities, declaring templates, seeding roles for a new account, giving the first member the members or roles capability, writing policies, checking reach in host code, checking in host code whether a change would leave the account with no member who holds the members capability, configuring which members and which waiting invitations the members pages list, how a member or an invitation is found at its address, how the pages invite a person, send an invitation again and cancel one, which members cannot be removed and how one is removed, configuring which capabilities open the pages, and rewording the refusal messages are out of scope for this local. Hand that work to the account_authz-develop local.
+- The members pages, the invite page and the role pages are the only screens account_authz adds. Deleting a role is not offered on them, and a screen for it belongs to the host. Sending an invitation and accepting one also belong to the host.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: account_authz
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 0.2.0
 platform: ruby
 authors:
 - tylercschneider
@@ -51,6 +51,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: public_code
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.2'
 - !ruby/object:Gem::Dependency
   name: keystone_ui
   requirement: !ruby/object:Gem::Requirement
@@ -119,6 +133,7 @@ files:
 - db/migrate/20260916000001_add_rank_to_citizen_roles.rb
 - db/migrate/20260921220000_rename_citizen_tables_to_account_authz.rb
 - db/migrate/20260922150000_rename_citizen_member_index.rb
+- db/migrate/20261012230000_add_public_code_to_account_authz_roles.rb
 - lib/account_authz.rb
 - lib/account_authz/catalog.rb
 - lib/account_authz/engine.rb