# Integrating wrokin — a manual for coding agents

This document is written to be **executed by an AI agent** setting up wrokin on a repository. Every step states its verifiable outcome. Two steps — marked **HUMAN CHECKPOINT** — require a person: GitHub's install consent + API-key custody, and payment. Everything else is yours.

wrokin is a GitHub App that runs an AI agent team on a repo: **code review** and **security audit** on pull requests, **issue triage** on new issues, and **Warden**, a deterministic repo-setup audit. Reviews are **BYOK**: they run on the installer's own LLM API key and chosen model, per agent.

## 1. Install the GitHub App — HUMAN CHECKPOINT

Send the human ONE link and ask them to install it on the target repositories —
the deep-link form lands directly on GitHub's account/repo picker, which is as
much pre-selection as GitHub allows:

    https://github.com/apps/wrokin/installations/new

**Verify** (agent-executable): comment `/w audit` on any open issue or PR, from an account with repo write access — **Warden replies with a repo-posture report and needs no API key**, so it works the moment the install lands. On a **public** repo the reply carries the counts per tier and a dashboard link, not the checks themselves (a list of what's weak in a public repo's setup is readable by anyone); a private repo gets the full report. Either reply verifies the install. Alternatively, the human can confirm `wrokin` under the repo's Settings → GitHub Apps. Do **not** try `GET /repos/{owner}/{repo}/installation` — that endpoint requires the app's own JWT (which only wrokin holds), so its 404 proves nothing about the install. Until this step verifies, nothing below has any effect.

## 2. Add a model API key — HUMAN CHECKPOINT

Reviews spend the installer's own LLM key. Two paths; the human chooses:

**Path A — dashboard (human does it all):**

    https://app.wrok.in  →  Keys  →  add a key for the provider you plan to use

For **Bytesbrains AI Cruise** specifically (tenant → `cru_live_…` key → vault row →
`bb/…` lane), follow the short human guide: https://wrok.in/docs/cruise — it names
where the key goes and never includes a key value.

**Path B — setup token (human mints, agent configures):** the human clicks once in
the dashboard (Keys → "Mint setup token"), and hands YOU a short-lived `wst_…`
token. You then drive the setup API yourself — submit keys, pick models, enable
events — without the human clicking through anything else. Contract below (§2a).
If you will keep managing wrokin after setup, ask instead for an **API token**
(`wrk_…`, Keys → "API tokens"): same API, scopes and expiry chosen by the human (§2b).

Supported providers: `anthropic`, `openai`, `deepseek`, `google`, `mistral`, `openrouter`, `moonshot`, `groq`, `xai`, `meta`, `cruise`, plus any
`custom:<slug>` endpoint the installation has defined (its own OpenAI-compatible URL +
key). Custom endpoints are created in the dashboard, are BYOK-only, and must be https
and publicly reachable — private and loopback addresses are refused, and so is any port but 443 (a deployed Worker would drop it silently). To put your own [Headroom](https://github.com/headroomlabs-ai/headroom) proxy in front of review agents this way, follow https://wrok.in/docs/headroom.
Each custom model's picker card shows whether it is serving or refused (HTTP 404) for
your key, from what real calls answered; an untried model shows "not checked", and a
click sends one tiny request to find out — nothing is probed in the background. NVIDIA's free hosted API
(`https://integrate.api.nvidia.com/v1`) works as a custom endpoint, but its trial terms
permit training on submitted content and exclude production use — public repos and
evaluation only.

`meta` is Meta's own API (`api.meta.ai`), which serves the **Muse** family — it serves no
Llama model, and has not since the hosted Llama API was retired on 2026-07-06. For Llama
weights, name a host: `openrouter` with a `meta-llama/…` id.

Key custody is deliberately a human decision — do not ask for the key yourself; on
path B the human gives the token *and* the key material to you deliberately, once.

**Verify:** you can't read keys back (by design; `GET /api/setup/state` shows
`configured` + a last-4 hint). Verification happens at step 4: a missing key
produces a **self-diagnosing comment** on the first PR ("…no `<provider>` API key
is configured", with both fix paths — the dashboard URL and the setup-token
route), so a wrong setup tells you what to fix.

### 2a. The setup API (token-authed)

All calls: `Authorization: Bearer wst_…` against `https://api.wrok.in`. The token
lives **60 minutes**, is shown exactly once at mint, and holds the scopes `read`,
`agents:write` and `keys:write`. Each call runs the same operation the dashboard runs
(listed in [capabilities.json](https://wrok.in/capabilities.json) → `operations`), so
the validation and its error messages are identical. `{provider}` may be one of ours
or a `custom:<slug>` endpoint the installation has defined.

| Call | Effect |
|---|---|
| `GET /api/setup/state` | Installation id, per-provider key coverage (`configured` + hint), custom endpoints included — never key material |
| `PUT /api/setup/keys/{provider}` body `{"apiKey": "…"}` | Store/rotate a BYOK key (encrypted at rest) |
| `GET /api/setup/repos/{owner}/{repo}/agents` | The repo's effective agents (id, role, model, enabled) |
| `PATCH /api/setup/repos/{owner}/{repo}/agents/{agentId}` | Configure behavior: `enabled`, `provider`, `modelName`, `events`, `paths`, `thinking` (`"default"` or `"off"`), `reviewGuide` (`"off"`, `"map"` or `"ai"`), `reviewGuideMinCoreLines` (integer 0–100000), `claimCheck` (`"on"` or `"off"`) |
| `GET /api/setup/audit?limit=&before=` | The audit log, newest first: who changed what, through which interface and token (`nextBefore` pages on) |
| `DELETE /api/setup/token` | Revoke the token — call it when you finish |

Boundaries an agent should know up front: identity fields (`name`, `avatarUrl`,
`customInstructions`) and `billing` are **refused with a 403 naming the field and the
scope it needs** (`identity`, `billing`) — a setup token configures behavior, never
identity or spend (same rule as `.wrokin/config.yml`). A
`provider` switch without its key in the vault is a **409 naming the fix**
(`PUT /api/setup/keys/{provider}` first). A repo outside the installation is a
404, and so is an agent id that is not that repo's own. Revoke the token as your last call; expiry covers you if you forget.
### 2b. API tokens (`wrk_…`, long-lived)

A human creates one in the dashboard (Keys → "API tokens") with a **name**, a set of
**scopes** and an **expiry** of 7, 30, 90 or 365 days (no "never"). It drives the same
`/api/setup/*` calls as §2a with `Authorization: Bearer wrk_…`, holding exactly the scopes
chosen:

| Scope | Lets you |
|---|---|
| `read` | `GET /api/setup/state`, `GET …/agents`, `GET /api/setup/audit` |
| `agents:write` | `PATCH …/agents/{agentId}` behavior fields |
| `keys:write` | `PUT /api/setup/keys/{provider}` |
| `identity` | also set `name`, `avatarUrl`, `customInstructions` |
| `billing` | also set `billing` (`"byok"` or `"managed"`) |

`GET /api/setup/state` returns `scopes`, so you can tell your human which one to add
rather than guessing. A call needing a scope the token lacks is a 403 naming it. Only
a hash is stored, the value is shown once, an installation holds at most 25, and a
token can never create another token. An expired or revoked token is a 401 that says
to create a new one. `DELETE /api/setup/token` revokes it.

Every change you make is in the installation's **audit log**, shown to your human in the
dashboard (Keys → Audit log) and readable at `GET /api/setup/audit`: when, who, the
interface (`api` for you), **which token** by name, the action (an operation name such as
`agents.configure`) and the field-level `from`/`to` of each change. Reads and refused
calls are not recorded. Key values never are: `keys.set` records the provider, whether
it was set or rotated, and the last-4 hint, and `projectsToken.set` the same for the
GitHub Projects token. Rows are kept 365 days.

`thinking: "off"` turns the model's thinking channel off for every call that agent
makes. It binds on DeepSeek's own API, direct or through Cruise; other models,
Workers AI's DeepSeek included, ignore it. Use it when a reasoning model spends its
output budget thinking and posts nothing. It is not settable from `.wrokin/config.yml`.

`reviewGuide` controls the reading aid on a review. `"map"` (the default) adds a
collapsed **Review map** to the first part of the review: changed files grouped as
core, tests, config & assets, docs and generated, core first, with a core-only line
count, a link to each file's diff, and which part of a split review covered it. It is
deterministic and costs nothing. `"ai"` adds the map and, on code-review runs, asks the
model for guide sections: the change split into sections in reading order, core first,
each saying what it is and what it affects, with the findings listed under the section
they belong to. Sections cost output tokens, so they are requested only when the diff
has at least `reviewGuideMinCoreLines` changed core lines (default 400) or the review
is split into parts. `"off"` removes both. Not settable from `.wrokin/config.yml`.

`claimCheck` (code-review and security-audit; default `"on"`) checks each finding
against the code before the review posts. It reads the code the finding depends on at
the PR head (the cited file, files it names, and callers or importers that mention what
it names), plus the cited code at the PR's base, and asks the model whether the claim
still holds. A finding the code contradicts is withdrawn, one it half-supports is
narrowed one severity lower, and one the base already had is tagged pre-existing; the
review says how many. A high-severity finding is never withdrawn. It's shown as medium
when the check cites a line that contradicts it (with a "disputed" note naming the line),
supports only part of it, or shows the base already had it. It costs one extra short model call per review
part with findings. `"off"` posts findings as the reviewer wrote them. Not settable
from `.wrokin/config.yml`. The same setting governs the `/w wrong` re-check: with it on,
a correction is checked against the code the review read and the ack says whether the
code confirmed it (see w-commands.md); with it off, a correction is only recorded.

### 2c. Every operation: REST `/api/v1` and the MCP server

Each operation in [capabilities.json](https://wrok.in/capabilities.json) → `operations`
is also reachable **by name**, with the same validation, scopes, error messages and
audit log as the dashboard. Use a `wrk_` token (§2b) or a setup token (§2a).

| Call | Effect |
|---|---|
| `GET /api/v1/operations` | What you may run: each operation's `name`, `summary`, `tier`, `scope` and input JSON Schema, plus your token's `scopes` |
| `POST /api/v1/operations/{name}` body = its input | Run it, e.g. `POST /api/v1/operations/agents.configure` with `{"owner":"…","repo":"…","agentId":"…","enabled":false}`. An unknown name is a 404 that lists the real ones |

To **add an agent** to a repo, read `agents.catalog` first: the templates with their
default model, events and paths, the providers, and the models this installation can
pick (live Cruise lanes and its own custom endpoints included, with each role's sizing).
Then call `agents.create` with `owner`, `repo`, `templateId` (one of the catalog's
templates) and `provider`, which
must already have a key (a `409` names the call that adds it). `modelName`, `events`
and `paths` default to the template's, and `enabled` to `true`; the run settings
(`thinking`, `reviewGuide`, …) are the ones `agents.configure` takes. As there,
`name`, `avatarUrl` and `customInstructions` need the `identity` scope and `billing`
the `billing` scope; without `name` the agent gets the template's label.
**Removing** one, `agents.delete`, is `confirm` tier: it is listed, but outside the
dashboard it is refused with a link for your human to do it there. To stop an agent,
use `agents.configure` with `enabled: false`, which is reversible.

To see **what wrokin did**, read `runs.list` (recent runs: agent, PR or issue, model,
status and error), `runs.summary` (total/ok/failed over the last 1–90 days with a daily
series; take counts from here, not by counting a `runs.list` page, which is capped at
200) and `findings.list` (Security Hunter findings, filterable by `status`). All three
take an optional `owner` + `repo` to narrow to one repo and need only the `read` scope.
`runs.context` with a run's `deliveryId` shows what Scout read before that review: the
ranked file excerpts, the guidance docs and what it pruned. Bundles are kept 7 days, and
a run Scout did not gather for is a `404`.

When **a PR got no review**, call `reviews.diagnose` with `owner`, `repo` and `pr`. It
replays the PR through the gates an automatic review passes, in order (`pr_open`,
`author`, `skip_label`, `paused`, `quota`, `review_agents`), and returns each with
`passed` and a `detail`, plus `blockedBy` (the first that failed), a per-agent `verdict`
for the next push (`will_review`, `reviewed_this_commit`, `failed_this_commit`,
`disabled`, `not_on_pull_requests`, `no_key`, `managed_refused`) and the PR's last 10
runs. It
judges the PR as it is now: a past rate-limit hit is not recorded, but a past failure
shows in the runs.

A bot's PR (Dependabot, Renovate, Sentry) fails the `author` gate unless the repo trusts
that bot. `reviews.settings` reads the repo's `trustedBotAuthors`, and
`reviews.configure` replaces the whole list (`["dependabot"]` and `["dependabot[bot]"]`
mean the same; `[]` trusts none). Every review it lets through spends tokens, so it
needs `agents:write`.

For a repo's **posture** (Warden: branch protection, pinned actions, community files and
more), `posture.get` returns the latest scan with every check's `tier`, `status`,
`evidence` and `remediation`; `scan` is `null` if the repo was never scanned.
`posture.scans` lists past scans with their counts, newest first, to show drift.
`posture.scan` queues a fresh scan (`agents:write`). It is not inline: read
`posture.get` again in a minute. A repeat within 90 seconds answers
`{ "queued": false, "debounced": true }`. `posture.settings` and `posture.configure`
read and set `reportAsIssues`, which files the report as a tracked GitHub issue on the
repo.

For **spend**, `billing.status` returns the plan, this month's run quota (`entitlement`:
used and limit, monthly and daily) and the managed-agent credit balance (`agentCredits`:
bundle, used, purchased, remaining). It needs only the `read` scope. Buying credits
or changing plan stays in the dashboard. `billing.cancel` (the `billing` scope) cancels
the subscription at the end of the paid period; it is confirm tier, so it is listed and
refused outside the dashboard.

If an operation fails on our side (GitHub or our database briefly unavailable), REST
answers `503` with `{ "error", "ref" }` and MCP returns a tool error with the same text.
Retry it shortly; quote the `ref` if you report it.

**MCP:** `https://api.wrok.in/mcp` (Streamable HTTP, stateless JSON over POST). Tools are
the operations, with dots as underscores (`agents.configure` → `agents_configure`), and
the names are stable. Protocol revisions: **2026-07-28** (no handshake: send the version
and client capabilities in each request's `_meta`, with matching `MCP-Protocol-Version`,
`Mcp-Method` and, on `tools/call`, `Mcp-Name` headers; `server/discover` lists what we
speak), and 2025-11-25, 2025-06-18, 2025-03-26 and 2024-11-05 through `initialize`.
A browser page may call only from `wrok.in`, `app.wrok.in` or localhost; any other `Origin` gets `403`.

**Connect with OAuth (no token to copy).** Add the server with no header and the host
signs in: `/mcp` answers `401` with an RFC 9728 challenge, the host discovers the
authorization server (issuer `https://api.wrok.in`), and your human lands on
`https://app.wrok.in/oauth/consent`. There they pick **one installation** and the scopes;
`read` is always granted, everything else starts unticked, and `keys:write` is never on
offer. The page names the GitHub account approving, which is whoever is signed in at
github.com; switch there first to approve as someone else. Access tokens last 1 hour and
refresh for 30 days. The human can disconnect the app any time under Keys → Connected apps,
and if they lose access to the installation, the app is disconnected at its next refresh. For Claude Code:

```bash
claude mcp add --transport http wrokin https://api.wrok.in/mcp
```

**Or pass a token as a header**, for a host without OAuth or a headless agent:

```bash
claude mcp add --transport http wrokin https://api.wrok.in/mcp --header "Authorization: Bearer wrk_…"
```

or in a host's JSON config:

```json
{ "mcpServers": { "wrokin": { "type": "http", "url": "https://api.wrok.in/mcp",
  "headers": { "Authorization": "Bearer wrk_…" } } } }
```

Over MCP, an operation's error (a missing scope, a bad field) comes back as a tool
result with `isError: true` and the same message, so you can fix the next call.
**`keys_set` and `projectsToken_set` are never offered over MCP**, because a key must
not pass through a model's transcript: set keys with `PUT /api/setup/keys/{provider}`,
`POST /api/v1/operations/keys.set` (or `projectsToken.set`), or the dashboard.
Operations a human must confirm (`agents.delete`, `keys.delete`,
`projectsToken.delete`, `customProviders.delete`, `billing.cancel`, and `hunter.enable` /
`builder.enable`, which open a PR adding a workflow to your repo) are listed and refused with a
dashboard link. So is **changing `baseUrl` on a custom provider that holds a key**:
the URL is where that key is sent, so only a human may move it. And so is **turning
Builder auto-merge on** (`builder.configure {autoMerge: true}`): it lets a green Builder
PR merge with no human review; turning it off works anywhere. A `baseUrl` set on a keyless
provider from here (on create or configure) stays **unconfirmed** until a human confirms it
in the dashboard. Until then, `keys.set` for that provider needs the URL repeated as
`confirmBaseUrl`, and the dashboard asks whoever adds the key to tick a box that names the
URL. Changes show in the audit log
as `mcp` or `api`, under your token's name (or the connected app's).

Note: **Warden (`repo-audit`) needs no key** — its checks are deterministic code, not model calls. It works from step 1 alone.

## 3. Configure as code

Commit `.wrokin/config.yml` (also honored: `.wrokin/config.yaml`, `.pi/config.yml`). It is a **sparse override** of the dashboard settings — only the fields you write change anything; absent fields keep their stored values. Validate against the JSON Schema first: https://wrok.in/config.schema.json

```yaml
version: 1
agents:
  code-review:
    enabled: true
    model: { provider: anthropic, name: claude-sonnet-5 }
    on: [pull_request]
  security-audit:
    enabled: true
    model: { provider: deepseek, name: deepseek-v4-flash }
  issue-triage:
    enabled: true
    model: { provider: mistral, name: codestral-latest }
architecture:
  audit: auto   # platform-architecture audit: auto (detected) | on | off
```

**Platform-architecture audit** (code review): every *new* Cloud Function, Cloudflare Worker, Firestore collection/sub-collection, or Storage path a PR proposes is judged against the repo's existing ones — extend-existing by default, so a project does not drift to 50+ functions where 15–20 would do. It also asks whether uploaded images ship size variants and whether a new dependency-free module should be a publishable package. It is **detected, not assumed**: on for Firebase when the repo has `firebase.json` / `firestore.rules` / `storage.rules` / a `functions/` entry, on for Cloudflare when it has a `wrangler.toml|json|jsonc`, silent otherwise. `architecture.audit: on` forces it, `off` silences it.

Field reference (per role under `agents.<role>`):

| Field | Type | Meaning |
|---|---|---|
| `enabled` | boolean | Turn the agent on/off for this repo |
| `model` | `{provider, name}` | Provider must be one of the eleven listed above (or a `custom:<slug>` the installation defined); `name` is any model id the key can call — for Cruise, a `bb/…` lane id is usual |
| `on` | string list | Trigger events; `pull_request` and `issues` are what the roles use |
| `paths` | string list | Accepted and stored, but **dispatch filtering by path is not enforced yet** — do not rely on it to exclude files |

Valid roles: `code-review`, `security-audit`, `issue-triage`, `repo-audit`, `project-management`. Persona/custom instructions are **not settable from the file** — they are owner-controlled in the dashboard, so a config commit can never rewrite an agent's identity.

Invalid entries are ignored and the rest of the file still applies — the file fails **open** to stored settings. There is no error channel back to the committer, which is why validating against the schema *before* committing matters.

## 4. Verify end to end

Open a small pull request (any real change). **Expected:** within a couple of minutes, `wrokin[bot]` posts a review comment for each PR-enabled agent, headed `🤖 wrokin — Code Review` (and `— Security Audit` if enabled), with `file:line` findings.

- Comment appears but says **no API key configured** → step 2 is incomplete; the comment names the provider and links to the exact screen that fixes it. Exception: on a public repo where free OSS reviewed the PR, other keyless agents post nothing on automatic runs; `reviews.diagnose` still reports them as `no_key`.
- No comment at all → confirm the app is installed on **this** repo (step 1), the PR author has repo write access (see §6), and the agent is `enabled` (step 3).
- Comment appears but says the agent **couldn't complete** → it carries a failure code and a run ref, like `LlmError:429:wallet_exhausted · ref 8f3c…`. The code is a link to https://wrok.in/docs/errors, which says for every code what was refused, what changes it, and what does not. **Read that before retrying**: several of these codes cannot be cleared by waiting or re-running, so a retry loop just spends time. An unrecognised code is published as its bare status (`LlmError:403`) and links to that status's section.

## 5. Operate by comment

All commands work in PR/issue comments. Bare `@wrokin` or `/w` also works: review on a PR, triage on an issue.

| Command | Where | Effect |
|---|---|---|
| `/w review` | PR | Code review of the diff |
| `/w security audit` | PR | Security-focused diff review |
| `/w triage` | issue | Structured triage (labels, priority, duplicate) |
| `/w audit` (or `/w posture`) | PR or issue | Warden repo-setup audit — deterministic, no key needed |
| `/w wrong [comment-link] <reason>` | PR | Report a wrokin review comment as a **false claim**, with your reason — link the comment to target it, or omit to mean the latest |

Full contract — gates (both silent on failure), precedence, per-command acknowledgements: https://wrok.in/w-commands.md

## 6. Who can trigger it

Agents run for repo **owners, members, and collaborators** only — on a public repo, a third party opening a PR or commenting cannot spend the installer's tokens or quota. If your PRs come from an outside account, have a member trigger the review with `/w review`.

Monthly run quotas per account: Free 150 · Pro 1,000 · Team 3,000 · Business 20,000. Plan changes and payment are a **HUMAN CHECKPOINT**: https://wrok.in/#pricing

**Free for open source:** on a **public** repo, a code-review agent with **no key** runs on wrokin's key on a Cruise open-source lane (`oss/…`) instead of asking for one. It runs automatically on PRs from owners, members and collaborators, and on any other PR when one of them comments `/w review`. Limits: one free review per account every 45 minutes (one event's agents share it), diffs up to 200 KB, and a global daily budget; when that is spent, free reviews pause until 00:00 UTC. Each counts toward the plan's monthly runs. A saved key always wins; private repos and custom endpoints are never sponsored. On such a repo, any other agent with no key stays quiet on automatic runs (no "add your key" comment beside the free review; the run is still recorded as `no_key`), and still answers when asked by `/w` command. The lane's model may train on what it is sent (today: Meta's Muse Spark contributor tier), which is acceptable for public code only. Footer: `free for open source · wrokin's key, wrokin's lane (sponsored)`, then a short closing note with the wrok.in logo and install link (once per review, on its last part). A review refused by a limit says why and when the next one is free.

## 7. Give quality feedback

wrokin measures whether its reviews were *right*, per model — help it:

- React **👍/👎** on a review comment (recorded when the PR closes; collaborators only).
- Reply **`/w wrong <comment-link> <reason>`** when a review asserts something false — paste the comment's link (Copy link) to pin the verdict on it; without a link it binds to the latest wrokin review comment. wrokin's inline review comments (`#discussion_r…` on GitHub, `#note_…` on GitLab) can be targeted too: they come from the deterministic diff scan, not a model, so the verdict is recorded against the scan (`wrokin/grounding`) and no model's record changes. The reason is the valuable part. wrokin confirms which comment the verdict attached to.

This feeds per-model quality metrics that decide which models stay in the pool — published, anonymized, at https://api.wrok.in/quality (counts only: findings, rework rate, verdict tallies per provider×model; no repos, no actors). A model is credited for what it actually answered — where a request is routed to a pool, the member that served it, not the pool.

## 8. Data handling (what leaves where)

- The diff and bounded repo context go to **the installer's chosen model provider under the installer's key** for the review call — that is the BYOK deal. Exception the OWNER can opt into per role (dashboard only: not the setup API, not the committed config file): `billing: managed` runs that role on wrokin's key and model for the role, debiting agent credits per run.
- Exception on **public** repos only: with no key set, a code review may run free on wrokin's key on a Cruise `oss/…` lane, whose model may train on what it is sent (today: Meta's Muse Spark contributor tier). Private repos never take this path; setting a key opts out. https://wrok.in/data-handling.html#free-oss
- wrokin's own telemetry stores finding **locations** (file/line/severity) and outcomes (was the line later changed; 👍/👎; false-claim verdicts) — **not** the prose of findings and **not** your code.
- Review output is posted as PR/issue comments in your repo, where it is yours.
- The dashboard's Workflow runs page caches GitHub Actions run metadata (repo, workflow, branch, status, actor, the run's title — usually a commit message's first line) for up to 5 minutes, then it expires — never logs, never code.

Details: https://wrok.in/privacy.html · https://wrok.in/dpa.html

## 9. Roles that run on your own runner

### `hunter` — the Verified Security Hunter (paid plans)

Proof-by-execution security scanning on wrokin's managed model keys. Debits the shared agent-credits pool.

1. **Plan** — Pro, Team, or Business (Free has a zero credit bundle).
2. **Enable** — one click in the dashboard (or `POST /api/installations/{id}/repos/{owner}/{repo}/hunter/enable`). That opens a setup PR adding `.github/workflows/wrokin-hunter.yml`; **a human merges it**.
3. **Run** — comment `/w hunter [foray|stakeout|expedition]` on a **PR** (default `stakeout`). Entitlement and credits are checked before dispatch.

Command contract: https://wrok.in/w-commands.md

### `builder` — the Builder (on demand only)

Implements an issue on **your own GitHub Actions runner**: pi works on it, calling Cruise with **your** Cruise key, then the action runs your tests itself — a ready pull request when they pass, a draft marked *not proven* when they fail or there are none. It debits no agent credits.

**Not included in catalog plans or agent-credit bundles.** On demand only — customised and tailored for specific projects, use cases and guardrails. Contact the wrokin team if you need it (`contact@bytesbrains.com`). Do not plan a self-serve integration around enabling it from the dashboard.

When enabled for an engagement:

1. **Enable** — a setup PR adds `.github/workflows/wrokin-agent-build.yml`; **a human merges it**.
2. **Run** — comment `/w build` on an **issue** (the issue text and its human comments are the task).
3. **Reviewed like any PR** — the Builder's PR (author `wrokin[bot]`, branch `wrokin/builder/…`) gets your enabled review and security agents automatically, with no trusted-bot entry needed; the `skip-bot-review` label still opts it out.
4. **Auto-merge is off** — a Builder PR is a pull request unless the repo explicitly opts in *and* the engagement includes auto-merge, *and* the change is proven green (the action's own proof-run passed and the run wasn't cut off), *and* your own CI passes, *and* GitHub reports it mergeable.

### Bringing an existing Hunter or Builder workflow up to date

Enable writes the workflow once. While `.github/workflows/wrokin-hunter.yml` or `wrokin-agent-build.yml` is on the default branch the agent counts as enabled, and **Enable again changes nothing**, so wrok.in never rewrites the file on its own. Files generated before v0.9.6 pin `actions/checkout` by tag (`@v4`, or whatever Dependabot moved it to), which GitHub's **Require actions to be pinned to a full-length commit SHA** policy refuses to start. To fix it, either:

- **Pin the one line** (keeps every edit you made): `- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1`, or the SHA of whichever release you are on; or
- **Regenerate it**: delete the workflow file on the default branch, then Enable again and merge the new setup PR. Hand edits to the old file are lost.

**How a run works (`actions/wrokin-agent`).** pi runs on your runner and calls Cruise directly with **your** Cruise key. Save the key and the lane on the repo's **Builder card**; the workflow needs `permissions: id-token: write`. At job start the action sends its GitHub OIDC token (audience `wrokin-agent`) to `POST https://api.wrok.in/agent/checkin` and gets back `{ cruise_api_key, model, cruise_base_url, read_cap_kb, base_branch, compress_tool_output, thinking, github_token, github_token_expires_at }`; both secrets are masked in the log. The run calls wrok.in once more only if it opens a **ready** PR: `POST https://api.wrok.in/agent/verified` with a fresh OIDC token, the PR number and its head sha. Auto-merge requires that record for the PR's current head, so a hand-edited PR body or a later push doesn't merge (#893). `github_token` is a wrokin App installation token for **this one repository** with `contents`, `pull_requests` and `issues` write — never `workflows` — so the action reads the issue, pushes, opens the PR and comments as `wrokin[bot]`: no "Allow GitHub Actions to create and approve pull requests" setting, and your own CI runs on the PR. The action revokes it at job end and pi never holds it: pi runs as a separate, unprivileged OS user, so it can't read the action's environment either. The runner needs Linux and passwordless `sudo` (GitHub-hosted runners have both); without them the Builder refuses to run and says why on the issue. Changing the lane on the card changes the next run's model, no YAML edit. The card's **whole-file read cap** (`read_cap_kb`: KB, `0` = off, default 24) works the same way: a whole-file read over it is cut at a line boundary with a note saying where to continue; a `read_cap_kb` input in the workflow overrides it. The card's **base branch** (`base_branch`, `null` = automatic) is where the run starts and what its PR targets; left automatic, the run uses what the repo's `AGENTS.md`/`CLAUDE.md`/`CONTRIBUTING.md` say PRs target, else the branch recent merged feature PRs target, else the default branch; a `base_branch` input in the workflow overrides it. The card's **tool output compression** (`compress_tool_output`, `null` = default on) compresses repetitive bash, grep and find results; a `compress_tool_output` input in the workflow overrides it. The card's **model thinking** (`thinking`, `'default'` = default off on lanes and DeepSeek, `'off'` = off, `'on'` = on) controls the reasoning channel; a `thinking` input in the workflow overrides it. Refusals: `401` token didn't verify, `402` plan excludes the Builder, `403` not installed or the installation lacks one of the three permissions (named — re-authorize the app), `409` "add a Cruise key on the Builder card", `502` the GitHub token couldn't be minted (all posted on the issue). Passing a `cruise_api_key` input skips wrok.in entirely and uses the job's `GITHUB_TOKEN`, which needs `contents`/`pull-requests`/`issues: write` and the repo setting above.

Command contract: https://wrok.in/w-commands.md

## 10. Uninstall

GitHub → Settings → Applications → wrokin → Uninstall (human action). Committed `.wrokin/config.yml` is inert without the app; keys are removed in the dashboard.

---

*Machine-readable summary: https://wrok.in/llms.txt · Capability manifest: https://wrok.in/capabilities.json · Command contract: https://wrok.in/w-commands.md · Config schema: https://wrok.in/config.schema.json*
