# Glossary

> Plain definitions for Fermix-specific terms and the technical concepts behind them.

This page defines terms used throughout the Fermix documentation. Entries are grouped loosely by theme and link to the relevant reference pages where appropriate.

## Runtime and platform

| Term | Definition |
|------|------------|
| **BEAM** | The Erlang virtual machine that executes Elixir code. Fermix runs as a single BEAM instance; all subsystems (agent, channels, web, memory) share one process space with no HTTP bridges between them. |
| **OTP** | Open Telecom Platform. The Erlang/Elixir library of supervisor trees, GenServers, and fault-isolation primitives. Fermix leans on OTP for process supervision, crash recovery, and scheduled work. See [supervision](/docs/supervision). |
| **Umbrella** | An Elixir project structure that groups multiple applications under one build root. Fermix is organized as an umbrella with five runtime apps: `fermix_core`, `fermix_channels`, `fermix_web`, `fermix_nif`, and `fermix_opik`. |
| **FERMIX_HOME** | The root directory for all Fermix state: `config.toml`, bootstrap files, skills, traces, logs, and the memory database. Defaults to `~/.fermix`; override with the `FERMIX_HOME` environment variable. |

## Agent and loop

| Term | Definition |
|------|------------|
| **MainAgent** | The persistent top-level agent process (`FermixCore.Agents.MainAgent`). It holds runtime-context cache state, composes the prompt, reads conversation history, fetches tools, and delegates each turn to `AgentLoop`. There is exactly one `MainAgent` per running daemon. |
| **AgentLoop** | The bounded LLM/tool iteration (`FermixCore.AgentLoop`). It calls the configured provider, parses tool calls, executes them through the capability registry, appends results, and continues until the provider returns a final response or the iteration cap is reached (default 100 for interactive turns; a system-side setting, not a `config.toml` key). See [the agent loop](/docs/the-agent-loop). |
| **Conversation key** | The three-tuple `{channel, chat_id, thread_scope}` that uniquely identifies one logical conversation. Used for per-conversation history, single-flight scheduling, and compaction state. |
| **Single-flight** | The guarantee that at most one agent turn runs per conversation key at a time. Newer same-conversation messages are appended to a FIFO pending queue and run in arrival order after the active turn completes; a new message does not cancel the in-flight turn. (Only `/stop` cancels a running turn.) |
| **Ultra mode** | A run-mode of the normal turn triggered by the `/ultra` channel command. It tags the turn `run_profile: :ultra`, which unlocks wider subagent caps (up to ~50 narrow probes, up to 12 concurrent) and activates an exhaustive-mode prompt addendum. It is not a separate orchestrator; workers nest under the parent trace like regular subagents. |

## Capabilities and tools

| Term | Definition |
|------|------------|
| **Capability** | A single registered entry in `CapabilityRegistry`. Every capability has a `name`, `description`, JSON Schema `parameters`, a `kind`, a `policy_class`, and an executor. "Capability" and "tool" are used interchangeably in agent-facing language. See [capabilities and tools](/docs/capabilities-and-tools). |
| **Capability kind** | The origin of a capability. `:builtin` means a pure Elixir tool shipped with Fermix; `:skill` means a SKILL.md-defined sub-agent; `:mcp` means a tool discovered from an outbound MCP server. |
| **Tool** | Synonym for a built-in capability from the model's perspective. Skills and MCP tools also appear as tools in the provider's tool list. |
| **Plugin** | An integration that owns a surface (an API or a vault) and registers its own tools. The Gmail, Google Calendar, and Google Drive plugins are bundled and always present; additional plugins install from a signed catalog bundled in the binary, verified with sha256 + `cosign` before activation. |
| **Plugin rail** | How an installable plugin runs: `http` (declarative request templates executed in-VM, https-only behind an SSRF floor) or `mcp` (a supervised local process whose discovered tools register as `<plugin>_<tool>`). |
| **Skill** | A filesystem-backed sub-agent defined by a `SKILL.md` file. Skills live under `priv/skills`, `~/.fermix/skills`, or plugin roots. Each skill carries its own instructions and tool boundary. Trust is derived from location: bundled and local skills run with operator trust; plugin-loaded skills run with guest trust. See [skills](/docs/skills). |
| **MCP** | Model Context Protocol. Fermix can act as both an MCP server (exposing its tools to external clients) and an MCP client (consuming tools from outbound MCP servers). Discovered MCP tools are registered as `:mcp` capabilities. See [MCP](/docs/mcp). |
| **Policy class** | The trust-based classification of a capability: `:read_only`, `:read_write`, `:exec`, `:network`, `:external_api`, or `:gui_control`. The last covers desktop **computer use** and is operator-only (never delegated to sub-agents). The capability filter uses policy class to restrict what a caller may invoke — a guest-trust caller is limited to `:read_only`. |
| **Computer use** | An experimental capability, off by default, that lets the agent control the host desktop directly — taking a screenshot to see, then driving the mouse and keyboard one action per call. It carries the `:gui_control` policy class, is operator-only, and is never delegated to sub-agents. Enabling it installs a separate native helper (a checksum-verified download) from the setup page and flips a feature flag; what it is allowed to do is derived from the sandbox mode. See [capabilities and tools](/docs/capabilities-and-tools). |
| **Hidden capability** | A capability registered with `hidden_from_agent?: true`. It is excluded from the tool list sent to the model but remains callable from internal code paths. |
| **Deferred tool** | A plugin or MCP tool whose full JSON Schema is kept off the provider wire by default (tool-schema deferral, on by default). The model discovers and invokes deferred tools on demand through `tool_search` (search the catalog), `tool_describe` (fetch one tool's schema), and `tool_call` (invoke by name). Built-in tools stay inline. |

## Channels and ingress

| Term | Definition |
|------|------------|
| **Channel** | A messaging integration through which users reach the agent: Telegram, WhatsApp, Slack, Discord, Signal, or the local CLI. All channels normalize inbound messages and dispatch through `MainAgent`. See [channels](/docs/channels). |
| **Ingress** | The trust-resolution and authorization layer (`FermixChannels.Gateway.Authorizer`) that runs before a message reaches the agent. It maps an inbound sender to operator or guest trust, or denies the request. See [ingress and trust](/docs/ingress-and-trust). |
| **Gateway** | The shared entry point (`FermixChannels.Gateway.ingest/2`) that normalizes messages, runs ingress authorization, dispatches slash commands, and hands turns to the per-conversation queue (processed in arrival order, first in first out). |
| **Transcription backend** | The speech-to-text engine that converts inbound voice notes and audio attachments to text before the turn reaches the agent, selected by `backend` under `[fermix_core.transcription]`: `openai` (default, `gpt-4o-mini-transcribe`), `xai`, or `deepgram`. Each backend has its own API key slot. An audio attachment is transcribed whenever the channel can fetch it; if the message also carries a caption, the caption and the transcript are both delivered. See [channels](/docs/channels). |
| **Operator** | The human owner of a Fermix installation. The operator always resolves to full (`:operator`) trust, whether arriving via CLI, channel `owner_user_id`, scheduled job, or voice companion. |
| **Source trust** | The trust level (`operator` or `guest`) resolved by the ingress layer and carried through the turn into `AgentLoop`'s capability filter. |

## Sandbox

| Term | Definition |
|------|------------|
| **Sandbox** | The boundary that enforces filesystem access, command execution, and environment variable passthrough for agent tool calls. Configured by a mode and a command profile. See [sandbox](/docs/sandbox). |
| **Mode** | The sandbox setting controlling which filesystem subtrees are accessible: `strict` (the workspace only), `standard` (the workspace, plus the directory the daemon was launched from, plus the directory an owner's turn was started from — the latter two only when they sit strictly inside `$HOME`), or `open` (all of `$HOME`). Operator-granted roots are added on top of whichever mode is set. |
| **Command profile** | The sandbox setting controlling which preset OS commands are wired as capabilities: `bare`, `assistant`, or `extended`. |
| **Effective roots** | The set of filesystem subtrees the sandbox permits for a turn: the mode's roots plus any operator-granted roots, canonicalized (symlinks resolved) and with `blocked_roots` and protected paths removed. `fermix sandbox explain` lists each effective root and marks whether it came from the mode or from an explicit grant. |
| **Protected path** | A filesystem location the sandbox refuses to read or write regardless of mode, including system roots, `~/.ssh`, and Fermix's own `auth.json`. |
| **Grant** | An extra filesystem root the operator has explicitly allowed (`[sandbox] allowed_roots`). Grants are added on top of whatever the mode allows, in every mode, but never override a protected path. Add one with `fermix grant path PATH` or the owner-only `/grant path PATH`. |
| **Confirmation token** | The single-use, 60-second token Fermix returns when a sandbox change proposed from a chat channel would widen the surface — a looser mode, a new grant, a new command preset, or a new environment passthrough. The owner approves with `/confirm TOKEN` from the same channel, chat, and sender that proposed it. (The CLI commands apply directly and need no token.) When the agent hits a denied directory during an attended operator turn it can ask for access itself (`request_directory_access`), showing the canonical path, its reason, and the config diff; on confirmation the grant is saved and the original request resumes. On Telegram and Discord that prompt also carries a one-tap **Approve** button; it sends the identical confirmation and rides the same single-use, time-limited, origin-bound, owner-only path. Every other surface shows the same prompt as text. In a shared chat on a button channel the code itself is deliberately withheld — approve from the button, a direct message, or the CLI. |
| **Hardline** | The sandbox's first-pass shell-command classifier. It refuses obviously dangerous commands (`rm -rf /`, `shutdown`, and similar) regardless of mode or operator grants. |
| **Guest trust** | The restricted capability surface granted to non-owner channel senders and plugin-loaded skills. Guest callers may only invoke `:read_only` policy-class capabilities. |

## Memory, prompt, and compaction

| Term | Definition |
|------|------------|
| **Bootstrap files** | Operator-owned files under `~/.fermix/bootstrap/<agent_id>/` that are prepended to every prompt as system context. `fermix setup` seeds default bootstrap files on first run. See [prompt and compaction](/docs/prompt-and-compaction). |
| **Prompt memory** | Facts and summaries promoted from conversation history into persistent memory and reflected into the agent's prompt on each turn. Stored durably in SQLite; the prompt-memory files (`USER.md`, `MEMORY.md`) are derived artifacts. |
| **Compaction** | The process of summarizing older messages in a conversation and replacing them with that summary to stay within the model's context window. Auto-triggered when token usage crosses the configured threshold (default 0.85 of the context window). See [prompt and compaction](/docs/prompt-and-compaction). |
| **Soul / SOUL.md** | The agent's persona file (`SOUL.md`, a bootstrap file). Owner-curated through the `/soul` command family, which drafts a bounded persona edit and applies it only after an explicit confirmation; every change is versioned in the Resource registry and revertable. |
| **Resource** | A versioned, hash-tracked artifact managed by `FermixCore.Resource.Registry`. Covers prompt bootstrap files and memory files. Supports diff and rollback for file-backed resources. See [resource versioning](/docs/resource-versioning). |

## Providers and routing

| Term | Definition |
|------|------------|
| **Provider** | A configured LLM backend. Fermix supports OpenAI (API key), `openai_codex` (Codex OAuth), Anthropic (API key or subscription OAuth), xAI (API key or Grok OAuth), OpenRouter, Mistral (API key), and a keyless local Ollama. See [providers and models](/docs/providers-and-models). |
| **Primary provider** | The provider marked `primary = true` in its `[fermix_core.providers.<name>]` block. Exactly one provider is primary, and it handles every turn unless it fails. Setup marks a newly configured provider primary by default; the web setup provider page can flip the primary flag without re-entering credentials (takes effect after a daemon restart). |
| **Fallback chain** | Every configured provider other than the primary, tried automatically when the primary fails, in deterministic catalog order (`openai_codex`, `openai`, `anthropic`, `xai`, `openrouter`, `mistral`, `ollama`). Sub-agents and scheduled jobs can instead be pinned to a specific provider and model. |
| **Adapter** | The provider-specific module that implements the `chat/3` and `continue/3` callbacks. Stateless; provider-specific transcript shape is kept in `provider_state`. |
| **Reasoning effort** | A provider-side hint controlling how much the model deliberates before responding. The canonical vocabulary is `none`, `low`, `medium`, `high`, `xhigh`, and `max`, with per-provider subsets. OpenRouter, Mistral, and Ollama do not accept a reasoning effort field. |
| **Route key** | The dispatch tuple `%{provider, model, auth_mode, base_url}` used to resolve which adapter and options to use for a given turn. |

## Scheduled jobs

| Term | Definition |
|------|------------|
| **Scheduled job** | A durable, cron-scheduled agent task. Each run is isolated, bounded by the iteration cap, stored with a result trace, and delivered through the configured channel layer. Jobs can carry an optional `expires_at` timestamp. See [scheduled jobs](/docs/scheduled-jobs). |

## Observability

| Term | Definition |
|------|------------|
| **Trace** | A structured JSONL record of a single agent turn, tool execution, or provider call. Written to `FERMIX_HOME/traces/YYYY-MM-DD/<type>.jsonl` by `FermixCore.Trace`. See [traces and telemetry](/docs/traces-and-telemetry). |
| **Telemetry** | `:telemetry` events emitted by every Fermix component at boundaries where work enters, leaves, blocks, or fails. The telemetry handler bridges these events into durable trace files and optionally into external observability backends. |