@gitruck/cli 1.3.3 → 1.3.5

package/docs/development.en.md

@@ -1,47 +1,47 @@
-# Development and contributions
-
-[Back to README](../README.en.md) · [Command reference](reference.en.md) · [简体中文](development.md)
-
-## Local development
-
-The CLI runtime requires Node.js ≥ 20.6. Source development and builds use Bun.
-
-```bash
-git clone https://github.com/Gitruck/cli.git
-cd cli
-bun install
-bun run src/index.ts --help
-npm run typecheck
-bun run build
-```
-
-The public repository supports reading, developing and building the CLI. `test/` and `openspec/` are private submodules requiring maintainer access. Public contributors do not need a recursive clone; authorized maintainers run the complete test suite.
-
-## Repository layout
-
-```text
-src/index.ts       Command entry point
-src/commands/      CLI commands
-src/lib/           Cloud calls, media processing, project assembly and rendering
-skills/            Bundled Agent Skills
-contracts/         Open project and motion graphics contracts
-docs/              Workflow, configuration, command and development references
-assets/            README artwork
-AGENT.md           Portable agent playbook
-```
-
-Add commands through registration functions in `src/commands/` and wire them into `src/index.ts`. Toolbox additions should reuse existing descriptors and runners where applicable. `src/commands/skills.ts` owns the bundled Skill list; see the [reference](reference.en.md) for details.
-
-## Documentation and checks
-
-- README presents the product and onboarding. Maintain parameters, configuration and full explanations in `docs/reference.md` / `docs/reference.en.md`.
-- Update both READMEs and corresponding bilingual documents together. Preserve command names, flags, fields and artifact filenames; keep example commands identical.
-- Use publicly accessible images or files in `assets/`. Keep examples traceable and large videos out of the npm package.
-- Maintainers run `npm test`, which builds and uses Node's test runner. Do not substitute `bun test`. Documentation-only changes should at least run the relevant guards and check links and rendering.
-- Check `npm pack --dry-run` when moving bundled documentation so it remains in the package.
-
-## Contributing
-
-Use [Issues](https://github.com/Gitruck/cli/issues) to describe problems, use cases or behavior you would like improved. Explain changes and validation in your PR. Do not include API keys, personal configuration, media paths, generated outputs or private submodule contents.
-
-See [contracts](../contracts/README.md) for interfaces and [AGENT.md](../AGENT.md) for agent usage.
+# Development and contributions
+
+[Back to README](../README.en.md) · [Command reference](reference.en.md) · [简体中文](development.md)
+
+## Local development
+
+The CLI runtime requires Node.js ≥ 20.6. Source development and builds use Bun.
+
+```bash
+git clone https://github.com/Gitruck/cli.git
+cd cli
+bun install
+bun run src/index.ts --help
+npm run typecheck
+bun run build
+```
+
+The public repository supports reading, developing and building the CLI. `test/` and `openspec/` are private submodules requiring maintainer access. Public contributors do not need a recursive clone; authorized maintainers run the complete test suite.
+
+## Repository layout
+
+```text
+src/index.ts       Command entry point
+src/commands/      CLI commands
+src/lib/           Cloud calls, media processing, project assembly and rendering
+skills/            Bundled Agent Skills
+contracts/         Open project and motion graphics contracts
+docs/              Workflow, configuration, command and development references
+assets/            README artwork
+AGENT.md           Portable agent playbook
+```
+
+Add commands through registration functions in `src/commands/` and wire them into `src/index.ts`. Toolbox additions should reuse existing descriptors and runners where applicable. `src/commands/skills.ts` owns the bundled Skill list; see the [reference](reference.en.md) for details.
+
+## Documentation and checks
+
+- README presents the product and onboarding. Maintain parameters, configuration and full explanations in `docs/reference.md` / `docs/reference.en.md`.
+- Update both READMEs and corresponding bilingual documents together. Preserve command names, flags, fields and artifact filenames; keep example commands identical.
+- Use publicly accessible images or files in `assets/`. Keep examples traceable and large videos out of the npm package.
+- Maintainers run `npm test`, which builds and uses Node's test runner. Do not substitute `bun test`. Documentation-only changes should at least run the relevant guards and check links and rendering.
+- Check `npm pack --dry-run` when moving bundled documentation so it remains in the package.
+
+## Contributing
+
+Use [Issues](https://github.com/Gitruck/cli/issues) to describe problems, use cases or behavior you would like improved. Explain changes and validation in your PR. Do not include API keys, personal configuration, media paths, generated outputs or private submodule contents.
+
+See [contracts](../contracts/README.md) for interfaces and [AGENT.md](../AGENT.md) for agent usage.

package/docs/development.md

@@ -1,47 +1,47 @@
-# 开发与贡献
-
-[返回首页](../README.md) · [命令参考](reference.md) · [English](development.en.md)
-
-## 本地开发
-
-CLI 运行时需要 Node.js ≥ 20.6；源码开发与构建使用 Bun。
-
-```bash
-git clone https://github.com/Gitruck/cli.git
-cd cli
-bun install
-bun run src/index.ts --help
-npm run typecheck
-bun run build
-```
-
-公共仓库可用于阅读、开发和构建 CLI。`test/` 与 `openspec/` 是需要维护者权限的私有子模块，公开贡献者无需递归拉取它们；完整测试由有权限的维护者运行。
-
-## 项目结构
-
-```text
-src/index.ts       命令入口
-src/commands/      CLI 命令
-src/lib/           云端调用、素材处理、工程装配与渲染
-skills/            随包 Agent Skills
-contracts/         工程与动态图等开放契约
-docs/              工作流、配置、命令和开发参考
-assets/            README 配图
-AGENT.md           可移植 Agent 操作手册
-```
-
-新增命令在 `src/commands/` 中提供注册函数，并在 `src/index.ts` 接入；工具族优先复用已有描述器与执行器。随包 Skills 的权威清单在 `src/commands/skills.ts`，详细名单见[参考文档](reference.md)。
-
-## 文档与校验
-
-- README 负责产品展示和上手；参数、配置与完整操作解释维护在 `docs/reference.md` / `docs/reference.en.md`。
-- 两份 README 和对应双语文档同步更新。命令名、参数、字段与产物文件名保持原样；示例命令保持一致。
-- 配图使用公开可访问资源，或放入 `assets/`；案例保持可追溯，不将大视频打包进 npm。
-- 维护者运行 `npm test`（构建后通过 Node 测试），不要用 `bun test` 代替。纯文档变更至少运行相关文档守卫、检查链接和展示效果。
-- 修改公开随包文档时，检查 `npm pack --dry-run` 的文件清单，避免移动后漏包。
-
-## 提交贡献
-
-通过 [Issues](https://github.com/Gitruck/cli/issues)描述问题、使用场景或希望改进的行为。提交 PR 时说明变更与验证方式。不要提交 API Key、个人配置、素材路径、生成产物或私有子模块的内容。
-
-接口约定见 [contracts](../contracts/README.md)，Agent 使用方式见 [AGENT.md](../AGENT.md)。
+# 开发与贡献
+
+[返回首页](../README.md) · [命令参考](reference.md) · [English](development.en.md)
+
+## 本地开发
+
+CLI 运行时需要 Node.js ≥ 20.6；源码开发与构建使用 Bun。
+
+```bash
+git clone https://github.com/Gitruck/cli.git
+cd cli
+bun install
+bun run src/index.ts --help
+npm run typecheck
+bun run build
+```
+
+公共仓库可用于阅读、开发和构建 CLI。`test/` 与 `openspec/` 是需要维护者权限的私有子模块，公开贡献者无需递归拉取它们；完整测试由有权限的维护者运行。
+
+## 项目结构
+
+```text
+src/index.ts       命令入口
+src/commands/      CLI 命令
+src/lib/           云端调用、素材处理、工程装配与渲染
+skills/            随包 Agent Skills
+contracts/         工程与动态图等开放契约
+docs/              工作流、配置、命令和开发参考
+assets/            README 配图
+AGENT.md           可移植 Agent 操作手册
+```
+
+新增命令在 `src/commands/` 中提供注册函数，并在 `src/index.ts` 接入；工具族优先复用已有描述器与执行器。随包 Skills 的权威清单在 `src/commands/skills.ts`，详细名单见[参考文档](reference.md)。
+
+## 文档与校验
+
+- README 负责产品展示和上手；参数、配置与完整操作解释维护在 `docs/reference.md` / `docs/reference.en.md`。
+- 两份 README 和对应双语文档同步更新。命令名、参数、字段与产物文件名保持原样；示例命令保持一致。
+- 配图使用公开可访问资源，或放入 `assets/`；案例保持可追溯，不将大视频打包进 npm。
+- 维护者运行 `npm test`（构建后通过 Node 测试），不要用 `bun test` 代替。纯文档变更至少运行相关文档守卫、检查链接和展示效果。
+- 修改公开随包文档时，检查 `npm pack --dry-run` 的文件清单，避免移动后漏包。
+
+## 提交贡献
+
+通过 [Issues](https://github.com/Gitruck/cli/issues)描述问题、使用场景或希望改进的行为。提交 PR 时说明变更与验证方式。不要提交 API Key、个人配置、素材路径、生成产物或私有子模块的内容。
+
+接口约定见 [contracts](../contracts/README.md)，Agent 使用方式见 [AGENT.md](../AGENT.md)。

package/docs/reference.en.md

@@ -15,7 +15,7 @@ Once installed, a single sentence in any agent invokes a gtrk skill:
 | ![Calling gtrk from an agent, example 1](../assets/agent-example-1.png) | ![Calling gtrk from an agent, example 2](../assets/agent-example-2.png) |
 | ![Calling gtrk from an agent, example 3](../assets/agent-example-3.png) | ![Calling gtrk from an agent, example 4](../assets/agent-example-4.png) |
 
-`gtrk install` installs the 18 bundled CLI skills (`gtrk-oralcut`·`gtrk-long2short`·`gtrk-splitter`·`gtrk-matrix`·`gtrk-mg`·`gtrk-ai-drama`·`gtrk-style-maker`·`gtrk-transcript`·`gtrk-tools`·`gtrk-music-visualizer`·`gtrk-cover`·`gtrk-travel-recap`·`gtrk-live-slicing`·`gtrk-talking-head`·`gtrk-narration`·`gtrk-voiceover`·`gtrk-food-recap`·`gtrk-vlog-docu`) into the agents detected on this machine. The mechanism matches lark-cli: gtrk hands its local skill sources to the generic `skills` CLI, which owns agent detection, directory mapping and update rules; gtrk no longer hardcodes per-vendor paths.
+`gtrk install` installs the 19 bundled CLI skills (`gtrk-oralcut`·`gtrk-long2short`·`gtrk-splitter`·`gtrk-matrix`·`gtrk-mg`·`gtrk-composite`·`gtrk-ai-drama`·`gtrk-style-maker`·`gtrk-transcript`·`gtrk-tools`·`gtrk-music-visualizer`·`gtrk-cover`·`gtrk-travel-recap`·`gtrk-live-slicing`·`gtrk-talking-head`·`gtrk-narration`·`gtrk-voiceover`·`gtrk-food-recap`·`gtrk-vlog-docu`) into the agents detected on this machine. The mechanism matches lark-cli: gtrk hands its local skill sources to the generic `skills` CLI, which owns agent detection, directory mapping and update rules; gtrk no longer hardcodes per-vendor paths.
 
 By default `~/.agents/skills` is the single source of truth, linked into each agent's compatible directory (junctions on Windows); where linking is unavailable the adapter falls back to copying. That way updates touch one canonical copy instead of letting duplicates drift apart. Common commands:
 
@@ -64,6 +64,7 @@ Then just say "**cut a version of this talking-head**", or explicitly pick `gtrk
 | ③ | `/gtrk-ai-drama` | (no command, pure authoring) | **B-roll base · AI scene-clip leg (same stage as matrix, not last)**: emits four-part description docs (backstory / characters / shots / source text, in Chinese and English blocks) → generate on any external platform and re-insert by hand (the artifact is description text with no mechanical tail, same as `/gtrk-style-maker`: skill only, no command) |
 | ④ | (no skill) | (no command) | **Global frame-sampling composition check**: sample frames from the merged three-source base layer and have the user confirm the composition — a hard agent-discipline gate feeding ⑤'s placement decisions |
 | ⑤ | `/gtrk-mg` | `gtrk mg` | **MG (incl. ov) goes on last** (stacked on the settled, composition-checked base layer) |
+| ⑥ | `/gtrk-composite` | `gtrk composite` | **Composite layer** (after subtitles, before export): turn chosen time windows into composite particles — one code particle takes over the whole frame for that span (picture changes per sentence, side-by-side contrasts, list cards, subtitle layout) while the talking head and B-roll are drawn into its slots; three entry modes (cover the whole film / let the AI pick / user-given ranges), candidates show up in the client outline's CP row; purely local, zero billing. On export, `gtrk composite bake` bakes them into video locally (the first run needs `gtrk deps install --browser`) |
 | — | `/gtrk-style-maker` | (no command, builds a show) | A one-time interview that builds your show's style system (skill family + show config, see next section) |
 | ③′ | "**screen-recording PiP**" | `gtrk pip lay` | Mirror the talking-head rough cut's cut points onto a screen recording / second camera recorded in sync: lays a full-frame companion track + a muted picture-in-picture copy of the talking head (ellipse / rounded rectangle / heart / diamond / star mask, optional corner radius); purely local, zero billing; when alignment confidence is low it writes an alignment project for the client to drag into place, then `--resume` |
 | — | (wrap-up) | `gtrk render` | Render a gtrk project locally → finished mp4 (overlays and MG particles included; particles that miss the cache are cloud-rendered and billed, `--no-particles` skips them) |
@@ -81,7 +82,7 @@ Then just say "**cut a version of this talking-head**", or explicitly pick `gtrk
 | 🧭 | `/gtrk-vlog-docu` | orchestrates `gtrk transcript` → `tool audio_tts_clone` → `split` → `matrix` → `mg` → `audio lay` → `subtitle lay` | **Documentary-vlog blueprint**: a batch of on-location footage → footage understanding, register choice and script, one sign-off → live-sound skeleton + narration voice-over + B-roll + subtitle layer + BGM run unattended → a client-ready project; alternates on-location sound with post-production narration, unlike the pure talking-head or pure voice-over chains |
 
 > **Skill vs command**: `/gtrk-mg` is the **brain** — it knows it belongs at SOP step ⑤ (MG only after all three B-roll sources have landed and the composition is checked), asks for your confirmation, and resolves which particle type to produce from the show config; `gtrk mg` is the **hands** — purely deterministic lint + track laying. You trigger the skill by talking, and the skill runs the command for you.
-> The 18 `/gtrk-X` skills above are **framework skills bundled with the CLI** (installed by `gtrk skills install`; the list is identical to the ones in "Using it with AI agents" and "Layout") — the 7 marked 🧭 are **composite blueprints** (one sentence runs a whole chain; they only orchestrate the single-command skills above and add no commands of their own); `/gtrk-long2short` independently drives long-to-short, `/gtrk-transcript` independently drives video/audio-to-transcript, `/gtrk-tools` covers only the single-shot tool family, `/gtrk-cover` handles covers, and none of the four belong to the production SOP; `/gtrk-ai-drama`·`/gtrk-style-maker`·`/gtrk-cover` are pure authoring skills (no command). Show-specific **visual style and content** come instead from your own show's production skills (created by `/gtrk-style-maker`, bound through the show config's `style.skills`) and are never hardcoded into these framework skills.
+> The 19 `/gtrk-X` skills above are **framework skills bundled with the CLI** (installed by `gtrk skills install`; the list is identical to the ones in "Using it with AI agents" and "Layout") — the 7 marked 🧭 are **composite blueprints** (one sentence runs a whole chain; they only orchestrate the single-command skills above and add no commands of their own); `/gtrk-long2short` independently drives long-to-short, `/gtrk-transcript` independently drives video/audio-to-transcript, `/gtrk-tools` covers only the single-shot tool family, `/gtrk-cover` handles covers, and none of the four belong to the production SOP; `/gtrk-ai-drama`·`/gtrk-style-maker`·`/gtrk-cover` are pure authoring skills (no command). Show-specific **visual style and content** come instead from your own show's production skills (created by `/gtrk-style-maker`, bound through the show config's `style.skills`) and are never hardcoded into these framework skills.
 
 **How each lane's actual visuals/content get produced** — what the MG looks like, what tone the AI re-enactment has — is not hardcoded into the CLI. It comes from **your own show's production skills** (created interactively with `/gtrk-style-maker`, kept locally). They are bound through the show config's **`style.skills[].produces`** (the value is the lane name), and **general-purpose drivers** such as `gtrk mg` / `gtrk matrix` consume them accordingly. **The direction is: the CLI drives the show skills** — show skills only supply style/content and carry no "which command to run" orchestration; the framework only knows lanes and pipeline interfaces, and the look always belongs to your show. Without a show, the built-in defaults are used and everything still runs end to end.
 
@@ -187,7 +188,7 @@ Common entry points: `gtrk oralcut` edits talking heads, `gtrk long2short` selec
 
 ### `gtrk long2short` / `gtrk pip` / `gtrk qc` — Additional commands
 
-- `gtrk long2short <input>`: select topics and jump-cut into per-clip gtrk / Jianying / XML projects. `--split-screen` uses a 720p proxy for smart split-screen; `--output-size` selects the aspect ratio; `--subtitle-out` writes captions for each clip. Run landscape and portrait separately; content determines the number of clips. See `gtrk long2short --help` for all options.
+- `gtrk long2short <input>`: select topics and jump-cut into per-clip gtrk / Jianying / XML projects. `--split-screen` uses a 720p proxy for smart split-screen; `--output-size` selects the aspect ratio; `--subtitle-out` writes captions for each clip; `--speed-factor 0.5–2.0` writes an overall speed change (pitch preserved) into every clip project (no cloud rendering, no extra charge); `--camera-move` has the cloud write push / pull camera moves as scale keyframes on main-track segments (visible and editable in the client and Jianying, not shown by local `gtrk render` or Premiere projects; `clips.md` marks "N camera moves"), and later `gtrk patch` trims / splits keep those keyframes valid. The output root also gets a whole-source transcript `json/transcript.json`, so any clip can get a client caption track: `gtrk subtitle lay --gtrk <clip dir>/gtrk/<project>.gtrk --transcript <output root>/json/transcript.json --language <source language>` (`--language` sets the cloud line-split language, default zh-CN). Run landscape and portrait separately; content determines the number of clips. See `gtrk long2short --help` for all options.
 - `gtrk pip lay`: lay a simultaneously recorded screen or second camera against the talking-head cut points. Both sources need shared audio for alignment; low-confidence matches require calibration in the client before resuming. Use `gtrk pip lay --help` for inputs, shapes, positions and offsets.
 - `gtrk qc <video>`: inspect flash frames, black/frozen frames, volume and synchronization. Add `--gtrk` for project context and `--fail-on` for pipeline gating. Findings locate issues; they do not automatically repair the video.
 
@@ -331,8 +332,8 @@ Each source becomes one low-resolution full-window preview candidate. `source-im
 | `--lay <n>` | How many candidate tracks to lay (`0` = produce the plan only, lay nothing) | `1` |
 | `--top-k <n>` | Candidate cap per query (overrides the dispatch's shots; server cap is 50) | dispatch value |
 | `--material-class <c>` | Material type `real_shot` \| `concept` (matrix-member endpoint only; overrides the show policy) | show policy |
-| `--score-floor <f>` | Fill-confidence floor: segments scoring below this are not used and the slot stays empty — empty spots **expose the black bed track** (laid by default; only `--no-black-bed` exposes the main track instead). Raising it shrinks the candidate pool, and a span that cannot be filled at all becomes pure black over the talking-head, so check the hole warnings after adjusting | `0.2` |
-| `--no-black-bed` | Do not lay the solid black bed track (one is laid by default) | laid by default |
+| `--score-floor <f>` | Fill-confidence floor: segments scoring below this are not used and the slot stays empty — in talking-head projects the candidate track **patches empty spots with solid black**. Raising it shrinks the candidate pool, and a span that cannot be filled at all becomes pure black over the talking-head, so check the hole warnings after adjusting | `0.2` |
+| `--black-bed` | Legacy layout: lay one solid black bed track and leave candidate clips without a background fill (for older clients that do not read clip fills); `--no-black-bed` is now the default (no-op) | off |
 | `--force-relay` | Strip and re-lay even when you have already edited a candidate track in the client (by default it refuses and keeps that track) — **this deletes the `broll-raw-*` material registrations of confirmed source clips, orphaning those files on disk** | off |
 | `--out <file>` | Write ad-hoc results to a file; for `matrix fetch`, the raw-footage output directory (never the Jianying draft folder) | stdout / `./matrix-fetch/` |
 | `--arrange <m>` | **B-roll arrangement route** — **picked automatically by material source; you normally do not pass it**: your own local footage → `cloud` (arranged in the cloud, billed by **arrangement volume**, with an estimate and a confirmation prompt first; `--yes` skips). Material from the asset matrix → `local` (arranged on your machine, not billed, unchanged byte for byte). `shadow` is an observation mode: your machine lays as usual while the cloud runs the same arrangement for comparison only. ⚠️ On the local-footage route `--arrange local` is not accepted (passing it is a parameter error), and if the cloud cannot deliver a result the command **fails outright** instead of quietly switching to a different algorithm. It is **not a way to save credits** either — asset-matrix material is billed for search. Both routes cost something; they just cost it at different steps | picked by material source |
@@ -367,7 +368,9 @@ Each source becomes one low-resolution full-window preview candidate. `source-im
 >
 > **Material-on-disk self-check**: after writing back the project, the CLI read-only checks whether every `materials[].path` exists. Relative paths resolve against the directory containing the `.gtrk` file (`<output>/gtrk/`). `--json` emits `integrity:{ checked, counts, dangling:[…], danglingReferenced, danglingOrphan, external:[…], noPathIds:[…] }`; `dangling` lists registered materials missing on disk and marks whether the timeline references each one, while missing absolute paths are counted as `external`; http(s) materials are counted without network requests. This check only reports: it does not change `ok`, the exit code, material entries or files. Repair a dangling reference by re-confirming the source clip in the client or deleting the corresponding clip. Runs that never write back (`--lay 0` / refused / missing project) emit no `integrity` field.
 >
-> **The solid black bed track**: by default a solid black track covers the landed beat envelope beneath candidate tracks and above the talking-head track, so empty B-roll spans do not reveal the picture underneath. Empty candidate spans become “black-bed holes”; `--json` always emits `lay.blackBedHoleSec` and `lay.blackBedHoles`, with a non-fatal warning at ≥3 s for one span or ≥15% of one beat. Adjust `--score-floor`, use `--no-black-bed`, or patch in the client. The material is stored at `assets/builtin/solid-000000-<W>x<H>.png` and reused idempotently; drag replacements onto candidate tracks, never onto the black bed. Client 0.2.10+ rejects drops onto the black bed; upgrade older clients first. Use `--no-black-bed` to remove it.
+> **Clip background fill (default)**: every candidate clip carries a solid black fill (gtrk contract `background_fill`, so narrow or shrunken clips never reveal the talking-head underneath), and each candidate track patches its own empty spans inside every landed beat envelope with solid black clips — with `--lay 2`, leaving only one track visible still hides the talking-head; audio-driven projects (no talking-head) are not patched. `--json` emits `lay.bed` (`fill`) and `lay.bed_fill` (patches and seconds). Spans with no B-roll at all count as holes: `lay.blackBedHoleSec` / `lay.blackBedHoles` are always emitted, with a non-fatal warning at ≥3 s for one span or ≥15% of one beat; adjust `--score-floor` or patch in the client. The patch material is stored at `assets/builtin/solid-000000-<W>x<H>.png` and reused idempotently.
+>
+> **Solid black bed track (`--black-bed`, legacy)**: one solid black track covers the landed beat envelope beneath candidate tracks and above the talking-head track, and candidate clips carry no fill; holes are counted the same way with the same numbers. A black bed track left in an older project is replaced by clip fills on the next default re-lay.
 
 **Local-footage mode (`matrix index` / `--local`)**: footage does not have to live in the cloud library — retrieve and lay tracks straight from your local footage folders (video and images mixed):
 
@@ -386,7 +389,7 @@ gtrk matrix lay --project <dir> [--plan <path>]                # ③ consume the
 - **Highlight rubric**: `--highlight-rubric <text|@file>` (same flag on `describe` and `lay`; ≤2000 characters; `@<path>` reads from a file, which is the main form since a rubric is multi-line). It tells the highlight score (`--highlight-weight`) **what to judge by** — each vertical blueprint carries its own (food judges portion contrast and visible prices, travel judges rare landforms and extreme weather). **Omit it and the field is not sent at all**: the server falls back to its own domain-agnostic default, byte-for-byte identical to behaviour before this flag existed. Highlight scores are cached in **per-rubric buckets**: switching rubric rescores without invalidating or overwriting the objective description cache. `describe --plan` pins the run's `rubric_hash` into the plan and `lay` reads that same bucket automatically (no need to pass it twice); if the two disagree `lay` **fails hard** instead of silently picking one — scoring against the wrong rubric is undetectable after the fact. ⚠️ Rescoring under a new rubric still re-sends the frames (billed per frame): a text-only rescore channel needs server support and does not exist yet.
 - **Index knobs and score scale**: `--scene-threshold` tunes scene-split granularity, `--stability-threshold` collapses static-camera scenes to fewer sampled frames, `--rebuild` forces a rebuild (describe caches are kept); the index is not portable across machines (keys are absolute paths — just re-run `index` on the new machine). Local score scale differs from the cloud's (a perfect hit can score as low as ~0.25), so do not raise `--score-floor` on cloud instincts.
 
-**`gtrk matrix material "<query>"` (general tri-state material search)**: the second line alongside the B-roll search above, returning a download link for the **whole material** (not a segment) — `--scope clip|image|audio` (default `audio`, the BGM use case), `--commercial-only` searches commercially usable material only (**an explicit opt-in switch — off by default**), `--min-duration/--max-duration` picks by finished-cut length, `--top-k` (default 5, server cap 50), `--diversity`, `--json` for machine reading, `--out` to write a file.
+**`gtrk matrix material "<query>"` (general tri-state material search)**: the second line alongside the B-roll search above, returning a download link for the **whole material** (not a segment) — `--scope clip|image|audio` (default `audio`, the BGM use case), `--commercial-only` searches commercially usable material only (**an explicit opt-in switch — off by default**), `--min-duration/--max-duration` picks by finished-cut length, `--top-k` (default 5, server cap 50), `--diversity`, `--json` for machine reading, `--out` to write a file. With `--scope clip|image` it also returns **Pexels supplementary results**, listed separately in `pexels_results` and not counted as candidates (`--no-stock` turns this off); download them straight from `download_url` (not via `matrix fetch`) and keep the photographer credit and the Pexels link when you use them.
 
 > ⚠️ **`is_copyright` means "may this be used commercially", not "is this under copyright"**: `true` = **commercially usable** (owned ∪ licensed), `false` = **not commercially usable**.
 >
@@ -438,6 +441,39 @@ Consumes the `dispatch.mg` dispatch landed by `gtrk split`, laying html-particle
 > **Aux overlay particles**: if `gtrk split` dispatched an `overlay` particle in some beat's `aux_layers`, it derives a `<beat>-aux<n>` composition entry into `dispatch.mg` — `gtrk mg` lays it too, giving you "a main visual on the base track plus a transparent conceptual diagram stacked on the same span".
 > **Dual-read compatibility**: `dispatch.mg` (also reads the old `rrv_mg`), the source directory `mg/` (also reads the old `rrv/`), the material prefix `mg-` (also reads the old `rrv-`) — projects created before the de-branding need zero migration.
 
+### `gtrk composite` — composite layer (plan / review / scaffold / build / lint / lay / shots / bake)
+
+Once the rough cut, B-roll and subtitles are settled, turn chosen time windows into **composite particles**: one code particle takes over the whole frame for that span, and the client draws the talking head and B-roll into its slots. Driven by `/gtrk-composite` (which carries the layout rules and two checkpoints); purely local, zero billing.
+
+```bash
+gtrk composite plan --project <dir> [--mode full|auto|ranges] [--range 11,32 | --range u0004-u0009]... [--density 0.25]
+gtrk composite review --project <dir> [--approve W01,W03] [--reject W02] [--adjust W04=80,90.9] [--add 140,150] [--approve-all]
+gtrk composite scaffold --project <dir> [--only W03] [--force]
+gtrk composite shots --project <dir> --material <material id or file> [--around <sec> --span <sec> | --from <sec> --to <sec>] [--every <sec>]
+gtrk composite build --project <dir> [--only cp-w03] [--theme <css>] [--materials <json>]
+gtrk composite lint --project <dir> [--only cp-w03] [--stills 26,86.6] [--no-browser]
+gtrk composite lay --project <dir> [--only cp-w03] [--dry-run]
+gtrk composite bake --project <dir> [--only cp-w03] [--fps 30] [--workers 4] [--install-browser] [--progress jsonl] [--json]
+gtrk composite bake --input <snapshot.gtrk> --base <project gtrk dir> [--progress jsonl]
+gtrk composite bake --abi
+```
+
+- `plan`: writes candidate windows to `struct_meta.composite` in the `.gtrk` (that key only, atomic write-back; the same pattern as `gtrk split` writing `struct_meta.split`); the client outline's CP row draws them as proposal blocks. Also writes a review sheet `composite/plan.md`. Re-running keeps built windows and does not re-propose rejected ones.
+- `review`: approve / reject / adjust / add windows, written back to the same key; later steps only act on approved windows.
+- `scaffold`: writes a scene skeleton `composite/scenes/cp-wNN.html` and a context sheet `cp-wNN.context.md` for each approved window; existing scenes are not overwritten.
+- `shots`: for picking footage — a contact sheet stamped with source time codes, shot cut points, and measured black bars (values for `data-crop`); it does not pick for you and does not touch the project.
+- `build`: scene → self-contained particle `gtrk/assets/composite/<id>.html`. Resolution matches the infra `composite-particle-profile` rules byte for byte (frame-grid window, track identity, anchors, subtitle input, `inputs_hash`); style comes from `composite/theme.css`.
+- `lint`: static checks plus a per-frame layout check in the local Chrome / Edge (a lower picture's foreground border over an upper picture, a foreground line crossing a picture, a picture leaving the stage) and a **frame-purity** check (each sampled frame is rendered twice — once right after the previous frame, once after a distant frame — and element and slot geometry must match; impure scenes draw the wrong picture at bake chunk starts and after preview seeks), optionally rendering stills. Exit code 0 pass / 1 problems / 3 layout not checked (no browser found; set `GTRK_CHROME`).
+- `lay`: idempotently lays onto the topmost beat track by producer identity, registers materials, marks windows built; refuses stale particles; never overwrites a same-id particle the user edited in the client.
+- `bake`: bakes the laid composite particles **into opaque video locally**, written to `gtrk/assets/composite-bake/<key>.mp4`; inputs (slot pictures, subtitles, anchors) are computed from the **current timeline**. Purely local, zero billing.
+  - **Browser**: prefers the pinned chrome-headless-shell (deterministic frames, fastest); otherwise falls back to the local Chrome / Edge (screenshot mode, slower, one fewer worker by default). **Never downloads silently**: install only with `gtrk deps install --browser` or this command's explicit `--install-browser` (about 110 MB). `GTRK_CHROME` selects a browser.
+  - **Concurrency**: resident worker pages render chunks in parallel, default `min(logical cores/3, 6)`, overridden by `--workers`; chunked and sequential bakes are bit-identical.
+  - **Cache**: the key covers the particle, the computed inputs, material file fingerprints (size + mtime), fps, browser build and encode settings; hits are reused. Changing concurrency does not change the key.
+  - **Frame rate**: defaults to the project rate; `--fps` overrides (e.g. a 30fps export). Frame count = `ceil(window × fps)`, covering the whole window.
+  - **Exit codes**: 0 all succeeded (cache hits included) / 1 some composite failed (the rest still bake; reasons per composite) / 2 argument or environment error / 130 cancelled.
+  - **Machine-readable**: `--progress jsonl` prints one event per line with `type` in `start` / `browser` / `prep` / `progress` / `composite` / `cancelled` / `done`, at most 1 second apart; in this mode **closing stdin cancels** (other modes ignore stdin). `--abi` prints only `{abi, version}` without reading the project. `--input <snapshot> --base <dir>`: use the snapshot as the timeline (for the client's unsaved state); relative material paths and the output location resolve against `--base`; the snapshot is never written back.
+- `gtrk render` / `gtrk project export` bake the project's composites first: a successfully baked span shows the baked video (in Jianying / Premiere, a video clip on that layer), and **MG / OV particles lying entirely inside a composite window are no longer pre-rendered or billed**; a composite that fails to bake (missing footage, no browser, …) falls back to the rough cut with its reason reported, and never blocks export.
+
 ### `gtrk project init` / `gtrk audio lay` / `gtrk audio tighten` — audio-first project atoms (voice-over first)
 
 Project entry points that start from **a voice-over** instead of a talking-head raw: with the voice-over in hand (TTS-synthesized or self-recorded), `project init` builds the `.gtrk` project, and `gtrk split --project` continues the production pipeline as usual; `audio lay` adds an audio track (BGM/score) to any project; `audio tighten` tightens the pauses between sentences in the voice-over.
@@ -475,6 +511,35 @@ There are two billing surfaces: structural project export is billed per task, wh
 
 Before particle rendering, the command performs HTML, path and cache preflight; a preflight failure submits no cloud task. A single particle render or download failure is recorded in `result.json` while other formats continue. With `--json`, stdout contains one result JSON line and human logs go to stderr.
 
+**Things only the client draws** (text, stickers, graphics and effects added in the client, and the canvas background) do not reach the exported project files: when the project has any, the command says once, before submitting, which kinds and how many; when there is text it points to exporting a Jianying draft from the client (the client carries text over as editable captions). `droppedByContract.clientOnly` in `result.json` holds the per-kind counts, and `clientVisualElementCount` is the number of elements (it used to count lanes by mistake).
+
+**Clip background fill** (`background_fill`): the bottom track of Jianying / CapCut drafts carries it natively; on other tracks the cloud inserts a helper track beneath the clip — a solid color becomes a same-color solid image, a blur becomes the same footage (same time range, muted, scaled to cover the canvas) with Jianying's Blur effect. Premiere projects get the same treatment on every track, with a Gaussian Blur; FCPXML / OTIO only do solid colors, and a blur degrades to solid black there with a log notice (Jianying / Premiere also degrade when the footage size is unknown and it cannot be scaled to cover). Clips that already cover the whole canvas get no backdrop. The solid images are referenced as `solid-<rrggbb>-<W>x<H>.png` inside the output folder, and the command writes them before the project files — **moving or deleting the output folder takes those images offline**. `backgroundFill` in `result.json` records the written images and degradation notices (absent when the project has no fills).
+
+### `gtrk project background` — clip background fill (blur / solid color)
+
+By default writes a clip-level `background_fill` (gtrk contract field) on **every video / image clip of the main track**: beneath the clip, only for its duration, covering the whole canvas; blur = the clip's own picture scaled to cover and blurred. The typical use is a blurred fill instead of black bars when a landscape source sits on a portrait canvas. Users can change it per clip or for a multi-selection in the client; Jianying drafts exported from the client or `gtrk project export` carry it natively (the main track is the bottom track), Premiere projects use the same footage scaled to cover with a Gaussian Blur, FCPXML / OTIO degrade it to solid black with a notice, and local `gtrk render` carries it. Overlay-track clips and gaps are left alone, and `struct_meta.client_background` is not touched (the receipt says whether one is still present). Zero credits, no cloud access.
+
+`--scope canvas` keeps the old canvas-level write: only `struct_meta.client_background` changes (the client renders the canvas background from it; Jianying / Premiere projects and local rendering do not carry it).
+
+```bash
+gtrk project background --gtrk <project-file> --blur
+gtrk project background --project <project-dir> --blur --intensity 300
+gtrk project background --gtrk <project-file> --color "#1A1A1A"
+gtrk project background --gtrk <project-file> --clear
+```
+
+| Option | Purpose |
+|---|---|
+| `--project <dir>` / `--gtrk <path>` | Locate the project, same rules as `project export` |
+| `--blur` | Blurred fill: the clip's own picture scaled to cover and blurred (canvas scope: a blurred copy of the main-track picture) |
+| `--intensity <n>` | With `--blur`, 0–1000, default 200 (must be an integer per clip) |
+| `--color <#RRGGBB>` | Solid color (six-digit hex) |
+| `--clear` | Remove the fill (per clip: drop `background_fill` from main-track clips; canvas: delete `client_background` and return to the client's default black) |
+| `--scope <clips\|canvas>` | Scope: `clips` (default) per main-track clip; `canvas` canvas level (old behavior) |
+| `--dry-run` | Validate and report the value that would be written, without writing |
+
+Exactly one mode is required. Writes go through atomic replace with the content-revision guard and leave everything else intact; nothing is written when the value is unchanged. The `--json` receipt includes the revisions before and after.
+
 > **`--beat-align`**: follows the climax-anchor rule in the table above; an explicit `--climax` overrides the automatic selector. The mode calls `audio_music_analyze` and incurs its listed charge.
 
 
@@ -590,11 +655,12 @@ gtrk render <gtrk> [-o <out.mp4>] [--crf <n>] [--codec <c>] [--ffmpeg-path <dir>
 
 Treats the `.gtrk` as an EDL and renders it with local ffmpeg. **Footage always comes from the local originals** (`materials[].path`); the cloud never produces the finished file.
 
-**What gets composited**: the base track (the lowest `track_index` that is not the black bed) plus every audio source, then **every visible overlay layer** stacked in contract z-order (ascending `track_index`, larger = closer to the front) — overlay video tracks (B-roll candidates, AI re-enactment) and the MG particles on `beat_track`.
+**What gets composited**: the base track (the lowest `track_index` that is not the black bed) plus every audio source, then **every visible overlay layer** stacked in contract z-order (ascending `track_index`, larger = closer to the front) — overlay video tracks (B-roll candidates, AI re-enactment) and the MG particles on `beat_track`. Composite particles are baked locally first (see `gtrk composite bake`, zero billing) and laid as the baked video on their layer; MG particles they fully cover are no longer cloud-rendered.
 
 - **Visibility reads the `hidden` field only** (the client's "eye" toggle): a hidden track stays out of the cut entirely and is reported. The renderer never guesses which track belongs in the picture.
 - **When several candidate tracks are visible, the topmost one wins** (exactly what the client preview shows). To pick a different one, hide or delete tracks in the client.
 - Missing overlay footage (e.g. B-roll proxies not fully downloaded) **degrades instead of blocking**: that clip is not composited, a warning is printed, and the render still completes.
+- **Things only the client draws stay out of the cut**: text added in the client (including captions laid by `gtrk subtitle lay`), stickers, graphics, effects, and the canvas background (`gtrk project background --scope canvas`). When the project has any, the command says once, before rendering, which kinds and how many, and points to local export in the client; it does not block or change the render. The `--json` result always carries `clientOnly` (`text / sticker / graphic / effect / other` counts and a `background` boolean, present even when all zero).
 
 **The particle half is billed** (the only cloud egress of this command):
 
@@ -620,8 +686,8 @@ A QC pass runs automatically afterwards and writes `.qc.json` (`--no-qc` skips i
 - `gtrk install [--api-key … -y --skill-agents codex,cursor --all-agents --copy-skills --skills-dir …]` — install everything in one command (skills + config + health check), modelled on Feishu's `lark-cli install`.
 - `gtrk init [--api-key … --api-base … --jianying-draft-dir … -y]` — configuration only (interactive or not).
 - `gtrk doctor` — health check (including the CLI version and whether a newer one exists).
-- `gtrk deps status` — show **where** ffmpeg/ffprobe and the render fonts currently come from (`--ffmpeg-path` / `~/.gitruck` / system / missing), plus version, licence and source-code location.
-- `gtrk deps install [--ffmpeg] [--font] [--force]` — install runtime assets from the Gitruck Cloud mirror, **skipping anything already present**.
+- `gtrk deps status` — show **where** ffmpeg/ffprobe, the render fonts and the composite-bake browser currently come from (`--ffmpeg-path` / `~/.gitruck` / system / missing), plus version, licence and source-code location.
+- `gtrk deps install [--ffmpeg] [--font] [--browser] [--force]` — install runtime assets from the Gitruck Cloud mirror, **skipping anything already present**. Without flags it installs ffmpeg and fonts; `--browser` additionally installs the pinned chrome-headless-shell for composite baking (about 110 MB, into `~/.gitruck/browsers`, BSD licence, provenance and source in the mirror's `SOURCE.md`), **only when named explicitly**.
   - **It never downloads silently**: any missing-dependency path only errors out and points at this command (the packages are 30–90 MB and the distributed artifacts carry licence obligations, so a user or agent must trigger it explicitly).
   - Downloads are always https with **strict sha256 verification**; anything that fails verification is discarded and never lands. Extraction uses the **system tar** (bundled with Windows 10+/macOS/Linux), pulling in no third-party decompression dependency.
   - The resolution order is unchanged: `--ffmpeg-path` → `~/.gitruck/ffmpeg` → system `PATH`. The mirror only fills the middle slot and **never overrides an ffmpeg you installed yourself**.
@@ -634,4 +700,4 @@ A QC pass runs automatically afterwards and writes `.qc.json` (`--no-qc` skips i
 
 ### Highlight discovery (internal preview)
 
-`gtrk tool video_highlight <video> --out <project> --json` uploads a locally generated silent 224p/4fps proxy. Inputs must be longer than 3 seconds and at most 30 minutes. Results contain three-second candidates grouped by request; scores cannot be compared across requests. Review candidates against the story and actual footage. Provider failure stays explicit; Vlog planning can continue with Agent material review. External billing is not enabled.
+`gtrk tool video_highlight <video> --out <project> [--no-audio] --json` uploads a locally generated 448p/4fps analysis proxy with a low-bitrate mono audio track by default (`--no-audio` to omit it); the original file is never uploaded. Inputs must be longer than 3 seconds and at most 30 minutes. Results contain three-second candidates grouped by request; scores cannot be compared across requests. Review candidates against the story and actual footage. Provider failure stays explicit; Vlog planning can continue with Agent material review. External billing is not enabled.