ravensight-playtest 0.5.2 → 0.7.0

package/README.md

@@ -57,8 +57,8 @@ progression checks through your own game adapter. It runs locally without
 model calls and saves bounded results to the same Playtest workspace. See
 [Simulation Runner](docs/SIMULATION.md) for setup.
 
-You need a Ravensight account and Node 22 or newer. You do not need an
-Anthropic API key: model calls go through Ravensight under the same token you
+You need a Ravensight account and Node 22 or newer. You do not need a model
+provider's API key: model calls go through Ravensight under the same token you
 log in with, so there is one credential on your machine and you can revoke it
 from the dashboard.
 
@@ -123,7 +123,7 @@ In CI, set `RAVENSIGHT_TOKEN` instead and skip `login` entirely.
 
 ## Commands
 
-Thirteen commands. Flags below are the ones the code accepts, not the ones the
+Fourteen 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:
@@ -274,6 +274,11 @@ login).
 | `--game <gameId>` | The game to link. Optional with one visible game, or in a terminal. |
 | `--force` | Relink a repo that is already linked. |
 
+A repository with a `project.godot` at its root is linked with `driver:
+godot_driver` and `build: { kind: godot_project, ref: "." }`, so `run` needs no
+`--driver` or `--godot-project`. The concurrency written is the one `check`
+recommends for this machine.
+
 ### personas
 
 Lists the persona slugs `--personas` accepts, from the content pack this game
@@ -415,13 +420,15 @@ splitting the job in two is what gets everything played.
 | `--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. |
+| `--godot-project <dir>` | The Godot project directory. A relative path is read from the repository root. |
+| `--godot-path <path>` | Where Godot is, if it is not on the PATH. `RAVENSIGHT_GODOT` does the same. |
+| `--realtime` | `godot_driver` only: let the game run in real time between actions. By default the game is paused while the persona decides and runs only while an action executes. |
 | `--driver-config <file>` | The native driver config, or the JSON-RPC bridge config for `cli_stdio`. |
 | `--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. |
+| `--concurrency <n>` | Personas at once. Default the number `init` wrote, which is what `check` recommends for this machine. |
 | `--controller <name>` | One playthrough using `standard` or an available System One controller. The server must advertise and quote that exact choice. |
 | `--compare-with jev` | Separate agent/skill and Jev playthroughs for each chosen persona. Shows their combined quote before purchase. Comparisons run one playthrough at a time. |
 | `--record-video` | Capture the selected web or graphical Godot game locally. Does not upload the video. |
@@ -616,6 +623,14 @@ ravensight-playtest fix fnd_7g3k --no-verify
 The target is either `<jobId>/<label>`, where the label is the one the report
 gives the finding, or a bare finding id.
 
+It can also be a punch list or blue tape item, `li_...`, when the item came
+from a finding or a fresh-eyes finding.
+The fix then runs exactly as it does for that finding, at the same price. After
+the job registers, the job id is recorded on the item. The item stays open
+until you close it. An item that did not come from a finding is refused before
+anything is charged; `feature` is the tool for that item. See
+[Punch list and blue tape](#punch-list-and-blue-tape-labs-beta).
+
 | Flag | Effect |
 |---|---|
 | `--game <gameId>` | The game, when this repo is not linked. |
@@ -625,6 +640,11 @@ gives the finding, or a bare finding id.
 | `--max-actions <n>` | Cap the turns the fix may spend. Capped at 60 whatever you ask for. |
 | `--build-url <url>`, `--godot-project <dir>`, `--driver <name>` | Where the verify run plays, resolved exactly as `run` resolves them. |
 | `--json` | Print the changeset instead of the summary. |
+| `--open-pr` | Fix v2 (Labs beta) only. After a fix the verify scored as fixed, ask, then commit the fix's files, push the branch and open a pull request with the evidence report. |
+| `--no-labs` | Run the ordinary fix even when Fix v2 is on for the game. |
+| `--allow-tests` | Fix v2: let the checks run the project's GUT or gdUnit4 tests, and run on edits to test files. Asked at a terminal when not given. |
+| `--allow-tool-scripts` | Fix v2: let the checks import a project whose edits touched `project.godot`, `export_presets.cfg`, `override.cfg`, `addons/`, `.godot/` or a `@tool` script. |
+| `--godot-path <file>` | The Godot binary for the verify run and the Fix v2 checks. |
 
 What happens, in order:
 
@@ -643,15 +663,21 @@ What happens, in order:
 7. `changeset.json` and `report.md` are written, uploaded and attached to the
    fix run, and the pull request command is printed.
 
-**It never pushes and never commits.** There is no `git commit`, no `git push`
-and no forge client anywhere in the command. You are left on the branch with
+**It never pushes and never commits** unless you pass `--open-pr` to a Fix v2
+attempt and answer yes at its prompt (see below). You are left on the branch with
 the change in your working tree, and the last thing printed is the command to
 open the pull request once you have read the diff.
 
-A fix attempt is one unit. It is refunded when the finding turns out to be
-design intent, and refunded when the attempt changes nothing, in both cases
-without a model turn being spent on the edit itself. The verify run is included
-in the price.
+A fix attempt is one unit, refunded in full in three cases: the finding turns
+out to be design intent, the attempt changes nothing, or the game did not boot
+for the verify run, in which case the $5.00 comes back because the fix could
+not be verified. The verify run is included in the price, and the CLI always
+completes the verify run before the fix run so the server can read it.
+
+An account gets 5 refunds in any 30 days of a fix attempt that used model time,
+counting a cancel or any other failure. Past that the attempt is kept, and the CLI
+prints the server's note saying so instead of a refund. An attempt that used no model
+time always comes back. A persona run has the same rule with 20 refunds, and a game profile with 5.
 
 **A verify can only mean something against a build this machine serves.** The
 change exists in your working tree and nowhere else, so a `--build-url`
@@ -663,6 +689,90 @@ branch locally before the verify, or skip it.
 The verdict is printed in words: fixed below 0.35, still reproduced above 0.65,
 unknown in between, and "not verified" when there was no verify run.
 
+#### Fix v2 (Labs beta)
+
+When Ravensight Labs is on for the game and the server reports Fix v2 as live,
+`fix` adds four things. Without that answer from the server, `fix` is exactly
+the command described above.
+
+- **An acceptance contract before any edit.** The CLI writes
+  `{ expected, actual, reproSteps, regressionPersonas }` from the finding,
+  prints it before the price, and sends it when the job is registered. The
+  server freezes it on the job. The apply step reads it and cannot change it,
+  and the verify brief is built from it alone. If the server does not freeze
+  it, the attempt carries on as an ordinary fix and says so.
+- **Named checks, never a shell.** The apply step may call `run_check` with one
+  of three names, and the CLI runs all three after every apply:
+
+  | Check | What runs |
+  |---|---|
+  | `godot_import` | `godot --headless --path <copy> --import`, then every script error in the log |
+  | `godot_script_check` | `--check-only` on each changed `.gd` file, after the import |
+  | `project_tests` | GUT (`addons/gut`) or gdUnit4 (`addons/gdUnit4`), whichever the project ships |
+
+  Each runs on a fresh temporary copy of the project (no `.git`, no
+  `.ravensight`), with a time limit and an output cap, and the copy is
+  deleted afterwards. A check that cannot run (no Godot, no tests) is reported
+  as unavailable, not as passed. **A fix whose `godot_import` or
+  `godot_script_check` still fails after its repairs is never uploaded:** the
+  fix run is completed as failed, the unit comes back, the edit stays on the
+  branch and the evidence stays in the run directory. Project tests that still
+  fail do not block: the change uploads, the unit is kept, and the report's
+  first line and the terminal name the failing checks.
+- **What a fix can never touch.** The model's tools refuse, whatever a file in
+  the repository asks for: anything outside the repository or through a symbolic
+  link; `.git`; credential files by name (`.env`, keys, `.netrc`, `secrets.json`,
+  `export_presets.cfg` and the like); gitignored files, which are neither read nor
+  written because git would never show the change; a nested repository or
+  submodule; git's own controls, hooks and CI (`.gitignore`, `.gitattributes`,
+  `.husky`, `.github/workflows`, the directory `core.hooksPath` names and so on);
+  art, audio and anything that is not UTF-8 text; and a file name with control or
+  invisible characters. Each refusal goes back to the model as an answer.
+- **What runs on your machine.** The checks and the verify run execute the
+  edited project on this machine, and the price confirmation says so. A
+  Godot import runs editor-side code, and tests run your test code with the
+  model's edits in place, so:
+  - every check gets a reduced environment: `PATH` and the locale from yours,
+    and `HOME`, the temp directories and Godot's user-data directory pointed
+    into the check's own temp root. No token, provider key, SSH agent, cloud
+    or GitHub credential is passed on. The verify run's Godot gets the
+    driver's own short allowlist, as before.
+  - no check runs when the edits touched `project.godot`,
+    `export_presets.cfg`, `override.cfg`, anything under `addons/` or
+    `.godot/`, or a `@tool` script, unless you pass `--allow-tool-scripts`;
+    nor when they touched test files (`test/`, `tests/`, `test_*.gd`,
+    `*Test.gd`, `*_test.gd`, or a directory in `.gutconfig.json`) unless you
+    allow tests. The result is `check_refused`, and the fix is not uploaded.
+  - `project_tests` runs only with `--allow-tests`, or a yes at a terminal;
+    otherwise it is unavailable.
+  - the temp copy leaves out credential files, and a check's process group is
+    killed with it at its time limit and at Ctrl-C
+  - on macOS, when `sandbox-exec` exists, each check runs under a profile
+    that denies all network access and every write outside its temp root.
+    On Linux and Windows no OS sandbox is applied: the reduced environment
+    and the temp copy are the whole of the isolation.
+- **Bounded repair.** A failed check, or a verify that still reproduces the
+  finding (above 0.65), starts one more apply turn set inside the same run
+  budget, with the failure in front of the model and the contract unchanged.
+  At most two repairs. A repair after a verify needs a spare verify run from
+  the server to judge it; without one the result is reported, not repaired.
+- **An evidence report as the pull request body.** `report.md` carries the
+  contract, the checks with their results and times, the files, the verify
+  before and after, the remaining risks, and keeps verified facts (what the
+  CLI and git measured) apart from model judgement (the hypothesis, the
+  description, the verify score).
+
+`--open-pr` is the one way this command pushes. It needs Fix v2, a verify that
+scored the fix as fixed, `gh auth status` to pass and a yes at its own prompt
+(`--yes` agrees to the price, not to publishing). It commits only the files the
+fix changed, pushes with a plain `git push -u origin <branch>`, never forced,
+and runs `gh pr create` with the evidence report as the body. Later runs in this
+repository check that pull request with your own `gh`, in the background, and tell
+the job whether it was merged, reverted or abandoned. The URL stays in the local
+journal, the check never holds up or fails a command, and no charge or refund reads
+the answer. A revert pushed directly rather than through a pull request reads as
+merged.
+
 **A fix cannot be resumed.** Ctrl-C, or cancelling the job from the dashboard,
 abandons the attempt and gives the unit back: whatever was written stays on the
 branch for you to read or delete, and nothing is committed. That is different
@@ -859,12 +969,14 @@ reasoning, exactly as `profile` already does, and the same guards apply: a file
 that trips the secret scan is withheld rather than read, and both files a fix
 writes are scanned again before they are uploaded.
 
+Your art and audio stay on your machine. The `assets` command sends nothing. During a `feature` job the model reads, through the same proxy, a list of each asset's path, type, size and measurements, and a model can never read an art or audio file's content. What uploads with the job is `changeset.json` and `report.md` as for a fix, plus how many files, how many used and unused, and how many of each kind of warning, in `report.md`, with no file names. The model writes the pull request text in `report.md`, so it may name a file it used. Placeholders are uploaded by name, because they are what you are being asked to supply. `assets-report.md` and `assets.json`, which name every file, are not on the allowlist.
+
 Run `upload --dry-upload` or `run --dry-upload` to see the exact file list and
 byte count before anything leaves the machine.
 
-Model calls go to Ravensight's proxy rather than to Anthropic, under the token
-you logged in with. No Anthropic key exists on your machine, and the CLI builds
-its client with `apiKey` explicitly null, so an `ANTHROPIC_API_KEY` already in
+Model calls go to Ravensight's proxy rather than to a model provider, under the
+token you logged in with. No provider key exists on your machine, and the CLI
+builds its client with `apiKey` explicitly null, so a provider key already in
 your environment is never picked up and never sent anywhere.
 
 Before anything is written to a run directory, the transcript and `usage.json`
@@ -994,6 +1106,199 @@ feedback and timing-sensitive gameplay.
 
 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) and the [native runner starter](docs/NATIVE_RUNNER.md); `check` probes the automation server for free before a paid native run.
 
+## Validate changes (Labs beta)
+
+Godot only, and only when Ravensight Labs is on for the game. Plays a branch and its base with the same personas on the same seeds and compares them. Your source stays on your machine; the commits are extracted to temp directories, and both must start before a price is shown.
+
+```sh
+ravensight-playtest validate my-branch --base main --runs 5
+ravensight-playtest replay <runId> --ref my-branch --baseline
+```
+
+Each persona run is one standard Playtest purchase of 5 AI units, and the whole plan is charged once at the start. Below five runs a side the result says not significant and shows a direction only. A run that does not earn its unit is refunded and does not count in the comparison. If one side ends with no usable run there is nothing to compare, and the runs on the other side that played and reported keep their units, because those runs happened and their reports are real. `--extend-to <n>` buys more pairs only when the first answer was too small to call. `--fail-on-regression` exits 1 for CI. A replay makes no model call and is free. See [what a replay does and does not prove](docs/REPLAY.md).
+
+## Create a game (Labs, Experimental)
+
+Godot 2D only, and only when the platform has Create a game switched on. It is for owners and admins, and for an account that has added at least $10 in top-ups. The balance has to reach the plan's start balance, the whole plan's price plus 25 percent, at least $2 extra, rounded up to a whole dollar, and only the price is charged. The balance has to cover the whole plan you declare, and the command shows that total before you confirm. It may not produce a game you want.
+
+```bash
+ravensight-playtest create "A keeper walks a dark hall and lights each lamp in turn" --name "Lantern Sweep" --milestones 3 --size medium
+# read the design and approve it in the dashboard, then, from the project folder:
+ravensight-playtest create <job-id>
+```
+
+The first command makes a new game, with its key in `ravensight_key.cfg`, which git ignores, and asks for a game design. A person approves or rejects that in the dashboard. Rejecting it gives the whole charge back, within the refund limit below. To change a design, reject it and start again from a better brief.
+
+The second command writes the scaffold and checks in Godot that it imports and starts. Then it builds one milestone at a time, each an ordinary Build a feature job with its own charge, refund rules and branch, landing on `main` when it validates. A milestone that does not validate stops the run: its branch holds the attempt, and the same command tries again, which uses up another declared milestone if that attempt kept its charge. The run always stops at the declared count, however many milestones the design lists.
+
+When every declared milestone has validated, a persona plays the finished game. Playable means Ravensight's own records show that run finished cleanly, and the game itself reports at least one completed core loop. A persona is a model playing the game, not a player, so play it yourself before you ship it.
+
+**Stopping.** Ctrl-C, or `create <job-id> --stop` later, closes the plan. What finished stays paid for, the playable check comes back if it never started, and a milestone that was never started was never charged. If the process dies without that, run the same command to carry on. A plan left alone closes after 14 days.
+
+**The refund limit.** Once the model has been used on a plan, an account can get its first charge back twice in any 30 days. Past that, a brief that is declined, a design you reject and a plan that stops before its scaffold boots all keep that charge, and the plan's page and this command say so. The persona run that never played still comes back. The command states how many you have left before you confirm.
+
+**The hourly limit.** A studio has an hourly model spend limit, and a large milestone's budget can pass it. The job pauses until the top of the next hour, says how long, and carries on. Ctrl-C ends the wait. The wait costs no model time, but it does count toward the run's own time limit, so a run that passes that limit while it waits stops there and its job's refund rules apply.
+
+**Your own art and audio.** Ravensight does not make any. The first command says where the files go, inside the new project: `assets`, or the folder you name with `--assets-dir`. Put them there before the second command, and each milestone reads what was measured about them and can use them, as in [Your own art and audio](#your-own-art-and-audio). Anything missing stays a placeholder. If you add files after the scaffold is written, commit them before you carry on, because a milestone only starts from a clean tree.
+
+**The scaffold** is a Godot 4 2D project from the template in this package, with the public Ravensight SDK unmodified, a key loader, a player opt-out in its settings, build-time key injection for a public build, events that always say what they mean through `rs_kind`, and a `_ravensight_state()` node a playtest reads. Every visual is a placeholder primitive. Studios bring their own art and audio: nothing is generated. `README.md` in the project says how each part works, and `tools/selftest.gd` checks them.
+
+| Flag | What it does |
+|---|---|
+| `--name <title>` | The working title. |
+| `--dir <path>` | Where to make the project, default `./<title>`. It has to be new or empty. |
+| `--milestones <n>` | How many milestones to buy at most, default 3. |
+| `--size <size>` | The largest a milestone may be: `small`, `medium` or `large`. |
+| `--personas <list>` | Persona slugs. |
+| `--godot-path <path>` | Where Godot is, if it is not on the `PATH`. |
+| `--headless` | Play headless: no screenshots, and no mouse or GUI input reaches the game. |
+| `--allow-tool-scripts` | Let the checks import edits to `project.godot`, addons, `.godot` or `@tool` scripts. |
+| `--stop` | Close the plan now. |
+| `--assets-dir <dir>` | The folder inside the project that holds your art and audio, default `assets`. |
+
+## Build a feature (Labs beta)
+
+2D Godot projects only, and only when Ravensight Labs is on for the game and the platform has Build a feature switched on. The specification and the job are separate, so a person approves what will be built before any code is bought.
+
+```sh
+ravensight-playtest feature "Hold shift to sprint, draining stamina that refills at rest"
+# read, edit and approve it on the Labs page in the dashboard, then:
+ravensight-playtest feature <spec-id> --godot-project .
+```
+
+Writing a specification is one AI unit. It covers requirements, acceptance criteria, affected systems, proposed files, the SDK events to add, and up to three test scenarios. A brief bigger than the large size, outside the bounded gameplay systems (movement, health, stamina, inventory, scoring, simple enemy behaviour, HUD widgets), or needing 3D is declined and costs nothing. A CLI token cannot edit or approve a specification.
+
+Building it needs an account that has added at least $10 in top-ups, a clean working tree, and a balance at the plan's start balance (the whole plan's price plus 25 percent, at least $2 extra, rounded up to a whole dollar), shown before you confirm with only the price charged. The plan is a price set by the specification's size, plus one persona run per test scenario, charged once. Everything then happens on your machine, on a new branch that is never committed or pushed for you: plan, edits (at most 8 files for a small feature, 20 for a medium one and 40 for a large one, counted across the repairs too), the named checks, a persona playing each scenario, and a summary. A failed check or a failed scenario starts a repair, at most two, and the specification frozen on the job never moves.
+
+The whole plan comes back if nothing changed or the change does not pass its checks, up to three times in any 30 days per account once a job has used model time. Past that the feature's own price is kept, the command and the job say so, and scenario runs that did not play still come back. A job that used no model time is always refunded. The unit is kept once a change is delivered, verified or not, and the report says which. Verified means the server's own records show every scenario's persona run finished with an accepted report, no script errors and no blocker or major finding; those personas are model players, so play it yourself before you ship it. After a repair, a scenario that already passed replays its recorded inputs for free, and if they no longer replay the same it stops counting as passed.
+
+Studios bring their own art and audio. See [Your own art and audio](#your-own-art-and-audio). If the feature needs an asset the project lacks, it is built with a placeholder primitive and named in the report.
+
+| Flag | Effect |
+|---|---|
+| `--game <gameId>` | The game, when this repo is not linked. |
+| `--assets-dir <dir>` | The folder inside the project that holds your art and audio, default `assets`. |
+| `--branch <name>` | The branch to create, default `ravensight/feature-<title>-<hex>`. |
+| `--personas <list>` | Who plays the scenarios, used in turn. |
+| `--godot-project <dir>`, `--godot-path <path>` | Where the project and Godot are. |
+| `--headless` | Play the scenarios headless: no screenshots, and no mouse or GUI input reaches the game. |
+| `--allow-tests`, `--allow-tool-scripts` | The same two permissions a fix asks for. |
+| `--open-pr` | After a verified feature, ask, then commit its files, push the branch and open a pull request with your own `gh`. |
+| `--max-actions <n>` | A lower ceiling on model turns in the apply loop. |
+
+### Your own art and audio
+
+Ravensight does not make art or audio, and there is no separate price for using yours. Put your files in a folder inside the project, `assets` unless you say otherwise (`--assets-dir`, or `assets_dir` in `.ravensight/config.json`), and a feature uses them.
+
+```sh
+ravensight-playtest assets
+ravensight-playtest assets --assets-dir art --grid 32
+```
+
+`assets` reads that folder on your machine and prints each file with what was measured. It needs no login, sends nothing and costs nothing, so run it as often as you like.
+
+| What | Measured for |
+|---|---|
+| Type and size | Every file |
+| Width, height, transparency, pixel pitch, layout guess (one picture, a tile, a strip or a sheet) | PNG |
+| Format, channels, sample rate, length | WAV and Ogg |
+
+Other formats are listed by type and size only. `--grid <n>` warns about any PNG that does not measure `n` art pixels across.
+
+The warnings come from wiring real art into a real game:
+
+- **The real pixel pitch.** Measured from the pixels, not from what a file was meant to be. A file described as a 32 grid can be 100 or more art pixels across.
+- **Alpha before trimming.** Faint, nearly invisible pixels can reach the edge of the canvas, so a trim keeps almost all of it. The warning gives the box both ways.
+- **Tiles with their own frame.** A frame around each tile draws a grid across the floor. Use tiles with no per-tile frame, or one seamless texture.
+- **Sound Godot will not import.** Opus in an Ogg file, compressed WAV and WAV saved with the extended header.
+- **Smooth filtering on pixel art.** Pixel art blurs when the project's default filter is smooth, unless the node drawing it sets the nearest filter.
+
+During a feature job the model reads a list of those measurements, never the files. It cannot read or quote an art or audio file, and it cannot write one, or anything else in the declared folder except the `.import` settings beside a file. Three more checks join the others: `asset_references` (every asset the change names exists, with that exact case, inside the project), `asset_import` (real Godot imports it) and `pixel_art_settings` (pixel art the change names has the nearest filter and clean import settings). A reference that does not resolve or a file that does not import blocks the change, and the job is refunded, once its repairs are used. A pixel art setting that stays wrong is listed as a risk. Only what the change names can fail a job.
+
+The report says what was wired in, what the project uses, what is unused and which placeholders are left for you to supply. The names are in `assets-report.md` in the run directory, which stays on your machine.
+
+## Punch list and blue tape (Labs beta)
+
+Adding, closing, promoting and drafting need Ravensight Labs on for the game.
+The list commands still read when Labs is off; they show an empty list then.
+The dashboard shows the same two lists.
+
+The punch list holds what has to be finished before handover. You close the
+items one at a time. Blue tape holds small annoyances a new player meets in the
+first minutes. Capture them fast, then promote the ones that matter to the
+punch list.
+
+```sh
+ravensight-playtest punch list                  # open items; --status open|done|dropped|all
+ravensight-playtest punch add "Make the jump button respond on the first press."
+ravensight-playtest punch done li_9f2c
+ravensight-playtest punch drop li_9f2c
+ravensight-playtest punch draft                 # one AI unit; prints proposals, saves nothing
+ravensight-playtest punch draft --accept        # one AI unit; adds every proposal
+
+ravensight-playtest tape "The title music is too loud."
+ravensight-playtest tape list
+ravensight-playtest tape promote li_4a1b        # moves it to the punch list
+ravensight-playtest tape drop li_4a1b
+
+ravensight-playtest fix li_9f2c                 # an item that came from a finding
+```
+
+Reading, adding, closing and promoting are free. `punch draft` proposes items
+from the game's findings and specifications. It costs one AI unit, and nothing
+when there is nothing to propose. Without `--accept` it saves nothing. It asks
+before it spends, so pass `--yes` in a script. A list holds at most 500 open
+items.
+
+Each added item gets a free plain-language check, printed as hints under it:
+long sentences, two instructions in one sentence, passive voice, and words with
+a simpler choice. The hints follow the rules of Simplified Technical English.
+They never block an item.
+
+No command here closes an item for you, including `fix li_...`.
+
+| Flag | Effect |
+|---|---|
+| `--game <gameId>` | The game, when this repo is not linked. |
+| `--status <status>` | `list` only: `open` (the default), `done`, `dropped` or `all`. |
+| `--accept` | `punch draft` only: add every proposal to the punch list. |
+| `--json` | Print the server's answer as JSON. |
+
+### Fresh eyes
+
+A fresh-eyes playtest is a persona run with the `fresh-eyes` persona: a player
+in their first session who reports only small friction. When the job finishes,
+each of its findings becomes an open blue tape item.
+
+```sh
+ravensight-playtest personas                    # check that fresh-eyes is listed for your game
+ravensight-playtest run --personas fresh-eyes
+```
+
+It is priced as any persona run is. Personas come from the content pack the
+server sends, so `fresh-eyes` works once the server lists it. No CLI upgrade is
+needed for it.
+
+## 3D proof of concept (Labs, Alpha)
+
+Labs beta is Godot 2D. There is one 3D template, for trying Build a feature and Validate changes on a 3D project. That is the whole of the Alpha: `create` does not make a 3D game from a brief and refuses to try, and how well a real model builds 3D has not been measured. It has no switch of its own, needing the same Labs opt-in and capability switches, and no price of its own: the jobs cost what they cost on a 2D project.
+
+```sh
+ravensight-playtest template godot-3d --game <gameId> --dir beacon-walk --name "Beacon Walk"
+cd beacon-walk
+ravensight-playtest feature "Each beacon is worth two points" --alpha-3d
+# read, edit and approve it on the Labs page in the dashboard, then:
+ravensight-playtest feature <spec-id> --alpha-3d
+# commit the branch, then:
+ravensight-playtest validate <branch> --base main --alpha-3d
+```
+
+**The template** is a small project of primitive meshes: walk to a beacon, it moves, and that is one pass of the core loop. It has the public Ravensight SDK, unmodified, the same key loader, opt-out and `tools/selftest.gd` as the 2D template, and a `_ravensight_state()` node that reports positions in three axes. It is written with no key, so the SDK does nothing until you add this game's key. Writing it costs nothing and no model is involved.
+
+**`--alpha-3d`** is how you ask. Without it, `feature` and `validate` refuse a project whose main scene has a 3D root, for free. With it on a 2D project they refuse too, and a specification written for one kind of project does not build on the other.
+
+**What works differently.** A persona reads positions as `@(x,y,z)` in world units, and can click a node by its path, where the active camera draws it. It plays with keys and input actions: it cannot steer a camera with the mouse, so a feature that needs mouse look cannot be played by a persona. Headless, as in 2D, no mouse input reaches the game. Your own models are listed by `assets` by type and size, are never read by the model, and the checks confirm that Godot imports the ones a change names. See [docs/REPLAY.md](docs/REPLAY.md) for what replays on 3D.
+
 ## Simulation Runner
 
 Available since `0.4.0`. Simulation Runner requires macOS or Linux (including WSL); native Windows is refused before purchase.