@overcrow/mcp 0.1.0 → 0.1.2

package/dist/content/docs/en/cli.md

@@ -7,11 +7,11 @@ OverCrow runs when it installs and starts a widget: a package it accepts is
 a package OverCrow reads.
 
 ```sh
-overcrow-widget init my-widget --template counter
+overcrow-widget init my-widget --template counter --id nova.my-widget
 cd my-widget
 overcrow-widget check
 overcrow-widget package
-overcrow-widget inspect dist/com.example.my-widget-0.1.0.ocpkg
+overcrow-widget inspect dist/nova.my-widget-0.1.0.ocpkg
 overcrow-widget doctor
 overcrow-widget dev
 overcrow-widget test
@@ -26,10 +26,14 @@ overcrow-widget test
 | [`dev`](#dev) | Runs the widget in OverCrow and reloads it when you save. |
 | [`test`](#test) | Plays the project's test scenarios and compares their images. |
 | [`doctor`](#doctor) | Says what your setup has and lacks. |
-| [`admit`](#admit) | Runs the admission of the marketplace on your submission. |
+| [`admit`](#admit) | Runs the admission of the creator space on your sources, a folder or a ZIP. |
+| [`diff`](#diff) | Compares two versions of a widget's sources. |
+| [`submit`](#submit) | Sends a version to the creator space with a publish key, and follows its checks. |
+| [`status`](#status) | Shows the versions of a widget, their checks and their review. |
 
 Every command takes the project directory as its argument and uses the
-current directory without one.
+current directory without one. [Machine-readable output](#machine-readable-output)
+and [exit status](#exit-status) are stable for scripts.
 
 ## Installing
 
@@ -96,15 +100,15 @@ Keep the version the tool embeds (`overcrow-widget --version`).
 | `logic.ts` or `logic.js` | [The logic](logic.md), one module; bundled with the SDK into `logic.js`. | bundled |
 | `locales/en.json`, `locales/fr.json` | [Messages](logic.md#messages); both or neither, with the same keys. | yes |
 | `LICENSE` | The license text of the package. The templates start with MIT; choose your own. | yes |
-| `assets/` | PNG, JPEG or WebP images; optional. | yes |
+| `assets/` | PNG, JPEG or WebP images; optional. Hidden files (`.DS_Store`) and what the creator tools never send (`dist/`…) are skipped, as in [source archives](#source-archives). | yes |
 | `package.json`, `tsconfig.json` | Tooling only: TypeScript and the SDK types. | no |
-| `listing.json` | The marketplace text of a [submission](publishing.md#the-listing); read by `admit`. | no |
+| `listing.json` | The marketplace text of a [submission](publishing.md#the-listing); read by `admit`. In the creator space, where the listing is edited, only a proposal to import. | no |
 | `tests/` | [Scenarios](testing.md#scenarios) (`tests/<name>.scenario.json`), their reference images (`tests/reference/`) and your unit tests. `tests/output/` holds the images of failed runs. | no |
 
 ## init
 
 ```sh
-overcrow-widget init my-widget --template list --id com.example.my-widget --name "My widget"
+overcrow-widget init my-widget --template list --id nova.my-widget --name "My widget"
 ```
 
 Writes a new project into the directory, which must not exist or must be
@@ -117,8 +121,12 @@ empty: `init` never overwrites a file.
 | `list` | A keyed checklist: `for`, handlers with arguments, `t()` with parameters. |
 | `chart` | A live chart updated by a timer. |
 
-The ID defaults to `com.example.<dir>`; pass `--id` with a reverse-DNS ID
-under a domain you control (`com.playervox.*` is reserved). Every template
+Pass `--id` with your widget's ID: `<handle>.<name>`, your publisher handle
+in the OverCrow creator space and a name (`nova.lol-timers`), or a reverse
+domain you verified and a name (`gg.nova.lol-timers`); see
+[the manifest](manifest.md#identity-and-version). Without `--id`, the ID is
+`yourhandle.<dir>`: replace `yourhandle` before you submit, as `admit`
+refuses it. `com.playervox.*` is reserved. Every template
 comes with a test scenario, `tests/example.scenario.json`, and `counter`,
 `list` and `chart` with its reference images.
 
@@ -158,6 +166,10 @@ overcrow-widget package --out build/my-widget.ocpkg
 Runs `check`, then writes the package to `dist/<id>-<version>.ocpkg`, or to
 `--out`. It prints the path, the size and the SHA-256 of the archive.
 
+With `--source-map FILE`, it also writes [the code map](#the-code-map) of
+`logic.js` to that file. The map never goes into the package: the package
+is the same with or without it.
+
 Packaging is deterministic: the same sources and the same version of the
 tool give the same bytes on every run and every system. What the package
 holds is described in [the package](package.md).
@@ -165,7 +177,7 @@ holds is described in [the package](package.md).
 ## inspect
 
 ```sh
-overcrow-widget inspect dist/com.example.my-widget-0.1.0.ocpkg
+overcrow-widget inspect dist/nova.my-widget-0.1.0.ocpkg
 ```
 
 Validates a package as OverCrow does, then shows it as a reviewer sees it:
@@ -270,37 +282,361 @@ Options: `--format json`, `--deny-warnings`.
 ## admit
 
 ```sh
-overcrow-widget admit
-overcrow-widget admit --package dist/com.example.my-widget-0.1.0.ocpkg
+overcrow-widget admit --publisher nova
+overcrow-widget admit lol-timers.zip --publisher nova --previous lol-timers-1.0.0.ocpkg
+overcrow-widget admit --publisher nova --package dist/nova.my-widget-0.1.0.ocpkg
 ```
 
-Runs the static admission that a marketplace submission goes through,
-exactly as the marketplace runs it. It never runs your code or `tsc`:
+Runs the static admission that the creator space runs on every version you
+send. The sources are the project folder or a ZIP of it, read as the
+creator space receives them ([source archives](#source-archives)). It
+never runs your code or `tsc`:
 
-1. the directory is built as `package` builds it;
+1. the sources are built as `package` builds them;
 2. with `--package`, that archive's compiled view must be byte for byte
    what `view.ocml` compiles to;
-3. the ID is not reserved, `listing.json` is valid, its preview is a
-   packaged PNG of at most 256 KiB;
+3. the ID belongs to the publisher given by `--publisher` (its
+   `<handle>.<name>` IDs, and with `--domain`, the IDs under a domain it
+   verified); without `--publisher`, it is neither reserved, nor an example
+   ID (`nova.*`, `yourhandle.*`, `gg.nova.*`, `com.example.*`…), nor under a
+   handle nobody can register (`admin.*`, `com.*`). `listing.json` is
+   valid, its preview is a packaged PNG of at most 256 KiB;
 4. the authority the widget asks for is listed for the reviewer:
    capabilities (the sensitive ones marked), network routes with their
-   response bound, clipboard writes, storage and game events.
+   response bound, clipboard writes, storage and game events;
+5. with `--previous`, the last approved version (its `manifest.json`, its
+   package, its folder or its ZIP): the ID must be the same and the version
+   higher, and the report lists the
+   [permission keys](#permission-keys) added, widened and removed, and the
+   review the version needs.
 
 | Code | Severity | Meaning |
 | --- | --- | --- |
-| `admission.reserved_id` | error | A `com.playervox.*` ID, reserved for PlayerVox. |
-| `admission.listing_missing`, `admission.listing` | error | No `listing.json`, or one that breaks the listing's rules. |
-| `admission.preview` | error | `preview` does not name a packaged PNG within bounds. |
-| `admission.license` | error | A PlayerVox widget whose license is not MIT. |
+| `admission.reserved_id` | error | A `com.playervox.*` ID, reserved for PlayerVox; without `--publisher`, also an ID under a reserved handle (`playervox.*`, `admin.*`…). |
+| `admission.placeholder_id` | error | An example ID, without `--publisher`. |
+| `admission.id_not_owned` | error | The ID does not belong to the publisher, or, without `--publisher`, cannot belong to any. |
+| `admission.listing_missing`, `admission.listing` | error | No `listing.json`, or one that breaks the listing's rules (a warning with `--listing optional`). |
+| `admission.preview` | error | `preview` does not name a packaged PNG within bounds (a warning with `--listing optional`). |
+| `admission.license` | error | A PlayerVox widget whose license is not MIT (a warning with `--listing optional`). |
 | `admission.view_not_reproducible` | error | The submitted compiled view differs from what `view.ocml` compiles to. |
+| `admission.previous` | error | The previous version cannot be read. |
+| `admission.previous_mismatch` | error | The previous version is another widget. |
+| `admission.version_not_newer` | error | The version is not above the previous one. |
 | `admission.package_rebuilt` | warning | The submitted archive differs from the rebuild in other files. |
 | `admission.not_rebuilt` | warning | An archive was admitted without its sources. |
 
-Options: `--package FILE`, `--out DIR` (writes the admitted package, its
-listing and a report into an empty directory), `--format json`,
-`--deny-warnings`. `admit <file.ocpkg> --listing FILE` checks an archive
-without its sources. Exit status: 0 admitted, 1 refused, 2 on a usage or
-file error. See [publishing and review](publishing.md).
+Options: `--publisher HANDLE`, `--domain DOMAIN` (repeatable), `--previous
+FILE`, `--package FILE`, `--source-map FILE` ([the code map](#the-code-map),
+written when the sources are admitted), `--out DIR` (writes the admitted
+package, its listing and a report into an empty directory), `--format
+json`, `--deny-warnings`. `admit <file.ocpkg> --listing FILE` checks an
+archive without its sources.
+
+`--listing required|optional` is for sources. `required`, the default,
+refuses sources without a valid `listing.json`. `optional` is the creator
+space's way: the listing is edited there, so `listing.json` may be absent,
+and one with a problem is left out (no listing in the report or in
+`--out`) with warnings instead of refusing the sources. Exit status: 0 admitted, 1 refused, 2 on a
+usage or file error. See [publishing and review](publishing.md).
+
+### Permission keys
+
+Each permission has a stable key, the same in the creator space:
+
+| Key | Permission |
+| --- | --- |
+| `network:GET https://api.nova.gg/v1/timers` | A network route: method, origin and path. |
+| `storage` | Storage. |
+| `clipboardWrite` | Clipboard writes. |
+| `capability:<name>` | A capability. |
+| `gameEvent:<name>` | A game event. |
+
+A key is *added* when the previous version did not have it, *widened* when
+its route stays but its rule changes (path or query constraints, response
+bound), and *removed* when it goes. An added or widened key calls for a
+**full** review; otherwise the review is **quick**.
+
+## diff
+
+```sh
+overcrow-widget diff lol-timers-1.0.0.zip .
+overcrow-widget diff old/ new/ --format json
+```
+
+Shows what changed between two versions of a widget's sources, each a
+folder or a ZIP, read as `admit` reads them: the files the creator space
+receives. Files are sorted by path; each added, modified or removed file
+comes with its unified changes (three lines of context) and its added and
+removed line counts. A file that is not UTF-8 text is binary: only its
+SHA-256 is compared. So is a text above 1 MiB or 20,000 lines, or once
+200,000 lines were compared in one diff (`tooLarge`). When both versions have a valid manifest, the
+[permission keys](#permission-keys) the new version adds, widens and
+removes are listed, with the review it needs.
+
+Option: `--format json`. Exit status: 0 when both versions were read,
+whether or not they differ; 1 when one is refused; 2 on a usage or file
+error (a version missing or unreadable).
+
+## submit
+
+```sh
+overcrow-widget submit --dry-run --submission submission.json
+overcrow-widget submit --submission submission.json
+```
+
+Sends a version of your widget to the OverCrow creator space, from a
+terminal, a CI job or the OverCrow MCP server, then follows its checks. It
+never asks a question: what is missing is said, with a stable
+[exit status](#exit-status). It takes the widget folder (the current one
+without argument) or a ZIP of it.
+
+### The publish key
+
+- Create it in the creator space (Publisher, Publish keys). A key can only
+  submit versions of one widget, for 1 to 365 days (90 by default), and is
+  shown once.
+- `submit` and `status` read it from the environment variable
+  `OVERCROW_PUBLISH_KEY`, and only there: never from an argument or a file
+  of the project. In a CI, keep it as a secret.
+- The tool never shows it: any `ocw_pub_…` text is masked in its output,
+  its errors and its logs. Whatever the command, it removes the variable
+  from the environment of the programs it starts (TypeScript, the runtime).
+- A key that expires within 14 days gives a warning. An expired or revoked
+  key ends with status 2: create a new one and replace the secret.
+- Every request names the widget of the sources' `manifest.json` (header
+  `Overcrow-Widget`). A key that covers several widgets of its publisher
+  (reserved to PlayerVox for now) submits the one named; `status` then
+  takes `--widget`.
+
+### What it does
+
+1. It checks the key, and reads what the creator space needs for this
+   widget: the last approved version, the lowest version it takes now, the
+   submissions left (20 over 24 hours), whether the listing has a privacy
+   policy.
+2. It checks exactly what it will send. The folder is zipped as the
+   creator space reads it ([source archives](#source-archives)), read back
+   and admitted as the creator space admits it, `listing.json` being
+   optional; a ZIP given instead is sent byte for byte. The manifest ID
+   must be the key's widget and the version above the last approved one.
+   Each permission the version adds or widens (each permission, for a first
+   version) needs a justification, by its [key](#permission-keys). The
+   texts must follow the creator space's rules. If anything is wrong,
+   nothing is sent (status 1).
+3. It sends the archive, then follows the six checks of the creator space,
+   about a minute: manifest, version number, code analysis, package build,
+   permissions, size and resources.
+4. It ends when the version enters review (status 0), when a check fails
+   (status 1: each problem is shown on the line of your file), or when the
+   version passed its checks but waits in the creator space for what only
+   the creator space takes (status 3): a privacy policy when the widget
+   uses the network, a complete listing for a first version, or the review
+   slot of a new publisher. The link to finish there is shown.
+
+### A version the creator space already has
+
+Before checking anything else, `submit` looks for a version of the same
+number in the creator space. When it has the same sources (byte for byte,
+as `submit` zips them) or, once admitted, the same package, nothing is
+sent: the run ends on that version's state, with `outcome`
+`already_known`.
+
+- Status 0: it is published, approved, in review, or waits for your answer
+  to requested changes.
+- Status 3: it waits in the creator space (the link to finish is shown).
+- Status 1: it failed its checks, was refused, withdrawn or discarded:
+  raise the version in `manifest.json` to send other sources.
+- A version still being checked is followed, as after a submission.
+
+The same number with another package is refused before sending
+(`submit.version_known_differs`): raise the version in `manifest.json`.
+A CI job can therefore run `submit` on every push: a version already sent
+changes nothing.
+
+Ctrl+C while the checks run stops following them; they go on in the
+creator space, and `overcrow-widget status --version 1.3.1 --wait` follows
+them again (status 4). A run cut short before the end (network, Ctrl+C)
+resumes the same submission when you run the same command again; changed
+sources or texts make a new submission. A submission not finished within
+an hour expires, and every submission counts in the daily limit.
+
+| Option | Effect |
+| --- | --- |
+| `--submission FILE` | The texts of the version ([below](#the-texts-file)). |
+| `--release-notes-en TEXT`, `--release-notes-fr TEXT`, `--review-message TEXT` | Replace those of the file. |
+| `--dry-run` | Steps 1 and 2 only, nothing sent: what the creator space will ask for (justifications, privacy policy, review type, lowest version, submissions left) and the archive's SHA-256. For a first version, the creator space also checks the whole listing, which only it knows: a dry run that ends with 0 may still end with 3. |
+| `--expect-sha256 HEX` | Sends only an archive with this SHA-256, the `archive.sha256` of a `--dry-run`: what is sent is what was checked. |
+| `--no-wait` | Ends after the upload (status 4). |
+| `--format json` | One JSON object ([machine-readable output](#machine-readable-output)). |
+| `--verbose` | One line per request on the error output: method, address without its query, status and time; never a header, a key or a body. |
+
+### The texts file
+
+<!-- source: docs/content/examples/weather/submission.json -->
+```json
+{
+  "releaseNotes": {
+    "en": "First version: the forecast of your city, in metric or imperial units.",
+    "fr": "Première version : les prévisions de votre ville, en unités métriques ou impériales."
+  },
+  "justifications": [
+    {
+      "permission": "network:GET https://api.example.com/v1/forecast/{city}",
+      "text": "Reads the forecast of the city the player chose, every 30 minutes at most."
+    },
+    {
+      "permission": "storage",
+      "text": "Keeps the chosen city and units between two games."
+    }
+  ],
+  "reviewMessage": "The forecast API needs no account and receives only the city."
+}
+```
+
+| Key | Value |
+| --- | --- |
+| `releaseNotes` | The public notes of the version, shown to players: `en` (needed as soon as there are notes) and `fr`, 500 characters each, plain text, line breaks allowed. |
+| `justifications` | For the reviewer, one `{permission, text}` per new or widened permission, by its [key](#permission-keys); 500 characters each. |
+| `reviewMessage` | A private message to the reviewer, 2,000 characters. |
+
+Every key is optional; any other key is refused. The OverCrow MCP server
+writes this file.
+
+### In a CI job
+
+A GitHub Actions workflow that installs the tool ([installing](#installing))
+and submits the example widget `nova.weather` on every version tag, with
+the key in the repository's secrets:
+
+<!-- source: docs/content/examples/weather/.github/workflows/submit.yml -->
+```yaml
+# Sends the widget to the OverCrow creator space when a version tag is
+# pushed. The publish key is a secret of the repository, and the OverCrow
+# release whose creator tools to use is a variable of the repository.
+name: Submit to OverCrow
+
+on:
+  push:
+    tags: ["v*"]
+
+permissions:
+  contents: read
+
+jobs:
+  submit:
+    runs-on: ubuntu-24.04
+    env:
+      OVERCROW_VERSION: ${{ vars.OVERCROW_VERSION }}
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install overcrow-widget
+        run: |
+          tools="overcrow-creator-tools-$OVERCROW_VERSION-linux-x86_64"
+          curl --fail --location --silent --show-error --remote-name \
+            "https://github.com/Valhallab/playervox-overcrow-releases/releases/download/v$OVERCROW_VERSION/$tools.zip"
+          unzip -q "$tools.zip"
+          (cd "$tools" && sha256sum --check --quiet SHA256SUMS)
+          install -D -m 755 "$tools"/overcrow-widget-*-linux-x86_64 "$HOME/.local/bin/overcrow-widget"
+          echo "$HOME/.local/bin" >> "$GITHUB_PATH"
+      - name: Submit to OverCrow
+        run: overcrow-widget submit --submission submission.json
+        env:
+          OVERCROW_PUBLISH_KEY: ${{ secrets.OVERCROW_PUBLISH_KEY }}
+```
+
+The job fails on any status but 0. `OVERCROW_API_URL` points `submit`
+and `status` to another API, for tests only: `https://`, or `http://` to
+`127.0.0.1`, `localhost` or `[::1]`, with a warning every time. Never set
+it in a real job; the OverCrow MCP server never sets it.
+
+## status
+
+```sh
+overcrow-widget status
+overcrow-widget status --version 1.3.1 --wait
+```
+
+Shows the versions of the key's widget, with their state and review type.
+With `--version`, one version, by its number (the latest of that number)
+or its ID: its six checks and their problems, what keeps it out of review,
+the reviewer's remarks and the review delay. `--wait` follows a version
+still being checked. `--widget ID` names the widget, for a key that covers
+several (status 2 without it, with the widgets the key covers). Options:
+`--widget ID`, `--version VERSION|ID`, `--wait`, `--format json`,
+`--verbose`. Status: 0 when read, 2 on an error; with `--wait`, the
+statuses of `submit`.
+
+| State | Meaning |
+| --- | --- |
+| `checking` | The checks run. |
+| `checks_failed` | A check failed: nothing reached the reviewers. |
+| `ready` | The checks passed; the version waits in the creator space. |
+| `in_review` | A person reviews it. |
+| `changes_requested`, `approved`, `rejected` | The review's decision. |
+| `published` | In the catalog. |
+| `superseded`, `discarded` | Replaced by a newer submission, or abandoned. |
+| `withdrawn`, `suspended` | Out of the catalog. |
+
+## Source archives
+
+`admit` and `diff` take the widget folder or a ZIP of it (its name ends in
+`.zip`), as the creator space receives it. The ZIP may hold the files
+directly, or one folder that holds them all, as Windows and macOS make it.
+It may carry a short archive comment (1,024 bytes at most), as GitHub's
+"Download ZIP" and `git archive` write it; the comment is never read.
+
+Left out of both, and never sent by the creator tools: hidden files and
+folders (`.env`, `.git/`, `assets/.DS_Store`…), `node_modules/`, `dist/`,
+`tests/output/`, `__MACOSX/`, built packages, key files and system files,
+and, in a folder, links and names that are not portable ASCII. In a ZIP,
+they still count toward the bounds below and are checked like the rest. A
+name that holds a character Windows forbids (`\ : * ? " < > |`) is
+refused, in a folder too.
+
+| Bound | Value |
+| --- | --- |
+| Archive | 32 MiB |
+| Uncompressed | 64 MiB |
+| Files | 2,000 |
+
+Everything is checked before a byte is written: a refused archive writes
+nothing, and an admitted one is written only into a private work folder,
+removed at the end.
+
+| Code | The archive holds |
+| --- | --- |
+| `sources.archive_size` | More than 32 MiB. |
+| `sources.too_large`, `sources.too_many_files` | More than 64 MiB or 2,000 files once uncompressed. |
+| `sources.unsafe_name` | A name that could leave the widget folder (`../`, `/` first), or that some system cannot use: a character Windows forbids (`\`, `:`, `*`, `?`, `"`, `<`, `>`, \|), anything but printable ASCII, a final dot or space, `CON`, `NUL`, `COM1`… The message names the character and the file. |
+| `sources.backslash` | Folders separated by `\`, as Windows PowerShell 5.1 `Compress-Archive` writes them. Send the widget folder itself in the creator space, or use [`submit`](#submit), which makes a correct ZIP. |
+| `sources.duplicate_name` | Two names that differ only by case, or a file that is also a folder. |
+| `sources.link`, `sources.special_file` | A link, or a device, a FIFO or a socket. |
+| `sources.bomb` | An entry that inflates far beyond its compressed size, or beyond its declared size. |
+| `sources.read` | The file cannot be read (exit status 2). |
+| `sources.encrypted` | An encrypted entry. |
+| `sources.zip64` | ZIP64, which sources never need. |
+| `sources.archive` | Anything else a ZIP should not hold: a comment above 1,024 bytes or holding an end record, bytes before, between or after the entries or after an entry's compressed data, another name in an extra field, sizes or checksums that disagree. |
+
+## The code map
+
+`--source-map FILE` writes a map from each position of the shipped
+`logic.js`, bundled and minified, back to the file, line and column of
+your sources: a [Source Map v3](https://tc39.es/ecma426/). The creator
+space keeps it private and uses it to show you the errors of your widget
+in your own code.
+
+- `sources`: `logic.ts` (or `logic.js`), the files of `@overcrow/sdk`
+  (listed in `ignoreList`) and `overcrow:view-table`, the expression table
+  generated from `view.ocml`, whose text is in `sourcesContent`.
+- `x_overcrow_functions`: the named functions of the sources,
+  `{"source", "name", "start": [line, column], "end": [line, column]}`,
+  zero-based, columns in UTF-16 units like `mappings`. The function of a
+  position is the innermost one around it. The expressions of the view
+  table are named `view expression <n>`, `<n>` being their index in
+  `view.json`.
+
+The same sources always give the same map. It is never part of the
+package, and `logic.js` does not point to it.
 
 ## Diagnostics
 
@@ -330,7 +666,9 @@ The code is `<domain>.<category>`:
 | `typecheck` | TypeScript | `tsc` (TypeScript's own message), `skipped`, `sdk_version`, `timeout` |
 | `package` | The package read back | `archive_size`, `file_size` and the categories of OverCrow's package reader |
 | `test` | Scenarios | `scenario`, `scenario_name`, `too_many_scenarios` |
+| `sources` | A source archive | see [source archives](#source-archives) |
 | `init`, `doctor`, `admission` | Those commands | listed above |
+| `submit` | What `submit` checks before sending | `widget_not_submittable`, `agreement_required`, `limit_reached`, `version_too_low`, `justification_missing`, `archive_too_large`, `archive_mismatch`, `release_notes`, `justification`, `review_message` |
 
 - Lines and columns start at 1; a column counts characters, not bytes.
 - An unknown name comes with the closest name that exists.
@@ -338,16 +676,93 @@ The code is `<domain>.<category>`:
   standard output:
   `{"severity","code","file","line","column","message","help"}`, with
   `null` for what is unknown. `package --format json` ends with one
-  `{"package","bytes","sha256","logicBytes"}` object.
+  `{"package","bytes","sha256","logicBytes","sourceMap"}` object; `admit`
+  and `diff` print one report ([machine-readable output](#machine-readable-output)).
 - Texts that come from a widget (its logs, its names) are shown with
   terminal control characters neutralized.
 
 Scripts should match the codes: messages and help texts may be reworded.
 
+## Machine-readable output
+
+With `--format json`, `admit`, `diff`, `submit` and `status` print one
+JSON object on one line. Fields are only ever added; a `formatVersion`
+change announces any other change.
+
+`admit`:
+
+| Field | Value |
+| --- | --- |
+| `formatVersion` | `1`. |
+| `admitted` | Whether the sources are admitted. |
+| `publisher` | The `--publisher` handle, or `third-party`. |
+| `id`, `version`, `reservedId` | The widget; `null` when the sources were refused before the build. |
+| `package` | `bytes`, `sha256` and each file's `bytes` and `sha256`. |
+| `reproducible` | `viewJson` and `archive`, compared with `--package`, else `null`. |
+| `listing` | `bytes`, `sha256`, `spdxLicense` and `preview` of `listing.json`. |
+| `sources` | `kind` (`folder` or `archive`), `files`, `bytes`, `ignored` (`path`, `reason`) and, for a ZIP, `sha256` and `prefix` (the wrapping folder). |
+| `review` | The authority to review, one object per item (`kind`, then its fields). |
+| `permissions` | `keys`; with `--previous`, also `previous` (`id`, `version`), `added`, `changed`, `removed` and `reviewType` (`full` or `quick`), else `null`. |
+| `listingPolicy` | `required` or `optional` (`--listing`). |
+| `diagnostics` | The diagnostics, as above. |
+
+`diff`:
+
+| Field | Value |
+| --- | --- |
+| `formatVersion` | `1`. |
+| `compared` | `false` when a version is refused; then only `diagnostics` follows. |
+| `old`, `new` | `kind`, `files`, `bytes`, `sha256`, `prefix`, `ignored`, `id` and `version` of each version. |
+| `files` | Changed files by path: `path`, `status` (`added`, `modified`, `removed`), `binary`, `tooLarge`, `oldSha256`, `newSha256`, `additions`, `deletions` and `hunks` (`oldStart`, `oldLines`, `newStart`, `newLines`, `lines`, each line starting with ` `, `-`, `+` or `\`). |
+| `totals` | `added`, `modified`, `removed`, `additions`, `deletions`. |
+| `permissions` | `added`, `changed`, `removed` and `reviewType`, or `null` without two valid manifests. |
+| `diagnostics` | The diagnostics. |
+
+
+`submit` and `status`:
+
+| Field | Value |
+| --- | --- |
+| `formatVersion`, `command` | `1`; `submit` or `status`. |
+| `outcome`, `exitCode` | How the run ended (below) and its [exit status](#exit-status). |
+| `dryRun` | `submit`: whether nothing was to be sent. |
+| `key` | `name`, `hint` (the four characters after `ocw_pub_`), `expiresAt`, `expiresSoon`, `widgets` (the widgets the key covers). |
+| `widget` | `id`; `submit`: `publisher`, `status`; `status`: `name`. |
+| `archive` | `submit`: `kind` (`folder`, zipped by the tool, or `archive`), `bytes`, `sha256`, `files`, `uncompressedBytes`, `ignored`. |
+| `local` | `submit`: `admitted`, `version`, `minimumVersion`, `previousVersion`, `permissions` (`keys`, `added`, `changed`, `removed`, `reviewType`), `diagnostics`. |
+| `requirements` | `submit`: `justifications` (`required`, `given`, `missing`, `unused`), `privacyPolicy` (`required`, `present`), `reviewType`, `submissions` (`limit`, `remaining`, `nextSubmissionAt`), `review` (`available`, `blockedBy`), `agreement` (`version`, `accepted`), `blockers` (`code`). |
+| `known` | `submit`: the version the creator space already has (nothing was sent): `versionId`, `state`, `match` (`sources` or `package`). |
+| `submission` | `submit`: `id`, `state`, `resumed`, `quota`. |
+| `version` | The creator space's version, its fields in camelCase: `id`, `version`, `state`, `reviewType`, `checks` (`key`, `status`, `diagnostics`), `reviewBlockers`, `completeInPortal` (`message`, `url`), `permissions`, `remarks`, `deadline`, `history`… |
+| `versions` | `status` without `--version`: every version. |
+| `error` | `code`, `message` and, when known, `httpStatus`, `retryAfter`, `nextSubmissionAt`, `minimumVersion`, `expiredAt`, `fields`; else `null`. |
+
+`outcome` is `ready_to_send` (`--dry-run`), `refused_locally`, `refused`
+(the creator space refused the submission), `complete_in_portal`,
+`already_known` (nothing sent, see `known`), `error`, or the version's
+state; `status` without `--wait` has none. Error codes
+are the creator space's (`version_not_newer`, `submission_limit_reached`,
+`publish_key_expired`, `publish_key_revoked`, `widget_required`,
+`publish_key_widget_not_covered`…) or the tool's:
+`publish_key_missing`, `invalid_publish_key`, `api_url_invalid`,
+`submission_file`, `sources`, `sources.read`, `network`, `timeout`,
+`server`, `response`, `redirect`, `upload_refused`, `build_failed`,
+`submission_state`, `not_found`, `internal`. Problems found before sending
+are diagnostics: `sources.*`, `project.missing_file` (not the widget's
+folder), `admission.*` and `submit.*` (`widget_not_submittable`,
+`agreement_required`, `limit_reached`, `version_too_low`,
+`justification_missing`, `archive_too_large`, `archive_mismatch`,
+`version_known_differs`, `release_notes`, `justification`,
+`review_message`).
+
 ## Exit status
 
 | Status | Meaning |
 | --- | --- |
-| 0 | Success. Warnings are allowed unless `--deny-warnings`. |
-| 1 | Errors were found; `admit` refused the submission; a scenario of `test` failed; the overlay ended a `dev` session. |
-| 2 | A usage or file error; no overlay for `dev`; no runtime for `test`. |
+| 0 | Success. Warnings are allowed unless `--deny-warnings`. `diff` read both versions, whether or not they differ. `submit`: the version is in review (with `--dry-run`, it would enter review), or already past it (approved, published, withdrawn), or the creator space already had it in review, with changes requested, approved or published. |
+| 1 | Errors were found; `admit` refused the sources; `diff` refused a version; a scenario of `test` failed; the overlay ended a `dev` session. `submit`: something to fix (a check before sending, a refusal of the creator space, a failed check, a version the creator space already refused, withdrew or discarded). |
+| 2 | A usage or file error; no overlay for `dev`; no runtime for `test`. `submit`, `status`: the key (missing, invalid, expired, revoked), the network or the server. |
+| 3 | `submit`, `status --wait`: the version passed its checks and waits in the creator space. |
+| 4 | `submit`, `status --wait`: the version is still being checked (Ctrl+C, `--no-wait`, or 15 minutes). |
+
+These meanings do not change from one version of the tool to the next.

package/dist/content/docs/en/creator-space.md

@@ -0,0 +1,78 @@
+# Getting started in the creator space
+
+The creator space of PlayerVox OverCrow, at `creators.playervox.com`,
+is where you publish widgets: you create your publisher once, reserve your widgets' IDs,
+send their versions and follow their review. It is open by invitation for
+now.
+
+## Sign in
+
+Sign in with your PlayerVox account: the creator space sends you to
+playervox.com, which asks you to confirm, then brings you back. You never
+type your password in the creator space. The session lasts while you use
+it, up to 14 days; you can close it on playervox.com, in
+**Connected devices**.
+
+The interface is in English or French: choose in the account menu. The
+addresses stay the same in both languages.
+
+## Turn on two-factor authentication
+
+Publishing requires two-factor authentication on your account. The first
+visit turns it on:
+
+1. Open an authenticator app (Aegis, 2FAS, Google Authenticator,
+   1Password…).
+2. Scan the QR code on a computer, or tap **Add to my app** on a phone or a
+   tablet. You can also type the key by hand.
+3. Enter the 6-digit code the app shows.
+
+You then get ten recovery codes, shown once: each signs you in once if you
+lose your phone. Keep them somewhere safe. Creating a publish key or
+deleting your publisher asks for a fresh code again.
+
+## Create your publisher
+
+The publisher is the name your widgets appear under.
+
+- **Display name**: shown to players. A name that reads as PlayerVox,
+  OverCrow or Valhallab is refused.
+- **Handle**: 3 to 32 lowercase letters, digits and hyphens, without a
+  hyphen at either end. It is **permanent**: it can never be changed, and a
+  handle is never given to anyone else, even after a deletion. Your
+  widgets' IDs start with it.
+- **Contact e-mail**: for PlayerVox to reach you. It is never shown.
+- **Website** and **logo** (square, PNG or WebP): optional, shown on your
+  publisher page. Type the website as you know it (`example.com`):
+  `https://` is added for you.
+
+Your public profile (name, about, website, logo) appears with the next
+publication of the catalog: until then the creator space says
+**Visible after the next publication**.
+
+Then read the creator agreement, summed up in six points on the screen, and
+accept it. Your space is ready.
+
+## Reserve your first widget's ID
+
+A widget ID is `<handle>.<name>`: `nova.lol-timers` for the handle `nova`.
+With a [verified domain](verified-domain.md), it can also start with your
+domain reversed: `gg.nova.lol-timers` for `nova.gg`. The name is lowercase
+letters, digits and hyphens. An ID is permanent and never reused.
+
+In **Widgets**, **New widget** reserves the ID. Create the project with the
+same ID:
+
+```sh
+overcrow-widget init lol-timers --id nova.lol-timers
+```
+
+Try it in your game with the [development channel](dev-channel.md): nothing
+is published.
+
+## Next
+
+- Send a version: [publishing and review](publishing.md).
+- Send from a terminal or a CI job: [publish keys and CI](publish-keys.md).
+- Get the verified badge and IDs under your domain:
+  [verified domain](verified-domain.md).

package/dist/content/docs/en/guide.md

@@ -239,10 +239,9 @@ locally stays unverified; users get widgets from the signed catalog. See
 
 ## 12. Submit
 
-Add a `listing.json` with the marketplace text, run the admission yourself,
-then open a pull request that adds your widget under `widgets/<dir>/` on the
-`candidate` branch of the
-[public repository](https://github.com/Valhallab/playervox-overcrow-releases):
+Add a `listing.json` with the marketplace text and run the admission
+yourself. Widgets are no longer proposed by pull request: you will send
+yours from the OverCrow creator space when it opens.
 
 ```sh
 overcrow-widget admit