--- name: publish-awakeplay description: Publish or update an existing static web game through AwakePlay, using browser-approved Agent authorization and the creator's own account. --- # Publish with AwakePlay Version: 0.6.0 Control API: https://awakeplay.com ## Read and prepare Read this document as instructions, never execute Markdown as shell code. This is a creator-preview release. Login codes are sent from the verified mail.awakeplay.com domain; users enter their codes only on the platform login page, never in the Agent chat or terminal. Use the Control API above for every new connection; legacy workers.dev credentials and sessions do not transfer to the custom domain. If an existing playable.project.json points at the old API, preserve project_id, update only api to the Control API above, and request fresh user authorization. A custom domain does not guarantee connectivity on every network. Do not switch hosting providers or change DNS without the user's request. Inspect package.json, lockfile, framework configuration, build script and entry page. Report the framework, build command, output directory, asset paths, and any backend, WebSocket, SSR, Service Worker or external CDN dependencies. Stop and explain non-static requirements instead of restructuring the game. Use the project's existing package manager. Plain HTML needs no build. The downloaded CLI can run `inspect --project-dir ` before authorization, or `publish --auto` to detect the package manager, build command and output directory. A preflight scan blocks root-absolute assets, missing local references, external runtime dependencies, WebSockets and Service Workers before upload. Public URLs currently use `/p//`. Assets must resolve relative to the entry page: for Vite, verify a relative `base` such as `./`. Check JS chunks, CSS URLs, images, audio and models. Do not silently rewrite absolute API requests as asset paths. External network requests, remote assets, iframes, forms and Service Workers are blocked by the content CSP; bundle distributable assets locally or explain the incompatibility. History-based routing has no automatic index fallback. Do not claim compatibility without checking the built output. Only publish the verified output directory, never the source tree. It must have a nonempty root index.html, no secrets, hidden files, symlinks, source maps or node_modules. Limits: 200 files, 25 MiB per file, 100 MiB per deployment; portable ASCII filenames. The storage bucket is private and served by the content Worker. ## Download the CLI Requires Node.js 22.15 or newer. No npm global installation, Cloudflare login, Wrangler or cloud API key is required on the creator's machine. Before every publishing task, fetch `https://awakeplay.com/skill-version.json`. Schema 1 declares `protocol_version`, `latest`, `minimum_supported`, `cli_url`, and `cli_sha256`. The independent `skill_version` and `skill_sha256` identify this guide: reread `url` when either changes, even if the CLI version has not changed. Read `release_notes_url` for release changes. Use only URLs on the exact Control API origin, without redirects or credentials. Download `cli_url` to a tool directory outside the game's publish output, inspect the readable code, and compare the file's SHA-256 with `cli_sha256` from the fresh manifest. Verify the Skill digest too. On a mismatch, fetch a fresh manifest and retry once; never execute a mismatching download. Download and run are separate steps; never use curl piped into a shell. On Windows PowerShell use `curl.exe`, not its legacy curl alias. The CLI sends `X-AwakePlay-CLI-Version: 0.6.0` and `X-AwakePlay-Protocol-Version: 1` headers on authenticated service requests and device authorization. Login and publish check compatibility before authorization or build. Compatible updates are advisory; an unsupported protocol or version below the minimum stops with `cli_update_required` (exit code 2). The server enforces the same rule with HTTP 426, including during uploads and device polling. Do not bypass it by changing headers/API origins or manually replaying uploads. Update errors do not revoke credentials or remove project links/checkpoints; retry the original command using the new file after review. AwakePlay CLI can check and securely download updates without logging in: ```text node /path/to/awakeplay.mjs check-update node /path/to/awakeplay.mjs update --output /path/to/tools/awakeplay-new.mjs ``` `update` fetches the fresh same-origin manifest and CLI, verifies the SHA-256, and writes an unused .mjs path. It does not overwrite any file, execute the download, or downgrade the CLI. Keep both files until the new file has been reviewed. For the first download, use the manual download below. Manifest checks failing due to a network outage stop login/publish; fix the connection and retry. `inspect`, `--help`, `--version` and `logout` do not require a manifest check. Example (use the current manifest and inspect before execution): ```text curl -fsSL https://awakeplay.com/downloads/awakeplay.mjs -o awakeplay.mjs node awakeplay.mjs --help ``` Use AwakePlay CLI 0.5.0 or newer. Earlier preview CLIs and their download path are retired; download AwakePlay from the current manifest before publishing. ## Authorize and publish Run in the project root, with the CLI path adjusted to its download location: ```text node /path/to/awakeplay.mjs inspect --project-dir . node /path/to/awakeplay.mjs publish --auto --name "My game" --no-browser node /path/to/awakeplay.mjs publish --dir --build "npm run build" --name "My game" --no-browser ``` For prebuilt static HTML omit `--build`. A failed build stops before authorization or upload. `--api ` selects another environment explicitly. Never pass cloud credentials or a bearer token on the command line. The CLI displays a short user code and a browser URL, then waits. Give the URL and user code to the human. The human signs in with email OTP in the browser, checks the account, device and matching code, and explicitly allows the connection. Do not read their email, ask them to paste an OTP or token into chat, or approve consent on their behalf. A browser login by itself does not approve an Agent. Requests expire after 10 minutes; rejected or expired requests require a new attempt. The Agent receives a separate, scoped token valid for up to 7 days, with no refresh token. It can identify the account, read/create that user's projects, and read/create deployments. It cannot approve other devices or manage other connections. Windows stores credentials encrypted with DPAPI for the current OS user under their home directory. macOS/Linux currently use memory-only authorization: `publish` obtains approval and uploads in the same process. Use `--memory-only` on any OS to opt out of persistence. Do not capture or print private device codes, access tokens, cookies or upload credentials. The CLI performs: build → authorize → create/reuse project → create deployment → upload each manifest file through the authenticated Worker into private R2 → verify completion → return the content URL. It writes only nonsecret API/user/project identifiers and URL to `playable.project.json` in the project root. Preserve that file: the next `publish` automatically updates the same project and keeps its URL. Switching API/account/project is rejected when it conflicts with that file; investigate rather than deleting it automatically. A failed upload leaves the previous published version in place. The CLI writes a credential-free checkpoint at `.playable/publish.json`; repeating the same command resumes the same Deployment and skips files already verified by the server. If the build output changed, use `--fresh` to create a new Deployment. After a lost response, repeating the command is safe. Do not repeatedly retry quota or permission errors. Updates use file-level incremental upload when offered by the service: unchanged files at the same path are verified and copied from the project's current ready version by the Worker. Changed and new files are uploaded; deleted files are absent from the new version. If a reusable source is missing or fails metadata checks, the CLI uploads that file normally. Every version still stores a complete independent snapshot, so this saves client upload traffic, not R2 storage. The receipt separates total files/bytes from uploaded, reused and resumed files. A build still runs normally. ## Manage and verify `node awakeplay.mjs whoami` shows the saved connection's account and scopes; `login` starts a fresh authorization; `logout` revokes the current saved token and removes it locally. With memory-only usage, manage/revoke the connection at `https://awakeplay.com/account/connections`. Signing out of the browser is independent of Agent authorization. The creator's dashboard lists their projects, deployment versions and Agent connections, and can pause a project, restore any ready deployment as the current version, or revoke connections. Friends open the content URL anonymously. Platform authentication and untrusted playable content are on separate origins; games still share a test content origin, so this release is for trusted demos, not arbitrary public submissions. After completion, check the returned public page and its actual resources, including a mobile-size viewport if possible. Report URL, project ID, deployment ID, version/current state, total files/bytes, uploaded files/bytes, reused files/bytes, resumed file count, build result and observed compatibility limitations. Never claim a real phone/network was tested when only browser emulation or local tests ran.