--- name: baocut description: >- BaoCut-only operator for the installed `bcut` CLI and `.bcut` projects. Implicitly trigger only when the request explicitly names BaoCut or `bcut`, targets a `.bcut` project or BaoCut Subtitle Studio, or continues a BaoCut workflow already established in the conversation. Do not trigger solely for generic audio or video, transcription, subtitles, translation, editing, animation, review, rendering or export, FFmpeg, or another NLE. Once triggered, execute and verify the requested BaoCut transcription, subtitle or timeline, overlay, review, render, or export workflow. Being inside the BaoCut source repository is not itself a trigger; ordinary code and documentation tasks follow repository instructions unless they also operate the product or a `.bcut` project. metadata: version: "1.1.4" minAppVersion: "1.1.4" ---

# BaoCut

Use the bundled resolver for every command. On macOS/Linux:

```bash BAOCUT_SKILL_ROOT="<this-skill-directory>" "$BAOCUT_SKILL_ROOT/bin/baocut" --json version ```

On Windows, run the native PowerShell resolver (WSL is not required):

```powershell $env:BAOCUT_SKILL_ROOT = "<this-skill-directory>" & "$env:BAOCUT_SKILL_ROOT\bin\baocut.ps1" --json version ```

## Mandatory startup version gate

Run this gate once at the start of every BaoCut task, before `spec`, `doctor`, any project command, or reuse of an existing `bcut serve`:

1. Explicitly run the platform resolver's `--json version` command above and retain its `appVersion` and `commit`. A successful resolver handshake, a compatible `spec`, `doctor`, or `serve --status` is not an update check. 2. Immediately read and execute [references/updates.md](references/updates.md): fetch the published appcast and compare its version numerically with the local `appVersion`. Only an unavailable appcast may be reported as skipped. 3. When the appcast is newer, update the standalone skill and let its refreshed resolver download, verify, and cache the pinned CLI before continuing. Do not merely report the update or keep using the compatible old CLI. Never overwrite a development checkout or an App-bundled skill; use the supported source/App update path documented in the reference instead. 4. After any CLI update, run the refreshed resolver with `serve --background`, then `serve --status`. This idempotent start replaces an older same-root service, restores its mounts, and must report the refreshed CLI's `appVersion` and `commit`; also require HTTP 200 from its health endpoint. Discard any URL discovered before the restart.

Only after this gate may capability preflight and the requested work begin.

The resolver locates the right CLI on its own — never call `bcut` directly:

- An explicit `BAOCUT_CLI` (or `BCUT_EXECUTABLE` / `BAOCUT_BIN`) override wins. Point it only at a CLI built for this machine's architecture — see the architecture guard below. - In a BaoCut development checkout (this skill directory inside the source tree) it uses the workspace build — newest of release/debug, under `core/target/{release,debug}/bcut` or `core/target/<host-triple>/…` — or runs the sources via `cargo run` when nothing is built yet (it looks for `cargo` in `~/.cargo/bin`, Homebrew's rustup, and `~/.rustup/toolchains` when PATH lacks it). It prints a `development checkout detected` note to stderr in that case, and a separate note when it must compile from source or when it falls back to the installed App CLI because nothing is built and `cargo` is unavailable — read those notes instead of guessing why a version gate failed. A foreign-architecture build in the tree (for example `core/target/x86_64-apple-darwin/…` on Apple Silicon) is never selected. - In a released install it uses the CLI embedded in BaoCut.app, in either `/Applications` or `~/Applications`; every App release ships with its matching `baocut-cli`, so App and CLI versions always move together. - Then a `bcut` on PATH. - Then the cached CLI this skill pinned earlier, under `${XDG_CACHE_HOME:-~/.cache}/baocut/cli/<version>-build.<build>/bcut`.

On Windows, `bin/baocut.ps1` uses the same explicit overrides, development-checkout build, and PATH lookup first. It then checks cached `<version>-build.<build>` CLIs newest-first — by version *and* build, because the handshake only reports the marketing version and cannot tell two builds apart — and compatibility-checks them locally. Only when no compatible cache exists does it find the newest stable `baocut-v<version>-build.<build>` GitHub Release that includes `windows-cli-release.json`, downloads its x64 Windows archive, verifies the manifest-pinned SHA-256, and caches `bcut.exe` under `%LOCALAPPDATA%\BaoCut\cli\<version>-build.<build>\bcut.exe`. "Newest" is the highest `<version>`/`<build>` parsed from the release tags, not the first entry the API returns: Windows assets are appended to an already-published macOS release, so creation order does not track build order. The Windows archive is currently an unsigned preview, so SmartScreen, Smart App Control, or enterprise policy may warn about or block it; SHA-256 proves download integrity, not publisher identity.

A compatible cache normally ends the search, so a rebuild published under the same marketing version is not picked up on its own — nothing local announces it, since the Windows skill ships no CLI pin and `--json version` carries no build number. Set `BAOCUT_SKILL_CLI_UPDATE_CHECK=1` to let the cache path compare against the newest release and adopt a higher build; unset, that path stays entirely offline, and any failed check silently keeps the cached CLI. `BAOCUT_SKILL_NO_DOWNLOAD=1` still wins over this opt-in.

Before choosing a Windows cache or release, the resolver runs `bin/detect-windows-cli-variant.ps1`. The detector uses `nvidia-smi` and selects `cuda13` only when at least one NVIDIA GPU has compute capability 8.0+ (Ampere / RTX 30 series or newer) and the installed driver is >= 580; a missing or failed probe and an incompatible GPU select `cpu`. The CUDA choice additionally requires backend `candle-cuda`, gives the cache directory a `-cuda13` suffix, and downloads the release's `windows-cli-cuda-release.json` and `…-x86_64-pc-windows-msvc-cuda13.zip` asset, extracting the bundled CUDA runtime DLLs next to `bcut.exe`. No CUDA Toolkit install is needed. If no release ships the selected CUDA asset yet, the resolver fails clearly instead of silently using a different build. `BAOCUT_VARIANT=cpu|cuda13` remains an explicit force override for troubleshooting and controlled environments; normal installs do not need it.

The resolver then checks the CLI contract and minimum BaoCut App version before it runs the requested command, and finally checks the CLI's architecture against the host: `--json version` reports `target` (and, on current CLIs, `rosetta`), and a CLI built for another architecture — typically an x86_64 `bcut` on Apple Silicon, which macOS silently runs under Rosetta 2 with `backend: candle-cpu` — is refused for `auto` / `transcribe` (exit 3) and only warned about for other commands. Do not work around that refusal by setting `BAOCUT_ALLOW_FOREIGN_ARCH=1` (or the CLI's own `BCUT_ALLOW_ROSETTA=1`); a 100-second clip once sat 40+ minutes in VAD on such a binary while the native build finished the whole pipeline in about three. Resolve it by choosing a native CLI: BaoCut.app's bundled CLI, a native workspace build, or the pinned release CLI.

If nothing above resolves, or the resolved CLI is older than `metadata.minAppVersion`, the resolver downloads the CLI pinned by this skill's `cli-release.json` — the standalone release archive built from the same commit as the matching App. It verifies the archive's SHA-256 against the pin before extracting anything, unpacks `bcut` and its co-located `mlx.metallib` into the cache, and reruns the full contract and version handshake against the downloaded binary. Any failure exits 3 with the manual download URL. The download carries no `com.apple.quarantine` attribute and the Developer ID signature lives in the binary itself, so the cached CLI runs without a Gatekeeper prompt. The resolver exports the packaged Metal library path before executing the cached CLI, so local MLX transcription never depends on a metallib left behind on the release build machine.

Two deliberate exceptions never trigger the download: an explicit `BAOCUT_CLI`-style override and a development checkout. Both are chosen on purpose, so a failing handshake there must be fixed at the source — update the override or rebuild the workspace — rather than silently shadowed by a release binary. Set `BAOCUT_SKILL_NO_DOWNLOAD=1` to disable the download entirely; `BAOCUT_SKILL_NO_DEV=1` disables development-checkout detection.

The skill copy bundled inside BaoCut.app has no `cli-release.json`, because an App install always ships its own matching CLI beside it.

If the resolver exits 3, follow its guidance instead of bypassing the check.

## Choose the workflow

- For transcription, polish, and translation, create the project in the shared projects library first, start the preview server, then run the pipeline; read [references/workflows.md](references/workflows.md). - For a complete local pipeline, use `auto`; read [references/workflows.md](references/workflows.md). It defaults to the fast path without closing refinement; only pass `--refine` after the user chooses quality-first execution. - To run transcription on another machine on the same local network instead of this one, read the remote-node note in [references/workflows.md](references/workflows.md). - For an Agent-backed AI stage with pending calls, immediately read and follow [references/agent-tasks.md](references/agent-tasks.md). For a short clip its "short-job fast path" is the whole procedure (see "Right-size the run" below). For long media its on-demand worker rules — pool sized from the actual page plan (translate uses `ceil(source words / 880)` by default (`--align-fusion rows`), or `/2200` under `--align-fusion on|off`; align also enforces at most 40 items and a complexity budget, all capped by real slots), per-stage worker tiers (mid-tier for translate/polish, high-reasoning tier for align and repair), hand-written align answers with no scripted cutting and no unchanged resubmits — and its consolidated-repair rules (including what `refine-align --only-hard` really dispatches) are execution requirements, not optional tuning. - For the Subtitle Studio browser preview — serving and mounting projects, applying page edits, page requests, history recovery, punctuation display, or preview troubleshooting — read [references/studio.md](references/studio.md). The page code itself is this skill's `templates/` directory, served live by `serve`. - For source cuts, OUTPUT clip arrangement, appended media, or rough cutting, read [references/editing.md](references/editing.md). - For overlays, B-roll, watermarks, text styles, or debug frames, read [references/elements.md](references/elements.md). - For overlay motion, read [references/animation.md](references/animation.md). - For reusable foreground templates — caption slot, segment rail, progress bar, station logo — and the `data.json` data layer that binds them, read [references/templates.md](references/templates.md). - For text baked into video frames, read [references/screentext.md](references/screentext.md). - For delivery, run `check --strict` and then use the export recipes in [references/exports.md](references/exports.md). - For granular project edits, discover the installed surface with `spec` and command `--help`; do not infer commands from older BaoCut releases. - For deterministic Transcript lookup, replacement, or lexical name fixes, use the CLI before opening Subtitle Studio: run `transcript find`, then `transcript replace --expect <count>`. Use `--scope all`

--- name: baocut description: >- BaoCut-only operator for the installed `bcut` CLI and `.bcut` projects. Implicitly trigger only when the request explicitly names BaoCut or `bcut`, targets a `.bcut` project or BaoCut Subtitle Studio, or continues a BaoCut workflow already established in the conversation. Do not trigger solely for generic audio or video, transcription, subtitles, translation, editing, animation, review, rendering or export, FFmpeg, or another NLE. Once triggered, execute and verify the requested BaoCut transcription, subtitle or timeline, overlay, review, render, or export workflow. Being inside the BaoCut source repository is not itself a trigger; ordinary code and documentation tasks follow repository instructions unless they also operate the product or a `.bcut` project. metadata: version: "1.1.4" minAppVersion: "1.1.4" ---

# BaoCut

Use the bundled resolver for every command. On macOS/Linux:

```bash BAOCUT_SKILL_ROOT="<this-skill-directory>" "$BAOCUT_SKILL_ROOT/bin/baocut" --json version ```

On Windows, run the native PowerShell resolver (WSL is not required):

```powershell $env:BAOCUT_SKILL_ROOT = "<this-skill-directory>" & "$env:BAOCUT_SKILL_ROOT\bin\baocut.ps1" --json version ```

## Mandatory startup version gate

Run this gate once at the start of every BaoCut task, before `spec`, `doctor`, any project command, or reuse of an existing `bcut serve`:

1. Explicitly run the platform resolver's `--json version` command above and retain its `appVersion` and `commit`. A successful resolver handshake, a compatible `spec`, `doctor`, or `serve --status` is not an update check. 2. Immediately read and execute [references/updates.md](references/updates.md): fetch the published appcast and compare its version numerically with the local `appVersion`. Only an unavailable appcast may be reported as skipped. 3. When the appcast is newer, update the standalone skill and let its refreshed resolver download, verify, and cache the pinned CLI before continuing. Do not merely report the update or keep using the compatible old CLI. Never overwrite a development checkout or an App-bundled skill; use the supported source/App update path documented in the reference instead. 4. After any CLI update, run the refreshed resolver with `serve --background`, then `serve --status`. This idempotent start replaces an older same-root service, restores its mounts, and must report the refreshed CLI's `appVersion` and `commit`; also require HTTP 200 from its health endpoint. Discard any URL discovered before the restart.

Only after this gate may capability preflight and the requested work begin.

The resolver locates the right CLI on its own — never call `bcut` directly:

- An explicit `BAOCUT_CLI` (or `BCUT_EXECUTABLE` / `BAOCUT_BIN`) override wins. Point it only at a CLI built for this machine's architecture — see the architecture guard below. - In a BaoCut development checkout (this skill directory inside the source tree) it uses the workspace build — newest of release/debug, under `core/target/{release,debug}/bcut` or `core/target/<host-triple>/…` — or runs the sources via `cargo run` when nothing is built yet (it looks for `cargo` in `~/.cargo/bin`, Homebrew's rustup, and `~/.rustup/toolchains` when PATH lacks it). It prints a `development checkout detected` note to stderr in that case, and a separate note when it must compile from source or when it falls back to the installed App CLI because nothing is built and `cargo` is unavailable — read those notes instead of guessing why a version gate failed. A foreign-architecture build in the tree (for example `core/target/x86_64-apple-darwin/…` on Apple Silicon) is never selected. - In a released install it uses the CLI embedded in BaoCut.app, in either `/Applications` or `~/Applications`; every App release ships with its matching `baocut-cli`, so App and CLI versions always move together. - Then a `bcut` on PATH. - Then the cached CLI this skill pinned earlier, under `${XDG_CACHE_HOME:-~/.cache}/baocut/cli/<version>-build.<build>/bcut`.

On Windows, `bin/baocut.ps1` uses the same explicit overrides, development-checkout build, and PATH lookup first. It then checks cached `<version>-build.<build>` CLIs newest-first — by version *and* build, because the handshake only reports the marketing version and cannot tell two builds apart — and compatibility-checks them locally. Only when no compatible cache exists does it find the newest stable `baocut-v<version>-build.<build>` GitHub Release that includes `windows-cli-release.json`, downloads its x64 Windows archive, verifies the manifest-pinned SHA-256, and caches `bcut.exe` under `%LOCALAPPDATA%\BaoCut\cli\<version>-build.<build>\bcut.exe`. "Newest" is the highest `<version>`/`<build>` parsed from the release tags, not the first entry the API returns: Windows assets are appended to an already-published macOS release, so creation order does not track build order. The Windows archive is currently an unsigned preview, so SmartScreen, Smart App Control, or enterprise policy may warn about or block it; SHA-256 proves download integrity, not publisher identity.

A compatible cache normally ends the search, so a rebuild published under the same marketing version is not picked up on its own — nothing local announces it, since the Windows skill ships no CLI pin and `--json version` carries no build number. Set `BAOCUT_SKILL_CLI_UPDATE_CHECK=1` to let the cache path compare against the newest release and adopt a higher build; unset, that path stays entirely offline, and any failed check silently keeps the cached CLI. `BAOCUT_SKILL_NO_DOWNLOAD=1` still wins over this opt-in.

Before choosing a Windows cache or release, the resolver runs `bin/detect-windows-cli-variant.ps1`. The detector uses `nvidia-smi` and selects `cuda13` only when at least one NVIDIA GPU has compute capability 8.0+ (Ampere / RTX 30 series or newer) and the installed driver is >= 580; a missing or failed probe and an incompatible GPU select `cpu`. The CUDA choice additionally requires backend `candle-cuda`, gives the cache directory a `-cuda13` suffix, and downloads the release's `windows-cli-cuda-release.json` and `…-x86_64-pc-windows-msvc-cuda13.zip` asset, extracting the bundled CUDA runtime DLLs next to `bcut.exe`. No CUDA Toolkit install is needed. If no release ships the selected CUDA asset yet, the resolver fails clearly instead of silently using a different build. `BAOCUT_VARIANT=cpu|cuda13` remains an explicit force override for troubleshooting and controlled environments; normal installs do not need it.

The resolver then checks the CLI contract and minimum BaoCut App version before it runs the requested command, and finally checks the CLI's architecture against the host: `--json version` reports `target` (and, on current CLIs, `rosetta`), and a CLI built for another architecture — typically an x86_64 `bcut` on Apple Silicon, which macOS silently runs under Rosetta 2 with `backend: candle-cpu` — is refused for `auto` / `transcribe` (exit 3) and only warned about for other commands. Do not work around that refusal by setting `BAOCUT_ALLOW_FOREIGN_ARCH=1` (or the CLI's own `BCUT_ALLOW_ROSETTA=1`); a 100-second clip once sat 40+ minutes in VAD on such a binary while the native build finished the whole pipeline in about three. Resolve it by choosing a native CLI: BaoCut.app's bundled CLI, a native workspace build, or the pinned release CLI.

If nothing above resolves, or the resolved CLI is older than `metadata.minAppVersion`, the resolver downloads the CLI pinned by this skill's `cli-release.json` — the standalone release archive built from the same commit as the matching App. It verifies the archive's SHA-256 against the pin before extracting anything, unpacks `bcut` and its co-located `mlx.metallib` into the cache, and reruns the full contract and version handshake against the downloaded binary. Any failure exits 3 with the manual download URL. The download carries no `com.apple.quarantine` attribute and the Developer ID signature lives in the binary itself, so the cached CLI runs without a Gatekeeper prompt. The resolver exports the packaged Metal library path before executing the cached CLI, so local MLX transcription never depends on a metallib left behind on the release build machine.

Two deliberate exceptions never trigger the download: an explicit `BAOCUT_CLI`-style override and a development checkout. Both are chosen on purpose, so a failing handshake there must be fixed at the source — update the override or rebuild the workspace — rather than silently shadowed by a release binary. Set `BAOCUT_SKILL_NO_DOWNLOAD=1` to disable the download entirely; `BAOCUT_SKILL_NO_DEV=1` disables development-checkout detection.

The skill copy bundled inside BaoCut.app has no `cli-release.json`, because an App install always ships its own matching CLI beside it.

If the resolver exits 3, follow its guidance instead of bypassing the check.

## Choose the workflow

- For transcription, polish, and translation, create the project in the shared projects library first, start the preview server, then run the pipeline; read [references/workflows.md](references/workflows.md). - For a complete local pipeline, use `auto`; read [references/workflows.md](references/workflows.md). It defaults to the fast path without closing refinement; only pass `--refine` after the user chooses quality-first execution. - To run transcription on another machine on the same local network instead of this one, read the remote-node note in [references/workflows.md](references/workflows.md). - For an Agent-backed AI stage with pending calls, immediately read and follow [references/agent-tasks.md](references/agent-tasks.md). For a short clip its "short-job fast path" is the whole procedure (see "Right-size the run" below). For long media its on-demand worker rules — pool sized from the actual page plan (translate uses `ceil(source words / 880)` by default (`--align-fusion rows`), or `/2200` under `--align-fusion on|off`; align also enforces at most 40 items and a complexity budget, all capped by real slots), per-stage worker tiers (mid-tier for translate/polish, high-reasoning tier for align and repair), hand-written align answers with no scripted cutting and no unchanged resubmits — and its consolidated-repair rules (including what `refine-align --only-hard` really dispatches) are execution requirements, not optional tuning. - For the Subtitle Studio browser preview — serving and mounting projects, applying page edits, page requests, history recovery, punctuation display, or preview troubleshooting — read [references/studio.md](references/studio.md). The page code itself is this skill's `templates/` directory, served live by `serve`. - For source cuts, OUTPUT clip arrangement, appended media, or rough cutting, read [references/editing.md](references/editing.md). - For overlays, B-roll, watermarks, text styles, or debug frames, read [references/elements.md](references/elements.md). - For overlay motion, read [references/animation.md](references/animation.md). - For reusable foreground templates — caption slot, segment rail, progress bar, station logo — and the `data.json` data layer that binds them, read [references/templates.md](references/templates.md). - For text baked into video frames, read [references/screentext.md](references/screentext.md). - For delivery, run `check --strict` and then use the export recipes in [references/exports.md](references/exports.md). - For granular project edits, discover the installed surface with `spec` and command `--help`; do not infer commands from older BaoCut releases. - For deterministic Transcript lookup, replacement, or lexical name fixes, use the CLI before opening Subtitle Studio: run `transcript find`, then `transcript replace --expect <count>`. Use `--scope all`

--- name: baocut description: >- BaoCut-only operator for the installed `bcut` CLI and `.bcut` projects. Implicitly trigger only when the request explicitly names BaoCut or `bcut`, targets a `.bcut` project or BaoCut Subtitle Studio, or continues a BaoCut workflow already established in the conversation. Do not trigger solely for generic audio or video, transcription, subtitles, translation, editing, animation, review, rendering or export, FFmpeg, or another NLE. Once triggered, execute and verify the requested BaoCut transcription, subtitle or timeline, overlay, review, render, or export workflow. Being inside the BaoCut source repository is not itself a trigger; ordinary code and documentation tasks follow repository instructions unless they also operate the product or a `.bcut` project. metadata: version: "1.1.4" minAppVersion: "1.1.4" ---

# BaoCut

Use the bundled resolver for every command. On macOS/Linux:

```bash BAOCUT_SKILL_ROOT="<this-skill-directory>" "$BAOCUT_SKILL_ROOT/bin/baocut" --json version ```

On Windows, run the native PowerShell resolver (WSL is not required):

```powershell $env:BAOCUT_SKILL_ROOT = "<this-skill-directory>" & "$env:BAOCUT_SKILL_ROOT\bin\baocut.ps1" --json version ```

## Mandatory startup version gate

Run this gate once at the start of every BaoCut task, before `spec`, `doctor`, any project command, or reuse of an existing `bcut serve`:

1. Explicitly run the platform resolver's `--json version` command above and retain its `appVersion` and `commit`. A successful resolver handshake, a compatible `spec`, `doctor`, or `serve --status` is not an update check. 2. Immediately read and execute [references/updates.md](references/updates.md): fetch the published appcast and compare its version numerically with the local `appVersion`. Only an unavailable appcast may be reported as skipped. 3. When the appcast is newer, update the standalone skill and let its refreshed resolver download, verify, and cache the pinned CLI before continuing. Do not merely report the update or keep using the compatible old CLI. Never overwrite a development checkout or an App-bundled skill; use the supported source/App update path documented in the reference instead. 4. After any CLI update, run the refreshed resolver with `serve --background`, then `serve --status`. This idempotent start replaces an older same-root service, restores its mounts, and must report the refreshed CLI's `appVersion` and `commit`; also require HTTP 200 from its health endpoint. Discard any URL discovered before the restart.

Only after this gate may capability preflight and the requested work begin.

The resolver locates the right CLI on its own — never call `bcut` directly:

- An explicit `BAOCUT_CLI` (or `BCUT_EXECUTABLE` / `BAOCUT_BIN`) override wins. Point it only at a CLI built for this machine's architecture — see the architecture guard below. - In a BaoCut development checkout (this skill directory inside the source tree) it uses the workspace build — newest of release/debug, under `core/target/{release,debug}/bcut` or `core/target/<host-triple>/…` — or runs the sources via `cargo run` when nothing is built yet (it looks for `cargo` in `~/.cargo/bin`, Homebrew's rustup, and `~/.rustup/toolchains` when PATH lacks it). It prints a `development checkout detected` note to stderr in that case, and a separate note when it must compile from source or when it falls back to the installed App CLI because nothing is built and `cargo` is unavailable — read those notes instead of guessing why a version gate failed. A foreign-architecture build in the tree (for example `core/target/x86_64-apple-darwin/…` on Apple Silicon) is never selected. - In a released install it uses the CLI embedded in BaoCut.app, in either `/Applications` or `~/Applications`; every App release ships with its matching `baocut-cli`, so App and CLI versions always move together. - Then a `bcut` on PATH. - Then the cached CLI this skill pinned earlier, under `${XDG_CACHE_HOME:-~/.cache}/baocut/cli/<version>-build.<build>/bcut`.

On Windows, `bin/baocut.ps1` uses the same explicit overrides, development-checkout build, and PATH lookup first. It then checks cached `<version>-build.<build>` CLIs newest-first — by version *and* build, because the handshake only reports the marketing version and cannot tell two builds apart — and compatibility-checks them locally. Only when no compatible cache exists does it find the newest stable `baocut-v<version>-build.<build>` GitHub Release that includes `windows-cli-release.json`, downloads its x64 Windows archive, verifies the manifest-pinned SHA-256, and caches `bcut.exe` under `%LOCALAPPDATA%\BaoCut\cli\<version>-build.<build>\bcut.exe`. "Newest" is the highest `<version>`/`<build>` parsed from the release tags, not the first entry the API returns: Windows assets are appended to an already-published macOS release, so creation order does not track build order. The Windows archive is currently an unsigned preview, so SmartScreen, Smart App Control, or enterprise policy may warn about or block it; SHA-256 proves download integrity, not publisher identity.

A compatible cache normally ends the search, so a rebuild published under the same marketing version is not picked up on its own — nothing local announces it, since the Windows skill ships no CLI pin and `--json version` carries no build number. Set `BAOCUT_SKILL_CLI_UPDATE_CHECK=1` to let the cache path compare against the newest release and adopt a higher build; unset, that path stays entirely offline, and any failed check silently keeps the cached CLI. `BAOCUT_SKILL_NO_DOWNLOAD=1` still wins over this opt-in.

Before choosing a Windows cache or release, the resolver runs `bin/detect-windows-cli-variant.ps1`. The detector uses `nvidia-smi` and selects `cuda13` only when at least one NVIDIA GPU has compute capability 8.0+ (Ampere / RTX 30 series or newer) and the installed driver is >= 580; a missing or failed probe and an incompatible GPU select `cpu`. The CUDA choice additionally requires backend `candle-cuda`, gives the cache directory a `-cuda13` suffix, and downloads the release's `windows-cli-cuda-release.json` and `…-x86_64-pc-windows-msvc-cuda13.zip` asset, extracting the bundled CUDA runtime DLLs next to `bcut.exe`. No CUDA Toolkit install is needed. If no release ships the selected CUDA asset yet, the resolver fails clearly instead of silently using a different build. `BAOCUT_VARIANT=cpu|cuda13` remains an explicit force override for troubleshooting and controlled environments; normal installs do not need it.

The resolver then checks the CLI contract and minimum BaoCut App version before it runs the requested command, and finally checks the CLI's architecture against the host: `--json version` reports `target` (and, on current CLIs, `rosetta`), and a CLI built for another architecture — typically an x86_64 `bcut` on Apple Silicon, which macOS silently runs under Rosetta 2 with `backend: candle-cpu` — is refused for `auto` / `transcribe` (exit 3) and only warned about for other commands. Do not work around that refusal by setting `BAOCUT_ALLOW_FOREIGN_ARCH=1` (or the CLI's own `BCUT_ALLOW_ROSETTA=1`); a 100-second clip once sat 40+ minutes in VAD on such a binary while the native build finished the whole pipeline in about three. Resolve it by choosing a native CLI: BaoCut.app's bundled CLI, a native workspace build, or the pinned release CLI.

If nothing above resolves, or the resolved CLI is older than `metadata.minAppVersion`, the resolver downloads the CLI pinned by this skill's `cli-release.json` — the standalone release archive built from the same commit as the matching App. It verifies the archive's SHA-256 against the pin before extracting anything, unpacks `bcut` and its co-located `mlx.metallib` into the cache, and reruns the full contract and version handshake against the downloaded binary. Any failure exits 3 with the manual download URL. The download carries no `com.apple.quarantine` attribute and the Developer ID signature lives in the binary itself, so the cached CLI runs without a Gatekeeper prompt. The resolver exports the packaged Metal library path before executing the cached CLI, so local MLX transcription never depends on a metallib left behind on the release build machine.

Two deliberate exceptions never trigger the download: an explicit `BAOCUT_CLI`-style override and a development checkout. Both are chosen on purpose, so a failing handshake there must be fixed at the source — update the override or rebuild the workspace — rather than silently shadowed by a release binary. Set `BAOCUT_SKILL_NO_DOWNLOAD=1` to disable the download entirely; `BAOCUT_SKILL_NO_DEV=1` disables development-checkout detection.

The skill copy bundled inside BaoCut.app has no `cli-release.json`, because an App install always ships its own matching CLI beside it.

If the resolver exits 3, follow its guidance instead of bypassing the check.

## Choose the workflow

- For transcription, polish, and translation, create the project in the shared projects library first, start the preview server, then run the pipeline; read [references/workflows.md](references/workflows.md). - For a complete local pipeline, use `auto`; read [references/workflows.md](references/workflows.md). It defaults to the fast path without closing refinement; only pass `--refine` after the user chooses quality-first execution. - To run transcription on another machine on the same local network instead of this one, read the remote-node note in [references/workflows.md](references/workflows.md). - For an Agent-backed AI stage with pending calls, immediately read and follow [references/agent-tasks.md](references/agent-tasks.md). For a short clip its "short-job fast path" is the whole procedure (see "Right-size the run" below). For long media its on-demand worker rules — pool sized from the actual page plan (translate uses `ceil(source words / 880)` by default (`--align-fusion rows`), or `/2200` under `--align-fusion on|off`; align also enforces at most 40 items and a complexity budget, all capped by real slots), per-stage worker tiers (mid-tier for translate/polish, high-reasoning tier for align and repair), hand-written align answers with no scripted cutting and no unchanged resubmits — and its consolidated-repair rules (including what `refine-align --only-hard` really dispatches) are execution requirements, not optional tuning. - For the Subtitle Studio browser preview — serving and mounting projects, applying page edits, page requests, history recovery, punctuation display, or preview troubleshooting — read [references/studio.md](references/studio.md). The page code itself is this skill's `templates/` directory, served live by `serve`. - For source cuts, OUTPUT clip arrangement, appended media, or rough cutting, read [references/editing.md](references/editing.md). - For overlays, B-roll, watermarks, text styles, or debug frames, read [references/elements.md](references/elements.md). - For overlay motion, read [references/animation.md](references/animation.md). - For reusable foreground templates — caption slot, segment rail, progress bar, station logo — and the `data.json` data layer that binds them, read [references/templates.md](references/templates.md). - For text baked into video frames, read [references/screentext.md](references/screentext.md). - For delivery, run `check --strict` and then use the export recipes in [references/exports.md](references/exports.md). - For granular project edits, discover the installed surface with `spec` and command `--help`; do not infer commands from older BaoCut releases. - For deterministic Transcript lookup, replacement, or lexical name fixes, use the CLI before opening Subtitle Studio: run `transcript find`, then `transcript replace --expect <count>`. Use `--scope all`

--- name: baocut description: >- BaoCut-only operator for the installed `bcut` CLI and `.bcut` projects. Implicitly trigger only when the request explicitly names BaoCut or `bcut`, targets a `.bcut` project or BaoCut Subtitle Studio, or continues a BaoCut workflow already established in the conversation. Do not trigger solely for generic audio or video, transcription, subtitles, translation, editing, animation, review, rendering or export, FFmpeg, or another NLE. Once triggered, execute and verify the requested BaoCut transcription, subtitle or timeline, overlay, review, render, or export workflow. Being inside the BaoCut source repository is not itself a trigger; ordinary code and documentation tasks follow repository instructions unless they also operate the product or a `.bcut` project. metadata: version: "1.1.4" minAppVersion: "1.1.4" ---

# BaoCut

Use the bundled resolver for every command. On macOS/Linux:

```bash BAOCUT_SKILL_ROOT="<this-skill-directory>" "$BAOCUT_SKILL_ROOT/bin/baocut" --json version ```

On Windows, run the native PowerShell resolver (WSL is not required):

```powershell $env:BAOCUT_SKILL_ROOT = "<this-skill-directory>" & "$env:BAOCUT_SKILL_ROOT\bin\baocut.ps1" --json version ```

## Mandatory startup version gate

Run this gate once at the start of every BaoCut task, before `spec`, `doctor`, any project command, or reuse of an existing `bcut serve`:

1. Explicitly run the platform resolver's `--json version` command above and retain its `appVersion` and `commit`. A successful resolver handshake, a compatible `spec`, `doctor`, or `serve --status` is not an update check. 2. Immediately read and execute [references/updates.md](references/updates.md): fetch the published appcast and compare its version numerically with the local `appVersion`. Only an unavailable appcast may be reported as skipped. 3. When the appcast is newer, update the standalone skill and let its refreshed resolver download, verify, and cache the pinned CLI before continuing. Do not merely report the update or keep using the compatible old CLI. Never overwrite a development checkout or an App-bundled skill; use the supported source/App update path documented in the reference instead. 4. After any CLI update, run the refreshed resolver with `serve --background`, then `serve --status`. This idempotent start replaces an older same-root service, restores its mounts, and must report the refreshed CLI's `appVersion` and `commit`; also require HTTP 200 from its health endpoint. Discard any URL discovered before the restart.

Only after this gate may capability preflight and the requested work begin.

The resolver locates the right CLI on its own — never call `bcut` directly:

- An explicit `BAOCUT_CLI` (or `BCUT_EXECUTABLE` / `BAOCUT_BIN`) override wins. Point it only at a CLI built for this machine's architecture — see the architecture guard below. - In a BaoCut development checkout (this skill directory inside the source tree) it uses the workspace build — newest of release/debug, under `core/target/{release,debug}/bcut` or `core/target/<host-triple>/…` — or runs the sources via `cargo run` when nothing is built yet (it looks for `cargo` in `~/.cargo/bin`, Homebrew's rustup, and `~/.rustup/toolchains` when PATH lacks it). It prints a `development checkout detected` note to stderr in that case, and a separate note when it must compile from source or when it falls back to the installed App CLI because nothing is built and `cargo` is unavailable — read those notes instead of guessing why a version gate failed. A foreign-architecture build in the tree (for example `core/target/x86_64-apple-darwin/…` on Apple Silicon) is never selected. - In a released install it uses the CLI embedded in BaoCut.app, in either `/Applications` or `~/Applications`; every App release ships with its matching `baocut-cli`, so App and CLI versions always move together. - Then a `bcut` on PATH. - Then the cached CLI this skill pinned earlier, under `${XDG_CACHE_HOME:-~/.cache}/baocut/cli/<version>-build.<build>/bcut`.

On Windows, `bin/baocut.ps1` uses the same explicit overrides, development-checkout build, and PATH lookup first. It then checks cached `<version>-build.<build>` CLIs newest-first — by version *and* build, because the handshake only reports the marketing version and cannot tell two builds apart — and compatibility-checks them locally. Only when no compatible cache exists does it find the newest stable `baocut-v<version>-build.<build>` GitHub Release that includes `windows-cli-release.json`, downloads its x64 Windows archive, verifies the manifest-pinned SHA-256, and caches `bcut.exe` under `%LOCALAPPDATA%\BaoCut\cli\<version>-build.<build>\bcut.exe`. "Newest" is the highest `<version>`/`<build>` parsed from the release tags, not the first entry the API returns: Windows assets are appended to an already-published macOS release, so creation order does not track build order. The Windows archive is currently an unsigned preview, so SmartScreen, Smart App Control, or enterprise policy may warn about or block it; SHA-256 proves download integrity, not publisher identity.

A compatible cache normally ends the search, so a rebuild published under the same marketing version is not picked up on its own — nothing local announces it, since the Windows skill ships no CLI pin and `--json version` carries no build number. Set `BAOCUT_SKILL_CLI_UPDATE_CHECK=1` to let the cache path compare against the newest release and adopt a higher build; unset, that path stays entirely offline, and any failed check silently keeps the cached CLI. `BAOCUT_SKILL_NO_DOWNLOAD=1` still wins over this opt-in.

Before choosing a Windows cache or release, the resolver runs `bin/detect-windows-cli-variant.ps1`. The detector uses `nvidia-smi` and selects `cuda13` only when at least one NVIDIA GPU has compute capability 8.0+ (Ampere / RTX 30 series or newer) and the installed driver is >= 580; a missing or failed probe and an incompatible GPU select `cpu`. The CUDA choice additionally requires backend `candle-cuda`, gives the cache directory a `-cuda13` suffix, and downloads the release's `windows-cli-cuda-release.json` and `…-x86_64-pc-windows-msvc-cuda13.zip` asset, extracting the bundled CUDA runtime DLLs next to `bcut.exe`. No CUDA Toolkit install is needed. If no release ships the selected CUDA asset yet, the resolver fails clearly instead of silently using a different build. `BAOCUT_VARIANT=cpu|cuda13` remains an explicit force override for troubleshooting and controlled environments; normal installs do not need it.

The resolver then checks the CLI contract and minimum BaoCut App version before it runs the requested command, and finally checks the CLI's architecture against the host: `--json version` reports `target` (and, on current CLIs, `rosetta`), and a CLI built for another architecture — typically an x86_64 `bcut` on Apple Silicon, which macOS silently runs under Rosetta 2 with `backend: candle-cpu` — is refused for `auto` / `transcribe` (exit 3) and only warned about for other commands. Do not work around that refusal by setting `BAOCUT_ALLOW_FOREIGN_ARCH=1` (or the CLI's own `BCUT_ALLOW_ROSETTA=1`); a 100-second clip once sat 40+ minutes in VAD on such a binary while the native build finished the whole pipeline in about three. Resolve it by choosing a native CLI: BaoCut.app's bundled CLI, a native workspace build, or the pinned release CLI.

If nothing above resolves, or the resolved CLI is older than `metadata.minAppVersion`, the resolver downloads the CLI pinned by this skill's `cli-release.json` — the standalone release archive built from the same commit as the matching App. It verifies the archive's SHA-256 against the pin before extracting anything, unpacks `bcut` and its co-located `mlx.metallib` into the cache, and reruns the full contract and version handshake against the downloaded binary. Any failure exits 3 with the manual download URL. The download carries no `com.apple.quarantine` attribute and the Developer ID signature lives in the binary itself, so the cached CLI runs without a Gatekeeper prompt. The resolver exports the packaged Metal library path before executing the cached CLI, so local MLX transcription never depends on a metallib left behind on the release build machine.

Two deliberate exceptions never trigger the download: an explicit `BAOCUT_CLI`-style override and a development checkout. Both are chosen on purpose, so a failing handshake there must be fixed at the source — update the override or rebuild the workspace — rather than silently shadowed by a release binary. Set `BAOCUT_SKILL_NO_DOWNLOAD=1` to disable the download entirely; `BAOCUT_SKILL_NO_DEV=1` disables development-checkout detection.

The skill copy bundled inside BaoCut.app has no `cli-release.json`, because an App install always ships its own matching CLI beside it.

If the resolver exits 3, follow its guidance instead of bypassing the check.

## Choose the workflow

- For transcription, polish, and translation, create the project in the shared projects library first, start the preview server, then run the pipeline; read [references/workflows.md](references/workflows.md). - For a complete local pipeline, use `auto`; read [references/workflows.md](references/workflows.md). It defaults to the fast path without closing refinement; only pass `--refine` after the user chooses quality-first execution. - To run transcription on another machine on the same local network instead of this one, read the remote-node note in [references/workflows.md](references/workflows.md). - For an Agent-backed AI stage with pending calls, immediately read and follow [references/agent-tasks.md](references/agent-tasks.md). For a short clip its "short-job fast path" is the whole procedure (see "Right-size the run" below). For long media its on-demand worker rules — pool sized from the actual page plan (translate uses `ceil(source words / 880)` by default (`--align-fusion rows`), or `/2200` under `--align-fusion on|off`; align also enforces at most 40 items and a complexity budget, all capped by real slots), per-stage worker tiers (mid-tier for translate/polish, high-reasoning tier for align and repair), hand-written align answers with no scripted cutting and no unchanged resubmits — and its consolidated-repair rules (including what `refine-align --only-hard` really dispatches) are execution requirements, not optional tuning. - For the Subtitle Studio browser preview — serving and mounting projects, applying page edits, page requests, history recovery, punctuation display, or preview troubleshooting — read [references/studio.md](references/studio.md). The page code itself is this skill's `templates/` directory, served live by `serve`. - For source cuts, OUTPUT clip arrangement, appended media, or rough cutting, read [references/editing.md](references/editing.md). - For overlays, B-roll, watermarks, text styles, or debug frames, read [references/elements.md](references/elements.md). - For overlay motion, read [references/animation.md](references/animation.md). - For reusable foreground templates — caption slot, segment rail, progress bar, station logo — and the `data.json` data layer that binds them, read [references/templates.md](references/templates.md). - For text baked into video frames, read [references/screentext.md](references/screentext.md). - For delivery, run `check --strict` and then use the export recipes in [references/exports.md](references/exports.md). - For granular project edits, discover the installed surface with `spec` and command `--help`; do not infer commands from older BaoCut releases. - For deterministic Transcript lookup, replacement, or lexical name fixes, use the CLI before opening Subtitle Studio: run `transcript find`, then `transcript replace --expect <count>`. Use `--scope all`