# 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. 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

**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).

Supported providers: `anthropic`, `openai`, `deepseek`, `google`, `mistral`, `openrouter`, `moonshot`, `groq`, `cruise`.

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 is scoped to setup only.

| Call | Effect |
|---|---|
| `GET /api/setup/state` | Installation id, per-provider key coverage (`configured` + hint) — 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` |
| `DELETE /api/setup/token` | Revoke the token — call it when you finish |

Boundaries an agent should know up front: identity fields (`name`, `avatarUrl`,
`customInstructions`) are **refused with a 403 naming the field** — a setup token
configures behavior, never identity (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. Revoke the token as your last call; expiry covers you if you forget.

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 eight above; `name` is any model id the key can call |
| `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 the fix.
- 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).

## 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

## 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. 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).

## 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.
- 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.

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

## 9. Roles that run on your own runner

### `builder` — the Verified Builder (paid plans)

Implements an issue and **proves the change green on your own GitHub Actions runner** before proposing it: a ready pull request when your build and tests pass, a draft clearly marked *unproven* when they don't, and at `patch` an unproven change is dropped rather than opened. Reasoning, prompts, model choice and keys stay on wrokin's servers — this is the one role that does **not** use your BYOK key, and it debits agent credits.

To plan an integration around it:

1. **Plan** — requires Pro, Team or Business. On a plan without it, check-in refuses with a reason naming the plan.
2. **Enable** — one click in the dashboard (or `POST /api/installations/{id}/repos/{owner}/{repo}/builder/enable`). That opens a setup PR adding `.github/workflows/wrokin-builder.yml`; **a human merges it** — GitHub will not run a workflow that isn't committed to the repo.
3. **Run** — comment `/w build [patch|feature|expedition]` on an **issue** (the issue text is the task; default level `patch`). Entitlement and credits are checked before dispatch, so a refused build costs you no Actions minutes.
4. **Auto-merge is off** — a Builder PR is a pull request unless the repo explicitly opts in *and* the plan includes auto-merge, *and* the change is proven green, *and* your own CI passes, *and* GitHub reports it mergeable.

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

### Not to plan around (private preview)

`hunter` (proof-by-execution security scanning) exists but is **invite-only and cannot be enabled by customers today**. Do not include it in an integration plan; watch https://wrok.in for availability.

## 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*