ci(docs): catch docs that drift from the CLI

.github/workflows/docs-impact.yml

@@ -0,0 +1,62 @@
+name: Docs impact
+
+permissions:
+  contents: read
+
+# Suppress hyperframes CLI telemetry from HeyGen's own CI runs.
+# External users' CI continues to emit telemetry unless they set this themselves.
+env:
+  HYPERFRAMES_NO_TELEMETRY: "1"
+
+# No path filter: a public export can change from any package source, and the script passes at once when
+# neither the CLI nor a package changed. `edited`, `labeled` and `unlabeled` start a fresh run when the
+# opt-out changes; re-running an old run would reuse the event's stale body and labels. Reading the label
+# and body from the event payload needs no extra permission, fork PRs included. Not a merge-queue check:
+# a merge group has no PR body (see merge-queue-workflows.test.mjs before adding merge_group).
+on:
+  pull_request:
+    types: [opened, synchronize, reopened, edited, labeled, unlabeled]
+    branches: [main]
+
+concurrency:
+  group: docs-impact-${{ github.event.pull_request.number }}
+  cancel-in-progress: true
+
+jobs:
+  docs-impact:
+    name: Docs impact
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
+        with:
+          fetch-depth: 0
+
+      - uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2
+
+      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
+        with:
+          node-version: 22
+
+      # HEAD is the PR merge ref; its first parent is the current base tip, unlike the payload's
+      # base.sha, which goes stale and would count the base's newer commits as the PR's changes.
+      - name: Find the pull request's current base
+        id: base
+        run: |
+          git rev-parse --verify -q HEAD^2 > /dev/null || { echo "::error::HEAD is not the pull request merge commit"; exit 1; }
+          sha="$(git rev-parse --verify HEAD^1)"
+          echo "sha=$sha" >> "$GITHUB_OUTPUT"
+          git diff --quiet "$sha" HEAD -- packages/cli/src || echo "cli=true" >> "$GITHUB_OUTPUT"
+
+      - run: bash scripts/ci/install-workspace-dependencies.sh
+
+      # Only a CLI change needs the command tree, which imports core's generated sources.
+      - if: steps.base.outputs.cli == 'true'
+        run: bun run --cwd packages/core build
+
+      - name: Require docs for CLI and public export changes
+        env:
+          BASE_SHA: ${{ steps.base.outputs.sha }}
+          PR_BODY: ${{ github.event.pull_request.body }}
+          PR_LABELS: ${{ toJSON(github.event.pull_request.labels.*.name) }}
+        run: node scripts/check-docs-impact.mjs --base "$BASE_SHA"

.github/workflows/docs.yml

@@ -16,13 +16,23 @@ on:
       - "DOCS_GUIDELINES.md"
       - "packages/core/schemas/**"
       - "scripts/sync-schemas.ts"
+      # A CLI change can strand a command or flag the docs still show.
+      - "packages/cli/src/**"
+      - "scripts/cli-command-tree.ts"
+      - "scripts/check-docs-cli-references.mjs"
+      - ".github/workflows/docs.yml"
   push:
     branches: [main]
     paths:
       - "docs/**"
       - "DOCS_GUIDELINES.md"
       - "packages/core/schemas/**"
       - "scripts/sync-schemas.ts"
+      # A CLI change can strand a command or flag the docs still show.
+      - "packages/cli/src/**"
+      - "scripts/cli-command-tree.ts"
+      - "scripts/check-docs-cli-references.mjs"
+      - ".github/workflows/docs.yml"
 
 concurrency:
   group: docs-${{ github.ref }}
@@ -52,3 +62,24 @@ jobs:
         # --check-redirects also resolves every redirect destination, so a
         # restructure cannot leave a redirect pointing at a page it removed.
         run: npx mint broken-links --check-redirects
+
+  cli-references:
+    name: CLI references
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
+
+      - uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2
+
+      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
+        with:
+          node-version: 22
+
+      - run: bash scripts/ci/install-workspace-dependencies.sh
+
+      # The command tree loads the CLI's command modules, which import core's generated sources.
+      - run: bun run --cwd packages/core build
+
+      - name: Check every command and flag the docs show exists in the CLI
+        run: node scripts/check-docs-cli-references.mjs

docs/packages/cli.mdx

@@ -23,13 +23,13 @@ npm install -g hyperframes
 | You want to              | Use                                                                                                                                                                                                                              |
 | ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | Start a project          | [`init`](#init), [`add`](#add), [`catalog`](#catalog)                                                                                                                                                                            |
-| Bring in source material | [`capture`](#capture), [`transcribe`](#transcribe), [`tts`](#tts), [`remove-background`](#remove-background), [`media-treatment`](#media-treatment), [`beats`](#beats), [`audio`](#audio), [`normalize-audio`](#normalize-audio) |
+| Bring in source material | [`capture`](#capture), [`transcribe`](#transcribe), [`tts`](#tts), [`remove-background`](#remove-background), [`media-treatment`](#media-treatment), [`beats`](#beats), [`audio`](#audio), [`normalize-audio`](#normalize-audio), [`models`](#models) |
 | Look at it, or share it  | [`preview`](#preview), [`present`](#present-and-play), [`play`](#present-and-play), [`publish`](#publish), [`open`](#open-and-catch-up), [`catch-up`](#open-and-catch-up)                                                        |
 | Find problems            | [`lint`](#lint), [`check`](#check), [`snapshot`](#snapshot), [`keyframes`](#keyframes), [`compare`](#compare-and-grade-compare), [`grade-compare`](#compare-and-grade-compare)                                                   |
 | Edit from the terminal   | [`timeline`](#timeline), [`history`](#history)                                                                                                                                                                                   |
 | Make a file              | [`render`](#render), [`benchmark`](#benchmark)                                                                                                                                                                                   |
 | Render somewhere else    | [`cloud`](#hyperframes-cloud), [`lambda`](#hyperframes-lambda), [`cloudrun`](#hyperframes-cloudrun)                                                                                                                              |
-| Fix your setup           | [`doctor`](#doctor), [`browser`](#browser), [`upgrade`](#upgrade), [`docs`](#docs), [`info`](#info-and-compositions), [`compositions`](#info-and-compositions)                                                                   |
+| Fix your setup           | [`doctor`](#doctor), [`browser`](#browser), [`upgrade`](#upgrade), [`docs`](#docs), [`info`](#info-and-compositions), [`compositions`](#info-and-compositions), [`clean`](#clean)                                                |
 | Connect other tools      | [`auth`](#hyperframes-auth), [`skills`](#skills), [`figma`](#figma-and-events), [`telemetry`](#telemetry), [`feedback`](#feedback)                                                                                               |
 
 `validate`, `inspect`, and `layout` still work but are
@@ -73,11 +73,12 @@ prompts, apart from confirmations you can skip with `--yes` or `--no-confirm`.
 
 **Version notices.** An owned install (npm, bun, pnpm, brew) updates itself
 quietly in the background and prints one line on the next run:
-`hyperframes auto-updated to v0.1.5`. It never crosses a major version. Anywhere
+{/* cli-references: ignore */}
+`hyperframes auto-updated to v0.8.181`. It never crosses a major version. Anywhere
 it cannot install — `npx`, an unknown installer — you get a notice instead:
 
 ```
-  Update available: 0.1.4 → 0.1.5
+  Update available: 0.8.180 → 0.8.181
   Run: npx hyperframes@latest
 ```
 

docs/studio-app/index.mdx

@@ -38,19 +38,29 @@ green guide, points you to the next step along the way.
   <Tab title="Linux">
     <Steps>
       <Step title="Download">
-        Go to [hyperframes.dev/studio](https://hyperframes.dev/studio) and choose **Download** next to Linux. You get
-        one file, `HyperFrames-x86_64.AppImage`, for 64-bit Intel and AMD computers.
+        Go to [hyperframes.dev/studio](https://hyperframes.dev/studio) and choose **Download** next to Linux (.deb).
+        You get `HyperFrames-amd64-<build>.deb` for 64-bit Intel and AMD computers on Debian, Ubuntu and their
+        relatives.
       </Step>
-      <Step title="Make it runnable and open it">
+      <Step title="Install it and open it">
         In a terminal, in the folder you downloaded it to:
 
         ```bash
-        chmod +x HyperFrames-x86_64.AppImage
-        ./HyperFrames-x86_64.AppImage
+        sudo apt install ./HyperFrames-amd64-*.deb
         ```
+
+        Then open **HyperFrames** from your app menu.
       </Step>
     </Steps>
 
+    Prefer one portable file, or not on a Debian-based system? Choose **Linux (AppImage)** instead, then in the
+    folder you downloaded it to:
+
+    ```bash
+    chmod +x HyperFrames-x86_64-*.AppImage
+    ./HyperFrames-x86_64-*.AppImage
+    ```
+
     The AppImage is the whole app. Keep it anywhere you like and open it the same way next time.
   </Tab>
 </Tabs>

package.json

@@ -34,6 +34,8 @@
     "check:tracked-artifacts": "node scripts/check-tracked-artifacts.mjs",
     "check:docs-snippet-motion": "node scripts/check-docs-snippet-motion.mjs",
     "check:docs-catalog": "node scripts/check-docs-catalog.mjs",
+    "check:docs-cli-references": "node scripts/check-docs-cli-references.mjs",
+    "check:docs-impact": "node scripts/check-docs-impact.mjs",
     "generate:catalog": "bun scripts/generate-catalog.ts",
     "check:catalog-drift": "tsx scripts/catalog-drift.ts",
     "verify:catalog-payloads": "tsx scripts/verify-catalog-payloads.ts",
@@ -53,7 +55,7 @@
     "player:perf": "bun run --filter @hyperframes/player perf",
     "format:check": "oxfmt --check .",
     "knip": "knip",
-    "test:scripts": "node --import tsx --test scripts/animejs-v4-guidance.test.mjs scripts/check-tracked-artifacts.test.mjs scripts/check-registry-set-delta.test.mjs scripts/check-no-main-deletions.test.mjs scripts/check-pr-captures.test.mjs scripts/check-comment-citations.test.mjs scripts/comments-workflow.test.mjs scripts/comment-ratchet.test.mjs scripts/check-docs-snippet-motion.test.mjs scripts/registry-target-paths.test.mjs scripts/check-workspace-contracts.test.mjs scripts/check-media-use-copy-parity.test.mjs scripts/check-svg-sanitize-parity.test.mjs scripts/check-media-use-svg-sanitize-generated.test.mjs scripts/check-package-cycles.test.mjs scripts/check-cli-process-ownership.test.mjs scripts/check-studio-copy-dashes.test.mjs scripts/check-large-files.test.mjs scripts/package-subpaths.test.mjs scripts/validate-release-channel.test.mjs scripts/clawhub-sync.test.mjs scripts/publish-workflow.test.mjs scripts/pr-edit-concurrency.test.mjs scripts/merge-queue-workflows.test.mjs scripts/install-workspace-dependencies.test.mjs scripts/check-edit-accuracy-filter.test.mjs scripts/edit-accuracy-retry.test.mjs scripts/draft-changelog.test.ts scripts/set-version.test.ts scripts/release-prepare.test.ts scripts/cli-options.test.ts scripts/changelog-weekly.test.ts scripts/claude-plugin-compression.test.ts scripts/catalog-payload-assets.test.ts scripts/host-registry-assets.test.ts scripts/catalog-preview-temp.test.ts scripts/backfill-block-previews.test.ts scripts/catalog-hosted-files.test.ts scripts/player-cdn-pin.test.ts scripts/studio-runtime-smoke.test.mjs scripts/verify-packed-manifests.test.mjs scripts/rewrite-relative-import-extensions.test.mjs scripts/lint-skills.test.mjs scripts/creator-editing-recipes.test.mjs packages/gcp-cloud-run/check-dockerfile-workspaces.test.mjs packages/core/scripts/writeGeneratedFile.test.ts scripts/catalog-publication.test.mjs scripts/ci/resolve-workflow-pr.test.mjs scripts/ci/base-file.test.mjs scripts/check-catalog-source-pr.test.mjs scripts/generate-registry-items.test.ts scripts/catalog-drift.test.ts scripts/catalog-fetch-mirror.test.ts scripts/catalog-script-inlining.test.ts scripts/catalog-detail.test.ts scripts/generate-catalog-pages.test.ts scripts/verify-catalog-payloads.test.ts scripts/registry-skill-files.test.ts scripts/creator-editing-capabilities.test.mjs scripts/generate-catalog-previews.test.ts scripts/registry-primitive-payloads.test.ts registry/components/pan-stations/pan-stations.test.mjs registry/components/filmed-screen/filmed-screen.test.mjs && vitest run scripts/catalog/ scripts/contrastRatchet.test.ts scripts/generate-catalog-payloads.test.ts",
+    "test:scripts": "node --import tsx --test scripts/animejs-v4-guidance.test.mjs scripts/check-tracked-artifacts.test.mjs scripts/check-registry-set-delta.test.mjs scripts/check-no-main-deletions.test.mjs scripts/check-pr-captures.test.mjs scripts/check-comment-citations.test.mjs scripts/comments-workflow.test.mjs scripts/comment-ratchet.test.mjs scripts/check-docs-snippet-motion.test.mjs scripts/cli-command-tree.test.ts scripts/check-docs-cli-references.test.mjs scripts/check-docs-impact.test.mjs scripts/public-api-surface.test.mjs scripts/registry-target-paths.test.mjs scripts/check-workspace-contracts.test.mjs scripts/check-media-use-copy-parity.test.mjs scripts/check-svg-sanitize-parity.test.mjs scripts/check-media-use-svg-sanitize-generated.test.mjs scripts/check-package-cycles.test.mjs scripts/check-cli-process-ownership.test.mjs scripts/check-studio-copy-dashes.test.mjs scripts/check-large-files.test.mjs scripts/package-subpaths.test.mjs scripts/validate-release-channel.test.mjs scripts/clawhub-sync.test.mjs scripts/publish-workflow.test.mjs scripts/pr-edit-concurrency.test.mjs scripts/merge-queue-workflows.test.mjs scripts/install-workspace-dependencies.test.mjs scripts/check-edit-accuracy-filter.test.mjs scripts/edit-accuracy-retry.test.mjs scripts/draft-changelog.test.ts scripts/set-version.test.ts scripts/release-prepare.test.ts scripts/cli-options.test.ts scripts/changelog-weekly.test.ts scripts/claude-plugin-compression.test.ts scripts/catalog-payload-assets.test.ts scripts/host-registry-assets.test.ts scripts/catalog-preview-temp.test.ts scripts/backfill-block-previews.test.ts scripts/catalog-hosted-files.test.ts scripts/player-cdn-pin.test.ts scripts/studio-runtime-smoke.test.mjs scripts/verify-packed-manifests.test.mjs scripts/rewrite-relative-import-extensions.test.mjs scripts/lint-skills.test.mjs scripts/creator-editing-recipes.test.mjs packages/gcp-cloud-run/check-dockerfile-workspaces.test.mjs packages/core/scripts/writeGeneratedFile.test.ts scripts/catalog-publication.test.mjs scripts/ci/resolve-workflow-pr.test.mjs scripts/ci/base-file.test.mjs scripts/check-catalog-source-pr.test.mjs scripts/generate-registry-items.test.ts scripts/catalog-drift.test.ts scripts/catalog-fetch-mirror.test.ts scripts/catalog-script-inlining.test.ts scripts/catalog-detail.test.ts scripts/generate-catalog-pages.test.ts scripts/verify-catalog-payloads.test.ts scripts/registry-skill-files.test.ts scripts/creator-editing-capabilities.test.mjs scripts/generate-catalog-previews.test.ts scripts/registry-primitive-payloads.test.ts registry/components/pan-stations/pan-stations.test.mjs registry/components/filmed-screen/filmed-screen.test.mjs && vitest run scripts/catalog/ scripts/contrastRatchet.test.ts scripts/generate-catalog-payloads.test.ts",
     "typecheck:scripts": "tsc --noEmit -p scripts/tsconfig.json",
     "test:skills": "HYPERFRAMES_MEDIA_HOME_REQUIRED=1 node --import ./packages/cli/scripts/test-home.mjs --test 'skills/**/*.test.mjs' 'packages/cli/src/media-use/**/*.test.mjs'",
     "generate:previews": "tsx scripts/generate-template-previews.ts",