> ## Documentation Index
> Fetch the complete documentation index at: https://docs-stg.outerlayer.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Key concepts
> The words every other page uses, each defined once.
Everything in OuterLayer hangs off a **work item**. An issue becomes a work item when it is added to a factory's Work page. Sessions, pull requests, checks and reviews all attach to the item, not to each other.
Because checks attach to the item, a check still counts when one pull request is closed and another opens in its place.
## The five words you need first
* **Factory**: one team's Work page, repositories, keys and policy.
* **Work page**: the factory's list of work items.
* **Work item**: an issue added to the Work page. It gets a number of its own, so issue 42 might be item 7.
* **Session**: one run of a coding agent. It uploads only when you start it with `OUTERLAYER_WORK` set to the item's number.
* **Runner**: the `outerlayer runner` process that builds items unattended, on a machine you run it on. You need one only for **Build**, not for a session you start.
The tables below define every other term.
## Where work lives
| Term | What it is |
| - | - |
| Organization | Your company's account. It holds members, roles and billing, and one or more factories. |
| Factory | One team's unit of work: its Work page, repositories, keys and policy. `appId` in config files and the API is the factory's id. |
| Work page | The factory's list of work items. |
| Work item | An issue added to the Work page. It gets a number of its own on the factory: issue 42 might be item 7. Commands and `OUTERLAYER_WORK` take the item number, never the issue number. |
| Item page | One work item's page. Its tabs are **Activity**, **Criteria**, **Findings** and **Checks**, with the item's sessions and pull requests beside them. See [Review and merge](/review-the-work#the-item-page-is-the-review). |
| Control plane | One repository that supplies agent instructions and policy to the factory's other repositories. Older versions of the dashboard called it the context source. See [Share instructions across repositories](/share-instructions-across-repositories). |
## Who does the work
| Term | What it is |
| - | - |
| Session | One run of a coding agent. It uploads only when it was started with `OUTERLAYER_WORK` set to an item number. See [Work on an item locally](/launch-a-session). |
| Build | One attempt to turn an item into a pull request, either by a runner or in a session you start yourself. |
| Runner | One `outerlayer runner` process, with its own config file, runner key and name. It claims the items queued with **Build** and builds them. A runner on a machine of yours is a **self-hosted runner**. See [Run work on your machines](/run-work-on-your-machines). |
| Host | A machine that one or more runners run on. Two runners on one host, one for each factory, each need their own name. See [Several factories, one machine](/run-a-host-as-a-service#several-factories-one-machine). |
| Slot | One build a runner can run at a time. `runner.concurrency` sets how many slots a runner has. |
| Claim | The hold a runner, or a person's session, has on an item while it works on it. While it lasts, no runner starts the item. It expires unless it is renewed, so a stopped machine never holds an item for long. Error codes, flags and the CLI call it a **lease**. A session's claim lasts 20 minutes, and its hooks renew it while the session works. A runner renews its own while the build runs. |
| Item key | The key a runner's build uses in place of the runner's key. It acts only on the claimed item and stops working when the claim ends. See [Item key](/reference/build-reference#item-key). |
| Host key | A signing key the runner makes on its host, at `runner/host-key.pem` beside its config file. The first claim binds it to the runner key. The gateway then refuses that runner key from any other host. See [The host key](/run-a-host-as-a-service#the-host-key). |
| Pull request | Joins an item when a session on that item declares it. See [Open and declare the pull request](/launch-a-session#open-and-declare-the-pull-request). |
| Hook | An executable, or a `builtin:` value, that the runner runs around a build's command. The provision hook sets up where the build runs, and the cleanup hook removes it. See [Write your own hooks](/write-your-own-hooks). |
| Isolation | What separates a build from its host. The hooks decide it, and each build records it: `vm`, `container`, or `shared-user` for none. See [Choose how to run the runner](/run-work-on-your-machines#choose-how-to-run-the-runner). |
| Recipe | The devcontainer file that a repository's build image is built from. It comes from the repository that governs the build. See [Build a repository's image from its devcontainer file](/build-image-from-devcontainer). |
| Build image | The image a repository's container and microVM builds run in. The runner, or `outerlayer runner image`, builds it from the recipe. That build is an image build. |
| Runner image | The published container image that runs the runner itself, `ghcr.io/outerlayerai/runner`. See [Run the runner in a container](/run-the-runner-in-a-container). |
| Tunnel | The proxy the runner serves for one build. It is a container or microVM build's only way to the network. See [The tunnel](/container-builds#the-tunnel). |
| Destination | A private service that the runner serves to a build on a local address. The runner adds the service's secret, so the build never holds it. See [Destinations and secrets](/destinations-and-secrets). |
## How the work is judged
| Term | What it is |
| - | - |
| Policy | `.outerlayer/policy.yaml`, read from each pull request's base branch. It says which checks run and whether a failing one blocks the merge. See [Policy and validators](/policy-and-validators). |
| Validator | A file in `.outerlayer/validators/` that declares one check: its name, the sentence it shows, and what satisfies it. |
| Check | One named pass or fail on the item, such as "a code review report is attached". A check holds across every pull request the item has. The item page's **Checks** tab lists them. |
| Check item | One result inside a check, about one thing the check judged: a criterion, a file or a test. It has its own pass or fail and a reason. A failing check item fails its check. See [Check items](/policy-and-validators#check-items). |
| Evidence rows | The item's checks, one row each. They show on the item page's **Checks** tab. When **Post session summaries on pull requests** is on, they also appear in the **evidence comment** on each pull request. |
| Acceptance criteria | The list of what the item must do. The item page's **Criteria** tab shows the list recorded with [`outerlayer emit criteria`](/reference/cli-emit#outerlayer-emit-criteria). A criterion missing its declared proof flags the verdict. |
| Artifact | A file attached as proof. Its file type sets its kind: a screenshot, a video, a report, a log, a test result, or a plain file. See [Prove the work](/attach-evidence). |
| Review | A person's pass or fail on the whole item. A review is not a check. Only a person records one, on the item page or with `outerlayer work comment --pass` or `--fail`. See [Review and merge](/review-the-work). |
| Finding | A problem an agent hit in the factory while it worked, such as a flaky test or a wrong instruction. Findings never affect whether the work passes. |
## How an item moves
Every item has one status on the Work page that says whose turn it is. On the usual path it moves from top to bottom.
**With agent** shows only while an agent holds the item. After you request changes, the item reads **Queued** until an agent takes the work.
An open item whose issue closes with nothing merged reads **Closed, not shipped**.
[Statuses](/review-the-work#statuses) says what each status means and what the line under the title adds.
**An item arrives** in one way only. Add an issue from the Work page with **Add work**, or from a terminal with `outerlayer work build --issue 42`. Either way the item gets a number. **Build**, or `work build` alone, queues the item for a runner. **Build locally**, or `work build --local`, leaves it for you to build yourself, and no runner takes it.
**An item is withdrawn** with `outerlayer work remove`, which withdraws your request for it. The item leaves the Work page once no request for it remains, and its history is kept.
**An item ships** when its pull requests merge. Once its checks are green and every declared proof is present, a person can approve it and merge its pull requests from the item's page. Merging on GitHub also ships the item. A merge made while the verdict still blocks marks it *Done, unverified*.
A shipped item keeps its cost and duration. A session's page shows what that session cost. The factory's **Metrics** page totals cost per item, time to complete and throughput.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.