@outerlayer/cli 0.2.0 → 0.4.1

package/CHANGELOG.md

@@ -1,5 +1,137 @@
 # @outerlayer/cli
 
+## 0.4.1
+
+### Patch Changes
+
+- a5cda3d: `import capture` and `context emit` help list all four maintained skills, and `mcp serve` no longer suggests the hidden `--api-key` flag when it finds no API key.
+- b150a61: `emit artifact` reads a JUnit XML file bound with `--for` as test results, and a repeatable `--test "<name>[=path:line]"` selects the tests that prove the criterion and gives a location the file lacks.
+- 32850dd: When a build's command exits 0, `outerlayer runner` reads the work item's evidence verdict before it releases the claim. A build whose item still has a failing check, or a required check with no result, is released `incomplete`, with a reason naming each check, instead of `ok`. A verdict that is not passing is read again every 30 seconds for up to 5 minutes; a passing one is believed at once. The report hook's `OUTERLAYER_OUTCOME` is the outcome the release carries. Runner protocol 12.
+
+## 0.4.0
+
+### Minor Changes
+
+- 1cffcc2: `outerlayer connect` now checks that the repository is linked to the factory it chose. When it is not, `connect` saves the connection as before, prints the factory's Work page link where the setup panel links a repository, and exits 2. `init` reports its connect step as done with `linked: false` and repeats the link under "Next", and still exits 0. A factory key skips the check. `connect` also takes `--json`, which writes one document with `linked` and, when it is false, `linkUrl`.
+- ecc937a: Add `outerlayer emit criteria <file> [--item <number>]`, which records a work item's acceptance criteria as one list. The list is validated before anything is sent: an empty list, a repeated id or a reserved id is refused. The newest recorded list is what the item's Criteria tab, its count and its status read, and criteria written in an issue body are no longer read. Once an item has a list, only a person can replace it.
+- 6bde8e9: `outerlayer init` now sets up Claude Code in the repository: it installs the starter skills and a new `outerlayer` skill, writes `.outerlayer/config.json` when there is none, runs `outerlayer context emit`, and adds the OuterLayer MCP server to `.mcp.json`. It asks nothing and changes nothing you wrote. It skips this in a repository whose context comes from a control plane, and `--local` skips it too.
+- 69e695a: Adds `builtin:vm`, a third built-in runner backend. On a Linux x86_64 host where the runner's user can use `/dev/kvm`, each build runs in a Firecracker microVM made from the recipe's image. The microVM has no network device. It reaches the runner's tunnel over vsock, and it has the vCPUs, memory and disk that `runner.build` sets.
+
+  The guest kernel and helper are not published yet, and the hashes pinned in the CLI are placeholders. Until they are published, `outerlayer runner init` does not name `builtin:vm` on any host, and `outerlayer doctor` fails `builtin:vm` hooks with that reason. After the first publish, `runner init` names `builtin:vm` on a Linux x86_64 host where the user can use `/dev/kvm`. A host without usable KVM keeps `builtin:container` or `builtin:process`, unchanged. `outerlayer doctor` adds a `KVM` check, which names the group to join, and a `MicroVM memory` check, which warns when `runner.concurrency` times `runner.build.memory` is more than the host's memory.
+
+  The first microVM build downloads Firecracker, a guest kernel and a guest helper from github.com, and checks each against a sha256 pinned in the CLI.
+
+- b678856: A runner now keeps itself at the CLI version its gateway names. When it has no build in flight, it installs that version beside its current one, checks the version's tarball and provenance against this repository's release workflow, and switches to it. If the new version fails its own checks, the runner goes back to the previous version. Turn this off with `runner.autoUpdate: false`. Run `outerlayer runner install` once on an existing host to move it onto the install layout.
+
+### Patch Changes
+
+- 48352ce: The starter `build` skill now records the item's acceptance criteria at intake with `outerlayer emit criteria`. It reads an `## Acceptance criteria` section with ids, or a bullet list under an `Acceptance:` line and adds `AC-<item number>-NN` ids. A list a person already recorded is never replaced. The criteria judge reads the recorded list from the build's state file.
+- 93695bc: `init` ends by saying to commit and push `.outerlayer/` when its agent setup step left files in the repository. The factory reads the policy from the default branch, so no check runs on the repository's pull requests until it is there. The line is left out with `--local`, outside a repository, and under `--json`.
+- d7d56d3: The microVM build disk's copy step can now be supplied by the host that builds the disk. The runner still copies with GNU `cp --sparse=always` by default, so builds on Linux are unchanged.
+- e1a440f: A `builtin:vm` build runs Docker when its recipe asks for it. A recipe asks by listing the `ghcr.io/devcontainers/features/docker-in-docker` feature, at any tag or digest. The microVM then starts its own Docker daemon, and the agent user can run `docker` before the clone starts. Image pulls go through the runner's tunnel like the rest of the build's traffic. Containers the build starts have no route out. If the daemon does not answer within 60 seconds, provisioning fails and names the daemon. Its reason includes the end of the daemon's log. A recipe that does not list the feature runs no daemon. The build's recorded recipe report says whether Docker was asked for.
+
+## 0.3.0
+
+### Minor Changes
+
+- 9b8ebd0: Adds `outerlayer work open-pr --title <text> --body-file <path>`. A host build sends it to the gateway, which opens or edits the item's pull request as the factory's GitHub App. A person's own session runs `gh` under their login and declares the pull request on the item.
+
+  The runner now speaks protocol 4. A claim names the branch the build works on, and the runner checks that branch out in the provisioned workdir before the command starts. It also sets `OUTERLAYER_BRANCH` for every hook and the command. A container build gets `OUTERLAYER_BRANCH` but not the checkout, so it checks the branch out itself. The runner skips a claim the gateway refuses, such as a pull request from a fork, and logs the refusal code. A gateway from this release refuses a runner below protocol 4 with `runner_upgrade_required`, so upgrade runners to this version.
+
+- e377274: `outerlayer login` signs in to your account through the browser: it opens a page where you approve the CLI, then saves a token for your account. It chooses no organization or factory, so commands that need a factory tell you to run `outerlayer connect`. `outerlayer logout` revokes the token and removes it. A factory key, from a flag, `OUTERLAYER_API_KEY` or the config file, always wins over the login, so CI and runners keep acting as their key. Use `--no-browser` to print the link instead, `--no-input` to skip waiting on a person, and `--check` to finish a login that was still waiting.
+- 39f75bc: Adds `outerlayer connect`, which chooses the factory a repository's work goes to. It picks by itself when only one answer is possible, says what it picked and why, and saves the choice in the repository's git directory, shared by every worktree and never committed. With no terminal it exits 1 and lists the `--factory <org>/<factory>` values to pass.
+
+  `outerlayer init` now connects the repository, installs the hooks and runs `doctor`. It never signs in: with no login it skips the connect step and says to run `outerlayer login`. `init --local` is the old behavior, with no connect step and no network call. `init --json` prints one document naming the outcome of each step.
+
+  A login now takes its factory from the repository it runs in, not from `appId` in the config file. `--app-id` and `OUTERLAYER_APP_ID` still win. A factory key is unchanged. Run `outerlayer connect` once in each repository that used a login's saved factory.
+
+- 91c2778: A container build of a governed repository now starts with its control plane's context in the checkout: `AGENTS.md`, skills and validators, at the control plane's current head. The runner reads the control plane on the host with the host's own git login, and the build receives files, never a credential. A host whose git login cannot read the control plane fails the build at provision with `context_unavailable`, and `outerlayer doctor` checks this on a container host.
+
+  The runner now speaks protocol 9, because it asks the gateway which repository governs a build's repository. A gateway from this release still accepts a runner at protocol 8.
+
+- 3294997: `outerlayer doctor` now asks the gateway three questions. Does the saved credential work? Can it use the factory chosen for this repository? Is the repository linked to that factory? A login and a factory key are each checked the way a command would use them, and a factory key wins over a login. With no credential, the three checks are skipped and doctor makes no network call. The GitHub App check runs only when the credential check passes. Fix hints no longer name `--api-key`, `--root` or `npx @outerlayer/cli`.
+- 89a20a5: `outerlayer doctor` adds one check per repository connected to your factory, once `outerlayer login` has saved a factory key. It warns when the GitHub App installation has not accepted a permission builds need, naming each one and the installation's settings page, and when the default branch does not require a pull request. It reads `GET /v1/repositories/access` and changes nothing.
+- b0519e1: `outerlayer emit finding` now records a problem you hit in the factory. It takes `--category` (`context`, `flaky-test`, `tooling`, `environment`, `defect` or `other`) and drops `--subject`, `--kind`, `--severity`, `--verdict`, `--fixed` and `--source`; each removed flag is refused by name. A `context` finding names the instruction with `--rule-path` and `--rule-relation` (`wrong`, `broken` or `missing`), and quotes it with `--rule-quote` unless the relation is `missing`.
+
+  `outerlayer emit findings <file>` takes `"schemaVersion": 2` files. A `schemaVersion: 1` file is refused. The gateway refuses a `schemaVersion: 1` batch with a message to upgrade the CLI.
+
+  `outerlayer init --template default` and `outerlayer context emit` install a new maintained `reporting-findings` skill that tells agents when to record a finding.
+
+- 6bddf79: Uploads now carry the session's token counts so far, split per model, speed and input size, so the gateway can price the whole session itself. Each turn's usage also names its 5-minute cache writes and the request's speed. The gateway stores its own price and keeps the cost the CLI worked out only for a turn it has no price for.
+
+  The CLI's local cost estimate now prices a turn as unknown when the model has no rate for a token class the turn used, such as cache reads. It used to price that class at zero, so the status line showed a lower cost than the true one.
+
+- e3f8d26: The runner sends a heartbeat at the end of every poll — its CLI version, poll interval, slots in use and total, and the result of that poll's own request for work. A key without the new `hosts.ingest` permission still polls and claims normally; the heartbeat is refused, logged once, then every tenth poll while it continues, and the host stays off `GET /v1/hosts` until the key is edited to add it.
+- 9de5518: A build the runner starts now holds an item key, not the runner's own key. The claim response carries the key, and the runner passes it as `OUTERLAYER_API_KEY` to the hooks, the command, the sync step and the cleanup hook. It acts only on the claimed item, and only while the claim is live. The runner keeps its own key for renewing and releasing the claim and for heartbeats, and it runs the final sync under the item key before it releases. The runner protocol is now 2, so a gateway that predates the item key does not return one. The runner then releases the claim without starting the build and says so in its log.
+- ea3130e: `outerlayer runner image --repository <owner/name>` builds the image a repository's builds run in, from the devcontainer file on its default branch. It ignores every setting that reaches the host or widens the container's privileges, and lists each one it ignored. It adds this CLI and a pinned Claude Code to the image, reuses the image until the recipe or the tools change, and keeps the newest three. `outerlayer doctor` on a runner host now checks each fetched repository's recipe, the devcontainer CLI, and whether the pinned Claude Code version is behind. The CLI now depends on `@devcontainers/cli`.
+- 1834f72: A build's commits are now authored by the GitHub App's bot account, and credit the member who asked for the build. The claim response carries `commitAuthor` and, when the requester signed in with GitHub, `coAuthor`. The runner sets `GIT_AUTHOR_NAME`, `GIT_AUTHOR_EMAIL`, `GIT_COMMITTER_NAME` and `GIT_COMMITTER_EMAIL` for every process an attempt starts, so a host's own git identity no longer authors a commit.
+
+  For a co-author, the runner writes a hooks directory into the build's directory and points git at it through `GIT_CONFIG_COUNT`, after any entries the host already passes. Each hook runs the repository's own hook of the same name with the same arguments, input and exit status. `prepare-commit-msg` then adds one `Co-authored-by` line. A build run through an `exec` gets the bot as author and no co-author line.
+
+  The release records `environment.commitIdentity`. The runner now speaks protocol 8. A gateway that predates the field refuses a release that names it, and the runner sends the release again without it.
+
+- c2032f3: A runner whose provision and cleanup hooks are `builtin:container` now runs each build in its own hardened container: no network but loopback, no Linux capabilities, a read-only root filesystem and one volume. The build reaches public addresses only through a tunnel the runner serves, which refuses private, link-local, shared-address and the host's own addresses and records every host the build reached. The runner config gains a `build` block (`memory`, `cpus`, `pids`, `disk`, `variables`), the image's tools layer gains an unprivileged user, `gh` and `tini`, and every release now carries an `environment` object recording what the attempt ran in. The runner protocol is now 2.
+- ca1cc05: A container build no longer holds a credential that can write to its repository. The runner serves the build a local git remote and holds the repository tokens itself. It asks the gateway for a read token before it provisions anything, and for a push token on the build's first push. It renews each token within ten minutes of expiry and revokes every one when the attempt ends. The build's `gh` holds only the read token.
+
+  The runner forwards a push only when every ref it updates is the branch the claim names. On a branch outside `outerlayer/`, it forwards only creating the branch or a fast-forward. `GH_TOKEN`, `GITHUB_TOKEN`, `GH_ENTERPRISE_TOKEN` and `GITHUB_ENTERPRISE_TOKEN` in `runner.build.variables` are no longer passed into a build. The runner logs each name it skips.
+
+  A container build now needs a gateway with a GitHub App configured. Without one, every claim ends as `failed` at provision with the reason `repository_tokens_unavailable`. The release records which kinds of token the build used as `environment.credentials`.
+
+  The runner now speaks protocol 6, because the release carries `credentials` and the runner calls the token route. A gateway that has not been upgraded refuses a release that names `credentials`, so upgrade the gateway first.
+
+- 3a32b01: A build the runner provisions with `builtin:container` or `builtin:process` no longer holds the item key or Claude's credential. The runner serves two built-in destinations, `gateway` and `claude`. The build's `OUTERLAYER_URL` and `ANTHROPIC_BASE_URL` point at local addresses, and its `OUTERLAYER_API_KEY` and Claude credential variable hold placeholders. The runner sets the item key and the host's credential on each request it forwards.
+
+  The runner reads `CLAUDE_CODE_OAUTH_TOKEN`, or else `ANTHROPIC_API_KEY`, from its own environment. A host that sets neither now ends each attempt as `failed` at `provision` with the reason `agent_credential_missing`, so set one before upgrading. Remove `CLAUDE_CODE_OAUTH_TOKEN` from `runner.build.variables`: a name there now gets a placeholder. A host may list at most 18 destinations, down from 20, and may not name one `gateway` or `claude`.
+
+- e07a51f: A host's own hooks can now report how their builds are isolated, and `outerlayer runner init` names the hooks that fit the machine. A provision hook can write `isolation`, `exec`, `broker` and `recipe` to `provision.out`. It receives the build's directory, the repository, the recipe commit and the four limits. The new `builtin:process` hooks run builds as processes on machines that cannot isolate them, through the same tunnel, and record `shared-user`. `runner init` names `builtin:container` on Linux or WSL2 with Docker Engine 26 or later, and `builtin:process` elsewhere, and no longer writes hook scripts. `outerlayer doctor` says what a host's builds get. A host can list credentialed services in `runner.build.destinations`. The runner forwards a build's requests to them over HTTPS with the host's header in place of any credential the build sent, so the secret never enters the build, and the release names the destinations a build called. The runner protocol is 4.
+- ad6979c: `outerlayer runner check` now exits 1, before the host takes work, when an enabled queue's command is still the placeholder `runner init` wrote, when built-in hooks find neither `CLAUDE_CODE_OAUTH_TOKEN` nor `ANTHROPIC_API_KEY` set, and when the key lacks `work.claim`. Each message names the queue, `claude setup-token` or the permission.
+
+  On a runner host, `outerlayer doctor` lists the laptop checks as skipped with one line that says why, adds a `Claude credential` check that names the variable and never its value, and names a missing permission instead of calling the key revoked or expired. Its GitHub App hint says whether the App's own settings must add a permission or an installation owner must accept it.
+
+  A container build fetches the image recipe of a private repository with the claim's read token, so the host needs no git login. `outerlayer runner image` exits 1 with one line naming the repository when its fetch fails. `outerlayer work build` warns when the gateway says the request cannot earn repository tokens.
+
+- b2a18b7: `outerlayer runner init` no longer chooses builds without isolation for you. On a machine that cannot isolate a build, it refuses and says what isolation needs; pass `--allow-process-builds` to run builds as processes under your user instead. On a Mac with no terminal to ask, it refuses and names `--vm`. A host can now list the public hosts its builds may reach in `runner.build.allowHosts`: the tunnel refuses every other name before resolving it, and records the refusal with the range `not-allowed`.
+- 3019459: A runner key now works only from the host that first used it, and the runner signs every request it makes. The runner makes an Ed25519 host key in `~/.outerlayer/runner/host-key.pem` the first time it starts. Its first claim binds the key's public half to the runner key. After that the gateway refuses any request made with that runner key unless the host key signed it.
+
+  The runner speaks protocol 7, and a gateway from this release refuses a runner below it with `runner_upgrade_required`, so upgrade every runner. To move a runner key to a new host, a member clears its binding on the factory's API keys page, and the new host's next claim binds its own key.
+
+  `outerlayer doctor` says whether the runner key is bound to this host, bound to another, or not yet bound. A refused signature is reported with its cause: a stale one names the host's clock. `outerlayer runner init` prints the host key's fingerprint.
+
+- 85fa250: On macOS, `outerlayer runner init` now offers to create a Linux VM with Lima and run the runner inside it, so builds run in containers and record `container`. `--vm` answers yes and `--no-vm` answers no; a run with no terminal answers no. The VM holds the runner key and the host key, and starts at login through a launch agent and a systemd service. The Mac's config loses `apiKey` and `runner` and gains a `runnerVm` note.
+
+  `outerlayer doctor` on a Mac with process hooks now says builds are not isolated and names `outerlayer runner init --vm`. With the runner in a VM, it reports the VM's state and how to start it.
+
+- 365dab4: The runner and `outerlayer work claim` now send the runner protocol they were built with, as `runnerProtocol`, on every claim, and the runner sends it on every heartbeat. A gateway that needs a newer protocol refuses the claim with `426 runner_upgrade_required`. The runner then logs the minimum protocol and a link to the upgrade steps, and keeps polling so it takes work again once it is upgraded and restarted.
+- 02f7990: `outerlayer init --template default` installs a starter skill pack into `.outerlayer/skills/`. The templates `spec`, `writing-specs` and `build` are copied once and never overwritten. The maintained skills `emitting-evidence` and `amend` are rewritten from the installed CLI on every `outerlayer context emit`, and each carries the CLI version on its first line. `init --template default` also writes a starter `.outerlayer/policy.yaml` unless one exists.
+
+  `outerlayer context emit --check` now reports drift, and exits 1, when a maintained skill differs from the installed CLI's copy, for example after a CLI upgrade. `outerlayer import capture` rewrites both maintained skills instead of refusing to overwrite a skill with local edits.
+
+- 1177caa: `outerlayer work build` takes a Linear or Jira issue key, not only a GitHub issue number: `outerlayer work build --issue ENG-123 --tracker linear`. `--tracker` names which tracker a keyed issue belongs to, required only when a factory has connected more than one. `--repo` is the only way to attach a repository to a keyed issue. A new `--retry <count>` option sends a build request again, up to 4 more times, after any 5xx or 429 answer, including a 5xx from a proxy in front of the gateway. A retry after such an answer can record the request twice. It never resends after a network error or a 4xx other than 429.
+- 852946a: Add `outerlayer work build`, which asks a host to build a work item. `outerlayer work add` alone no longer queues an item for a host. A session launched with `OUTERLAYER_WORK` now holds a 20-minute lease on its item, renewed by a new `PostToolUse` hook and released when the session ends; run `outerlayer init` to add the hook to an existing install.
+- b52a19e: `outerlayer work build` is the one command that starts work on an item. `work build --issue <n>` asks a host to build it. `work build --issue <n> --local` puts it on Work for you to build, and prints the `OUTERLAYER_WORK=<n> claude` line that starts your session on it. `outerlayer work add` is removed; use `work build --local` where you used it.
+- cfddc47: Adds `outerlayer work comment` and `outerlayer work threads`. A work item's review, and each acceptance criterion's own proof, live on comment threads now: a person's pass or fail, an agent's attach or ready. `outerlayer emit`'s per-artifact verdict option is removed — record it as a comment instead.
+
+### Patch Changes
+
+- 9787d1c: The runner now sends the step an attempt ended in, its exit code, and a one-line reason from `$OUTERLAYER_JOB_DIR/reason` when it releases a work item claim. The reason comes only from a file the host's own cleanup hook writes, scrubbed and cut to 200 characters before it leaves the machine.
+- 22ce869: The status line now keeps the session cost Claude Code reports, and `sync` and the daemon send it with each Claude Code session as `totals.agentReportedCostUsd`. The daily pricing check compares it with the cost the gateway stored.
+- ac57469: Every command on a runner host signs its requests with the host key when it uses the saved runner key. `outerlayer doctor`, `work status`, `sync`, `emit` and the other commands no longer fail with `runner_key_signature_required` once the runner key is bound to the host.
+- 1ba39dc: A container build now starts on the branch its claim names, by the rule a host build uses, before its lifecycle commands run. The checkout is a partial clone that keeps every commit, so a merged `outerlayer/` branch starts from the default branch's head. The build image also writes Claude Code managed settings that run `outerlayer hook`, so the sessions a build starts are linked to the item and uploaded by its sync. The runner copies the build's hook error log into the job directory before it removes the container.
+- 4677cd6: A container or process build can run `yarn install`. The runner now also sets `YARN_HTTPS_PROXY` and `YARN_HTTP_PROXY`, because Yarn 2 and later ignore `HTTPS_PROXY` and could not reach the registry from a build.
+- 1e2f5e3: `outerlayer doctor` checks that a container host can read the control plane of every repository the runner builds. With no `repos.include`, which is how `runner init` leaves the config, it checks every repository connected to the factory instead of nothing.
+- e4f5e1e: `outerlayer sync` no longer writes `~/.outerlayer/spool/session-repos.json`. Nothing reads that file, so it is safe to delete.
+- 0248261: Hooks written by `outerlayer init` run the CLI through `node`, so they keep working when a copy of the CLI loses its execute bit. Run `outerlayer init` again to rewrite hooks written by an earlier version. `outerlayer doctor` now fails "Hooks installed" when a hook runs the CLI script directly and the script is not executable.
+- f90e444: Help and error text use the product's own words. Every `--app-id` option is described as the factory id, no text calls the Work page "Floor", and a key bound to another factory is refused with "bound to a different factory". The package description names only commands the CLI has.
+- e78d9a9: The cost estimate charges 1-hour cache writes at the model's published 1-hour rate. It also charges a request whose total input exceeds a model's long-request threshold at the higher rates for every token, and charges fast mode at its multiplier for models that have one, such as Opus 5.5.
+- 0db0425: The provision hook written by `outerlayer runner init` clones the repository the work item records (`specRepository` in `outerlayer work status --json`) instead of reading it off the tracker key. A Linear or Jira item, whose key such as `ENG-123` names no repository, now clones the right one. An item that records no repository fails its job with one line saying so, rather than trying to clone a URL that does not exist. `runner init` never overwrites a hook, so delete an existing `provision.sh` written by an earlier version before running it again, or make the same edit by hand.
+- 112813e: No change in behavior. The committed `.outerlayer-pin.json` is still written and read the same way; the server no longer compares sessions against it.
+- 02db30e: The `reporting-findings` skill that `outerlayer init` installs now describes the moments it applies to: writing a "Factory problems" section, a build or review report, or noticing a stale instruction, a flaky test or a misbehaving gate. Its batch shape is spelled out so `outerlayer emit findings` files can be written from the skill alone.
+- 4c5a9ea: `outerlayer emit <name>` from inside a recorded session can now record checks on the work item the session was launched for, stored as the session's own. A session still cannot clear a person's fail. The help text and README say so.
+- 7720377: `outerlayer sync` no longer guesses a price for a model name it doesn't recognize exactly, case-insensitively, or as a listed variant (a provider prefix, a region prefix, a date suffix, a `-vN:M` suffix, or a `[1m]` suffix). A name like `claude-opus-4-9` now shows the existing unknown-model warning and stores an unpriced cost, instead of silently pricing as `claude-opus-4` — a different model, at a different rate.
+- 07c2785: `outerlayer work comment` now says that a person's `fail` on the item's general thread is what hands the item to an agent, and that a plain comment or a criterion `fail` no longer does. The README describes the item page in place of the removed Review tab.
+- d15ccf4: `outerlayer work comment` and `outerlayer work threads` print a failed request as a one-line error and exit 1, as the other `work` commands do, instead of a stack trace.
+- dec3f5b: `outerlayer work list --claimed` lists only the work items a host holds right now. Each claimed row shows which host holds it, as which kind of claim, since when and until when. With `--json`, each row carries its `claim` object.
+
 ## 0.2.0
 
 ### Minor Changes

package/README.md

@@ -13,8 +13,9 @@ network, and when, is below.
 Launch a session naming the work it's for, then sync:
 
 ```
-npx @outerlayer/cli init                          # install the capture hooks
-npx @outerlayer/cli work add --issue 42           # create the work item; prints its number
+npx @outerlayer/cli login                         # sign in, once per machine
+npx @outerlayer/cli init                          # connect this repository to a factory, install the capture hooks
+npx @outerlayer/cli work build --issue 42 --local # create the work item; prints its number
 OUTERLAYER_WORK=7 claude                     # launch a session naming that number
 npx @outerlayer/cli sync --dry-run                # see exactly what would leave your machine
 npx @outerlayer/cli sync                          # upload sessions launched that way
@@ -23,7 +24,7 @@ npx @outerlayer/cli sync                          # upload sessions launched tha
 ## Privacy, stated plainly
 
 **A session uploads only when you launch it with `OUTERLAYER_WORK` naming
-the work item it's for.** Create the item first with `outerlayer work add`,
+the work item it's for.** Create the item first with `outerlayer work build --local`,
 which prints its factory-scoped number, then set that number before
 starting your agent — `OUTERLAYER_WORK=7 claude`. The session-start hook
 then records the launch and the session uploads whole, from its first turn,
@@ -39,7 +40,7 @@ and never upload.
 sessions.** It runs when you run it. The hooks also fire `outerlayer sync
 --quiet` in the background after each agent turn and when a session ends, at
 most once every five minutes, as soon as `outerlayer login` has saved
-credentials. So a launched session uploads while it is still running, not
+credentials and `outerlayer connect` has chosen the repository's factory. So a launched session uploads while it is still running, not
 only once it is over. Set `"autoSync": false` in `~/.outerlayer/config.json`
 to leave every automatic upload — the background sync and the daemon's
 streaming below — to your own command.
@@ -58,16 +59,26 @@ along before that sync ever runs.
 These commands also talk to your workspace. None of them sends session
 content:
 
-- **`outerlayer work add`, `remove`, `status`, `list`, `link-session`, `pr`,
-  `claim`, `renew`, `release`** read and write your Floor. The session-start
+- **`outerlayer work build`, `remove`, `status`, `list`, `link-session`, `pr`,
+  `claim`, `renew`, `release`, `comment`, `threads`** read and write your factory's work items. The session-start
   hook spawns `outerlayer work link-session` when you launch a session with
   `OUTERLAYER_WORK`, naming the item and the session id — the item itself
-  must already exist, created ahead of time with `outerlayer work add`.
+  must already exist, created ahead of time with `outerlayer work build --local`.
   `outerlayer work pr` sends the session id and the pull request number and
-  repository — never the session's own content. `outerlayer work claim`
+  repository — never the session's own content. `outerlayer work open-pr`
+  sends the pull request's title and the text of the body file you name. In a
+  host build, which holds an item key, it goes to the gateway, which opens or
+  edits the pull request as the factory's GitHub App on the branch the claim
+  named, and no `gh` command runs. In your own session it runs `gh pr create`
+  or `gh pr edit` under your login, then sends the pull request number and
+  repository the way `work pr` does. `outerlayer work claim`
   records a lease for this host before it starts working on an item, so two
   hosts never build the same piece of work at once; `renew` extends it and
-  `release` marks it done. A runner key needs `git.read` and `work.read` to
+  `release` marks it done. `outerlayer work comment` posts one comment on a
+  work item's general thread or a criterion thread — the detected session id
+  rides along the same way it does for `emit`, only ever narrowing what the
+  comment may do; `outerlayer work threads` reads them back. A runner key
+  needs `git.read` and `work.read` to
   list and read items, and `work.claim` to claim, renew or release — `work.claim`
   is not granted to a dashboard role by default, since a claim is a host's
   lease, not a person's.
@@ -75,9 +86,159 @@ content:
   items the same way `work claim`/`renew`/`release` do, on the schedule its
   config sets — it sends nothing about the job it runs beyond that; the
   agent it starts is a separate process with its own credentials, from the
-  `runner` block, never the copy-out daemon's. `runner check` makes one
-  list call to confirm the key works and sends nothing else; `runner init`,
-  `runner status` and `runner logs` make no network call at all.
+  `runner` block, never the copy-out daemon's. It also sends a heartbeat at
+  the end of every poll: the host, the CLI version, the poll interval, the
+  slots in use and total, and the result of that poll's own request for
+  work — success, or the error code and message the platform returned.
+  When a build's command exits 0, it reads that work item once more, for its
+  evidence verdict, before releasing it: it sends nothing but the request.
+  Before a build's command starts, the runner also runs `git ls-remote` and
+  `git fetch` in the job's workdir, with the host's own git credentials, to
+  put it on the branch the claim named. Nothing about the job leaves the host
+  that way.
+  When the gateway names a higher CLI version than the one running,
+  `outerlayer runner start` also calls the public npm registry
+  (`registry.npmjs.org`) for `@outerlayer/cli` only: that version's metadata
+  at once, and once no build is in flight, its tarball and its provenance
+  attestation, plus an `npm install` and an `npm audit signatures` run
+  against that same registry. The calls carry no credentials and nothing
+  about the host or the factory. Set `runner.autoUpdate` to `false` to stop
+  them.
+  `runner check` makes a list call and a host-key lookup to confirm the key
+  works and sends nothing else; `runner status` and `runner logs` make no network call at all.
+  On a runner host, any command that uses the saved runner key signs each
+  request it makes with the host key, the way the runner does. The signature
+  covers the request's method, path, query and body, and adds nothing else
+  to it.
+- **`outerlayer runner init`** makes no network call, except `runner init --vm`
+  on a Mac. That runs `limactl`, and Lima downloads a Linux VM image. Inside
+  the VM, `apt` downloads Node and `npm` downloads this CLI. Your runner key goes to the VM on the standard
+  input of a `limactl shell` command and is never a file or an argument on the
+  Mac.
+- **`outerlayer login`**, with no key on stdin, signs in to your account by
+  browser approval. It sends your dashboard a one-time public key and this
+  machine's host name, then polls for the answer. The answer is a token for
+  your account, encrypted to that public key, so only this process can read
+  it. It comes with the gateway address and your email, and no factory
+  or organization. The token is saved to `~/.outerlayer/config.json` and
+  never printed. If this machine held a token from an earlier login, login
+  asks the dashboard to revoke it. A key piped on stdin makes no network
+  call.
+- **`outerlayer connect`**, and the first step of `outerlayer init`, send a
+  request with your login's token: `GET /v1/me/factories?repository=<host/owner/name>`,
+  naming this checkout's remote. The gateway answers with the factories you can
+  use, and whether this repository is linked to each. Once a factory is chosen,
+  a second request, `GET /v1/apps/<factory id>/git/links`, asks which
+  repositories that factory has linked, to say whether this one is among them.
+  Nothing else leaves the machine. The choice is saved in the repository's git directory, at
+  `outerlayer/connection.json`, which git never tracks. With a factory key it
+  makes no network call. `outerlayer init --local` makes none either.
+- **`outerlayer logout`** sends the saved token to your dashboard
+  (`POST /api/cli/logout`) so it is revoked, then deletes it from the config
+  file. It sends nothing else.
+- **`outerlayer runner image`** runs `git fetch` against the repository's
+  remote, `https://github.com/<owner>/<name>.git` unless `--remote` names
+  another, with the host's own git credentials. It sends nothing about the
+  host. Docker pulls base images, features and Claude Code's npm package
+  from registries while the image builds, with the host's own `docker
+  login`. The tools layer also downloads the pinned `gh` and `tini` releases
+  from GitHub, checking each against a digest. The image build runs outside
+  any work item and sends nothing to your factory.
+- **`outerlayer runner start` with `builtin:vm` hooks** runs each build in its
+  own Firecracker microVM, which has no network device. The guest kernel and
+  helper are not published yet, so no host is offered `builtin:vm` and
+  `outerlayer doctor` fails it. Once they are, the first microVM
+  build downloads a pinned Firecracker release, a guest kernel and a guest
+  helper from github.com, and checks each against a sha256 pinned in the CLI;
+  the requests send nothing about the host. The build reaches the network only
+  through the same tunnel a container build uses, which the runner serves on
+  Unix sockets and the guest reaches over vsock. The guest's exec agent accepts
+  connections from the host only, and the runner runs every step of the build
+  through it, including the build's command (`outerlayer vm-exec` on the host).
+- **`outerlayer runner start` with `builtin:container` hooks** runs each
+  build in its own Docker container, which has no network but loopback. The
+  build reaches the network only through a tunnel the runner serves on a
+  Unix socket, which the container's own `outerlayer broker-relay` process
+  reaches from loopback. The tunnel refuses loopback, private, link-local,
+  shared-address, multicast and unique-local addresses and the host's own,
+  and it terminates no TLS. The tunnel also serves the build a local git
+  remote. Git in the container still shows
+  `https://github.com/<owner>/<name>.git` and reaches the runner instead,
+  which forwards only git's fetch and push requests and Git LFS batch calls
+  to github.com. For the item's repository the runner adds a GitHub App
+  token it asked your gateway for (`POST /v1/work-items/{id}/claim/tokens`):
+  a read token for a fetch, and a push token for a push, which it forwards
+  only when every ref the push updates is the branch the claim names. Any
+  other repository is forwarded with no credential. Before it forwards a
+  push to a branch outside `outerlayer/`, the runner runs `git fetch` and
+  `git receive-pack` in a bare mirror it keeps under its own directory, with
+  the read token, to check that the push moves the branch forward. The
+  build's `gh` holds the read token in a directory the runner owns and
+  nothing else. When the attempt ends, the runner revokes every token it was
+  issued with `DELETE https://api.github.com/installation/token`, sent with
+  the token it revokes. The release for the attempt then lists the hosts the
+  build reached, each address the tunnel refused with its range, the names,
+  never the values, of the host variables the runner's config passed in, the
+  names of the destinations it called, which kinds of token the build used,
+  and whether its commits were authored by the GitHub App's bot account and
+  credited the member who asked for the build. The runner sets that author in
+  the build's environment and adds the `Co-authored-by` line with git hooks it
+  writes into the build's own directory.
+- **`outerlayer runner start` with `builtin:container` hooks** also asks your
+  gateway which repository governs the item's repository (`GET
+  /v1/context/source`, signed with the host key), after the recipe's
+  lifecycle commands. When one does, the runner runs `git fetch` against that
+  control plane on the host, with the host's own git credentials, and copies
+  its context into the checkout through the build's directory. The build
+  receives files and no credential for the control plane. The runner deletes
+  the staged copy before the command starts. A host that cannot read the
+  control plane fails the build at provision.
+- **`outerlayer runner start` with `builtin:process` hooks** runs each build
+  as a process under the runner's own user, with no isolation, and the
+  attempt records `shared-user`. The runner clones the item's repository
+  from `https://github.com/<owner>/<name>.git` with the host's own git
+  credentials. It serves the same tunnel on a loopback port, which the
+  build reaches through its proxy settings, and the release lists the same
+  hosts and refusals.
+- **`outerlayer runner start` with your own executable hooks** runs
+  `git ls-remote` against `https://github.com/<owner>/<name>.git`, with the
+  host's own git credentials, before each provision hook, to tell the hook
+  the commit the default branch points at. It sends nothing about the host,
+  and a host whose git cannot reach the remote loses only that hint.
+- **`outerlayer runner start` with `build.destinations`** serves each
+  destination the config lists on a local address, and forwards each request
+  a build sends there to the destination's upstream, over HTTPS, with the
+  header the config names in place of any credential the build sent. The
+  header's secret is read from the runner's own environment.
+  It is never in a build's environment or files, and the release names a
+  destination and nothing more.
+- **`outerlayer runner start` with `builtin:vm`, `builtin:container` or
+  `builtin:process` hooks** also serves two built-in destinations, `gateway` and `claude`, to
+  each build. The gateway destination forwards a build's requests to your
+  gateway with the attempt's item key, and the `claude` destination forwards
+  them to `https://api.anthropic.com` with the host's `CLAUDE_CODE_OAUTH_TOKEN`
+  or `ANTHROPIC_API_KEY`, read from the runner's own environment. A build holds a placeholder for each and never the value, and the
+  release names the two destinations and nothing more. A build under
+  `builtin:process` runs as the runner's user and can still read the runner's
+  environment and the attempt's job file.
+- **`outerlayer doctor`**, once a factory key is saved (`echo "$KEY" | outerlayer login`),
+  asks your gateway (`GET /v1/repositories/access`, with that key) which
+  GitHub App permissions each connected repository's installation has not
+  accepted, and whether each default branch requires a pull request. The
+  request carries nothing about the host, and the gateway stores nothing.
+- **`outerlayer runner check`** also asks your gateway (`GET /v1/runner/host-key`,
+  with the runner key, signed with the host key) whether the key holds
+  `work.claim`, so a key that cannot claim is named before the host takes work.
+  The request carries nothing about the host beyond the signature the key's
+  own requests already carry, and the gateway stores nothing.
+- **`outerlayer doctor`** on a runner host, one with a `runner` block in its
+  config, also asks the npm registry for the latest Claude Code version, to
+  say whether the version the runner's images pin is behind. The request
+  names the package and nothing about the host. On a host with
+  `builtin:container` hooks it also asks your gateway which repository governs
+  each repository in `repos.include` (`GET /v1/context/source`), then runs
+  `git ls-remote` against that control plane with the host's own git
+  credentials, to say whether the host can read it.
 - **`outerlayer emit artifact`** uploads the file you name — a screenshot, a
   recording, a report, a log — along with its caption. With no recorded
   session to attach it to, it uploads immediately, anchored to a pull request
@@ -88,9 +249,14 @@ content:
   route. Run from CI or a plain shell, where there is no session, it sends
   as it always has.
 - **`outerlayer emit finding`** and **`outerlayer emit findings <file>`** send
-  one finding, or a whole batch of them, for a work item — the same
-  anchoring as `emit <name>` (`--item`, or the recorded session's own item),
-  except a session may record findings on the item it was launched for.
+  one finding, or a whole batch of them, for a work item — a problem an agent
+  hit in the factory. The anchoring is the same as `emit <name>` (`--item`, or
+  the recorded session's own item).
+- **`outerlayer emit criteria <file>`** sends the acceptance criteria of a work
+  item as one list (`POST /v1/criteria`): each criterion's id, text and
+  declared proof kind, from the JSON file you name. The anchoring is the same
+  as `emit finding`. Nothing but the file's content and the item number is
+  sent.
 - **`outerlayer mcp serve`** is the stdio MCP server your editor spawns. It
   forwards every JSON-RPC message the editor sends to the gateway and returns
   the reply.
@@ -122,9 +288,9 @@ space, past both stubs, so the same test records every program each run
 starts and asserts none of them fetches over the network.
 
 Failures the hook cannot show you — a refused `OUTERLAYER_WORK` value, a
-`work add` that could not reach the Floor — are appended to
+`work link-session` that could not reach the factory — are appended to
 `~/.outerlayer/spool/hook-errors.log`, and the next session start says so.
-The addition retries a gateway it cannot reach a few times, with backoff,
+The link retries a gateway it cannot reach a few times, with backoff,
 before it gives up.
 
 - **The tier is applied before anything leaves.** The default tier is
@@ -142,37 +308,43 @@ before it gives up.
 | Command | What it does |
 |---|---|
 | `outerlayer sync` | Upload sessions launched with `OUTERLAYER_WORK` to your OuterLayer cloud workspace (incremental — only what's new since the last sync). Tier-gated client-side (`--tier metrics\|redacted\|full`, default `full`); `--dry-run` prints exactly what would leave the machine; `--all` re-sends everything (idempotent server-side). Credentials come from `outerlayer login`, `OUTERLAYER_*` env vars, or `--url/--app-id`. |
-| `outerlayer login [--url] [--app-id]` | Save the cloud URL, app id, and API key to `~/.outerlayer/config.json` once. The key is read from stdin (`echo "$KEY" \| outerlayer login …`) or a prompt with echo off; it is never a flag. `--no-input` refuses to prompt. |
-| `outerlayer init` | Install the capture hooks and the status-line segment. `--json` for scripts. Run through `npx`, it copies the CLI to `~/.outerlayer/cli` and points the hooks at that copy, so they survive npm clearing its cache; `npx @outerlayer/cli@latest init` upgrades it. From any other install, the hooks run that install. Claude Code deletes transcripts after ~30 days; run `outerlayer daemon` separately to mirror them first — `init` does not start it for you. |
+| `outerlayer login [--dashboard] [--no-browser] [--check <id>]` | Sign in to your account by browser approval: prints an approve link and a code, a signed-in person approves it, and a token for their account is saved to `~/.outerlayer/config.json` without ever being shown. It chooses no factory; `outerlayer connect` does. Without a terminal it prints one JSON document and exits 75; `--check <id>` finishes it (0 signed in, 75 still waiting, 1 denied or expired). A factory key piped on stdin (`echo "$KEY" \| outerlayer login --url … --app-id …`) is saved as before; it is never a flag, and it always wins over the login. `--no-input` refuses to wait on a person. |
+| `outerlayer logout` | Revoke this machine's login on the dashboard and delete it from the config file. A saved factory key and factory are left alone. If the dashboard cannot be reached it still deletes the local copy, exits 1, and says the token stays valid until revoked on `/profile/security`. |
+| `outerlayer connect [--factory <org>/<factory>] [--json]` | Choose the factory this repository's work goes to, and say what it chose and why. With a login it lists the factories you can use and takes the first rule that leaves one answer: `--factory`, the factory this repository is already connected to, the one factory it is linked to, the one factory you can use; on a terminal it then asks, and with no terminal it exits 1 listing each `--factory` value. The choice is saved in the repository's git directory, shared by every worktree and never committed. A factory key already belongs to one factory, so `connect` changes nothing for it. It never links a repository. Once a factory is chosen it asks that factory whether this repository is linked. If not, it still saves the choice, prints the factory's Work page link to stderr and exits 2. `--json` writes one JSON document to stdout. |
+| `outerlayer init` | Connect this repository (`outerlayer connect`), install the capture hooks and the status-line segment, and run `doctor`. It never signs in: without a login it skips the connect step and says to run `outerlayer login`. `--local` installs the hooks only, with no network call. `--json` prints one document naming each step's outcome. Run through `npx`, it copies the CLI to `~/.outerlayer/cli` and points the hooks at that copy, so they survive npm clearing its cache; `npx @outerlayer/cli@latest init --local` upgrades it. From any other install, the hooks run that install. Claude Code deletes transcripts after ~30 days; run `outerlayer daemon` separately to mirror them first — `init` does not start it for you. |
 | `outerlayer daemon` | Run the copy-out daemon in the foreground (`--once` for a single sweep, which uploads nothing). Once cloud credentials exist, it also streams a launched session's new turns as they land — see Privacy, above. `outerlayer watch` is the former name and still works, with a warning. |
-| `outerlayer doctor` | Check the installation: hooks, status-line freshness, and sync health. `--json` prints the checks and a summary for scripts. |
+| `outerlayer doctor` | Check the installation: hooks, status-line freshness, sync health and, with a factory key, the GitHub App access builds need. `--json` prints the checks and a summary for scripts. |
 | `outerlayer context emit [--check]` | Compile `.outerlayer/` into each configured target tool's native files (targets come from `.outerlayer/config.json`). `--check` computes outputs and diffs against disk without writing (CI mode). Bare `outerlayer emit` with no name still compiles, with a deprecation warning. |
 | `outerlayer import ruler` | Port a `.ruler/` tree ([Ruler](https://github.com/intellectronica/ruler)) into the equivalent `.outerlayer/` tree — mostly a rename; never overwrites an existing `.outerlayer/`. |
 | `outerlayer hooks wrap` / `outerlayer hooks unwrap` | Auto-wrap (or undo wrapping) `PreToolUse`/`PostToolUse` hooks for execution evidence — one spawn per firing. |
-| `outerlayer emit artifact <file> --caption <text> [--for <criterion-id>] [--pr <n>]` | Upload a proof artifact — screenshot, recording, report, or log — with its caption. Inside a recorded session it spools locally and ships on the next `sync`; otherwise it uploads immediately, anchored to a pull request or the current checkout. `--replaces` retires artifacts an earlier run uploaded. |
-| `outerlayer emit <name> --result <pass\|fail> [--link <url>] [--body <text>\|--body-file <path>] --item <number>` | Record one named check's outcome on a work item. A check that ran carries the run URL as its proof (`--link`); a judgment you are making yourself carries one sentence (`--body`, or `--body-file` to read it from a file — `-` reads standard input). A `fail` needs at least one of the two; a `pass` needs neither. `--item` names the work item by the number printed when the item was created — always required, in or out of a recorded session; from inside a session it can only name an item that session was NOT launched for (a session cannot record a check on its own item). Prints the recorded check's id. Who recorded it comes from your API key, never from what you send. |
-| `outerlayer emit artifact-review --result <pass\|fail> --artifact <id> [--body <text>\|--body-file <path>]` | Record a person's own pass or fail on one artifact — evidence already emitted, bound to a criterion. `--artifact` names it and replaces `--item`; the gateway resolves the work item from the artifact's own pull request. `--link` is refused. A `fail` reads its sentence from `--body`/`--body-file`, or from standard input when neither is given. Refused from inside a recorded session — an artifact verdict is a person's act, the same rule the gateway enforces. Prints the recorded verdict's id. |
-| `outerlayer emit finding --id <id> --subject <change\|context> --title <text> --file <path> --kind <behavior\|hygiene\|proof> --verdict <confirmed\|refuted\|unverified> --source <implementer\|reviewer\|refuter\|gate> --where <label> [--item <number>] …` | Record one finding — what was found wrong about the change (`--subject change`) or about a rule it ran on (`--subject context`, which then needs `--rule-path`, `--rule-quote` and `--rule-relation` together — all three are required, not just `--rule-path`). Validated against the same contract the gateway checks before anything is sent. `--item` names the work item; without it, inside a recorded session, the item that session was launched for is used automatically — unlike `emit <name>`, a session may record findings on its own item. Re-emitting the same `--id` on the item replaces that finding. |
-| `outerlayer emit findings <file> [--item <number>]` | Record a whole batch at once, read from a `FindingBatch` JSON file (`-` for standard input) — the same shape and validation as `emit finding`, one record per subject/title/file/kind/verdict/source/where. Anchored the same way: `--item`, else a recorded session's own item. |
+| `outerlayer emit artifact <file> --caption <text> [--for <criterion-id>] [--pr <n>]` | Upload a proof artifact — screenshot, recording, report, or log — with its caption. Inside a recorded session it spools locally and ships on the next `sync`; otherwise it uploads immediately, anchored to a pull request or the current checkout. `--replaces` retires artifacts an earlier run uploaded. A JUnit XML file bound with `--for` proves a criterion that declares `test` proof; `--test <name[=path:line]>` binds only the named tests. |
+| `outerlayer emit <name> --result <pass\|fail> [--link <url>] [--body <text>\|--body-file <path>] --item <number>` | Record one named check's outcome on a work item. A check that ran carries the run URL as its proof (`--link`); a judgment you are making yourself carries one sentence (`--body`, or `--body-file` to read it from a file — `-` reads standard input). A `fail` needs at least one of the two; a `pass` needs neither. `--item` names the work item by the number printed when the item was created — always required, in or out of a recorded session; a session records checks on its own item like any other, stored as the session's, but cannot clear a person's fail. Prints the recorded check's id. Who recorded it comes from your API key, never from what you send. |
+| `outerlayer work comment --item <n> [--criterion <id>] --body <text> [--artifact <id>] [--pass\|--fail\|--attach\|--ready]` | Post one comment on a work item's general thread, or on one acceptance criterion's own thread with `--criterion`. `--pass`/`--fail` need a person's own credential and apply to the whole item, so they work on the general thread only and the gateway refuses them with `--criterion`; `--attach` makes the named artifact that criterion's current proof; `--ready` hands a thread back to a person. The detected session id rides along automatically, only ever narrowing what the comment may do. |
+| `outerlayer work threads --item <n>` | Read a work item's threads back — the general thread first, then one per criterion with proof or a comment, each with its `waitingOn`. |
+| `outerlayer emit finding --id <id> --category <context\|flaky-test\|tooling\|environment\|defect\|other> --title <text> --file <path> --where <label> [--line <n>] [--item <number>] …` | Record one problem you hit in the factory. `--category` is one of `context` (an instruction that is wrong, broken or missing), `flaky-test`, `tooling`, `environment`, `defect` (a bug outside your own change) or `other`. A `context` finding also needs `--rule-path` and `--rule-relation` (`wrong`, `broken` or `missing`), and `--rule-quote` unless the relation is `missing`. Findings are informational; nothing reads one to pass or fail the work. `--item` names the work item; without it, inside a recorded session, the item that session was launched for is used automatically. Re-emitting the same `--id` on the item replaces that finding. |
+| `outerlayer emit findings <file> [--item <number>]` | Record a whole batch at once, read from a JSON file (`-` for standard input) with `"schemaVersion": 2` — the same shape and validation as `emit finding`, one record per id, category, title, file, line, rule and where. Anchored the same way: `--item`, else a recorded session's own item. |
+| `outerlayer emit criteria <file> [--item <number>]` | Record a work item's acceptance criteria as one list, read from a JSON file (`-` for standard input): `{"criteria": [{"id": "AC-1", "text": "Given …", "proof": null}]}`. An `id` is 1 to 64 characters of `A-Z a-z 0-9 . _ : -`, the same id `emit artifact --for` binds evidence to. `proof` is `video`, `screenshot`, `report`, `log`, `test`, `file` or `null` (any bound artifact proves it). The list holds 1 to 200 criteria, each `text` at most 2,000 characters, with no id twice. It is validated before anything is sent. This list is the only source for the item's Criteria tab. Once an item has a list, only a person can replace it: run the command outside an agent session, with your own login. Anchored the same way as `emit findings`: `--item`, else a recorded session's own item. |
 | `outerlayer mcp install [--transport stdio\|http] [--url] [--name] [--command]` | Write (or update) an `mcpServers` entry in `.mcp.json` for the OuterLayer gateway. Default `stdio`: the client spawns `outerlayer mcp serve`, which reads the API key from `~/.outerlayer/config.json` (or `OUTERLAYER_API_KEY`) each time it connects, so a reconnect picks up a newly saved or rotated key. `--transport http` writes a direct `POST /v1/mcp` entry referencing `${OUTERLAYER_API_KEY}`, resolved by the client from the environment it was launched with. Never writes an API key. Pass `--url`/`--app-id` for self-host. |
 | `outerlayer mcp serve [--url] [--app-id]` | Stdio MCP server bridging stdin/stdout JSON-RPC to the gateway's `POST /v1/mcp`. What the stdio `.mcp.json` entry runs; exits 1 with a clear message when no API key is configured. |
-| `outerlayer work add --issue <n>\|--pr <n> [--repo] [--note]` | Records that a source — a recorded session, a CI run, or the API key's bound member — is working on an issue or pull request. The only way an item becomes visible on the Floor. |
-| `outerlayer work remove --issue <n>\|--pr <n> --reason <text> [--repo]` | Withdraws the caller's own addition, recording the reason. Never deletes anything; the item leaves the Floor only once no live addition remains on it. Removing again is a no-op that still succeeds. |
+| `outerlayer work build --issue <n\|KEY>\|--item <n> [--tracker linear\|jira] [--local] [--repo] [--note] [--retry <count>]` | Starts work on an item and puts it on the Work page. `--issue` takes a GitHub issue number or a Linear or Jira key such as `ENG-123`; the gateway verifies a key against the factory's tracker connection before adding it. `--tracker` is needed only when both Linear and Jira are connected. A key gets a repository only from `--repo`, never from the checkout. Without `--local`, records a build request that a host takes when it has a free slot. With `--local` (issue only), no host takes it: it prints the item's number and the line that starts your own session on it, such as `OUTERLAYER_WORK=7 claude`. `--retry` resends after a 5xx or 429 answer, up to that many more times. |
+| `outerlayer work remove --issue <n>\|--pr <n> --reason <text> [--repo]` | Withdraws the caller's own addition, recording the reason. Never deletes anything; the item leaves the Work page only once no live addition remains on it. Removing again is a no-op that still succeeds. |
 | `outerlayer work status --issue <n>\|--pr <n> [--repo]` | Shows one item's stage, section, gate ledger, linked pull requests and sessions, and its additions. |
-| `outerlayer work list [--stage] [--section] [--repo] [--unclaimed] [--startable] [--needs amend]` | Lists live work items for the current factory, filterable by stage, section, claim state and whether an open fail is waiting for an answer. |
+| `outerlayer work list [--stage] [--section] [--repo] [--claimed] [--unclaimed] [--startable] [--needs amend]` | Lists live work items for the current factory, filterable by stage, section, claim state, startability and whether a comment thread is waiting on an agent. |
 | `outerlayer work pr <n> [--repo] [--session-id]` | Run inside a session on a work item: declares that pull request `<n>` in the checkout's repository belongs to that item. Idempotent — declaring the same pull request twice is a no-op. Refuses when the session is on no item, or the repository is not connected. |
-| `outerlayer work claim --item <n>\|--issue <n> --kind implement\|amend [--repo] [--host] [--seconds]` | Records a lease for this host (default: its own hostname), so two hosts never build the same item at once. A live lease already held by a different host is refused; claiming again under the same host extends it. Lease length defaults to 900 seconds, the server's own cap. |
-| `outerlayer work renew --item <n>\|--issue <n> [--repo] [--host] [--seconds]` | Extends this host's own live lease. Refused if the lease has expired, or if a different host holds it. |
+| `outerlayer work open-pr --title <text> --body-file <path> [--repo] [--session-id] [--json]` | Opens the pull request for the work item this session is on, or edits the one already open on its branch. A host build, which holds an item key, sends it to the gateway, which opens it as the factory's GitHub App from the branch the claim named; no `gh` command runs. Your own session runs `gh pr create` or `gh pr edit` under your login and then declares the pull request on the item. Run it again after changing the title or description. |
+| `outerlayer work claim --item <n>\|--issue <n> --kind implement\|amend [--repo] [--host] [--seconds]` | Records a lease for this host (default: its own hostname), so two hosts never build the same item at once. The lease belongs to the runner key that claimed it: a live lease held by a different key is refused, even under the same host name, and claiming again with the same key extends it. The first claim creates the host key (`host-key.pem` beside the config file) and binds the runner key to it; from then on every request made with that key is signed. Lease length defaults to 900 seconds, the server's own cap. |
+| `outerlayer work renew --item <n>\|--issue <n> [--repo] [--host] [--seconds]` | Extends this host's own live lease. Refused if the lease has expired, or if a different runner key holds it (403 `claim_not_held`). |
 | `outerlayer work release --item <n>\|--issue <n> [--repo] [--host] [--outcome]` | Marks this host's lease released, optionally recording how the attempt ended. Releasing an already-released lease is a no-op that returns the recorded release time and outcome. |
-| `outerlayer runner init [--config <path>]` | Writes a `runner` block with defaults and three example hooks, keeping every key the config already had. Refuses rather than overwriting an existing block. |
+| `outerlayer runner init [--vm\|--no-vm] [--config <path>]` | Writes a `runner` block with defaults, keeping every key the config already had. It names `builtin:vm` on a Linux machine where the user can use `/dev/kvm` and Docker Engine can build images once the guest kernel and helper are published (not yet), `builtin:container` on that machine until then, `builtin:container` on any other machine with Docker Engine, and `builtin:process` on one without, and writes no hook script. Refuses rather than overwriting an existing block. On macOS it asks whether to create a Linux VM with Lima, installs Docker Engine and the runner in it, and starts both at login; `--vm` answers yes and `--no-vm` answers no, and a run with no terminal answers no. The runner key and the host key then live only in the VM: the Mac's config loses `apiKey` and `runner` and gains a `runnerVm` note, which `outerlayer doctor` reads. |
 | `outerlayer runner check [--config <path>]` | Validates the config, the hooks and the key, prints the settings the runner would use, and exits non-zero on a problem. Takes no work and writes no pid file. |
 | `outerlayer runner start [--config <path>]` | Runs the loop: claim work, run it, sync, clean up, report, release with an outcome. Repeat. Reads the `runner` block from the config file (default `~/.outerlayer/config.json`). Refuses to start on a bad config, an unrunnable hook, or a refused key. |
+| `outerlayer runner image --repository <owner/name> [--remote <url>] [--config <path>] [--json]` | Builds the image a repository's builds run in. Fetches the head of the default branch into the runner's cache, builds its `.devcontainer/devcontainer.json` with the devcontainer CLI, ignores every setting that reaches the host or widens the container's privileges, and adds this CLI and a pinned Claude Code. Reuses the image until the recipe or the tools change, keeps the newest three, and writes `recipe.json` beside the image record. Refuses a Compose recipe (`recipe_needs_docker`) and a repository with only named configurations (`recipe_ambiguous`). |
 | `outerlayer runner stop [--config <path>] [--now]` | Takes no more work and waits for running jobs to finish, naming each every five seconds. `--now` ends them immediately with outcome `stopped`. Ctrl-C on a foreground runner drains; a second one stops now. |
 | `outerlayer runner status [--config <path>] [--recent] [--json]` | A header naming the runner's own state, then a row per running job — item, queue, stage, elapsed, started, lease, job directory. `--recent` adds finished jobs, newest first, capped at 20, with their outcomes. |
 | `outerlayer runner logs <item> [--config <path>] [-f]` | Prints the newest attempt's log for one item, following it with `-f`. |
 
 The `work` commands need an API key that carries `work.insert` to add,
-remove, and declare a pull request (`pr`), and `work.read` to look an item up
+remove, and declare a pull request (`pr`, `open-pr`), and `work.read` to look an item up
 — which `remove` and `status` both do before they act. Tick both when you
 mint the key, in Settings → API keys. Claiming, renewing or releasing a
 lease needs `work.claim`. Withdrawing an addition somebody else made
@@ -203,10 +375,9 @@ Record a pass once the work is right:
 outerlayer emit code-review --result pass --item 412
 ```
 
-`--item` is always required, in or out of a recorded session. A session
-records a check only on an item it was NOT launched for, by naming it with
-`--item`; a check on the item the session itself was launched for needs a
-machine key (an API key run outside the recorded session) or CI.
+`--item` is always required, in or out of a recorded session. Inside a
+recorded session, the check is stored as the session's, on the item it was
+launched for or any other. A session cannot record over a person's fail.
 
 Three things to know. Who recorded a check is decided by the API key you
 used, never by anything in the request. A key bound to a membership records
@@ -216,30 +387,28 @@ because a fail with neither is something nobody can act on. And a check only
 holds a gate once a validator in `.outerlayer/validators/` declares its emit
 name; without one the check is recorded and read back, and blocks nothing.
 
-A review of the work itself is different: it is recorded from the Review
-tab on the work item page, not the CLI, and holds every pull request of the
-item until a person records a pass — no validator declaration needed.
-`outerlayer emit` refuses `work-review` outright; recording it anywhere but
-the work item page is not supported. The gateway refuses a review, and an
-artifact verdict, on an item that is closed or shipped, has no evaluation
-yet, or whose evaluation is still waiting on a session link, with the code
-`item_not_reviewable`. A recorded pass carries the head commit of every
-pull request the item had at the time; once one of them moves, that pass
-stops counting and a fresh review is needed. A repository can require a
-current pass before the evidence check completes by setting the base
-branch's `review` policy key to `required` (default `optional`, alongside
-`merge_gate`) — the check then stays in progress, not failed, until a
-current pass exists.
-
-`outerlayer emit artifact-review` sits between the two: a person's own pass
-or fail, like a review, but on one piece of evidence rather than the whole
-item. A fail here holds the item the same way a review's fail does, and
-counts the work as bad on Quality once, however many artifacts carry one —
-it also lists the item on a queue the API exposes, naming the artifact and
-why it failed, so a host with a session linked to the item can answer it
-with a replacement, or the fail's own recorder can pass over it directly.
-The item's own pass stays available only once every required artifact has
-a pass and no fail is still open.
+A review of the work itself is different: a person records it as a `pass`
+or `fail` on a work item's general thread (the item page, or `outerlayer
+work comment` on the general thread), never as a named check — no validator declaration needed. The gateway refuses a
+pass or fail on an item that is closed or shipped, has no evaluation yet,
+or whose evaluation is still waiting on a session link, with the code
+`not_reviewable`. A recorded pass on the general thread carries the head
+commit of every pull request the item had at the time; once one of them
+moves, that pass stops counting and a fresh review is needed. A repository
+can require a current pass before the evidence check completes by setting
+the base branch's `review` policy key to `required` (default `optional`,
+alongside `merge_gate`) — the check then stays in progress, not failed,
+until a current pass exists.
+
+A criterion thread is scoped to one acceptance criterion rather than the
+whole item: an agent attaches proof with `outerlayer work comment
+--criterion <id> --artifact <id> --attach`, and a person leaves a note on
+it with a plain comment. A pass or fail is a verdict on the whole item, so
+the gateway refuses one on a criterion thread. A fail on any thread counts
+the work as bad on Quality once, however many threads carry one — a fail on
+the general thread also lists the item on the amend queue `outerlayer
+runner start` reads, naming the thread waiting on an agent, until a
+person's next pass or fail clears it.
 
 Every command accepts `--no-color`, and color is off on its own when stdout is not a terminal, when `NO_COLOR` is set, or when `TERM` is `dumb`. `FORCE_COLOR=1` turns it on for a pipe. Commands that print anything accept `--json`.