@gitruck/cli 1.3.4 → 1.3.6

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.
 
@@ -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, browser, overrides}` without reading the project: `browser.pinned` says whether the pinned render component is installed; `overrides` lists the slot user overrides this version can bake (`fit` / `framing` / `crop` / `box` for the picture-in-picture window size and position / `slip_ms` for shifting a referenced clip's frames), so the client can tell whether the adjustments in a project can be baked. `--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,9 +511,15 @@ 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.
 
-### `gtrk project background` — client canvas background (blur / solid color)
+**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.
 
-Changes only `struct_meta.client_background` in the `.gtrk`; the client renders the canvas background from it when the project opens, and the user can change it back in the client settings. The typical use is a blurred fill instead of black bars when a landscape source sits on a portrait canvas. Zero credits, no cloud access; Jianying / Premiere projects and local `gtrk render` do not carry this setting.
+`--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
@@ -489,10 +531,11 @@ gtrk project background --gtrk <project-file> --clear
 | Option | Purpose |
 |---|---|
 | `--project <dir>` / `--gtrk <path>` | Locate the project, same rules as `project export` |
-| `--blur` | Blurred fill: a blurred copy of the visible main-track picture underneath |
-| `--intensity <n>` | With `--blur`, 0–1000, default 200 |
+| `--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 setting and return to the client's default black |
+| `--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.
@@ -612,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):
 
@@ -642,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**.
@@ -656,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.

package/docs/reference.md

@@ -23,7 +23,7 @@
 | ![在 Agent 中调用 gtrk 示例 1](../assets/agent-example-1.png) | ![在 Agent 中调用 gtrk 示例 2](../assets/agent-example-2.png) |
 | ![在 Agent 中调用 gtrk 示例 3](../assets/agent-example-3.png) | ![在 Agent 中调用 gtrk 示例 4](../assets/agent-example-4.png) |
 
-`gtrk install` 会把 18 个 CLI 自带 skill（`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`）装进本机检测到的 Agent。实现方式与 lark-cli 一致：gtrk 把本地 skill 源交给通用 `skills` CLI，由它维护 Agent 探测、目录映射及更新规则；gtrk 不再硬编码各家路径。
+`gtrk install` 会把 19 个 CLI 自带 skill（`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`）装进本机检测到的 Agent。实现方式与 lark-cli 一致：gtrk 把本地 skill 源交给通用 `skills` CLI，由它维护 Agent 探测、目录映射及更新规则；gtrk 不再硬编码各家路径。
 
 默认使用 `~/.agents/skills` 作为统一正本，再链接到各 Agent 的兼容目录（Windows 使用 junction）；链接不可用时适配器会回退复制。这样更新只有一份正本，不会让多份副本逐渐漂移。常用命令：
 
@@ -70,6 +70,7 @@ gtrk skills install --copy
 | ③ | `/gtrk-ai-drama` | （无命令，纯创作） | **B-roll 底轨·AI 情景片段腿（与 matrix 同阶段，不是最后）**：产四段描述稿（故事背景/角色/分镜/原文，中英分块）→ 任意外部平台出片、手动回铺（产物即描述文本、无机械尾巴，同 `/gtrk-style-maker` 只 skill 无命令） |
 | ④ | （无 skill） | （无命令） | **全局抽帧检查画面构图**：对三源合并后的最终底轨抽帧，用户确认构图——这是 agent 纪律硬门，供 ⑤ 的排版避让决策使用 |
 | ⑤ | `/gtrk-mg` | `gtrk mg` | **MG（含 ov）最后叠上**（叠在已定稿、构图已核的底轨之上） |
+| ⑥ | `/gtrk-composite` | `gtrk composite` | **合成层**（字幕之后、出片之前）：把选定时间窗做成合成颗粒——一段时间内的整个画面由一颗代码颗粒接管（逐句换画面、对照并排、并列卡片、字幕排版），讲者与 B-roll 作为槽位画进去；入口三选一（整片铺满 / AI 判定 / 指定区间），候选显示在客户端大纲 CP 行；纯本地零计费。出片时由 `gtrk composite bake` 在本机烘焙成视频（首次需 `gtrk deps install --browser`） |
 | — | `/gtrk-style-maker` | （无命令，建栏目） | 一次性访谈式建你栏目的风格体系（skill 家族 + 栏目配置，见下节） |
 | ③′ | 「**屏录画中画**」 | `gtrk pip lay` | 把口播粗剪的切点镜像到同步录的屏录 / 第二机位，铺屏录满幅轨 + 人像画中画副本轨（圆 / 圆角方 / 爱心 / 菱形 / 星形蒙版，可圆角）；纯本地零计费；低置信时产对齐工程让客户端拖齐后 `--resume` |
 | — | （收口） | `gtrk render` | 本地渲染 gtrk 工程 → 成片 mp4（含 overlay 与 MG 颗粒；颗粒未命中缓存时云渲计费，`--no-particles` 可跳过） |
@@ -87,7 +88,7 @@ gtrk skills install --copy
 | 🧭 | `/gtrk-vlog-docu` | 编排 `gtrk transcript` → `tool audio_tts_clone` → `split` → `matrix` → `mg` → `audio lay` → `subtitle lay` | **Vlog 纪实图纸**：一批现场素材 → 素材理解、选档写稿、一次拍板 → 同期声骨架 + 旁白配音 + B-roll + 字幕层 + BGM 全自动 → 客户端可出片工程；「现场同期声 × 后期旁白」双声道交替，区别于纯口播链与纯配音链 |
 
 > **skill 与命令的区别**：`/gtrk-mg` 是**脑**——懂它在 SOP 第 ⑤ 步（B-roll 三源全齐、构图核过才铺 MG）、带用户确认、按栏目配置解析该产哪种颗粒；`gtrk mg` 是**手**——纯确定性 lint + 铺轨。你对话触发 skill，skill 替你跑命令。
-> 上面 18 个 `/gtrk-X` 都是 **CLI 自带框架 skill**（`gtrk skills install` 装；名单与「给 AI Agent 用」一节、「结构」一节完全一致）——其中 🧭 标记的 7 张是**组合图纸**（一句话跑全链，只编排上面的单命令 skill、本身不新增命令）；`/gtrk-long2short` 独立驱动长剪短，`/gtrk-transcript` 独立驱动视频/音频转文字稿，`/gtrk-tools` 只负责单点工具族，`/gtrk-cover` 管封面，四者都不属成片 SOP 序列；`/gtrk-ai-drama`·`/gtrk-style-maker`·`/gtrk-cover` 是纯创作 skill（无命令）。栏目专属的**视觉风格/生产内容**另由你栏目的生产 skill（`/gtrk-style-maker` 产、经栏目配置 `style.skills` 绑定）供，不写死在这些框架 skill 里。
+> 上面 19 个 `/gtrk-X` 都是 **CLI 自带框架 skill**（`gtrk skills install` 装；名单与「给 AI Agent 用」一节、「结构」一节完全一致）——其中 🧭 标记的 7 张是**组合图纸**（一句话跑全链，只编排上面的单命令 skill、本身不新增命令）；`/gtrk-long2short` 独立驱动长剪短，`/gtrk-transcript` 独立驱动视频/音频转文字稿，`/gtrk-tools` 只负责单点工具族，`/gtrk-cover` 管封面，四者都不属成片 SOP 序列；`/gtrk-ai-drama`·`/gtrk-style-maker`·`/gtrk-cover` 是纯创作 skill（无命令）。栏目专属的**视觉风格/生产内容**另由你栏目的生产 skill（`/gtrk-style-maker` 产、经栏目配置 `style.skills` 绑定）供，不写死在这些框架 skill 里。
 
 **各车道的具体视觉/内容怎么产**——MG 动态图长什么样、AI 情景动画什么调性——不写死在 CLI 里，而由**你自己栏目的生产 skill** 提供（用 `/gtrk-style-maker` 访谈式产出、留本地）。它们经**栏目配置 `style.skills[].produces`**（值 = 车道名）绑定，`gtrk mg` / `gtrk matrix` 等**通用驱动器**据此消费。**驱动方向 = CLI 驱动栏目 skill**：栏目 skill 只供风格/内容、不含任何「跑哪条命令」的编排职责；框架只认车道与管线接口，画面风格永远归你的栏目。不建栏目就用内置默认，端到端照常跑。
 
@@ -330,8 +331,8 @@ gtrk matrix source-import --project <工程目录> --beat B07 --urls links.txt -
 | `--lay <n>` | 候选铺轨数：平铺 N 条 B-roll 候选轨（`0` = 只出 plan 不铺轨） | `1` |
 | `--top-k <n>` | 每 query 候选数上限（覆盖派单 shots；服务端上限 50） | 派单值 |
 | `--material-class <c>` | 素材类型 `real_shot` \| `concept`（仅矩阵成员口；覆盖栏目策略） | 栏目策略 |
-| `--score-floor <f>` | 填充置信度地板：segment score 低于此值不采纳、槽位留空——留空处**露黑底垫轨**（默认铺；除非 `--no-black-bed` 才露主轨）。调高会收缩取材池，整段铺不满即纯黑压口播，调完先看空洞告警 | `0.2` |
-| `--no-black-bed` | 不铺纯黑底垫轨（默认铺一条） | 默认铺 |
+| `--score-floor <f>` | 填充置信度地板：segment score 低于此值不采纳、槽位留空——口播工程里留空处由候选轨**补纯黑片**。调高会收缩取材池，整段铺不满即纯黑压口播，调完先看空洞告警 | `0.2` |
+| `--black-bed` | 旧形态：铺一条纯黑底垫轨、候选片段不带底板（给不认片段底板的老版客户端过渡用）；`--no-black-bed` 已是缺省（无操作） | 关 |
 | `--force-relay` | 候选轨已被你在客户端编辑过时仍强剥重铺（缺省会拒铺并保留那条轨）——**会删掉已确认原片的 `broll-raw-*` 素材登记、盘上原片成孤儿** | 关 |
 | `--arrange <m>` | **B-roll 编排取数路**，**按素材来源自动定档、一般不用传**：铺你自己电脑里的素材 → `cloud`（编排在云端做，按「编排量」计费，跑前报预估并征求确认，`--yes` 跳过）；铺素材矩阵的素材 → `local`（编排仍在本机、不计费，逐字不动）。`shadow` 是观测档：本机照跑照铺轨、云端只对拍不采纳。⚠️ 本地素材路上 `--arrange local` 不受理（传了报参数错）；云端拿不到产物时**直接报错**，不会悄悄换算法把活干完 | 按素材来源自动 |
 | `--arrange-qc` | **编排期质检**（缺省关）：落轨**之前**就查每个 beat 的卡点句「画面有没有给到稿子说的东西」，没给到就换候选重排，最多 2 轮，到限即交付并如实登记还差哪几句。全程零渲染——替代「铺完 → 渲 → 看 → 重铺 → 再渲」那两轮。⚠️ 判定走素材理解口、**按帧计费**（每个卡点句 1 帧/轮，命中判定缓存的不重复计费），跑前报预估并征求确认（`--yes` 跳过）。与 `--arrange` 正交：本机档与云端档都能开 | 关 |
@@ -395,7 +396,9 @@ gtrk matrix source-import --project <工程目录> --beat B07 --urls links.txt -
 >
 > **素材落盘自检**：写回工程之后只读检查 `materials[].path` 是否落盘。相对路径以 `.gtrk` 文件所在目录（`<产物目录>/gtrk/`）为基准解析。`--json` 出 `integrity:{ checked, counts, dangling:[…], danglingReferenced, danglingOrphan, external:[…], noPathIds:[…] }`；`dangling` 是登记存在但文件缺失的素材，并标出是否被时间线引用，绝对路径缺失另计 `external`，http(s) 素材只计数且不发网络请求。检查只告知，不改 `ok`、退出码、素材条目或文件；修复悬空引用请在客户端重新确认原片或删除对应 clip。未写回的运行（`--lay 0` / 拒铺 / 工程缺失）不出 `integrity` 字段。
 >
-> **纯黑底垫轨**：默认在候选轨之下、口播主轨之上铺满已落成的 beat 包络，避免 B-roll 留空处露出底下画面。候选轨未填满的部分会形成「黑底空洞」；`--json` 恒出 `lay.blackBedHoleSec` 与 `lay.blackBedHoles`，单段 ≥ 3s 或单 beat 占比 ≥ 15% 时给非致命告警。可调 `--score-floor`、改用 `--no-black-bed` 或在客户端补片。素材落在 `assets/builtin/solid-000000-<W>x<H>.png` 并幂等复用；换片请拖到候选轨，不要拖到黑底条。客户端 0.2.10+ 拖到黑底条会直接拒绝，旧客户端先升级；不需要黑底时用 `--no-black-bed` 重跑。
+> **片段底板（缺省）**：每个候选片段自带纯黑底（gtrk 契约 `background_fill`，窄画幅 / 缩小时不露下层口播），每条候选轨在已落成的 beat 包络内把自己的空档补成纯黑片——`--lay 2` 时只留任一条可见也不露口播；音频驱动工程（无口播）不补。`--json` 出 `lay.bed`（`fill`）与 `lay.bed_fill`（补了几段、几秒）。没有任何 B-roll 的纯黑时段记作空洞：`lay.blackBedHoleSec` / `lay.blackBedHoles` 恒出，单段 ≥ 3s 或单 beat 占比 ≥ 15% 时给非致命告警，可调 `--score-floor` 或在客户端补片。补片素材落在 `assets/builtin/solid-000000-<W>x<H>.png` 并幂等复用。
+>
+> **纯黑底垫轨（`--black-bed`，旧形态）**：在候选轨之下、口播主轨之上铺满已落成的 beat 包络，候选片段不带底板；空洞口径与数值同上。老工程里已有的黑底轨在下次缺省重铺时被换成片段底板。
 
 **本地素材模式（`matrix index` / `--local`）**：素材不必入云端素材库，用你本地的素材文件夹（视频+图片混合）直接检索铺轨：
 
@@ -414,7 +417,7 @@ gtrk matrix lay --project <目录> [--plan <path>]               # ③ 消费（
 - **看点准则**：`--highlight-rubric <text|@file>`（describe 与 lay 同参，≤2000 字符，`@<路径>` 从文件读）给看点分（`--highlight-weight`）指定**评判基准**——垂类图纸各持一份（美食判分量对比/价格实物，旅拍判奇观地貌/极端天候）。**不传 = 整个字段不上行、服务端走领域无关缺省，与本参数引入前逐字节一致**。看点分按准则分桶缓存：换准则只重打分、客观描述缓存照常复用不被覆盖；`describe --plan` 会把本轮准则的 `rubric_hash` 钉进 plan，`lay` 据此自动取同一个桶（无需重复传参），两者不同源时**硬失败**而不是静默择一。⚠️ 换准则要重新打分就得重新看片（按张计费）——免看片的文本级重打分要等服务端轻通道，现在没有。
 - **索引参数与量纲**：`--scene-threshold` 调场景切分粒度、`--stability-threshold` 固定机位判稳收敛抽帧、`--rebuild` 强制重建（理解缓存不清）；索引跨机不可移植（键=绝对路径，换机重跑 index 即可）。本地 score 量纲与云端不同（完美命中可低至 ~0.25），`--score-floor` 别按云端直觉调高。
 
-**`gtrk matrix material "<词>"`（通用三态素材检索）**：与上面的 B-roll 检索并列的第二条线，出**整条素材**的下载直链（不是段落）——`--scope clip|image|audio`（缺省 `audio`，BGM 主场）、`--commercial-only` 只搜可商用（**按需收紧的显式开关，缺省不带**）、`--min-duration/--max-duration` 按成片时长挑、`--top-k`（缺省 5，服务端上限 50）、`--diversity` 去同质、`--json` 机读、`--out` 落盘。
+**`gtrk matrix material "<词>"`（通用三态素材检索）**：与上面的 B-roll 检索并列的第二条线，出**整条素材**的下载直链（不是段落）——`--scope clip|image|audio`（缺省 `audio`，BGM 主场）、`--commercial-only` 只搜可商用（**按需收紧的显式开关，缺省不带**）、`--min-duration/--max-duration` 按成片时长挑、`--top-k`（缺省 5，服务端上限 50）、`--diversity` 去同质、`--json` 机读、`--out` 落盘。`--scope clip|image` 时另附 **Pexels 补充结果**，单列在 `pexels_results`、不计入候选数（`--no-stock` 关闭）；补充素材直接用 `download_url` 下载（不走 `matrix fetch`），引用时保留摄影师署名与 Pexels 链接。
 
 > ⚠️ **`is_copyright` 读作「能不能商用」，不是「有没有被版权保护」**：`true` = **可商用**（自有 ∪ 已授权），`false` = **不可商用**。
 >
@@ -470,6 +473,39 @@ gtrk matrix lay --project <目录> [--plan <path>]               # ③ 消费（
 > **aux 叠层颗粒**：`gtrk split` 若在某 beat 的 `aux_layers` 派了 `overlay` 颗粒，会派生 `<beat>-aux<n>` 合成条目进 `dispatch.mg`——`gtrk mg` 一并铺，实现「同段既有底轨主视觉、又叠透明概念图解」。
 > **双读兼容**：`dispatch.mg`（读旧 `rrv_mg`）、源目录 `mg/`（读旧 `rrv/`）、素材前缀 `mg-`（读旧 `rrv-`）——去品牌化前的既有工程零迁移。
 
+### `gtrk composite` — 合成层（plan / review / scaffold / build / lint / lay / shots / bake）
+
+粗剪、B-roll、字幕都定了之后，把选定时间窗做成**合成颗粒**：一段时间内的整个画面由一颗代码颗粒接管，讲者与 B-roll 作为槽位由客户端画进去。由 `/gtrk-composite` 驱动（含编排规则与两个检查点）；纯本地、零计费。
+
+```bash
+gtrk composite plan --project <工程> [--mode full|auto|ranges] [--range 11,32 | --range u0004-u0009]... [--density 0.25]
+gtrk composite review --project <工程> [--approve W01,W03] [--reject W02] [--adjust W04=80,90.9] [--add 140,150] [--approve-all]
+gtrk composite scaffold --project <工程> [--only W03] [--force]
+gtrk composite shots --project <工程> --material <素材 id 或文件> [--around <秒> --span <秒> | --from <秒> --to <秒>] [--every <秒>]
+gtrk composite build --project <工程> [--only cp-w03] [--theme <css>] [--materials <json>]
+gtrk composite lint --project <工程> [--only cp-w03] [--stills 26,86.6] [--no-browser]
+gtrk composite lay --project <工程> [--only cp-w03] [--dry-run]
+gtrk composite bake --project <工程> [--only cp-w03] [--fps 30] [--workers 4] [--install-browser] [--progress jsonl] [--json]
+gtrk composite bake --input <快照.gtrk> --base <工程 gtrk 目录> [--progress jsonl]
+gtrk composite bake --abi
+```
+
+- `plan`：候选窗口写进 `.gtrk` 的 `struct_meta.composite`（只动这一个键、原子写回；与 `gtrk split` 写 `struct_meta.split` 同一套做法），客户端大纲 CP 行据此画提案块；另出审稿稿 `composite/plan.md`。重跑保留已做的、不再提用户不要的。
+- `review`：采纳 / 不要 / 调起止 / 补窗口，写回同一个键；后续步骤只处理已采纳的窗口。
+- `scaffold`：为已采纳窗口落场景骨架 `composite/scenes/cp-wNN.html` 与上下文 `cp-wNN.context.md`；已有场景不覆盖。
+- `shots`：给选片用——带源时间码的联系表、镜头切点、黑边实测（`data-crop` 取值）；不替你选、不改工程。
+- `build`：场景 → 自包含颗粒 `gtrk/assets/composite/<id>.html`。解析规则与 infra `composite-particle-profile` 逐字节一致（帧格窗口、轨身份、锚点、字幕输入、`inputs_hash`）；风格取 `composite/theme.css`。
+- `lint`：静态校验 + 本机 Chrome / Edge 逐帧排版机检（下层画面的前景描边压上层画面、前景线条穿过画面、画面越出舞台）与**帧纯度**机检（同一帧号按「先渲前一帧」「先渲远处一帧」两种顺序各渲一次，元素与槽位几何必须一致——不一致的场景在烘焙段首、预览跳转后会画错），可出静帧。退出码 0 通过 / 1 有问题 / 3 排版未机检（找不到浏览器，可设 `GTRK_CHROME`）。
+- `lay`：按自产身份幂等铺进 beat 轨最上层、补登记素材、窗口记为已做；过期颗粒拒铺；用户在客户端改过的同 id 颗粒不覆盖。
+- `bake`：把已铺的合成颗粒在本机**烘焙成不透明视频**，产物落 `gtrk/assets/composite-bake/<键>.mp4`；输入（槽位画面、字幕、锚点）按**当前时间线**现算。纯本地、零计费。
+  - **浏览器**：优先钉定版本的 chrome-headless-shell（确定性出帧、最快）；没有时退回本机 Chrome / Edge（截图模式，更慢、并发降一档）。**不会静默下载**：`gtrk deps install --browser` 或本命令 `--install-browser` 显式授权才装（约 110 MB）。`GTRK_CHROME` 可指定浏览器。
+  - **并发**：常驻工作页分段并发，缺省 `min(逻辑核数/3, 6)`，`--workers` 覆盖；分段与顺序烤出的画面逐位相同。
+  - **缓存**：键含颗粒、现算输入、素材文件指纹（大小 + 修改时间）、帧率、浏览器版本与编码参数；命中直接复用。改并发不换键。
+  - **帧率**：缺省 = 工程帧率；`--fps` 指定（例如导出 30fps）。帧数 = `ceil(窗口 × fps)`，盖满整个窗口。
+  - **退出码**：0 全部成功（含命中缓存）/ 1 有颗失败（其余照常，逐颗给原因）/ 2 参数或环境错误 / 130 被取消。
+  - **机读**：`--progress jsonl` 逐行输出 `type` 为 `start` / `browser` / `prep` / `progress` / `composite` / `cancelled` / `done` 的事件，相邻两行不超过 1 秒；此模式下**关闭 stdin 即取消**（其它模式不认 stdin）。`--abi` 只输出 `{abi, version, browser, overrides}`，不读工程：`browser.pinned` 是钉定的渲染组件装没装；`overrides` 是本版能烤出的槽位用户覆盖（`fit` / `framing` / `crop` 裁切 / `box` 画中画窗口大小与位置 / `slip_ms` 引用片段前后挪取帧），客户端据此判断工程里的调整能否烤出。`--input <快照> --base <目录>`：以快照为时间线来源（客户端交未保存状态用），相对素材路径与产物落点按 `--base` 解析，快照不回写。
+- `gtrk render` / `gtrk project export` 会先烘焙工程里的合成颗粒：烘焙成功的那段以烘焙视频出画（剪映 / Pr 里是该层位上的一段视频），**时段整段落在合成窗口内的 MG / OV 不再预渲、不计费**；烘焙失败（素材丢失、找不到浏览器等）的那颗按粗剪出画并点名原因，不拦导出。
+
 ### `gtrk project init` / `gtrk audio lay` / `gtrk audio tighten` — 音频驱动工程零件（配音先行）
 
 不从口播毛片、而从**一条配音**起盘的工程入口：先有配音（TTS 合成或自己录的），`project init` 建好 `.gtrk` 工程，之后 `gtrk split --project` 投影拆分照常接成片流水线；`audio lay` 则给任意工程补音频轨（BGM/配乐）；`audio tighten` 收紧配音的句间停顿。
@@ -507,9 +543,15 @@ gtrk project export --gtrk <工程文件> --formats jianying,xml --out <产物
 
 颗粒预渲前会先完成 HTML、路径和缓存预检；预检失败不会提交任何云任务。单颗粒渲染或下载失败会记录在 `result.json`，其余格式继续导出。`--json` 输出单行结果 JSON，人读日志走 stderr。
 
-### `gtrk project background` — 客户端画布背景（模糊底 / 纯色）
+**只在客户端出画的东西**（客户端加的文字、贴纸、图形、特效与画布背景）进不了这次导出的工程文件：工程里有它们时提交前提示一次哪几类、各几个；有文字时指向客户端导出剪映草稿（客户端会把文字带成可编辑字幕）。`result.json` 的 `droppedByContract.clientOnly` 记分类计数，`clientVisualElementCount` 为元素个数（此前误按车道数计）。
+
+**片段底板**（`background_fill`）：剪映 / CapCut 的最底层轨原生承接；其它轨由云端在该片段之下插一条辅助轨——纯色 = 一段同色纯色图，模糊 = 同一段素材（同一时间段、静音、铺满画布）加剪映「模糊」特效。Pr 工程全部轨同样处理，模糊用高斯模糊；FCPXML / OTIO 只做纯色，模糊降级为纯黑并在日志里点名（素材缺尺寸信息、没法铺满时，剪映 / Pr 也降级）。片段自己就铺满画布时不垫底。纯色图引用产物目录里的 `solid-<rrggbb>-<W>x<H>.png`，命令在写工程文件之前把它们写好——**挪动或删除产物目录会让这些纯色图脱机**。`result.json` 的 `backgroundFill` 记录写出的纯色图与降级告警（工程不带底板时整键缺席）。
+
+### `gtrk project background` — 片段底板（模糊底 / 纯色）
+
+缺省给**主轨每个视频 / 图片片段**写片段级底板 `background_fill`（gtrk 契约字段）：片段之下、仅在其时长内铺满画布，模糊 = 片段自己画面铺满后的模糊。典型用途是横屏源进竖屏画布时用模糊底替代黑边。客户端可逐片段或多选批量改；从客户端或 `gtrk project export` 导出的剪映草稿原生承接（主轨是最底层轨），Pr 工程用同一素材铺满加高斯模糊，FCPXML / OTIO 降级为纯黑并提示，本地 `gtrk render` 承接。叠加轨片段与空档不写不改，`struct_meta.client_background` 不动（回执点名它是否仍在）。零计费、不访问云端。
 
-只改 `.gtrk` 的 `struct_meta.client_background` 一个键：客户端打开工程即按它呈现画布背景，可在客户端设置里改回。典型用途是横屏源进竖屏画布时用模糊底替代黑边。零计费、不访问云端；剪映 / PR 工程与本地 `gtrk render` 不承接该设置。
+`--scope canvas` 走旧的画布级写法：只改 `struct_meta.client_background` 一个键（客户端打开即按它呈现画布背景；剪映 / PR 工程与本地渲染不承接）。
 
 ```bash
 gtrk project background --gtrk <工程文件> --blur
@@ -521,10 +563,11 @@ gtrk project background --gtrk <工程文件> --clear
 | 参数 | 作用 |
 |---|---|
 | `--project <dir>` / `--gtrk <path>` | 定位工程，规则同 `project export` |
-| `--blur` | 模糊底：主轨可见画面的模糊副本垫底 |
-| `--intensity <n>` | 配合 `--blur`，0–1000，缺省 200 |
+| `--blur` | 模糊底：片段自己画面铺满后的模糊（画布级 = 主轨画面的模糊副本） |
+| `--intensity <n>` | 配合 `--blur`，0–1000，缺省 200（逐片段须为整数） |
 | `--color <#RRGGBB>` | 纯色底（六位十六进制） |
-| `--clear` | 删除该设置，回到客户端缺省黑底 |
+| `--clear` | 去掉底板（逐片段 = 去掉主轨片段的 `background_fill`；画布级 = 删 `client_background`，回到客户端缺省黑底） |
+| `--scope <clips\|canvas>` | 作用面：`clips`（缺省）主轨逐片段；`canvas` 画布级（旧写法） |
 | `--dry-run` | 只校验并回执将写入的值，不写文件 |
 
 三种模式恰好选一个。写回走原子替换与内容 revision 守卫，其余内容原样保留；值未变时不写盘。`--json` 回执含写前写后 revision。
@@ -654,11 +697,12 @@ gtrk render <gtrk> [-o <out.mp4>] [--crf <n>] [--codec <c>] [--ffmpeg-path <dir>
 
 把 `.gtrk` 当 EDL 用本地 ffmpeg 出成片。**素材一律取本地原片**（`materials[].path`），云端不产成片。
 
-**合成什么**：底轨（`track_index` 最小的非黑底垫轨）+ 全部音源，再按契约 z 序（`track_index` **升序**，越大越靠前）叠**全部可见叠加层**——overlay 视频轨（B-roll 候选 / AI 情景动画回铺）与 `beat_track` 的 MG 颗粒。
+**合成什么**：底轨（`track_index` 最小的非黑底垫轨）+ 全部音源，再按契约 z 序（`track_index` **升序**，越大越靠前）叠**全部可见叠加层**——overlay 视频轨（B-roll 候选 / AI 情景动画回铺）与 `beat_track` 的 MG 颗粒。合成颗粒先在本机烘焙（见 `gtrk composite bake`，零计费），以烘焙视频叠在原层位；被它整段盖住的 MG 不再云渲。
 
 - **可见性只读 `hidden` 字段**（客户端的「小眼睛」）：关掉的轨整条不进片，如实计数告知。渲染器**不猜**哪条该叠。
 - **多条候选轨都可见时成片取最上层**（= 客户端预览所见）。要换，在客户端关小眼睛或删轨。
 - overlay 素材本地缺失（如 B-roll 代理没下全）**只降级不阻断**：该 clip 不叠 + 告警，片子照出。
+- **只在客户端出画的东西不进片**：客户端加的文字（含 `gtrk subtitle lay` 铺的字幕）、贴纸、图形、特效，以及画布背景（`gtrk project background --scope canvas`）。工程里有它们时，渲染前提示一次哪几类、各几个，并指向客户端本地导出；不拦、不改渲染。`--json` 结果恒带 `clientOnly`（`text / sticker / graphic / effect / other` 计数与 `background` 布尔，全零也给）。
 
 **颗粒那一段有计费**（本命令唯一的云端出口）：
 
@@ -685,8 +729,8 @@ gtrk render <gtrk> [-o <out.mp4>] [--crf <n>] [--codec <c>] [--ffmpeg-path <dir>
 - `gtrk install [--api-key … -y --skill-agents codex,cursor --all-agents --copy-skills --skills-dir …]` — 一条命令装全（skill + 配置 + 体检），对标飞书 `lark-cli install`。
 - `gtrk init [--api-key … --api-base … --jianying-draft-dir … -y]` — 仅配置（交互 / 非交互）。
 - `gtrk doctor` — 体检（含 CLI 版本 / 有无新版）。
-- `gtrk deps status` — 查 ffmpeg/ffprobe 与渲染字体的**当前来源**（`--ffmpeg-path` / `~/.gitruck` / 系统 / 缺失）、版本、授权与源码地址。
-- `gtrk deps install [--ffmpeg] [--font] [--force]` — 从同合云镜像安装运行时资产，**已存在则跳过**。
+- `gtrk deps status` — 查 ffmpeg/ffprobe、渲染字体与合成烘焙浏览器的**当前来源**（`--ffmpeg-path` / `~/.gitruck` / 系统 / 缺失）、版本、授权与源码地址。
+- `gtrk deps install [--ffmpeg] [--font] [--browser] [--force]` — 从同合云镜像安装运行时资产，**已存在则跳过**。不带开关装 ffmpeg 与字体；`--browser` 另装合成烘焙用的钉定版本 chrome-headless-shell（约 110 MB，落 `~/.gitruck/browsers`，BSD 许可，来源与源码见分发点 `SOURCE.md`），**只在显式点名时装**。
   - **不会静默自动下载**：任何缺失路径只报错并指向本命令（包体 30–90 MB，且分发物涉及授权，须由用户/agent 显式触发）。
   - 下载一律 https + **sha256 强校验**，校验不过即丢弃、不落地；解包调**系统 tar**（Win10+/macOS/Linux 自带），不引第三方解压依赖。
   - 定位优先级不变：`--ffmpeg-path` → `~/.gitruck/ffmpeg` → 系统 PATH。镜像只填中间那一格，**不越过你自己装的 ffmpeg**。
@@ -699,4 +743,4 @@ gtrk render <gtrk> [-o <out.mp4>] [--crf <n>] [--codec <c>] [--ffmpeg-path <dir>
 
 ### 视频高光发现（内部验收）
 
-`gtrk tool video_highlight <视频> --out <工程目录> --json`：本地224p/4fps无声代理，只上传代理；返回分请求三秒候选。3秒以上、30分钟以内。候选须按制片语义复核；不可跨请求比较分数。服务失败不冒充成功，Vlog可继续Agent素材理解。尚未开放外部收费。
+`gtrk tool video_highlight <视频> --out <工程目录> [--no-audio] --json`：本地生成448p/4fps分析代理（缺省附单声道低码率原声，`--no-audio` 去声），只上传代理、原片不上传；返回分请求三秒候选。3秒以上、30分钟以内。候选须按制片语义复核；不可跨请求比较分数。服务失败不冒充成功，Vlog可继续Agent素材理解。尚未开放外部收费。