# Glossary

**This page defines every term hlix uses in a load-bearing way, and links each one to the page that owns it.** If a word in these docs is doing more work than its everyday meaning, it is here.

Start with the four confusable pairs — they cause more misreadings than the rest of the vocabulary combined.

## The four pairs people get wrong
**Workspace is not the Coding Workspace:** **Workspace** is your tenant — the organization your team and your projects live in. It is what `--workspace` selects and what `X-Organization-Id` names.

**Coding Workspace** is one project's execution environment: a persistent sandbox with a filesystem and a shell, where agents actually run code.

One workspace contains many projects. Each project has exactly one Coding Workspace. They are different objects at different levels, and the only thing they share is a word.

| These look alike | …but | And this one |
| --- | --- | --- |
| **Workspace** — your tenant/organization | ≠ | **Coding Workspace** — one project's sandbox |
| **Revision** — an immutable snapshot's identity | ≠ | **Generation** — its monotonic counter |
| **Worker persona** — how work is *assigned* | ≠ | **Execution lane** — what run history *reports* |
| **Harness** — the coder binary that edits files | ≠ | **Agent role** — the orchestration job an LLM does |

## The work tree

**Workspace** · Your tenant. Better-auth calls it an organization, the API header calls it `X-Organization-Id`, the CLI calls it `--workspace`, and the product calls it a Workspace. One entity, named by layer — `workspaceId` and `organizationId` are the same value. → [Work tree](/concepts/work-tree/)

**Project** · One codebase under hlix's control. Owns a Coding Workspace, zero or more repositories, a roadmap, a budget, and its own revision history. → [Work tree](/concepts/work-tree/)

**Cycle** · A multi-task unit of work with its own conversation — the level a roadmap is planned into, and the level that executes. → [Cycles](/running/cycles/)

**Task** · The atomic unit of execution: one worker agent, one git worktree, one branch, one outcome. → [Tasks](/running/tasks/)

**Wave** · The set of tasks a cycle dispatches in parallel. Outcomes are collected per task, so one failing task does not cancel its siblings. → [Cycles](/running/cycles/)

**Roadmap** · The project-level plan the orchestrator produces from your brief, and re-plans after each cycle outcome. → [Agents & orchestration](/concepts/agents/)

**Triage** · The stage every cycle is created at, and the decision made there: forward it to planning, or cancel it. Judged by the Triage Agent from the request's content, never skipped by any intake path. → [Triage](/concepts/triage/)

**Lane** · The risk classification a cycle is routed into, derived by versioned platform rules from how well understood and how risky the change is — never named by the model. Four of the nine lanes force a human approval before dispatch on their own. → [Triage](/concepts/triage/)

**Priority** · The integer a cycle carries, derived from the urgency tier Triage judged: `300` urgent, `200` high, `100` normal, `0` low. Ready cycles dispatch highest first, and `orderBy=priority` lists them the same way. Not a named level, and not something the planner can change. → [Triage](/concepts/triage/)

**Stage history** · The record of every status move a cycle made — from, to, when, who decided (`human`, `agent`, or `rule`), under which rules version, and why. It is what the delivery metrics are computed from, and the reason a stage change is always attributable. → [Cycles](/running/cycles/#stage-history)

## Who does the work

**Orchestrator** · The project-level agent that turns a brief into a roadmap, dispatches cycles, and decides what happens after each outcome. One per project — there is no master orchestrator above them, and no path by which the work it creates skips Triage. → [Agents & orchestration](/concepts/agents/)

**Triage Agent** · The one-shot, tool-less agent that judges an incoming request's complexity, risk and urgency and decides whether it becomes a cycle. Not part of a project's team; its model is configured separately. → [Triage](/concepts/triage/)

**Worker agent** · An agent that executes one task. Which persona it takes decides how the work is framed. → [Agents & orchestration](/concepts/agents/)

**Worker persona** · The role a task is assigned under — the six named identities defined in the DNA layer. Personas route work; they are not what run history reports back. → [Agents & orchestration](/concepts/agents/)

**Execution lane** · What a run actually records: `planner`, `builder`, `tester`, or `reviewer`. Several personas share one lane, so a Senior Engineer's run and a UI Engineer's run both appear as `builder`. → [Agents & orchestration](/concepts/agents/)

**Harness** (also **coding agent**) · The program that edits your code inside a task — `hlix`, our own, or an external coder you already use: `claude-code`, `codex`, `cursor-agent`. Chosen per task by a six-rung cascade whose bottom rung is `hlix`. → [Connect your agents](/guides/connect-agents/)

**Hlix** (the harness) · hlix's own coding agent, driven from the backend rather than launched inside the sandbox. The default when a task names no other harness, and the only one whose reasoning streams live and whose turn appears in a cycle's Transcript. → [Connect your agents](/guides/connect-agents/)

**Agent role** · An orchestration job an LLM performs — `classifier`, `interviewer`, `planner`, `reviewer`, `chat`, `orchestrator`, `worker`, `triage`. Each maps to a model you can override. Unrelated to which harness runs. → [Connect your agents](/guides/connect-agents/)

**ACP driver** · The in-sandbox process that launches an external coder and reports its result. Every harness except `hlix` runs through it. → [Connect your agents](/guides/connect-agents/)

## Execution and isolation

**Coding Workspace** · One project's persistent execution environment — a sandbox with a filesystem and a shell, durable across the project's whole life. Idle sandboxes stop themselves; the filesystem survives, and the next task resumes it. → [The Coding Workspace](/concepts/coding-workspace/)

**Worktree** · A git working tree checked out from the project's shared clone, one per task, so concurrent tasks never share a checkout. → [The Coding Workspace](/concepts/coding-workspace/)

**Task branch** · The branch a task commits to, created off the base branch inside its worktree. Repository-backed projects push it; repo-less projects merge it locally. → [GitHub](/integrations/github/)

**Repo-less project** · A project with no Git remote. Task branches are merged inside the Coding Workspace and the result is snapshotted and downloadable — no GitHub required. → [The Coding Workspace](/concepts/coding-workspace/)

**Merge lock** · The mutex serializing merges into a project's default branch, held per repository so two repositories in one project do not queue behind each other. → [The Coding Workspace](/concepts/coding-workspace/)

## Files, snapshots, and sync

**Revision** · One immutable snapshot of a project's files, identified by a revision ID. Never edited — a change creates a new one. → [Push, pull & sync](/cli/sync/)

**Generation** · The monotonically increasing counter on a revision. `push` is a compare-and-swap against the expected revision ID *and* generation, which is what makes a lost race a `conflict` rather than a silent overwrite. → [Push, pull & sync](/cli/sync/)

**Manifest** · The hashed inventory of a snapshot: every file's path, size, and SHA-256. Comparing manifests is how local-versus-cloud drift is computed without transferring anything. → [Import a project](/cli/import/)

**Bundle** · The Git bundle carrying the snapshot's files and history. Hashed before upload and verified after. → [Import a project](/cli/import/)

**Snapshot commit** · The synthetic commit an import creates in a temporary clone so dirty and untracked files can be captured without touching your repository. → [Import a project](/cli/import/)

**Protected file** · A recognized credential-bearing file — dotenv, `.netrc`, cloud credentials, `.npmrc`. Excluded from Git and moved through encrypted storage instead. → [Secrets & protected files](/security/secrets/)

**Quarantined resource** · An agent brief, skill, or MCP configuration that import preserved encrypted but deliberately did **not** activate. Activating one is a separate, explicit command. → [Import trust model](/security/trust-model/)

**`.hlixignore`** · Project-local additions to the snapshot ignore list, in Git-ignore syntax. It cannot hide a protected file; those are found regardless. → [Initialize a project](/cli/init/)

## Context and review

**DNA** · The composed identity every hlix agent is built from — voice, principles, and standards, cascading System → Owner → Org → Project. It is why two agents on one project produce consistent work. → [Context, memory & DNA](/concepts/context-memory/)

**Memory** · Durable, scoped knowledge the workspace has learned, retrieved by semantic search inside a tenant-namespaced index. Only approved memories are composed into prompts. → [Context, memory & DNA](/concepts/context-memory/)

**Scope** · Which level a memory applies at, and the object it is attached to. → [Context, memory & DNA](/concepts/context-memory/)

**Review evidence** · The verified record behind a task's change — the diff read back from the repository host, the checks, and the provenance. It is an observation, not the agent's own summary of itself. → [Reviewing output](/running/review/)

**Revision request** · Sending a task back with unresolved comments folded into its feedback, re-entering the cycle rather than starting over. → [Reviewing output](/running/review/)

**Transcript** · The stored, post-hoc record of what each pipeline agent was told and what it answered — prompt and response, redacted. Distinct from the live streams, which do not survive a reload. Agency-only. → [The dashboard](/running/dashboard/#transcript)

**Approval gate** · The human checkpoint before a gated cycle dispatches. Off by default at the project level; a forced lane opens it regardless. → [Approvals](/running/approvals/)

**Pending request** · The durable record of a blocking question — an approval, or an agent's elicitation — that a run parks on until it is resolved. → [Approvals](/running/approvals/)

## Extensions and integrations

**Skill** · A reviewed `SKILL.md` activated for a project, giving agents a named capability. → [Import skills, agents & MCP servers](/cli/resources/)

**MCP server** · A Model Context Protocol server. **Inbound**: one you activate inside a cloud project so agents can use it ([Import skills, agents & MCP servers](/cli/resources/)). **Outbound**: the official `@hlix/mcp` server, which lets a coding agent on your machine read your workspace ([Official MCP server](/mcp/)). Opposite directions; do not confuse them.

**Environment** · A per-project bundle of variables, files, skills, and MCP servers that a Coding Workspace loads. → [Environment discovery](/cli/environment-discovery/)

**Pack** · A pre-built capability bundle baked into the sandbox image. → [The Coding Workspace](/concepts/coding-workspace/)

**Client collaborator** · An external customer invited to one project, fenced by a second authorization layer beneath the workspace boundary. Can read and comment; cannot change execution settings. → [Import trust model](/security/trust-model/)

## Release and audit

**Release ledger** · `packages/releases.json` — the single source of truth for which package versions are publicly available. Written last in a publication run, which is why the availability page can be trusted. → [Availability](/releases/availability/)
**Three terms with no owning page yet:** **Preview deployment** (a disposable deployment of a task's branch, for review before merge), **audit log** (the immutable, hash-chained record of who did what, to what, when, and with what outcome), and **trace ID** (the correlation ID joining one request's audit rows, events, runs, and logs) are all implemented in the platform but have no documentation page of their own. They are defined here so the vocabulary is complete, and this note is the honest reason there is no link.

## If a term here does not match what you see

- **Run history shows `builder` but you assigned a UI Engineer.** Expected — personas route work, lanes report it. See the two-column table above.
- **The API says `organizationId` where the UI says Workspace.** Same value. The auth and data layers keep better-auth's vocabulary deliberately; never introduce a second tenant concept.
- **A term appears in the API reference but not here.** The [generated reference](/api/reference/) describes the contract's own field names, which are not always product vocabulary.

## Next steps

[Work tree](/concepts/work-tree/)
  [Agents & orchestration](/concepts/agents/)
  [The Coding Workspace](/concepts/coding-workspace/)
  [Context, memory & DNA](/concepts/context-memory/)