Conventions
One page freezes the vocabulary. If a term isn’t here, it’s defined where it’s used.
Canonical lexicon
Castellan docs use two metaphor families — organism (biology of a harness) and field (coordination through the environment). Product name Castellan and Castle Holdings branding stay. Body copy does not lean on animal packs or feudal/military castle staff.
| Prefer | Avoid | Meaning |
|---|---|---|
| Organism / harness as living system | Static config file as the whole story | Genome + circulation + immune gate over a run |
| Genome | Opaque “config blob” without lineage | Named topology snapshot in the evolve archive (parent_genome_id) |
| Circulation / vitals | Vague “health metrics” without the CLI | Tick-level field health (castellan vitals, CirculationVitals) |
| Immune gate / quarantine | “Auto-merge whatever evolve proposes” | Reject or quarantine harmful topology mutations before seeding |
| Evolve / episode flywheel | “Retrain the model” | run → episodes → evolve → drift-check |
| Episode | Vague “session log” | One castellan run goal attempt under .castellan/episodes/ |
| Stigmergy | Agent-to-agent chat / router LLM handoffs | Coordination through deposits in the shared environment |
| Pheromone / deposits | Chat messages between agents | Decaying zone signals agents write; scheduler reads |
| Pressure (field / scheduler) | Manager model picking the next agent | Wake priority from deps + zone signals |
| Blackboard | Free-form shared scratchpad chat | Typed JSON slots plugins declare |
| Mux panes / multiplexer | Bare tmux-script farm metaphors | In-tree PTY workspaces, tabs, panes |
| Dashboard | Control tower / war room | Ratatui operator UI (castellan dashboard) |
| Agents / panes / coordination field | Herd, flock, rookery, swarm-as-animals, “coordinate the herd” | Who runs and where they deposit |
| Plain operator language | Castellan-as-officer, garrison, troops, keep/lord body metaphors | How humans drive the binary |
Command names vs prose
castellan herd and castellan swarm-demo remain CLI subcommand names (historical product surface). In prose, describe what they do — multiplexer UX, multi-pane demo — without animal metaphor. Prefer saying “mux status” / “pane status” next to the literal command:
castellan herd status # pane / mux status (subcommand name is historical)
Crate names (castellan-herdr) and hook scripts (herdr-agent-state.sh) stay as identifiers. Peer product names do not appear in operator prose — see Doc style.
Brand vs body copy
| Keep | Do not expand into body metaphor |
|---|---|
| Product name Castellan | Garrison, troops, lord of the keep |
| Logo: castle keep silhouette (theme asset) | Feudal / military narrative in guides |
| Castle Holdings (org branding) | “Coordinate the herd / flock / rookery” |
Names and paths
| Term | Value | Notes |
|---|---|---|
| Binary | castellan | Single CLI; subcommands below |
| Config file | castellan.toml | Layered — repo root, then .castellan/, then env |
| State directory | .castellan/ | Episodes, archive, proposals, skills |
| Episode logs | .castellan/episodes/ | One JSON per goal run (castellan run) |
| Topology archive | .castellan/topology_archive.json | Genome lineage for castellan evolve / --seed-archive |
| Multiplexer socket | ~/.config/castellan/castellan.sock | Default Unix socket; override with --socket or CASTELLAN_SOCKET |
| Statusline snapshot | ~/.config/castellan/statusline.json | Written by castellan dashboard; read by castellan_read_statusline |
| Telemetry DB | ~/.config/castellan/telemetry.db | castellan telemetry query target |
| MCP tools | castellan_* prefix | e.g. castellan_deposit_signal, castellan_discover_tools — see MCP tools |
| Permission Prompt | TTY ask / non-TTY fail-closed | PermissionMode::Prompt uses a host prompter; see Governance overview and CASTELLAN_PERMISSION_PROMPT |
Note: Paths above are defaults. Named multiplexer sessions (
--session) scope their own socket and persist directory — see Multiplexer overview.
Glossary
| Term | One-liner |
|---|---|
| Episode | A single castellan run goal attempt, logged as JSON under .castellan/episodes/ — field state, topology, wake stats, verdict |
| Topology | The wake graph (nodes, edges, thresholds) agents coordinate through; mutated by castellan evolve |
| Coordination field | Shared environment: blackboard + pheromone zones + pressure scheduler |
| Pressure field | Scheduler wake-priority substrate — pheromone zones + dependency signals decide when a pending task dispatches |
| Stigmergy | Coordination by depositing into the environment instead of negotiating in chat |
| Pheromone / deposit | Named zone signal with decay; agents write, scheduler and peers read within perception radius |
| Blackboard | Typed JSON slots agents read/write instead of talking to each other in natural language |
| Genome | A named topology snapshot in the evolve archive, with lineage (parent_genome_id) |
| Circulation / vitals | Per-run field health (castellan vitals) — cold zones, fever, expression |
| Immune gate | Evolve-time reject/quarantine of harmful topology candidates |
| Quorum | Multi-contributor density gate for colony phase unlock (not a router LLM) |
| Response threshold | Per-node θ for task kinds; surplus drives emergent specialization |
| Corridor / Physarum | Optional trail edges with evaporation + conductance pruning |
| MAP-Elites | Illuminated genome archive by behavior descriptor cells |
| Drift-check | castellan drift-check — validates repo guardrails and topology mutations against the verification manifest |
| RAH (Recursive Agent Harness) | Depth-bounded harness-within-harness spawn (multiplexer pane + topology binding); see castellan rah-demo and Frontier positioning |
| Mux / multiplexer | In-tree PTY server and pane tree; CLI UX includes historical castellan herd |
Page structure (Q&A order)
Prefer this order on concept and operate pages so readers get answers without hunting:
- What — one-sentence definition
- Why — the bet / what it replaces
- How — commands and mechanism
- Failure paths — symptom → cause → fix
- Next — cross-links, not a second essay
Cut redundancy: link Daily driver / Coordination model / Organism model instead of repeating them.
Command surface at a glance
castellan doctor
castellan --version
castellan --help