ravensight-playtest 0.2.3 → 0.2.5

package/README.md

@@ -87,6 +87,18 @@ content pack verified by sha256, disk, recommended concurrency, and the two
 optional tools. Exit code 3 when any row fails; a missing optional tool is a
 warning and never a failure, so CI does not break on it.
 
+For a web game there is also a `browser` row: `check` imports Playwright,
+launches a headless Chromium and closes it, which is exactly how a web run
+starts. A missing browser fails the check when the linked build is a URL or you
+pass `--web`. When no build is linked yet and the configured driver is the
+default `playwright_web`, it is only a warning, so a Godot repo that never
+changed the default is not failed over a browser it will not use. A repo linked
+to a Godot project or a driver config gets no browser row. The fix is:
+
+```bash
+npm i -D playwright && npx playwright install chromium
+```
+
 Past `--personas` in `POST /jobs`, requesting more than 100 personas or the same
 slug twice is refused with 400 `too_many_personas`, and a slug this game does
 not have is 400 `unknown_persona`; `run` checks the count against the same
@@ -101,6 +113,7 @@ automatically. `check` shows that same warning as a row when it applies.
 | `--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. |
 | `--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. |
 
 ### init
 
@@ -108,9 +121,15 @@ 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`.
 
+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
+CI or a pipe it prints the list and asks you to pass `--game` instead. A token
+that can see no games is told so, with the fix (approve a game for the token at
+login).
+
 | Flag | Effect |
 |---|---|
-| `--game <gameId>` | The game to link. With one visible game it is optional. |
+| `--game <gameId>` | The game to link. Optional with one visible game, or in a terminal. |
 | `--force` | Relink a repo that is already linked. |
 
 ### brief
@@ -130,6 +149,30 @@ warning `run` shows. A brief is required before `run`; the server answers 409
 | `--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. |
 
+#### The `brief --from` file
+
+A JSON object of brief fields, or the same object wrapped as
+`{ "fields": { ... } }`, which is how a saved brief carries them. The first four
+are what makes a brief complete; the rest are optional.
+
+| Field | Shape | Notes |
+|---|---|---|
+| `goals` | `[{ "goal": "...", "priority": 1 }]` | At least one. `goal` is one of `find_bugs`, `onboarding`, `balance`, `level_flow`, `narrative`, `accessibility`, `performance`. `priority` is 1 (highest) to 5. |
+| `success_criteria` | string | What success looks like, one criterion per line. The aggregate report scores each line. |
+| `build_notes.controls` | string | How to play: keys, buttons, the verbs a persona needs. |
+| `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. |
+
+```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"]
+}
+```
+
 ### profile
 
 Builds the game profile and the capability report: what your game is, what can
@@ -158,7 +201,7 @@ splitting the job in two is what gets everything played.
 | `--build-url <url>` | The web build to play. |
 | `--godot-project <dir>` | The Godot project directory. |
 | `--cli <command>` | The command that starts a text build. |
-| `--max-actions <n>` | Cap the actions one persona may take. |
+| `--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. |
 | `--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. |
@@ -166,10 +209,24 @@ splitting the job in two is what gets everything played.
 | `--headed`, `--headless` | Show or hide the browser. |
 | `--verbose` | Print each turn. |
 
-Four flags are accepted and reported as not applied by this release, rather than
-silently ignored: `--budget-usd` and `--quality` (the budget and the model tier
-are the server's, enforced at the proxy), `--offline-upload` (uploads already
-queue) and `--build-dir` (serve the build and pass `--build-url`).
+Three flags are accepted and reported as not applied by this release, rather
+than silently ignored: `--quality` (the model tier is the server's, enforced at
+the proxy), `--offline-upload` (uploads already queue) and `--build-dir` (serve
+the build and pass `--build-url`). There is no spending flag: each run's model
+budget is set by the server from what the job was charged, and `--budget-usd` is
+an unknown option (the refusal says where the budget comes from).
+
+Each run hands its playtest identity to the game, so the game's own Ravensight
+events from a playtest are marked synthetic rather than counted as a player. A
+Godot game reads it from its environment. A web game's JavaScript SDK reads it
+from the page: the browser driver sets `window.__RAVENSIGHT_PLAYTEST__` and
+`localStorage['ravensight.playtest']` before the game's scripts run. It is never
+sent as a request header, which would reach your game's own API too.
+
+When a run reaches its model budget before the report step, nothing more is
+asked of the model. The persona's notes are written to a partial `report.json`
+(`partial: true`, one unreviewed finding per note with the nearest screenshot as
+evidence) and uploaded, so the job's aggregate still counts them.
 
 ### fix
 
@@ -465,3 +522,29 @@ import { createClient, packs, uploadRunDir } from 'ravensight-playtest';
 ## License
 
 MIT. Copyright Reality Software Entertainment.
+
+## Ravensight Playtester action selection
+
+The optional `--controller jev` mode uses the existing persona run. A screenshot
+observer proposes actions, Ravensight selects one on the server, and the local
+driver executes only that choice. Ambiguous controls stop the run for review.
+Reports, screenshots and findings use the normal upload and review flow.
+
+```sh
+ravensight-playtest run --driver playwright_web --controller jev --build-url https://your-game.example/ --max-actions 12 --headed
+```
+
+Sign in, initialize the project and save its expectations brief first. The server
+must advertise this controller in its content pack; otherwise the command stops
+before registering a paid job. No provider key belongs in the CLI. Selection costs
+share the existing persona-run budget and do not create another wallet charge.
+Resume preserves the controller recorded in the job journal.
+
+For Jump Bunny, use `https://reality-software-entertainment.github.io/poc-jump-bunny/`
+and the public player label **Ravensight Playtester**. This is a local browser run,
+not a hosted browser service. Human playtesting is still needed for subjective
+feedback and timing-sensitive gameplay.
+
+## Build adapters
+
+Browser and Godot runners share the paid playtest lifecycle with desktop, Unity/Unreal export, Android/iOS and custom JSON-RPC adapters. Native adapters require a locally configured automation server and remain experimental until validated against your build. See [adapter setup and validation boundaries](docs/ADAPTERS.md).

package/docs/ADAPTERS.md

@@ -0,0 +1,77 @@
+# Connect a game to Ravensight Playtester
+
+Run the CLI on the machine that can access your build. Sign in, link the project with `ravensight-playtest init --game <gameId>`, and complete its expectations brief. `run` quotes the existing persona price before registration. Adapters share the same prepaid job, action limits, model budget, cancellation, reports and uploads.
+
+| Adapter | Target | Validation |
+| --- | --- | --- |
+| `playwright_web` | Browser URL, including canvas/WebGL exports | Automated tests and live Jump Bunny gameplay |
+| `godot_driver` | Godot project with the playtest addon | Existing addon protocol and runner tests |
+| `desktop_driver` | Local W3C/Appium session configuration | Protocol tested; experimental on physical builds |
+| `unity_driver`, `unreal_driver` | Desktop exports through that same W3C interface | Engine-neutral screen controls, not editor plugins; experimental |
+| `android_driver`, `ios_driver` | Appium device/emulator/simulator configuration | Protocol tested; hardware/build validation still required |
+| `cli_stdio` | Developer-owned JSON-RPC bridge | Real child-process protocol test |
+
+No adapter promises every game is autonomously solvable. Fast action games, unusual controls, anti-cheat, hardware access and protected platforms may require a game-specific bridge. Console tooling and authorization remain the developer's responsibility. The runner cannot bypass platform access restrictions.
+
+## Browser and Godot
+
+```sh
+ravensight-playtest run --driver playwright_web --build-url https://your-game.example/ --headed
+ravensight-playtest run --driver godot_driver --godot-project ./your-game
+```
+
+`--controller jev` enables structured action selection when the server supports it. Screen interpretation proposes controls and the selector chooses a supplied action. Uncertain decisions stop for review. Provider credentials stay on Ravensight. A completed playtest report is evidence for human review, not proof that a game is bug-free.
+
+## Desktop and mobile
+
+Install and configure an Appium-compatible driver for your platform. Start its server locally. Supply `ravensight-driver.json` with a loopback endpoint and capabilities appropriate to the installed driver:
+
+```json
+{
+  "endpoint": "http://127.0.0.1:4723",
+  "capabilities": {
+    "platformName": "Android",
+    "appium:automationName": "UiAutomator2",
+    "appium:deviceName": "YOUR_LOCAL_DEVICE",
+    "appium:app": "/absolute/path/to/game.apk"
+  }
+}
+```
+
+```sh
+ravensight-playtest run --driver android_driver --driver-config ./ravensight-driver.json
+```
+
+For iOS, use `ios_driver`, `platformName: iOS`, your XCUITest driver and a provisioned device or simulator. For desktop, use the capabilities required by your installed desktop driver. Unity/Unreal exports use `unity_driver`/`unreal_driver`; no engine source is uploaded by this configuration. Configuration files are local and should not contain provider credentials. Do not expose the automation server publicly.
+
+The runner creates a W3C session, reads page source plus PNG screenshots, and executes bounded coordinate clicks, keys, text and single-pointer swipes. It releases input after each action and closes the session when done. One persona uses the device at a time. Native adapters currently capture screenshots, not video or engine logs. Browser navigation is unavailable on these adapters. Model-visible text is limited to 12,000 characters; responses are bounded to 8 MB and commands time out after 30 seconds.
+
+## Custom bridge
+
+Use this for text games or your own engine/hardware integration. `--driver-config` points to:
+
+```json
+{
+  "command": "/absolute/path/to/bridge-executable",
+  "args": ["--game", "/absolute/path/to/build"],
+  "cwd": "/absolute/path/to/project"
+}
+```
+
+The configured executable is trusted local code chosen by the developer. The model cannot change it. It runs without a shell. Standard output must contain newline-delimited JSON-RPC 2.0 responses. Put diagnostics on stderr. Respond with the request ID and `result`, or an `error`:
+
+```json
+{"jsonrpc":"2.0","id":1,"method":"launch","params":{"protocolVersion":1}}
+{"jsonrpc":"2.0","id":1,"result":{"ok":true}}
+```
+
+Required methods:
+
+- `launch`: initialize/reset the game; return `{ "ok": true }`.
+- `observe`: return `{ "text": "visible state" }`, optionally `screenshotBase64` containing PNG data.
+- `act`: accept a `kind` of `key`, `type`, `click` or `wait`; return `{ "ok": true }` after execution. Apply your own game-specific legality checks. Never interpret model text as shell code.
+- `screenshot`: return `{ "pngBase64": "..." }`, or a JSON-RPC error if unavailable. Text-only games can still produce text reports without screenshots.
+
+Requests expire after 30 seconds. Oversized or malformed responses stop the bridge. The runner terminates its child when the session ends; the bridge must clean up any game processes it owns on termination. No custom protocol can establish compatibility with untested hardware by itself.
+
+Protocol references: [W3C WebDriver](https://www.w3.org/TR/webdriver/), [Appium capabilities](https://appium.io/docs/en/3.2/guides/caps/).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ravensight-playtest",
-  "version": "0.2.3",
+  "version": "0.2.5",
   "description": "AI personas play your game and file reports to Ravensight.",
   "license": "MIT",
   "homepage": "https://ravensight.io/docs/#playtest",
@@ -25,6 +25,7 @@
     "bin",
     "src",
     "addons",
+    "docs/ADAPTERS.md",
     "README.md",
     "LICENSE",
     "!src/**/*.test.js",

package/src/cli.js

@@ -50,14 +50,15 @@ async function loadRunner(name, exportName) {
  * Kept in the same order as `VALUED` and `BOOLEAN` in src/run/args.js, which is
  * the list it has to agree with.
  */
-const RUNNER_HELP = `
+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
-  --driver <name>           playwright_web or godot_driver
+  --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
-  --cli <command>           the command that starts a text build
-  --max-actions <n>         cap the actions one persona may take
+  --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
   --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,7 +68,10 @@ Run options (parsed by the runner, see src/run/args.js):
   --verbose                 print each turn
 
 Accepted and reported as not applied by this release:
-  --budget-usd, --quality, --offline-upload, --build-dir
+  --quality, --offline-upload, --build-dir
+
+There is no spending flag: each run's model budget is set by the server from
+what the job was charged.
 `;
 
 /** Flags every command shares. */
@@ -156,13 +160,15 @@ export function buildProgram() {
     .addOption(new Option('--modules <list>', 'price this module list').argParser(list))
     .addOption(new Option('--personas <list>', 'price this persona list').argParser(list))
     .option('--godot-path <path>', 'where Godot is, if it is not on the PATH')
+    .option('--web', 'check the browser even when this repo is not linked to a web build')
     .action(capture(slot, async options => {
       const { check } = await import('./commands/check.js');
       return check(flagsFrom(options, {
         game: options.game,
         modules: options.modules,
         personas: options.personas,
-        godotPath: options.godotPath
+        godotPath: options.godotPath,
+        web: Boolean(options.web)
       }));
     }));
 

package/src/commands/check.js

@@ -19,6 +19,75 @@ const row = (name, status, detail, fix = null) => ({ name, status, detail, fix }
 /** "1 persona", "3 personas". A doctor that cannot count reads like a draft. */
 const plural = (count, noun) => `${count} ${noun}${count === 1 ? '' : 's'}`;
 
+/** The two commands that make the playwright_web driver work. */
+export const BROWSER_FIX = 'npm i -D playwright && npx playwright install chromium';
+
+/**
+ * The repo config, for deciding whether this is a web game. A config that
+ * cannot be read is reported by the rows that need it, not here.
+ *
+ * @param {Object} flags
+ * @returns {Promise<Object|null>}
+ */
+async function configForBrowser(flags) {
+  if (flags.config !== undefined) return flags.config;
+  try {
+    return await loadConfig({ repoRoot: flags.repoRoot });
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * How much a missing browser matters here, or null when the row is skipped.
+ *
+ * `fail` when `--web` asks for it or the linked build is a URL: a web run
+ * cannot start without one. `warn` when only the configured driver says
+ * `playwright_web` and no build is linked yet, because that is the untouched
+ * default `init` writes, and a Godot developer who never changed it must not
+ * get exit 3 over a browser they will never launch. Skipped otherwise.
+ *
+ * @param {Object} flags
+ * @param {Object|null} config
+ * @returns {'fail'|'warn'|null}
+ */
+export function browserSeverity(flags, config) {
+  if (flags.web) return 'fail';
+  if (!config) return null;
+  const kind = config.build && config.build.kind;
+  if (kind === 'url') return 'fail';
+  if (kind) return null;
+  return config.driver === 'playwright_web' ? 'warn' : null;
+}
+
+/**
+ * Import Playwright, launch headless Chromium, close it. The same three steps
+ * a web run starts with, so a pass here means the run will get a browser.
+ *
+ * @param {(specifier: string) => Promise<any>} [importer] test seam
+ * @returns {Promise<{ok: boolean, detail: string}>}
+ */
+export async function probeBrowser(importer) {
+  const load = importer || (specifier => import(specifier));
+  let browser = null;
+  try {
+    const playwright = await load('playwright');
+    browser = await playwright.chromium.launch({ headless: true });
+    const version = typeof browser.version === 'function' ? browser.version() : '';
+    return { ok: true, detail: `chromium ${version}`.trim() + ' launched headless' };
+  } catch (error) {
+    return { ok: false, detail: String(error && error.message ? error.message : error).split('\n')[0] };
+  } finally {
+    if (browser) {
+      try {
+        await browser.close();
+      } catch {
+        // A browser that will not close still launched, which is what was asked.
+      }
+    }
+  }
+}
+
 /**
  * Every environment check, as data.
  *
@@ -37,6 +106,7 @@ const plural = (count, noun) => `${count} ${noun}${count === 1 ? '' : 's'}`;
  * @param {string[]} [flags.modules]
  * @param {string[]} [flags.personas]
  * @param {string} [flags.repoRoot]
+ * @param {boolean} [flags.web] probe the browser whatever the config says
  * @param {Object} [deps]
  * @returns {Promise<{rows: Array, ok: boolean}>}
  */
@@ -243,6 +313,17 @@ export async function runChecks(flags = {}, deps = {}) {
     'needed only to re-encode a session video before upload'
   ));
 
+  const browserNeed = browserSeverity(flags, await configForBrowser(flags));
+  if (browserNeed) {
+    const probe = await probeBrowser(deps.importer);
+    rows.push(row(
+      'browser',
+      probe.ok ? 'ok' : browserNeed,
+      probe.detail,
+      probe.ok ? null : BROWSER_FIX
+    ));
+  }
+
   const godot = await (deps.inspectGodot || inspectGodot)(
     { repoRoot, godotPath: flags.godotPath },
     deps

package/src/commands/fix.js

@@ -1,7 +1,7 @@
 import { randomUUID } from 'node:crypto';
 import { appendFile, mkdir, readdir, readFile, writeFile } from 'node:fs/promises';
 import path from 'node:path';
-import { optionsFrom } from '../run/args.js';
+import { optionsFrom, unknownOptionNotes } from '../run/args.js';
 import { getDeps } from '../run/deps.js';
 import { createDriver } from '../run/drivers/index.js';
 import EXIT from '../run/exit.js';
@@ -15,7 +15,7 @@ import { createRepoTools, PROFILE_TOOLS } from '../run/repoTools.js';
 import { assertNoSecrets } from '../run/secretScan.js';
 import * as stateFile from '../run/state.js';
 import { createUsageLedger, writeUsageFile } from '../run/usage.js';
-import { createInterruptHandler, deliver, exitCodeFor, explainRegisterRefusal, formatCents, resolveSetup, resolveTarget, skillFor } from './run.js';
+import { createInterruptHandler, deliver, driverOptions, exitCodeFor, explainRegisterRefusal, formatCents, resolveSetup, resolveTarget, skillFor } from './run.js';
 
 /**
  * `ravensight-playtest fix <target>`: take one finding, change the code on a
@@ -155,6 +155,7 @@ async function fix(target, flags, injected, deps, log) {
   const { options, unknown } = optionsFrom(flags);
   if (unknown.length > 0) {
     log(`I do not know these options: ${unknown.join(', ')}. Run "ravensight-playtest fix --help".`);
+    for (const line of unknownOptionNotes(unknown)) log(line);
     return EXIT.ENVIRONMENT;
   }
   const parsed = parseTarget(target);
@@ -506,6 +507,7 @@ async function fix(target, flags, injected, deps, log) {
         repoRoot,
         entry: verifyRun,
         pack,
+        brief,
         finding,
         driverName,
         target: buildTarget,
@@ -752,6 +754,7 @@ export async function runVerify({
   repoRoot,
   entry,
   pack,
+  brief = null,
   finding,
   driverName,
   target,
@@ -769,7 +772,7 @@ export async function runVerify({
     return null;
   }
   const headless = driverName === 'godot_driver' ? options.headless === true : options.headed !== true;
-  const driver = await makeDriver(driverName, { headless });
+  const driver = await makeDriver(driverName, driverOptions({ headless, driverName, target, directory, entry, jobId }));
   const ledger = createUsageLedger();
   const heartbeat = createHeartbeat({
     api,
@@ -796,7 +799,8 @@ export async function runVerify({
       target,
       runDirectory: directory,
       skill: skillFor(pack, 'persona_playtest'),
-      brief: verifyBrief(pack.brief || null, finding),
+      // The brief fetched above, as `run` does: the pack does not always carry one.
+      brief: verifyBrief(brief || pack.brief || null, finding),
       intentNotes: pack.intent_notes || [],
       schemas: pack.schemas || [],
       maxActions,

package/src/commands/init.js

@@ -37,7 +37,8 @@ export async function ensureGitignore(repoRoot) {
 /**
  * `ravensight-playtest init --game <gameId>`
  *
- * Link this repo to a Ravensight game.
+ * Link this repo to a Ravensight game. Without `--game`, one visible game is
+ * used as is, and several are offered as a numbered list on a terminal.
  *
  * The game is checked against `whoami` before anything is written, because the
  * alternative is a config that looks right and fails on the first job with a
@@ -45,7 +46,7 @@ export async function ensureGitignore(repoRoot) {
  * authority: an unapproved game is invisible to it, by design.
  *
  * @param {{game?: string, apiUrl?: string, repoRoot?: string, force?: boolean, json?: boolean}} flags
- * @param {Object} [deps]
+ * @param {{context?: Object, choose?: Function}} [deps]
  * @returns {Promise<number>}
  */
 export async function init(flags = {}, deps = {}) {
@@ -58,15 +59,39 @@ export async function init(flags = {}, deps = {}) {
   // Every API call in this command goes through the one 401 handler, so a
   // refused credential is cleared and explained here the same way it is
   // everywhere else.
-  return withAuthHandling(context, () => linkRepo(context, flags, repoRoot));
+  return withAuthHandling(context, () => linkRepo(context, flags, repoRoot, deps.choose || ui.choose));
 }
 
-async function linkRepo(context, flags, repoRoot) {
+/**
+ * @param {Object} context
+ * @param {Object} flags
+ * @param {string} repoRoot
+ * @param {(question: string, labels: Array<string>) => Promise<number|null>} choose
+ *   the picker; answers null when there is no terminal to ask on
+ */
+async function linkRepo(context, flags, repoRoot, choose) {
   const whoami = await context.api.cli.whoami();
 
   const games = whoami.games || [];
   let gameId = flags.game;
 
+  if (!gameId && games.length === 0) {
+    throw new CliError(
+      'This token can see no games, so there is nothing to link.',
+      1,
+      { hint: 'Create a game in the dashboard, then run login again and approve it for this token.' }
+    );
+  }
+
+  // Never under --json: whatever reads that output is a script, not a person.
+  if (!gameId && games.length > 1 && !flags.json) {
+    // On a terminal, ask. Anywhere else (CI, a pipe) the picker answers null
+    // and the command falls through to the list and the --game error, which
+    // is what a script needs to see.
+    const picked = await choose(`Which game? [1-${games.length}]`, games.map(game => `${game.name || game.gameId} (${game.gameId})`));
+    if (Number.isInteger(picked) && games[picked]) gameId = games[picked].gameId;
+  }
+
   if (!gameId) {
     if (games.length === 1) {
       gameId = games[0].gameId;

package/src/commands/profile.js

@@ -1,6 +1,6 @@
 import { randomUUID } from 'node:crypto';
 import { mkdir } from 'node:fs/promises';
-import { optionsFrom } from '../run/args.js';
+import { optionsFrom, unknownOptionNotes } from '../run/args.js';
 import { getDeps } from '../run/deps.js';
 import EXIT from '../run/exit.js';
 import { createHeartbeat } from '../run/heartbeat.js';
@@ -55,6 +55,7 @@ async function profile(flags, injected, deps, log) {
   const { options, unknown } = optionsFrom(flags);
   if (unknown.length > 0) {
     log(`I do not know these options: ${unknown.join(', ')}.`);
+    for (const line of unknownOptionNotes(unknown)) log(line);
     return EXIT.ENVIRONMENT;
   }