--- title: Glossary description: Definitions for the Foreman terms that recur across the docs, covering trust, the pipeline, storage, and eve framework concepts. type: reference summary: One definition per term, so the rest of the docs can link instead of re-explaining. related: - /docs/trust-model - /docs/pipeline - /docs/how-it-works --- # Glossary Foreman's docs lean on a small vocabulary borrowed from the eve framework and from its own trust model. Each term is defined once here and linked from everywhere else. ## Trust and authorization | Term | Definition | | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Principal | The identity a session acts as, resolved by the framework at dispatch and available on `ctx.session.auth.current`. Real GitHub actors project as `github:`. | | Trusted | A session carrying the `trusted` auth attribute, applied by `stampTrusted`. GitHub applies it to commenters whose `author_association` is `OWNER`, `MEMBER`, or `COLLABORATOR`; Linear applies it to every Agent Session. | | Autonomous | A session running under the constructed principal `github:foreman-factory` with `principalType: "service"`, applied by `stampAutonomous`. Factory-label intake and red-CI fix runs work this way. | | Unattended | A run with no person watching it. In practice this means an autonomous run, so the two terms describe the same sessions from different angles: one names the identity, the other names the situation. | | Attended | A run with a person present who can answer a question or approve a card. Mentions, Linear Agent Sessions, and the dev TUI are attended. | | Parks | The run pauses on an approval card and waits for a person to decide. The tool call is held, not executed. | | Denied | The call is refused server-side and the run continues, reporting what it could not do. Unattended runs are denied rather than parked, because nobody is there to clear a card. | | Not-applicable | The policy's way of saying no gate applies, so the call runs. | | Intake issue | The issue or pull request number stamped into session auth at dispatch on an unattended run. `commentPolicy` reads it to scope comment writes to that one thread. | | Draft PR ceiling | The highest-impact action an unattended run can take. A draft pull request cannot merge, so shipping stays a human decision. | ## The pipeline | Term | Definition | | ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Station | One of the four subagents every work item passes through in order: Classifier, Analyst, Implementer, Reviewer. Each is a declared eve subagent under `agent/subagents/`. | | Orchestrator | The root agent. It routes work between stations, assembles the result, and speaks to people. It never writes code or performs analysis itself. | | Task mode | The execution mode a subagent enters when it declares an `outputSchema`. The child returns structured output and cannot park, which is why no station may hold an approval-gated tool. | | `outputSchema` | The JSON Schema a station declares in its `agent.ts`. It is the contract the orchestrator reads back, and declaring it is what puts the station in task mode. | | Clarification gate | The stop signal the Classifier raises with `needs_clarification`. Attended runs ask and wait; unattended runs post the questions and stop. | | Review loop | The bounded cycle back to the Implementer when the Reviewer returns `request_changes`. Capped at 2 revision cycles. | ## Storage | Term | Definition | | ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Factory brain | A single shared Markdown document of durable facts about `FACTORY_REPO`, stored in Vercel Blob. Every run reads it; only trusted callers write it. | | User preferences | Per-person standing notes stored in Vercel Blob, keyed from the resolved principal so one person's habits never leak into another's runs. | | Reserved prefix | A Blob path prefix that only its own tools may reach, `factory-brain/` and `user-preferences/`. Guard helpers exist so a general-purpose Blob capability added later cannot become a side channel. | ## eve framework concepts | Term | Definition | | ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Channel | An inbound surface that turns an external event into a session, under `agent/channels/`. Channels decide trust at dispatch. | | Extension | A prebuilt bundle of tools mounted under a namespace, under `agent/extensions/`. The filename is the namespace, so `github.ts` produces `github__*` tools. | | Connection | An MCP server the agent can call, under `agent/connections/`. Foreman connects to Linear's hosted MCP server. | | Connector | A [Vercel Connect](https://vercel.com/docs/connect) record for one third-party service, identified by a UID like `github/foreman-agent`. It mints short-lived provider tokens and forwards verified webhooks. Despite the similar name, this is not a connection: a connection is an MCP server the agent calls, a connector is how Vercel brokers auth to GitHub and Linear. | | Skill | A load-on-demand instruction package at `agent/skills//SKILL.md`. Its `description` frontmatter is the routing hint. Skills are per-agent, so stations never see the root's. | | Sandbox | The isolated `/workspace` environment every eve agent runs in. Agents get one whether or not they ask for one; adding a `sandbox.ts` customizes it. The Analyst, Implementer, and Reviewer each do, to hold a repository checkout. The other two run in an empty one. | | Default tools | eve's built-ins, available with no setup: `bash`, `read_file`, `write_file`, `glob`, `grep`, `web_fetch`, `web_search`, and `todo`. Every agent gets the ones its session can actually use. | | Revalidation key | A string that identifies a sandbox template build. Changing it rebuilds the snapshot, so the expensive clone and setup run once rather than per session. | | Brokered credential | Token injected at the sandbox firewall on egress rather than handed to the sandbox. | ## Next steps --- For a semantic overview of all documentation, see [/sitemap.md](/sitemap.md) For an index of all available documentation, see [/llms.txt](/llms.txt) For agent-facing discovery, including API and MCP surfaces, see [/agents.md](/agents.md)