@ttmg/cli 0.4.6-vibe-beta.6 → 0.4.6-vibe-beta.8

package/vibe-upload.md

@@ -2,25 +2,21 @@
 
 ## 中文
 
-本次范围：本地准备 → 扫码绑定 → 上传头像 → 提交名称和头像信息 → 上传代码包 → 上传完成。不包含预览、审核或正式发布。当前可交付的是 Mock 与本地 HTTP 合同验证，尚未开放真实平台上传。
+本次范围：本地准备 → 扫码绑定 → 上传头像 → 提交名称和头像信息 → 上传代码包 → 上传完成。不包含预览、审核或正式发布。当前创建／查询接 PPE，授权和素材上传仍为模拟。
 
 ### 博华如何接入
 
-Skill 只引导开发者准备游戏名称、本地头像和工程，然后调用 CLI、读取结构化状态。不调用平台接口、不保存 Token、不自行轮询、不增加名称头像表单。
-
-开发环境先配置一次（属于运行配置，不写成 Skill 的流程分支）：
+继续使用 `--mock`，无需本地环境配置。CLI 内置 `ppe_op_vc` 创建任务，展示授权二维码，并查询三次真实状态；之后模拟授权和头像／信息／代码包上传。二维码可用于查看端内授权页，不要求完成授权。真实请求失败仍报错，素材不会上传到 PPE。上线时由 CLI 版本去掉 PPE 路由，Skill 不负责切换环境。
 
-```sh
-export TTMG_VIBE_BACKEND=mock
-```
+Skill 只引导开发者准备游戏名称、本地头像和工程，然后调用 CLI、读取结构化状态。不调用平台接口、不保存 Token、不自行轮询、不增加名称头像表单。
 
 Skill 固定调用：
 
 ```sh
-ttmg upload --vibe --dir ./game --title "星环守卫" --icon ./avatar.png --format ndjson
+ttmg upload --vibe --mock --dir ./game --title "星环守卫" --icon ./avatar.png --format ndjson
 ```
 
-未安装本地构建时，以 `node /绝对路径/cli/dist/index.js` 替换 `ttmg`。也可以显式传 `--mock`；命令行选择优先于环境配置。未来真实后端由 CLI 内部适配，Skill 的参数、状态分支和完成判定不需要跟着 HTTP 字段变化。
+未安装本地构建时，以 `node /绝对路径/cli/dist/index.js` 替换 `ttmg`。已调通的步骤接真实接口、未调通的步骤继续模拟，由 CLI 内部维护；Skill 不跟着 HTTP 字段和联调环境变化。
 
 可先检查素材，不创建 task、不打开页面：
 
@@ -30,8 +26,53 @@ ttmg upload --vibe --dir ./game --title "星环守卫" --icon ./avatar.png --dry
 
 已有 ZIP 时，用 `--package ./game.zip` 替换 `--dir ./game`。名称和头像必须由开发者提供；演示脚本中的临时样本不作为产品默认素材。
 
+### 完整应用信息校验
+
+维护者可添加 `--app-info ./app-info.json`，为真实上传准备完整参数。该选项不改变现有 `--mock` 用法，也不解除 PPE 素材上传限制。
+
+```sh
+ttmg upload --vibe --package ./game.zip --title "测试游戏" --icon ./avatar.png --app-info ./app-info.json --dry-run --format json
+```
+
+JSON 文件为以下字段组成的对象，最大 64 KiB；名称由 `--title` 提供，头像 URI 由上传接口返回，不在文件中填写。
+
+| 字段 | 要求 |
+| --- | --- |
+| description、category、subcategory | 必填非空字符串；分类与子分类应使用平台分类表中的配对值，本地暂不校验分类枚举 |
+| terms_of_service、privacy_policy | 必填 HTTP(S) 链接，不含用户名和密码；须使用游戏自己的真实条款与隐私链接 |
+| copyright_confirmation | 必须显式为 true；只有用户已确认版权时才填写，Skill 不得代为默认确认 |
+| apple_team_id、contact_email、region、min_sdk_version | 可选字符串；填写邮箱时检查基本格式 |
+
+提供该文件后，创建任务前检查名称最多 30 个字符，以及头像为 PNG/JPEG、1024×1024、最大 5 MiB。头像仅做文件头预检，完整解码由后端校验。错误分别返回 `VIBE_INVALID_APP_INFO`、`VIBE_TITLE_TOO_LONG`、`VIBE_PLATFORM_ICON_INVALID`，`nextAction=fix_input`。JSON 不接受额外字段，内容不会进入结构化输出；修改后重新运行 dry-run。
+
 ### Skill 读取什么
 
+#### 上传时直接使用网页授权
+
+使用 `--web`：CLI 通过内置 `ppe_op_vc` 真实创建任务，在执行机的系统浏览器打开授权页，并持续查询真实绑定状态。Skill 不需要配置环境或再调用 `auth open`。只有服务端返回 `ready_for_input=true` 才算绑定就绪，不模拟授权成功。
+
+```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 模式也会打开浏览器，但不污染结构化输出。当前授权就绪后仍返回 `VIBE_REAL_UPLOAD_NOT_READY`，不会伪装成上传成功，也不自动降级 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` 为准。
+
+成功返回 `status=open_requested`、`browserOpenRequested=true`、`platformWrite=false`，只表示已请求系统浏览器打开。页面过期、流程结束或没有可用真实授权地址时，返回 `VIBE_AUTH_PAGE_UNAVAILABLE`；URL 输入错误返回 `VIBE_INVALID_PAGE_URL`，浏览器启动失败返回 `VIBE_BROWSER_OPEN_FAILED`。不得因打开失败而自动创建新任务。
+
+命令在 CLI 所在电脑执行；远程机器不会打开开发者电脑的浏览器。二维码原路径和 `--mock` 自动推进逻辑保持不变：混合模拟不会等待网页授权，真实网页联调请使用维护者的 PPE 模式。本功能需包含新命令的构建版本。
+
 输出 schema 为 `"2"`。每行 NDJSON 是同一 `operationId` 的状态快照；只有最后一行 `terminal=true`。`--format json` 仅在结束时向 stdout 输出一个对象，等待授权的本地页面地址写到 stderr。不要解析中文／英文文案判断状态。
 
 | status                          | Skill 处理                                                                                |
@@ -45,15 +86,19 @@ ttmg upload --vibe --dir ./game --title "星环守卫" --icon ./avatar.png --dry
 
 固定字段：`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`、`scan_qr`、`fix_input`、`restart_authorization`、`check_task`、`none`。已开始上传后发生失败／超时，先检查 task，不能直接再次创建并重传。若上传已完成但页面失败，仍保留 `uploaded=true`，同时返回错误；Skill 提示上传已完成但展示失败。
 
-退出码：成功／dry-run 为 0，失败为 1，Ctrl+C 为 130。进程或宿主意外终止导致没有终态时，不得认定上传成功。Mock 必须显示为模拟：即使 `uploaded=true`，只表示模拟步骤完成，`simulation=true`、`platformWrite=false`，不是真实平台结果。
+退出码：成功／dry-run 为 0，失败为 1，Ctrl+C 为 130。进程或宿主意外终止导致没有终态时，不得认定上传成功。模拟必须显示为模拟：即使 `uploaded=true`，`simulation=true` 时也只表示模拟步骤完成。纯 Mock 的 `platformWrite=false`；混合联调创建过真实任务时为 true，但都不代表真实上传。
 
 ### Mock 覆盖与演示
 
-`npm run demo:vibe` 会构建并用临时工程和头像运行真实 CLI；真实检查和 ZIP 打包，模拟平台调用，无需手机或后端。结果页在进程结束后继续保留至到期。
+`npm run demo:vibe` 会构建并用临时工程和头像运行 CLI；真实检查、ZIP 打包和 PPE 创建／查询，模拟授权与上传。需要后端可访问，无需完成手机授权。结果页在进程结束后继续保留至到期。
 
 ```sh
 ttmg upload --vibe --package ./game.zip --title "测试游戏" --icon ./avatar.png --mock --format ndjson
@@ -73,7 +118,7 @@ ttmg upload --vibe --package ./game.zip --title "测试游戏" --icon ./avatar.p
 
 Mock 的 denied 是交互测试场景，真实端内拒绝授权如何映射错误仍待后端确认。Mock 不请求任何远端，不更改平台登录态，不创建真实应用。
 
-默认 Mock 轮询间隔 1 秒；其他适配使用创建任务返回的 `poll_interval_seconds`。`--poll-interval` 仅用于覆盖测试间隔。`--timeout` 是整体超时，默认 300 秒。不自动重试写接口、不实现跨进程续传。
+轮询间隔使用创建任务返回的 `poll_interval_seconds`，第三次真实查询后模拟授权。`--poll-interval` 仅用于覆盖测试间隔。`--timeout` 是整体超时，默认 300 秒。不自动重试写接口、不实现跨进程续传。
 
 ### 页面与素材
 
@@ -96,7 +141,7 @@ Mock 与本地 HTTP 共用请求构造、业务响应校验及状态映射，基
 | 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.app_name、app_info.icon_uri           | error_info                                                |
+| 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 时无损编码。
@@ -105,11 +150,11 @@ Mock 与本地 HTTP 共用请求构造、业务响应校验及状态映射，基
 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`。只接受回环 IP，不接受远端或 localhost，不跟随重定向、不读取 Cookie。没有配置则明确失败，不自动使用 Mock。该本地服务需实现上表协议；本轮没有开放 PPE／正式平台 HTTP 模式。真实接入后才能报告 platformWrite=true。
+维护者可使用 `--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 不变。
 
-仍待真实联调确认：头像／代码包规则、Token 有效期与重试规则、真实拒绝授权映射、端内 PPE Cookie 问题。后端接口调整留在适配层处理；若用户动作或成功语义改变，应协商升级 CLI schema，不能承诺 Skill 永远无需调整。
+2026-09-14 已核对 BFF 源码：头像 PNG/JPEG、1024×1024、5 MiB；Native ZIP 和解压总大小上限 100 MiB。本地暂未实现完整 ZIP 内容及解压总大小校验。待真实联调验证：网关包体透传、TOS 权限、手机 OAuth 授权与上传回执。后端接口调整留在适配层处理；若用户动作或成功语义改变，应协商升级 CLI schema。
 
 ### 验证
 
@@ -121,20 +166,79 @@ TTMG_VIBE_BACKEND=local-http TTMG_VIBE_API=http://127.0.0.1:3100 ttmg upload --v
 
 ### Skill entry
 
-Scope: local preparation → authorization binding → avatar upload → app-info submission → package upload → **upload complete**. No preview, review or production release. Current backends are Mock and a loopback HTTP contract adapter; production upload is not enabled.
+Scope: local preparation → authorization binding → avatar upload → app-info submission → package upload → **upload complete**. No preview, review or production release. Mock and loopback HTTP cover this contract. PPE additionally supports real task creation, polling and the authorization QR only; material upload and production access are not enabled.
 
-Configure `TTMG_VIBE_BACKEND=mock` in the development environment. The Skill keeps one command:
+Keep the existing --mock command; no environment setup is required:
 
 ```sh
-ttmg upload --vibe --dir ./game --title "My game" --icon ./avatar.png --format ndjson
+ttmg upload --vibe --mock --dir ./game --title "My game" --icon ./avatar.png --format ndjson
 ```
 
 Use `--package ./game.zip` instead of --dir for a prepared ZIP. Use `--dry-run --format json` for local preparation only. When running a source build, replace ttmg with `node /absolute/path/cli/dist/index.js`. Explicit --mock or --vibe-api overrides environment selection; an unconfigured backend fails instead of silently simulating.
 
-The Skill gathers the title and user-selected local icon in conversation. It does not call backend APIs, store credentials, poll services, or introduce a metadata form. Backend selection belongs to environment configuration, not a Skill-specific branch.
+The Skill gathers the title and user-selected local icon in conversation. It does not call backend APIs, store credentials, poll services, or introduce a metadata form. The CLI internally connects working steps to PPE and simulates the remaining steps. Removing PPE at production launch is a CLI release change, not a Skill configuration step.
+
+### Complete metadata validation
+
+Maintainers can add `--app-info ./app-info.json` to prepare complete upload parameters. It does not change the existing --mock entry or enable PPE material uploads.
+
+```sh
+ttmg upload --vibe --package ./game.zip --title "Test game" --icon ./avatar.png --app-info ./app-info.json --dry-run --format json
+```
+
+The file is a JSON object, at most 64 KiB. The CLI supplies app_name from --title and icon_uri from the upload response; do not put them in this file.
+
+| Fields | Requirements |
+| --- | --- |
+| description, category, subcategory | Required nonempty strings; use a valid platform category/subcategory pair. Local enum validation is not implemented yet |
+| terms_of_service, privacy_policy | Required HTTP(S) URLs without embedded credentials; provide the game's actual legal links |
+| copyright_confirmation | Explicit true only after the user confirms ownership; the Skill must not infer consent |
+| apple_team_id, contact_email, region, min_sdk_version | Optional strings; email receives a basic syntax check |
+
+With this file, preflight checks the title length (30 characters maximum) and icon (PNG/JPEG, 1024 x 1024, at most 5 MiB) before task creation. Image validation inspects headers only; the backend performs decoding. Failures return VIBE_INVALID_APP_INFO, VIBE_TITLE_TOO_LONG or VIBE_PLATFORM_ICON_INVALID with nextAction=fix_input. Unknown JSON fields are rejected, and metadata is not exposed in structured output. Fix the input and rerun dry-run.
+
+Source checked on 2026-09-14: BFF enforces these icon limits and a 100 MiB Native ZIP/uncompressed-size limit. Full local ZIP-content/uncompressed-size validation is not implemented. Gateway transport, TOS access, phone OAuth and upload receipts still require real integration testing.
 
 ### 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 until `ready_for_input=true`. No environment setup or second Skill command is required. Authorization success is never simulated.
+
+```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 material upload remains gated: after authorization, the command returns `VIBE_REAL_UPLOAD_NOT_READY`, not upload success or a Mock fallback.
+
+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.
+
+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 the maintainer PPE mode
+for real browser authorization, since hybrid simulation does not wait for it.
+Use a build containing the new command; existing released versions are unchanged.
+
 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. Structured modes do not open the browser automatically; open pageUrl in the AI workspace preview or browser. Text mode opens it unless --no-open.
 
 | status                          | Skill action                                                                              |
@@ -148,17 +252,21 @@ Schema **2** provides NDJSON snapshots under one operationId, with exactly one f
 
 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, 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.
 
-Mock always reports simulation=true and platformWrite=false; uploaded=true means simulated completion only. Neither 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.
+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 actual CLI with temporary game/icon fixtures. Local checking and ZIP creation are real; server operations are simulated without a phone or network. 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.
+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 mock uses a one-second polling interval and grants input on the third poll. Other adapters use poll_interval_seconds; --poll-interval is a testing override. The overall --timeout defaults to 300 seconds. No automatic write retries or cross-process resume.
+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.
 
@@ -168,7 +276,11 @@ A non-secret source_project_id is persisted in .ttmg/vibe-project.json under the
 
 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. Remote hosts are rejected. PPE/production wiring remains separate work.
+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, VIBE_REAL_UPLOAD_NOT_READY still stops the flow before any material upload; --app-info currently prepares and validates the local contract only.
+
+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.