Add complete CLI tutorial and refresh assistant guide

book/SUMMARY.md

@@ -6,6 +6,7 @@
 * [What is available today](status.md)
 * [Prerequisites and installation](getting-started/prerequisites.md)
 * [First game: build to publish](getting-started/first-game.md)
+* [CLI: every command, step by step](tutorials/cli.md)
 
 ## Tutorials
 

book/games/publish.md

@@ -1,8 +1,9 @@
 # Publish and verify a build
 
-**Availability: staging through the source-preview CLI.** Select your target
+**Availability: staging through the CLI; ZIP signing is a source preview.** Select your target
 environment before publishing. A publication uploads the store page and game
-build, creates a version and makes the game visible to players.
+build and creates a version. The server verifies the ZIP and an admin reviews
+the version before it goes live.
 
 ## Before upload
 
@@ -23,8 +24,9 @@ vapour publish --dry-run --version 0.1.0 --notes "Dry run"
 ```
 
 The CLI validates the manifest, store text, layout and media, packs a directory
-or selects the supplied ZIP, checks release notes, and enforces local upload
-limits. Dry run exits before API authentication, registration or upload. It does
+or selects the supplied ZIP, checks release notes and local upload limits, then
+scans and signs the ZIP. It writes `.vapour/build.zip.attestation.json` even on
+a dry run. Dry run exits before API authentication, registration or upload. It does
 not load the game in a browser, test ownership, or run all server-side checks.
 
 ## Upload
@@ -42,8 +44,9 @@ vapour publish --dir ./games/my-game --version 0.2.0 --notes "Release 0.2.0"
 If the project has no ID, the CLI registers it first and saves the assigned ID.
 It updates the store page first, then sends the version, release notes and build
 ZIP. Updating the store first prevents rejected media from consuming a version.
-The service checks ownership and the archive before publishing. The CLI prints
-the public game-page URL.
+The service checks ownership before accepting the upload and verifies the archive asynchronously. The CLI prints
+the game-page URL, but upload does not mean the version is live. See
+[.zip verification](zip-verification.md) for the local and server checks.
 
 ## After you upload
 
@@ -90,6 +93,17 @@ the first push registers the project and writes its ID to `vapour.toml`.
 
 ## Verify the outcome
 
+After uploading, check the server verification record:
+
+```sh
+vapour verify --remote --version 0.2.0
+```
+
+This checks the signed attestation and server record, not the bytes of a local
+ZIP. To check those too, pass the exact ZIP used for upload. A folder publish
+packs into a temporary ZIP; use a prebuilt ZIP and retain it when exact-byte
+verification matters. Admin review still follows server verification.
+
 - Inspect the returned game page and public catalog entry.
 - Open the player, checking the entry point and all asset requests.
 - Confirm Wasm MIME type and compression behavior in the browser network panel.

book/games/zip-verification.md

@@ -1,7 +1,8 @@
 # .zip verification
 
-**Availability: planned for CLI v0.2.** The commands and files on this page are a
-design target. The current CLI does not run this scan or write an attestation.
+**Availability: implemented on CLI main; check your installed release and server.**
+These commands may not be present in older CLI releases. A compatible API is
+required for server verification.
 
 `vapour publish` checks the build zip on your computer before anything is
 uploaded, signs it, and the server checks it again. It protects players and the

book/llm.txt

@@ -1,10 +1,10 @@
 # Vapour developer guide for LLMs
-Version: 2026-10-16
+Version: 2026-10-17
 Source: https://vapour-dev-docs.pages.dev/llm.txt
 
 Status terms in this file:
-- Released: on vapour-cli main.
-- Preview: merged in source but not guaranteed in a published release yet.
+- Released: available in a published CLI release; check your installed binary's help for its commands.
+- Preview: merged in source but not guaranteed in a published release or deployed service yet.
 
 1) What Vapour is and the normal flow
 
@@ -24,6 +24,8 @@ Rules that often matter:
 - `vapour publish` requires `--version` and exactly one of `--notes` or `--notes-file`, including dry runs.
 - Each game version can be published once; publishing the same version again returns a version-exists error.
 - `vapour publish --dry-run` validates and packs locally, without API auth/upload.
+- ZIP publishing scans and signs the exact packed build before upload, including dry runs. A failing scan stops before a version is used.
+- Upload is not the same as going live: the server verifies the ZIP, then a Vapour admin reviews the version.
 - Store push and publish can register a project and write `project.id` into `vapour.toml` on first server registration.
 - A new version is not live until an admin approves it (preview; while it waits, players keep the previous approved version).
 
@@ -32,6 +34,7 @@ Getting this file:
 - Options: `--refresh`, `--offline`, `--url <URL>`
 - Env override: `VAPOUR_LLM_URL`
 - Direct URL: `https://vapour-dev-docs.pages.dev/llm.txt`
+- Guided tutorial for every top-level CLI command: `https://vapour-dev-docs.pages.dev/tutorials/cli.html`
 
 2) `vapour.toml` reference (fields assistants should use)
 
@@ -191,6 +194,7 @@ Zip scan and signing (preview, CLI v0.2):
 - `vapour verify <zip> [--attestation <file>] [--json]` checks a zip against its attestation locally.
 - `vapour publish` (including `--dry-run`) runs the scan, signs the zip and writes `.vapour/build.zip.attestation.json`. There is no flag to skip the scan. With `--experimental-chunks` the scan runs but no attestation is sent.
 - `vapour verify <zip> --remote --version <semver>` also compares the server's recorded SHA-256 and status; exit 1 unless the status is `verified`.
+- `vapour verify --remote --version <semver>` may omit the ZIP: it checks the signed attestation and server record, but not local ZIP bytes. `--dir` selects the project and `--json` emits a result object.
 - Server verification is asynchronous: the upload is accepted right away and the server records `pending`, then `verified`, `rejected` or `unverified`. `unverified` means no attestation was sent (older CLI) and the server scan passed.
 - Reject reasons include `bad_signature`, `hash_mismatch`, `size_mismatch`, `bad_key_id`, `bad_key`, `unsupported_version`, `unknown_key`, `bad_attestation`, or any scan code. A rejected version is taken offline and can never be approved; publish a new version.
 - Malformed requests (invalid attestation JSON, attestation over 64 KiB) fail immediately with HTTP 400 `invalid_upload`.

book/tutorials/cli.md

@@ -0,0 +1,188 @@
+# CLI: every command, step by step
+
+This walkthrough covers every top-level `vapour` command in the current CLI
+source, including the `store` and `controller` subcommands. Follow the local
+steps first. Commands that contact the API need a developer token and a
+compatible staging service; **do not publish a test version by accident**.
+Check [availability](../status.md) and your binary's `--help` before starting.
+
+## 1. Install and find your way around
+
+Follow [prerequisites](../getting-started/prerequisites.md) to install a release.
+For unreleased commands, use a matching source checkout. Inspect the logo and command list:
+
+```sh
+vapour --help
+vapour --version
+vapour publish --help
+```
+
+The lowercase wordmark and blue particles appear only in root help. Redirected
+help uses plain text; command output you pipe stays clean. Use `vapour <command> --help` for its exact flags. The
+global `--api <base-url>` selects an API; a custom host needs an explicit
+trust opt-in (`--allow-custom-api`). Local HTTP is allowed only for localhost
+with `--allow-insecure-http`. Do not send your token to an unknown host.
+
+## 2. Account: `login`, `whoami`, `logout`
+
+Create a personal access token in your developer dashboard. Use stdin rather
+than putting the token in shell history:
+
+```sh
+vapour login --token -
+vapour whoami
+```
+
+Type the token into standard input, then press Enter. The CLI does not print a
+prompt. `login` verifies the account via the selected
+API; `--no-verify` skips that network check but does not grant permissions.
+`whoami` confirms the active account, role and API base. `VAPOUR_TOKEN` takes
+precedence over the saved token. At the end of this tutorial, run
+`vapour logout` to remove the saved credential; it does not revoke a token or
+clear `VAPOUR_TOKEN`. See [tokens](../auth/tokens.md).
+
+## 3. Start a project: `create` or `template`
+
+Choose **one** route and replace the example name:
+
+```sh
+vapour create "My Game" --engine godot
+```
+
+This makes a project manifest and starter store files. `--engine` also accepts
+`unity`, `bevy` and `other`. `--from <git-url>` imports source; `--offline`
+uses local scaffolding without network. Alternatively:
+
+```sh
+vapour template godot "My Game"
+```
+
+`template` clones an engine-specific skeleton. Bevy and Unity are also
+supported; `--org` selects its GitHub organization and `--offline` uses the
+local fallback. The skeleton is not a complete engine game. Add your project
+and a Web export. See [templates](../templates/overview.md) and the
+[manifest reference](../games/manifest.md). Run subsequent commands inside
+the new game directory, or pass `--dir <game-dir>` where supported.
+
+## 4. Build and inspect: `build`, `perf`, `test`
+
+Set `[build].dir` to your Web export folder, with a top-level `index.html`.
+Install the matching engine/export tools, then run:
+
+```sh
+vapour build
+vapour perf
+vapour test --no-profile
+```
+
+`build` runs the configured exporter, validates the output and writes
+`.vapour/build.json`. `perf` prints engine-specific warnings; use
+`--engine godot|unity|bevy` to choose a different engine for that check.
+`build`, `test` and `publish` accept `--no-perf-hints` to silence hints.
+`test` serves the build on loopback with an FPS overlay; the serve-time
+injection does not rewrite your build. On Linux, profiling can launch a
+private browser and local profiler. `--no-profile` skips that integration;
+`--no-telemetry`, `--no-open`, `--port` and `--profiler <path>` control the
+other test paths. Stop the server with Ctrl-C. See
+[profile locally](profile-locally.md).
+
+## 5. Prepare phone input: `controller init`, `check`, `preview`
+
+If you want on-screen controls, run:
+
+```sh
+vapour controller init --mode keyboard-map --preset default
+vapour controller check
+vapour controller preview
+vapour controller preview --html --out controller-preview.html
+```
+
+The initializer writes `[controller]` in `vapour.toml`; `check` validates
+bindings and `preview` draws an ASCII layout or writes HTML. Set the keys to
+those your game actually handles. Other presets are `shooter` and
+`dpad-only`; `dedicated` uses named actions instead of keyboard keys.
+`--force` replaces existing controls **after making a manifest backup**.
+Test the result in a phone-sized viewport; config validation does not prove
+the player supports a device. See [controls](../games/manifest.md).
+
+## 6. Prepare the store: `store check`, `store push`
+
+Edit `store/page.json`, `store/template.md` and the referenced media.
+
+```sh
+vapour store check
+```
+
+This is local validation; fix any reported fields or media before continuing.
+When you intend to update the remote page without a build, run
+`vapour store push`. It requires login, uploads the page and may register a
+new game, writing its project ID into `vapour.toml`. See
+[store page](../games/store-page.md).
+
+## 7. Check the ZIP: `scan`
+
+```sh
+vapour scan
+vapour scan ./build/web --json
+```
+
+With no argument, `scan` uses the manifest's `build.dir`. A folder is packed
+temporarily for static checks. Errors block publishing; `--json` gives
+machine-readable findings. Scanning is a heuristic, not antivirus. See
+[ZIP verification](../games/zip-verification.md).
+
+## 8. Publish safely: `publish`
+
+```sh
+vapour publish --dry-run --version 0.1.0 --notes "First release"
+```
+
+Supply a new version and exactly one of `--notes` or `--notes-file` even on
+a dry run. This validates the store and ZIP, scans and signs the archive,
+and writes `.vapour/build.zip.attestation.json`; it does not log in or upload.
+For a real publication, remove `--dry-run` **only when you are ready**:
+
+```sh
+vapour publish --version 0.1.0 --notes "First release"
+```
+
+It updates the store first, then uploads the ZIP and signed attestation.
+Each version is single-use. The server verifies the upload and an admin
+reviews it before it goes live. `--skip-store` leaves the page unchanged.
+`--experimental-chunks` is a separate, server-dependent preview; it scans
+but does not send a signed ZIP attestation or release notes. Do not use it
+against an ordinary ZIP-only API. See [publishing](../games/publish.md).
+
+## 9. Check integrity: `verify`
+
+```sh
+vapour verify ./build.zip --attestation .vapour/build.zip.attestation.json
+vapour verify --remote --version 0.1.0
+```
+
+The first command checks an **exact copy of the signed ZIP**. Folder
+publishing uses a temporary ZIP, so zipping the folder again may change the
+hash; if you did not keep the original ZIP, use the second command. Remote
+verification checks the signature and server record, but **not** local ZIP
+bytes when no ZIP is supplied. `--json` emits a result for scripts. Remote
+checks require the project ID and login. See [ZIP verification](../games/zip-verification.md).
+
+## 10. Keep tools and help current: `update`, `llm`, `completion`
+
+```sh
+vapour update --check
+vapour llm --offline
+vapour completion --help
+```
+
+`update --check` queries releases without replacing the binary; `update`
+installs a release after checksum verification on supported systems.
+`--version <tag>` selects one release. Windows users download the release
+archive instead of self-updating. `llm` prints the assistant guide to
+standard output. `--offline` uses its cache or embedded copy; `--refresh`
+forces a fetch and `--url <url>` overrides the source. `completion` generates
+shell scripts; follow its help for your shell. If update notices are unwanted,
+set `VAPOUR_NO_UPDATE_CHECK=1`.
+
+Finally, run `vapour logout` if you saved a token on a shared machine.
+For options and environment rules, see the [CLI reference](../reference/cli.md).

book/tutorials/overview.md

@@ -4,6 +4,9 @@ Step-by-step walkthroughs that take a **real sample project** all the way to a V
 separate from the [reference docs](../README.md): the docs tell you what every setting does, the tutorials show you
 the order to do things in, what went wrong for us, and why.
 
+New to the command line? Start with [CLI: every command, step by step](cli.md)
+for a guided pass through the full CLI, including optional and offline commands.
+
 Each tutorial uses a project we forked into the [`vapour-computer`](https://github.com/vapour-computer) organization, on a
 branch called `vapour-tutorial`. The branch contains exactly the files we added, so you can compare it to upstream and
 see the whole change.