brainiac 0.4.3 → 0.4.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4a563d46d55d8eb7534c68583a1518f89dc5f5d2685ea1d9c55f43f7015861ab
-  data.tar.gz: c714c9da68680106d183fab643a2c3dc9589ad21d5b96cdd97dd89945dd64c23
+  metadata.gz: ad4e2a76bc43943ef2dd556f67fa2d3b4181836dc5abf04c236944fe08c2bd74
+  data.tar.gz: a26c2581219ed65257deef259809099e4c03b2ec08f7d95d4fb649f831ce6d44
 SHA512:
-  metadata.gz: d36fbb11a493c2545554f3a6a244060f6bd13e49c9790b3d65c01959cbf271ac43c2fea62b795f98fde60c42a36b2b0f8117e29dd7a9853d583271715d8468c0
-  data.tar.gz: 6a4f88dd9b432d306442172fd15e42eece2424c5436ef8b7cb713673323b029e7b12f6842140fb701aae550dc8352f332b3b627f9bb4054a095c49e0eca92d34
+  metadata.gz: 1bdfbf38d91e481e7b51b1f8701fa446bb67206989b651bcb1f7f0bd920b7c18e6f011d21f4e9e59cbab3bcb80a878808e299d4f82f054cb5fc18b1d6bc78f25
+  data.tar.gz: 2c19663ee311472f732ae4c685b0708990deaa0d1101ac52191da5d5bc751444b8b572ae72c1fb002d4ea8158fcd4c8d61557dcd440e7ad0ce0454b10f9541a9

data/README.md

@@ -90,7 +90,7 @@ Any agent can be tagged on any card. If Merlin is working card #42 and someone c
 
 #### Display Name Accuracy
 
-Agents need to spell @mentions exactly as they appear in Fizzy (e.g. `@Robin` not `@robin`). The agent registry's `fizzy_name` field handles this — every prompt includes an agent roster with the correct spelling:
+Agents need to spell @mentions exactly (e.g. `@Robin` not `@robin`). The agent registry's `display_name` field handles this — every prompt includes an agent roster with the correct spelling:
 
 ```
 ## Agent Roster
@@ -100,7 +100,7 @@ When @mentioning other agents in Fizzy comments, use the EXACT spelling below.
   - @Merlin
 ```
 
-Detection is case-insensitive (inbound `@robin` still matches Robin), but outbound mentions use the exact `fizzy_name` from the registry.
+Detection is case-insensitive (inbound `@robin` still matches Robin), but outbound mentions use the exact `display_name` from the registry.
 
 #### Agent-to-Agent Loop Prevention
 
@@ -162,25 +162,73 @@ This installs the `brainiac` binary to your gem bin path (just like `rails`, `rs
 
 ### Quick Start (New Machine)
 
-After installing the gem:
+From zero to an agent you can @mention in Discord:
 
 ```bash
-brainiac setup
+gem install brainiac
+brainiac setup                    # ~/.brainiac/ dirs, example configs, CLI providers
+brainiac install discord          # plus any of: fizzy, github, zoho, basecamp
+cd ~/Code/my-app && brainiac register
+brainiac server --daemon
+
+brainiac agent create Quill --local --avatar ~/quill.png --icon 🪶
 ```
 
-This creates the `~/.brainiac/` directory structure, detects existing agents in `~/.brainiac/agents.json`, and sets your default agent. If no agents exist, it offers to create your first one.
+`agent create` walks you through the rest: it opens `$EDITOR` for the agent's persona, asks for a role, then lets each installed plugin set up its part (for Discord that's one pasted bot token). The bot comes online without a restart. See [Adding an Agent](#adding-an-agent) for what each step does. (If you gave `brainiac setup` a first agent name, finish that agent with `brainiac agent setup <key>` instead.)
+
+Make sure the [prerequisites](#prerequisites) are installed first, at least Ruby, an agent CLI, and qmd.
+
+Each plugin also has its own setup/config commands (e.g. `brainiac discord default <project>`, `brainiac github setup`) and README.
+
+### Adding an Agent
 
-Then install the plugins you need:
+One command creates everything an agent needs:
 
 ```bash
-brainiac install discord     # Discord bots
-brainiac install fizzy       # Fizzy card management
-brainiac install github      # GitHub webhooks
-brainiac install zoho        # Zoho Mail
-brainiac restart             # Restart to activate
+brainiac agent create "Judge Dredd" --local \
+  --avatar ~/dredd.png --icon ⚖️ \
+  --description-file ~/dredd-style.md \
+  --role-file ~/law-specialist.md
 ```
 
-Each plugin has its own setup command (e.g. `brainiac discord setup`, `brainiac github setup`) that creates the necessary config files.
+**Names.** Type the name the way people should see it, quoted if it has spaces. `Judge Dredd` is the display name (Discord username, Fizzy/Basecamp name, @mentions). `judge-dredd` is the key (agents.json, `persona/judge-dredd/`, `memory/judge-dredd/`, `brainiac agent setup judge-dredd`).
+
+**What core writes**
+
+| Input | Flag | Ends up in | If you leave it out |
+|-------|------|------------|---------------------|
+| Persona (how they talk) | `--description-file f`, `--description "text"`, `--description @f`, `--description -` | `brain/persona/<key>/style.md` | `$EDITOR` opens |
+| Role (what they do) | `--role-file f.md` or `--role <existing>` (repeatable) | `roles/<name>.md`, `role` in agents.json | Pick existing roles by number, `n` for a new one in `$EDITOR`, blank to skip |
+| Avatar | `--avatar pic.png` | `brain/persona/<key>/avatar.png` | Plugins skip the picture |
+| Status bar icon | `--icon 🪶` | `waybar.json` (Omarchy bar, waybar, xbar) | Asked for an emoji |
+| Email | `--email a@b.com` | agents.json `email` | `agent_email_template` in `brainiac.json`, e.g. `"agent+{key}@example.com"` |
+| Local dispatch | `--local` | agents.json `local: true` | Agent is known but won't pick up work on this machine |
+
+A `--role-file` keeps its file name: `law-specialist.md` becomes the `law-specialist` role, so the same file can be passed for several agents. Pass `--role <new-name>` to name it something else. If your persona or role file already has YAML frontmatter it's kept as-is.
+
+**What the plugins do** (each installed plugin implements `on_agent_created`)
+
+| Plugin | Automated | You do |
+|--------|-----------|--------|
+| discord | Bot username, avatar, app icon and description, Message Content intent, token saved to agents.json, `user_mappings`, invite link opened | Create the application in the developer portal (opened for you) and paste the bot token |
+| fizzy | Name, avatar, `authorized_users`, `FIZZY_TOKEN` | Open the printed join link in a **private window**, sign up as the agent's email, create an access token and paste it |
+| basecamp | Finds the person by name, or invites them by email after a confirm prompt; adds them to every mapped project, `bot_accounts` entry | Nothing |
+
+Before each plugin runs you're asked `Set up basecamp for Judge Dredd? [Y/n]`. Answer up front with `--skip basecamp` or `--only discord,fizzy`; skips are saved on the agent. `--no-browser` (or `BRAINIAC_NO_BROWSER=1`) prints links instead of opening them.
+
+**Finishing or changing an agent later**
+
+```bash
+brainiac agent setup judge-dredd                      # re-run every plugin; finished steps are skipped
+brainiac agent setup judge-dredd --only fizzy         # just one plugin (also un-skips it)
+brainiac agent setup judge-dredd --icon ⚖️ --only none # change the icon, no plugin steps
+brainiac agent setup judge-dredd --role-file ~/r.md    # add a role
+brainiac agent remove judge-dredd                     # remove from the registry and bars
+```
+
+`agent setup` also asks for a role or icon if the agent doesn't have one yet. With the server running, a new or changed token is picked up without a restart.
+
+Writing a plugin that should take part in this? See "Agent Onboarding (`on_agent_created`)" in [skills/brainiac-plugins/SKILL.md](skills/brainiac-plugins/SKILL.md). `brainiac plugin new` scaffolds the hook for you.
 
 ### Prerequisites
 
@@ -203,13 +251,16 @@ After setup, `~/.brainiac/` looks like:
 ```
 ~/.brainiac/
 ├── brainiac.json        # Core config (default_agent, default_cli_provider)
-├── agents.json          # Agent registry (tokens, display names, local flag)
+├── agents.json          # Agent registry (display names, tokens, role, local flag)
 ├── projects.json        # Registered projects
 ├── users.json           # Cross-platform user identity registry
 ├── plugins.json         # Installed plugins
+├── waybar.json          # Status bar icons/colors per agent (Omarchy bar, waybar, xbar)
+├── roles/               # Role definitions (<name>.md), assigned via agents.json "role"
+├── cli-providers/       # One JSON per agent CLI (kiro, claude, codex, ...)
 ├── brain/
 │   ├── knowledge/       # Shared technical knowledge (all agents)
-│   ├── persona/         # Per-agent personality files
+│   ├── persona/         # Per-agent personality files (style.md, avatar)
 │   └── memory/          # Per-agent session memory
 ├── handlers/            # Legacy custom webhook handlers
 ├── plans/               # Planning mode output
@@ -222,12 +273,12 @@ Plugins add their own config files when installed (e.g. `discord.json`, `fizzy.j
 
 #### 1. Agent Registry (`~/.brainiac/agents.json`)
 
-Maps agents to their identity and environment. Every agent that should dispatch on this machine needs an entry here with `"local": true`:
+Maps agents to their identity and environment. Every agent that should dispatch on this machine needs an entry here with `"local": true`. `brainiac agent create` writes these entries for you (see [Adding an Agent](#adding-an-agent)); this is what one looks like:
 
 ```json
 {
   "sherlock": {
-    "fizzy_name": "Sherlock",
+    "display_name": "Sherlock",
     "local": true,
     "env": {
       "FIZZY_TOKEN": "fizzy_abc...",
@@ -389,6 +440,8 @@ Both machines receive the same webhooks. The agent registry (`~/.brainiac/agents
 
 ### Step 1: Agent Registry
 
+`brainiac agent create` writes the entry, persona, role and plugin tokens for you (see [Adding an Agent](#adding-an-agent)). The rest of this section explains what it produces, in case you want to edit it by hand.
+
 The agent registry at `~/.brainiac/agents.json` is the authority for agent identity. This serves four purposes:
 
 1. **Per-agent environment variables** — any env var can be set per-agent via the `env` hash (e.g. `FIZZY_TOKEN`, `DISCORD_BOT_TOKEN`, custom vars)
@@ -399,7 +452,7 @@ The agent registry at `~/.brainiac/agents.json` is the authority for agent ident
 ```json
 {
   "sherlock": {
-    "fizzy_name": "Sherlock",
+    "display_name": "Sherlock",
     "local": true,
     "env": {
       "FIZZY_TOKEN": "fizzy_abc...",
@@ -407,19 +460,19 @@ The agent registry at `~/.brainiac/agents.json` is the authority for agent ident
     }
   },
   "robin": {
-    "fizzy_name": "Robin",
+    "display_name": "Robin",
     "env": {
       "FIZZY_TOKEN": "fizzy_xyz...",
       "DISCORD_BOT_TOKEN": "Bot_xyz..."
     }
   },
   "merlin": {
-    "fizzy_name": "Merlin"
+    "display_name": "Merlin"
   }
 }
 ```
 
-Keys are lowercase lookup keys (normalized: non-alphanumeric chars become hyphens). `fizzy_name` is the exact Fizzy account display name. The `env` hash is injected into the spawned agent process — every key/value pair becomes an environment variable.
+Keys are lowercase lookup keys (normalized: non-alphanumeric chars become hyphens). `display_name` is the exact name used for @mentions and on every platform (Discord, Fizzy, Basecamp). The `env` hash is injected into the spawned agent process — every key/value pair becomes an environment variable.
 
 The `local` flag controls which agents pick up card assignments on this machine. Agents without `"local": true` are still known for mention detection, display names, tokens, and cross-agent interactions — they just won't pick up card assignments. The default agent (from `AI_AGENT_NAME` or `brainiac.json`) is always considered local.
 
@@ -427,13 +480,13 @@ Agents without an `env` block (like Merlin above on a Linux box) still appear in
 
 The registry reloads on every webhook and via `POST /api/reload`.
 
-### Step 3: Seed Agent Persona and Knowledge
+### Step 2: Seed Agent Persona and Knowledge
 
 Agents get their personality from persona files and their technical context from knowledge files. These live in the brain directory and are indexed by qmd for semantic search.
 
 #### Persona
 
-Each agent needs at least one persona file. Create it directly in the brain:
+Each agent needs at least one persona file. `brainiac agent create` writes `style.md` from `--description-file` or `$EDITOR`. To create one by hand:
 
 ```bash
 # Create persona file for your agent
@@ -471,7 +524,7 @@ qmd update
 
 Agents also update knowledge themselves during sessions (when they learn something significant), but seeding it with your project's conventions and tool docs gives them a head start.
 
-### Step 4: Initialize Each Agent's Brain
+### Step 3: Initialize Each Agent's Brain
 
 ```bash
 brainiac brain init              # Default agent (from brainiac.json or AI_AGENT_NAME)
@@ -479,7 +532,7 @@ brainiac brain init SecurityBot  # Additional agent
 brainiac brain list              # Verify all agents
 ```
 
-This creates the directory structure, sets up qmd collections, and indexes everything. Run this after you've placed your persona and knowledge files.
+This creates the directory structure, sets up qmd collections, and indexes everything. Run this after you've placed your persona and knowledge files (`agent create --local` already does it for the new agent).
 
 ### How Dispatch Works
 
@@ -559,6 +612,8 @@ React with ❌ to any message that triggered an agent to immediately terminate t
 
 ### Setup
 
+**For a new agent, use `brainiac agent create` (or `brainiac agent setup <key> --only discord` for an existing one).** It covers steps 1-3 below: it opens the developer portal, takes the pasted token, sets the bot's name, avatar and Message Content intent, and opens the invite link. The manual steps are here for reference.
+
 #### Step 1: Create Discord Applications
 
 Create one Discord application per agent at https://discord.com/developers/applications:
@@ -588,7 +643,7 @@ brainiac discord token robin "BOT_TOKEN_FOR_ROBIN"
 This adds `DISCORD_BOT_TOKEN` to the agent's `env` hash in `~/.brainiac/agents.json`. You can verify with:
 
 ```bash
-brainiac discord agents
+brainiac agent <name> show
 ```
 
 #### Step 3: Invite Bots to Your Server
@@ -597,18 +652,22 @@ Go to the "OAuth2" tab for each application:
 
 1. Under "OAuth2 URL Generator", check the **bot** scope
 2. Under "Bot Permissions", select:
+   - View Channels
    - Send Messages
+   - Embed Links
+   - Attach Files
+   - Read Message History
+   - Add Reactions
    - Create Public Threads
    - Send Messages in Threads
-   - Add Reactions
-   - Read Message History
+   - Manage Threads
 3. Copy the generated URL and open it in your browser
 4. Select your server and authorize
 
-The permission integer for these permissions is `326417591296`. You can also construct the invite URL manually:
+The permission integer for these permissions is `326417632320`. You can also construct the invite URL manually:
 
 ```
-https://discord.com/oauth2/authorize?client_id=YOUR_APP_ID&scope=bot&permissions=326417591296
+https://discord.com/oauth2/authorize?client_id=YOUR_APP_ID&scope=bot&permissions=326417632320
 ```
 
 Replace `YOUR_APP_ID` with the Application ID from the "General Information" tab. Repeat for each agent bot.
@@ -709,7 +768,7 @@ Leave `authorized_role_ids` and `authorized_user_ids` empty to allow everyone in
 
 ```bash
 brainiac discord token <agent> <token>        # Set Discord bot token for an agent
-brainiac discord agents                       # List agents with Discord bot tokens
+brainiac discord owner <user-id>              # Set the owner's Discord user ID
 brainiac discord default <project>            # Set default project for all channels
 brainiac discord map <channel-id> <project>   # Override for a specific channel
 brainiac discord config                       # Show current Discord config
@@ -1124,8 +1183,8 @@ Brainiac supports a plugin system that lets you extend functionality via Ruby ge
 ### Installing Plugins
 
 ```bash
-brainiac install whatsapp      # Installs brainiac-whatsapp gem + registers it
-brainiac install slack         # Installs brainiac-slack gem + registers it
+brainiac install discord       # Installs brainiac-discord gem + registers it
+brainiac install fizzy         # Installs brainiac-fizzy gem + registers it
 brainiac restart               # Restart server to load new plugins
 ```
 
@@ -1134,7 +1193,7 @@ This runs `gem install brainiac-<name>`, adds the plugin to `~/.brainiac/plugins
 You can also install a specific version:
 
 ```bash
-brainiac install whatsapp --version 0.2.0
+brainiac install discord --version 0.0.25
 ```
 
 ### Managing Plugins
@@ -1147,8 +1206,8 @@ brainiac uninstall <name>      # Remove plugin from config (gem stays installed)
 To fully remove the gem after uninstalling:
 
 ```bash
-brainiac uninstall whatsapp
-gem uninstall brainiac-whatsapp
+brainiac uninstall discord
+gem uninstall brainiac-discord
 ```
 
 ### Configuration
@@ -1158,7 +1217,7 @@ Installed plugins are tracked in `~/.brainiac/plugins.json`:
 ```json
 {
   "plugins": [
-    { "name": "whatsapp", "gem": "brainiac-whatsapp", "installed_at": "2026-06-30T14:00:00-04:00" }
+    { "name": "discord", "gem": "brainiac-discord", "installed_at": "2026-06-30T14:00:00-04:00" }
   ]
 }
 ```
@@ -1167,7 +1226,7 @@ At server startup, `load_plugins!` iterates this list, requires each gem, and ca
 
 ### Creating a Plugin
 
-Any Ruby gem named `brainiac-<name>` can be a Brainiac plugin. The gem must:
+Any Ruby gem named `brainiac-<name>` can be a Brainiac plugin. `brainiac plugin new <name>` generates a working skeleton (gemspec, module, CLI with an `on_agent_created` stub, tests, and a skill doc); the full contract is in [skills/brainiac-plugins/SKILL.md](skills/brainiac-plugins/SKILL.md). The gem must:
 
 1. **Define a module** at `Brainiac::Plugins::<Name>`
 2. **Implement `.register(app)`** — receives the Sinatra app instance for defining routes and starting threads
@@ -1222,7 +1281,8 @@ The `Brainiac::Plugins` namespace is defined in `lib/brainiac.rb`. Plugin module
 | fizzy | `brainiac-fizzy` | Fizzy card management — assignment, comments, @mentions, cross-agent reviews, duplicate detection, planning mode |
 | github | `brainiac-github` | GitHub webhooks — PR reviews, PR comments, PR merges, CI workflow notifications, deploy tracking |
 | zoho | `brainiac-zoho` | Zoho Mail webhooks — rule-based email notifications, AI triage, OAuth for content fetching |
-| whatsapp | `brainiac-whatsapp` | WhatsApp Business API integration |
+| basecamp | `brainiac-basecamp` | Basecamp epic orchestration — card tables, review gates, epic branches |
+| featureparity | `brainiac-featureparity` | FeatureParity integration for Brainiac agents |
 
 ### Backward Compatibility
 
@@ -1275,10 +1335,31 @@ brainiac brain search --persona <query>  # Search agent persona
 brainiac brain list                      # List everything
 ```
 
+### Agents
+
+```bash
+brainiac agent create <name> [flags]     # New agent + persona + role + plugin setup (see Adding an Agent)
+brainiac agent setup <name> [flags]      # Finish/re-run plugin setup; change icon, avatar, email, role
+brainiac agent remove <name>             # Remove from the registry
+brainiac agent list                      # List agents
+brainiac agent <name> show               # Show config (tokens redacted)
+brainiac agent <name> env <KEY> <VALUE>  # Set an env var
+```
+
+### Roles
+
+```bash
+brainiac role list                         # Roles and who has them
+brainiac role show <name>                  # Print a role
+brainiac role create <name> [--from f] [--assign agent]  # New role ($EDITOR on a template)
+brainiac role assign <agent> <role>        # Add a role to an agent
+brainiac role unassign <agent> <role>      # Remove it
+```
+
 ### Plugins
 
 ```bash
-brainiac install <name>                  # Install a plugin gem (e.g., whatsapp)
+brainiac install <name>                  # Install a plugin gem (e.g., discord)
 brainiac install <name> --version 0.2.0  # Install specific version
 brainiac uninstall <name>                # Remove plugin from config
 brainiac plugins                         # List installed plugins
@@ -1439,7 +1520,7 @@ ls brainiac receiver.rb lib/brainiac/*.rb lib/brainiac/handlers/*.rb | entr -r b
 
 **Agent commenting as wrong user:** Check `~/.brainiac/agents.json` has the correct `FIZZY_TOKEN` in the agent's `env` hash. The env is injected into the spawned agent process — verify with `curl http://localhost:4567/api/agents` to see the roster.
 
-**Agent @mention not linking in Fizzy:** The `fizzy_name` in `agents.json` must match the exact Fizzy account name (case-sensitive). Check `curl http://localhost:4567/api/agents` to see what the roster looks like.
+**Agent @mention not linking in Fizzy:** The `display_name` in `agents.json` must match the exact Fizzy account name (case-sensitive). Check `curl http://localhost:4567/api/agents` to see what the roster looks like.
 
 **Agent-to-agent loop:** Shouldn't happen — dispatch depth is capped at 10 hops by default. Check `curl http://localhost:4567/api/dispatch-depth` to see current state. Adjust `AGENT_DISPATCH_MAX_DEPTH` in `lib/brainiac/sessions.rb` if needed.
 

data/bin/brainiac

@@ -374,6 +374,25 @@ def write_role_file(role_name, text, agent_name = nil)
   file
 end
 
+# Role for --role-file: named after the first --role that doesn't exist yet,
+# else the file's name (blog-writer.md → blog-writer), so one file can be
+# reused across agents. Reusing an existing role is fine when the file is
+# that role or has the same content; a different role by that name is an error.
+# Returns [role_name, needs_write].
+def role_from_file(role_file, requested_roles)
+  name = requested_roles.find { |r| !available_roles.include?(r) } || role_name_arg(File.basename(role_file, ".*"))
+  existing = File.join(BRAINIAC_DIR, "roles", "#{name}.md")
+  return [name, true] unless File.exist?(existing)
+
+  same = File.expand_path(existing) == role_file || File.read(existing).strip == File.read(role_file).strip ||
+         File.read(existing).include?(File.read(role_file).strip)
+  return [name, false] if same
+
+  puts "❌ A different role named '#{name}' already exists (#{existing})."
+  puts "   Use --role #{name} to assign it as-is, or --role <new-name> to name the role from #{role_file}."
+  exit 1
+end
+
 # Add roles to a registry entry, keeping the string-or-array shape.
 def assign_roles(entry, new_roles)
   roles = (Array(entry["role"]) + new_roles).uniq
@@ -1537,10 +1556,14 @@ when "setup"
 
   puts ""
   puts "Next steps:"
-  puts "  1. Register projects: cd ~/Code/myproject && brainiac register"
-  puts "  2. Initialize brain: brainiac brain init"
-  puts "  3. Install plugins: brainiac install discord / fizzy / github / zoho"
-  puts "  4. Start server: brainiac server"
+  puts "  1. Install plugins: brainiac install discord / fizzy / github / zoho / basecamp"
+  puts "  2. Register projects: cd ~/Code/myproject && brainiac register"
+  puts "  3. Start server: brainiac server --daemon"
+  if agent_name
+    puts "  4. Finish #{agent_name} (persona, role, icon, plugin accounts): brainiac agent setup #{existing_agents.first}"
+  else
+    puts "  4. Add an agent (persona, role, icon, plugin accounts): brainiac agent create <Name> --local"
+  end
 
   # Shell completion setup
   puts ""
@@ -2592,7 +2615,8 @@ when "agent"
       puts "  --local                Mark agent as local (dispatches on this machine)"
       puts "  --role <role>          Assign a role (repeatable)"
       puts "  --role-file <path>     Create a role from a markdown file and assign it"
-      puts "                         (named after the agent, or after a new --role name)"
+      puts "                         (named after the file, e.g. blog-writer.md → blog-writer,"
+      puts "                         or after a new --role name; an identical role is reused)"
       puts "  --cli <provider>       Set CLI provider (default: kiro)"
       puts "  --skip <plugins>       Don't set up these plugins for this agent, e.g. --skip basecamp"
       puts "  --only <plugins>       Set up just these plugins, e.g. --only discord,fizzy"
@@ -2612,7 +2636,7 @@ when "agent"
       puts "  brainiac agent create MyAgent                            # interactive"
       puts "  brainiac agent create SecurityBot --local --role code-reviewer"
       puts "  brainiac agent create \"Judge Dredd\" --local --avatar dredd.png --icon ⚖️ \\"
-      puts "    --description-file dredd-style.md --role-file dredd-role.md"
+      puts "    --description-file dredd-style.md --role-file law-specialist.md"
       exit 1
     end
 
@@ -2720,13 +2744,9 @@ when "agent"
       exit 1
     end
     if role_file
-      # --role-file names its role after a --role that doesn't exist yet, else the agent key.
-      new_role = (roles - available_roles).first || agent_key
-      if available_roles.include?(new_role)
-        puts "❌ Role '#{new_role}' already exists. Pass --role <new-name> to name the role from #{role_file}."
-        exit 1
-      end
-      roles |= [new_role]
+      role_name, write_role = role_from_file(role_file, roles)
+      new_role = role_name if write_role
+      roles |= [role_name]
     elsif roles.empty? && $stdin.tty?
       roles = prompt_for_agent_role(agent_key, name)
     end
@@ -2757,7 +2777,7 @@ when "agent"
       end
     end
 
-    puts "✓ Created role #{write_role_file(new_role, File.read(role_file), name)}" if new_role
+    puts "✓ Created role #{write_role_file(new_role, File.read(role_file))}" if new_role
 
     registry[agent_key] = entry
     File.write(agent_registry_file, JSON.pretty_generate(registry))
@@ -2836,7 +2856,7 @@ when "agent"
       puts ""
       puts "  --icon e      Set the status bar icon (Omarchy bar, waybar, xbar)"
       puts "  --role r      Assign an existing role"
-      puts "  --role-file f Create a role from a markdown file (named after the agent) and assign it"
+      puts "  --role-file f Create a role from a markdown file (named after the file) and assign it"
       puts "  --skip a,b    Never set up these plugins for this agent (saved)"
       puts "  --only a,b    Run just these plugins (also un-skips them)"
       puts "  --no-browser  Print links instead of opening them"
@@ -2896,12 +2916,8 @@ when "agent"
 
     display = entry["display_name"] || name
     if role_file
-      role_name = (new_roles - available_roles).first || agent_key
-      if available_roles.include?(role_name)
-        puts "❌ Role '#{role_name}' already exists. Pass --role <new-name> to name the role from #{role_file}."
-        exit 1
-      end
-      puts "✓ Created role #{write_role_file(role_name, File.read(role_file), display)}"
+      role_name, write_role = role_from_file(role_file, new_roles)
+      puts "✓ Created role #{write_role_file(role_name, File.read(role_file))}" if write_role
       new_roles |= [role_name]
     elsif new_roles.empty? && entry["role"].nil? && $stdin.tty?
       new_roles = prompt_for_agent_role(agent_key, display)
@@ -4608,7 +4624,7 @@ when "help", "--help", "-h", nil
       Brainiac CLI - Manage projects with Brainiac server
 
       Usage:
-        brainiac setup                  Bootstrap a new machine (deps, dirs, configs)
+        brainiac setup                  Bootstrap a new machine (dirs, example configs, CLI providers)
         brainiac server [options]       Start the Brainiac webhook server (foreground)
         brainiac start [options]        Alias for 'brainiac server'
         brainiac stop                   Stop the running server
@@ -4683,6 +4699,9 @@ when "help", "--help", "-h", nil
         role unassign <agent> <role>     Remove a role from an agent
 
       Agent Commands:
+        agent create <name> [options]      Add an agent: persona, role, icon, plugin accounts
+        agent setup <name> [options]       Finish or re-run plugin setup (skips what's done)
+        agent remove <name>                Remove an agent from the registry
         agent list                         List all agents in the registry
         agent <name> show                  Show agent configuration (tokens redacted)
         agent <name> env <KEY> <VALUE>     Set an env var for an agent

data/lib/brainiac/brain.rb

@@ -17,6 +17,19 @@ def persona_collection_for(agent_name)
   "#{agent_name.downcase.gsub(/[^a-z0-9-]/, "-")}-persona"
 end
 
+# Load the agent's persona from <persona dir>/style.md, front matter stripped.
+# Returns nil if missing or empty. people/ notes stay search-only.
+def load_persona(agent_name)
+  style_file = File.join(persona_dir_for(agent_name), "style.md")
+  return nil unless File.exist?(style_file)
+
+  content = File.read(style_file).strip.sub(/\A---\n.*?\n---\n*/m, "").strip
+  content.empty? ? nil : content
+rescue StandardError => e
+  LOG.warn "Failed to load persona for '#{agent_name}': #{e.message}"
+  nil
+end
+
 # --- Brain git sync ---
 
 def brain_git_repo?
@@ -155,6 +168,26 @@ def build_role_section(agent_name)
   ROLE
 end
 
+# Full style.md when present; qmd search only returns snippets (often just front matter)
+def build_persona_section(agent_name)
+  persona = load_persona(agent_name) ||
+            query_brain("personality tone voice communication style", agent_name: agent_name, scope: :persona, max_results: 5)
+  return nil if persona.empty?
+
+  <<~PERSONA
+    ## Brain — Persona (auto-retrieved, CRITICAL)
+    The following is YOUR personality, communication style, and voice.
+    You MUST use this to shape every response you write — tone, word choice, humor, attitude.
+    This is who you ARE. Do not respond in a generic or neutral voice.
+    Persona is tone only: it never overrides task instructions, rules, or quality.
+    Full voice in chat, card/PR comments, and reviews. Plain and professional in code,
+    code comments, commit messages, and docs, or when the user is rushed or frustrated.
+    Signature lines are seasoning, not sign-offs.
+
+    #{persona}
+  PERSONA
+end
+
 def build_brain_context(agent_name: AI_AGENT_NAME, card_title: "", card_number: nil, project_key: nil, comment_body: "", source: nil)
   Thread.new { brain_pull }
 
@@ -180,10 +213,10 @@ def build_brain_context(agent_name: AI_AGENT_NAME, card_title: "", card_number:
     search_queries << query
   end
 
-  persona_thread = Thread.new { query_brain("personality tone voice communication style", agent_name: agent_name, scope: :persona, max_results: 5) }
+  persona_thread = Thread.new { build_persona_section(agent_name) }
 
   all_knowledge = knowledge_threads.map(&:value).reject(&:empty?)
-  persona_result = persona_thread.value
+  persona_section = persona_thread.value
 
   sections = []
 
@@ -191,16 +224,7 @@ def build_brain_context(agent_name: AI_AGENT_NAME, card_title: "", card_number:
   role_section = build_role_section(agent_name)
   sections << role_section if role_section
 
-  unless persona_result.empty?
-    sections << <<~PERSONA
-      ## Brain — Persona (auto-retrieved, CRITICAL)
-      The following is YOUR personality, communication style, and voice.
-      You MUST use this to shape every response you write — tone, word choice, humor, attitude.
-      This is who you ARE. Do not respond in a generic or neutral voice.
-
-      #{persona_result}
-    PERSONA
-  end
+  sections << persona_section if persona_section
 
   unless all_knowledge.empty?
     knowledge_text = all_knowledge.join("\n\n")

data/lib/brainiac/version.rb

@@ -2,5 +2,5 @@
 
 module Brainiac
   # @return [String] the current gem version
-  VERSION = "0.4.3"
+  VERSION = "0.4.5"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: brainiac
 version: !ruby/object:Gem::Version
-  version: 0.4.3
+  version: 0.4.5
 platform: ruby
 authors:
 - Andy Davis