@gitruck/cli 1.3.10 → 1.3.12

package/docs/reference.en.md

@@ -61,7 +61,7 @@ Then just say "**cut a version of this talking-head**", or explicitly pick `gtrk
 | ① | `/gtrk-oralcut` | `gtrk oralcut` | Smart talking-head cut → desktop client / Jianying / Premiere projects + transcript |
 | ② | `/gtrk-splitter` | `gtrk split` | Storyboard dispatch → `dispatch.json` (A_ROLL/MG/AI_DRAMA/FILM_BROLL, four lanes) |
 | ③ | `/gtrk-matrix` | `gtrk matrix` | **B-roll base · film/local-footage leg**: lays candidate tracks → **you adjust/choose** (toggle visibility in opencut) |
-| ③ | `/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) |
+| ③ | `/gtrk-ai-drama` | `gtrk ai-drama validate` (check storyboard drafts) · `lay` / `pack` / `swap` (re-insert) | **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`) |
@@ -73,7 +73,7 @@ Then just say "**cut a version of this talking-head**", or explicitly pick `gtrk
 | 📝 | `/gtrk-transcript` | `gtrk transcript` | Local video / voice-over audio → one Markdown file with an agent-written summary, timecoded record and plain text; **not part of the production SOP** |
 | 🧰 | `/gtrk-tools` | `gtrk tool <name>` | The single-shot tool family (image-to-camera-move / image & video matting …) — single request, single result, **not part of the production SOP**, usable standalone at any time |
 | 🎵 | `/gtrk-music-visualizer` | `gtrk music-visualizer` | One song → a spectrum-visualizer video (template + optional background/cover + colour styling), **not part of the production SOP**, used standalone for audience acquisition |
-| 🖼️ | `/gtrk-cover` | (no command, pure authoring) | The two-stage cover workbench: design diagnosis + text-to-image prompts in three sizes and two languages → you generate images on an external platform → an HTML5 typesetting workbench (drag/scroll fine-tuning, one-click export to multiple PNG sizes). Show-specific cover aesthetics are injected through the show config's `style.skills` (`produces:"cover"`); **not part of the production SOP** (it is the "stage zero" companion to distribution) |
+| 🖼️ | `/gtrk-cover` | `gtrk cover embed` (compress background images into the workbench; purely local, zero billing) | The two-stage cover workbench: design diagnosis + text-to-image prompts in three sizes and two languages → you generate images on an external platform → an HTML5 typesetting workbench (drag/scroll fine-tuning, one-click export to multiple PNG sizes). Show-specific cover aesthetics are injected through the show config's `style.skills` (`produces:"cover"`); **not part of the production SOP** (it is the "stage zero" companion to distribution) |
 | 🧭 | `/gtrk-talking-head` | orchestrates `gtrk audio` → `oralcut` → `split` → `matrix` → `mg` → `audio lay` → `subtitle lay` | **Talking-head chain blueprint**: one or more on-camera raw takes → external audio aligned and swapped in, multi-take stitching, rough cut, dispatch, B-roll / MG cards, BGM, subtitles → a client-ready project |
 | 🧭 | `/gtrk-travel-recap` | orchestrates `gtrk tool audio_tts_clone` → `project init` → `split` → `matrix` → `mg` → `audio lay` → `subtitle lay` | **Travel-recap blueprint**: a folder of travel footage → the AI reads the footage, writes a three-act narration, you confirm once → voice-over / project / dispatch / B-roll / cards / BGM / subtitles run unattended → a client-ready project |
 | 🧭 | `/gtrk-live-slicing` | orchestrates `gtrk long2short` (very long replays are segmented first) | **Live-stream slicing blueprint**: a multi-hour replay → segmentation (server-side 2 h hard limit) → topic list confirmed → a batch of per-clip rough-cut projects (gtrk + Jianying + Premiere), split-screen matched to the picture |
@@ -83,7 +83,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 20 `/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, `/gtrk-ref-reading` handles reference reading, and none of the five 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 20 `/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, `/gtrk-ref-reading` handles reference reading, and none of the five belong to the production SOP; `/gtrk-style-maker` is a pure authoring skill (no command), while `/gtrk-ai-drama`·`/gtrk-cover` are mostly authoring and only run commands for mechanical steps such as validation and image embedding. 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.
 
@@ -260,13 +260,13 @@ Look at any local video by timecode or by spoken line: frame grids labelled with
 
 | Subcommand | What it does |
 |---|---|
-| `probe <video>` | Duration, display size (pixel aspect and rotation applied), frame rate and VFR, audio presence |
+| `probe <video \| folder>` | Duration, display size (pixel aspect and rotation applied), frame rate and VFR, audio presence. Given a **folder** it looks at that level only (no recursion, hidden files skipped), picks the audio and video files (`mp4 mov mkv avi webm m4v mts` / `wav mp3 m4a flac aac ogg opus`), probes each and sorts by name: `{mode:"probe-dir", files:[{path, kind, duration, codec, width?, height?, fps?, hasAudio}], skipped:[{path, reason}], truncated?}`; a broken file goes to `skipped` without stopping the rest, and only the first 200 are probed |
 | `lines <transcript>` | One line per utterance `u<id> start–end text`; `--find <phrase>` lists every occurrence with word-level times |
 | `frames <video>` | Single frames by `--at` / `--every` / `--frames` / `--every-frame`; with `--transcript` or `--label` a label band is added below each frame |
 | `tile <video>` | One labelled grid (≤60 cells) |
 | `tiles <video>` | Paginated grids (`--cols × --rows`, default 3×3); `--ranges <json>` visits several intervals; `--every-frame` decodes each interval once and keeps every original frame |
 | `boundaries <video>` | Visual-change candidates (`--rate` default 12, `--threshold` default 0.1, `--min-gap` merges neighbours); with `--transcript` each candidate notes which line it falls on. **Mechanical evidence, not shot detection** |
-| `cut <video>` | Saves an evidence clip (`.mp4/.mov/.mkv`) |
+| `cut <video>` | Saves an evidence clip (`.mp4/.mov/.mkv`, re-encoded). With `--copy` it **stream-copies** instead: no re-encode, seconds for a long raw recording (e.g. splitting raws over 2 hours); the start falls on the last keyframe before `--start`, the receipt's `seconds` is the actual length and its `note` says so; `-o` must keep the source's extension; audio-only sources work too |
 
 ```bash
 gtrk media tiles "reference.mp4" --frames 48 --cols 6 --rows 4 --cell 320 --transcript "reading/transcript.json" -o "reading/evidence/overview"
@@ -277,7 +277,28 @@ gtrk media boundaries "reference.mp4" --rate 4 --threshold 0.12 --transcript "re
 - **Intervals**: `--start/--end` (seconds or `[hh:]mm:ss.mmm`), or `--around <phrase> [--occurrence n] [--padding s]` to locate by the spoken line (needs `--transcript`; a repeated phrase must name its occurrence — `lines --find` lists them).
 - **Transcripts**: the `gtrk transcript --json` output (v1, with word-level times) works as is; `hypit.transcript@1` is also accepted. The transcript must belong to this video — a duration or file-name mismatch prints a warning on stderr.
 - **Labels** (below the picture, so the original captions and graphics stay visible): source seconds · timecode (plus frame number in frame-by-frame mode) · utterance id / the word being spoken with its times / the whole sentence with the current word highlighted. Moments with no timed word are labelled as such, never inferred as silence. Labels are drawn with libass; an ffmpeg without the `ass` filter fails with a pointer to `gtrk deps install --ffmpeg`.
-- **Output**: `-o` is required — nothing lands in the current directory or next to the source; existing paths are never overwritten, and `--force` only replaces this command family's own earlier output. `frames` / `tiles` directories include an `index.json` recording each cell's file, time, word and utterance. Frame-by-frame is capped at 1800 frames per call.
+- **Output**: `-o` is required (except `frames`, which defaults to a new folder under `$GTRK_FRAMES_DIR` when that is set) — nothing lands in the current directory or next to the source; existing paths are never overwritten, and `--force` only replaces this command family's own earlier output. `frames` / `tiles` directories include an `index.json` recording each cell's file, time, word and utterance. Frame-by-frame is capped at 1800 frames per call.
+
+### `gtrk client <subcommand>` — read the project as it is in the editor
+
+When the desktop client has this project open, reads the **live state** over the local bridge (which segment is selected, the playhead, unsaved edits, the picture the editor shows); otherwise reads the project files or renders a frame locally. Both paths return the same shape and `source` says which one answered. **The client is never required**: not installed, not running or showing another project, all three subcommands still exit successfully.
+
+| Subcommand | What it does | `--json` output |
+|---|---|---|
+| `state` | Project summary: clips on every track with their timeline times, project duration; clips on the main track (the one carrying the voice) get a 1-based `no`. Never prints the whole `.gtrk` | `{source:"client"\|"file", project, duration, tracks:[{track, kind, index, main?, clips:[{no?, clip_id, track_st, track_ed, duration, volume?}]}], selection, playhead, viewport}`; the last three are `null` when read from files |
+| `segment --no <N>` | Timeline times and spoken text of main-track segment N (utterances aligned to timeline times exactly as in the `gtrk split` projection view; cut utterances are left out). Out of range exits non-zero and says how many segments there are | `{source, no, clip_id, track_st, track_ed, text}` |
+| `frame --at <sec>` | One composited frame at that timeline moment (`--width` default 768). Rendered by the client it matches the editor; rendered locally it is free and has no MG particles (`note` says so). Past the end it is pinned to the last frame, with a note | `{source:"client"\|"local-render", at, path, width, height, note?}` |
+
+```bash
+gtrk client state --project . --json
+gtrk client segment --no 12 --json
+gtrk client frame --at 31.5 --json          # 31.5 s on the timeline, not 31.5 s into the raw footage
+```
+
+- `--project` defaults to the current directory (`gtrk/project.gtrk` or `project.gtrk`).
+- `frame` writes to `$GTRK_FRAMES_DIR` by default, or `gtrk-frames/<project-path-hash>/frame-<sec>.jpg` under the system temp folder — **never into the project folder** (projects get packed up whole). `-o <file.jpg>` picks the path; an existing file needs `--force`.
+- When the bridge was not used, `--json` carries `bridge:{tried, reason}` (`no_file` / `not_running` / `not_open` / `protocol_too_new` / `protocol_too_old` / `timeout` / …) for troubleshooting; human output says on its first line whether it read files or rendered locally.
+- The bridge: on start the client writes `~/.gitruck/client-bridge.json` (port, token, process id, protocol version) and listens on `127.0.0.1` only; the CLI sends the token and gives each request 10 seconds.
 
 ### `gtrk oralcut <raw>`
 
@@ -329,7 +350,7 @@ Finished cut × transcript projection → beat storyboard. **No positional argum
 >
 > **Dispatch entries carry their own `span:{from,to}`** (the utterance range that entry covers; `overlay` aux entries carry **their own** span, which may be a sub-range of the main beat's). **`track_st/track_ed` are a snapshot taken at projection time** — `gtrk mg` / `gtrk matrix` **re-project on the spot** when consuming them (see below), so after editing the talking-head track you do **not** need to re-run `gtrk split`; only a change to the split doc itself requires that.
 
-### `gtrk patch <move|trim|split|set>` — element-level editing (the only way to edit a project)
+### `gtrk patch <move|trim|split|set|add|replace>` — element-level editing (the only way to edit a project)
 
 Edit the timecode or parameters of a single clip / gap / particle. **Agents must not hand-edit `.gtrk` JSON** —
 a clip carries **two parallel timecode representations** (`clip_st`+`clip_ed` and `clip_st`+`duration`).
@@ -342,6 +363,8 @@ gtrk patch move  --project <dir> --clip c2 --to 5.0
 gtrk patch trim  --project <dir> --clip c2 --out -1s
 gtrk patch split --project <dir> --clip c2 --cut 5.5
 gtrk patch set   --project <dir> --track audio:1 --at 3.0 --volume 0.5
+gtrk patch add     --project <dir> --track video:2 --to 263.733 --candidate <clip_id>   # put a candidate into a gap
+gtrk patch replace --project <dir> --clip <clip_id> --candidate <clip_id>               # swap the source in place
 ```
 
 | Flag | Purpose | Default |
@@ -349,10 +372,16 @@ gtrk patch set   --project <dir> --track audio:1 --at 3.0 --volume 0.5
 | `--project <dir>` / `--gtrk <path>` | Project dir (auto-locates `gtrk/project.gtrk`) or an explicit path | — |
 | `--clip <clip_id>` | Address by id. A video/audio **mirror pair** counts as one editing unit | — |
 | `--track <kind:idx> --at <sec>` | Address by position (`track_st ≤ at < track_ed`). Mutually exclusive with `--clip` | — |
-| `--to <sec\|Nf>` | Target position for `move` | — |
+| `--to <sec\|Nf>` | Target position for `move` / `add` (`add` does not take `--at`: in this command `--at` always means addressing) | — |
+| `--candidate <clip_id>` / `--material <id>` | Source for `add` / `replace`, exactly one: a B-roll candidate (the project candidate pool including neighbours first, then `split/broll-plan.json`) or a video / image material already in `materials` | — |
+| `--beat <id>` | The beat the candidate belongs to (required when the same candidate appears in several beats with different windows) | — |
+| `--from <sec>` | Source in-point for `add` / `replace` (a candidate uses its own source time; external candidates are converted to preview-file time) | Same window as dragging a candidate in the client: centred on `seg.best`, clamped to the material; a material starts at 0 |
+| `--dur <sec\|Nf>` | Duration for `add` | The length of the gap at the target (up to the start of the next element on that track, ending on the same frame number); the candidate's window length when nothing follows |
 | `--in` / `--out` / `--set-in` / `--set-out` / `--slip` | The five `trim` semantics (first two relative, next two absolute, `--slip` shifts only the source window) | — |
 | `--cut <sec\|Nf>` | Cut point for `split`. ⚠️ Distinct from the addressing flag `--at` | — |
-| `--muted` / `--volume <gain>` / `--opaque` | Element-level parameters for `set` (`--volume` is linear gain, not dB) | — |
+| `--muted` / `--no-muted` / `--volume <gain>` / `--opaque` | Element-level parameters for `set` (`--volume` is linear gain, not dB, and must be > 0; `--volume 0` fails with `volume_zero_use_muted` — use `--muted` to silence). Track mute is a master switch: if the clip's track is muted, `--no-muted` fails with `track_muted_master` — unmute the track's speaker in the client | — |
+| `--audio-fade-in <sec\|Nf>` / `--audio-fade-out <sec\|Nf>` | `set`: audio fade-in / fade-out length (a video clip's own sound or an audio-track clip; particles and gaps are rejected); seconds or frames, whole milliseconds; 0 deletes the key; rejected outright if the two sides together exceed the clip duration (never scaled for you); `trim` / `split` maintain fades automatically | — |
+| `--audio-track <index>` | `set`: move an audio clip onto an existing audio track; timing, material and effective volume / mute are kept, overlaps and track settings that cannot be preserved are rejected, an emptied source track is removed; moving a clip that is audible onto a muted track fails with `audio_track_target_muted` | — |
 | `--total <sec\|Nf\|max>` | Top-level duration for `set` (project-scoped op, mutually exclusive with element addressing) | — |
 | `--ops <file\|->` | Batch transaction: read once, compute all, validate all, write once; any failure writes **nothing** | off |
 | `--dry-run` | Compute and validate only, do not write | off |
@@ -368,6 +397,21 @@ gtrk patch set   --project <dir> --track audio:1 --at 3.0 --volume 0.5
 > ⚠️ A gap cannot be addressed with `--clip ""`: the contract lets multiple gaps share that value, so it is
 > not an address. Use `--track/--at` instead.
 
+**`add` / `replace` (putting candidates on the timeline and swapping sources while fine-editing)**:
+
+- When the candidate's material is not yet in `materials`, the preview is downloaded to `assets/broll-preview/` and registered (the same landing code as `gtrk matrix lay`); a registered material is reused, never downloaded again. So right after `matrix source-import` a single `patch add` puts it on the timeline. A failed download writes nothing and exits non-zero (`preview_download_failed`: the candidate URL may have expired — re-run the search / import to refresh); a preview already on disk is kept for next time.
+- `add` only uses existing video tracks; overlapping a non-gap element is refused (`add_overlap`, listing the blockers; when the blocker is a black fill patch it points to `patch replace`); explicit gaps covered by the new clip give way; no ripple, no new tracks. Image candidates are refused (they need a camera-move render first). A source that is too short is clamped with an `add_clamped` warning, never stretched. The new clip's `clip_id` is `<beat>-add-<n>`, it carries no `producer`, and a candidate source gets a solid black `background_fill`.
+- `replace` swaps only `material` and the source window: `clip_id`, track, start, speed, transform, fill, transitions and keyframes stay. If the new material is too short from the in-point, the clip is shortened honestly (`replace_shortened`) — never stretched, start never moved; `producer` is removed so the next `matrix lay` keeps the track as a user track; the old material entry is kept. Mirror pairs (video + mirrored audio) are refused.
+- Every change is first computed and validated with declared values; only then is anything landed. `--dry-run` downloads and writes nothing and the receipt carries `would_download`. The op receipt also carries `source` (candidate / material, `material_id`, `landed`: existing / reused / downloaded / registered) and, for `add`, `gaps_consumed`. `--ops` entries have the same shape: `{"action":"add","track":"video:2","to":263.733,"candidate":"…"}`.
+
+**Preserving and maintaining transitions** (`transition_in` / `transition_out` / `transition_next`; created in the client — the CLI does not produce transitions in this release and adds no flags):
+
+- `split`: the entrance transition stays on the front part; the exit transition and the transition into the next clip go to the back part (`to_clip_id` unchanged); the new cut carries no transition.
+- Every run (a single action or a whole `--ops` batch) maintains the changed tracks once before writing: a dangling `transition_next` is deleted (never re-pointed at the new neighbour), a transition that no longer fits is shortened frame by frame (head first, then tail), and one left under 1 frame is deleted; the receipt's `warnings[]` lists each `transition_dropped` / `transition_shortened`.
+- The granule catalog is fetched at run time from `https://api.ai-mcn.tv:9000/cloud/static/assets/transitions/catalog.json` and cached at `~/.gitruck/cache/transitions/catalog.json` (the shared static-resource cache, also used by the client, refreshed after 24 hours; `composite lay` reads only the cache and never goes online); it is not shipped in the npm package. Offline, with the catalog unavailable, or for a granule missing from it, the transition is kept as is.
+- Pre-existing transition violations unrelated to this edit only go to `preexisting` (`transition_invalid`) and do not block.
+- When a lay command re-lays its own tracks, the number of replaced clips that carried transitions is reported in the log and the `--json` receipt as `replacedTransitionClips`, and each maintenance deletion or shortening is listed in `transitions[]`; `gtrk project export` normalizes the upload body before submitting (the file on disk is untouched; deletions and shortenings go to `result.json` under `transitions`) and prints each cloud `transition_not_carried` warning; `gtrk render` renders hard cuts in this release and counts `transition_not_carried` (`format: "cli_render"`).
+
 ### `gtrk matrix source-import` — Put selected video URLs into a B-roll beat
 
 When the source videos are already known, send them directly to one beat instead of running keyword search:
@@ -381,6 +425,29 @@ Repeat `--url`, or provide one URL per line with `--urls` (1–32 total). Suppor
 
 Each source becomes one low-resolution full-window preview candidate. `source-import` itself does not download the high-resolution source, change the timeline, or create an `online_broll_resolve` task. The client may still open the Trim dialog by double-clicking it, but the selectable range is strictly bounded by that candidate's source window; the pretrim is carried into the timeline when dragged. After the user places the candidate on a track and clicks “Confirm B-roll”, the client submits the selected source window to `online_broll_resolve`; the cloud downloads that high-resolution window and replaces the low-resolution timeline media. `更多外网候选` / `More external candidates` paginates keyword-search tasks only and never treats manually specified sources as another search page.
 
+### `gtrk matrix status` — See where a beat stands in one command (read-only)
+
+```bash
+gtrk matrix status --project <project-dir> --beat B20 --json
+gtrk matrix status --project <project-dir> --beat B20,B21
+gtrk matrix status --project <project-dir> --json          # every B-roll beat, one line each
+```
+
+Accepts only `--project` / `--beat` / `--json`. It calls no cloud endpoint, needs no Key and writes no file; it reads the project on disk, not unsaved edits in the client (that is `gtrk client state`'s job). Here `--beat` may list several beats separated by commas; `matrix source-import`'s `--beat` still takes exactly one.
+
+With `--beat`, each beat reports:
+
+| Field | Content |
+|---|---|
+| `window` | Time window, re-projected on the spot (the same code `gtrk matrix` / `gtrk mg` use); when it falls back to the dispatch snapshot, `source:"dispatch_snapshot"` with a `degraded_reason` |
+| `lane` / `queries` | Lane and dispatch queries |
+| `candidates` | The project candidate pool in compact form: `clip_id`, `type` (online / cloud / local / image), platform and title, score, `seg` window, `review_only`, `preview_landed` (material registered and the file is on disk), `used_by` (clips already using it); no download URLs |
+| `plan` | Total candidates for the beat in `split/broll-plan.json`, how many are not in the pool, and the top 5 by score; `present:false` when there is no plan |
+| `clips` | Clips on every video track that intersect the window: track, `clip_id`, material, start/end, `category` (broll / raw / black_fill / user / a_roll), and whether it carries a producer identity |
+| `gaps` / `black_only` | Spans above the main track with no picture (seams shorter than one frame are ignored); the part of them covered only by black fill patches |
+
+Without `--beat`, one line per B-roll beat: window, candidate count, plan candidate count, covered seconds, number and seconds of gaps. Both forms also carry the project `revision` (usable as `gtrk patch --expected-revision`), `main_track`, the re-projection summary, the strip verdict of each candidate track and `lay.relay_refused` (whether a full re-lay would now be refused with `tracks_edited`). Beats in non-B-roll lanes get only the window, lane and clips. An unknown beat gives `ok:false`, exit code 1, and the list of all known beats.
+
 ### `gtrk matrix` — B-roll retrieval + candidate track laying
 
 **No positional argument = consume the dispatch**: reads the `film_broll` queue from `split/dispatch.json` → dual-endpoint retrieval → produces the candidate list `split/broll-plan.json`, downloads preview proxies, and lays N candidate tracks in the project (open it in opencut and toggle track visibility to compare and choose). **`matrix search "<query>"` = a one-off ad-hoc search** (independent of any dispatch). **`matrix fetch <clip_id...>` = pull raw footage during the fine cut** (project-independent; see below).
@@ -393,6 +460,7 @@ 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 |
+| `--neighbors <n>` | Bring back up to n neighboring shots on each side of a matched concept clip, taken from its source film (0–5, matrix-member endpoint only). Results gain `source_ref` (source title, sequence number, start/end in the source; called `source` in the server docs) and `neighbors[]` (with `offset` / `contiguous` / `hit`). `matrix search` prints the run in source order plus a ready-to-run `gtrk matrix fetch` line; dispatch searches write neighbors into the plan and the project, folded in the client panel, and **never auto-laid**. Ignored with a notice on the public endpoint, `--local` and `--online`; invalid values fail before any request | `0` for `matrix search`; `2` for dispatch searches |
 | `--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 |
@@ -493,7 +561,7 @@ Consumes the `dispatch.mg` dispatch landed by `gtrk split`, laying html-particle
   - **Callback and seek semantics** (`x-callback-driven` / `x-engine-api-override` / `x-raf-interval`, **always non-fatal, never blocks laying**): aligned with the same-named contract section. The engine MUST use `seek(t,false)` / `time(t)` / `progress(p)` when fixing a frame; particles may drive their picture from timeline callbacks but MUST NOT override `tl.seek` or replace `window.__timelines[…]`. These lint items are reminders only and do not require seek shims.
 - **status** (`gtrk mg status --project <dir>`): summarizes the MG pipeline — total beats in `dispatch.mg` / how many source HTML files exist / how many are laid into `.gtrk`, annotating each beat (missing HTML / produced but not laid / laid).
 - **render** (`gtrk mg render <particle.html> --duration <sec> [--out <dir>] [--yes]`): renders a single particle in the cloud, **independent of any project**, into a Jianying-readable qtrle transparent alpha MOV (the fine-cut supplement channel — when the rough cut is already exported to Jianying and one more motion graphic is needed, you can add it without going back to the client app). The chain = lint upfront (envelope = `--duration`; any fatal item is blocked locally, zero submission, zero billing) → **billing-estimate confirmation** (live price lookup; the CLI has no local HTML render engine, so the cloud billed task is the only path for standalone particles; `--yes` skips the prompt) → inline submission to the cloud → `<composition_id>.mov` landed with `task.json`/`result.json` breadcrumbs (recoverable by task_id after a crash). **Scope**: qtrle only for now (`--format webm` is explicitly refused — Jianying cannot read VP8-alpha), particle geometry must be positive integers, and `--duration` is required; the MOV comes out at the particle's declared `data-width` / `data-height` (a 1080×1920 portrait particle yields a 1080×1920 MOV). The output never enters `.gtrk` and never lands in the Jianying draft folder; qtrle is lossless and relatively large, suited to seconds-long particles. Note it shares a word with `gtrk render` (full-video rendering) but is a different thing.
-- **fetch** (`gtrk mg fetch <query|block> [--top 3] [--all]` / `gtrk mg fetch --pick <block> --slot <beat> --project <dir>` / `--pick <block> --as <composition_id> --duration <sec> [--out <dir>]`): the **neutral particle source** from the HyperFrames registry — MG without a show skill. Candidate mode is **offline** (the snapshot ships with the package, pinned to a source commit) and lists 2–3 blocks per query with compat flags and poster links; pick mode fetches the block through three sources in order (our mirror first, then jsdelivr, then GitHub raw; 5 s each, **sha256-verified per source**, nothing is written if all three fail) → eight mechanical rewrites (`<template>` wrap / id rename / drop data-start and fit the slot / sink the solid backdrop into a child / swap GSAP to the contract CDN / swap fonts to a CJK font provable in our runtime mirror / fit duration to the slot / letterbox scaling, never stretch) → `gtrk mg lint` (fatal items block the write) → lands at `<project>/mg/<composition_id>.html`. **A skeleton is not a deliverable**: the returned `editable` (copy / number arrays / colors) MUST be rewritten for the beat and the show before laying. Registry neutral blocks come in one geometry only, 1920×1080 (the size is baked into each block), and `--canvas` with any other size is refused; in slot mode, a project whose `.gtrk` `video_size` is not 16:9 (7% tolerance, so 4K landscape and 17:9 DCI still fetch) is refused before anything is downloaded or written — portrait / square projects use `--source text` (no `.gtrk` or an invalid `video_size` skips the check with a notice); `excluded` blocks are refused, `review` blocks (canvas / house-rule 8 shapes) can be fetched but need a real render check. `GITRUCK_MG_REGISTRY_BASE` overrides the fetch prefix.
+- **fetch** (`gtrk mg fetch <query|block> [--top 3] [--all]` / `gtrk mg fetch --pick <block> --slot <beat> --project <dir>` / `--pick <block> --as <composition_id> --duration <sec> [--out <dir>]`): the **neutral particle source** from the HyperFrames registry — MG without a show skill. Candidate mode is **offline** (no network: it reads the locally cached catalog `~/.gitruck/cache/mg-registry/catalog.json`, or the snapshot that ships with the package; pinned to a source commit) and lists 2–3 blocks per query with compat flags and poster links; pick mode first checks the arguments and the landing spot locally, then refreshes the catalog once (unified static-resource delivery: refreshed every 24 hours, falling back to the cache and then the bundled snapshot), then fetches the block through the mirrors the catalog lists (Gitruck Cloud first, reachable from mainland China, then GitHub raw → jsDelivr fastly → jsDelivr gcore → gh-proxy; 8 s per mirror, **every copy is checked against its sha256 and byte count**, nothing is written if all of them fail; fetched blocks are cached under `~/.gitruck/cache/mg-registry/files/`) → eight mechanical rewrites (`<template>` wrap / id rename / drop data-start and fit the slot / sink the solid backdrop into a child / swap GSAP to the contract CDN / swap fonts to a CJK font provable in our runtime mirror / fit duration to the slot / letterbox scaling, never stretch) → `gtrk mg lint` (fatal items block the write) → lands at `<project>/mg/<composition_id>.html`. **A skeleton is not a deliverable**: the returned `editable` (copy / number arrays / colors) MUST be rewritten for the beat and the show before laying. Registry neutral blocks come in one geometry only, 1920×1080 (the size is baked into each block), and `--canvas` with any other size is refused; in slot mode, a project whose `.gtrk` `video_size` is not 16:9 (7% tolerance, so 4K landscape and 17:9 DCI still fetch) is refused before anything is downloaded or written — portrait / square projects use `--source text` (no `.gtrk` or an invalid `video_size` skips the check with a notice); `excluded` blocks are refused, `review` blocks (canvas / house-rule 8 shapes) can be fetched but need a real render check. Setting `GITRUCK_MG_REGISTRY_BASE` makes it the only mirror root for both the catalog and the blocks (`<root>/catalog.json`, `<root>/files/…`, i.e. the layout of a publish staging folder or the static disk); nothing is written to the local cache.
 
 `--json` output: `{ ok, mode:"lay"|"lint"|"status", … }` (each mode carries its own fields, e.g. `laid` / `skipped` when laying, per-beat status for `status`). Laying mode additionally carries **`track_total`** (how many laid particles currently exist on the track), **`kept`** / **`kept_ids`** (how many are **left over from the previous round** and not re-laid this time, plus their `composition_id` list) and **`removed`** (how many old self-produced particles were stripped this run) — `laid` (this run), `track_total` (total on the track) and `kept` (left over) **must be read together**, and `track_total = laid + kept` always holds. Reading `laid` alone makes "lay 1, strip 20" look identical to "patch in 1", and reading only the first two hides the cost that "a few particles on the track are not from this round" (`kept_ids` and `skipped` overlap: something that failed to land this round is still there from the previous one). When not fully green it also carries a machine-readable **`reason`**: `skipped` (some were not laid) / `empty_queue` (**write-back refused**, the project was not modified, with `refused:true` and `blocked[]`) / `no_project` (project missing, nothing laid). Runs that actually wrote back also carry **`integrity`** (the material-on-disk self-check, identical in name and shape to `gtrk matrix`; see the previous section).
 
@@ -502,13 +570,14 @@ 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)
+### `gtrk composite` — composite layer (plan / review / status / 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 status --project <dir> [--json]
 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>]
@@ -521,6 +590,7 @@ 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. The text signals behind the suggested layout (lists / contrasts / numbers / steps) are recognised in Chinese and English; other languages rely on B-roll density only, and the review sheet says so.
 - `review`: approve / reject / adjust / add windows, written back to the same key; later steps only act on approved windows.
+- `status`: read-only progress summary — window counts per state, `pending` (approved but not yet laid), laid count, one row per window with its span re-projected onto the current timeline via `source_ranges` (empty with a note when the speech was cut). All zeros when there is no composite key.
 - `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`. Write anchor keywords as they appear in the sentence: matching ignores spaces, punctuation and case on both sides, and English matches whole words (`"cold brew"` works as written; `tea` does not match `teas`).
@@ -543,7 +613,7 @@ Project entry points that start from **a voice-over** instead of a talking-head
 |---|---|
 | `gtrk project init --tts-task <task_id>` | **Main path**: references a completed `audio_tts_clone` task — the server hands over the audio and sentence timecodes directly (zero ASR, zero extra billing); the audio download lands in the project's `audio/` |
 | `gtrk project init --audio <voice-over> --transcript <transcript.json>` | **Fallback path**: your own voice-over audio plus its sentence-timecoded transcript as a pair (produced by `gtrk transcript <voice-over> --json`; for TTS-synthesized voice-overs take the main path instead of re-running ASR) |
-| `gtrk audio lay --project <dir> --file <bgm.mp3>` | Appends an audio track to the project; **idempotent same-source replacement** (re-running with the same source replaces instead of piling up tracks; zero-reference protection when stripping the old one); `--volume <0..1>` (default 0.1, bed volume — the contract carries linear gain only, never dB; the client's volume panel shows -20.0, the same scale on both sides), `--offset <ms>` sets the in-point |
+| `gtrk audio lay --project <dir> --file <bgm.mp3>` | Appends an audio track to the project; **idempotent same-source replacement** (re-running with the same source replaces instead of piling up tracks; zero-reference protection when stripping the old one); `--volume <0..1>` (default 0.1, bed volume — the contract carries linear gain only, never dB; the client's volume panel shows -20.0, the same scale on both sides; must be > 0 — `0` does not mute and is rejected, use `gtrk patch set --muted` to silence), `--offset <ms>` sets the in-point |
 | `gtrk audio lay … --beat-align` | **Climax anchoring** (`audio_music_analyze`, billed once): pins the BGM’s emotional peak `H` (the server’s `highlight.time`) onto the cut’s climax `A`; the mapping is always `track_sec = A + (bgm_sec − H)`. **Both sides long enough ⇒ zero tiling** (exactly one clip); only a short side is tiled outward, with seams snapped to downbeats (the two hard track boundaries are cut without snapping). `A` comes from the criterion chain over `struct_meta.split.beats`: elevation → container flip → callback closure → `0.75×total` fallback, and **the CLI reports which rung was used — the fallback is explicitly flagged as a guess**. Without a key / on analysis failure / when the track has no highlight it degrades to no anchoring and the command never fails over it |
 | `gtrk audio lay … --beat-align --climax <track-sec>` | Climax **escape hatch**: always overrides the chain above. Out of range (≤ `--offset` or ≥ the project end) or non-numeric **errors out immediately** rather than falling back silently — an explicitly wrong value should be visible at once. Must be used together with `--beat-align` |
 | `gtrk audio lay … --no-loop` | No tiling: with `--beat-align` it lays only the anchored span and leaves head/tail silence (**the silent seconds are reported**); without `--beat-align` it keeps a single pass instead of looping to fill the project |
@@ -748,12 +818,15 @@ 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 cover embed <workbench.html> [--bg-16x9 <img>] [--bg-4x3 <img>] [--bg-3x4 <img>] -o <out.html>` — embed background images into the cover workbench: each image is compressed to JPEG for its size (long edge 16:9 ≤1280, 4:3 ≤1600, 3:4 ≤1400) and swapped in as base64 for `__BG_16_9__` / `__BG_4_3__` / `__BG_3_4__` (exporting PNG from a `file://` page requires embedded images). `-o` is required and may equal the input; placeholders for sizes without an image are kept and reported; the workbench gets a hint above 600 KB and a warning above 1 MB. Purely local, zero billing, no intermediate image files.
+- `gtrk ai-drama validate <draft-storyboard.md> [...]` — production-side contract check for AI scene storyboards (same rules and output as `scripts/validate-storyboard.mjs` bundled with `/gtrk-ai-drama`): one JSON line per file; exit 0 when all pass, 1 when any fails, 2 when no file is given.
 - `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**.
-  - Fonts land in `~/.gitruck/fonts` and are supplied to burn-in through the ffmpeg `ass` filter's `fontsdir` — **never installed into the system font table, never written to the registry, never requiring administrator rights**.
+  - Fonts come from the font catalog of the unified static-resource delivery (`https://api.ai-mcn.tv:9000/cloud/static/assets/fonts/catalog.json`, the same one the desktop client reads): `--font` installs the subtitle font the catalog names (Source Han Sans CN Bold, `sourcehansanscn-bold.otf`), `--font-family <family…>` installs whole families by `font_id` or Chinese / English family name; every file is checked against its sha256 and byte count, and a failed download errors out without leaving a partial file. An installed font is recognised by its normalised file name (the older `SourceHanSansCN-Bold.otf` counts too); `--force` re-downloads it under the catalog's name.
+  - Fonts land in `~/.gitruck/fonts` (that folder is the cache; no second copy goes to `~/.gitruck/cache/`) and are supplied to burn-in through the ffmpeg `ass` filter's `fontsdir` — **never installed into the system font table, never written to the registry, never requiring administrator rights**.
   - The distributed ffmpeg is a GPLv3 build, and the corresponding source is provided alongside the binaries (see `SOURCE.md` at the distribution point); **downloads carry no additional usage restrictions**.
 - `gtrk upgrade [--check]` — upgrade the CLI to the latest version + refresh skills (config preserved); `--check` only reports.
 - `gtrk skills install [--agents codex,workbuddy,comate,…] [--all] [--copy] [--dir <skills dir>]` — install/refresh agent skills on their own; by default the generic adapter and the gtrk supplement layer detect hosts automatically.

package/docs/reference.md

@@ -67,7 +67,7 @@ gtrk skills install --copy
 | ① | `/gtrk-oralcut` | `gtrk oralcut` | 智能剪口播 → 客户端/剪映/PR 三方工程 + transcript |
 | ② | `/gtrk-splitter` | `gtrk split` | 拆分派单 → `dispatch.json`（A_ROLL/MG/AI_DRAMA/FILM_BROLL 四车道） |
 | ③ | `/gtrk-matrix` | `gtrk matrix` | **B-roll 底轨·影视/本地素材腿**：铺候选轨 → **用户调整/挑选**（opencut 小眼睛切换） |
-| ③ | `/gtrk-ai-drama` | （无命令，纯创作） | **B-roll 底轨·AI 情景片段腿（与 matrix 同阶段，不是最后）**：产四段描述稿（故事背景/角色/分镜/原文，中英分块）→ 任意外部平台出片、手动回铺（产物即描述文本、无机械尾巴，同 `/gtrk-style-maker` 只 skill 无命令） |
+| ③ | `/gtrk-ai-drama` | `gtrk ai-drama validate`（校验分镜稿）· `lay` / `pack` / `swap`（回填） | **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`） |
@@ -79,7 +79,7 @@ gtrk skills install --copy
 | 📝 | `/gtrk-transcript` | `gtrk transcript` | 本地视频/配音音频 → 一个含 Agent 总结、时码记录和纯文本的 Markdown，**不在成片 SOP 序列内** |
 | 🧰 | `/gtrk-tools` | `gtrk tool <name>` | 单点工具族（图转运镜 / 图片·视频抠像…）——单发单收，**不在成片 SOP 序列内**、随时可独立用 |
 | 🎵 | `/gtrk-music-visualizer` | `gtrk music-visualizer` | 一首歌 → 频谱可视化成片（模板 + 可选背景/封面 + 配色样式），**不在成片 SOP 序列内**、独立引流用 |
-| 🖼️ | `/gtrk-cover` | （无命令，纯创作） | 封面工作台两阶段：设计诊断 + 三尺寸中英双版文生图 Prompt → 用户外部平台抽图 → H5 排字工作台（拖拽/滚轮微调、一键导出多尺寸 PNG）。栏目封面审美经栏目配置 `style.skills`（`produces:"cover"`）注入；**不在成片 SOP 序列内**（投放配套的「第 0 阶段」） |
+| 🖼️ | `/gtrk-cover` | `gtrk cover embed`（背景图压缩嵌进工作台，纯本地零计费） | 封面工作台两阶段：设计诊断 + 三尺寸中英双版文生图 Prompt → 用户外部平台抽图 → H5 排字工作台（拖拽/滚轮微调、一键导出多尺寸 PNG）。栏目封面审美经栏目配置 `style.skills`（`produces:"cover"`）注入；**不在成片 SOP 序列内**（投放配套的「第 0 阶段」） |
 | 🧭 | `/gtrk-talking-head` | 编排 `gtrk audio` → `oralcut` → `split` → `matrix` → `mg` → `audio lay` → `subtitle lay` | **口播链图纸**：一条或一组真人出镜毛片 → 外录音轨对齐换轨、多段拼接、粗剪、拆分派单、B-roll/MG 字卡、BGM、字幕 → 客户端可出片工程 |
 | 🧭 | `/gtrk-travel-recap` | 编排 `gtrk tool audio_tts_clone` → `project init` → `split` → `matrix` → `mg` → `audio lay` → `subtitle lay` | **旅拍解说图纸**：旅拍素材夹 → AI 理解素材、写三段式解说稿、一次确认 → 配音/建工程/拆分/B-roll/字卡/BGM/字幕全自动跑完 → 客户端可出片工程 |
 | 🧭 | `/gtrk-live-slicing` | 编排 `gtrk long2short`（超长回放先分段） | **直播切片图纸**：数小时直播回放 → 分段（服务端 2h 硬闸）→ 选题清单确认 → 一批逐 clip 粗剪工程（gtrk + 剪映 + PR），按画面形态配分屏 |
@@ -89,7 +89,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 替你跑命令。
-> 上面 20 个 `/gtrk-X` 都是 **CLI 自带框架 skill**（`gtrk skills install` 装；名单与「给 AI Agent 用」一节、「结构」一节完全一致）——其中 🧭 标记的 7 张是**组合图纸**（一句话跑全链，只编排上面的单命令 skill、本身不新增命令）；`/gtrk-long2short` 独立驱动长剪短，`/gtrk-transcript` 独立驱动视频/音频转文字稿，`/gtrk-tools` 只负责单点工具族，`/gtrk-cover` 管封面，`/gtrk-ref-reading` 管参考片精读，五者都不属成片 SOP 序列；`/gtrk-ai-drama`·`/gtrk-style-maker`·`/gtrk-cover` 是纯创作 skill（无命令）。栏目专属的**视觉风格/生产内容**另由你栏目的生产 skill（`/gtrk-style-maker` 产、经栏目配置 `style.skills` 绑定）供，不写死在这些框架 skill 里。
+> 上面 20 个 `/gtrk-X` 都是 **CLI 自带框架 skill**（`gtrk skills install` 装；名单与「给 AI Agent 用」一节、「结构」一节完全一致）——其中 🧭 标记的 7 张是**组合图纸**（一句话跑全链，只编排上面的单命令 skill、本身不新增命令）；`/gtrk-long2short` 独立驱动长剪短，`/gtrk-transcript` 独立驱动视频/音频转文字稿，`/gtrk-tools` 只负责单点工具族，`/gtrk-cover` 管封面，`/gtrk-ref-reading` 管参考片精读，五者都不属成片 SOP 序列；`/gtrk-style-maker` 是纯创作 skill（无命令），`/gtrk-ai-drama`·`/gtrk-cover` 以创作为主、只有校验 / 嵌图这类机械段走命令。栏目专属的**视觉风格/生产内容**另由你栏目的生产 skill（`/gtrk-style-maker` 产、经栏目配置 `style.skills` 绑定）供，不写死在这些框架 skill 里。
 
 **各车道的具体视觉/内容怎么产**——MG 动态图长什么样、AI 情景动画什么调性——不写死在 CLI 里，而由**你自己栏目的生产 skill** 提供（用 `/gtrk-style-maker` 访谈式产出、留本地）。它们经**栏目配置 `style.skills[].produces`**（值 = 车道名）绑定，`gtrk mg` / `gtrk matrix` 等**通用驱动器**据此消费。**驱动方向 = CLI 驱动栏目 skill**：栏目 skill 只供风格/内容、不含任何「跑哪条命令」的编排职责；框架只认车道与管线接口，画面风格永远归你的栏目。不建栏目就用内置默认，端到端照常跑。
 
@@ -263,13 +263,13 @@ gtrk transcript "D:/素材/采访视频.mp4" --lang zh-CN --out "D:/文字稿/
 
 | 子命令 | 做什么 |
 |---|---|
-| `probe <视频>` | 时长、显示尺寸（计入像素宽高比与旋转）、帧率与 VFR、有无音轨 |
+| `probe <视频 \| 目录>` | 时长、显示尺寸（计入像素宽高比与旋转）、帧率与 VFR、有无音轨。传**目录**时只看这一层（不递归、跳过隐藏文件），挑出音视频（`mp4 mov mkv avi webm m4v mts` / `wav mp3 m4a flac aac ogg opus`）逐个探测、按文件名排序：`{mode:"probe-dir", files:[{path, kind, duration, codec, width?, height?, fps?, hasAudio}], skipped:[{path, reason}], truncated?}`；坏文件进 `skipped` 不中断，超过 200 个只探前 200 个 |
 | `lines <转写稿>` | 逐句 `u<id> 起–止 文本`；`--find <台词>` 列出每处出现与字级起止 |
 | `frames <视频>` | 按 `--at` / `--every` / `--frames` / `--every-frame` 取单帧；带 `--transcript` 或 `--label` 时帧下方加标签 |
 | `tile <视频>` | 一张带标签的网格（≤60 格） |
 | `tiles <视频>` | 分页网格（`--cols × --rows`，缺省 3×3）；`--ranges <json>` 一次看多段；`--every-frame` 每段连续解码、保留每一原始帧 |
 | `boundaries <视频>` | 视觉变化候选（`--rate` 缺省 12、`--threshold` 缺省 0.1、`--min-gap` 合并近邻）；带 `--transcript` 时标注对着哪句话。**是机械证据，不是镜头判定** |
-| `cut <视频>` | 截一段证据片（`.mp4/.mov/.mkv`） |
+| `cut <视频>` | 截一段证据片（`.mp4/.mov/.mkv`，重编码）。带 `--copy` 改为**流拷贝**：不重编码、秒级截长毛片（如超 2 小时的毛片分段），起点落在 `--start` 之前最近的关键帧，回执 `seconds` 是实际时长、`note` 注明关键帧对齐；`-o` 须与源片同扩展名，纯音频也收 |
 
 ```bash
 gtrk media tiles "参考片.mp4" --frames 48 --cols 6 --rows 4 --cell 320 --transcript "精读/transcript.json" -o "精读/evidence/overview"
@@ -280,7 +280,28 @@ gtrk media boundaries "参考片.mp4" --rate 4 --threshold 0.12 --transcript "
 - **区间**：`--start/--end`（秒或 `[hh:]mm:ss.mmm`），或 `--around <台词> [--occurrence n] [--padding s]` 按台词定位（须配 `--transcript`；台词多处出现时必须指定第几处，`lines --find` 可先列出）。
 - **转写稿**：`gtrk transcript --json` 的产物（v1，含字级时码）原生可用，也认 `hypit.transcript@1`。转写稿须是这条视频的——时长 / 文件名对不上会在 stderr 告警。
 - **标签**（画面下方，不遮原片字幕与图形）：源片秒 · 时码（逐帧加帧号）· 句号 / 正在读的字与字级起止 / 所在整句（当前字高亮）。无字时写「此刻无字在读」「句间空隙」，不推断静音。标签用 libass 画，ffmpeg 缺 `ass` 滤镜时报错并指向 `gtrk deps install --ffmpeg`。
-- **落点**：`-o` 必填，不落当前目录或源片旁；已存在不覆盖，`--force` 只覆盖本命令族的旧产物。`frames` / `tiles` 的产物目录含 `index.json`，逐格记录文件、时间、字与句号。逐帧单次上限 1800 帧。
+- **落点**：`-o` 必填（`frames` 例外：设了 `$GTRK_FRAMES_DIR` 时缺省落其下的新目录），不落当前目录或源片旁；已存在不覆盖，`--force` 只覆盖本命令族的旧产物。`frames` / `tiles` 的产物目录含 `index.json`，逐格记录文件、时间、字与句号。逐帧单次上限 1800 帧。
+
+### `gtrk client <子命令>` — 读编辑器里的工程
+
+即剪客户端开着这个工程时，经本机通道读**活状态**（选中哪段、播放头、未存盘的改动、编辑器所见的画面）；没开时读工程文件 / 本地渲染出帧。两条路输出同形，`source` 标明走的是哪条。**不依赖客户端**：没装、没开、开的是别的工程，三个子命令照样成功退出。
+
+| 子命令 | 做什么 | `--json` 输出 |
+|---|---|---|
+| `state` | 工程摘要：各轨片段与轨上时码、工程时长；主轨（口播所在那条）片段带从 1 开始的 `no`。不输出整份 `.gtrk` | `{source:"client"\|"file", project, duration, tracks:[{track, kind, index, main?, clips:[{no?, clip_id, track_st, track_ed, duration, volume?}]}], selection, playhead, viewport}`；读文件时后三项为 `null` |
+| `segment --no <N>` | 主轨第 N 段的轨上时码与口播文字（按转写句与轨上时码对位，同 `gtrk split` 投影视图口径；被剪掉的句不计入）。越界非 0 退出并说明共几段 | `{source, no, clip_id, track_st, track_ed, text}` |
+| `frame --at <秒>` | 时间线这一刻合成后的一帧（`--width` 缺省 768）。客户端渲染时与编辑器所见一致；本地渲染零计费、不含 MG 颗粒（`note` 注明）。超出工程时长钉到末帧并说明 | `{source:"client"\|"local-render", at, path, width, height, note?}` |
+
+```bash
+gtrk client state --project . --json
+gtrk client segment --no 12 --json
+gtrk client frame --at 31.5 --json          # 时间线上的 31.5 秒，不是毛片的 31.5 秒
+```
+
+- `--project` 缺省当前目录（`gtrk/project.gtrk` 或 `project.gtrk`）。
+- `frame` 的图缺省写到 `$GTRK_FRAMES_DIR`，未设时为系统临时目录下 `gtrk-frames/<工程路径哈希>/frame-<秒>.jpg`，**不写进工程目录**（工程会被整体打包带走）；`-o <file.jpg>` 指定落点，已存在须 `--force`。
+- 没走成本机通道时 `--json` 带 `bridge:{tried, reason}`（`no_file` / `not_running` / `not_open` / `protocol_too_new` / `protocol_too_old` / `timeout` / …）便于排障；人读输出首行注明读的是文件还是本地渲染。
+- 本机通道：客户端启动时写 `~/.gitruck/client-bridge.json`（端口、口令、进程号、协议版本），只监听 `127.0.0.1`；CLI 带口令请求、单次 10 秒超时。
 
 ### `gtrk oralcut <毛片>`
 
@@ -332,7 +353,7 @@ gtrk media boundaries "参考片.mp4" --rate 4 --threshold 0.12 --transcript "
 >
 > **派单条目自带 `span:{from,to}`**（该条目对应的 utterance 区间；`overlay` aux 派生条目写 **aux 自己的** span，可为主 beat span 的子区间）。**`track_st/track_ed` 是投影时刻的快照**——`gtrk mg` / `gtrk matrix` 消费时会**现场重投影**（见下），所以改完口播轨**不必**回来重跑 `gtrk split`，只有拆分稿本身变了才要重跑。
 
-### `gtrk patch <move|trim|split|set>` — 元素级编辑（改工程唯一入口）
+### `gtrk patch <move|trim|split|set|add|replace>` — 元素级编辑（改工程唯一入口）
 
 改一个 clip / gap / 颗粒的时码或参数。**agent 勿裸手改 `.gtrk` JSON** —— 片段时码是两套并存的
 （`clip_st`+`clip_ed` 与 `clip_st`+`duration`），改一份不改另一份是**静默失败**：客户端优先读 `clip_ed`，
@@ -343,6 +364,8 @@ gtrk patch move  --project <dir> --clip c2 --to 5.0
 gtrk patch trim  --project <dir> --clip c2 --out -1s
 gtrk patch split --project <dir> --clip c2 --cut 5.5
 gtrk patch set   --project <dir> --track audio:1 --at 3.0 --volume 0.5
+gtrk patch add     --project <dir> --track video:2 --to 263.733 --candidate <clip_id>   # 把候选放上空位
+gtrk patch replace --project <dir> --clip <clip_id> --candidate <clip_id>               # 原地换源
 ```
 
 | 参数 | 作用 | 缺省 |
@@ -350,11 +373,16 @@ gtrk patch set   --project <dir> --track audio:1 --at 3.0 --volume 0.5
 | `--project <dir>` / `--gtrk <path>` | 工程目录（自动定位 `gtrk/project.gtrk`）或直接给路径 | — |
 | `--clip <clip_id>` | 按 id 寻址。命中 video/audio **镜像对**时视为一个编辑单元 | — |
 | `--track <kind:idx> --at <sec>` | 按位置寻址（`track_st ≤ at < track_ed`）。与 `--clip` 互斥 | — |
-| `--to <sec\|Nf>` | `move` 的落点 | — |
+| `--to <sec\|Nf>` | `move` / `add` 的落点（`add` 不收 `--at`：`--at` 在本命令里恒为寻址义） | — |
+| `--candidate <clip_id>` / `--material <id>` | `add` / `replace` 的来源，二选一：B-roll 候选（先查工程候选池含邻居，再查 `split/broll-plan.json`）或 `materials` 里已登记的视频 / 图片素材 | — |
+| `--beat <id>` | 候选所在 beat（同一候选在多个 beat 取窗不同时必给） | — |
+| `--from <sec>` | `add` / `replace` 的源片入点（候选按它自己的源片时间，外网候选自动换成预览文件时间） | 与客户端拖候选上轨同一取窗：以 `seg.best` 居中、钳在素材范围内；素材从 0 |
+| `--dur <sec\|Nf>` | `add` 的时长 | 落点所在空位的长度（到该轨上落点之后第一个元素的起点，出点与它取同一帧号）；后面没有元素时取候选取窗长度 |
 | `--in` / `--out` / `--set-in` / `--set-out` / `--slip` | `trim` 的五种语义（前两个相对、中两个绝对、`--slip` 只换源窗） | — |
 | `--cut <sec\|Nf>` | `split` 的切点。⚠️ 与寻址用的 `--at` 是两个参数 | — |
-| `--muted` / `--volume <gain>` / `--opaque` | `set` 的元素级参数（`--volume` 是线性增益不是 dB） | — |
-| `--audio-track <index>` | `set`：将音频片段转入已有音轨；时码、素材和有效音量/静音不变，拒绝重叠或无法保真的轨级设置，移除变空的原轨 | — |
+| `--muted` / `--no-muted` / `--volume <gain>` / `--opaque` | `set` 的元素级参数（`--volume` 是线性增益不是 dB，须 > 0；`--volume 0` 报 `volume_zero_use_muted`，静音用 `--muted`）。轨静音是总开关：片段所在轨已静音时 `--no-muted` 报 `track_muted_master`，请在客户端点开轨喇叭 | — |
+| `--audio-fade-in <sec\|Nf>` / `--audio-fade-out <sec\|Nf>` | `set`：音频淡入 / 淡出时长（视频轨原声或音频轨片段，颗粒与空档拒收）；秒或帧、整毫秒；设 0 即删键；与另一侧之和超过片段时长即硬拒（不按比例缩）；`trim` / `split` 自动维护淡变 | — |
+| `--audio-track <index>` | `set`：将音频片段转入已有音轨；时码、素材和有效音量/静音不变，拒绝重叠或无法保真的轨级设置，移除变空的原轨；原本出声的片段移进静音轨报 `audio_track_target_muted` | — |
 | `--total <sec\|Nf\|max>` | `set` 的顶层总长（工程级 op，与元素寻址互斥） | — |
 | `--ops <file\|->` | 批量事务：一次读、全算、全校验、一次写；任一条失败**零写** | 关 |
 | `--dry-run` | 只算与校验、不写文件 | 关 |
@@ -367,6 +395,21 @@ gtrk patch set   --project <dir> --track audio:1 --at 3.0 --volume 0.5
 >
 > ⚠️ 空档（gap）不能用 `--clip ""` 寻址：契约允许多个 gap 共享该取值，它不构成地址；用 `--track/--at`。
 
+**`add` / `replace`（精修期放候选上轨、原地换源）**：
+
+- 候选的素材还不在 `materials` 里时，顺手把预览下载到 `assets/broll-preview/` 并登记（与 `gtrk matrix lay` 同一份落地实现）；已登记的直接复用、不重下。所以 `matrix source-import` 之后一条 `patch add` 就能上轨。下载失败零写、非 0（`preview_download_failed`：候选地址可能过期，重跑检索 / 导入刷新）；已落盘的预览留作下次复用。
+- `add` 只放已存在的视频轨；落点与非空档元素重叠即拒（`add_overlap`，列出挡路元素；挡路的是黑底补片时指路 `patch replace`）；落点覆盖到的显式空档让位；不 ripple、不新建轨。图片候选不收（上轨要先生成运镜）。源片不够长时钳短并告警 `add_clamped`，不拉伸。新片段 `clip_id` 为 `<beat>-add-<n>`，不带 `producer`，候选来源带纯黑 `background_fill`。
+- `replace` 只换 `material` 与源窗：`clip_id`、所在轨、起点、倍速、变换、填充、转场、关键帧都不动；新素材从入点起不够长时如实缩短（`replace_shortened`），不拉伸、不挪起点；删去 `producer`，下一次 `matrix lay` 把这条轨当用户轨保留；旧素材条目不删。镜像对（视频 + 镜像音频）不收。
+- 先按自述值把全部改动算一遍、全档校验，通过了才落地；`--dry-run` 不下载、不写文件，回执带 `would_download`。回执的 op 另带 `source`（候选 / 素材、`material_id`、`landed`：existing / reused / downloaded / registered）与 `add` 的 `gaps_consumed`。`--ops` 条目同形：`{"action":"add","track":"video:2","to":263.733,"candidate":"…"}`。
+
+**转场字段的保真与维护**（`transition_in` / `transition_out` / `transition_next`；由客户端产生，CLI 本期不产出、无新参数）：
+
+- `split`：入场转场留前段，出场转场与接下一段的转场归后段（`to_clip_id` 不变），新切口不带转场。
+- 每次运行（单发或整个 `--ops` 批）写回前对有变化的轨统一维护：悬空的 `transition_next` 删除（不改挂新邻居），放不下的按帧缩短（先头后尾），不足 1 帧删除；回执 `warnings[]` 逐条给 `transition_dropped` / `transition_shortened`。
+- 颗粒目录运行时从 `https://api.ai-mcn.tv:9000/cloud/static/assets/transitions/catalog.json` 拉取，缓存 `~/.gitruck/cache/transitions/catalog.json`（统一静态资源缓存，与客户端共用，24 小时重拉；`composite lay` 只读缓存不联网），不随 npm 包分发；离线、目录不可用或颗粒不在目录里时转场原样保留。
+- 与本次编辑无关的存量转场违例只进 `preexisting`（`transition_invalid`），不阻断。
+- 铺轨命令重铺自产轨时，被替换片段带转场的条数在日志与 `--json` 回执里出 `replacedTransitionClips`，维护的删缩逐条列在 `transitions[]`；`gtrk project export` 上行前对上行体规整（盘上不动，删缩写进 `result.json` 的 `transitions`），云端 `transition_not_carried` 告警逐条打出；`gtrk render` 本期按硬切出片并计 `transition_not_carried`（`format: "cli_render"`）。
+
 ### `gtrk matrix source-import` — 指定视频链接进入某个 B-roll beat
 
 当你已经选定视频链接，不需要关键词检索时，可以把它们直接送进指定 beat：
@@ -380,6 +423,29 @@ gtrk matrix source-import --project <工程目录> --beat B07 --urls links.txt -
 
 每个指定来源生成一个整段低清预览候选，`source-import` 本身不会下载高清原片、不会改时间线，也不会创建 `online_broll_resolve`。候选的时间窗就是该来源已下载预览的完整窗口。客户端对它仍可双击打开 Trim 对话框，但裁剪范围严格限制在该候选来源窗口内；预裁剪会随拖拽进入时间线。用户把候选放入轨道并点击“确认 B-roll”后，客户端才把当前源时间窗口提交给 `online_broll_resolve`，由云端下载高清窗口并置换当前低清素材。`更多外网候选` 只对关键词检索任务分页，不会把指定来源任务重复当作搜索结果。
 
+### `gtrk matrix status` — 一条命令看清某个 beat 的现状（只读）
+
+```bash
+gtrk matrix status --project <工程目录> --beat B20 --json
+gtrk matrix status --project <工程目录> --beat B20,B21
+gtrk matrix status --project <工程目录> --json          # 全部 B-roll beat，一行一个概要
+```
+
+只接受 `--project` / `--beat` / `--json`。不调云端、不需要 Key、不写任何文件；读的是盘上工程，不含客户端里未保存的改动（那是 `gtrk client state` 的事）。`--beat` 在这里可以逗号分隔给多个；`matrix source-import` 的 `--beat` 仍只认一个。
+
+带 `--beat` 时每个 beat 给出：
+
+| 字段 | 内容 |
+|---|---|
+| `window` | 时间窗：现场重投影（与 `gtrk matrix` / `gtrk mg` 同一段代码）；退回派单快照时 `source:"dispatch_snapshot"` 并带 `degraded_reason` |
+| `lane` / `queries` | 车道与派单检索词 |
+| `candidates` | 工程候选池，精简字段：`clip_id`、`type`（online / cloud / local / image）、平台与标题、得分、取窗 `seg`、`review_only`、`preview_landed`（素材已登记且文件在盘上）、`used_by`（已用在哪些片段上）；不带下载地址 |
+| `plan` | `split/broll-plan.json` 里该 beat 的候选总数、不在候选池的条数与得分最高 5 条；没有 plan 时 `present:false` |
+| `clips` | 时间窗内各视频轨上的片段：轨、`clip_id`、素材、起止、`category`（broll / raw / black_fill / user / a_roll）、是否带产出方身份 |
+| `gaps` / `black_only` | 主轨之上没有画面的区间（短于一帧的缝不算）；其中只盖着黑底补片的区间 |
+
+不带 `--beat` 时，每个 B-roll beat 一行：时间窗、候选数、plan 候选数、已覆盖秒数、空缺段数与秒数。顶层另给工程 `revision`（可直接作 `gtrk patch --expected-revision`）、`main_track`、重投影摘要、各候选轨的剥离判定与 `lay.relay_refused`（现在整轮重铺会不会被 `tracks_edited` 拒）。非 B-roll 车道的 beat 只给时间窗、车道与轨上片段。beat 不存在时 `ok:false`、退出码 1，并列出全部已知 beat。
+
 ### `gtrk matrix` — B-roll 检索 + 候选铺轨
 
 **无 positional = 派单消费**：读 `split/dispatch.json` 的 `film_broll` 队列 → 双口检索 → 产候选清单 `split/broll-plan.json` + 下载 preview 代理、在工程里平铺 N 条候选轨（opencut 打开即可用轨道小眼睛对比挑选）。**`matrix search "<query>"` = 单条 ad-hoc 检索**（不依赖派单）。**`matrix fetch <clip_id...>` = 精剪期拉原片**（脱离工程，见下）。
@@ -392,6 +458,7 @@ 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`（仅矩阵成员口；覆盖栏目策略） | 栏目策略 |
+| `--neighbors <n>` | 命中的概念素材带回原片前后各 n 条相邻片段（0–5，仅矩阵成员口）。结果多出 `source_ref`（出处名、序号、原片起止；服务端文档里叫 `source`）与 `neighbors[]`（`offset` / `contiguous` / `hit` 等）。`matrix search` 人读输出按原片顺序列出整段，并给出现成的 `gtrk matrix fetch` 命令；派单检索把邻居写进 plan 与工程，客户端面板里折叠，**不参与自动铺轨**。公开口、`--local`、`--online` 带了会提示已忽略；非法值发请求前报错 | `matrix search` 为 `0`；派单检索为 `2` |
 | `--score-floor <f>` | 填充置信度地板：segment score 低于此值不采纳、槽位留空——口播工程里留空处由候选轨**补纯黑片**。调高会收缩取材池，整段铺不满即纯黑压口播，调完先看空洞告警 | `0.2` |
 | `--black-bed` | 旧形态：铺一条纯黑底垫轨、候选片段不带底板（给不认片段底板的老版客户端过渡用）；`--no-black-bed` 已是缺省（无操作） | 关 |
 | `--force-relay` | 候选轨已被你在客户端编辑过时仍强剥重铺（缺省会拒铺并保留那条轨）——**会删掉已确认原片的 `broll-raw-*` 素材登记、盘上原片成孤儿** | 关 |
@@ -521,8 +588,8 @@ gtrk matrix lay --project <目录> [--plan <path>]               # ③ 消费（
   - **回调与 seek 语义**（`x-callback-driven` / `x-engine-api-override` / `x-raf-interval`，**恒非致命、不拦铺轨**）：对齐契约同名一节。引擎定帧 MUST 使用 `seek(t,false)` / `time(t)` / `progress(p)`；颗粒可用时间线回调驱动画面，但不得覆写 `tl.seek` 或替换 `window.__timelines[…]`。三项 lint 只作提醒，不要求作者添加垫片。
 - **status**（`gtrk mg status --project <dir>`）：汇总 MG 流水线——`dispatch.mg` beat 总数 / 已产源 HTML 数 / 已铺进 `.gtrk` 数，并逐 beat 标注（缺 HTML / 已产未铺 / 已铺）。
 - **render**（`gtrk mg render <颗粒.html> --duration <sec> [--out <dir>] [--yes]`）：**脱离工程**把单颗颗粒云渲成剪映可读的 qtrle 透明 alpha MOV（精剪补给口——粗剪导剪映后缺一颗动态图，不回客户端就能补）。链路 = lint 前置（包络 = `--duration`，任一致命项本地拦截、零提交零计费）→ **计费预估确认**（实时查价；CLI 无本地 HTML 渲染引擎，独立颗粒唯一路 = 云渲计费任务，`--yes` 跳过确认）→ 内联提交云端 → `<composition_id>.mov` 落盘 + `task.json`/`result.json` 面包屑（崩溃可凭 task_id 恢复）。**射程**：首发只出 qtrle（`--format webm` 明确拒绝，剪映不吃 VP8-alpha）、颗粒几何须为正整数、`--duration` 必填；MOV 按颗粒声明的 `data-width` / `data-height` 原尺寸出（竖屏 1080×1920 颗粒出 1080×1920 MOV）。产物不进 `.gtrk`、不写剪映草稿目录；qtrle 无损体积偏大，适合秒级颗粒。注意与 `gtrk render`（整片成片渲染）同词不同物。
-- **fetch**（`gtrk mg fetch <检索词|块名> [--top 3] [--all]` / `gtrk mg fetch --pick <块名> --slot <beat> --project <dir>` / `--pick <块名> --as <composition_id> --duration <sec> [--out <dir>]`）：**registry 中性颗粒源**——没建栏目也能出 MG。候选态**离线**（快照随包、钉死来源 commit）按检索词列 2–3 件（含 compat 标记与海报链接）；取块态按三源顺序取块（我方镜像优先、jsdelivr、GitHub raw，每源 5 s，**逐源 sha256 强校验**，三源皆败零落盘）→ 机械改写八条（`<template>` 包裹 / 改 id / 去 data-start 贴坑位 / 实心底下沉子层 / GSAP 源换契约 CDN / 字体换运行时镜像可证的 CJK 字体 / 时长贴坑位 / 信箱缩放不拉伸）→ `gtrk mg lint` 致命项不过不落盘 → 落 `<project>/mg/<composition_id>.html`。**骨架不是成品**：返回的 `editable`（文案 / 数值数组 / 色值）MUST 按 beat 与栏目改写后再铺。registry 中性块只有 1920×1080 一种几何（尺寸写死在块里），`--canvas` 给其它画幅拒绝；派单模式下工程 `.gtrk` 的 `video_size` 比例不是 16:9（容差 7%：4K 横屏与 DCI 17:9 照取）在下载前拒、不落盘，竖屏 / 方形工程走 `--source text`（找不到 `.gtrk` 或 `video_size` 不合法时不比对、照取并提示）；`excluded` 件拒取，`review` 件（canvas / 铁律 8 高危形态）可取但须真渲验收。`GITRUCK_MG_REGISTRY_BASE` 可整体覆盖取块前缀。
-- **fetch --source text**（`gtrk mg fetch --source text <检索词> [--top 3] [--offline]` / `--pick <模板 id> --slot <beat> --project <dir>` / `--pick <模板 id> --as <composition_id> [--out <dir>]`）：**同合云自家的文字特效模板库**——与中性块是两条路。模板是我方 clean-room 重写的**成品**（配色与排版已做过），**不做机械改写、MUST NOT 直接改 HTML**。每颗内嵌产生它的 IR 与双哈希，颗粒因此自带出身证明（三态 `ir` / `detached` / `html`）；手改一个字节就掉成 `detached`，云端改写会拒绝它（`gtrk mg lint` 报非致命的 `x-ir-detached`）。目录走**远端择新、随包兜底**：优先取镜像上的 `catalog.json` 按 `version` 择新并缓存 24h，三源皆不可达时回落随包那份并**明示**（候选态因此永远离线可用）。取块仍逐源 sha256 强校验，三源皆败零落盘。`GITRUCK_TEXT_TEMPLATE_BASE` 可整体覆盖取块与目录前缀。
+- **fetch**（`gtrk mg fetch <检索词|块名> [--top 3] [--all]` / `gtrk mg fetch --pick <块名> --slot <beat> --project <dir>` / `--pick <块名> --as <composition_id> --duration <sec> [--out <dir>]`）：**registry 中性颗粒源**——没建栏目也能出 MG。候选态**离线**（零网络：读本机缓存的目录 `~/.gitruck/cache/mg-registry/catalog.json`，没有就用随包快照；钉死来源 commit）按检索词列 2–3 件（含 compat 标记与海报链接）；取块态先在本地判完参数与落点，再刷新一次目录（统一静态资源下发，24 小时一刷，拉不到用缓存、再用随包），然后按目录里的镜像取块（同合云优先、大陆可达，之后 GitHub raw → jsDelivr fastly → jsDelivr gcore → gh-proxy 回源；每个镜像 8 s，**每份字节都校 sha256 与字节数**，全部失败零落盘；取到的块缓存在 `~/.gitruck/cache/mg-registry/files/`）→ 机械改写八条（`<template>` 包裹 / 改 id / 去 data-start 贴坑位 / 实心底下沉子层 / GSAP 源换契约 CDN / 字体换运行时镜像可证的 CJK 字体 / 时长贴坑位 / 信箱缩放不拉伸）→ `gtrk mg lint` 致命项不过不落盘 → 落 `<project>/mg/<composition_id>.html`。**骨架不是成品**：返回的 `editable`（文案 / 数值数组 / 色值）MUST 按 beat 与栏目改写后再铺。registry 中性块只有 1920×1080 一种几何（尺寸写死在块里），`--canvas` 给其它画幅拒绝；派单模式下工程 `.gtrk` 的 `video_size` 比例不是 16:9（容差 7%：4K 横屏与 DCI 17:9 照取）在下载前拒、不落盘，竖屏 / 方形工程走 `--source text`（找不到 `.gtrk` 或 `video_size` 不合法时不比对、照取并提示）；`excluded` 件拒取，`review` 件（canvas / 铁律 8 高危形态）可取但须真渲验收。`GITRUCK_MG_REGISTRY_BASE` 设了就只用它当目录与取块的镜像根（`<根>/catalog.json`、`<根>/files/…`，即统一发布的暂存包 / 静态盘布局），不写本机缓存。
+- **fetch --source text**（`gtrk mg fetch --source text <检索词> [--top 3] [--offline]` / `--pick <模板 id> --slot <beat> --project <dir>` / `--pick <模板 id> --as <composition_id> [--out <dir>]`）：**同合云自家的文字特效模板库**——与中性块是两条路。模板是我方 clean-room 重写的**成品**（配色与排版已做过），**不做机械改写、MUST NOT 直接改 HTML**。每颗内嵌产生它的 IR 与双哈希，颗粒因此自带出身证明（三态 `ir` / `detached` / `html`）；手改一个字节就掉成 `detached`，云端改写会拒绝它（`gtrk mg lint` 报非致命的 `x-ir-detached`）。目录从同合云取（统一静态资源下发，缓存在与客户端共用的 `~/.gitruck/cache/text-templates/`，24 小时一刷）：拉到即以远端为准（不比版本号），拉不到用本机缓存、再用随包那份并**明示**（候选态因此永远离线可用；`--offline` 只读本机缓存与随包）；旧缓存 `~/.gitruck/text-templates/` 已废弃、不再读。取块每份字节都校 sha256 与字节数，全部失败零落盘。`GITRUCK_TEXT_TEMPLATE_BASE` 设了就只用它当目录与正文的镜像根（`<根>/catalog.json`、`<根>/files/…`），不写本机缓存。
   **落点与时长由命令钉定**：派单模式的 `composition_id` 取自 `dispatch.mg` 那条（`<工程slug>-<beatId>`，不是 `--slot` 收的 beat id），颗粒内嵌 IR 的 `id` 与 `canvas.duration` 被钉到「期望 id」与「坑位包络 + 0.3s 余量」（铁律⑦，贴模板末尾的层跟着钉），再走 `mg compile` 同一条本地编译链重编——产物仍是 `ir` 态，`1-cid-expect` 天然对得上。独立模式 `--as` 同样改写颗粒内部 id，`--duration` 钉时长；`--slot` 与 `--duration` 互斥。两者都没改、且目标画幅就是模板的 1920×1080 时原字节落盘。
   **画幅**：按目标画幅编（IR 住在 1920 参考系，画幅是编译入参）。派单模式缺省取工程 `.gtrk` 的 `video_size`（显式 `--canvas` 与它不符当场拒；找不到 `.gtrk` 时按 1920×1080 编并提示补 `--canvas`），独立模式取 `--canvas`、不给即 1920×1080；`--json` 带 `canvas` 与 `canvas_from`（`flag` / `project` / `reference`）。
 - **compile**（`gtrk mg compile <ir.json | 颗粒.html> [--canvas <WxH>] [--out <dir>] [--remote]`）：把 IR **确定性编译**成颗粒（**0 积分**）。改字、换色、改字号描边阴影、改时长都走它——改 IR 再编，比手改 HTML 干净，且颗粒保持 `ir` 态（云端还能继续调）。缺省在本地编（零请求、断网可用，与服务端编译器逐字节等价）；`--remote` 改走服务端，留给排查与对拍。给颗粒 HTML = 按它内嵌的 IR 重置回模板。`--canvas` 是目标画幅：不给时重置沿用那颗自己的画幅、`.ir.json` 按 1920×1080；`--remote` 把同一画幅交给服务端，产物画幅与请求不符（旧服务端不认画幅）时不落盘。
@@ -535,13 +602,14 @@ 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）
+### `gtrk composite` — 合成层（plan / review / status / 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 status --project <工程> [--json]
 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>]
@@ -554,6 +622,7 @@ gtrk composite bake --abi
 
 - `plan`：候选窗口写进 `.gtrk` 的 `struct_meta.composite`（只动这一个键、原子写回；与 `gtrk split` 写 `struct_meta.split` 同一套做法），客户端大纲 CP 行据此画提案块；另出审稿稿 `composite/plan.md`。重跑保留已做的、不再提用户不要的。「建议画面」用到的文字信号（列举 / 对照 / 数字 / 分点）识别中文与英文；其他语种只看 B-roll 密度，审稿稿里写明未识别。
 - `review`：采纳 / 不要 / 调起止 / 补窗口，写回同一个键；后续步骤只处理已采纳的窗口。
+- `status`：只读汇总合成进度——各状态窗口数、`pending`（已采纳、还没铺轨的段数）、已铺数，逐窗口一行，起止按 `source_ranges` 投影到当刻时间线（口播被剪掉的窗口起止为空并注明）。没有合成键时全零。
 - `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`。锚点关键词照句子原文写：匹配时关键词与句子都忽略空格、标点与大小写，英文按整词（`"cold brew"` 直接写，`tea` 不命中 `teas`）。
@@ -576,7 +645,7 @@ gtrk composite bake --abi
 |---|---|
 | `gtrk project init --tts-task <task_id>` | **主路**：引用一个已完成的 `audio_tts_clone` 配音任务——服务端直取产物音频与句级时码（零 ASR、零额外计费），音频下载落工程 `audio/` |
 | `gtrk project init --audio <配音> --transcript <transcript.json>` | **兜底路**：自备配音音频 + 句级时码稿成对给（时码稿由 `gtrk transcript <配音音频> --json` 产出；TTS 合成的配音请走主路，别重跑 ASR） |
-| `gtrk audio lay --project <目录> --file <bgm.mp3>` | 往工程追加一条音频轨；**同源幂等替换**（同一来源重跑替换不堆轨、零引用保护剥旧）；`--volume <0..1>`（默认 0.1 垫底音量——契约 volume 只写线性增益、不写 dB；客户端音量面板显示 -20.0，两侧同一标尺）、`--offset <ms>` 定入点 |
+| `gtrk audio lay --project <目录> --file <bgm.mp3>` | 往工程追加一条音频轨；**同源幂等替换**（同一来源重跑替换不堆轨、零引用保护剥旧）；`--volume <0..1>`（默认 0.1 垫底音量——契约 volume 只写线性增益、不写 dB；客户端音量面板显示 -20.0，两侧同一标尺；须 > 0——`0` 不会静音、会被拒，静音用 `gtrk patch set --muted`）、`--offset <ms>` 定入点 |
 | `gtrk audio lay … --beat-align` | **高潮点锚定**（`audio_music_analyze`，计费一次）：把 BGM 的情绪峰值 `H`（服务端 `highlight.time`）压到成片高潮点 `A` 上，映射恒为 `轨秒 = A + (BGM 秒 − H)`；**两侧都够长就零平铺**（恰好 1 个 clip），不够长才按小节线平铺补齐、接缝吸附 downbeat（轨的两个硬边界处的截断不吸附）。`A` 取自 `struct_meta.split.beats` 的判据链：升华段 → 容器转折 → 回扣段 → `0.75×全片`兜底，**命中哪一档 CLI 如实报出，兜底档会明示是猜的**。无 Key / 分析失败 / 曲子缺高潮点一律降级为不锚定，命令不失败 |
 | `gtrk audio lay … --beat-align --climax <轨秒>` | 高潮点**逃生门**：一律覆盖上面那条判据链。越界（≤ `--offset` 或 ≥ 工程末尾）或非数**直接报错**，不静默回落 —— 显式给错了值要当场知道。须与 `--beat-align` 同用 |
 | `gtrk audio lay … --no-loop` | 不平铺补齐：开了 `--beat-align` 时只放锚点那一段、头尾留白（**留白秒数如实报出**）；未开 `--beat-align` 时保留单次、不循环叠满至工程末尾 |
@@ -792,12 +861,15 @@ 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 cover embed <工作台.html> [--bg-16x9 <图>] [--bg-4x3 <图>] [--bg-3x4 <图>] -o <输出.html>` — 封面工作台嵌背景图：按尺寸把图压成 JPEG（长边 16:9 ≤1280、4:3 ≤1600、3:4 ≤1400），以 base64 换进 `__BG_16_9__` / `__BG_4_3__` / `__BG_3_4__`（`file://` 下导出 PNG 要求内嵌）。`-o` 必填、可与输入同名；没给图的尺寸占位符保留并提示；工作台超过 600 KB 提示、超过 1 MB 告警。纯本地、零计费，不写中间图片。
+- `gtrk ai-drama validate <候选分镜稿.md> [...]` — AI 情景动画分镜稿的生产端硬契约校验（与 `/gtrk-ai-drama` 随包的 `scripts/validate-storyboard.mjs` 同判据、同输出）：每个文件一行 JSON；全过退出 0、有不过退出 1、没给文件退出 2。
 - `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**。
-  - 字体落 `~/.gitruck/fonts`，烧录时经 ffmpeg `ass` 滤镜的 `fontsdir` 供给——**不装进系统字体表、不写注册表、不要管理员权限**。
+  - 字体走统一静态资源下发的字体目录（`https://api.ai-mcn.tv:9000/cloud/static/assets/fonts/catalog.json`，与客户端同一份）：`--font` 装目录里登记的字幕字体（思源黑体 CN Bold，`sourcehansanscn-bold.otf`），`--font-family <族名…>` 按 `font_id` 或中英族名装整族；每款都校 sha256 与字节数，取不到报错、不落半成品。已装按文件名归一比对（历史命名 `SourceHanSansCN-Bold.otf` 也算），`--force` 才重下并换成目录里的命名。
+  - 字体落 `~/.gitruck/fonts`（落点即缓存，不另存一份到 `~/.gitruck/cache/`），烧录时经 ffmpeg `ass` 滤镜的 `fontsdir` 供给——**不装进系统字体表、不写注册表、不要管理员权限**。
   - 分发的 ffmpeg 为 GPLv3 构建，对应源码与二进制同处提供（见分发点 `SOURCE.md`）；**下载不附加任何使用限制**。
 - `gtrk upgrade [--check]` — 升级 CLI 到最新版 + 刷新 skill（配置保留）；`--check` 只查不装。
 - `gtrk skills install [--agents codex,workbuddy,comate,…] [--all] [--copy] [--dir <skills 目录>]` — 单独安装/刷新 Agent Skills；缺省由通用适配器与 gtrk 补充层自动检测。