protege 0.1.0.alpha.2 → 0.1.0.alpha.8

data/app/views/protege/agents/show.html.slim

@@ -0,0 +1,29 @@
+- content_for :sidebar do
+  = render "sidebar", current: @agent
+
+= page_container do
+  = page_header(@agent.name, @agent.class.display_name) do
+    = render("actions", agent: @agent)
+
+  .space-y-4
+    = info_card("Email address", { "Address" => @agent.email_address })
+
+    = card do
+      = heading_2("Instructions")
+      - if @agent.instructions.present?
+        .mt-3
+          = body_text(@agent.instructions)
+      - else
+        .mt-3
+          = hint("No instructions set yet — add them via Edit. They're used as the system prompt only when a resolver (e.g. LoadText) includes them in the agent's context.")
+
+    = render("access_rules", agent: @agent)
+
+    = render("toolkits", agent: @agent)
+
+  = render("protege/shared/confirm_dialog",
+      id: "delete-agent",
+      title: "Delete #{@agent.name}?",
+      message: "This permanently removes the agent and ALL of its data — every thread, message, attachment, responsibility, access rule, and tool-use record. This cannot be undone. To keep the history but stop the agent instead, archive it.",
+      action_url: agent_path(@agent),
+      action_text: "Delete agent")

data/app/views/protege/alert_mailer/inference_failed.text.erb

@@ -0,0 +1,4 @@
+An inference run failed and could not be recovered.
+
+Error:          <%= @error_class %>: <%= @error_message %>
+Correlation ID: <%= @correlation_id || '(none)' %>

data/app/views/protege/email_domains/show.html.slim

@@ -31,6 +31,6 @@
 = render("protege/shared/confirm_dialog",
     id: "remove-domain",
     title: "Remove #{@email_domain.domain}?",
-    message: "Removing this domain only deletes it from Protege. It does not affect your DNS records. If this domain is in use by a persona, you will need to de-register the MX, SPF, DKIM, and DMARC entries with your DNS provider separately.",
+    message: "Removing this domain only deletes it from Protege. It does not affect your DNS records. If this domain is in use by an agent, you will need to de-register the MX, SPF, DKIM, and DMARC entries with your DNS provider separately.",
     action_url: email_domain_path(@email_domain),
     action_text: "Remove domain")

data/app/views/protege/home/show.html.slim

@@ -2,9 +2,9 @@
   = page_header('About Protege')
 
   div class="space-y-4 text-sm leading-relaxed mb-10"
-    p Protege is an email-native AI agent toolkit. Your personas receive email, process it through an inference pipeline, and respond autonomously using the tools you configure. Every conversation — whether from an external email client or this console — flows through the same harness.
+    p Protege is an email-native AI agent toolkit. Your agents receive email, process it through an inference pipeline, and respond autonomously using the tools you configure. Every conversation — whether from an external email client or this console — flows through the same harness.
 
-    p To get started, configure at least one email domain with valid DNS records, create a persona with a routable email address, and set up your provider credentials. Once a persona is active and your MTA is running, it will process inbound email automatically.
+    p To get started, configure at least one email domain with valid DNS records, create an agent with a routable email address, and set up your provider credentials. Once an agent is active and your MTA is running, it will process inbound email automatically.
 
     p Protege is a toolkit for developers, not an out-of-the-box solution. Every part of the pipeline — providers, resolvers, tools, hooks — is an extension surface you implement. The #{ui_link("documentation", "https://docs.protege.bot", target: "_blank")} covers each surface in detail with examples and guides.
 
@@ -13,14 +13,14 @@
       = heading_2("Extension surfaces")
 
     = grid_container(cols: 2) do
-      = grid_card("Personas", "The agent identity that receives and responds to email. Each persona has its own address, resolver chain, and display name.", href: "https://docs.protege.bot/personas")
-      
-      = grid_card("Providers", "LLM provider integration — OpenRouter, Anthropic, or any OpenAI-compatible endpoint.", href: "https://docs.protege.bot/providers")
-      
-      = grid_card("Resolvers", "Build inference context before each generation — system prompts, conversation history, or custom data.", href: "https://docs.protege.bot/resolvers")
-      
-      = grid_card("Tools", "Capabilities exposed to the LLM — send email, query APIs, or anything you implement.", href: "https://docs.protege.bot/tools")
-      
-      = grid_card("Hooks", "Subscribe to lifecycle events — inference, tool calls, failures — for logging, metrics, or side effects.", href: "https://docs.protege.bot/hooks")
-      
-      = grid_card("Gateway", "Inbound and outbound email transport — SMTP, console messages, threading, and persistence.", href: "https://docs.protege.bot/gateway")
+      = grid_card("Agents", "The addressable identity that receives and responds to email. Each agent has its own address, resolver chain, and display name.", href: "https://docs.protege.bot/reference/agents")
+
+      = grid_card("Providers", "LLM provider integration — OpenRouter, Anthropic, or any OpenAI-compatible endpoint.", href: "https://docs.protege.bot/extensions/providers")
+
+      = grid_card("Resolvers", "Build inference context before each generation — system prompts, conversation history, or custom data.", href: "https://docs.protege.bot/extensions/resolvers")
+
+      = grid_card("Tools", "Capabilities exposed to the LLM — send email, query APIs, or anything you implement.", href: "https://docs.protege.bot/extensions/tools")
+
+      = grid_card("Hooks", "Subscribe to lifecycle events — inference, tool calls, failures — for logging, metrics, or side effects.", href: "https://docs.protege.bot/extensions/hooks-and-events")
+
+      = grid_card("Gateway", "Inbound and outbound email transport — SMTP, console messages, threading, and persistence.", href: "https://docs.protege.bot/architecture/gateway")

data/app/views/protege/responsibilities/_form.html.slim

@@ -4,13 +4,13 @@
 = form_with url:, method:, scope: :responsibility, class: "space-y-5" do |f|
   = form_errors(responsibility)
 
-  = form_select(f, :persona_id, all_personas.map { |p| [p.name, p.id] }, label: "Persona", prompt: "Choose a persona")
+  = form_select(f, :agent_id, all_agents.map { |p| [p.name, p.id] }, label: "Agent", prompt: "Choose an agent")
 
   = form_field(f, :name, placeholder: "e.g. Morning digest")
 
   = form_field(f, :schedule, label: "Schedule", placeholder: "0 9 * * 1-5", hint: "A 5-field cron expression (minute hour day-of-month month day-of-week) in the app timezone — e.g. \"0 9 * * 1-5\" is 9am on weekdays, \"*/15 * * * *\" every 15 minutes.")
 
-  = form_text_area(f, :instructions, label: "Instructions", rows: 8, hint: "The task the agent carries out on each run, delivered as the opening message. The persona's responsibility_resolvers chain supplies the system context around it.")
+  = form_text_area(f, :instructions, label: "Instructions", rows: 8, hint: "The task the agent carries out on each run, delivered as the opening message. The agent's responsibility_resolvers chain supplies the system context around it.")
 
   - unless responsibility.new_record?
     = form_checkbox(f, :active, label: "Active")

data/app/views/protege/responsibilities/_responsibility_sidebar_item.html.slim

@@ -1,5 +1,5 @@
 = sidebar_item(responsibility.name, responsibility_path(responsibility),
     detail: responsibility_status(responsibility),
-    subtitle: "#{responsibility.persona.name} · #{responsibility.schedule}",
+    subtitle: "#{responsibility.agent.name} · #{responsibility.schedule}",
     active: local_assigns[:active],
     id: dom_id(responsibility))

data/app/views/protege/responsibilities/new.html.slim

@@ -2,6 +2,6 @@
   = render "sidebar"
 
 = page_container do
-  = page_header("New responsibility", "A scheduled duty a persona carries out on a cron schedule.")
+  = page_header("New responsibility", "A scheduled duty an agent carries out on a cron schedule.")
 
   = card { render "form", responsibility: @responsibility }

data/app/views/protege/responsibilities/show.html.slim

@@ -2,13 +2,13 @@
   = render "sidebar", current: @responsibility
 
 = page_container do
-  = page_header(@responsibility.name, "#{@responsibility.persona.name} · #{@responsibility.schedule}") do
+  = page_header(@responsibility.name, "#{@responsibility.agent.name} · #{@responsibility.schedule}") do
     div
       = ui_link("Edit", edit_responsibility_path(@responsibility), class: 'px-3')
       = inline_button("Run now", responsibility_runs_path, params: { responsibility_run: { responsibility_id: @responsibility.id } })
 
   .space-y-4
-    = info_card("Schedule", { "Cron" => @responsibility.schedule, "Persona" => @responsibility.persona.name, "Active" => (@responsibility.active? ? "Yes" : "No") })
+    = info_card("Schedule", { "Cron" => @responsibility.schedule, "Agent" => @responsibility.agent.name, "Active" => (@responsibility.active? ? "Yes" : "No") })
 
     = card do
       = heading_2("Instructions")

data/app/views/protege/responsibility_runs/show.html.slim

@@ -1,5 +1,5 @@
 = page_container do
-  = page_header("Run · #{@responsibility.name}", @responsibility.persona.name) do
+  = page_header("Run · #{@responsibility.name}", @responsibility.agent.name) do
     = ui_link("Back", responsibility_path(@responsibility))
 
   .space-y-4

data/app/views/protege/shared/_header.html.slim

@@ -4,8 +4,9 @@ header class="flex h-14 flex-shrink-0 items-center justify-between px-5" style="
 
     nav class="flex items-center gap-1"
       = nav_item("Inbox", protege.threads_path, request.path)
+      = nav_item("Agents", protege.agents_path, request.path)
+      = nav_item("Toolkits", protege.toolkits_path, request.path)
       = nav_item("Responsibilities", protege.responsibilities_path, request.path)
-      = nav_item("Personas", protege.personas_path, request.path)
       = nav_item("Domains", protege.email_domains_path, request.path)
       = nav_item("Traces", protege.traces_path, request.path)
 

data/app/views/protege/shared/_hotkeys.html.slim

@@ -3,19 +3,21 @@
 /
 / Registry — the single source of truth for app-wide combos. Each is a hidden link keys.js activates on
 / its combo; it navigates via the same route helper the visible UI uses, so a global command works from
-/ anywhere, independent of what's on screen. Nav combos are numbered by position (1..5, left to right)
+/ anywhere, independent of what's on screen. Nav combos are numbered by position (1..6, left to right)
 / rather than by initial — the "go to the Nth section" convention (⌘1..9 in browsers/editors). Rendered
 / after the page body, so a page-local hotkey reusing a combo is matched first and shadows the global one.
 div hidden=true aria-hidden="true"
   = link_to "Documentation",      'https://docs.protege.bot',      data: { hotkey: "g 0" }, target: '_blank'
   = link_to "Inbox",              protege.threads_path,            data: { hotkey: "g 1" }
-  = link_to "Responsibilities",   protege.responsibilities_path,   data: { hotkey: "g 2" }
-  = link_to "Personas",           protege.personas_path,           data: { hotkey: "g 3" }
-  = link_to "Domains",            protege.email_domains_path,      data: { hotkey: "g 4" }
-  = link_to "Traces",             protege.traces_path,             data: { hotkey: "g 5" }
+  = link_to "Agents",             protege.agents_path,             data: { hotkey: "g 2" }
+  = link_to "Toolkits",           protege.toolkits_path,           data: { hotkey: "g 3" }
+  = link_to "Responsibilities",   protege.responsibilities_path,   data: { hotkey: "g 4" }
+  = link_to "Domains",            protege.email_domains_path,      data: { hotkey: "g 5" }
+  = link_to "Traces",             protege.traces_path,             data: { hotkey: "g 6" }
   = link_to "New Thread",         protege.new_thread_path,         data: { hotkey: "g c" }
+  = link_to "New Agent",          protege.new_agent_path,          data: { hotkey: "g a" }
+  = link_to "New Toolkit",        protege.new_toolkit_path,        data: { hotkey: "g k" }
   = link_to "New Responsibility", protege.new_responsibility_path, data: { hotkey: "g r" }
-  = link_to "New Persona",        protege.new_persona_path,        data: { hotkey: "g p" }
   = link_to "New Email Domain",   protege.new_email_domain_path,   data: { hotkey: "g d" }
 
 / Help overlay, opened with "?" or the header's "?" button (keys.js just toggles it open/closed). This
@@ -26,16 +28,18 @@ div hidden=true aria-hidden="true"
   .mt-3.space-y-1
     = hotkey_section("Go to")
     = hotkey_row("Inbox", "g", "1")
-    = hotkey_row("Responsibilities", "g", "2")
-    = hotkey_row("Personas", "g", "3")
-    = hotkey_row("Domains", "g", "4")
-    = hotkey_row("Traces", "g", "5")
+    = hotkey_row("Agents", "g", "2")
+    = hotkey_row("Toolkits", "g", "3")
+    = hotkey_row("Responsibilities", "g", "4")
+    = hotkey_row("Domains", "g", "5")
+    = hotkey_row("Traces", "g", "6")
     = hotkey_row("Documentation", "g", "0")
 
     = hotkey_section("Create")
     = hotkey_row("New thread", "g", "c")
+    = hotkey_row("New agent", "g", "a")
+    = hotkey_row("New toolkit", "g", "k")
     = hotkey_row("New responsibility", "g", "r")
-    = hotkey_row("New persona", "g", "p")
     = hotkey_row("New email domain", "g", "d")
 
     = hotkey_section("General")

data/app/views/protege/threads/new.html.slim

@@ -2,11 +2,11 @@
   = render "protege/threads/sidebar", threads: inbox_threads
 
 = page_container do
-  = page_header("New message", "Send a message to a persona to start a thread.")
+  = page_header("New message", "Send a message to an agent to start a thread.")
 
   = card do
     = form_with url: threads_path, scope: :thread, class: "space-y-5", multipart: true do |f|
-      = form_select(f, :persona_id, available_persona_options, label: "To", prompt: "Select persona...")
+      = form_select(f, :agent_id, available_agent_options, label: "To", prompt: "Select agent...")
 
       = form_field(f, :subject, label: "Subject", placeholder: "Subject")
 

data/app/views/protege/toolkits/_form.html.slim

@@ -0,0 +1,13 @@
+= form_with model: toolkit, class: "space-y-5" do |f|
+  = form_errors(toolkit)
+
+  = form_field(f, :name, placeholder: "e.g. Finance")
+
+  = form_text_area(f, :description, label: "Description", rows: 3, hint: "What this toolkit is for — shown only in the dashboard.")
+
+  - tool_id = ->(entry) { entry.id.to_s }
+  = form_checklist(f, :member_tool_ids, toolkit_tool_options, label: "Tools", value: tool_id, text: :display_name, description: :summary, hint: "The tools this toolkit bundles. Who may use them is set per agent when you attach it.")
+
+  .flex.items-center.gap-3.pt-2
+    = button("Save toolkit", type: :submit)
+    = ui_link("Cancel", toolkits_path)

data/app/views/protege/toolkits/_sidebar.html.slim

@@ -0,0 +1,11 @@
+- pagy, toolkits = paginate(all_toolkits)
+
+= sidebar_content do
+  = sidebar_header("Toolkits (#{pagy.count})", new_path: new_toolkit_path)
+
+  = sidebar_stream("protege:toolkits", pagy: pagy)
+
+  = sidebar_body(toolkits, empty: "No toolkits yet", id: "toolkits_list") do |toolkit|
+    = render "toolkit_sidebar_item", toolkit: toolkit, active: local_assigns[:current] == toolkit
+
+  = sidebar_pagination(pagy)

data/app/views/protege/toolkits/_toolkit_sidebar_item.html.slim

@@ -0,0 +1,5 @@
+= sidebar_item(toolkit.name, toolkit_path(toolkit),
+    subtitle: toolkit_tool_count_label(toolkit),
+    detail: (badge("System", :yellow, size: :sm) if toolkit.system?),
+    active: local_assigns[:active],
+    id: dom_id(toolkit))

data/app/views/protege/toolkits/edit.html.slim

@@ -0,0 +1,7 @@
+- content_for :sidebar do
+  = render "sidebar", current: @toolkit
+
+= page_container do
+  = page_header("Edit #{@toolkit.name}")
+
+  = card { render "form", toolkit: @toolkit }

data/app/views/protege/toolkits/index.html.slim

@@ -0,0 +1,6 @@
+- content_for :sidebar do
+  = render "sidebar"
+
+= page_empty do
+  | Select a toolkit from the sidebar, or  
+  = ui_link("create a new one.", new_toolkit_path)

data/app/views/protege/toolkits/new.html.slim

@@ -0,0 +1,7 @@
+- content_for :sidebar do
+  = render "sidebar"
+
+= page_container do
+  = page_header("New toolkit", "A bundle of tools exposed to an agent only for senders that pass its gate.")
+
+  = card { render "form", toolkit: @toolkit }

data/app/views/protege/toolkits/show.html.slim

@@ -0,0 +1,13 @@
+- content_for :sidebar do
+  = render "sidebar", current: @toolkit
+
+= page_container do
+  = page_header(@toolkit.name, @toolkit.description) do
+    div
+      = ui_link("Edit", edit_toolkit_path(@toolkit), class: "px-3")
+      - unless @toolkit.system?
+        = destructive_link("Delete", toolkit_path(@toolkit), confirm: "Delete this toolkit?", method: :delete)
+
+  .space-y-4
+    = info_card("Toolkit", toolkit_overview(@toolkit))
+    = hint("This toolkit is a reusable set of tools. Who may use them is decided per agent — attach it on an agent's page to set its sender gate.")

data/config/routes.rb

@@ -18,13 +18,24 @@ Protege::Engine.routes.draw do
   resources :responsibilities
   resources :responsibility_runs
 
+  resources :toolkits
+
+  # A grant (agent↔toolkit) is split across two controllers so nesting never goes two deep. The
+  # *nested* Agents::AgentToolkitsController lists an agent's grants and attaches/detaches them (in
+  # the agent's scope); the *top-level* AgentToolkitsController manages a created grant on its own
+  # page, where its sender-gate rules nest one level deep (like access_rules under an agent).
+  resources :agent_toolkits do
+    resources :agent_toolkit_rules
+  end
+
   resources :threads do
     resource :reply
   end
 
-  resources :personas do
+  resources :agents do
     resource :archive
     resources :access_rules
+    resources :agent_toolkits, module: :agents
   end
 
   resources :email_domains do

data/db/migrate/20260707120000_replace_persona_active_with_archived_at.rb

@@ -3,7 +3,7 @@
 # Replace the persona +active+ boolean with an +archived_at+ timestamp — the idiomatic soft-delete shape,
 # which also records *when* a persona was archived. The model keeps +active?+/+scope :active+ as derived
 # readers over +archived_at+, so routing/scheduler/status code is unchanged.
-class ReplacePersonaActiveWithArchivedAt < ActiveRecord::Migration[8.1]
+class ReplacePersonaActiveWithArchivedAt < ActiveRecord::Migration[7.2]
   # Add archived_at, mark already-deactivated personas as archived-now, then drop active.
   #
   # @return [void]

data/db/migrate/20260708120000_add_disabled_tool_ids_to_personas.rb

@@ -5,7 +5,7 @@
 # has switched *off* within that grant, so scoping narrows and never widens. Stored as a JSON array in a
 # text column (SQLite has no native JSON type), matching +Message+'s recipient-list convention, and
 # defaults to an empty array so an unconfigured persona keeps its full grant.
-class AddDisabledToolIdsToPersonas < ActiveRecord::Migration[8.1]
+class AddDisabledToolIdsToPersonas < ActiveRecord::Migration[7.2]
   # Add the JSON-array text column, non-null with an empty-array default.
   #
   # @return [void]

data/db/migrate/20260728140000_scope_message_and_thread_uniqueness_per_persona.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+# Scopes inbound-mail uniqueness per persona, so one email addressed to several proteges can be handled
+# by each of them independently. Previously +thread_id+ and +message_id+ were globally unique, which
+# assumed exactly one persona per inbound message: the second persona's thread/message insert collided on
+# the global index. Making both unique per +persona_id+ lets every addressed persona own its own thread
+# and message for the same RFC Message-ID, while still keeping a single persona's retries idempotent.
+class ScopeMessageAndThreadUniquenessPerPersona < ActiveRecord::Migration[7.2]
+  def change
+    remove_index :protege_email_threads, column: :thread_id, unique: true
+    add_index    :protege_email_threads, %i[persona_id thread_id], unique: true
+
+    remove_index :protege_messages, column: :message_id, unique: true
+    add_index    :protege_messages, %i[persona_id message_id], unique: true
+  end
+end

data/db/migrate/20260812000001_create_protege_toolkits.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+# Creates the toolkit binding tables — the first "Binding" of the extension framework. A toolkit is a
+# global, dashboard-managed, reusable bundle of tools (referenced by their manifest ids, stored as a JSON
+# id list like +disabled_tool_ids+) — nothing more. Permission lives on the *attachment*: a
+# +protege_persona_toolkits+ row gives a toolkit to one persona and carries that grant's sender gate
+# (child +persona_toolkit_rules+ rows, kind + pattern, mirroring +AccessRule+) plus +allow_proactive+ (may
+# these tools run on that persona's scheduled, senderless runs?). So the same toolkit attached to two
+# personas can be gated differently, with no tool-list duplication.
+class CreateProtegeToolkits < ActiveRecord::Migration[7.2]
+  def change
+    create_table :protege_toolkits do |t|
+      t.string :name, null: false, index: { unique: true }
+      t.text   :description
+      t.text   :member_tool_ids, null: false, default: '[]'
+
+      t.timestamps
+    end
+
+    create_table :protege_persona_toolkits do |t|
+      t.references :persona,         null: false, foreign_key: { to_table: :protege_personas }
+      t.references :toolkit,         null: false, foreign_key: { to_table: :protege_toolkits }
+      t.boolean    :allow_proactive, null: false, default: false
+
+      t.timestamps
+    end
+    add_index :protege_persona_toolkits, %i[persona_id toolkit_id], unique: true
+
+    create_table :protege_persona_toolkit_rules do |t|
+      t.references :persona_toolkit, null: false, foreign_key: { to_table: :protege_persona_toolkits }
+      t.string     :kind,            null: false
+      t.string     :pattern,         null: false
+
+      t.timestamps
+    end
+  end
+end

data/db/migrate/20260815000001_remove_disabled_tool_ids_from_personas.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+# Remove +disabled_tool_ids+ from personas. Tool access no longer flows through a per-persona ceiling (a
+# code-declared +tools+ grant minus this disable list); a persona's tools now come entirely from the
+# toolkits attached to it, gated per attachment (see +Protege::Toolable+ / +PersonaToolkit+). The
+# subtractive override this column backed no longer exists, so the column is dropped.
+class RemoveDisabledToolIdsFromPersonas < ActiveRecord::Migration[7.2]
+  # Drop the column.
+  #
+  # @return [void]
+  def up
+    remove_column :protege_personas, :disabled_tool_ids
+  end
+
+  # Restore the JSON-array text column, non-null with an empty-array default.
+  #
+  # @return [void]
+  def down
+    add_column :protege_personas, :disabled_tool_ids, :text, null: false, default: '[]'
+  end
+end

data/db/migrate/20260815000002_add_key_to_protege_toolkits.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+# Add a stable +key+ to toolkits so the engine can identify its *system* toolkits — the auto-maintained
+# "All Tools" (+all_tools+) and the auto-attached "Default Tools" (+default_tools+) — independently of
+# their display name (which operators may rename). User-created toolkits leave +key+ null; a unique index
+# (SQLite allows multiple NULLs) keeps at most one toolkit per system key.
+#
+# Installs seeded before system toolkits existed already have an "All Tools" toolkit (created by the old
+# host seed). Adopt it as the keyed system toolkit here, so the sync updates that record in place rather
+# than colliding on its unique name.
+class AddKeyToProtegeToolkits < ActiveRecord::Migration[7.2]
+  def up
+    add_column :protege_toolkits, :key, :string
+    add_index  :protege_toolkits, :key, unique: true
+
+    execute("UPDATE protege_toolkits SET key = 'all_tools' WHERE name = 'All Tools' AND key IS NULL")
+  end
+
+  def down
+    remove_column :protege_toolkits, :key
+  end
+end

data/db/migrate/20260815100000_rename_personas_to_agents.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+# Rename the Persona concept to Agent across the schema — the industry has settled on "agent" for the
+# addressable actor, and the code now follows suit (+Protege::Agent+, +AgentToolkit+, …). Pure renames,
+# so existing installs transition in place with their data intact: the three persona tables become agent
+# tables, and every +persona_id+ foreign key becomes +agent_id+. Rails renames the conventionally-named
+# indexes along with each table/column, and SQLite keeps foreign-key references pointed at the renamed
+# tables. Earlier migrations keep their historical persona names — on a fresh install they run first and
+# this migration renames their output.
+class RenamePersonasToAgents < ActiveRecord::Migration[7.2]
+  def change
+    rename_table :protege_personas, :protege_agents
+    rename_table :protege_persona_toolkits, :protege_agent_toolkits
+    rename_table :protege_persona_toolkit_rules, :protege_agent_toolkit_rules
+
+    rename_column :protege_email_threads, :persona_id, :agent_id
+    rename_column :protege_messages, :persona_id, :agent_id
+    rename_column :protege_access_rules, :persona_id, :agent_id
+    rename_column :protege_responsibilities, :persona_id, :agent_id
+    rename_column :protege_tool_uses, :persona_id, :agent_id
+    rename_column :protege_agent_toolkits, :persona_id, :agent_id
+    rename_column :protege_agent_toolkit_rules, :persona_toolkit_id, :agent_toolkit_id
+  end
+end

data/lib/generators/protege/agent/agent_generator.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require 'rails/generators/named_base'
+require_relative '../extension_naming'
+
+module Protege
+  module Generators
+    # Scaffolds an agent — the identity Protege binds an inbox to — into the host app's agents
+    # directory (+config.agents_path+, default +app/agents+). An agent is an STI subclass of
+    # +Protege::Agent+ (an ActiveRecord model); subclassing registers the subtype, and each agent
+    # declares its display name and the resolver chains that assemble context for its reply and
+    # scheduled runs.
+    #
+    # The +Agent+ suffix is applied for you, so all of +support+, +Support+, and +SupportAgent+
+    # produce class +SupportAgent+ in +support_agent.rb+.
+    #
+    # @example
+    #   bin/rails g protege:agent support
+    class AgentGenerator < Rails::Generators::NamedBase
+      include ExtensionNaming
+
+      source_root File.expand_path('templates', __dir__)
+
+      desc 'Scaffold a Protege::Agent subclass in the configured agents path (default app/agents).'
+
+      # Render the agent scaffold into +config.agents_path+.
+      #
+      # @return [void]
+      def create_agent
+        template 'agent.rb.tt',
+                 File.join(Protege.configuration.agents_path, "#{extension_file_name('Agent')}.rb")
+      end
+    end
+  end
+end

data/lib/generators/protege/{persona/templates/persona.rb.tt → agent/templates/agent.rb.tt}

@@ -1,31 +1,31 @@
 # frozen_string_literal: true
 
-# <%= extension_class_name('Persona') %> — a persona: the identity Protege binds an inbox to.
+# <%= extension_class_name('Agent') %> — an agent: the identity Protege binds an inbox to.
 #
-# Subclassing +Protege::Persona+ (an STI ActiveRecord model) registers this subtype. Create the row in
+# Subclassing +Protege::Agent+ (an STI ActiveRecord model) registers this subtype. Create the row in
 # the dashboard (or a seed) to give it a +name+, +email_address+, and +instructions+ (its editable
 # system prompt); inbound mail to that address routes here, and outbound replies are sent as it.
 #
 # The two chains below assemble the context sent to the model. Engine built-in resolvers are named by
 # their flat +Protege::+ constant; host-app resolvers (see <%= Protege.configuration.resolvers_path %>/) by their own top-level constant.
-class <%= extension_class_name('Persona') %> < Protege::Persona
-  # Human-friendly label shown for this persona in the dashboard, logs, and tooling.
-  self.display_name = '<%= extension_class_name('Persona').titleize %>'
+class <%= extension_class_name('Agent') %> < Protege::Agent
+  # Human-friendly label shown for this agent in the dashboard, logs, and tooling.
+  self.display_name = '<%= extension_class_name('Agent').titleize %>'
 
   # Context assembled before every reply to inbound mail. +Protege::LoadTextResolver+ supplies this
-  # persona's dashboard-editable +instructions+ as the system prompt; +Protege::ThreadHistoryResolver+
+  # agent's dashboard-editable +instructions+ as the system prompt; +Protege::ThreadHistoryResolver+
   # replays the conversation so far. Insert your own resolvers between them (e.g. to inject records,
   # summaries, or retrieved facts).
   message_resolvers do |chain|
-    chain.use(Protege::LoadTextResolver, role: :system) { |ctx| ctx.persona.instructions }
+    chain.use(Protege::LoadTextResolver, role: :system) { |ctx| ctx.agent.instructions }
     chain.use Protege::ThreadHistoryResolver
   end
 
   # Context assembled for a scheduled run (the Loop layer). There is no inbound thread, so the chain is
-  # just identity: the persona's +instructions+ as the system prompt and the responsibility's own
+  # just identity: the agent's +instructions+ as the system prompt and the responsibility's own
   # prompt as the opening user message. Add task-specific resolvers here if a responsibility needs more.
   responsibility_resolvers do |chain|
-    chain.use(Protege::LoadTextResolver, role: :system) { |ctx| ctx.persona.instructions }
+    chain.use(Protege::LoadTextResolver, role: :system) { |ctx| ctx.agent.instructions }
     chain.use(Protege::LoadTextResolver, role: :user)   { |ctx| ctx.responsibility.instructions }
   end
 end

data/lib/generators/protege/extension_naming.rb

@@ -9,7 +9,7 @@ module Protege
     #
     # The suffix is applied whether or not it was supplied, so all three of +send_email+, +SendEmail+,
     # and +SendEmailTool+ resolve to class +SendEmailTool+ / file +send_email_tool.rb+. Pass an empty
-    # suffix (as the persona generator does) to use the name verbatim.
+    # suffix (as the agent generator does) to use the name verbatim.
     module ExtensionNaming
       private
 

data/lib/generators/protege/hook/templates/hook.rb.tt

@@ -5,7 +5,7 @@
 # Subclassing +Protege::Hook+ wires these handlers onto the event bus at boot (auto-discovered, no
 # registration). Each +on+ block receives a typed, frozen +Protege::Event+ and runs isolated — a raised
 # error is swallowed and logged, never breaking the run. Read event fields with nil-safe named readers
-# (+event.persona+, +event.tool_call+, +event.result+, +event.error+, +event.correlation_id+).
+# (+event.agent+, +event.tool_call+, +event.result+, +event.error+, +event.correlation_id+).
 #
 # Declare a handler with +on(EventClass) { |event| ... }+ (pass several classes to share one block).
 # Available events (all +Protege::+ constants), in fire order:
@@ -21,7 +21,7 @@ class <%= extension_class_name('Hook') %> < Protege::Hook
 
   # TODO: replace with the events you care about.
   on InferenceStartedEvent do |event|
-    log "inference started for persona=#{event.persona&.name} (#{event.correlation_id})"
+    log "inference started for agent=#{event.agent&.name} (#{event.correlation_id})"
   end
 
   private