@ttmg/cli 0.4.6-agent-beta.2 → 0.4.6-agent-beta.3

package/vibe-upload.md

@@ -0,0 +1,358 @@
+# Vibe Binding and Upload — Skill Integration
+
+## 中文
+
+默认资料修复已在 `0.4.6-vibe-beta.11` 发布：CLI 自动补齐此前跑通的 PPE 试用资料，用户只提供标题和头像。beta.10 仅修改了输入提示，没有自动补齐字段，真实基础信息提交会被拒绝。
+
+本次范围：本地准备 → 授权绑定 → 上传头像 → 提交应用信息 → 上传代码包 → 上传完成。不包含预览、审核或正式发布。`--web` 使用真实 PPE 授权和上传；`--mock` 的授权与素材上传仍为模拟。网页授权后自动上传的修复已在 `0.4.6-vibe-beta.9` 发布；用户输入要求已在 `0.4.6-vibe-beta.10` 修正。
+
+### Web 上传入口
+
+真实授权和上传使用 `--web`。安装 `vibe-beta` 标签对应的版本，再用 `ttmg --version` 核对实际执行版本。`beta` 是另一个发布标签，不能用它判断 Web 链路是否包含最新修复。无需设置 PPE 环境变量或预先执行 `ttmg login`；用户在本次浏览器授权页完成授权。
+
+Skill 只引导开发者准备游戏名称、本地头像和工程，然后调用 CLI、读取结构化状态。不调用平台接口、不保存 Token、不自行轮询、不增加名称头像表单。
+
+Skill 固定调用：
+
+```sh
+npm install -g @ttmg/cli@vibe-beta
+ttmg --version
+ttmg capabilities --format json
+ttmg upload --vibe --web --dir ./game --title "星环守卫" --icon ./avatar.png --format ndjson
+```
+
+Skill 启动一次命令并持续读取 NDJSON。宿主工具返回会话 ID 时，继续读取同一进程；等待用户授权期间不终止、不重启，也不再调用第二次上传。`--web` 全程使用真实授权和上传；`--mock` 仅用于下方单独列出的演示。
+
+可先检查素材，不创建 task、不打开页面：
+
+```sh
+ttmg upload --vibe --web --dir ./game --title "星环守卫" --icon ./avatar.png --dry-run --format json
+```
+
+已有 ZIP 时，用 `--package ./game.zip` 替换 `--dir ./game`。名称和头像必须由开发者提供；演示脚本中的临时样本不作为产品默认素材。
+
+### 用户需要提供什么
+
+**只向用户收集游戏标题和本地头像，并使用当前游戏目录或代码包。** 描述、服务条款、隐私政策、版权确认及其他应用资料由 CLI 使用既有 PPE 试用默认值补齐。分类可由 Skill 按下方目录选择，未选择时仍使用默认值；不向用户索要额外资料或增加填写表单。
+
+能力查询和上传事件均返回 `inputRequirements`：`requiredUserInputs=["title","icon"]`、`additionalMetadataSource="cli-defaults"`、`requestAdditionalMetadata=false`。`--app-info` 仅兼容旧调用，当前流程不使用。
+
+CLI 在 `app_info` 请求中自动带上 `description`、`category`、`subcategory`、`terms_of_service`、`privacy_policy`、`copyright_confirmation`、`contact_email`，再填入用户标题和真实上传头像 URI。默认资料标识为 `ppe-trial`；命令中没有这些参数，不代表请求里没传。能力查询的 `appInfoFields.defaultedByCli` 列出默认字段。
+
+### 查询并推荐游戏分类
+
+以下命令和参数从 `0.4.6-vibe-beta.14` 开始提供。查询离线执行，不登录、不创建任务、不写平台：
+
+```sh
+ttmg game categories --format json
+ttmg game categories --category Puzzle --format json
+```
+
+返回 `schemaVersion="1"`、`catalogVersion`、`source=bundled`、`platformWrite=false`，以及 `categories[].value` 和 `subcategories[].value/description`。当前为 12 个类型、114 个子类型，玩法说明为英文；按精确英文值筛选。`catalogVersion` 标识随 CLI 打包的快照，不表示实时拉取线上配置。
+
+Skill 根据生成游戏的核心玩法和胜负条件选择组合，给用户一句推荐理由；用户已指定分类时优先保留。不增加必填表单；无法匹配时可使用 Other/Other。
+
+```sh
+ttmg upload --vibe --web --dir ./game --title "星环守卫" --icon ./avatar.png --category Puzzle --subcategory Physics --format ndjson
+```
+
+
+- 两个分类参数都不传：仍为 `Other / Other`，旧 Skill 命令无需修改。
+
+- 两个都传：校验通过后仅覆盖分类，其他默认资料继续自动补齐。
+
+- 只传一个：`VIBE_CATEGORY_PAIR_REQUIRED`；值无效或归属不匹配：`VIBE_INVALID_CATEGORY`。均在创建任务和打开浏览器前失败，不静默改成 Other。
+
+- 旧 `--app-info` 调用未传新参数时，保留文件分类与原校验行为；显式分类参数覆盖文件分类。新流程不需要该文件。
+
+- `prepared` 和后续终态返回 `classification={category, subcategory, source, catalogVersion}`，来源为 `arguments / defaults / app-info`。`--dry-run` 可核对最终选值。
+
+- 查询类型不存在：`GAME_CATEGORY_UNKNOWN`；格式无效：`GAME_CATEGORIES_INVALID_FORMAT`。返回非零退出码。
+
+### Skill 执行顺序
+
+1. 调用上方 `--web --format ndjson` 命令；本地预检可先加 `--dry-run`。
+2. 收到 `waiting_authorization`，提示用户在系统浏览器完成授权，保持原进程运行。
+3. 收到 `uploading`，按 `uploadStep` 展示 `avatar`、`app_info`、`package` 进度。授权轮询和上传由 CLI 完成。
+4. 收到 `terminal=true`、`status=uploaded`、`uploaded=true`、`simulation=false`，确认真实上传完成。`failed`、`cancelled` 或进程中断按下方失败说明处理。
+
+### Skill 读取什么
+
+#### 上传时直接使用网页授权
+
+使用 `--web`：CLI 通过内置 `ppe_op_vc` 真实创建任务，在执行机的系统浏览器打开授权页，并持续查询真实绑定状态。服务端返回 `ready_for_input=true` 后，原进程使用同一任务依次上传头像、提交应用信息、上传代码包。Skill 不需要配置环境、再调用 `auth open` 或另发上传命令。
+
+```sh
+ttmg upload --vibe --web --dir ./game --title "星环守卫" --icon ./avatar.png --format ndjson
+```
+
+原 `upload --vibe --mock` 链路不变。`--web` 与 `--mock`、`--mock-scenario`、`--vibe-api`、`--no-open` 互斥，在创建任务前报错；显式 `--web` 不继承旧 Mock 后端设置。`--dry-run` 不创建任务或打开浏览器。JSON/NDJSON 模式也会打开浏览器，但不污染结构化输出。真实上传失败时返回对应错误，不自动重试写入或降级 Mock。
+
+等待事件返回 `authorizationMode=web` 和 `browserOpenRequested`。真实授权场景的 `nextAction=open_browser` 表示在浏览器完成授权，不代表已授权。打开失败时返回 `browserOpenErrorCode=VIBE_BROWSER_OPEN_FAILED`，仍轮询原任务，可用下面的辅助命令重试，不重新建任务。
+
+#### 手动打开浏览器授权
+
+保持上传命令运行。收到 `waiting_authorization` 后，如果事件提供 `authorizationOpenCommand`，Skill 可执行该命令，或使用同一事件的 `pageUrl`：
+
+```sh
+ttmg auth open --page-url <pageUrl> --format json
+```
+
+命令通过临时本地页面跳转到后端原始 `landing_url`，不使用 `aweme://`，不新建任务或上传文件。凭证只留在上传进程与页面服务中，不输出到 Skill 或放进命令参数。原上传进程继续轮询，授权成功与否以其 `readyForInput` 为准。
+
+`pageUrl` 是本机绑定／上传进度页，不是平台原始授权页。`authorizationOpenCommand` 是重新打开同一任务授权页的入口；正常情况下 `--web` 已经自动打开，无需重复执行。`browserOpenRequested=true` 只代表发起打开浏览器，不能据此判定授权成功。两种页面入口都依赖原上传进程，不能把本机链接发给另一台电脑使用。
+
+成功返回 `status=open_requested`、`browserOpenRequested=true`、`platformWrite=false`，只表示已请求系统浏览器打开。页面过期、流程结束或没有可用真实授权地址时，返回 `VIBE_AUTH_PAGE_UNAVAILABLE`；URL 输入错误返回 `VIBE_INVALID_PAGE_URL`，浏览器启动失败返回 `VIBE_BROWSER_OPEN_FAILED`。不得因打开失败而自动创建新任务。
+
+命令在 CLI 所在电脑执行；远程机器不会打开开发者电脑的浏览器。二维码原路径和 `--mock` 自动推进逻辑保持不变；真实网页授权与上传使用 `--web`。
+
+输出 schema 为 `"2"`。每行 NDJSON 是同一 `operationId` 的状态快照；只有最后一行 `terminal=true`。`--format json` 仅在结束时向 stdout 输出一个对象，等待授权的本地页面地址写到 stderr。不要解析中文／英文文案判断状态。
+
+| status                          | Skill 处理                                                                                |
+| ------------------------------- | ----------------------------------------------------------------------------------------- |
+| precheck / packaging / prepared | 正在检查或准备素材；dry-run 的 prepared 为终态                                            |
+| creating_task                   | 正在准备授权绑定                                                                          |
+| waiting_authorization           | nextAction=open_browser 时在已打开的系统浏览器完成授权；scan_qr 时提示 TikTok 扫码；wait 时等待模拟推进 |
+| uploading                       | 根据 uploadStep 显示 avatar、app_info、package 的进度，不再询问授权                       |
+| uploaded                        | terminal=true 且 uploaded=true：本次上传完成；不是审核通过或正式发布                      |
+| failed / cancelled              | 根据 errorCode、message 和 nextAction 提示处理，不自动重传                                |
+
+固定字段：`schemaVersion`、`command`、`mode`、`operationId`、`ts`、`status`、`terminal`、`nextAction`、`message`、`backend`、`simulation`、`platformWrite`、`uploadAttempted`、`uploaded`、`errorCode`、`error`。
+
+从真实创建任务请求发起前开始 `platformWrite=true`，表示已尝试平台写入，不代表创建或上传成功。只有内部离线测试、本机 HTTP 和 dry-run 保持 `platformWrite=false`。
+
+`backend=ppe-mock` 时 `simulation=true`、`simulationStartsAt=authorization`；创建任务前开始 `platformWrite=true`。`taskStatusRaw`、`readyForInput` 始终保留最后一次真实查询值，模拟状态单独放在 `simulatedTaskStatusRaw`、`simulatedReadyForInput`。终态仍为 `uploaded`，但只表示模拟上传完成，不代表真实授权或上传成功；Skill 必须保留模拟提示。
+
+按阶段补充：`taskId`（字符串，禁止转成 JS Number）、`pollIntervalSeconds`、`readyForInput`、`taskStatusRaw`（仅诊断）、`uploadStep`、`loadedBytes`、`totalBytes`、`pageUrl`、`qrPurpose=authorization_binding`、素材大小和包 SHA256。代码包字节进度达到 100% 不代表成功，必须等待最终上传回执。
+
+`nextAction` 取值：`wait`、`open_browser`、`scan_qr`、`fix_input`、`restart_authorization`、`check_task`、`none`。已开始上传后发生失败／超时，先检查 task，不能直接再次创建并重传。若上传已完成但页面失败，仍保留 `uploaded=true`，同时返回错误；Skill 提示上传已完成但展示失败。
+
+退出码：成功／dry-run 为 0，失败为 1，Ctrl+C 为 130。进程或宿主意外终止导致没有终态时，不得认定上传成功。模拟必须显示为模拟：即使 `uploaded=true`，`simulation=true` 时也只表示模拟步骤完成。纯 Mock 的 `platformWrite=false`；混合联调创建过真实任务时为 true，但都不代表真实上传。
+
+### Mock 覆盖与演示
+
+`npm run demo:vibe` 会构建并用临时工程和头像运行 CLI；真实检查、ZIP 打包和 PPE 创建／查询，模拟授权与上传。需要后端可访问，无需完成手机授权。结果页在进程结束后继续保留至到期。
+
+```sh
+ttmg upload --vibe --package ./game.zip --title "测试游戏" --icon ./avatar.png --mock --format ndjson
+ttmg upload --vibe --package ./game.zip --title "测试游戏" --icon ./avatar.png --mock --mock-scenario denied --format ndjson
+ttmg upload --vibe --package ./game.zip --title "测试游戏" --icon ./avatar.png --mock --mock-scenario timeout --timeout 5 --format ndjson
+ttmg upload --vibe --package ./game.zip --title "测试游戏" --icon ./avatar.png --mock --mock-scenario upload-failed --format ndjson
+```
+
+| 场景                                      | 结果                                                                 |
+| ----------------------------------------- | -------------------------------------------------------------------- |
+| success                                   | 第三次轮询允许上传，头像／信息／代码包依次完成                       |
+| denied                                    | 授权取消，VIBE_AUTH_DENIED，不上传                                   |
+| expired                                   | 授权过期，VIBE_AUTH_EXPIRED，不上传                                  |
+| timeout                                   | 持续等待，直到整体超时 VIBE_TIMEOUT                                  |
+| icon-failed / info-failed / upload-failed | 在对应上传步骤失败，uploadStep 指明位置                              |
+| processing                                | 包已上传，后端状态仍为 PROCESSING；CLI 返回 uploaded，不等 SUCCEEDED |
+
+Mock 的 denied 是交互测试场景，真实端内拒绝授权如何映射错误仍待后端确认。独立离线测试通过注入传输实现；用户执行的 `--mock` 会真实创建并查询 PPE 任务，但不调用真实素材上传接口。
+
+轮询间隔使用创建任务返回的 `poll_interval_seconds`，第三次真实查询后模拟授权。`--poll-interval` 仅用于覆盖测试间隔。`--timeout` 是整体超时，默认 300 秒。不自动重试写接口、不实现跨进程续传。
+
+### 页面与素材
+
+同一电脑本地页显示绑定状态、上传进度、上传完成；二维码模式显示授权绑定码，Web 模式在系统浏览器完成授权。失败时清除授权码并显示失败原因。`--web` 在 text、JSON、NDJSON 格式下均自动打开授权页；其他模式只有 text 默认打开本地页，可用 `--no-open` 关闭。Skill 可用 `pageUrl` 展示本地进度页。
+
+页面只监听 127.0.0.1，二维码才由手机扫描，手机不访问 pageUrl。默认 15 分钟后关闭，内容驻留内存；测试可设置 `TTMG_VIBE_PAGE_TTL_MS`（1—900000）。取消进程会关闭页面；成功与可显示的失败页面保留至到期。不要分享本地页面地址。
+
+真实执行的部分包括本地项目检查和 ZIP 打包。文件直接输入只检查非空、大小与文件头，不代表完整图像解码、ZIP 内容检查或平台审核。现有 10 MiB 头像、100 MiB ZIP 为本地保护阈值，不是后端已确认限制。图片识别 PNG/JPEG/WebP。
+
+准备完成后固定本次素材字节，授权期间不会重新读取。打包排除 .ttmg、.env\*、PEM 和 KEY 等文件，但不保证识别所有业务秘密。
+
+CLI 在工程目录的 `.ttmg/vibe-project.json` 保存并复用非敏感 source_project_id；使用 --package 时保存在 ZIP 所在目录。不要将多个独立游戏的 ZIP 放在同一身份目录。dry-run 不创建此文件。每次运行使用新的 task_idempotency_id，当前不支持中断续传。凭证只驻留进程内存，不进入事件、文件、日志或错误信息。
+
+### HTTP 适配边界
+
+Mock 与本地 HTTP 共用请求构造、业务响应校验及状态映射，基于 2026-09-12 的 Minis Import BFF IDL：
+
+| 方法 / 接口（统一前缀 /bff/app_info/minis_import/） | 请求                                                                        | 响应                                                      |
+| --------------------------------------------------- | --------------------------------------------------------------------------- | --------------------------------------------------------- |
+| POST create_minis_import_task_for_agent/            | source_type=1、source_project_id、task_idempotency_id、minis_type=MINI_GAME | task_id、import_token、landing_url、poll_interval_seconds |
+| GET get_minis_import_task_status_for_agent/         | Query：task_id、import_token                                                | status、ready_for_input                                   |
+| POST upload_minis_import_app_icon_for_agent/        | Multipart：task_id、import_token、file                                      | icon_uri                                                  |
+| POST submit_minis_import_info_for_agent/            | JSON：task_id、import_token、app_info（完整应用信息，加 CLI 提供的 app_name、icon_uri） | error_info                                                |
+| POST upload_minis_import_package_for_agent/         | Multipart：task_id、import_token、asset_type=2、file                        | package_uri、status                                       |
+
+所有响应必须业务 `error_info.code=0`。最后一步还要求非空 package_uri 和合法非失败状态；完成后不再轮询。HTTP 200、进度100% 都不能单独作为成功判定。19位 task_id 在 CLI 内保留字符串，提交 i64 JSON 时无损编码。
+
+```sh
+TTMG_VIBE_BACKEND=local-http TTMG_VIBE_API=http://127.0.0.1:3100 ttmg upload --vibe --package ./game.zip --title "测试游戏" --icon ./avatar.png --format ndjson
+```
+
+维护者可使用 `--vibe-api http://127.0.0.1:3100` 验证本机 HTTP 合同，只接受回环 IP，不跟随重定向、不读取 Cookie；本地服务需实现上表协议。博华试用无需此选项，直接 `--mock`，PPE 路由由 CLI 内置。正式环境未开放。
+
+**v1 → v2 兼容性变化**：旧 UUID 换 Token 的三接口协议废弃，`--vibe-authorize-url` 返回明确错误；授权地址来自 landing_url。不再输出 preview_ready、game_preview、uploadId、reviewStatus。Skill 必须校验 schemaVersion=2，并按新终态处理。普通不带 --vibe 的 upload 不变。
+
+2026-09-14 已核对 BFF 源码：头像 PNG/JPEG、1024×1024、5 MiB；Native ZIP 和解压总大小上限 100 MiB。本地暂未实现完整 ZIP 内容及解压总大小校验。2026-09-15 修复构建使用自有测试素材跑通真实 PPE 网页授权、头像、默认资料和代码包上传；该验证不覆盖全部游戏、手机授权或正式环境。后端接口调整留在适配层处理；若用户动作或成功语义改变，应协商升级 CLI schema。
+
+### 验证
+
+`npm run test:vibe`：Mock、HTTP 合同、请求顺序、i64、失败、取消、输入和页面测试。
+
+`npm run test:vibe-process`：构建后的真实命令、JSON/NDJSON、环境配置、页面生命周期与退出码。完整 CLI 回归仍为 `npm run test:agent-contract`。测试通过不等于真实绑定上传已验证。
+
+## English
+
+The default-metadata fix shipped in `0.4.6-vibe-beta.11`. The CLI fills the existing PPE trial metadata automatically; users provide only title and icon. Beta.10 changed input guidance without filling the fields, and its real app-info submission was rejected.
+
+### Web upload entry
+
+Scope: local preparation → authorization binding → avatar upload → app-info submission → package upload → **upload complete**. No preview, review or production release. `--web` uses real PPE authorization and uploads; `--mock` still simulates authorization and material uploads.
+
+Automatic upload was fixed in `0.4.6-vibe-beta.9`; the user-input clarification ships in `0.4.6-vibe-beta.10`.
+
+Use `--web` for real authorization and upload. Install `vibe-beta` and check the executable with `ttmg --version`. The separate `beta` tag does not identify the latest Web fixes. No PPE environment variables or prior `ttmg login` are required; the user authorizes in the browser for this task.
+
+```sh
+npm install -g @ttmg/cli@vibe-beta
+ttmg --version
+ttmg capabilities --format json
+ttmg upload --vibe --web --dir ./game --title "My game" --icon ./avatar.png --format ndjson
+```
+
+Use `--package ./game.zip` instead of `--dir` for an existing ZIP. Add `--dry-run --format json` to the Web command for local preparation only; it creates no task and opens no browser.
+
+Start one command and keep reading its NDJSON. If the host tool returns a session ID, keep reading that same process while the user authorizes. Do not stop, restart or launch another upload. `--web` uses real authorization and uploads throughout; `--mock` is the separate demo mode below. The Skill does not call platform APIs, store credentials or add a metadata form.
+
+### User inputs
+
+**Collect only the game title and local icon, using the current game directory or ZIP.** The CLI fills other app metadata with existing PPE trial defaults. The Skill may select a category pair from the catalog below; omission keeps the defaults. Do not ask the user for extra fields or add a form.
+
+Capabilities and upload events include `inputRequirements` with `requiredUserInputs=["title","icon"]`, `additionalMetadataSource="cli-defaults"` and `requestAdditionalMetadata=false`.
+
+The `--app-info` option remains for legacy callers only; the current workflow does not use it.
+
+The CLI submits `description`, `category`, `subcategory`, `terms_of_service`, `privacy_policy`, `copyright_confirmation` and `contact_email` inside `app_info`, together with the user title and uploaded icon URI. The profile is `ppe-trial`; missing command-line arguments do not mean missing request fields. Capabilities list the defaults under `appInfoFields.defaultedByCli`.
+
+Source checked on 2026-09-14: BFF enforces PNG/JPEG, 1024×1024, 5 MiB icons and a 100 MiB Native ZIP/uncompressed-size limit. Full local ZIP-content/uncompressed-size validation is not implemented. On 2026-09-15, a corrected build completed real PPE web authorization and icon, default app-info and package uploads with owned test fixtures. This does not cover every game, phone authorization or production.
+
+### Query and recommend game categories
+
+These commands and options are available from `0.4.6-vibe-beta.14`. Queries run offline without login, task creation or platform writes:
+
+```sh
+ttmg game categories --format json
+ttmg game categories --category Puzzle --format json
+```
+
+The result includes `schemaVersion="1"`, `catalogVersion`, `source=bundled`, `platformWrite=false`, `categories[].value` and `subcategories[].value/description`.
+
+There are 12 categories and 114 subcategories with English gameplay descriptions. Filtering uses the exact category value. The version identifies a bundled snapshot, not a live platform fetch.
+
+The Skill selects a valid pair from the generated game's core gameplay and win conditions and gives a short reason. Preserve a user's explicit choice. Do not add a required form; use Other/Other when no category matches.
+
+```sh
+ttmg upload --vibe --web --dir ./game --title "My game" --icon ./avatar.png --category Puzzle --subcategory Physics --format ndjson
+```
+
+
+- Omit both: keep `Other / Other`; existing Skill commands work unchanged.
+
+- Supply both: override only category fields after validation; other metadata defaults remain.
+
+- Supply one: `VIBE_CATEGORY_PAIR_REQUIRED`. Invalid values or a mismatched pair: `VIBE_INVALID_CATEGORY`. Fail before task creation or browser opening, without a silent fallback.
+
+- Legacy `--app-info` calls retain file values and existing validation when new options are absent. Explicit category options override file category fields. New callers need no metadata file.
+
+- The `prepared` and subsequent terminal events return `classification={category, subcategory, source, catalogVersion}`, with source `arguments / defaults / app-info`. Use `--dry-run` to inspect the effective selection.
+
+- Unknown query category: `GAME_CATEGORY_UNKNOWN`. Invalid format: `GAME_CATEGORIES_INVALID_FORMAT`. Both return nonzero exit codes.
+
+### Skill execution order
+
+1. Run the `--web --format ndjson` command above; optionally precheck with `--dry-run`.
+2. At `waiting_authorization`, ask the user to authorize in the system browser and keep the process running.
+3. At `uploading`, display `uploadStep`: `avatar`, `app_info`, then `package`. The CLI owns polling and uploads.
+4. Confirm real completion only when `terminal=true`, `status=uploaded`, `uploaded=true`, `simulation=false`. Handle failure, cancellation or interruption as described below.
+
+### Output and decisions
+
+#### Use browser authorization during upload
+
+Use `--web` for real authorization. The CLI creates a task through the built-in `ppe_op_vc` lane, opens authorization in the execution machine's system browser and polls real binding status. Once the server returns `ready_for_input=true`, the same process uploads the icon, submits app information and uploads the package using the same task. No environment setup, `auth open` helper or second upload command is required.
+
+```sh
+ttmg upload --vibe --web --dir ./game --title "My game" --icon ./avatar.png --format ndjson
+```
+
+The original `upload --vibe --mock` workflow is unchanged. `--web` conflicts with `--mock`, `--mock-scenario`, `--vibe-api` and `--no-open` before task creation, and does not inherit an old Mock backend environment setting. Dry-run creates no task and opens no browser. JSON/NDJSON also open the browser without contaminating stdout. Real upload failures return an error; writes are not automatically retried or replaced by Mock results.
+
+Waiting events add `authorizationMode=web` and `browserOpenRequested`. For real authorization, `nextAction=open_browser` requests browser approval; it does not prove approval. If opening fails, `browserOpenErrorCode=VIBE_BROWSER_OPEN_FAILED` is returned while polling continues. Retry the helper below against the same task instead of creating another one.
+
+#### Open browser authorization manually
+
+Keep the upload process running. On `waiting_authorization`, execute its optional
+`authorizationOpenCommand`, or use the `pageUrl` from that event:
+
+```sh
+ttmg auth open --page-url <pageUrl> --format json
+```
+
+The temporary loopback page redirects the system browser to the original backend
+`landing_url`, without the `aweme://` wrapper. No new task or upload is performed.
+Credentials stay inside the uploader/page worker, not in Skill output or command
+arguments. The original uploader keeps polling; its `readyForInput` determines
+authorization readiness.
+
+`pageUrl` is the local binding/upload-progress page, not the original platform authorization URL. To reopen authorization for the same task, execute `authorizationOpenCommand`. Normally `--web` has already opened it. `browserOpenRequested=true` only confirms the open request, not authorization. Both page entry points depend on the original uploader and the CLI computer; do not send localhost links to another computer.
+
+Success reports `status=open_requested`, `browserOpenRequested=true`, and
+`platformWrite=false`; it does not mean authorization succeeded. Expired,
+completed, or unavailable authorization pages return `VIBE_AUTH_PAGE_UNAVAILABLE`;
+bad input returns `VIBE_INVALID_PAGE_URL`, and browser launch failures return
+`VIBE_BROWSER_OPEN_FAILED`. Do not create another task automatically on failure.
+
+This opens the browser on the CLI computer, not a remote user's computer. Existing
+QR behavior and `--mock` auto-advance stay unchanged. Use `--web` for real browser
+authorization followed by upload.
+
+Schema **2** provides NDJSON snapshots under one operationId, with exactly one final `terminal=true` event. JSON mode emits one final object on stdout and the authorization page address on stderr. With `--web`, all output formats open the system browser automatically. Other modes open pageUrl automatically only in text mode unless --no-open is set.
+
+| status                          | Skill action                                                                              |
+| ------------------------------- | ----------------------------------------------------------------------------------------- |
+| precheck / packaging / prepared | Wait for input preparation; prepared is terminal only for dry-run                         |
+| creating_task                   | Preparing binding                                                                         |
+| waiting_authorization           | open_browser requests approval in the opened system browser; scan_qr requests a TikTok scan; wait means simulation advances automatically |
+| uploading                       | Follow uploadStep: avatar, app_info, package                                              |
+| uploaded                        | terminal=true and uploaded=true mean upload complete, not release                         |
+| failed / cancelled              | Read errorCode, message and nextAction; do not blindly repeat uploads                     |
+
+Stable fields: schemaVersion, command, mode, operationId, ts, status, terminal, nextAction, message, backend, simulation, platformWrite, uploadAttempted, uploaded, errorCode, error. Optional evidence: taskId (string), taskStatusRaw (diagnostics only), pollIntervalSeconds, readyForInput, uploadStep, loadedBytes, totalBytes, pageUrl, qrPurpose=authorization_binding, sizes and packageSha256.
+
+platformWrite becomes true immediately before attempting real task creation, not as proof of successful creation or upload. Only injected offline tests, loopback HTTP and dry-run keep platformWrite=false.
+
+For backend=ppe-mock, simulation=true and simulationStartsAt=authorization. platformWrite becomes true before real task creation. taskStatusRaw and readyForInput retain the last real observation; simulatedTaskStatusRaw and simulatedReadyForInput describe the local demo separately. The uploaded terminal state means simulated completion only; the Skill must retain the simulation label.
+
+nextAction is wait, open_browser, scan_qr, fix_input, restart_authorization, check_task or none. If upload was attempted, verify the task before retrying. If a result page fails after confirmed upload, uploaded remains true alongside the error. Progress at 100% is not a receipt. Missing terminal output after a killed process is not success. Exit codes: 0 success/dry-run, 1 failure, 130 cancellation.
+
+Pure Mock reports simulation=true and platformWrite=false. Hybrid PPE + Mock reports platformWrite=true once real task creation is attempted, but uploaded=true still means simulated completion only. No backend exposes credentials or raw HTTP errors. Backend integration must preserve this public contract; changes to user actions or completion semantics require an explicit schema migration.
+
+### Mock, UI and inputs
+
+Run `npm run demo:vibe` for the CLI with temporary game/icon fixtures. Local checking, ZIP creation and PPE task creation/polling are real; authorization and uploads are simulated. Backend access is required, phone authorization is not. Scenarios: success, denied, expired, timeout, upload-failed, processing, icon-failed, info-failed. Use --mock-scenario and --timeout to test failures. Denial is a mock interaction scenario, not a confirmed backend error mapping.
+
+The same local page changes from binding QR to upload progress and completion, without preview QR or metadata form. Failures clear the binding QR. It listens only on 127.0.0.1, retains content in memory, and expires after 15 minutes; the phone scans the QR rather than visiting pageUrl. Success/failure pages remain after CLI completion; cancellation closes the page. Test TTL: TTMG_VIBE_PAGE_TTL_MS=1..900000.
+
+The trial follows poll_interval_seconds and simulates input readiness after the third real query; --poll-interval is a testing override. The overall --timeout defaults to 300 seconds. No automatic write retries or cross-process resume.
+
+The supplied title/icon/package bytes are fixed before authorization. Direct files are checked for size and signatures, not decoded or fully inspected. PNG/JPEG/WebP and 10 MiB icon / 100 MiB ZIP limits are provisional local guards, not confirmed platform rules. Project packaging excludes .ttmg, .env\*, PEM and KEY files, not every possible secret.
+
+A non-secret source_project_id is persisted in .ttmg/vibe-project.json under the project, or the ZIP parent for --package. Keep distinct games in separate directories. Dry-run does not create identity metadata. Each invocation has a new task_idempotency_id; credentials are held only in memory.
+
+### Adapter and verification
+
+The five endpoint contracts are listed in the table above. Mock and loopback HTTP share request construction and response validation. The HTTP adapter implements POST create → GET status with task_id/import_token query parameters → Multipart icon → JSON app_info → Multipart package with asset_type=2 (Native). Multipart Content-Type includes its generated boundary; JSON i64 task IDs are encoded losslessly.
+
+A business-success response requires error_info.code=0. Package completion additionally requires package_uri and a valid non-failure status; no polling until SUCCEEDED. No platform Cookies or redirects are used. Configure TTMG_VIBE_BACKEND=local-http plus TTMG_VIBE_API=http://127.0.0.1:3100, or pass --vibe-api explicitly; this option rejects remote hosts.
+
+For internal PPE integration, set TTMG_VIBE_BACKEND=ppe and TTMG_VIBE_PPE=ppe_op_vc without changing the Skill command. This uses real creation/polling on developers.tiktok.com and encodes the QR as aweme://webview?url=<encodeURIComponent(landing_url)>. The phone must use the same lane. OAuth is not bypassed or simulated. After authorization, the CLI uploads the icon, submits the title and icon URI, and uploads the package. The CLI fills other app metadata with existing PPE trial defaults. The regular --web entry configures PPE internally and opens the system browser.
+
+The normal --mock trial internally uses ppe_op_vc without environment variables. Task creation, QR and three polls are real; authorization, icon, app-info and package uploads are simulated with separate in-memory credentials. This changes --mock from an offline run into a PPE integration trial: platformWrite becomes true when task creation is attempted, while simulation remains true. No real material-upload endpoint is called, and real request failures still fail. --mock-scenario controls only simulated steps. Offline unit/process tests use injected transports, not a separate developer configuration.
+
+Schema-v1 UUID endpoints, --vibe-authorize-url, preview_ready, game_preview, uploadId and reviewStatus are retired. The deprecated option returns an explicit error. Ordinary upload without --vibe is unchanged.
+
+Unconfirmed: token expiry/retry rules, actual denial mapping and in-client PPE Cookie behavior. Run test:vibe, built test:vibe-process, and test:agent-contract. Local contract tests do not establish real platform or device results; the PPE test-fixture result above is recorded separately.