# Profile Bootstrapping

> Add new Hermes profiles to an existing Kanban multi-agent fleet — create profile, write config following fleet conventions, set delegation policy, integrate into orchestration.

- Skill: `theheavenlyd3mon/profile-bootstrapping` (Agent Skill, multi-file: 7 files)
- Install (CLI): `npx skillmds add theheavenlyd3mon/profile-bootstrapping`
- Raw SKILL.md: https://api.skillmd.com/api/skills/theheavenlyd3mon/profile-bootstrapping/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra
- Author: theheavenlyd3mon (https://skillmd.com/u/theheavenlyd3mon)
- Updated: 2026-09-09
- Page: https://skillmd.com/skills/theheavenlyd3mon/profile-bootstrapping

---


IDENTITY: Fleet Architect. Add new profiles to an existing multi-agent Kanban fleet following established conventions — never invent your own template.

## When to use this skill

You need to add a new profile to an existing Hermes multi-agent fleet. This covers the full lifecycle from profile creation through orchestration integration.

## Step-by-step

### Step 0 — Audit existing profiles before enhancing

Before creating a new profile OR planning enhancements to an existing one, check what's already there:

```bash
# List all profiles and their models
hermes profile list

# Check if target profile exists
ls -la ~/.hermes/profiles/<name>/

# Read existing SOUL.md (if any)
cat ~/.hermes/profiles/<name>/SOUL.md

# Read existing config (if any)
cat ~/.hermes/profiles/<name>/config.yaml

# Check what skills are loaded
ls ~/.hermes/profiles/<name>/skills/
```

**Why:** The Oracle profile (2026-05-21) existed with a solid SOUL.md and config but zero skills. Discovering this before planning saved a full "create from scratch" cycle and focused the plan on skill integration rather than profile creation.

**Rule:** Always audit before building. An existing profile with a good SOUL.md but missing skills is a different task than creating a new profile from scratch.

### Step 1 — Determine profile attributes

Before creating, decide these based on the role:

| Attribute | Options | Decision rule |
|-----------|---------|---------------|
| **Model tier** | Reasoning (r1), Specialized (v3.2, coder-plus), Speed (flash), Consensus (r1 xhigh), Creative (coder-next) | What does this profile DO? Deep reasoning? Get expensive. Broad sweep? Get cheap. |
| **Reasoning effort** | medium, xhigh | Workers → medium. Consensus/review/adversarial → xhigh. |
| **Provider** | nous (all current profiles) | Always nous unless the profile needs a provider not available on Nous. |
| **Delegation policy** | enabled or disabled | Only foreman/orchestrator and the user's chat profile retain delegation. All workers get delegation disabled. |
| **Plugins** | disk-cleanup, icarus, hermes-lcm | All profiles get all three. disk-cleanup = temp cleanup, icarus = cross-agent shared memory, hermes-lcm = history compression. |

### Step 2 — Create the profile

Before creating, check if external skill repos have relevant skills for this profile's domain. See the `multi-agent-profile-redesign` skill's `references/external-skill-repo-evaluation.md` for the evaluation framework.

```bash
hermes profile create <name>
```

This creates `~/.hermes/profiles/<name>/` with standard directories and SOUL.md. It does NOT create a config.yaml — that must be written separately.

### Step 3 — Write config.yaml

Copy the template from an existing worker profile (e.g. coder). The critical fields to change per profile:

```yaml
model:
  provider: nous
  default: <model-id>                     # ← CHANGE per profile role
  base_url: https://inference-api.nousresearch.com/v1

agent:
  reasoning_effort: <medium|xhigh>        # ← SET based on role (xhigh for consensus/review)

plugins:
  enabled:
    - disk-cleanup                        # ← KEEP for all profiles
    - icarus                              # ← KEEP for all profiles
    - hermes-lcm                          # ← KEEP for all profiles — history compression

skills:
  external_dirs:
  - ~/.hermes/skills          # ← KEEP for all profiles

terminal:
  env_passthrough:
  - GITHUB_TOKEN                          # ← KEEP for all profiles
  - GH_TOKEN
```

Everything else (security, compression, memory, auxiliary providers, display, TTS, delegations settings) stays identical across all profiles — copy verbatim from an existing config.

**API server config (only if needed):** Most profiles run as Discord bots and don't need an HTTP API server. Only profiles that the workspace connects to (senna, coder) need `platforms.api_server`. Add it only when the profile requires HTTP access:

```yaml
platforms:
  api_server:
    enabled: true
    extra:
      host: 127.0.0.1
      port: <unique port, not 8642 unless it's the only one>
```

Each profile with an API server must use a unique port. If another profile already has 8642, pick 8643 (or next free port). See the `hermes-companion-apps` skill's `references/hermes-workspace-setup.md` for the full multi-profile port allocation workflow.

**Pitfall: `hermes config set` writes to the ACTIVE profile, not a target profile.** Running `hermes config set plugins.enabled '...'` from senna's session writes to senna's config.yaml, not the profile you intended. To edit another profile's config, either:
- `cd ~/.hermes/profiles/<target> && hermes config set ...` (changes CWD to target profile)
- Edit the config.yaml directly with the `patch` tool or `write_file`

This burned a session where senna's plugins got overwritten with designer's values. Always verify which file was modified after running `hermes config set`.

**Pitfall:** Default profiles from `hermes profile create` may lack a config.yaml. Do not assume it exists — always write one explicitly.

### Step 4 — Disable delegation on worker profiles

Only foreman/orchestrator and the user's chat profile (senna) should have `delegation` enabled. All workers must have it disabled:

```bash
hermes --profile <name> tools disable delegation
```

Verify:
```bash
hermes --profile <name> tools list | grep delegation
# Expected: ✗ disabled delegation  👥 Task Delegation
```

**Why:** Forces all multi-profile work through Kanban — work survives crashes, has audit trail, uses proper profile context, supports dependency chains. Workers should never spawn subagents; that's the foreman's job.

### Step 4½ — Verify required plugins are active

After delegation is set, confirm the profile has the required plugins. `hermes profile create` does NOT automatically write a config.yaml with plugins — you must either copy the template (Step 3) or check:

```bash
grep -A4 'plugins:' ~/.hermes/profiles/<name>/config.yaml
# Expected: disk-cleanup, icarus, hermes-lcm
# Missing any? Patch the file directly.
```

If the profile is missing plugins, add them inline:
```bash
# Edit config.yaml — find the plugins.enabled block and add missing entries
```

**Pitfall:** The `hermes profile create` command creates a profile dir and SOUL.md but may not create config.yaml at all. If missing, write one following the template from Step 3.

**Pitfall:** Profiles created via `hermes profile create` (2026-05-18 batch) may lack `icarus` or `hermes-lcm` plugins — always verify after creation.

### Step 5 — Reference in fleet documentation

If the new profile introduces a new role category (e.g. consensus, creative, exploration):
- Update `profile-model-fleet` skill with the new profile's model, pricing, and tier
- Update `kanban-orchestrator` skill's fan-out examples if the new profile changes the default task-graph patterns
- Sync Obsidian llm-wiki fleet topology docs: update `concepts/multi-agent-topology.md` (profile inventory table + tier column) and `concepts/hermes-agent-team-architecture.md` (agent roles list + workflow + topology diagram)

**Fleet topology docs sync pattern (Obsidian):**
1. **`llm-wiki/concepts/multi-agent-topology.md`** — Profile Inventory table: add/remove rows, update count in the first paragraph and heading. If adding a new tier category, add a row explaining it.
2. **`llm-wiki/concepts/hermes-agent-team-architecture.md`** — Agent Roles numbered list: insert at correct position, renumber. Workflow step list: add new agent's step in the pipeline. Communication topology diagram: add the new agent to the ASCII tree.
3. Bump `updated:` in the frontmatter of both files.

### Step 6 — Save memory

Record the new profile's name, model, reasoning_effort, and role in Mnemosyne so the orchestrator knows about it in future sessions:

Key facts to store: profile name, model, reasoning_effort setting, role description, delegation disabled status.

## Right-sizing Profile Toolsets

New profiles ship with a copy-paste blob of every tool. This wastes context tokens and gives worker bots capabilities they shouldn't have (e.g. a coder with `image_gen`, an architect with `kanban`). After creating profiles, trim each one to its role.

### The 3 config surfaces to align

Every profile has three places where tools/plugins are declared. All three must match:

1. **`platform_toolsets.cli`** — which tools the profile can use
2. **`plugins.enabled`** — which plugin providers are loaded (gates tool functionality)
3. **`known_plugin_toolsets.cli`** — which plugin-provided tools are exposed

If `image_gen` is in `platform_toolsets` but `image_gen/fal` is NOT in `plugins.enabled`, the tool exists but has no provider — silent failure.

### Role-to-toolset mapping (Discord fleet)

| Profile | Role | CLI Tools | Plugins | Known_PT |
|---------|------|-----------|---------|----------|
| senna | Coordinator | (full — all tools) | (full) | fabric, spotify, web-search-plus |
| architect | System Design | file, terminal, skills, web, vision, session_search | disk-cleanup, icarus, hermes-lcm | — |
| coder | Implementation | file, terminal, code_execution, skills, web, vision, session_search | disk-cleanup, icarus, hermes-lcm | — |
| designer | UI/Graphics | file, terminal, image_gen, skills, web, vision, browser | disk-cleanup, icarus, hermes-lcm, image_gen/fal, image_gen/krea | — |
| foreman | Orchestration | file, terminal, delegation, kanban, memory, messaging, skills, todo, session_search | disk-cleanup, icarus, hermes-lcm | — |
| oracle | Market Intel | file, terminal, skills, web, vision, session_search, browser, memory, fabric | disk-cleanup, icarus, hermes-lcm, fabric | fabric |
| researcher | Investigation | file, terminal, skills, web, vision, session_search, browser, fabric | disk-cleanup, icarus, hermes-lcm, fabric | fabric |
| secretary | Knowledge Keeper | file, terminal, skills, web, memory, session_search, messaging, vision, fabric | disk-cleanup, icarus, hermes-lcm, fabric | fabric |

**Rationale for key decisions:**
- `messaging` — only foreman (dispatching tasks) and secretary (pushing docs). Worker bots respond when called.
- `memory` — only foreman (project state), secretary (knowledge base), oracle (watchlists/trade history).
- `fabric` — only oracle (market analysis patterns), researcher (content extraction), secretary (document processing).
- `browser` — only designer (checking design references), oracle/researcher (navigating live sites).
- `image_gen` — only designer.
- `delegation` — only foreman and senna.
- `kanban` — only foreman.
- `vision` — roles that process images: designer, oracle, researcher, secretary, plus architect/coder/reviewer for diagrams.
- Everyone drops `moa`, `clarify`, `spotify`, `todo` (except foreman).

Non-Discord profiles (data-analyst, debugger, devops, reviewer, security) can be optimized later — they're Kanban-dispatched workers with less impact.

For the full fleet toolset matrix with rationale, see `references/fleet-toolset-mapping.md`. For the windowshermes fleet's skill distribution across profiles, see `references/windowshermes-skill-distribution.md`.

## How to patch a profile's toolset

Edit `config.yaml` directly — do NOT use `hermes config set` for non-senna profiles (see pitfall below).

```yaml
# platform_toolsets.cli — the tool list
platform_toolsets:
  cli:
  - file
  - terminal
  - skills
  - web
  - vision
  - session_search

# plugins.enabled — the provider list
plugins:
  enabled:
  - disk-cleanup
  - icarus
  - hermes-lcm
  disabled: []

# known_plugin_toolsets.cli — which plugin tools to expose
known_plugin_toolsets:
  cli: []
```

### image_gen per-profile checklist

For any profile that needs image generation, ALL FOUR must be set:

1. `image_gen` in `platform_toolsets.cli`
2. `image_gen/fal` (and/or `image_gen/krea`) in `plugins.enabled`
3. `image_gen:` section with `enabled: true` and `use_gateway: true`
4. `FAL_KEY` in the profile's `.env` (or rely on Nous managed gateway with `use_gateway: true`)

Without step 2, the tool exists but has no provider. Without step 3, the gateway routing is off.

## Profile Audit & Cleanup

Periodically audit the fleet to prune dead weight. Profiles accumulate from experiments and abandoned ideas — they consume disk, clutter `hermes gateway list`, and confuse orchestration.

### Audit workflow

```bash
# 1. List all profiles and gateway status
hermes gateway list

# 2. Check disk usage per profile
du -sh ~/.hermes/profiles/*/

# 3. For each non-Discord profile, check if it has a custom SOUL.md
for p in $(ls ~/.hermes/profiles/); do
  soul="$HOME/.hermes/profiles/$p/SOUL.md"
  if [ -f "$soul" ]; then
    first=$(head -1 "$soul")
    if echo "$first" | grep -q "You are Hermes Agent"; then
      echo "GENERIC: $p"
    else
      echo "CUSTOM:  $p"
    fi
  else
    echo "NO SOUL: $p"
  fi
done

# 4. Check which profiles have Discord bots (launchd plists)
ls ~/Library/LaunchAgents/ai.hermes.gateway-*.plist
```

### Deletion criteria

Delete a profile if ALL of these are true:
- No Discord bot (no launchd plist)
- Generic SOUL.md (default boilerplate, no custom persona)
- No unique skills or config worth preserving
- Not referenced by any active kanban or cron workflow

**Safe to delete:** `rm -rf ~/.hermes/profiles/<name>`

### Transforming generic profiles into specialists

When a profile has a good name but generic SOUL.md (e.g., "designer" with default boilerplate):

1. Audit existing skills — check both the profile's own `skills/` dir AND what `external_dirs` pulls in
2. Strip non-relevant skills (see "Skill stripping" below)
3. Write a custom SOUL.md following the specialist pattern (IDENTITY, PersRubric, STYLE, AVOID, Role, Philosophy, Tools, Output Standards)
4. Verify the model is appropriate for the role (creative → qwen3-coder-next, analytical → reasoning model, etc.)

**Example:** Designer profile (2026-05-27) — had 900+ skills (all creative builtins + local UX/design skills from shared external_dirs) but generic SOUL.md. Transformed into "Master UI & Graphics" specialist by:
1. Removing 22 non-graphics skill category directories from profile's `skills/` dir
2. Setting `external_dirs: []` in config to stop loading shared skills
3. Writing a focused SOUL.md ("you BUILD visual things, not a UX consultant")

#### Skill stripping for specialization

When a profile needs to focus on ONE domain, strip everything else:

```bash
# 1. See what's in the profile's skills directory
find ~/.hermes/profiles/<name>/skills -maxdepth 2 -type d | sed 's|.*/skills/||' | sort

# 2. Remove non-relevant category directories
#    ⚠️ rm -rf may be blocked by safety guard — use execute_code with shutil.rmtree:
python3 -c "
import shutil, os
base = os.path.expanduser('~/.hermes/profiles/<name>/skills')
for d in ['category1', 'category2', ...]:
    path = os.path.join(base, d)
    if os.path.isdir(path):
        shutil.rmtree(path)
        print(f'Removed {d}')
"

# 3. Remove external_dirs from config to stop loading shared skills
#    Edit config.yaml: set external_dirs: []

# 4. Rewrite SOUL.md to match reduced scope
```

**Why strip skills?** A profile with 900+ skills wastes context tokens loading irrelevant skill metadata. A focused profile loads only what it needs — faster startup, cleaner behavior, fewer distractions.

**Pitfall: `external_dirs` pulls in EVERYTHING.** The shared `~/.hermes/skills/` directory has 800+ skills across all domains. If a profile's config has `external_dirs: [~/.hermes/skills]`, it loads ALL of them regardless of what's in the profile's own `skills/` dir. For specialized profiles, set `external_dirs: []` and rely on the profile's own skills + builtin skills only.

## Delegation policy at a glance

| Profile type | delegation enabled? | Reasoning |
|--------------|-------------------|-----------|
| **senna** (user chat) | ✅ YES | Primary interface — needs flexibility |
| **foreman** (orchestrator) | ✅ YES | Needs delegate_task for quick one-shots + Kanban for durable work |
| **All workers** (coder, architect, designer, reviewer, debugger, security, researcher, data-analyst, devops, secretary, oracle) | ❌ NO | Workers should never spawn children. Multi-profile work goes through Kanban. |

## Verification checklist

After adding a new profile:
- [ ] `hermes profile list` shows the new profile
- [ ] `cat ~/.hermes/profiles/<name>/config.yaml` has correct model, provider, base_url
- [ ] If the profile needs an HTTP API server (workspace connectivity): `grep -A4 'api_server:' ~/.hermes/profiles/<name>/config.yaml` shows enabled and unique port
- [ ] If the profile is Discord-only: confirm NO `api_server` section — not needed
- [ ] `grep 'reasoning_effort' ~/.hermes/profiles/<name>/config.yaml` is correct (medium for workers, xhigh for council)
- [ ] `hermes --profile <name> tools list | grep delegation` shows ✗ disabled (unless it's foreman or senna)
- [ ] `grep -A4 'plugins:' ~/.hermes/profiles/<name>/config.yaml | head -6` shows disk-cleanup + icarus + hermes-lcm
- [ ] Obsidian fleet topology docs updated (see Step 5)
- [ ] `hermes --profile <name> chat -q "ping" -Q` runs without errors (quick smoke test)

**Pitfall: `auth.json` symlink missing after `hermes profile create`.** The create command does NOT symlink `auth.json` from the global hermes dir. This causes "Hermes is not logged into Nous Portal" errors when the profile tries to use the Nous provider. After creating any profile, verify and fix:

```bash
# Check if auth.json symlink exists
ls -la ~/.hermes/profiles/<name>/auth.json
# If missing, create it:
ln -s ~/.hermes/auth.json ~/.hermes/profiles/<name>/auth.json
```

**Pitfall: `.env` symlink causes token conflicts for multi-bot Discord setups.** By default, `hermes profile create` symlinks each profile's `.env` to the shared `~/.hermes/.env`. This is fine for most setups, but when running multiple Discord bots (each needing its own `DISCORD_BOT_TOKEN`), the symlink means all profiles share the same token — all bots would respond as the same Discord user.

**Fix for multi-bot Discord:** Break the symlink and give each profile its own `.env`:

```bash
# 1. Copy the shared .env as a base, then remove the symlink
cp ~/.hermes/.env ~/.hermes/profiles/<name>/.env.bak
rm ~/.hermes/profiles/<name>/.env
cp ~/.hermes/profiles/<name>/.env.bak ~/.hermes/profiles/<name>/.env
rm ~/.hermes/profiles/<name>/.env.bak

# 2. Write the unique Discord token using Python (sed doesn't work on symlinks,
#    and tokens are masked at read time by Hermes' credential layer):
python3 -c "
import re
path = '~/.hermes/profiles/<name>/.env'
with open(path, 'r') as f:
    c = f.read()
c = re.sub(r'^DISCORD_BOT_TOKEN=.*', 'DISCORD_BOT_TOKEN=<unique token here>', c, flags=re.MULTILINE)
with open(path, 'w') as f:
    f.write(c)
print('done')
"
```

**Important:** Replace `<unique token here>` with the actual token BEFORE running the script. Tokens are masked (`***`) in all terminal/file read output by Hermes' credential layer — you cannot verify them by grepping the .env file. The only reliable verification is checking the gateway log for a successful `Connected as <botname>` message after restart.

**Terse version for multiple profiles at once** (write the script to a temp file and run):

```python
tokens = {
    'coder':    'DISCORD_BOT_TOKEN=<coder token>',
    'architect': 'DISCORD_BOT_TOKEN=<architect token>',
    'foreman':  'DISCORD_BOT_TOKEN=<foreman token>',
}
import re
for profile, line in tokens.items():
    path = f'~/.hermes/profiles/{profile}/.env'
    path = os.path.expanduser(path)
    with open(path, 'r') as f:
        content = f.read()
    content = re.sub(r'^DISCORD_BOT_TOKEN=.*', line, content, flags=re.MULTILINE)
    with open(path, 'w') as f:
        f.write(content)
```

**CRITICAL: Each token must come from a SEPARATE Discord bot application** in the Developer Portal. One application = one token = one bot identity. Sharing tokens means multiple profiles respond as the same bot.

**CRITICAL: `DISCORD_ALLOWED_USERS` must also be unique per profile** — set it to the human user's Discord ID so the bot only responds to you.

Each Discord bot application in the Developer Portal gets its own token. One token per profile. Never share tokens across profiles.

**When to symlink vs. separate:**
- Single bot or non-Discord setups → symlink `.env` is fine (default)
- Multi-bot Discord → separate `.env` per profile with unique `DISCORD_BOT_TOKEN`

**Pitfall: found an issue? Report it, don't auto-fix.** When auditing existing profiles, if you find a mismatch between the fleet skill and actual config (wrong model, missing plugin, etc.), **present the finding first and let the user decide**. This user prefers to approve changes before they're applied — especially model swaps and config modifications. The only exception is plugin additions that were explicitly requested.

## SOUL.md Discord Section Pattern

Each bot's SOUL.md should include a DISCORD section for channel-aware behavior:

```
DISCORD: Channel=<channel-name>. <role description>. <behavioral notes>. Create threads for deep dives. Save durable output to <destination>.
```

Keep SOUL.md compressed — remove redundant prose, use abbreviations. The DISCORD section is the only Discord-specific addition needed. See `references/discord-multi-bot-setup.md` for full channel structure and token writing techniques.

## Skill Sharing Across Profiles (3 Approaches)

When multiple profiles need the same skills, three approaches exist. Pick based on how many profiles need what:

### Option A: `skills.category` (auto-discovery)
Skills in `skills/<category>/` are auto-discovered by profiles with `skills.category: <category>`. Zero config per skill, but only works when all skills under that category belong to that profile.

```yaml
skills:
  category: software-development   # auto-loads everything in skills/software-development/
```

Best for: profile-specific skills that live in that profile's own `skills/` dir.

### Option B: `skills.paths` (explicit per-skill)
Each profile's config lists exact skill paths via relative `../../skills/...` references. Selective — only loads what you list.

```yaml
skills:
  category: software-development
  paths:
    - ../../skills/software-development/token-compression
    - ../../skills/software-development/look-before-edit
    - ../../skills/software-development/karpathy-coding-discipline
```

Best for: shared skills that multiple profiles need without loading everything in the category. This is the approach for cross-profile skill sharing when you want precision.

### Option C: `external_dirs` (bulk)
Loads ALL skills from a directory, regardless of category. Simple but wasteful — pulls in 800+ skills on a mature install.

```yaml
skills:
  external_dirs:
    - ~/.hermes/skills
```

Best for: the primary/chat profile (senna) that needs broad access. NOT for specialized worker profiles.

### Combining approaches
A profile can use `category` + `paths` together. The `category` loads profile-specific skills, `paths` adds shared skills from outside the profile's directory tree. Example from the windowshermes fleet:

```yaml
skills:
  category: unreal-engine    # loads profile's own UE skills
  paths:
    - ../../skills/software-development/token-compression   # shared across all profiles
    - ../../skills/software-development/systematic-debugging
```

### Repo layout for shared skills
```
windowshermes/
├── skills/                          # Shared — referenced by multiple profiles via paths
│   └── software-development/
│       ├── token-compression/
│       ├── look-before-edit/
│       └── systematic-debugging/
├── profiles/
│   ├── ue5-coder/
│   │   └── skills/                  # Profile-specific (auto-discovered via category)
│   │       └── unreal-engine/
│   └── arch/
│       └── skills/                  # Profile-specific
│           ├── software-development/
│           └── creative/
```

**Pitfall: `~` resolves to the profile's remapped home, not the filesystem path.** When the senna profile runs `~/.hermes/...`, it resolves to `~/.hermes/profiles/senna/home/.hermes/...` (the profile's isolated home). Skills are actually at `~/.hermes/profiles/senna/skills/` (the real filesystem path). Use `skill_view()` to find the actual path before copying skills between profiles.

## Cross-Machine Profile Sync (Git Repo Pattern)

When you need the same Hermes profiles on multiple machines (e.g., Mac for daily work + Windows PC for game dev), store profiles in a private GitHub repo instead of manually copying files.

### Repo structure
```
windowshermes/                  (or whatever you name it)
├── profiles/
│   ├── ue5-coder/
│   │   ├── SOUL.md             ← compressed DSL persona
│   │   ├── AGENTS.md           ← domain conventions
│   │   └── config.yaml         ← model/provider/inference settings
│   ├── threejs-coder/
│   ├── blender-coder/
│   └── designer/
├── knowledge/                  ← wiki snapshots for offline reference
│   ├── ue5/                    ← concept pages from LLM-Wiki
│   ├── threejs/
│   ├── blender/
│   └── design/
├── install.sh                  ← one-command setup script
└── README.md
```

### Install script pattern
The install script should:
1. Check prerequisites (`hermes` CLI, `ollama`)
2. Copy SOUL.md, AGENTS.md, config.yaml to `~/.hermes/profiles/<name>/`
3. Copy skills if bundled in the repo
4. Optionally pull the recommended model via `ollama pull`
5. Support installing all profiles or a subset: `./install.sh ue5-coder`

### Knowledge snapshots
Store wiki pages in the repo for offline reference. These are NOT loaded by the agent at runtime (skills handle that) — they're for the human to read and for the agent to reference when asked. Sync by pushing from the authoring machine and pulling on the target.

Also include `docs/` for setup guides specific to the deployment (e.g., fork build instructions, model download guides, troubleshooting). These are consumed by the human, not the agent.

### Config for local models
When profiles use a local llama.cpp fork (e.g., AtomicBot TurboQuant), the config.yaml should specify:
```yaml
backend: llamacpp
llamacpp:
  base_url: http://127.0.0.1:8080/v1
  model_dir: ~/models/gguf
  model_file: Qwen3.6-35B-A3B-UDT-Q4_K_XL_MTP.gguf
  server_binary: ~/atomic-llama-cpp-turboquant/build/bin/llama-server
  num_gpu_layers: 99
  context_size: 32768
  flash_attention: true
  cache_type_k: turbo3
  cache_type_v: turbo3
  spec_type: nextn
  draft_max: 2
  draft_min: 1
  port: 8080
```

For Ollama (simpler setup):
```yaml
backend: ollama
ollama:
  base_url: http://127.0.0.1:11434/v1
  model: hf.co/unsloth/Qwen3.6-35B-A3B-GGUF:UD-IQ2_XXS
```

**Multi-profile local LLM:** Use different ports for different models (e.g., ue5-coder on 8080, arch on 8081). Only one model can be loaded at a time on 12 GB VRAM — swap between them or run on separate ports if RAM allows.

### Secrets management in private repos
When the repo is private, use `.env.example` + `.gitignore` for API keys:
```
repo/
├── .env.example    ← committed, placeholder values
├── .gitignore      ← blocks .env from git
└── .env            ← local only, real keys
```
Each machine creates its own `.env` from the template. Safe to create dedicated API keys per machine.

### Sync workflow
```
Mac (authoritative) ──git push──→ GitHub private repo
                                        │
Windows PC ──git pull──←────────────────┘
```

After pulling, run `./install.sh` to copy updated profiles to `~/.hermes/profiles/`.

**Shared skills via `skills.paths`:** Instead of copying shared skills into each profile's `skills/` dir (wastes disk, drifts on update), store them once in `skills/software-development/` and reference via relative paths in each profile's config.yaml. This way `git pull` updates all profiles' shared skills in one shot. See "Skill Sharing Across Profiles" section above for the three approaches.

**Pitfall: profiles in repo are copies, not symlinks.** Edits on the target machine don't sync back. Always edit on the authoring machine and push. If you need bidirectional sync, use the repo as the source of truth on both sides.

**2026-06-04: Created `<your-github-username>/windowshermes` repo with 4 domain profiles (ue5-coder, threejs-coder, blender-coder, designer), 28 knowledge pages, and install script. Reference projects: ActionRoguelike (Tom Looman UE5 C++ reference) and ALIS (plugin architecture template) forked under same account.**

**2026-06-08: Added `arch` profile (system design & reasoning specialist). Updated all profiles to use AtomicBot TurboQuant fork + AtomicChat UDT GGUFs. Added docs/ with full setup guides. Repo now has 5 profiles, dual-backend support (Ollama or AtomicBot llama.cpp), and model-specific scripts for building, starting, and downloading GGUFs.**

**2026-06-08: Added `worldbuilder` (lore/characters/narrative, temp 0.85) and `abilities` (combat/GAS design, temp 0.7) profiles. Both share the same backend as ue5-coder (AtomicChat UDT on port 8080) — one model server, three personas. Added Obsidian vault with 20 Eldrath lore pages (7 kingdoms, 7 characters, Aether/Echoes/Tower systems). Vault is the shared brain that all game dev profiles reference. Non-coding profiles use different PersRubric calibration: worldbuilder has high O2E (90) for creativity, abilities has high C:Ord (85) for precision. See domain-coder-profiles.md for full calibration.

## Multi-Bot Fleet Quick Reference

Current fleet (8 bots with Discord gateways, as of May 27, 2026):

| Profile | Channel | Gateway | Role | auto_thread |
|---------|---------|---------|------|-------------|
| senna | #your-orchestrator-channel | ✅ launchd | Coordinator, front door | true |
| architect | #architecture | ✅ launchd | System design | true |
| coder | #engineering | ✅ launchd | Code implementation | true |
| designer | #design-studio | ✅ launchd | Master UI & Graphics | **false** |
| foreman | #operations | ✅ launchd | Mission orchestration | true |
| oracle | #market-intel | ✅ launchd | Market intel & trading | true |
| researcher | #research-lab | ✅ launchd | Investigation & deep dives | true |
| secretary | #writing-desk | ✅ launchd | Knowledge keeper, docs, wiki | true |

**Designer exception**: Uses `auto_thread: false` — replies directly in-channel for quick visual iteration without thread overhead. All other bots use `auto_thread: true` + `thread_require_mention: true`.

Non-Discord profiles (for Kanban dispatch):
| Profile | Role | Model |
|---------|------|-------|
| data-analyst | Data science, experiments | (configured) |
| debugger | Bug isolation, root cause | (configured) |
| devops | Infrastructure, pipelines | (configured) |
| reviewer | Quality gate, code review | (configured) |
| security | Security audit, vuln scanning | (configured) |

Server ID: <id>. Channel IDs in `references/discord-multi-bot-setup.md`.

**Deleted profiles (2026-05-27):** council, explorer, librarian — generic boilerplate with no custom SOUL.md, no Discord bots, no unique purpose. Removed to reduce clutter.