ravensight-playtest 0.3.1 → 0.3.2

package/README.md

@@ -45,9 +45,32 @@ Credential Manager, libsecret on Linux). With no keychain available it falls
 back to a file with 0600 permissions under your home directory, and says so.
 In CI, set `RAVENSIGHT_TOKEN` instead and skip `login` entirely.
 
+## Upgrading to 0.3.2
+
+- **A plain `run` plays one persona, not two.** The default persona set is now
+  `curious-kid` alone, so a first run costs one persona run. Name more with
+  `--personas curious-kid,grumpy-veteran` (or `personas` in
+  `.ravensight/config.json`); `ravensight-playtest personas` lists the slugs.
+  A script that relied on two personas by default has to name them.
+- **`run` checks the build before it prices anything.** A web build's URL has
+  to answer 2xx or 3xx, or the `preflight` URL in `.ravensight/config.json` has
+  to answer what you set (see `run`). A failure exits 1 with no job registered.
+  `--skip-preflight` skips it, as it already skipped the native probe.
+- **`brief` and `check` quote the run that `run` would start**: its modules and
+  its personas, the default one when you name none, each unit with its own
+  price. They used to quote a game profile with no personas.
+- **Two new brief fields stay on this machine**: `expected_noise` and
+  `test_account` (see the `brief --from` file). `init` adds
+  `.ravensight/brief.local.json` to `.gitignore`.
+- **Out of range report values are normalised before upload** instead of
+  failing the run (see how the report step reads what happened, under `run`).
+- **A CSS selector is no longer a target.** A target is a ref, coordinates, a
+  line copied from the screen, or text on the screen; anything else is refused
+  at once instead of searched for.
+
 ## Commands
 
-Twelve commands. Flags below are the ones the code accepts, not the ones the
+Thirteen commands. Flags below are the ones the code accepts, not the ones the
 prose elsewhere describes; `--help` on any command prints the same list.
 
 Every command takes these four:
@@ -89,9 +112,26 @@ to), `project binding` (the game and environment this directory is linked to,
 and whether that game is in the token's scope), `brief` (present, complete, and
 which of goals, success criteria, controls and how to start are empty), `build`
 (the URL, Godot project or native build a run would use), `automation server`
-(native drivers only, see below), then the balance against the next job's price,
-the content pack verified by sha256, disk, recommended concurrency, and the two
-optional tools.
+(native drivers only, see below), then the content pack verified by sha256, the
+balance against the price of the run `run` would start (its modules and
+personas, the default persona when none is named, each unit with its price),
+disk, recommended concurrency, and the two optional tools. A `--personas` slug
+the pack does not have fails a `personas` row that lists the valid slugs, and
+nothing is priced.
+
+For a web build linked by URL (`--build-url` is a `run` flag; `check` reads the
+URL from `.ravensight/config.json`), the `browser` row also loads the first
+screen headless and a `first screen` row measures it the way a persona would
+read it. When the whole text is over the 4,000 characters a persona reads per
+step, or the screen has a list of 50 or more look-alike items, the row is a
+warning that suggests `run --long` with the reason ("first screen is 18,400
+characters, about 4.6x the 4,000 a persona reads per step") and both prices,
+read from the server's free estimate. A light screen passes with its size. A
+first screen that does not load within 20 seconds is a warning, never a
+failure. The page is marked as a playtest before the game's scripts run (the
+same `window.__RAVENSIGHT_PLAYTEST__` a run sets, with the token `check`), so a
+build shipping the Ravensight web SDK has its session refused rather than
+recorded as a real player.
 
 Every row is `pass`, `warn` or `fail`, and every row that is not `pass` prints
 its fix. Exit code 3 when any row fails; a warning never fails, so CI does not
@@ -118,7 +158,7 @@ setup with the expected rows at each step.
   "ok": true,
   "reserves_units": false,
   "note": "check reserves no units and starts no job: ...",
-  "cli": { "installed": "0.3.1", "latest": "0.3.1", "min_supported": "0.1.0" },
+  "cli": { "installed": "0.3.2", "latest": "0.3.2", "min_supported": "0.1.0" },
   "login": { "present": true, "valid": true, "games": [{ "gameId": "g1", "name": "Pocket Knight" }] },
   "project": { "game": "g1", "environment": null, "in_scope": true },
   "brief": { "present": true, "complete": true, "missing": [] },
@@ -156,8 +196,8 @@ automatically. `check` shows that same warning as a row when it applies.
 | Flag | Effect |
 |---|---|
 | `--game <gameId>` | Check against this game instead of the linked one. |
-| `--modules <list>` | Price this module list, comma separated. |
-| `--personas <list>` | Price this persona list. Without it the balance row prices no personas, so the quote is lower than a real job's. |
+| `--modules <list>` | Price this module list, comma separated. Default the modules `run` registers, `persona_playtest,aggregate_report`. |
+| `--personas <list>` | Price this persona list. Without it, a module list with `persona_playtest` prices the repo config's personas or the default one, as `run` would. |
 | `--godot-path <path>` | Where Godot is, if it is not on the PATH. |
 | `--web` | Check the browser even when this repo is not linked to a web build. |
 | `--driver <name>` | Check the setup for this driver instead of the configured one. |
@@ -167,7 +207,8 @@ automatically. `check` shows that same warning as a row when it applies.
 
 Links this repo to a game and writes `.ravensight/config.json`. Refuses a game
 your token cannot see, so the first job does not fail with a 404. Adds
-`.ravensight/jobs/` to an existing `.gitignore`.
+`.ravensight/jobs/` and `.ravensight/brief.local.json` to an existing
+`.gitignore`.
 
 Without `--game`, one visible game is linked as is. With several, `init` lists
 them numbered and asks `Which game? [1-N]` when it is running in a terminal; in
@@ -180,11 +221,18 @@ login).
 | `--game <gameId>` | The game to link. Optional with one visible game, or in a terminal. |
 | `--force` | Relink a repo that is already linked. |
 
+### personas
+
+Lists the persona slugs `--personas` accepts, from the content pack this game
+gets: each one's name, action budget (its patience) and play style, with the
+default marked. A free read. Takes `--game <gameId>` and `--json`.
+
 ### brief
 
 Writes the expectations brief: your goals, what success looks like, how the game
-is controlled, where a persona starts. Then prints what a job would cost,
-whether your balance covers it, and, past 8 personas, the same wall-clock
+is controlled, where a persona starts. Then prints what the run `run` would
+start costs ("A run of 1 persona (curious-kid) would cost $1.00: a persona run
+$1.00 each"; the game profile is a separate job), whether your balance covers it, and, past 8 personas, the same wall-clock
 warning `run` shows. A brief is required before `run`; the server answers 409
 `brief_required` without one.
 
@@ -195,7 +243,7 @@ warning `run` shows. A brief is required before `run`; the server answers 409
 | `--draft` | Save as a draft even when it looks complete. |
 | `--from <file>` | Read the fields from a JSON file instead of asking. |
 | `--game <gameId>` | The game, when this repo is not linked. |
-| `--modules <list>`, `--personas <list>` | Price this module and persona list in the estimate it prints. |
+| `--modules <list>`, `--personas <list>` | Price this module and persona list in the estimate it prints. Every unit is named with its own price, such as "profile job $4.00, a persona run $1.00 each". |
 
 #### The `brief --from` file
 
@@ -211,13 +259,43 @@ are what makes a brief complete; the rest are optional.
 | `build_notes.how_to_start` | string | Where a persona begins: the URL, the menu path, the first thing to press. |
 | `design_intent_notes` | array of strings | Deliberate choices a persona must not report as bugs. |
 | `known_issues` | array of strings | Issues you already know about, so they are not reported again. |
+| `expected_noise` | array of strings | Console errors and failed requests that are expected, such as `"401 /auth/me before login"`. Never a finding. Kept on this machine. |
+| `test_account` | `{ "email", "password", "how_to_sign_in" }` | A throwaway account the persona signs in with, so a run starts past sign-up. The password must be at least 8 characters. Kept on this machine. |
+
+`expected_noise` and `test_account` never go to the server: its brief schema
+refuses keys it does not list, and a password does not belong in a record the
+studio shares. `brief --from` splits them into `.ravensight/brief.local.json`,
+readable by you only, which `init` adds to `.gitignore`; `brief --show` prints
+them with the password masked, and `run` and `resume` read them from there.
+
+An `expected_noise` pattern matches an automatic console note when every status
+code (`401`) and every path (`/auth/me`) in it appears in the note; the other
+words describe it for the reader. A pattern with neither is matched as text,
+and `/.../` is a regular expression. One rule is built in: a 401 on a who am I
+check, a request whose last path segment is `/me`, `/whoami`, `/session` or
+`/current_user` (such as `/auth/me`), is what a signed out page does and is not
+a finding. A 401 anywhere else (`/me/inventory`, `/user/42/save`, `/token`,
+`/login`) is left to the report step. A matching note is marked "expected
+noise" in the report prompt, and the runner drops a finding whose evidence is
+only expected noise, listing it in `report.md`. A note the persona wrote itself
+is never noise.
+
+**The test account password crosses the model proxy during play only**: it is
+in the persona's prompt on every play turn, because that is how a persona can
+type it. Use an account made for testing, with nothing behind it you would mind
+losing. The report step never sees it: its prompt has no test account, and the
+password is replaced by `[test password]`, wherever it stands as a whole token, in the notes, the action log, the
+transcript, and in `report.md` and `report.json` before anything is uploaded. A
+password field's value is never shown in an observation.
 
 ```json
 {
   "goals": [{ "goal": "onboarding", "priority": 1 }, { "goal": "find_bugs", "priority": 2 }],
   "success_criteria": "A new player reaches level 2\nNobody gets stuck in the menu",
   "build_notes": { "controls": "Arrow keys to move, space to jump", "how_to_start": "Press Start on the title screen" },
-  "design_intent_notes": ["The fog on level 1 is intentional"]
+  "design_intent_notes": ["The fog on level 1 is intentional"],
+  "expected_noise": ["401 /auth/me before login"],
+  "test_account": { "email": "qa@example.test", "password": "a-throwaway-password", "how_to_sign_in": "Log in from the top right" }
 }
 ```
 
@@ -230,7 +308,36 @@ run options below.
 ### run
 
 Registers a job, plays it, writes the reports, uploads them, finishes the job.
-Prints the price and asks before spending.
+Prints the price and asks before spending. Before any charge, even with
+`--yes`, it prints one bold line with the persona count and the total ("This
+run: 1 persona (curious-kid) on playwright_web, $1.00 in total: a persona run
+$1.00 each"), the balance, and what a persona run buys: the action budget (the
+persona's patience in the pack, lowered by `--max-actions` or the server's
+ceiling) and that sign-up alone can take 8 of those actions. A `test_account`
+in the brief lets the persona sign in instead. An unknown `--personas` slug is
+refused with the valid slugs before anything is priced.
+
+`--long` makes every persona run a long run: twice the actions, model budget
+and wall time of a standard run, for a game whose screens are heavy or whose
+goal is far in. It costs twice a standard run. The price is the server's
+estimate for the long run, printed and confirmed like any other, never a figure
+built into the CLI. Locally a long run uses the run's own action limit when the
+server's register answer carries one, otherwise twice the standard ceilings
+(the persona's patience and the per run ceiling); `--max-actions` still only
+lowers it. `check` suggests `--long` when the first screen is heavy.
+
+Before the estimate, `run` checks the build is up, so a down server is never
+paid for. Set `preflight` in `.ravensight/config.json` to name what to check:
+
+```json
+{ "preflight": { "url": "/api/health", "expect_status": 200 } }
+```
+
+`url` may be relative to the build URL; `expect_status` is a number or a list
+of numbers, and without it any 2xx or 3xx passes (redirects are not followed).
+With no `preflight`, a web build's own URL has to answer 2xx or 3xx; other
+drivers are not checked unless a `preflight.url` is set. A failure prints the
+status it saw (or the network error), exits 1, and registers nothing.
 
 With a native driver, `run` first runs the `build` and `automation server` rows
 of `check`. When either fails it exits 1 before the estimate, the confirmation
@@ -252,14 +359,15 @@ splitting the job in two is what gets everything played.
 | Flag | Effect |
 |---|---|
 | `--game <gameId>` | The game, when this repo is not linked. |
-| `--personas <list>` | Comma separated persona slugs. Defaults to the pack's set. |
+| `--personas <list>` | Comma separated persona slugs. Defaults to one, `curious-kid`; `ravensight-playtest personas` lists them. |
 | `--driver <name>` | `playwright_web`, `godot_driver`, `cli_stdio`, or a native driver: `desktop_driver`, `unity_driver`, `unreal_driver`, `android_driver`, `ios_driver`. |
 | `--build-url <url>` | The web build to play. |
 | `--godot-project <dir>` | The Godot project directory. |
 | `--driver-config <file>` | The native driver config, or the JSON-RPC bridge config for `cli_stdio`. |
-| `--skip-preflight` | Native drivers only: register without running the free automation probe first. The job is registered and charged even if the automation server turns out to be down. |
+| `--skip-preflight` | Register without the free checks first: the build health check (any driver) and the automation probe (native drivers). The job is registered and charged even if the build or the automation server turns out to be down. |
 | `--cli <command>` | The command that starts a text build. |
 | `--max-actions <n>` | Lower the actions one persona may take. It can only lower the persona's own patience (and the server's per run ceiling), never raise it. |
+| `--long` | A long persona run: twice the actions, model budget and wall time of a standard run, at twice the price. The price is read from the estimate and confirmed before any charge. |
 | `--concurrency <n>` | Personas at once. Default 2; `check` recommends a number for this machine. |
 | `--upload-video` | Upload `session.webm` as well as the reports. |
 | `--upload-transcript` | Upload `transcript.jsonl` as well as the reports. |
@@ -304,6 +412,30 @@ message, the run is completed as `failed`, and the job exits 1.
 
 How the report step reads what happened:
 
+- Values the report schema does not allow are normalised before upload, so a
+  run is not lost to them when the model has no budget left for a repair: a
+  severity that is a category word (`"severity": "ux"`) moves to `category`
+  when the category is missing or not allowed and the severity becomes
+  `minor`; any other unknown severity becomes `minor`; an unknown category
+  takes a close match the schema has (`ui` is `ux`, `crash` is `bug`), else
+  `other` when the schema has it, else `ux` (the server's schema has no
+  catch-all today); a value that differs only in case is respelled; any other
+  enum field takes the schema's default. Each change is a runner note at the
+  end of the finding's description and is listed in `report.md` under
+  "Normalised by the runner". The server's schema stays strict.
+- After the report is written, each blocker or major (at most 3) is checked
+  against its own evidence: the screenshot it cites taken nearest after the
+  observation it cites is sent with its claim, and the question "does this
+  image contradict the claim: yes, no, unclear". A yes downgrades it one step,
+  with a note naming the screenshot, in both report files. The cost is 3
+  calls at most, each one screenshot in and 32 tokens out, drawn from the
+  run's own model budget (the one the 80 percent warning keeps room in for
+  the report), never charged separately; a refusal ends the checks and keeps
+  the report as written.
+- Console notes that match the brief's `expected_noise`, or the built in rule
+  (a 401 on a who am I check while signed out), are expected noise
+  and never a finding; see the `brief --from` file.
+
 - Console errors are recorded as automatic notes. A 4xx on a request (`Failed
   to load resource`, `HTTP 404`, `status: 401`, `401 Unauthorized` and similar)
   is a network note: context, not a bug. On the web a `Failed to load
@@ -369,11 +501,26 @@ clicks and types by ref, which names exactly one element even when two share
 a name; two such elements are both shown, each with where it is ("in header
 strip", "in main"). A name that matches twice is answered with the refs to
 choose from, and a target written as locator code (`getByRole(...)`,
-`page.locator(...)`, `css=`, `xpath=`) is refused at once. Failures like these
+`page.locator(...)`, `css=`, `xpath=`) is refused at once. A whole line copied
+from the screen (`button "Run the week" [e12] @(1000,303)`, or any part of one)
+is clicked by its ref, else its `@(x,y)` (refused like a stale ref when the page
+has loaded a new document since); a ref or point inside a quoted name is part
+of the name, and a bare `e4` is text when something on screen is named exactly
+that. A target that is
+none of a ref, coordinates or text on the screen is refused at once rather than
+searched for. A name that matches one element on screen is clicked by that
+element's ref, and a text search skips hidden elements, so a mobile only copy
+hidden by CSS is never the one clicked. Failures like these
 are the driver's, not the game's: they are recorded as `driver_error`, and a
 blocker or major resting only on them is dropped before upload, as is any
 finding resting only on the persona's "waiting for X to finish" notes.
 
+An action counts as changing the screen when the URL changed, the page loaded
+a new document, the visible tree (field values included) changed, or for typing,
+the field's own value changed, with one short second look for a navigation
+still starting. That is the "screen changed" the report step's action log and
+the downgrade rule read.
+
 Every field, checkbox, radio, slider and select the persona sees carries what
 it holds now, read from the page rather than from the accessibility text:
 `value="..."` (cut at 80 characters), `checked` or `not checked`, or
@@ -382,7 +529,9 @@ the page could not answer for shows no value at all, so a typed password never
 reaches the model.
 
 On a long web page the persona's text view of the screen is capped at 4,000
-characters. Over the cap, buttons, links and fields are kept first, a long run
+characters. A run of 20 or more look-alike items is always shown as its first
+two and "and N more like it", under the cap too; a shorter run under the cap is
+shown as it is. Over the cap, buttons, links and fields are kept first, a long run
 of look-alike items (a list of 249 cards) is shown as its first two and "and
 247 more like it", and what changed since the last look comes next, so a form
 after a long list still reaches the persona.
@@ -394,7 +543,8 @@ reached. Every run gets its own identity to sign up with, an email
 short run id, so a second run never hits "that email is taken" from the first.
 `example.test` is a reserved name and never delivers mail. Point `--build-url` at a guest or demo path, or say where to start in
 the brief's `how_to_start` note (for example "choose Play as guest"), when the
-sign-up is not what you want tested.
+sign-up is not what you want tested, or give the brief a `test_account` the
+persona signs in with instead.
 
 ### fix
 
@@ -586,6 +736,7 @@ In your repo:
 ```
 .ravensight/
   config.json                 the game link and your defaults
+  brief.local.json            expected_noise and test_account, this machine only (0600)
   jobs/<jobId>/
     state.json                the resumable journal
     upload-queue.jsonl        what was uploaded, and what is still owed
@@ -602,8 +753,8 @@ and a local `transcript.jsonl` of the apply loop (which tool, on what, how
 much came back) that is never uploaded and is how an attempt that wrote
 nothing gets explained afterwards.
 
-Add `.ravensight/jobs/` to your `.gitignore`; `init` does it for you when you
-already have one.
+Add `.ravensight/jobs/` and `.ravensight/brief.local.json` to your
+`.gitignore`; `init` does it for you when you already have one.
 
 `fix` also leaves a branch on your working copy, checked out, with the change in
 your working tree and nothing committed. It is the only thing in this CLI that
@@ -633,6 +784,16 @@ pins it equal to the server's file when a checkout is on the same machine.
 Findings cite a file and a line range. The source text behind that line is not
 uploaded.
 
+`.ravensight/brief.local.json` is never uploaded. Its `expected_noise` goes into
+the persona and report prompts. Its `test_account`, password included, goes into
+the persona's prompt during play only, through the model proxy; the report step
+never gets it, and the password is scrubbed to `[test password]` from the
+transcript, the notes and both report files before upload.
+
+`run`'s build health check is one GET to your own build (or the `preflight`
+URL you set), made from your machine.
+
+
 A `fix` uploads `changeset.json` and `report.md`. The changeset carries the
 finding id, the branch name, the commit it branched from, the file paths it
 changed with their added and removed line counts, the verify verdict, and the

package/docs/NATIVE_RUNNER.md

@@ -60,7 +60,7 @@ Every device command times out after 30 seconds and responses are capped at
 ## Step 1: the account side
 
 ```bash
-npm install -g ravensight-playtest@0.3.1
+npm install -g ravensight-playtest@0.3.2
 ravensight-playtest login
 cd path/to/your/game
 ravensight-playtest init --game <gameId>
@@ -70,7 +70,7 @@ ravensight-playtest check --driver ios_driver
 Expected rows (your email, game and version differ):
 
 ```
-pass  cli version        installed 0.3.1; server latest 0.3.1, min_supported 0.1.0
+pass  cli version        installed 0.3.2; server latest 0.3.2, min_supported 0.1.0
 pass  login              you@example.com, valid, scoped to 1 game: Pocket Knight (g1)
 pass  project binding    linked to Pocket Knight (g1), in the token's scope
 fail  brief              this game has no expectations brief, and a persona run needs one

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ravensight-playtest",
-  "version": "0.3.1",
+  "version": "0.3.2",
   "description": "AI personas play your game and file reports to Ravensight.",
   "license": "MIT",
   "homepage": "https://ravensight.io/docs/#playtest",
@@ -53,6 +53,6 @@
   },
   "optionalDependencies": {
     "keytar": "^7.9.0",
-    "playwright": "^1.49.0"
+    "playwright": "^1.51.0"
   }
 }

package/src/api/client.js

@@ -189,9 +189,15 @@ export function createClient(options = {}) {
   };
 
   const jobs = {
-    estimate: (gameId, { modules = [], personas = [] } = {}) =>
-      request('POST', `${gameBase(gameId)}/estimate`, { body: { modules, personas } })
-        .then(answer => answer.body),
+    /**
+     * Price a job without charging. `runLength: 'long'` asks for the long
+     * persona run's price; anything else leaves `run_length` out, which the
+     * server reads as a standard run.
+     */
+    estimate: (gameId, { modules = [], personas = [], runLength = null } = {}) =>
+      request('POST', `${gameBase(gameId)}/estimate`, {
+        body: { modules, personas, ...(runLength === 'long' ? { run_length: 'long' } : {}) }
+      }).then(answer => answer.body),
 
     /**
      * Register a job: this is the request that moves money.

package/src/briefLocal.js

@@ -0,0 +1,126 @@
+import { join } from 'node:path';
+import { readJson, writeJson } from './fsutil.js';
+import { CliError } from './errors.js';
+
+/**
+ * The brief fields that stay on this machine: `expected_noise` and
+ * `test_account`.
+ *
+ * The server's expectations brief schema refuses any key it does not list
+ * (`additionalProperties: false`, drafts included), and a test account's
+ * password has no business in a record the whole studio can read. So these
+ * two live in `.ravensight/brief.local.json`, which `init` adds to
+ * `.gitignore` and which is written readable by its owner only. `brief --from`
+ * accepts them in the same file as the server's fields and splits them off;
+ * `run` and `resume` hand them to the persona with the rest of the brief.
+ *
+ * The password is still sent to the model like any other prompt text: that is
+ * how a persona can type it. It is for a throwaway account made for testing.
+ */
+
+/** The keys this file holds. */
+export const LOCAL_BRIEF_FIELDS = Object.freeze(['expected_noise', 'test_account']);
+
+/** The shortest test account password accepted. */
+export const MIN_PASSWORD_CHARS = 8;
+
+/** What a password is printed as. */
+export const HIDDEN_PASSWORD = '(hidden)';
+
+/**
+ * @param {{repoRoot?: string}} [options]
+ * @returns {string}
+ */
+export function localBriefFile(options = {}) {
+  return join(options.repoRoot || process.cwd(), '.ravensight', 'brief.local.json');
+}
+
+/**
+ * Split a brief fields object into what the server stores and what stays here.
+ *
+ * @param {Object} fields
+ * @returns {{server: Object, local: Object}}
+ */
+export function splitLocalFields(fields = {}) {
+  const server = {};
+  const local = {};
+  for (const [key, value] of Object.entries(fields || {})) {
+    if (LOCAL_BRIEF_FIELDS.includes(key)) local[key] = value;
+    else server[key] = value;
+  }
+  return { server, local };
+}
+
+/**
+ * What is wrong with a local brief, one line per problem; empty when it is fine.
+ *
+ * @param {Object} local
+ * @returns {Array<string>}
+ */
+export function localBriefProblems(local = {}) {
+  const problems = [];
+  if (local.expected_noise !== undefined) {
+    if (!Array.isArray(local.expected_noise) || !local.expected_noise.every(entry => typeof entry === 'string' && entry.trim())) {
+      problems.push('expected_noise must be an array of non empty strings, such as ["401 /auth/me before login"]');
+    }
+  }
+  if (local.test_account !== undefined) {
+    const account = local.test_account;
+    if (!account || typeof account !== 'object' || Array.isArray(account)) {
+      problems.push('test_account must be an object: { "email": ..., "password": ..., "how_to_sign_in": ... }');
+    } else {
+      for (const key of ['email', 'password']) {
+        if (typeof account[key] !== 'string' || !account[key]) problems.push(`test_account.${key} must be a non empty string`);
+      }
+      // The runner scrubs the password out of every report; a short one
+      // ("test", "ux") would also match ordinary words and enum values.
+      if (typeof account.password === 'string' && account.password && account.password.length < MIN_PASSWORD_CHARS) {
+        problems.push(`test_account.password must be at least ${MIN_PASSWORD_CHARS} characters, so scrubbing it from reports cannot rewrite ordinary words`);
+      }
+      if (account.how_to_sign_in !== undefined && typeof account.how_to_sign_in !== 'string') problems.push('test_account.how_to_sign_in must be a string');
+    }
+  }
+  return problems;
+}
+
+/**
+ * The local brief, or {} when there is none. Never throws for a missing file;
+ * a file that is not an object is an error naming it.
+ *
+ * @param {{repoRoot?: string}} [options]
+ * @returns {Promise<Object>}
+ */
+export async function loadLocalBrief(options = {}) {
+  const file = localBriefFile(options);
+  const value = await readJson(file, null);
+  if (value === null) return {};
+  if (typeof value !== 'object' || Array.isArray(value)) throw new CliError(`${file} is not a brief fields object.`);
+  return Object.fromEntries(Object.entries(value).filter(([key]) => LOCAL_BRIEF_FIELDS.includes(key)));
+}
+
+/**
+ * Merge these fields into the local brief and write it, owner readable only.
+ *
+ * @param {Object} local
+ * @param {{repoRoot?: string}} [options]
+ * @returns {Promise<Object>} what the file now holds
+ */
+export async function saveLocalBrief(local, options = {}) {
+  const problems = localBriefProblems(local);
+  if (problems.length > 0) throw new CliError(`The local brief fields are not valid: ${problems.join('; ')}.`);
+  const merged = { ...(await loadLocalBrief(options)), ...local };
+  await writeJson(localBriefFile(options), merged, { mode: 0o600 });
+  return merged;
+}
+
+/**
+ * The local brief as it may be printed: the password masked.
+ *
+ * @param {Object} local
+ * @returns {Object}
+ */
+export function displayLocalBrief(local = {}) {
+  const out = { ...local };
+  if (out.test_account && typeof out.test_account === 'object') out.test_account = { ...out.test_account, ...(out.test_account.password ? { password: HIDDEN_PASSWORD } : {}) };
+  return out;
+}

package/src/cli.js

@@ -52,13 +52,16 @@ async function loadRunner(name, exportName) {
  */
 export const RUNNER_HELP = `
 Run options (parsed by the runner, see src/run/args.js):
-  --personas <list>         comma separated persona slugs, default the pack's set
+  --personas <list>         comma separated persona slugs, default one (curious-kid); "personas" lists them
   --driver <name>           playwright_web, godot_driver, desktop_driver, unity_driver, unreal_driver, android_driver, ios_driver or cli_stdio
   --controller <name>       standard or jev action selection (default standard)
   --build-url <url>         the web build to play
   --godot-project <dir>     the Godot project directory
   --driver-config <file>    local WebDriver or JSON-RPC bridge configuration
   --max-actions <n>         lower the actions one persona may take; it can only lower the persona's own patience, never raise it
+  --long                    a long persona run: twice the actions, model budget and wall time of a standard
+                            run, for a game whose screens are heavy or whose goal is far in. It costs twice
+                            a standard run; the price is read from the estimate and confirmed before any charge
   --concurrency <n>         personas at once, default 2
   --upload-video            upload session.webm as well as the reports
   --upload-transcript       upload transcript.jsonl as well as the reports
@@ -67,8 +70,9 @@ Run options (parsed by the runner, see src/run/args.js):
   --headed                  show the browser
   --headless                hide it
   --verbose                 print each turn
-  --skip-preflight          native drivers: register without probing the automation server first;
-                            the job is registered and charged even if the server turns out to be down
+  --skip-preflight          register without the free checks first: the build health check (any driver)
+                            and the automation server probe (native drivers); the job is registered and
+                            charged even if the build or the server turns out to be down
 
 Accepted and reported as not applied by this release:
   --quality, --offline-upload, --build-dir
@@ -179,6 +183,13 @@ export function buildProgram() {
       }));
     }));
 
+  common(program.command('personas').description('list the persona slugs --personas accepts'))
+    .option('--game <gameId>', 'the game, when this repo is not linked')
+    .action(capture(slot, async options => {
+      const { personas } = await import('./commands/personas.js');
+      return personas(flagsFrom(options, { game: options.game }));
+    }));
+
   common(program.command('init').description('link this repo to a Ravensight game'))
     .option('--game <gameId>', 'the game to link')
     .option('--force', 'relink a repo that is already linked')