@spatius/cli 0.1.0-beta.0

package/dist/commands.js

@@ -0,0 +1,10 @@
+import {
+  buildProgram,
+  commandSchema,
+  definitions
+} from "./chunk-YILIK7FE.js";
+export {
+  buildProgram,
+  commandSchema,
+  definitions
+};

package/docs/deployment.md

@@ -0,0 +1,277 @@
+# Deployment and releases
+
+A published GitHub release deploys the production media Worker, then publishes
+`@spatius/cli` with its matching skills and documentation. The executable remains
+`spatius`. Keep the repository private while preparing this setup; perform the
+first publication after it becomes public.
+
+## Release contract
+
+| Setting     | Behavior                                                                                          |
+| ----------- | ------------------------------------------------------------------------------------------------- |
+| Trigger     | GitHub `release.published`, including prereleases; pushing a tag alone does not publish           |
+| Source      | Exact release commit, reachable from `main`; public repository required for provenance            |
+| Version     | Canonical `vX.Y.Z[-prerelease]` tag without build metadata; GitHub prerelease checkbox must agree |
+| npm channel | Any prerelease → `beta`; stable → `latest`                                                        |
+| Worker      | `spatius-cli-media` at `https://cli-media.spatius.ai` for **every** release                       |
+| Runtime     | GitHub-hosted Ubuntu, Node 24, compatible npm, and the workspace's pinned pnpm/Wrangler           |
+
+The workflow validates the release and npm version, runs `pnpm check`, installs
+and tests the exact release tarball, deploys the Worker, checks HTTPS health and
+unauthenticated upload rejection, and publishes that tarball with provenance.
+Only a registry 404 permits a new version; duplicates and registry errors stop
+before deployment. The release version is written in the runner only. There is
+no version commit and no new tag created by CI.
+
+Worker deployments record the release tag and commit SHA. Actions summarizes the
+Worker deployment and npm publication. Keep Worker `/v1` compatible with older
+CLI versions and inputs still in use. Prereleases also update production.
+
+## One-time production setup
+
+### 1. Cloudflare account, bucket, and domain
+
+Use the Spatius Cloudflare account `5e47c9255b3c952c52f162ed53f6e14a`, with Workers
+Paid and R2 enabled, and the active `spatius.ai` zone. In the dashboard, verify
+that `cli-media.spatius.ai` is unused or already belongs to this Worker. Wrangler
+can replace an existing custom-domain origin during noninteractive deployment.
+
+Install dependencies from the repository root, then use the operator's Wrangler
+login to provision storage:
+
+```sh
+pnpm install --frozen-lockfile
+export CLOUDFLARE_ACCOUNT_ID=5e47c9255b3c952c52f162ed53f6e14a
+cd packages/media-worker
+pnpm exec wrangler login
+pnpm exec wrangler whoami
+pnpm exec wrangler r2 bucket create spatius-cli-media-production
+pnpm exec wrangler r2 bucket lifecycle add spatius-cli-media-production temporary-inputs media/ --expire-days 2 --abort-multipart-days 1 --force
+pnpm exec wrangler r2 bucket lifecycle list spatius-cli-media-production
+```
+
+Keep the R2 bucket private: no bucket custom domain and no `r2.dev` access. The
+production Worker configuration attaches `cli-media.spatius.ai` to the Worker
+and disables its `workers.dev` endpoint. Provisioning storage needs the
+operator's R2 permissions; routine release credentials do not create buckets.
+If the bucket or lifecycle rule already exists, inspect and retain it instead
+of repeating creation; lifecycle additions append rules.
+
+### 2. Signing secret and first Worker deployment
+
+From `packages/media-worker`, generate the production key once and pipe it
+directly into Wrangler. The JSON contains a `v1` key matching `SIGNING_KEY_ID`:
+
+```sh
+node --input-type=module -e 'import { randomBytes } from "node:crypto"; process.stdout.write(JSON.stringify({ v1: randomBytes(32).toString("hex") }));' \
+  | pnpm exec wrangler secret put SIGNING_KEYS --env production
+pnpm exec wrangler secret list --env production
+pnpm exec wrangler deploy --env production --dry-run
+pnpm exec wrangler deploy --env production
+curl --fail --silent --show-error --max-time 15 https://cli-media.spatius.ai/health
+```
+
+Wrangler may offer to create the Worker when storing its first secret. The first
+full deployment applies its Durable Object migration and custom domain. Preserve
+the Worker name, bucket, Durable Object binding, and migration history across
+releases. `SIGNING_KEYS` is required; recurring deployments retain the saved
+secret. Do not regenerate it when retrying deployment.
+
+Before npm publication, run the authenticated upload/read check below. `/health`
+checks process/routing only; it does not prove Studio auth, storage, or signing.
+No Console signing secret, renderer token, app API key, or Studio refresh token
+belongs in this Worker.
+
+### 3. GitHub configuration
+
+In `spatius-ai/spatius-cli`, configure:
+
+| Setting                 | Type                        | Value/access                                                                          |
+| ----------------------- | --------------------------- | ------------------------------------------------------------------------------------- |
+| `CLOUDFLARE_API_TOKEN`  | Actions repository secret   | **Workers Scripts: Edit** for the production account; **Zone: Read** for `spatius.ai` |
+| `CLOUDFLARE_ACCOUNT_ID` | Actions repository variable | `5e47c9255b3c952c52f162ed53f6e14a`                                                    |
+
+For example, the GitHub CLI prompts securely for the API token:
+
+```sh
+gh secret set CLOUDFLARE_API_TOKEN --repo spatius-ai/spatius-cli
+gh variable set CLOUDFLARE_ACCOUNT_ID --repo spatius-ai/spatius-cli --body 5e47c9255b3c952c52f162ed53f6e14a
+```
+
+Only the deployment job receives Cloudflare credentials. Only the npm job gets
+`id-token: write`; all jobs have `contents: read`. Leave `SIGNING_KEYS` in
+Cloudflare. Do not configure `NPM_TOKEN`, Studio credentials, or renderer
+credentials in GitHub. No approval environment or release enablement variable
+is required.
+
+### 4. Create the npm package
+
+After the repository is public and production upload/read validation passes,
+use an npm account with 2FA and permission to publish under `@spatius`.
+The package must exist before configuring its trusted publisher, so create
+`0.1.0-beta.0` once from the checked tarball. This initial manual publication has
+no provenance; automated releases have provenance.
+[npm trusted-publisher prerequisites](https://docs.npmjs.com/cli/v11/commands/npm-trust/#prerequisites)
+
+From a clean repository root containing the merged release changes:
+
+```sh
+pnpm install --frozen-lockfile
+pnpm check
+SPATIUS_RELEASE_DIR=$(mktemp -d)
+pnpm package:check -- --artifact-dir "$SPATIUS_RELEASE_DIR"
+npm login --registry=https://registry.npmjs.org
+npm publish "$SPATIUS_RELEASE_DIR/spatius-cli-0.1.0-beta.0.tgz" --access public --tag beta --provenance=false --ignore-scripts
+```
+
+`package:check` retains the validated tarball and `release-artifact.json`
+(name, version, filename, and integrity) in the requested directory. Publish that
+same tarball instead of rebuilding after validation. This bootstrap does not
+need a published GitHub release; publishing `v0.1.0-beta.0` afterward would fail
+the duplicate-version check. If the package already exists, inspect its versions
+and configure the publisher instead of repeating bootstrap.
+
+### 5. Configure npm trusted publishing
+
+In the npm settings for `@spatius/cli`, add this trusted publisher:
+
+| Field             | Value                           |
+| ----------------- | ------------------------------- |
+| Provider          | GitHub Actions                  |
+| Organization      | `spatius-ai`                    |
+| Repository        | `spatius-cli`                   |
+| Workflow filename | `publish.yml`                   |
+| Environment       | Leave blank                     |
+| Allowed action    | Enable direct **`npm publish`** |
+
+New publishers may default to staged publication; select direct publication so
+GitHub releases complete automatically. npm uses the job's OIDC identity without
+a long-lived token. See [npm trusted publishing](https://docs.npmjs.com/trusted-publishers/).
+
+### 6. Publish releases
+
+After merge and CI pass, select a commit on `main` and publish the first automated
+release as `v0.1.0-beta.1`, with the GitHub prerelease checkbox selected. For
+example, from the clean repository root:
+
+```sh
+git fetch origin main
+SPATIUS_RELEASE_COMMIT=$(git rev-parse origin/main)
+gh release create v0.1.0-beta.1 --repo spatius-ai/spatius-cli --target "$SPATIUS_RELEASE_COMMIT" --prerelease --generate-notes
+```
+
+Wait for its Actions run, then verify:
+
+```sh
+npm install -g @spatius/cli@beta
+spatius --version
+spatius --help
+```
+
+Stable releases use a tag such as `v0.1.0`, with the prerelease checkbox cleared,
+and install with `npm install -g @spatius/cli` (`latest`). No release proceeds
+while the repository is private. Ordinary pushes and pull requests run checks
+without deployment or publication.
+
+## Partial failure and retry
+
+Publish one release at a time. A shared concurrency group with `queue: max`
+keeps pending releases without cancelling a running release. Do not rely on the
+queue to order releases for you.
+
+| Failure                                       | Recovery                                                                                                       |
+| --------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
+| Release validation, registry lookup, or tests | Fix the cause; Worker and npm remain unchanged                                                                 |
+| Worker deployment or post-deployment checks   | npm is not published; inspect the actual Worker deployment before retrying                                     |
+| npm publication after Worker deployment       | Keep the compatible Worker running; inspect npm before retrying. No automatic rollback or publish retry occurs |
+| Version already exists in npm                 | Confirm its integrity/version and the Actions result; do not overwrite or republish it                         |
+| Newer release has deployed since a failure    | Fix forward with a new version; never rerun the older release and roll production backward                     |
+
+Before rerunning a failed release, check its exact version with
+`npm view @spatius/cli@<version> version dist.integrity --json`, and check the
+Worker's release tag/commit in Cloudflare or `wrangler versions list --env production`.
+For an npm-only failure, rerun all jobs only after confirming the version is
+absent and no newer release has deployed. This repeats validation and deployment
+before publication. A network error from npm is not evidence that the version is
+absent.
+
+## Configuration and storage
+
+| Setting                                | Purpose                                                         |
+| -------------------------------------- | --------------------------------------------------------------- |
+| `STUDIO_API_URL`                       | Trusted Studio origin for online `GET /v1/auth/me` validation   |
+| `PUBLIC_URL`                           | Actual Worker HTTPS origin used to sign immutable input URLs    |
+| `SIGNING_KEY_ID`                       | Active key ID for new links                                     |
+| `SIGNING_KEYS` (secret)                | JSON map of key IDs to random secrets of at least 32 characters |
+| `MAX_STORED_BYTES`                     | Per-user reserved/retained byte limit; default 2 GiB            |
+| `MAX_UPLOADS_PER_DAY`                  | New uploads per rolling day; default 100                        |
+| `MAX_UNFINISHED_UPLOADS`               | Unfinished uploads per user; default 10                         |
+| `REQUESTS_PER_SECOND`, `REQUEST_BURST` | Management-operation token bucket; default 10 and 20            |
+
+The Worker streams exact-size 8 MiB parts to private R2, with a smaller final
+part allowed. Each Studio user's SQLite Durable Object persists admission,
+accepted parts, and the completion manifest. The whole-file digest is checked
+before its URL is published. Completed files cannot be overwritten or deleted
+through a public endpoint.
+
+DO alarms abort incomplete uploads after one hour and delete completed inputs
+after 24 hours. Failed cleanup retains quota reservations and retries. Signed
+URLs expire on time even if physical deletion is delayed. R2 lifecycle rules
+are fallback cleanup. For key rotation, add a key to `SIGNING_KEYS`, change
+`SIGNING_KEY_ID`, and retain old keys until every link signed with them expires.
+
+Monitor rejected admissions, authentication outages, upload completion failures,
+and cleanup retries through controlled error codes. Keep invocation URL logging
+disabled; request bodies, auth headers, and signed URLs must not enter logs.
+Run `pnpm --filter @spatius/media-worker typegen` after configuration changes.
+
+## Live smoke tests
+
+Routine CI uses mocks/local bindings and performs no paid generation. Live tests
+need the intended user's Studio login and approved Avatar/Video API access.
+From an unpublished checkout, run `pnpm package:check`, then use
+`node packages/cli/dist/cli.js` in place of `spatius` in these examples.
+
+**Upload/read check:** supply a real `./speech.wav`, a private config directory,
+and the intended media origin. This example needs Node.js. The signed URL stays
+in the pipeline rather than being printed:
+
+```sh
+export SPATIUS_CONFIG_DIR=/absolute/path/to/private-test-config
+export SPATIUS_MEDIA_URL=https://cli-media.spatius.ai
+spatius auth login
+spatius setup
+spatius assets upload ./speech.wav --kind audio | node --input-type=module -e '
+import { createHash } from "node:crypto";
+let input = "";
+for await (const chunk of process.stdin) input += chunk;
+const { data } = JSON.parse(input);
+if (data.status !== "completed") throw new Error("Upload not completed");
+const response = await fetch(data.url, { redirect: "error", signal: AbortSignal.timeout(30000) });
+if (!response.ok) throw new Error("Signed file read failed");
+const bytes = Buffer.from(await response.arrayBuffer());
+if (bytes.length !== data.size || createHash("sha256").update(bytes).digest("hex") !== data.sha256) throw new Error("File mismatch");
+console.log("Authenticated upload and signed read passed");'
+```
+
+Repeat setup and confirm the app ID is reused. Verify unsigned file reads and
+unauthenticated upload-management calls fail, and that a second Studio user
+cannot read/manage the first user's upload ID. The automated release probes
+check only health and unauthenticated rejection, not this authenticated flow.
+
+**Avatar → video → MP4:** follow the complete create/poll/download example in
+[workflows](workflows.md) using a real portrait, speech, and optional background.
+Save operation/job IDs, check progress, download the MP4 before expiry, and
+verify audio/video playback. Avatar creation and video generation use existing
+service allowances/accounting. Interrupted submissions should resume the saved
+operation; confirm only one remote job exists. Keep private inputs, IDs, and
+signed URLs out of public CI logs.
+
+**Staging:** use the separate `spatius-cli-media-staging` Worker and bucket,
+`--env staging`, and set `SPATIUS_MEDIA_URL` to
+`https://spatius-cli-media-staging.472617147.workers.dev`. Provision the same
+lifecycle rule on that bucket and its own signing key. If Studio uses staging
+hosts, set API `SPATIUS_STUDIO_URL` and browser `SPATIUS_STUDIO_WEB_URL`
+separately. The CLI requires completed upload links to match its configured
+media origin. The existing [staging validation record](staging-validation.md)
+is evidence for staging, not production readiness.

package/docs/staging-validation.md

@@ -0,0 +1,46 @@
+# Staging validation
+
+Validated on 2026-09-12 UTC. This is a staging record, not a production release.
+
+Final `pnpm check` passed on Node.js 22.23.2: **58 CLI tests, 27 Worker tests**,
+three packaged skills with 29 validated examples, type checks, lint, formatting,
+npm artifact installation, and the Worker deployment dry run.
+
+| Check                              | Result                                                  |
+| ---------------------------------- | ------------------------------------------------------- |
+| Studio browser login               | Passed with the real API and browser approval origins   |
+| App bootstrap                      | Passed; two setup calls reused the same dedicated app   |
+| Authenticated temporary upload     | Passed with a 649,644-byte real speech WAV              |
+| Signed input download              | HTTP 200; byte count and SHA-256 matched the source     |
+| Missing login / tampered signature | Rejected with HTTP 401 / 403                            |
+| Avatar list                        | HTTP 200; the account currently has no owned avatars    |
+| Video creation                     | Passed by resuming the original saved request           |
+| Video list                         | HTTP 200; exactly one succeeded job                     |
+| Video polling                      | Observed processing/rendering, then succeeded/completed |
+| MP4 download and decoding          | Passed; 1024×1024, 25 fps, H.264/AAC, 22.08 seconds     |
+| Live avatar creation               | Not run; remains a separate release check               |
+
+The staging Worker is
+`https://spatius-cli-media-staging.472617147.workers.dev`, backed by the private
+`spatius-cli-media-staging` R2 bucket. Lifecycle fallback rules delete objects
+after two days and abort multipart uploads after one day; the application
+enforces its shorter upload and signed-link deadlines.
+
+The original saved video operation was resumed after the Console deployment and
+access updates. Console accepted the request and completed it in approximately
+47 seconds. The CLI polled the job, refreshed its signed output link, and saved
+a 2,285,695-byte MP4. `ffprobe` confirmed H.264 video at 1024×1024 and 25 fps,
+with mono 16 kHz AAC audio; both streams are 22.08 seconds long. A full `ffmpeg`
+decode completed without errors. The account's job list contained exactly one
+succeeded job after the retry.
+
+The operation, credentials, and input links remain in the private CLI
+configuration directory. Do not put account identifiers, input URLs, keys, or
+tokens in public validation reports. The authenticated upload-to-video workflow
+has passed; live portrait-to-avatar creation remains a separate release check.
+
+Automated checks cover login and app recovery, multipart limits and leases,
+native Worker request construction, interrupted submission and resume, polling,
+download, terminal failures, packaged skills, and npm installation. The Worker
+suite also streams a complete 500 MiB upload through 63 local R2 parts. See
+`pnpm check` and [the deployment guide](deployment.md) for repeatable checks.

package/docs/workflows.md

@@ -0,0 +1,134 @@
+# Avatar and video workflows
+
+## Authentication and output
+
+Run `spatius auth login`, approve in a browser on the same machine, then run
+`spatius setup`. Login is required for credential setup and temporary uploads;
+Open API enablement still requires administrator approval. The CLI does not
+grant access or alter creation allowances. API-key-only CLI use is not supported.
+
+The Studio API and browser approval page have separate origins. Environment
+settings are optional for production; configure both origins explicitly when
+using a development or staging Studio deployment.
+
+| Environment variable     | Default                         | Purpose                                         |
+| ------------------------ | ------------------------------- | ----------------------------------------------- |
+| `SPATIUS_STUDIO_URL`     | `https://api.studio.spatius.ai` | Login/token, identity, and app/key API requests |
+| `SPATIUS_STUDIO_WEB_URL` | `https://app.spatius.ai`        | Expected browser approval origin                |
+| `SPATIUS_CONSOLE_URL`    | `https://console.spatius.ai`    | Avatar and Video Open APIs                      |
+| `SPATIUS_MEDIA_URL`      | `https://cli-media.spatius.ai`  | Temporary uploads and input links               |
+
+The web origin must match the Studio backend's configured frontend URL.
+Credential-bearing API requests reject redirects; the browser URL must match
+the configured web origin and the exact authorization request path.
+
+Commands return `{ "schemaVersion": 1, "ok": true, "data": ... }` on stdout.
+Errors use `ok: false` and `error.code/message/retryable/recovery` on stderr.
+Progress is also written to stderr. Help and version are plain text.
+
+| Exit code | Meaning                                              |
+| --------- | ---------------------------------------------------- |
+| 0         | Success                                              |
+| 1         | Operation failed; inspect the structured error       |
+| 2         | Invalid command arguments                            |
+| 3         | Waiting reached its deadline; the job remains active |
+| 130       | Interrupted locally; no remote job is cancelled      |
+
+## Create, poll, and download
+
+This Bash example requires `jq`. Supply your own portrait and speech files.
+
+```sh
+set -euo pipefail
+spatius auth login
+spatius setup
+AVATAR_CREATE=$(spatius avatars create --image ./portrait.png --name Presenter)
+AVATAR_JOB_ID=$(printf '%s' "$AVATAR_CREATE" | jq -er '.data.jobId')
+AVATAR_RESULT=$(spatius avatars jobs wait "$AVATAR_JOB_ID" --timeout 600)
+AVATAR_ID=$(printf '%s' "$AVATAR_RESULT" | jq -er '.data.job.avatarId')
+VIDEO_CREATE=$(spatius videos create --avatar-id "$AVATAR_ID" --audio ./speech.wav)
+VIDEO_JOB_ID=$(printf '%s' "$VIDEO_CREATE" | jq -er '.data.jobId')
+spatius videos wait "$VIDEO_JOB_ID" --timeout 600
+spatius videos download "$VIDEO_JOB_ID" --output ./video.mp4
+```
+
+If waiting exits 3, run the same wait command again. Creation accepts `--wait`
+as a convenience, but submitting and waiting separately makes job IDs easier
+to retain. Every creation exposes an operation ID in its result or recovery
+error; progress reports the ID before external preparation begins.
+
+## Inputs and presentation
+
+| Input           | Types                                                         | Maximum size |
+| --------------- | ------------------------------------------------------------- | -----------: |
+| Avatar portrait | JPEG, opaque PNG; shorter side ≥340 pixels and one clear face |        5 MiB |
+| Audio           | WAV, MP3, M4A/MP4 audio, AAC, Ogg                             |      500 MiB |
+| Background      | JPEG, PNG, WebP                                               |       50 MiB |
+
+The CLI and upload Worker check basic file signatures and sizes. Avatar content,
+PNG opacity, image dimensions, audio decoding, and audio duration remain validated
+by the existing services. Raw PCM and octet-stream sources are unsupported.
+
+Use local paths or public HTTP(S) URLs, including signed URLs. Caller-supplied
+URLs are not fetched by the CLI; existing Console download protections apply.
+They cannot contain embedded credentials or point to private networks.
+
+| Video option                              | Default | Allowed values                                |
+| ----------------------------------------- | ------- | --------------------------------------------- |
+| `--width`, `--height`                     | 1024    | Even integers 64–1920; area ≤2,073,600 pixels |
+| `--fit`                                   | crop    | crop, contain                                 |
+| `--background-color`                      | #000000 | Six-digit RGB hex                             |
+| `--background-fit`                        | cover   | cover, contain, stretch                       |
+| `--lead-in-seconds`, `--lead-out-seconds` | 0       | Finite values 0–60                            |
+
+Quote hex colors in shells. Encoding is service-controlled. Source URLs need to
+cover the preparation window of up to 30 minutes. Temporary inputs are immutable
+and expire 24 hours after upload completion. Anyone with a signed input URL can
+read it until expiry; avoid sharing these URLs outside the intended workflow.
+
+## Resume safely
+
+| Situation                                 | Action                                                                                                                                                    |
+| ----------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Interrupted upload                        | Re-run `assets upload <same-file> --kind <kind> --resume <upload-or-operation-id>`; accepted parts are reused. An aborted multipart needs a fresh upload. |
+| Video preparation or uncertain submission | `videos create --resume <operation-id>` reuses the saved request UUID and exact URLs.                                                                     |
+| Repeating a chosen video `--request-id`   | The same original input resumes its operation; different input conflicts before uploading.                                                                |
+| Avatar submission response lost           | `SUBMISSION_UNCERTAIN`: inspect recent avatar jobs and reconcile. Automatic resubmission is unsafe because this API has no retry key.                     |
+| Known job                                 | Poll/wait by job ID; do not submit again.                                                                                                                 |
+| Terminal failure                          | Fix its cause and intentionally start a new operation if wanted. `retryable` does not restart a job.                                                      |
+| Output link expired                       | `videos download` requests a fresh link, while output retention remains unchanged.                                                                        |
+
+Downloads require direct HTTPS output links and use no Studio/app authentication
+headers. Redirects are rejected with a retryable availability error; run download
+again for a fresh link. Loopback HTTP is allowed only when the CLI Console origin
+is explicitly configured for loopback development. Downloads stream into a temporary
+file in the destination directory, then rename atomically. Existing files require
+`--force`. Video output currently expires seven days after submission; use
+`job.expiresAt` as authoritative. Expired output cannot be recovered by refreshing
+a link.
+
+## Account and storage limits
+
+The existing APIs enforce user-level permissions, request rates, avatar concurrency,
+and billing. The CLI does not add a video concurrency quota. All apps belonging
+to one account share the server's Open API policies.
+
+Temporary storage separately defaults to 2 GiB reserved/retained per user,
+100 new uploads per rolling day, and 10 unfinished uploads. Management requests
+are limited to 10/second with burst 20. Unfinished uploads expire after one hour.
+Rejected requests return controlled errors; repeated upload admission with the
+same retry UUID does not consume another reservation.
+
+Credentials and saved input URLs are stored under private user configuration,
+outside repositories. On macOS/Linux use `$XDG_CONFIG_HOME/spatius` or
+`~/.config/spatius`; Windows uses `%APPDATA%/Spatius`. Set `SPATIUS_CONFIG_DIR`
+to an absolute private directory to isolate test accounts. macOS/Linux are the
+validated v1 platforms; Windows storage relies on inherited user-directory ACLs.
+
+If the cached CLI app was deleted, `spatius setup` reconciles existing apps and
+creates a replacement when needed. An explicit `--app-id` is never silently replaced.
+
+Logout clears local tokens and cached API keys and attempts refresh revocation.
+The current Studio backend does not immediately revoke already issued access
+tokens. It also does not provide cross-machine app-creation deduplication:
+simultaneous first-time setup may require selecting among matching apps.

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@spatius/cli",
+  "version": "0.1.0-beta.0",
+  "description": "Spatius avatar and video workflows for coding agents",
+  "type": "module",
+  "license": "MIT",
+  "bin": {
+    "spatius": "./dist/cli.js"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "files": [
+    "dist",
+    "skills",
+    "docs",
+    "README.md",
+    "LICENSE",
+    "THIRD_PARTY_NOTICES.md"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/spatius-ai/spatius-cli.git",
+    "directory": "packages/cli"
+  },
+  "scripts": {
+    "build": "tsup && node ../../scripts/package-assets.mjs",
+    "dev": "tsx src/cli.ts",
+    "typecheck": "tsc -p tsconfig.json",
+    "test": "vitest run",
+    "prepack": "pnpm build"
+  },
+  "dependencies": {
+    "commander": "^14.0.0"
+  },
+  "devDependencies": {
+    "@spatius/contracts": "workspace:*",
+    "tsup": "^8.5.0",
+    "tsx": "^4.20.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  }
+}

package/skills/spatius-avatar/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: spatius-avatar
+description: Create Spatius avatars from portrait images, inspect account avatars, and poll avatar creation jobs with Spatius CLI. Use for avatar creation and recovery, including preparing local image inputs.
+license: MIT
+---
+
+# Create a Spatius avatar
+
+Check `spatius auth status` and use the shared setup skill if login or app setup
+is missing. Read `spatius schema avatars create` for installed command details.
+
+Use an existing local portrait or the user's public URL. The image must be JPEG
+or PNG, at most 5 MiB, with its shorter side at least 340 pixels. PNG must be
+opaque; the portrait must contain one clearly visible face. These requirements
+are finally checked by the service. Do not assume an accepted job has passed them.
+
+```sh
+spatius avatars create --image ./portrait.png --name Presenter --dry-run
+spatius avatars create --image ./portrait.png --name Presenter
+```
+
+Use the actual input path. Local files upload automatically; URL inputs are
+passed to the service. Avatar creation consumes the user's existing Avatar
+Creations allowance. Return promptly after acceptance, retaining `operationId`
+and `jobId`, then wait or inspect:
+
+```sh
+spatius avatars jobs wait 00000000-0000-4000-8000-000000000001 --timeout 600
+```
+
+Replace the example UUID with the returned job ID. On success use `job.avatarId`
+for a video request. A wait timeout preserves the job; run wait/get again.
+
+On a preparation interruption, resume with
+`spatius avatars create --resume <operation-id>`. An uncertain submission cannot
+be repeated safely: this API has no creation retry key. If the CLI returns
+`SUBMISSION_UNCERTAIN`, inspect recent jobs or ask the user to reconcile the
+operation. Never automatically submit another avatar because the response was lost.
+
+Fix a failed image or permission issue before proposing a replacement creation.
+Do not retry terminal jobs in a loop, even when `job.error.retryable` is true.

package/skills/spatius-shared/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: spatius-shared
+description: Set up Spatius CLI authentication and app credentials, inspect command schemas, and recover account access for avatar or video workflows. Use when preparing Spatius CLI or resolving its authentication and setup errors.
+license: MIT
+---
+
+# Spatius setup and shared behavior
+
+Use the installed `spatius` executable. If installation is needed, the prerelease
+package is `@spatius/cli@beta` (`npm install -g @spatius/cli@beta`); stable releases
+use `@spatius/cli`. The executable name remains `spatius`.
+Read `spatius --version` and `spatius schema` to discover the installed contract.
+The CLI requires Node.js 22+. The npm package includes matching skills under
+`skills/`; prefer those over default-branch skills when versions differ.
+
+```sh
+spatius auth status
+spatius auth login
+spatius setup
+```
+
+The production browser approval origin is `https://app.spatius.ai`; the Studio
+API is `https://api.studio.spatius.ai`. For an explicitly configured development
+environment, `SPATIUS_STUDIO_WEB_URL` selects the approved browser origin and
+`SPATIUS_STUDIO_URL` selects the API. Do not change these to bypass an
+`UNSAFE_AUTH_URL` error; check the intended environment first.
+
+Run login only when needed. It opens a local browser approval page and waits up
+to five minutes. Hand the approval URL to the user; keep the process alive until
+approval or timeout. The browser must reach the CLI's localhost callback. A
+remote agent without that connection needs the user to run login on the machine
+where subsequent CLI commands run. Do not request tokens or passwords in chat.
+
+Setup reuses an owned `Spatius CLI` app and key. If selection is required, use
+`spatius apps list` and `spatius setup --app-id <id>`. Never read credential files
+to obtain keys. Login does not grant Avatar or Video API approval; report a 403
+as an account/permission issue instead of repeatedly logging in.
+
+Success is one JSON object on stdout with `schemaVersion`, `ok`, and `data`.
+Progress and structured failures go to stderr. Inspect the exit code and error
+`code`, `retryable`, and `recovery`; avoid parsing decorative human text. Exit 3
+means a wait deadline, and does not cancel the remote job.
+
+Save returned operation and job IDs. After interrupted creation, use the saved
+operation's resume command; after admission, poll its job. An error marked
+retryable is not authorization to create another paid job indefinitely.
+
+For ambiguous setup, rotating-token failures, or source-link privacy, read
+[recovery](references/recovery.md). Do not use `setup --retry-uncertain` until the
+uncertain creation has been reconciled and another creation is intended.

package/skills/spatius-shared/references/recovery.md

@@ -0,0 +1,24 @@
+# Recovery and credential boundaries
+
+| Condition                           | Next action                                                                                                                                                                         |
+| ----------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| No login or `AUTH_RELOGIN_REQUIRED` | Have the user approve `spatius auth login` locally. A lost refresh response cannot safely reuse the old rotating token.                                                             |
+| `UNSAFE_AUTH_URL`                   | Verify `SPATIUS_STUDIO_WEB_URL` matches the intended Studio frontend; `SPATIUS_STUDIO_URL` is the separate API origin. Do not approve an unexpected host.                           |
+| App selection required              | Choose an owned app from sanitized candidates and run `spatius setup --app-id <id>`.                                                                                                |
+| `BOOTSTRAP_UNCERTAIN`               | Run setup again to reconcile through reads. If unresolved, explain that the prior app/key creation may have succeeded; only use `--retry-uncertain` when a new attempt is intended. |
+| HTTP 402                            | Ask the user to check the Avatar Creations balance in Studio.                                                                                                                       |
+| HTTP 403                            | Check API enablement or avatar permission with the administrator. Login does not change the allowlist.                                                                              |
+| HTTP 429                            | Respect the retry hint. Stop after bounded retries and report the limiting condition.                                                                                               |
+
+If a cached app was deleted, run `spatius setup` to select or create its replacement.
+If an explicitly supplied `--app-id` is unavailable, choose an owned app instead;
+the CLI does not silently replace an explicit selection.
+
+Do not echo credentials, refresh tokens, or credential-file contents. Download
+URLs and temporary input URLs are bearer links: anyone possessing them can read
+the file until expiry. Use them only for the intended workflow; avoid putting
+them in commits, issue bodies, or diagnostics.
+
+Logout clears local credentials and attempts refresh-token revocation. The
+existing Studio backend does not immediately invalidate already issued access
+tokens. Never claim that logout has remotely revoked every credential.