ravensight-playtest 0.1.0

package/addons/ravensight_driver/export_plugin.gd

@@ -0,0 +1,51 @@
+# Keeps the driver out of builds that ship to players.
+#
+# The driver already refuses to start in an export template that lacks the
+# "ravensight_driver" feature tag, but a refusing-to-start TCP server is still
+# a TCP server sitting in the binary. This skips the whole addon at export
+# time unless the preset was built with that tag, so the usual release export
+# contains no driver code at all.
+#
+# One file does not simply vanish. A developer who installs the addon in their
+# own project gets the autoload written into project.godot, and project.godot
+# ships in the export. Removing driver.gd outright would leave that autoload
+# pointing at a file that is not there, and the exported game would greet the
+# player with a load error before its first frame. So driver.gd's path keeps a
+# script: a stub that frees itself and does nothing else. Every other file in
+# the addon, this plugin included, is dropped.
+@tool
+extends EditorExportPlugin
+
+const FEATURE_TAG := "ravensight_driver"
+const ADDON_PREFIX := "res://addons/ravensight_driver/"
+const DRIVER_PATH := "res://addons/ravensight_driver/driver.gd"
+
+const INERT_STUB := """extends Node
+
+# The Ravensight playtest driver was stripped from this export. This stub only
+# exists so a self-installed autoload entry still resolves to a real script.
+func _ready() -> void:
+	queue_free()
+"""
+
+var _keep := false
+
+
+func _get_name() -> String:
+	return "RavensightDriverStrip"
+
+
+func _export_begin(features: PackedStringArray, _is_debug: bool, _path: String, _flags: int) -> void:
+	_keep = FEATURE_TAG in features
+	if not _keep:
+		print("[ravensight-driver] stripping the playtest driver from this export")
+
+
+func _export_file(path: String, _type: String, _features: PackedStringArray) -> void:
+	if _keep:
+		return
+	if not path.begins_with(ADDON_PREFIX):
+		return
+	skip()
+	if path == DRIVER_PATH:
+		add_file(path, INERT_STUB.to_utf8_buffer(), false)

package/addons/ravensight_driver/plugin.cfg

@@ -0,0 +1,7 @@
+[plugin]
+
+name="Ravensight Playtest Driver"
+description="Opt-in JSON-RPC driver that lets Ravensight playtest personas observe and control a running Godot game. Inert unless launched with --ravensight-driver or RAVENSIGHT_DRIVER=1, binds 127.0.0.1 only, and is stripped from any export not built with the ravensight_driver feature tag."
+author="Ravensight"
+version="1.0.0"
+script="plugin.gd"

package/addons/ravensight_driver/plugin.gd

@@ -0,0 +1,36 @@
+# Editor side of the Ravensight Playtest driver.
+#
+# Two jobs, both about making sure the driver cannot reach players:
+#   1. Register (and unregister) the driver autoload, for developers who
+#      install the addon in their own project rather than letting the CLI
+#      inject it into a temporary copy.
+#   2. Install an export plugin that strips addons/ravensight_driver/ out of
+#      every export that was not deliberately built with the custom feature
+#      tag "ravensight_driver". A release build therefore does not merely
+#      refuse to start the driver, it does not contain it.
+@tool
+extends EditorPlugin
+
+const AUTOLOAD_NAME := "RavensightDriver"
+const AUTOLOAD_PATH := "res://addons/ravensight_driver/driver.gd"
+
+var _export_plugin: EditorExportPlugin
+
+
+func _enter_tree() -> void:
+	_export_plugin = preload("res://addons/ravensight_driver/export_plugin.gd").new()
+	add_export_plugin(_export_plugin)
+
+
+func _exit_tree() -> void:
+	if _export_plugin != null:
+		remove_export_plugin(_export_plugin)
+		_export_plugin = null
+
+
+func _enable_plugin() -> void:
+	add_autoload_singleton(AUTOLOAD_NAME, AUTOLOAD_PATH)
+
+
+func _disable_plugin() -> void:
+	remove_autoload_singleton(AUTOLOAD_NAME)

package/bin/ravensight-playtest.js

@@ -0,0 +1,31 @@
+#!/usr/bin/env node
+/**
+ * The only place this package calls `process.exit`.
+ *
+ * Every command answers an exit code instead of exiting, so the whole CLI can
+ * be driven from a test without taking the test process down with it. This file
+ * is the one boundary where a code becomes an exit, and the one place an
+ * unhandled rejection is turned into a message rather than a Node warning.
+ */
+import { main, report } from '../src/cli.js';
+
+const NODE_MIN_MAJOR = 22;
+const major = Number(process.versions.node.split('.')[0]);
+if (Number.isFinite(major) && major < NODE_MIN_MAJOR) {
+  process.stderr.write(
+    `ravensight-playtest needs Node ${NODE_MIN_MAJOR} or newer, and this is v${process.versions.node}.\n`
+  );
+  process.exit(3);
+}
+
+process.on('unhandledRejection', error => {
+  process.exitCode = report(error);
+});
+
+main(process.argv)
+  .then(code => {
+    process.exitCode = code;
+  })
+  .catch(error => {
+    process.exitCode = report(error);
+  });

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "ravensight-playtest",
+  "version": "0.1.0",
+  "description": "AI personas play your game and file reports to Ravensight.",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "ravensight-playtest": "bin/ravensight-playtest.js"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "files": [
+    "bin",
+    "src",
+    "addons",
+    "README.md",
+    "LICENSE",
+    "!src/**/*.test.js",
+    "!src/test-helpers",
+    "!src/run/__helpers__",
+    "!src/run/drivers/testing",
+    "!test"
+  ],
+  "exports": {
+    ".": "./src/api/index.js",
+    "./api": "./src/api/index.js"
+  },
+  "scripts": {
+    "test": "node --test --test-reporter=spec 'src/**/!(godot-real|web.e2e).test.js'",
+    "test:godot": "node --test --test-reporter=spec src/run/drivers/godot-real.test.js",
+    "test:e2e": "node --test --test-reporter=spec src/run/drivers/web.e2e.test.js",
+    "lint": "node scripts/no-dashes.mjs"
+  },
+  "dependencies": {
+    "@anthropic-ai/sdk": "^0.60.0",
+    "ajv": "^8.17.1",
+    "ajv-formats": "^3.0.1",
+    "commander": "^13.0.0"
+  },
+  "optionalDependencies": {
+    "keytar": "^7.9.0",
+    "playwright": "^1.49.0"
+  }
+}

package/src/api/README.md

@@ -0,0 +1,500 @@
+# The runner-facing interface
+
+Everything `src/run/*` (cli-runner) and `src/run/drivers/godot.js` (cli-godot)
+are allowed to import lives behind one module:
+
+```js
+import { createClient, uploadRunDir, packs } from '../api/index.js';
+```
+
+Nothing else in `src/` is a contract. `src/api/http.js`, `src/auth/*`,
+`src/upload/queue.js` and the command modules are implementation detail and
+may change without notice. If you need something that is not listed here,
+ask for it to be added to `src/api/index.js` rather than reaching past it.
+
+The barrel is also the package's public entry point (`exports` in
+`package.json`), so an external consumer sees exactly this surface.
+
+## Contents
+
+| Export | What it is |
+|---|---|
+| `createClient(options)` | the Ravensight API client |
+| `ApiError`, `isRetryable(error)`, `codeRetryLimit(error)` | the error envelope, and whether a retry could help |
+| `resolveApiUrl()`, `resolveToken(options)` | where the API is, and the credential to use |
+| `handleUnauthorized`, `withAuthHandling` | the one 401 handler every command funnels through |
+| `createContext(options)` | resolve config plus credential plus client in one call |
+| `loadConfig(options)`, `saveConfig(config, options)` | `<repo>/.ravensight/config.json` |
+| `packs` | pack cache: `packs.get()`, `packs.sync()`, `packs.cached()` |
+| `uploadRunDir(runDir, options)` | presign, PUT, record; one run directory |
+| `finalizeRun(runDir, options)` | `uploadRunDir` plus `complete`, with the 422 repair pass |
+| `readState`, `writeState`, `updateState`, `stateFileFor` | the resumable job journal |
+| `paths` | every directory and file this CLI writes |
+| `ui` | spinner, table, status lines, confirmation prompt |
+| `CLI_VERSION`, `compareVersions` | this package's version, sent as `cli_version` |
+| `ExitCode`, `CliError` | the spec 17 exit codes, and the error that carries one |
+| state lists | `MODULES`, `DRIVERS`, `RUN_STATES`, `RUN_TERMINAL_STATES`, `RUN_TRANSITIONS`, `isRunTerminal`, `canTransitionRun`, and the job equivalents |
+| link helpers | `dashboardUrl`, `gameLink`, `jobLink`, `reviewLink`, `briefLink`, `openInBrowser` |
+| `inspectGodot` | the Godot binary and project version, through cli-godot's own detection |
+| machine helpers | `recommendConcurrency`, `freeBytes`, `probe` |
+| allowlist | `contentTypeFor`, `isAllowedPath`, `JOB_UPLOAD_PATHS`, `RETENTION_TAGGED_PATHS`, the three size caps |
+| file helpers | `sha256`, `sha256File`, `readJson`, `writeJson`, `writeFileAtomic`, `stableStringify` |
+
+## createClient
+
+```js
+const api = createClient({
+  apiUrl: 'https://api.ravensight.io',  // default resolveApiUrl()
+  token: 'gt_cli_...',                  // required for everything but cli.version()
+  cliVersion: CLI_VERSION,              // default CLI_VERSION
+  fetch: globalThis.fetch,              // injectable, for tests
+  retries: 4,                           // network and 5xx and 429 retries
+  timeoutMs: 30000,
+  onRetry: ({ attempt, delayMs, error }) => {}
+});
+```
+
+The client is stateless and cheap. Make one per process, or one per run if
+you want the per-run token on it.
+
+### Read-only properties
+
+`api.apiUrl`, `api.token`, `api.cliVersion`.
+
+### The escape hatch
+
+```js
+const { status, headers, body } = await api.request('POST', '/api/v1/...', {
+  query: { limit: 10 },
+  body: { ... },
+  headers: { 'Idempotency-Key': key },
+  idempotent: false,   // true lets a mutation be retried
+  raw: false           // true returns body as text, not JSON
+});
+```
+
+Every named method below is a thin wrapper over `request`. A non-2xx answer
+throws `ApiError`; nothing returns an error as a value.
+
+### api.cli
+
+| Call | Server route | Answers |
+|---|---|---|
+| `api.cli.version()` | `GET /api/v1/playtest/cli/version` | `{ min_supported, latest, schema_version }`. No token needed. |
+| `api.cli.deviceCode({ client, clientVersion })` | `POST /api/v1/playtest/cli/device-code` | `{ device_code, user_code, verification_uri, expires_in, interval }` |
+| `api.cli.pollToken(deviceCode)` | `POST /api/v1/playtest/cli/token` | `{ token, games, scopes, expires_at }`, or throws `ApiError` with code `authorization_pending` (428), `slow_down` (429), `expired_token` (400) or `access_denied` (403) |
+| `api.cli.whoami()` | `GET /api/v1/playtest/cli/whoami` | `{ user, orgs, games: [{ gameId, name }], scopes, available_cents }` |
+| `api.cli.revoke()` | `DELETE /api/v1/playtest/cli/token` | nothing (204) |
+
+### api.packs
+
+Every pack route is cacheable. Pass `etag` to get a 304 instead of a body.
+
+```js
+const { status, etag, body } = await api.packs.bundle({ gameId, modules, etag });
+// status 200 -> body is the bundle; status 304 -> body is null
+```
+
+`api.packs.manifest`, `api.packs.personas({ gameId, etag })`,
+`api.packs.skills({ modules, etag })`, `api.packs.schemas({ etag })`,
+`api.packs.routing({ etag })`, `api.packs.bundle({ gameId, modules, etag })`.
+
+Prefer `packs.get()` (below) over these: it does the caching for you.
+
+### api.brief
+
+All game-scoped, all under `/api/v1/games/:gameId/playtest`.
+
+| Call | Route |
+|---|---|
+| `api.brief.get(gameId)` | `GET /brief` -> `{ brief, rendered }` or `{ brief: null }` |
+| `api.brief.versions(gameId)` | `GET /brief/versions` |
+| `api.brief.version(gameId, version)` | `GET /brief/versions/:version` |
+| `api.brief.put(gameId, { fields, status, parentVersion })` | `PUT /brief` -> `{ brief, rendered }`; 409 `stale_version` carries `current_version` |
+| `api.brief.estimate(gameId, { modules, personas })` | `POST /brief/estimate` -> `{ estimate_cents, breakdown, balance_cents, ok, topup_url }` |
+| `api.brief.check(gameId, completeness)` | `POST /brief/check` -> `{ completeness }` |
+
+`balance_cents` and `ok` are `null` when the caller's role has no
+`billing:manage`. That is not an error; show the estimate without a verdict.
+
+### api.jobs
+
+| Call | Route |
+|---|---|
+| `api.jobs.estimate(gameId, { modules, personas })` | `POST /estimate`, same body as `brief.estimate` |
+| `api.jobs.register(gameId, body, { idempotencyKey })` | `POST /jobs` |
+| `api.jobs.list(gameId, query)` | `GET /jobs` -> `{ jobs, next_cursor }` |
+| `api.jobs.get(gameId, jobId)` | `GET /jobs/:jobId` -> `{ job }` |
+| `api.jobs.patch(gameId, jobId, { state, reason })` | `PATCH /jobs/:jobId` -> `{ job }` |
+| `api.jobs.cancel(gameId, jobId)` | `POST /jobs/:jobId/cancel` |
+| `api.jobs.finish(gameId, jobId, { state, reason })` | `POST /jobs/:jobId/finish` |
+| `api.jobs.remove(gameId, jobId)` | `DELETE /jobs/:jobId` |
+| `api.jobs.uploads(gameId, jobId, { files })` | `POST /jobs/:jobId/uploads`, job-level keys |
+| `api.jobs.capabilityReport(gameId, jobId, body)` | `POST /jobs/:jobId/capability-report` |
+| `api.jobs.aggregateComplete(gameId, jobId, body)` | `POST /jobs/:jobId/aggregate/complete` |
+| `api.jobs.artifacts(gameId, jobId)` | `GET /jobs/:jobId/artifacts` |
+| `api.jobs.report(gameId, jobId, format)` | `GET /jobs/:jobId/report?format=md\|json`, returns text |
+| `api.jobs.summary(gameId)` | `GET /summary` |
+| `api.jobs.findings(gameId, query)` | `GET /findings` |
+
+`register` takes the server's own spelling, so nothing is translated twice:
+
+```js
+await api.jobs.register(gameId, {
+  modules: ['persona_playtest'],        // required, non-empty
+  personas: ['rage-quitter'],           // required when modules has persona_playtest
+  driver: 'playwright_web',             // required
+  cli_version: api.cliVersion,          // required, added for you if omitted
+  confirm_price_cents: 800,             // required integer, from the estimate
+  build: { kind: 'url', ref: 'http://localhost:8080' },
+  repo: { commit: 'abc123', dirty: false },
+  max_actions: 120,
+  budget: { wall_seconds_max: 1800 },
+  pack_versions: { pack: '1.0.0' }
+}, { idempotencyKey });
+```
+
+`Idempotency-Key` is required by the server, so `register` throws
+`TypeError` locally rather than sending a request that cannot succeed. The
+call is marked idempotent, so a dropped response is retried and the server
+replays instead of charging twice.
+
+On success: `{ job_id, runs: [{ run_id, module, persona, playtest_token, budget_usd }], price: { price_cents, breakdown }, links: { dashboard }, replayed }`.
+
+Refusals worth handling by code:
+
+| Status | `error` | What it means |
+|---|---|---|
+| 400 | `idempotency_key_required`, `invalid_job` | fix the request |
+| 402 | `insufficient_balance` | carries `estimate_cents`, `balance_cents`, `shortfall_cents`, `topup_url` |
+| 409 | `price_changed` | carries the new `estimate_cents` and `breakdown`; re-confirm |
+| 409 | `brief_required` | finish the brief first |
+| 409 | `cli_outdated` | carries `min_version` |
+| 409 | `charge_in_progress` | unknown, not refused. Honor `Retry-After` and ask again |
+| 429 | `too_many_active_jobs` | carries `max_active_jobs` |
+
+### api.runs
+
+| Call | Route |
+|---|---|
+| `api.runs.list(gameId, jobId)` | `GET /jobs/:jobId/runs` -> `{ runs }` |
+| `api.runs.add(gameId, jobId, personas)` | `POST /jobs/:jobId/runs` |
+| `api.runs.heartbeat(gameId, jobId, runId, opts)` | `PATCH /jobs/:jobId/runs/:runId` with no state |
+| `api.runs.transition(gameId, jobId, runId, state, opts)` | the same PATCH, with a state |
+| `api.runs.uploads(gameId, jobId, runId, { files, includeVideo })` | `POST .../uploads` |
+| `api.runs.complete(gameId, jobId, runId, body)` | `POST .../complete` |
+
+`opts` for both heartbeat and transition is
+`{ reason, checkpointStep, actionsTaken, heartbeat }`. Both answer
+`{ run, cancel_requested }`, and `cancel_requested` is the only signal a
+runner gets that it should stop, so read it on every beat.
+
+Heartbeat is marked idempotent and is retried. Transition is not: a retried
+transition can lose a race and come back 409 `invalid_transition`, which the
+caller has to see rather than have swallowed.
+
+Send a heartbeat at least every 5 seconds. The server marks a run
+`interrupted` after 30 minutes of silence.
+
+## ApiError
+
+```js
+try { await api.jobs.register(...); }
+catch (error) {
+  if (error instanceof ApiError) {
+    error.status;      // 402
+    error.code;        // 'insufficient_balance', the server's `error` field
+    error.message;     // the server's `message`, safe to print
+    error.details;     // [{ instancePath, message, code? }], [] when absent
+    error.retryAfter;  // seconds, or null
+    error.body;        // the parsed body, for the extra figures
+    error.method;      // 'POST'
+    error.path;        // '/api/v1/games/g1/playtest/jobs'
+  }
+}
+```
+
+`isRetryable(error)` is true for a network failure, a timeout, 408, 425, 429
+and 5xx, with two code-aware exceptions, because for these two the status alone
+gives the wrong answer:
+
+- **`too_many_active_jobs`** is a 429 and is NOT retried. It means this game
+  already has three jobs running, which waiting inside one request cannot
+  change. The person needs to be told, not made to wait through four backoffs.
+- **`charge_in_progress`** is a 409 and IS retried, on its own `Retry-After`,
+  up to five times, and that allowance is independent of the client's `retries`
+  setting. It does not mean refused: another caller holds the charge claim and
+  this one cannot tell whether money moved. It becomes a real answer (a replay,
+  or a charge) within seconds. A `charge_in_progress` with no `Retry-After` is
+  not retried, because then there is no interval the server has blessed.
+
+`isRetryable` says nothing about whether retrying is *safe*; that is what the
+`idempotent` flag is for. `codeRetryLimit(error)` exposes the per-code
+allowance.
+
+A network failure with no response is an `ApiError` with `status: 0` and
+`code: 'network_error'`.
+
+## Credentials, and what a 401 means
+
+`resolveToken({ apiUrl, required })` answers
+`{ token, source, host }`, where `source` is the real origin: `'env'` for
+`RAVENSIGHT_TOKEN`, or `'keychain'` or `'file'` depending on which store
+actually answered.
+
+Every command runs its API work inside `withAuthHandling(context, fn)`, which
+funnels a 401 through `handleUnauthorized(context, error)`:
+
+- a **stored** token (`tokenSource` is not `'env'`) is DELETED, a line says so,
+  and the thrown error is a `CliError` with `ExitCode.AUTH` and a "run login"
+  hint. Keeping a revoked token means every later command fails the same way
+  and nobody can tell why.
+- a token from **`RAVENSIGHT_TOKEN`** is never deleted, only reported. It is
+  probably a CI secret shared with other jobs.
+- anything that is not a 401 (a 403, a 404, a plain `Error`) passes through
+  untouched.
+
+If you add a command, wrap its body the same way. `createContext` gives you the
+`tokenSource` it needs.
+
+## packs
+
+The cache lives in the user cache directory, keyed by API host, verified by
+sha256, refreshed with `If-None-Match`.
+
+```js
+const { bundle, etag, fromCache, fetchedAt, stale } = await packs.get({
+  api, gameId, modules: ['persona_playtest'], offline: false
+});
+```
+
+- Online, no cache: fetches and writes the cache.
+- Online, cache present: sends `If-None-Match`; a 304 reuses the cached copy.
+- Offline (or the fetch fails): returns the cached copy with `stale: true`,
+  or throws when there is no cache at all.
+- `fetchedAt` is an ISO string. `stale` is true whenever the answer did not
+  come from this process's own successful request.
+
+`packs.cached({ apiUrl, gameId, modules })` reads the cache without any
+network. `packs.sync({ api, gameId, modules })` forces a fetch and returns
+the same shape.
+
+The bundle's own fields are the server's: `pack_version`, `generated_at`,
+`personas`, `skills`, `schemas`, `routing`, `code_brief`, `engine`,
+`intent_notes`, `etag`.
+
+## uploadRunDir and finalizeRun
+
+```js
+const result = await uploadRunDir(runDir, {
+  api, gameId, jobId, runId,
+  includeVideo: false,       // session.webm and session.mp4 are opt-in
+  includeTranscript: false,  // transcript.jsonl is opt-in
+  allowedPaths: null,        // narrow the allowlist (see JOB_UPLOAD_PATHS)
+  dryRun: false,             // list what would be sent, upload nothing
+  onFile: ({ path, size, status }) => {}
+});
+// { uploaded: [{path,size,sha256}], skipped: [{path,reason}], bytes, dryRun }
+```
+
+**The server has ONE opt-in flag and it covers BOTH opt-in artifacts.**
+`POST .../uploads` takes `include_video`, and the server's `contentTypeFor`
+skips every `optIn` entry when it is false, which includes `transcript.jsonl`.
+So a transcript-only batch sent with `include_video: false` is refused, and the
+refusal is a 400 on the whole batch rather than on the one path. `uploadRunDir`
+therefore sends `include_video: includeVideo || includeTranscript`. Keep the two
+CLI-side flags separate (they decide what goes in the batch); do not try to
+send two flags to the server.
+
+For a job-level upload (no `runId`), pass `allowedPaths: JOB_UPLOAD_PATHS`. The
+server's allowlist is one list for both levels and would happily sign
+`report.json` or `job.json` at the job root; the three artifacts that actually
+belong to a job are `capability-report.json`, `aggregate-report.md` and
+`aggregate-report.json`.
+
+`runDir` is a directory on disk. Files are matched against the upload
+allowlist compiled into the CLI (the same list as the server's
+`src/playtest/limits.js`); anything else is reported in `skipped` and never
+sent. Source code is not on the list and is never uploaded.
+
+Each file is sha256'd and sized locally, presigned in one request, then PUT
+with the `Content-Type` the server signed and, for `session.webm`,
+`session.mp4` and `transcript.jsonl`, the `x-amz-tagging` value the presign
+response handed back, sent verbatim. Dropping that header is a signature
+mismatch, not an untagged object.
+
+A 403 on a PUT means the URL expired: the file is presigned again once and
+retried. Anything else retries with backoff. Every attempt is journalled to
+`<jobDir>/upload-queue.jsonl`, so `ravensight-playtest upload <job>` can
+drain what a crash left behind, and a file whose sha256 is already recorded
+as uploaded is skipped rather than sent twice.
+
+```js
+const { run, dropped_findings, report_lint } = await finalizeRun(runDir, {
+  api, gameId, jobId, runId, includeVideo, includeTranscript,
+  body: { state: 'succeeded', report, report_md, actions_taken, quit_reason }
+});
+```
+
+`finalizeRun` uploads, then calls `complete`. A 422 `upload_unverified`
+names the failed paths in `details[].instancePath` as `/manifest/<path>`;
+`finalizeRun` re-uploads exactly those and completes once more. The run
+stays non-terminal through that, by design. A second failure throws.
+
+422 `invalid_report` and 422 `secrets_detected` are not repaired here and
+are thrown for the caller to deal with: a report the schema refuses needs
+regenerating, and a secret needs rotating.
+
+## State
+
+The resumable journal, one file per job, written atomically (temp file plus
+rename) so a kill mid-write cannot leave a half file.
+
+```js
+await writeState(jobId, { job_id, game_id, ... }, { repoRoot });
+const state = await readState(jobId, { repoRoot });   // null when absent
+await updateState(jobId, s => ({ ...s, runs: {...} }), { repoRoot });
+```
+
+The shape is the runner's to define; cli-core only requires `job_id` and
+`game_id` at the top level, which is what `resume` reads. Keep every value
+JSON-serializable.
+
+## paths
+
+```js
+paths.repoRoot(options)        // cwd, or options.repoRoot
+paths.ravensightDir(options)   // <repo>/.ravensight
+paths.configFile(options)      // <repo>/.ravensight/config.json
+paths.jobDir(jobId, options)   // <repo>/.ravensight/jobs/<jobId>
+paths.stateFile(jobId, options)
+paths.queueFile(jobId, options)
+paths.runDir(jobId, runId, options)   // .../jobs/<jobId>/runs/<runId>
+paths.userDir()                // ~/.ravensight-playtest
+paths.cacheDir(apiUrl)         // per-host pack cache
+```
+
+A run directory holds `report.md`, `report.json`, `usage.json`,
+`transcript.jsonl`, `screenshots/NN-slug.png` and `session.webm`. Those
+names are the allowlist's; a different name is not uploadable.
+
+## ui
+
+```js
+ui.info(text); ui.warn(text); ui.error(text); ui.ok(text);
+ui.table(rows, columns);            // aligned, no borders
+const spin = ui.spinner('Working'); spin.update('Still working'); spin.stop('Done');
+await ui.confirm('Start the job?', { yes: flags.yes });
+ui.json(value);                     // stable stringify for --json output
+```
+
+Nothing in `ui` writes to stdout when `RAVENSIGHT_JSON=1` or when
+`ui.setQuiet(true)` has been called, except `ui.json`, so `--json` output
+stays machine-readable. Spinners degrade to one line per update when stdout
+is not a TTY.
+
+## State lists
+
+`MODULES`, `DRIVERS`, `JOB_STATES`, `JOB_TERMINAL_STATES`, `RUN_STATES`,
+`RUN_TERMINAL_STATES` and `RUN_TRANSITIONS` are copies of the server's own
+enums, with `isRunTerminal(state)`, `isJobTerminal(state)` and
+`canTransitionRun(from, to)` over them. Use them to refuse a nonsense
+transition locally; the server is still the authority and refuses one it does
+not know.
+
+Two of them are load bearing. `interrupted` is NOT a terminal run state: it is
+what the server's sweep marks a run whose heartbeat stopped, and the whole
+point of it is that `resume` can take it back to `launching`. And a job reaches
+a terminal state only through `/finish`, `/cancel` or `DELETE`; a `PATCH` that
+asks for one is refused with 409, because the terminal state and the refund are
+one decision.
+
+## Godot
+
+```js
+const { isProject, projectVersion, binary, matches, source } = await inspectGodot({
+  repoRoot, godotPath
+});
+```
+
+This is an adapter, not a second implementation. When
+`src/run/drivers/godot-project.js` is present it calls that module's
+`isGodotProject`, `readProjectEngineVersion` and `detectGodotBinary`, so the
+binary `check` blesses is the one the driver will launch; without it, it falls
+back to a local probe and reports `source: 'fallback'`. Godot is never a
+failure in `check`: a missing one is a warning, because a web build run does
+not need it.
+
+## Exit codes
+
+`ExitCode` from spec 17, used by `process.exit` at the top level only:
+
+| Name | Value |
+|---|---|
+| `OK` | 0 |
+| `BUDGET_EXCEEDED` | 2 |
+| `ENVIRONMENT` | 3 |
+| `AUTH` | 4 |
+| `MODEL` | 5 |
+| `CANCELED` | 10 |
+
+Throw `new CliError(message, ExitCode.AUTH)` from anywhere; `bin/` maps it
+to the code and prints the message without a stack trace.
+
+## What cli-runner must export
+
+`src/cli.js` wires three commands to a lazy `import('./run/index.js')`, which
+keeps `check` from parsing the whole runner and turns a partial install into a
+sentence rather than a module-resolution stack trace. `src/run/index.js` exports
+exactly these three names, and `src/cli.test.js` resolves the module and checks
+for all three, so a rename on either side of the seam fails a test rather than a
+paid run.
+
+```js
+/**
+ * `ravensight-playtest run`
+ * @param {Object} flags - { apiUrl, repoRoot, json, yes, game, argv }
+ *   `argv` is every unrecognized argument, so the run command owns its own
+ *   flag parsing (--personas, --driver, --build-url, --max-actions, and so on).
+ * @returns {Promise<number>} an ExitCode
+ */
+export async function runCommand(flags) {}
+
+/**
+ * `ravensight-playtest profile`
+ * @param {Object} flags - the same shape
+ * @returns {Promise<number>} an ExitCode
+ */
+export async function profileCommand(flags) {}
+
+/**
+ * The handoff from `ravensight-playtest resume <jobId>`.
+ *
+ * cli-core has already: read the local journal, confirmed the job exists on the
+ * server, listed its runs, and printed which are finished. It does NOT restart
+ * anything, and it never filters the runs it hands over, so deciding which are
+ * resumable is yours (use `isRunTerminal` from this module: a `succeeded` run
+ * must never be re-run, and `interrupted` is the one that should be).
+ *
+ * @param {Object} args
+ * @param {Object} args.api        a createClient instance, already authenticated
+ * @param {string} args.gameId
+ * @param {string} args.jobId
+ * @param {Object} args.job        the server's job body, from GET /jobs/:jobId
+ * @param {Array}  args.runs       the server's run bodies, from GET .../runs
+ * @param {Object} args.state      the local journal, as written by writeState
+ * @param {string} args.repoRoot
+ * @param {Object} args.flags      { apiUrl, repoRoot, json, yes, game, status,
+ *                                   restartInterrupted }. `restartInterrupted`
+ *                                   is `resume --restart-interrupted`: without
+ *                                   it a run past the partial checkpoint floor
+ *                                   is finalised from its own transcript, with
+ *                                   it the run is replayed and spends its
+ *                                   action budget again.
+ * @returns {Promise<number>} an ExitCode. 2 for a budget stop, 10 for a cancel.
+ */
+export async function resumeJob(args) {}
+```
+
+Both commands must answer an exit code rather than calling `process.exit`:
+`bin/ravensight-playtest.js` is the only place in the package that exits.