@lingjingai/scriptctl 0.34.0 → 0.36.0

package/dist/help-text.js

@@ -6,25 +6,25 @@ const HELP_ENTRIES = [
 Usage
 - scriptctl <query> [flags]             # read a script
 - scriptctl <verb> <address> [flags]    # edit a script
-- scriptctl direct <command> [flags]    # existing material → draft script
-- scriptctl parse [dir] [flags]         # md workspace → script
+- scriptctl ingest --source-path SRC    # txt/md/docx/video → Script v3
 
 Workflows
-- direct    Existing source conversion. Run: scriptctl direct --help
-- parse     Deterministic md assembly. Run: scriptctl parse --help
+- ingest    txt/md/docx/video → Script v3 workspace. Run: scriptctl ingest --help
+- view      Render a workspace script.json to review.html (no model)
+- publish   Validate a workspace script.json + write to the output store
 
 Read
 - summary | episodes | scenes | actions
-- actors | locations | props | assets | states | speakers
+- actors | locations | props | assets | states
 - issues | refs | validate
 
 Write
-- create | add-actor | add-location | add-prop | add-episode | add-speaker
+- create | add-actor | add-location | add-prop | add-episode
 - replace | type | actor | emotion
 - insert | delete | move | split | merge
-- rename | describe | alias | role | worldview | synopsis | extend
-- state-add | state-rename | state-delete | state-change | transition | context
-- dialogue | overlap
+- rename | describe | alias | role | importance | worldview | synopsis | extend
+- state-add | state-rename | state-delete | transition | scene-ref
+- dialogue
 
 Batch
 - do [file|-]       run one CLI verb per line as one transaction
@@ -34,7 +34,7 @@ Tools
 - doctor | update | changelog
 
 Target
-- --script-path FILE | --draft | --remote | --local | --project-group-no NO
+- --script-path FILE | --remote | --local | --project-group-no NO
 - selection where supported: --in SELECTOR plus filters; see command help
 
 Output
@@ -44,7 +44,6 @@ Output
 
 More help
 - scriptctl <command> --help
-- scriptctl direct --help
 - scriptctl patch --schema
 
 Exit codes
@@ -95,325 +94,95 @@ Usage
 - scriptctl doctor [options]
 
 Options
+- --llm-config <path>  LLM task/model routing YAML. Otherwise env, fixed global path, then built-in config.
 - --json            Print machine-readable JSON.
 - --help            Show this help.
 
 Checks
 - Node version
-- optional source-conversion/provider dependencies
-- Anthropic API key presence
+- optional source-conversion/LLM dependencies
+- resolved LLM config, providers, profiles, task routes, and referenced credentials
 - local .env discovery
 - storage backend
 `,
     ],
     [
-        ["direct"],
-        `scriptctl direct converts existing scripts without using ep*.md.
+        ["ingest"],
+        `Convert a txt/md/docx or video source into a Script v3 workspace.
 
-Usage
-- scriptctl direct <command> [options]
-
-Commands
-- init       Build source manifest, episode plan, initial script, validation.
-- run        Re-run one direct stage, e.g. state-binding or metadata.
-- validate   Validate script.initial.json.
-- review     Proofread the draft: curation/issues, or --episode N for source↔extract.
-- export     Export script.initial.json to the final script store.
+Text pipeline: pass1 chunk → pass2 normalize (cheap model emits markdown, parsed
+deterministically) → pass3 merge → compile (provisional script.initial.json +
+evidence) → pass5 govern (asset recall + refine → merge/canonical/prune) →
+script.json (v3-validated). Fully decoupled from direct.
 
-Options
-- --json      Print machine-readable JSON.
-- --help      Show help for a command.
-
-Exit codes
-- 0   success
-- 64  usage or arguments error
-- 66  input file unavailable
-- 70  provider or runtime failure
-- 78  validation failed; agent repair needed
-`,
-    ],
-    [
-        ["direct", "init"],
-        `Build an initial structured script from an existing script file.
+Video pipeline (file or directory of episodes): pass1 Gemini transcribe → pass2
+parse → pass3 anchor-driven cross-episode roster merge + state merge → pass4
+second-pass video correction → pass5 pure-plot speaker audit → pass6 apply +
+converge onto the SAME govern tail as text → identical Script v3 (timestamps ride
+extend.timestamp). Needs GEMINI_API_KEY.
 
 Usage
-- scriptctl direct init --source-path <file> [options]
-
-Required
-- --source-path       Existing source file. Supported: txt, md, docx, xlsx, pdf, json.
+- scriptctl ingest --source-path <file|dir> [options]
 
 Options
-- --workspace-path    Workspace directory. Default: workspace
-- --provider          LLM provider: anthropic, mock(test only). Default: anthropic
-- --model             Provider model. Default: claude-sonnet-4-6-aihubmix
-- --concurrency       Parallel episode extraction workers. Default: 80
-- --batch-mode        Batch planning mode: episode. Default: episode
-- --batch-target-lines Target non-metadata content lines per batch. Default: 36
-- --batch-max-chars   Soft character cap per batch. Default: 1800
-- --batch-min-lines   Minimum content lines before soft cuts. Default: 12
-- --episodes <list>   Force re-run these episodes' batches (comma-separated, e.g. 27 or 1,2,27).
-- --batches <list>    Force re-run these specific batch keys (comma-separated, e.g. bat_0063,bat_0065).
-- --retry-errors      Force re-run every batch that currently has an error.
-- --all               Re-run every batch from scratch.
-- --skip-metadata     Skip metadata extraction and asset description enrichment.
-- --json              Print machine-readable JSON.
-- --help              Show this help.
-
-Progress
-- init prints live status to stderr for humans and agents. TTY stderr refreshes
-  a spinner/progress-bar view with user-facing stage names while work is running,
-  then collapses to the stage summary when it completes. Non-TTY stderr logs one
-  line per update. Status words are colored on TTY stderr; set NO_COLOR=1 to
-  disable color. --json keeps stdout as one final JSON envelope for scripts.
-
-Resume / re-run
-- init is resumable: a batch with a result file is reused, a batch with an error
-  file is sticky (skipped on a plain rerun so a content filter can't loop), a
-  never-run batch runs. Plain rerun only fills never-run batches.
-- Use --episodes / --batches / --retry-errors / --all to force specific units;
-  re-running a unit only touches that unit's files, never other episodes.
-- run "scriptctl direct status" to see what is done / errored / pending.
-
-Writes
-- workspace/source.txt
-- workspace/draft/scriptctl/direct/source_manifest.json
-- workspace/draft/scriptctl/direct/episode_plan.json
-- workspace/draft/scriptctl/direct/batch_plan.json
-- workspace/draft/scriptctl/direct/batch_results/*.json
-- workspace/draft/scriptctl/direct/batch_results/*.error.json
-- workspace/draft/scriptctl/direct/episode_results/*.json
-- workspace/draft/scriptctl/direct/asset_grouping.json
-- workspace/draft/scriptctl/direct/asset_curation.json
-- workspace/draft/scriptctl/direct/state_curation.json
-- workspace/draft/scriptctl/direct/state_binding.json
-- workspace/draft/scriptctl/direct/asset_metadata.json (unless --skip-metadata)
-- workspace/draft/scriptctl/direct/script.initial.json
-- workspace/draft/scriptctl/direct/validation.json
-- workspace/draft/scriptctl/direct/run_state.json
-- workspace/draft/scriptctl/direct/timings.json
-
-Exit codes
-- 0   initial script ready
-- 64  usage or arguments error
-- 66  source file unavailable
-- 70  provider or runtime failure
-- 78  initial script written but agent repair is needed
-`,
-    ],
-    [
-        ["direct", "run"],
-        `Re-run one direct pipeline stage against an existing workspace.
-
-Usage
-- scriptctl direct run <stage> [options]
-
-Stages
-- source-prepare
-- episode-plan
-- episode-titles
-- batch-plan
-- batch-extract
-- episode-merge
-- episode-synopsis
-- script-merge
-- asset-curation
-- state-curation
-- state-binding
-- metadata
-- script-synopsis
-- validate
-
-Options
-- --workspace-path    Workspace directory. Default: workspace
-- --force             Re-run the stage even when its primary artifact exists.
-- --provider          LLM provider for provider-backed stages. Default: anthropic
-- --model             Provider model. Default: claude-sonnet-4-6-aihubmix
-- --episodes <list>   Force re-run these episodes' batches where relevant.
-- --batches <list>    Force re-run these batch keys where relevant.
-- --retry-errors      Force re-run batches with existing error markers.
-- --skip-metadata     When running metadata, delete asset_metadata.json and mark metadata skipped.
-- --json              Print machine-readable JSON.
-- --help              Show this help.
+- --source-path <path>   txt/md/docx file, or a video file/directory. Required.
+- --workspace-path <dir> Workspace root (manifest + pass dirs + products). Default: workspace.
+- --llm-config <path>    LLM config override.
+- --concurrency <n>      Text/merge fanout concurrency. Default: text 80 / video 30.
+- --video-concurrency <n> Video upload+transcribe fanout. Default: 10.
+- --fps <n>              Video sampling fps (>1 unlocks sub-second timecodes). Default: 3.
+- --force                Same-source rerun: clears ingest products and redoes. Cannot switch sources.
 
 Notes
-- Script-mutating stages persist script.initial.json when run standalone:
-  script-merge, asset-curation, state-curation, state-binding, metadata.
-- state-curation writes state_curation.json and compresses asset state catalogs
-  to reusable production visual states before scene-level binding.
-- state-binding writes state_binding.json and updates scene state refs /
-  action state_changes using existing assets and states only.
-
-Exit codes
-- 0   stage completed
-- 64  usage or arguments error
-- 66  required artifact unavailable
-- 70  provider or runtime failure
-- 78  stage wrote diagnostics but agent repair is needed
+- Resumes from per-unit checkpoints (text: chunk markdown; video: pass1/pass4/pass5);
+  a cross-source workspace fails (choose a fresh --workspace-path). Unsupported
+  inputs (pdf/json/xlsx) are refused.
+- script.json validates without synopsis/metadata; enrich later with those commands.
+- Video: run \`scriptctl view\` for the click-to-seek review UI; episode numbering is
+  by filename number (all-or-none; mixed fails).
 `,
     ],
     [
-        ["direct", "status"],
-        `Direct workflow state, derived from disk artifacts (run_state only records internal runtime notes).
+        ["ingest", "status"],
+        `Report ingest progress from the workspace's REAL file state (no model, no store).
+Status is a pure function of the on-disk files — there is no separate state file
+to drift out of sync. This is the authoritative status: the runtime watcher and
+frontend consume \`--json\` instead of re-deriving it.
 
 Usage
-- scriptctl direct status [options]
+- scriptctl ingest status [--workspace-path <dir>] [--json]
 
-Options
-- --workspace-path    Workspace directory. Default: workspace
-- --json              Print machine-readable JSON.
-- --help              Show this help.
-
-Output
-- Overall status, stage status, episode status, and non-success detail ids.
-- Status values: success / running / pending / warning / error / skipped.
-- --json includes overall_status, running_stage, stages, episodes, and batches.
-- status can report an early snapshot as soon as source.txt exists, before planning finishes.
-
-Exit codes
-- 0   required stages complete (warnings may still be present)
-- 78  some required stage errored or pending (re-run with direct init --episodes/--batches/--retry-errors)
-`,
-    ],
-    [
-        ["direct", "validate"],
-        `Validate the current initial structured script.
-
-Usage
-- scriptctl direct validate [options]
-
-Required
-- none
-
-Options
-- --workspace-path    Workspace directory. Default: workspace
-- --script-path       Script JSON to validate. Default: workspace/draft/scriptctl/direct/script.initial.json
-- --json              Print machine-readable JSON.
-- --help              Show this help.
-
-Reads
-- workspace/source.txt
-- workspace/draft/scriptctl/direct/episode_plan.json
-- script.initial.json or --script-path
-
-Writes
-- workspace/draft/scriptctl/direct/validation.json
+State (top-level, folded from the files)
+- empty       No ingest workspace (no manifest.json).
+- incomplete  Started, not finished, no hard error (rerun \`scriptctl ingest\` to resume).
+- failed      Leftover unit error sidecars OR final v3 validation failed.
+- ready       script.json present and v3-validated.
 
-Exit codes
-- 0   validation passed
-- 64  usage or arguments error
-- 66  required artifact unavailable
-- 78  validation failed; agent repair needed
-`,
-    ],
-    [
-        ["direct", "review"],
-        `Proofread the direct draft. Read-only; no state side effects.
-
-Usage
-- scriptctl direct review [options]                 # curation/state-binding decisions + issues
-- scriptctl direct review --episode <n>[,<n>...]    # source.txt ↔ script.initial.json side-by-side per episode
-
-Options
-- --workspace-path    Workspace directory. Default: workspace
-- --episode           Comma-separated episode numbers for source↔extract alignment, e.g. 1 or 1,15,30.
-- --json              Print machine-readable JSON.
-- --help              Show this help.
-
-Notes
-- Generic per-episode / per-asset listings live on the top-level queries
-  (\`scriptctl episodes --draft\`, \`scriptctl assets --draft\`, ...).
-- Fix a wrong extraction by editing the draft with --draft, e.g.
-  \`scriptctl replace ep_001/scn_001#3 --from "…" --to "…" --draft\`.
-
-Reads
-- workspace/draft/scriptctl/direct/script.initial.json
-- workspace/draft/scriptctl/direct/asset_grouping.json
-- workspace/draft/scriptctl/direct/asset_curation.json
-- workspace/draft/scriptctl/direct/state_curation.json
-- workspace/draft/scriptctl/direct/state_binding.json
-- workspace/draft/scriptctl/direct/batch_results/*.error.json
-- workspace/draft/scriptctl/direct/episode_plan.json (--episode)
-- workspace/source.txt (--episode)
+--json payload (.status)
+- { workspace, exists, kind, state, phase, passes[], units, script, validation, errors[], updated }
+  passes[] = per-pass {name, done, unit?{total,done,failed}}; units = primary bar
+  (text: chunks; video: episodes). Liveness (is a run active?) is deliberately
+  NOT here — it can't be read from files; that's the watcher's / agent's concern.
 
-Exit codes
-- 0   review available
-- 64  usage or arguments error
-- 66  required artifact unavailable
+Examples
+- scriptctl ingest status
+- scriptctl ingest status --workspace-path 1_script/workspace --json
 `,
     ],
     [
-        ["direct", "export"],
-        `Export the current initial script to the final script store through Gateway.
+        ["view"],
+        `Render a workspace's script.json into review.html at the workspace root. No model.
 
 Usage
-- scriptctl direct export [options]
-
-Required
-- none
-
-Options
-- --workspace-path    Workspace directory. Default: workspace
-- --project-group-no  Project group no. Default: SANDBOX_PROJECT_GROUP_NO
-- --request-id        Optional idempotency key. Default: scriptctl-direct-export:<script-sha256>
-- --output-path       Deprecated; accepted for old invocations, no local file is written.
-- --force             Export with non-error validation issues only; errors still block.
-- --json              Print machine-readable JSON.
-- --help              Show this help.
-
-Reads
-- workspace/draft/scriptctl/direct/script.initial.json
-- workspace/draft/scriptctl/direct/validation.json
-
-Writes
-- Workbench script-output DB via Gateway
-- workspace/draft/scriptctl/direct/validation.json
-
-Exit codes
-- 0   script exported
-- 64  usage or arguments error
-- 66  required artifact unavailable
-- 78  validation, provider, or agent review blocks export
+- scriptctl view [--workspace-path <dir>]
 `,
     ],
     [
-        ["parse"],
-        `Assemble an agent-authored markdown workspace into a structured script —
-deterministic, no LLM. You write the md (per-episode body + 人物/场景/道具/发声源
-docs); parse turns it into a schema-v2 script.
-
-Two inputs are supported:
-- 正文 + 资产 docs → assemble directly (deterministic, no LLM).
-- 正文 only → first run \`parse <dir> --extract-assets\` to derive the asset docs
-  with an LLM (descriptions / worldview / 主角), review them, then assemble.
+        ["publish"],
+        `Validate a workspace's script.json (v3) and write it to the output store.
 
 Usage
-- scriptctl parse [dir] [options]
-- scriptctl parse [dir] --extract-assets   derive 人物/场景/道具/发声源.md + 元信息.md from body (LLM)
-- scriptctl parse --spec                  print the md grammar parse accepts
-
-Options
-- [dir]               md workspace directory. Default: <workspace>/parse.
-- --workspace-path <path>  Workspace root behind the default md dir (<workspace>/parse). Default: workspace.
-- --md-dir <path>     Point directly at the md workspace root (overrides [dir] / --workspace-path).
-- --episodes-dir <path>  Override the per-episode body directory.
-- --title <title>     Script title when the workspace omits 元信息.md.
-- --extract-assets    Derive asset docs from body-only episodes via an LLM, write them
-                      back for review. Writes md only — no script.json, no publish.
-- --provider <name>   Provider for --extract-assets (anthropic | mock). Default: anthropic.
-- --model <model>     Model for --extract-assets. Default: claude-sonnet-4-6-aihubmix.
-- --force             Overwrite existing asset docs when --extract-assets is set.
-- --publish           Validate then store the assembled script in the DB
-                      (omit to assemble + validate only, no write).
-- --project-group-no <no>  Target project for --publish.
-- --request-id <id>   Idempotency key for --publish.
-
-Notes
-- --extract-assets is a one-time seed step: it writes reviewable 资产 md, then you
-  re-run plain \`parse <dir>\` (deterministic) to assemble script.json. It never
-  publishes. Refuses to overwrite existing asset docs unless --force.
-- Completeness gaps (empty episode/scene, missing description) are warnings, not
-  blockers — same semantics as validate. Only integrity errors block --publish.
-- Run \`scriptctl parse --spec\` first to see the exact md layout and line grammar.
+- scriptctl publish [--workspace-path <dir>] [--remote|--local] [--project-group-no <no>] [--request-id <id>]
 `,
     ],
     // =========================================================================
@@ -421,7 +190,9 @@ Notes
     // =========================================================================
     [
         ["summary"],
-        `Show title and counts (episodes / scenes / actions / actors / locations / props / speakers).
+        `Show title, counts (episodes / scenes / actions / actors / locations / props)
+and the whole-script overview fields when present: worldview (+ worldview_raw),
+style, logline, theme, synopsis, main characters.
 
 Usage
 - scriptctl summary [options]
@@ -433,7 +204,6 @@ Target selection (applies to every query / edit verb)
 - --remote            Read/write the project DB (project group). Pairs with
                       --project-group-no.
 - --local             Read/write the conventional local store (output/ dir).
-- --draft             Edit the direct intermediate draft (script.initial.json).
 - --project-group-no  Project group no (implies remote). Default: SANDBOX_PROJECT_GROUP_NO.
 - (inferred remote)   When SANDBOX_PROJECT_GROUP_NO is set (the sandbox injects it)
                       a bare command auto-targets that project's DB — no flag needed.
@@ -461,7 +231,7 @@ Options
 - --min-chars <n>     Only episodes with total chars >= N.
 - --max-chars <n>     Only episodes with total chars <= N.
 - --format addr       Print only episode ids.
-- --draft / --project-group-no / --workspace-path / --json / --help
+- --project-group-no / --workspace-path / --json / --help
 
 Default output
 - TSV header + one row per episode:
@@ -486,10 +256,12 @@ Options
 - --has-actor <id>    Only scenes whose context references this actor.
 - --has-location <id> Only scenes whose context references this location.
 - --has-prop <id>     Only scenes whose context references this prop.
-- --draft / --project-group-no / --workspace-path / --json / --help
+- --project-group-no / --workspace-path / --json / --help
 
 Output line
-- ep_NNN/scn_NNN [space time] location=loc_NNN(name) actors=... props=... actions=N
+- ep_NNN/scn_NNN [space time] location=loc_NNN(name) actors=... props=... actions=N t=<t_start>..<t_end>
+  t_start / t_end are the first / last action extend.timestamp in the scene
+  (omitted when the scene carries no timestamps).
 
 Examples
 - scriptctl scenes --in ep_007
@@ -500,33 +272,34 @@ Examples
     [
         ["actions"],
         `Search actions across the script (the workhorse for "find where to edit").
-Default output is TSV: addr, type, delivery, speaker, actor, content.
+Default output is TSV: addr, timestamp, type, speaker, actor, emotion, content.
+timestamp is the action's extend.timestamp (episode-local "M:SS"; empty when
+absent) — the anchor for event-level alignment (an event spans first→last ts).
 
 Usage
 - scriptctl actions [options]
 
 Options
 - --in <addr>         Scope to ep_NNN / ep_NNN/scn_NNN / ep_NNN/scn_NNN#idx.
-- --grep <text>       Literal substring (default) or /regex/flags. Matches action.content + lines[].content.
-- --type <type>       dialogue | inner_thought | action.
-- --actor <id>        Actions where this actor speaks (resolves speaker→actor) or is action.actor_id.
-- --speaker <id>      Actions where this speaker appears.
-- --has <kind>        state-changes | transition | lines (filter by structural feature).
+- --grep <text>       Literal substring (default) or /regex/flags. Matches action.content.
+- --type <type>       dialogue | inner_thought | action | transition.
+- --actor <id>        Actions whose inline speaker is this actor (action.speaker.actor_id).
+- --has <kind>        transition | speaker (filter by structural feature).
 - --context <n>       Include N actions before/after each hit (for context windows).
-- --draft / --project-group-no / --workspace-path / --json / --help
+- --project-group-no / --workspace-path / --json / --help
 
 Requires at least one of: --in, --grep, --type, --actor, --speaker, --has. Bare \`scriptctl actions\`
 errors out — dumping every action across all episodes is too large.
 
 Default output
 - TSV header + one row per action:
-  addr type delivery speaker actor content
+  addr timestamp type speaker actor emotion content
 
 Examples
 - scriptctl actions --grep "台下掌声雷动"
 - scriptctl actions --in ep_001 --type dialogue
 - scriptctl actions --grep "金碧辉煌" --context 2
-- scriptctl actions --actor act_001 --has state-changes
+- scriptctl actions --actor act_001 --has speaker
 `,
     ],
     [
@@ -540,10 +313,13 @@ Options
 - --id <actor_id>     Filter to one actor.
 - --name <substr>     Match name substring (case-sensitive).
 - --in <addr>         Restrict to actors referenced under this address (ep/scn/action).
-- --draft / --project-group-no / --workspace-path / --json / --help
+- --counts            Append appearance counts: scenes=N episodes_count=M episodes=<ranges>
+                      (scene-context presence, compacted to episode ranges).
+- --project-group-no / --workspace-path / --json / --help
 
 Examples
 - scriptctl actors --name "陈"
+- scriptctl actors --counts
 - scriptctl actors --in ep_023
 - scriptctl actors --in ep_001/scn_001
 `,
@@ -555,10 +331,12 @@ Examples
 Usage
 - scriptctl locations [options]
 
-Options mirror \`scriptctl actors\`: --id, --name, --in, --project-group-no, etc.
+Options mirror \`scriptctl actors\`: --id, --name, --in, --counts, --project-group-no, etc.
+--counts appends scenes / episode-count / episode ranges of scene-context presence.
 
 Examples
 - scriptctl locations --name "办公室"
+- scriptctl locations --counts
 - scriptctl locations --in ep_007
 `,
     ],
@@ -569,10 +347,12 @@ Examples
 Usage
 - scriptctl props [options]
 
-Options mirror \`scriptctl actors\`: --id, --name, --in, --project-group-no, etc.
+Options mirror \`scriptctl actors\`: --id, --name, --in, --counts, --project-group-no, etc.
+--counts appends scenes / episode-count / episode ranges of scene-context presence.
 
 Examples
 - scriptctl props --name "公文包"
+- scriptctl props --counts
 - scriptctl props --in ep_001/scn_001
 `,
     ],
@@ -588,7 +368,8 @@ Options
 - --id <id>                     Filter by id.
 - --name <substr>               Match name substring.
 - --in <addr>                   Restrict to assets referenced under this address.
-- --draft / --project-group-no / --workspace-path / --json / --help
+- --counts                      Append scene / episode appearance counts per asset.
+- --project-group-no / --workspace-path / --json / --help
 
 Examples
 - scriptctl assets --name "陈"
@@ -597,41 +378,33 @@ Examples
     ],
     [
         ["states"],
-        `List every state on one asset: state_id ↔ name ↔ description.
+        `List every state on one asset: state_id ↔ name ↔ description ↔ episode arc.
 
 This is the read half of the state address space — run it to learn a state's
 id before editing (rename / delete / describe / state-change), instead of
 reading the raw script.json. Duplicate ids/names are flagged inline
 ([DUP_ID] / [DUP_NAME]).
 
+The address accepts a bare id (act_001 / loc_001 / prp_001) or the tagged form
+(actor:act_001) — the kind is inferred from the id prefix in the bare case.
+
+Each state line ends with its episode arc — where the state is bound across the
+script (scene context + action state_changes), compacted to episode ranges:
+  actor:act_001/st_002  石膏轮椅装  desc="…"  episodes=ep_018..ep_021 (4 eps, 4 scenes)
+This is the character's visual arc: which look is active in which episodes.
+A state bound nowhere shows episodes=none.
+
 Usage
 - scriptctl states <asset-addr>
 
 Examples
+- scriptctl states act_001
 - scriptctl states actor:act_001
 - scriptctl states location:loc_003
 
 Then edit by the printed address:
 - scriptctl rename actor:act_001/st_010 "平静（新）"
 - scriptctl delete actor:act_001/st_010 --strategy remove
-`,
-    ],
-    [
-        ["speakers"],
-        `List speakers with source kind / source id.
-
-Usage
-- scriptctl speakers [options]
-
-Options
-- --id <speaker_id>   Filter to one speaker.
-- --name <substr>     Match display_name substring.
-- --kind <kind>       Filter by source_kind (actor / location / prop / system / broadcast / group / other).
-- --draft / --project-group-no / --workspace-path / --json / --help
-
-Examples
-- scriptctl speakers --kind system
-- scriptctl speakers --name "陈"
 `,
     ],
     [
@@ -644,7 +417,7 @@ Usage
 Options
 - --severity <severity>   Filter by severity (error / warning / info / blocking).
 - --code <code>           Filter by issue code (e.g. STATE_NOT_FOUND).
-- --draft / --project-group-no / --workspace-path / --json / --help
+- --project-group-no / --workspace-path / --json / --help
 
 Output line
 - <severity> <code>: <summary> [<location>]
@@ -668,7 +441,7 @@ Address forms
 
 Options
 - --level <scene|action>   Restrict to scene-level or action-level refs only.
-- --draft / --project-group-no / --workspace-path / --json / --help
+- --project-group-no / --workspace-path / --json / --help
 
 Output line
 - <location> [<role>]   (e.g. ep_001/scn_001#3.actor_id [action_actor])
@@ -688,7 +461,7 @@ Usage
 - scriptctl validate [options]
 
 Options
-- --draft / --project-group-no / --workspace-path / --json / --help
+- --project-group-no / --workspace-path / --json / --help
 
 Exit codes
 - 0   passed
@@ -712,9 +485,7 @@ Required
 Options
 - --to                Replacement text. Default: "" (delete the substring).
 - --all               Replace every occurrence in the action. Without it, multiple matches reject.
-- --draft / --project-group-no / --workspace-path / --request-id / --json / --help
-
-Refuses overlap dialogue actions — use \`scriptctl overlap\` to rewrite their lines.
+- --project-group-no / --workspace-path / --request-id / --json / --help
 
 Example
 - scriptctl replace ep_001/scn_001#3 --from "，台下掌声雷动" --to ""
@@ -773,14 +544,13 @@ Usage
 - scriptctl insert <ep> --location <loc_id> [position-flags] [options]                  # scene insert
 
 Action insert (first arg is ep/scn)
-- --type              dialogue / action / inner_thought.
+- --type              dialogue / action / inner_thought / transition.
 - --content           Action content text.
 - --emotion <text>    Optional action.emotion.
-- --actor <id>        Optional action.actor_id.
-- --speaker <id>      Optional action.speaker_id.
+- --actor <id>        Optional: set the line's inline speaker to an actor (action.speaker).
 
 Scene insert (first arg is ep)
-- --location <id>     Required: the scene's primary location.
+- --location <id>     Required: the scene's location.
 - --time <time>       Default: day.
 - --space <space>     Default: interior.
 - --scene-id <id>     Optional explicit scene id (auto-assigned otherwise).
@@ -874,29 +644,6 @@ Examples
     // =========================================================================
     // Edit verbs — state / transition / context on actions+scenes
     // =========================================================================
-    [
-        ["state-change"],
-        `Add or clear a state_change on a specific action.
-
-Usage
-- scriptctl state-change <at> <kind:id> --to <state_id> [--from <state_id>] [--effective <after|before>]
-- scriptctl state-change <at> <kind:id> --clear
-
-Required
-- <at>                Action address.
-- <kind:id>           Asset target (actor/location/prop).
-
-Options
-- --to                Target state_id. Required unless --clear.
-- --from              Optional explicit from-state. Otherwise inferred from prior scene context.
-- --effective         after (default) or before.
-- --clear             Remove the existing state_change for this target on this action.
-
-Examples
-- scriptctl state-change ep_001/scn_001#3 actor:act_001 --to st_shock
-- scriptctl state-change ep_001/scn_001#3 actor:act_001 --clear
-`,
-    ],
     [
         ["transition"],
         `Set or clear an action.transition_prompt (process + contrast for visual generation).
@@ -911,20 +658,22 @@ Examples
 `,
     ],
     [
-        ["context"],
-        `Manage a scene's context.{actors|locations|props} ref.
+        ["scene-ref"],
+        `Manage a scene's cast / props / location ref (v3: scene.actors[] / props[] / location).
 
 Usage
-- scriptctl context <ep/scn> <kind:id> --state <state_id>     # upsert ref + set state
-- scriptctl context <ep/scn> <kind:id> --state none           # upsert ref, no state
-- scriptctl context <ep/scn> <kind:id> --clear                # keep ref, clear state
-- scriptctl context <ep/scn> <kind:id> --remove               # remove ref entirely
+- scriptctl scene-ref <ep/scn> <kind:id> --state <state_id>   # upsert ref + set state
+- scriptctl scene-ref <ep/scn> <kind:id> --state none         # upsert ref, no state
+- scriptctl scene-ref <ep/scn> <kind:id> --clear              # keep ref, clear state
+- scriptctl scene-ref <ep/scn> <kind:id> --remove             # remove ref entirely
 
+kind is actor / location / prop. Location is single-valued per scene (set replaces).
 Exactly one of --state / --clear / --remove must be passed.
 
 Examples
-- scriptctl context ep_001/scn_001 actor:act_001 --state st_calm
-- scriptctl context ep_001/scn_001 actor:act_001 --remove
+- scriptctl scene-ref ep_001/scn_001 actor:act_001 --state st_calm
+- scriptctl scene-ref ep_001/scn_001 location:loc_003 --state none
+- scriptctl scene-ref ep_001/scn_001 actor:act_001 --remove
 `,
     ],
     // =========================================================================
@@ -982,6 +731,21 @@ Only valid on actor:* addresses.
 
 Example
 - scriptctl role actor:act_001 主角
+`,
+    ],
+    [
+        ["importance"],
+        `Set an asset's importance tier. featured = 主角/配角 (downstream gets a render
+asset + state tracking); background = 龙套/背景 (skipped downstream).
+
+Usage
+- scriptctl importance <kind:id> <featured|background>
+
+Valid on actor / location / prop addresses.
+
+Examples
+- scriptctl importance actor:act_002 background
+- scriptctl importance location:loc_001 featured
 `,
     ],
     [
@@ -1033,8 +797,7 @@ Behavior
 - Uses a text-output contract and parser, not tool_use.
 
 Options
-- --provider <name>       openai | anthropic | mock. Default: openai
-- --model <model>         model name for the provider. Default: deepseek-v4-pro-packy
+- --llm-config <path>     task/model routing YAML; built-in route uses the deepseek gateway
 - --concurrency <n>       parallel chunk extraction, default 30
 - --checkpoint <dir>      checkpoint directory, default workspace direct loom dir
 - --overwrite             regenerate existing synopsis fields
@@ -1138,50 +901,18 @@ Examples
     // =========================================================================
     [
         ["dialogue"],
-        `Convert an action to a dialogue and attach speaker(s).
-
-Usage
-- scriptctl dialogue <at> --speakers <id1[,id2,...]> [--delivery <single|simultaneous|group>]
-
-Speakers can be a comma-separated list. Delivery defaults to single (1 speaker) or simultaneous (>1).
-
-Examples
-- scriptctl dialogue ep_001/scn_001#3 --speakers spk_chenmu
-- scriptctl dialogue ep_001/scn_001#3 --speakers spk_a,spk_b --delivery simultaneous
-`,
-    ],
-    [
-        ["overlap"],
-        `Set overlapping dialogue (multiple speakers each with their own line) on an action.
+        `Set a dialogue line's inline speaker (v3: a single speaker per line). Also flips
+the action to type=dialogue.
 
 Usage
-- scriptctl overlap <at> --line "<speaker_id>:<content>" [--line ...]
-
-Each --line associates one speaker with one line of dialogue. Repeatable.
+- scriptctl dialogue <at> --actor <actor_id>                      # an actor speaks
+- scriptctl dialogue <at> --kind <system|broadcast|offscreen|group> [--label <text>]
 
-Example
-- scriptctl overlap ep_001/scn_001#3 --line "spk_chenmu:你好" --line "spk_other:hi"
-`,
-    ],
-    [
-        ["add-speaker"],
-        `Register a new speaker entity.
-
-Usage
-- scriptctl add-speaker --kind <kind> --name <display_name> [options]
-
-Required
-- --kind              actor | location | prop | system | broadcast | group | other.
-- --name              Display name.
-
-Options
-- --source-id <id>    For kind=actor/location/prop, points at the asset.
-- --voice-desc <text> Free-form voice description.
-- --speaker-id <id>   Optional explicit id (auto-assigned otherwise).
+Pass exactly one of --actor (an actor) or --kind (a non-actor source).
 
 Examples
-- scriptctl add-speaker --kind actor --name "陈默" --source-id act_001
-- scriptctl add-speaker --kind system --name "广播员"
+- scriptctl dialogue ep_001/scn_001#3 --actor act_001
+- scriptctl dialogue ep_001/scn_001#3 --kind broadcast --label 广播
 `,
     ],
     // =========================================================================
@@ -1210,7 +941,7 @@ Use \`scriptctl patch --schema\` to see every supported op + its required fields
 Options
 - --schema [<op>]     Dump op schema (JSON) instead of applying. With <op>, dump just that op.
 - --dry-run           Apply to an in-memory copy, run validate, do NOT write to gateway.
-- --draft / --project-group-no / --workspace-path / --request-id / --json / --help
+- --project-group-no / --workspace-path / --request-id / --json / --help
 
 Examples
 - scriptctl patch changes.json