@outerlayer/cli 0.1.1 → 0.4.0

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,41 +59,202 @@ 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_connection.read` to list
-  and read items, `work_item_claim.insert` to claim, and
-  `work_item_claim.update` to renew or release — the two claim permissions
-  are not granted to a dashboard role by default, since a claim is a host's
+  `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.
 - **`outerlayer runner start`** lists, claims, renews and releases work
   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.
+  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
   or to the git checkout.
-- **`outerlayer emit <name>`** and **`outerlayer emit commit-credit`** send
-  one check's outcome, and one commit's attribution, for a work item. Run
-  from inside a session, they send only when that session carries a launch
-  record — the session's own content may not leave by a second route. Run
-  from CI or a plain shell, where there is no session, they send as they
-  always have.
+- **`outerlayer emit <name>`** sends one check's outcome for a work item.
+  Run from inside a session, it sends only when that session carries a
+  launch record — the session's own content may not leave by a second
+  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.
@@ -124,9 +286,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
@@ -144,45 +306,47 @@ 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 commit-credit --pr <n> …` | Send one commit's attribution for a pull request. |
-| `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 <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`, `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 `Ingest traces`
-(`trace.write`) to add, remove, and declare a pull request (`pr`), and `Read
-the Work page` (`git_connection.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 a lease needs `Claim work items`
-(`work_item_claim.insert`); renewing or releasing one needs `Renew or
-release work item claims` (`work_item_claim.update`). Withdrawing an
-addition somebody else made additionally needs `Withdraw others' work from
-the Work page` (`git_connection.update`).
+The `work` commands need an API key that carries `work.insert` to add,
+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
+additionally needs `work.update`.
 
 ### Recording your own pass or fail on a check
 
@@ -209,10 +373,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
@@ -222,30 +385,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`.