@lingjingai/scriptctl 0.5.0 → 0.6.1

package/dist/help-text.js

@@ -1,32 +1,74 @@
 const HELP_ENTRIES = [
     [
         [],
-        `scriptctl controls script-stage deterministic tools.
+        `scriptctl — 剧本阶段统一 CLI（0.6.0 扁平 namespace）
 
 Usage
-- scriptctl direct <command> [options]
-- scriptctl script <command> [options]
-- scriptctl episode <command> [options]
+- scriptctl <verb> <address> [flags]      # 编辑（多态 verb 按 address 格式分发）
+- scriptctl <plural-noun> [flags]         # 查询
+- scriptctl direct <command> [flags]      # 直转 workflow
+- scriptctl write <command> [flags]       # 逐集写作 workflow
 
-Commands
-- doctor            Check CLI runtime, dependencies, env, and storage.
+Workflow groups
 - direct init       Build the initial direct-conversion script.
 - direct validate   Validate the current initial script.
 - direct inspect    Inspect episodes, assets, or issues.
 - direct export     Store the final script through Gateway after validation.
-- script inspect    Inspect the current final script.
-- script validate   Validate the current final script.
-- script patch      Apply a batch patch to the current final script.
-- script state      Edit reusable asset states.
-- script context    Edit scene initial state.
-- script action     Edit action state changes and transition prompts.
-- script speaker    Manage speakers.
-- script dialogue   Edit multi-speaker dialogue.
-- episode init      Scaffold workspace/episodes/ + a meta.json template + gateway env preflight.
-- episode draft     Draft + lint + assemble-validate + auto-commit a single episode.
-- episode batch     Draft a range of episodes in one go.
-- episode workspace List per-episode draft state in the \`episode\` from-scratch workspace.
-- episode publish   Assemble all drafted episodes and upload to gateway (--dry-run available).
+- write init        Scaffold workspace/episodes/ + meta.json template.
+- write draft <n>   Draft + lint + assemble-validate + auto-commit a single episode.
+- write batch       Draft a range of episodes in one go.
+- write workspace   List per-episode draft state in the from-scratch workspace.
+- write merge       Local assembly: committed episodes → script.json + receipt.
+- write push        Upload the merge artifact to gateway.
+- write spec        Print the spec-md grammar.
+
+Query (plural-noun)
+- summary           title + counts of episodes / scenes / actions / assets / speakers
+- episodes          per-episode line: scenes, actions, chars
+- scenes            per-scene line with asset names; filters: --in / --has-actor / --has-location / --has-prop
+- actions           per-action line; filters: --in / --grep / --type / --actor / --speaker / --has / --context
+- actors / locations / props / assets / speakers   asset queries (kind-scoped or unified)
+- issues            current validation issues
+- refs <addr>       reverse lookup: state / asset / speaker → reference sites
+- validate          Validate the current final script.
+
+Edit content
+- replace <at> --from X [--to X] [--all]                literal substring replace in action.content
+- type <at> <dialogue|action|inner_thought>             action.type.set
+- actor <at> <actor_id|none>                            action.actor.set
+
+Edit structure (multipolar; address format dispatches)
+- insert <addr> ...                                     action.insert (ep/scn) or scene.insert (ep)
+- delete <addr> [--strategy replace|remove] [--force]   action / scene / asset / speaker
+- move <addr> <to> [--at <idx>]                         action / scene
+- split <ep/scn> --at <idx>                             split scene at action index
+- merge <src> --into <dst>                              asset.merge or scene.merge
+
+Edit asset metadata
+- rename <addr> <name>
+- describe <addr> <text>                                asset or state (addr with /state_id)
+- alias <addr> [--add X --remove Y]
+- role <actor:id> <主角|配角>
+- worldview <value>
+
+State / transition / context
+- state-add <addr> <name> [--description X] [--state-id X]
+- state-rename <addr> <name>
+- state-delete <addr> --strategy <replace|remove> [--replacement X]
+- state-change <at> <kind:id> --to <state> | --clear [--from X] [--effective X]
+- transition <at> <kind:id> --process X --contrast Y | --clear
+- context <ep/scn> <kind:id> --state X | --clear | --remove
+
+Dialogue / speaker
+- dialogue <at> --speakers id1,id2 [--delivery X]
+- overlap <at> --line "spk:text" [--line ...]
+- add-speaker --kind X --name Y [--source-id X] [--voice-desc X] [--speaker-id X]
+
+Patch (batch transaction)
+- patch <file> [--schema] [--dry-run]                   apply multi-op JSON; positional file
+
+Doctor
+- doctor            Check CLI runtime, dependencies, env, and storage.
 
 Options
 - --json            Print machine-readable JSON instead of agent text.
@@ -226,206 +268,7 @@ Exit codes
 `,
     ],
     [
-        ["script"],
-        `scriptctl script edits the current final script through Gateway.
-
-Usage
-- scriptctl script <command> [options]
-
-Commands
-- inspect      Inspect the current final script.
-- validate     Validate the current final script.
-- patch        Apply a JSON patch file.
-- state        Add, rename, describe, reference-check, or delete states.
-- context      Set or clear scene initial state.
-- action       Add/remove state changes and transition prompts.
-- speaker      Add non-human or actor-linked speakers.
-- dialogue     Set simultaneous or overlapping dialogue.
-
-Options
-- --project-group-no  Project group no. Default: SANDBOX_PROJECT_GROUP_NO
-- --script-path    Explicit local intermediate script JSON path. Omit to use DB-backed script-output.
-- --workspace-path Workspace directory for validation reports. Default: workspace
-- --request-id     Write commands only: optional idempotency key.
-- --json           Print machine-readable JSON.
-- --help           Show help for a command.
-`,
-    ],
-    [
-        ["script", "inspect"],
-        `Inspect the current final script. Read-only.
-
-Usage
-- scriptctl script inspect [options]
-
-Targets
-- summary             title + counts of episodes / scenes / actions / actors / locations / props / speakers
-- episode             per-episode line: scenes, actions, chars (dialogue / action split), title
-- action              per-action line: address + type + speaker + content. Requires --id or --grep.
-- asset               actors / locations / props with state counts
-- speaker             speakers with source kind and id
-- issue               current validation issues
-
-Options
-- --project-group-no  Project group no. Default: SANDBOX_PROJECT_GROUP_NO
-- --script-path       Explicit local intermediate script JSON path. Omit to use DB-backed script-output.
-- --workspace-path    Workspace directory. Default: workspace
-- --target            One of: summary, episode, action, asset, speaker, issue. Default: summary
-- --id                Item id filter. For target=episode: episode_id. For target=action:
-                      ep_001 (whole episode) / ep_001/scn_001 (whole scene) / ep_001/scn_001#3 (single action).
-                      For asset/speaker/issue: actor_id / speaker_id / issue code.
-- --grep              (target=action only) Literal substring filter on action content / dialogue lines.
-- --min-chars         (target=episode only) Only list episodes with total chars >= N.
-- --max-chars         (target=episode only) Only list episodes with total chars <= N.
-- --json              Print machine-readable JSON. Avoid unless you actually need to parse;
-                      the default agent-text output is shorter and more readable.
-- --help              Show this help.
-
-Examples
-- "Which episodes exceed 1000 chars?"
-    scriptctl script inspect --target episode --min-chars 1000
-- "Find the action that says 台下掌声雷动:"
-    scriptctl script inspect --target action --grep "台下掌声雷动"
-- "Dump every action in episode 1:"
-    scriptctl script inspect --target action --id ep_001
-`,
-    ],
-    [
-        ["script", "validate"],
-        `Validate the current final script.
-
-Usage
-- scriptctl script validate [options]
-
-Options
-- --project-group-no  Project group no. Default: SANDBOX_PROJECT_GROUP_NO
-- --script-path       Explicit local intermediate script JSON path. Omit to use DB-backed script-output.
-- --workspace-path    Workspace directory. Default: workspace
-- --json              Print machine-readable JSON.
-- --help              Show this help.
-`,
-    ],
-    [
-        ["script", "patch"],
-        `Apply a batch patch to the current final script.
-
-Usage
-- scriptctl script patch --patch <patch.json> [options]
-
-Required
-- --patch             JSON patch file with ops[] or operations[].
-
-Options
-- --project-group-no  Project group no. Default: SANDBOX_PROJECT_GROUP_NO
-- --request-id        Optional idempotency key for this write.
-- --script-path       Explicit local intermediate script JSON path. Omit to use DB-backed script-output.
-- --workspace-path    Workspace directory. Default: workspace
-- --json              Print machine-readable JSON.
-- --help              Show this help.
-`,
-    ],
-    [
-        ["script", "state"],
-        `Edit reusable asset states.
-
-Usage
-- scriptctl script state add <actor:act_001|location:loc_001|prop:prp_001> --name <name> [--description <text>] [--state-id <id>]
-- scriptctl script state rename <actor:act_001/st_001> --name <name>
-- scriptctl script state describe <actor:act_001/st_001> --description <text>
-- scriptctl script state refs <actor:act_001/st_001>
-- scriptctl script state delete-plan <actor:act_001/st_001>
-- scriptctl script state delete-apply <actor:act_001/st_001> --strategy <replace|remove> [--replacement <state_id>]
-
-Options
-- --project-group-no  Project group no. Default: SANDBOX_PROJECT_GROUP_NO
-- --request-id        Write commands only: optional idempotency key.
-- --script-path       Explicit local intermediate script JSON path. Omit to use DB-backed script-output.
-- --workspace-path    Workspace directory. Default: workspace
-- --json              Print machine-readable JSON.
-- --help              Show this help.
-`,
-    ],
-    [
-        ["script", "context"],
-        `Edit scene initial state.
-
-Usage
-- scriptctl script context set <ep_001/scn_001> <actor:act_001|location:loc_001|prop:prp_001> --state <state_id>
-- scriptctl script context clear <ep_001/scn_001> <actor:act_001|location:loc_001|prop:prp_001>
-
-Options
-- --project-group-no  Project group no. Default: SANDBOX_PROJECT_GROUP_NO
-- --request-id        Optional idempotency key for this write.
-- --script-path       Explicit local intermediate script JSON path. Omit to use DB-backed script-output.
-- --workspace-path    Workspace directory. Default: workspace
-- --json              Print machine-readable JSON.
-- --help              Show this help.
-`,
-    ],
-    [
-        ["script", "action"],
-        `Edit action state changes, transition prompts, and action content text.
-
-Usage
-- scriptctl script action state-change <ep_001/scn_001#4> <actor:act_001|location:loc_001|prop:prp_001> --to <state_id> [--from <state_id>] [--effective <after|before>]
-- scriptctl script action state-remove <ep_001/scn_001#4> <actor:act_001|location:loc_001|prop:prp_001>
-- scriptctl script action transition-set <ep_001/scn_001#4> <actor:act_001|location:loc_001|prop:prp_001> --process <text> --contrast <text>
-- scriptctl script action transition-clear <ep_001/scn_001#4> <actor:act_001|location:loc_001|prop:prp_001>
-- scriptctl script action content-replace <ep_001/scn_001#4> --from <text> [--to <text>] [--all]
-
-Options
-- --project-group-no  Project group no. Default: SANDBOX_PROJECT_GROUP_NO
-- --request-id        Optional idempotency key for this write.
-- --script-path       Explicit local intermediate script JSON path. Omit to use DB-backed script-output.
-- --workspace-path    Workspace directory. Default: workspace
-- --json              Print machine-readable JSON.
-- --help              Show this help.
-
-content-replace
-- Literal substring replace inside action.content. Refuses ambiguous matches
-  (substring appears more than once) unless --all is passed. Refuses overlap
-  dialogue actions — use \`script dialogue overlap\` to rewrite their lines.
-- --from is required and must be non-empty. --to defaults to "" (delete).
-- Example: delete a trailing clause that no longer fits the scene:
-    scriptctl script action content-replace ep_001/scn_001#3 --from "，台下掌声雷动" --to ""
-`,
-    ],
-    [
-        ["script", "speaker"],
-        `Manage speakers.
-
-Usage
-- scriptctl script speaker add --kind <actor|location|prop|system|broadcast|group|other> --name <display_name> [--source-id <id>] [--voice-desc <text>]
-
-Options
-- --project-group-no  Project group no. Default: SANDBOX_PROJECT_GROUP_NO
-- --request-id        Optional idempotency key for this write.
-- --script-path       Explicit local intermediate script JSON path. Omit to use DB-backed script-output.
-- --workspace-path    Workspace directory. Default: workspace
-- --speaker-id        Optional explicit speaker_id.
-- --json              Print machine-readable JSON.
-- --help              Show this help.
-`,
-    ],
-    [
-        ["script", "dialogue"],
-        `Edit multi-speaker dialogue.
-
-Usage
-- scriptctl script dialogue speakers <ep_001/scn_001#5> --speaker <speaker_id> [--speaker <speaker_id>...] --delivery <single|simultaneous|group>
-- scriptctl script dialogue overlap <ep_001/scn_001#6> --line <speaker_id:content> [--line <speaker_id:content>...]
-
-Options
-- --project-group-no  Project group no. Default: SANDBOX_PROJECT_GROUP_NO
-- --request-id        Optional idempotency key for this write.
-- --script-path       Explicit local intermediate script JSON path. Omit to use DB-backed script-output.
-- --workspace-path    Workspace directory. Default: workspace
-- --json              Print machine-readable JSON.
-- --help              Show this help.
-`,
-    ],
-    [
-        ["episode"],
+        ["write"],
         `scriptctl episode drives per-episode incremental script production for the creative
 mainline (灵感线 / 小说线 / 原创线). The full per-project loop:
 
@@ -480,7 +323,7 @@ merge (after any source edit) then push.
 `,
     ],
     [
-        ["episode", "init"],
+        ["write", "init"],
         `Scaffold the episode workspace. Creates <workspace>/episodes/ and writes a
 meta.json template with TODO placeholders for title / worldview / style.
 
@@ -499,7 +342,7 @@ Exit code: 0 always (skipped or written).
 `,
     ],
     [
-        ["episode", "draft"],
+        ["write", "draft"],
         `Draft + lint + assemble-validate + auto-commit episode <n> in one command.
 
 The full pipeline for one episode:
@@ -576,7 +419,7 @@ Exit codes
 `,
     ],
     [
-        ["episode", "batch"],
+        ["write", "batch"],
         `Batch-draft an inclusive range of episodes.
 
 Usage
@@ -601,7 +444,7 @@ Output
 `,
     ],
     [
-        ["episode", "merge"],
+        ["write", "merge"],
         `Assemble all committed episodes (those with .done-<NN> markers) + episodes/meta.json
 into a single script.json, run schema validation, and persist locally for review.
 NO network — gateway upload is the separate "episode push" command.
@@ -648,7 +491,7 @@ Exit codes
 `,
     ],
     [
-        ["episode", "push"],
+        ["write", "push"],
         `Upload the most recent \`episode merge\` artifact to the script-output gateway.
 Pure uploader — does not assemble or validate (merge already did). Refuses to
 upload if the artifact / inputs drifted since merge.
@@ -690,7 +533,7 @@ Exit codes
 `,
     ],
     [
-        ["episode", "spec"],
+        ["write", "spec"],
         `Print the spec-md grammar scriptctl's parser accepts. \`episode draft\` (Gemini)
 auto-injects this into the writing prompt; this command exposes the same string
 for agents writing spec md by hand (for \`episode draft --from-md\` / \`--resume\`).
@@ -713,7 +556,7 @@ Exit codes
 `,
     ],
     [
-        ["episode", "workspace"],
+        ["write", "workspace"],
         `Report per-episode draft state inside the \`episode\` from-scratch workspace.
 
 This is a workspace-area introspection command. It only knows about files under
@@ -734,6 +577,661 @@ States
 - blocked-collision   collision report exists; agent must resolve
 - blocked-lint        lint critical report exists; agent must resolve
 - committed           .done-<NN> marker exists
+`,
+    ],
+    // =========================================================================
+    // 0.6.0 flat namespace — plural-noun queries
+    // =========================================================================
+    [
+        ["summary"],
+        `Show title and counts (episodes / scenes / actions / actors / locations / props / speakers).
+
+Usage
+- scriptctl summary [options]
+
+Options
+- --project-group-no  Project group no. Default: SANDBOX_PROJECT_GROUP_NO
+- --script-path       Local intermediate script JSON. Omit to use DB-backed script.
+- --workspace-path    Workspace directory. Default: workspace
+- --json              Print machine-readable JSON. Avoid unless parsing.
+- --help              Show this help.
+
+Read-only. Always safe to run.
+`,
+    ],
+    [
+        ["episodes"],
+        `List episodes with per-episode counts and char totals.
+
+Usage
+- scriptctl episodes [options]
+
+Options
+- --id <ep_id>        Filter to one episode.
+- --min-chars <n>     Only episodes with total chars >= N.
+- --max-chars <n>     Only episodes with total chars <= N.
+- --project-group-no / --script-path / --workspace-path / --json / --help
+
+Output line
+- ep_NNN: scenes=N, actions=N, chars=N (dialogue=N, action=N), title=...
+
+Examples
+- scriptctl episodes
+- scriptctl episodes --min-chars 1000
+- scriptctl episodes --id ep_007
+`,
+    ],
+    [
+        ["scenes"],
+        `List scenes with their environment, asset refs, and action counts.
+
+Usage
+- scriptctl scenes [options]
+
+Options
+- --in <addr>         Scope to ep_NNN (episode) or ep_NNN/scn_NNN (single scene).
+- --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.
+- --project-group-no / --script-path / --workspace-path / --json / --help
+
+Output line
+- ep_NNN/scn_NNN [space time] location=loc_NNN(name) actors=... props=... actions=N
+
+Examples
+- scriptctl scenes --in ep_007
+- scriptctl scenes --has-actor act_001
+- scriptctl scenes --in ep_001/scn_001
+`,
+    ],
+    [
+        ["actions"],
+        `Search actions across the script (the workhorse for "find where to edit").
+
+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).
+- --context <n>       Include N actions before/after each hit (for context windows).
+- --project-group-no / --script-path / --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.
+
+Output line
+- ep_NNN/scn_NNN#idx [type] [speaker|actor] 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
+`,
+    ],
+    [
+        ["actors"],
+        `List actors with role / aliases / state counts.
+
+Usage
+- scriptctl actors [options]
+
+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).
+- --project-group-no / --script-path / --workspace-path / --json / --help
+
+Examples
+- scriptctl actors --name "陈"
+- scriptctl actors --in ep_023
+- scriptctl actors --in ep_001/scn_001
+`,
+    ],
+    [
+        ["locations"],
+        `List locations with state counts.
+
+Usage
+- scriptctl locations [options]
+
+Options mirror \`scriptctl actors\`: --id, --name, --in, --project-group-no, etc.
+
+Examples
+- scriptctl locations --name "办公室"
+- scriptctl locations --in ep_007
+`,
+    ],
+    [
+        ["props"],
+        `List props with state counts.
+
+Usage
+- scriptctl props [options]
+
+Options mirror \`scriptctl actors\`: --id, --name, --in, --project-group-no, etc.
+
+Examples
+- scriptctl props --name "公文包"
+- scriptctl props --in ep_001/scn_001
+`,
+    ],
+    [
+        ["assets"],
+        `Unified search across actor / location / prop. Use when you don't care which kind.
+
+Usage
+- scriptctl assets [options]
+
+Options
+- --kind <actor|location|prop>  Narrow to one kind.
+- --id <id>                     Filter by id.
+- --name <substr>               Match name substring.
+- --in <addr>                   Restrict to assets referenced under this address.
+- --project-group-no / --script-path / --workspace-path / --json / --help
+
+Examples
+- scriptctl assets --name "陈"
+- scriptctl assets --kind actor --name "陈"
+`,
+    ],
+    [
+        ["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).
+- --project-group-no / --script-path / --workspace-path / --json / --help
+
+Examples
+- scriptctl speakers --kind system
+- scriptctl speakers --name "陈"
+`,
+    ],
+    [
+        ["issues"],
+        `List current validation issues. Runs validateScript on demand.
+
+Usage
+- scriptctl issues [options]
+
+Options
+- --severity <severity>   Filter by severity (error / warning / info / blocking).
+- --code <code>           Filter by issue code (e.g. STATE_NOT_FOUND).
+- --project-group-no / --script-path / --workspace-path / --json / --help
+
+Output line
+- <severity> <code>: <summary> [<location>]
+
+Examples
+- scriptctl issues --severity error
+- scriptctl issues --code STATE_NOT_FOUND
+`,
+    ],
+    [
+        ["refs"],
+        `Reverse lookup: every place an asset / state / speaker is referenced.
+
+Usage
+- scriptctl refs <addr> [options]
+
+Address forms
+- actor:<id> / location:<id> / prop:<id>          asset refs
+- actor:<id>/<state_id> (and location/prop)        state refs
+- spk_<id>                                         speaker refs
+
+Options
+- --level <scene|action>   Restrict to scene-level or action-level refs only.
+- --project-group-no / --script-path / --workspace-path / --json / --help
+
+Output line
+- <location> [<role>]   (e.g. ep_001/scn_001#3.actor_id [action_actor])
+
+Examples
+- scriptctl refs actor:act_001
+- scriptctl refs actor:act_001 --level scene
+- scriptctl refs actor:act_001/st_calm
+- scriptctl refs spk_001
+`,
+    ],
+    [
+        ["validate"],
+        `Validate the current final script. Read-only side; writes a validation report to workspace.
+
+Usage
+- scriptctl validate [options]
+
+Options
+- --project-group-no / --script-path / --workspace-path / --json / --help
+
+Exit codes
+- 0   passed
+- 78  validation needs repair (see scriptctl issues)
+`,
+    ],
+    // =========================================================================
+    // Edit verbs — content
+    // =========================================================================
+    [
+        ["replace"],
+        `Literal substring replace inside action.content.
+
+Usage
+- scriptctl replace <at> --from <text> [--to <text>] [--all] [options]
+
+Required
+- <at>                Action address: ep_NNN/scn_NNN#idx
+- --from              Non-empty substring to replace.
+
+Options
+- --to                Replacement text. Default: "" (delete the substring).
+- --all               Replace every occurrence in the action. Without it, multiple matches reject.
+- --project-group-no / --script-path / --workspace-path / --request-id / --json / --help
+
+Refuses overlap dialogue actions — use \`scriptctl overlap\` to rewrite their lines.
+
+Example
+- scriptctl replace ep_001/scn_001#3 --from "，台下掌声雷动" --to ""
+`,
+    ],
+    [
+        ["type"],
+        `Set the action.type on a specific action.
+
+Usage
+- scriptctl type <at> <dialogue|action|inner_thought>
+
+Example
+- scriptctl type ep_001/scn_001#3 dialogue
+`,
+    ],
+    [
+        ["actor"],
+        `Set or clear action.actor_id (the action's narrative subject).
+
+Usage
+- scriptctl actor <at> <actor_id|none>
+
+Example
+- scriptctl actor ep_001/scn_001#3 act_002
+- scriptctl actor ep_001/scn_001#3 none
+`,
+    ],
+    // =========================================================================
+    // Edit verbs — structure (multipolar by first-arg address format)
+    // =========================================================================
+    [
+        ["insert"],
+        `Insert an action (into a scene) or a brand-new empty scene (into an episode).
+
+Usage
+- scriptctl insert <ep/scn> --type <type> --content <text> [position-flags] [options]   # action insert
+- scriptctl insert <ep> --location <loc_id> [position-flags] [options]                  # scene insert
+
+Action insert (first arg is ep/scn)
+- --type              dialogue / action / inner_thought.
+- --content           Action content text.
+- --actor <id>        Optional action.actor_id.
+- --speaker <id>      Optional action.speaker_id.
+
+Scene insert (first arg is ep)
+- --location <id>     Required: the scene's primary location.
+- --time <time>       Default: day.
+- --space <space>     Default: interior.
+- --scene-id <id>     Optional explicit scene id (auto-assigned otherwise).
+
+Position (both forms)
+- --at <idx>          Numeric index in the parent collection.
+- --before <addr>     Insert before this sibling.
+- --after <addr>      Insert after this sibling.
+- Default             Append at end.
+
+Examples
+- scriptctl insert ep_001/scn_001 --type action --content "..." --after ep_001/scn_001#3
+- scriptctl insert ep_001 --after ep_001/scn_005 --location loc_001
+`,
+    ],
+    [
+        ["delete"],
+        `Delete an action, scene, asset, or speaker. Multipolar by address format.
+
+Usage
+- scriptctl delete <addr> [--strategy replace|remove] [--replacement <addr>] [--force]
+
+Behavior by address kind
+- action (ep/scn#idx)   Remove the action; later indices shift.
+- scene (ep/scn)        Empty scene: removed. Non-empty: refused unless --force.
+- asset (kind:id)       Refuses by default if refs exist. Pass --strategy:
+                          replace --replacement <addr>: rewrite all refs to the replacement, then delete.
+                          remove:                       scrub refs and delete (refs become dangling).
+- speaker (spk_id)      Same --strategy logic as asset.
+
+Examples
+- scriptctl delete ep_001/scn_001#3
+- scriptctl delete ep_001/scn_005 --force
+- scriptctl delete actor:act_001 --strategy replace --replacement actor:act_002
+- scriptctl delete spk_001 --strategy remove
+`,
+    ],
+    [
+        ["move"],
+        `Move an action across actions / scenes, or move a scene across episodes.
+
+Usage
+- scriptctl move <addr> <to> [--at <idx>]
+
+Behavior by source address kind
+- action (ep/scn#idx)   <to> is target action address; insertion is "before that index".
+- scene (ep/scn)        <to> is target episode id (or ep/scn for insert-before-anchor);
+                        --at <idx> overrides position; default: append at end.
+
+Examples
+- scriptctl move ep_001/scn_001#5 ep_001/scn_002#0       # cross-scene
+- scriptctl move ep_001/scn_005 ep_002                   # cross-episode
+- scriptctl move ep_001/scn_005 ep_002 --at 0            # to ep_002 start
+`,
+    ],
+    [
+        ["split"],
+        `Split a scene at an action boundary into two sibling scenes.
+
+Usage
+- scriptctl split <ep/scn> --at <idx> [--new-scene-id <id>]
+
+Required
+- <ep/scn>            Scene to split.
+- --at                Action index (1 <= idx < action count).
+
+Options
+- --new-scene-id      Optional explicit id for the new tail scene.
+
+Example
+- scriptctl split ep_001/scn_005 --at 7
+`,
+    ],
+    [
+        ["merge"],
+        `Merge one asset / scene into another. Source disappears; refs are rewritten to the target.
+
+Usage
+- scriptctl merge <src> --into <dst>
+
+Both addresses must be the same kind (asset/asset same kind, or scene/scene same episode).
+
+Examples
+- scriptctl merge actor:act_001 --into actor:act_002
+- scriptctl merge ep_001/scn_005 --into ep_001/scn_006
+`,
+    ],
+    // =========================================================================
+    // 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).
+
+Usage
+- scriptctl transition <at> <kind:id> --process <text> --contrast <text>
+- scriptctl transition <at> <kind:id> --clear
+
+Examples
+- scriptctl transition ep_001/scn_001#3 actor:act_001 --process "深呼吸三秒" --contrast "由静转动"
+- scriptctl transition ep_001/scn_001#3 actor:act_001 --clear
+`,
+    ],
+    [
+        ["context"],
+        `Manage a scene's context.{actors|locations|props} ref.
+
+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
+
+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
+`,
+    ],
+    // =========================================================================
+    // Edit verbs — asset metadata
+    // =========================================================================
+    [
+        ["rename"],
+        `Rename an asset (actor / location / prop).
+
+Usage
+- scriptctl rename <kind:id> <new_name>
+
+Example
+- scriptctl rename actor:act_001 "陈墨"
+`,
+    ],
+    [
+        ["describe"],
+        `Set the description on an asset or a state (address with /state_id).
+
+Usage
+- scriptctl describe <kind:id> <text>                    # asset description
+- scriptctl describe <kind:id/state_id> <text>           # state description
+
+Examples
+- scriptctl describe actor:act_001 "男主，30 岁，雷厉风行"
+- scriptctl describe actor:act_001/st_calm "默认形态：平静"
+`,
+    ],
+    [
+        ["alias"],
+        `Add or remove aliases on an asset.
+
+Usage
+- scriptctl alias <kind:id> [--add <alias>] [--remove <alias>]
+
+Either --add or --remove (or both, repeatable) must be provided.
+
+Examples
+- scriptctl alias actor:act_001 --add "陈总"
+- scriptctl alias actor:act_001 --add "陈总" --add "老板"
+- scriptctl alias actor:act_001 --remove "老板"
+`,
+    ],
+    [
+        ["role"],
+        `Set an actor's role_type.
+
+Usage
+- scriptctl role <actor:id> <主角|配角>
+
+Only valid on actor:* addresses.
+
+Example
+- scriptctl role actor:act_001 主角
+`,
+    ],
+    [
+        ["worldview"],
+        `Set the script-level worldview (story setting / time period).
+
+Usage
+- scriptctl worldview <value>
+
+Value must match the supported enum (see SCRIPT_SCHEMA worldview values).
+
+Example
+- scriptctl worldview 现代
+`,
+    ],
+    // =========================================================================
+    // Edit verbs — state management
+    // =========================================================================
+    [
+        ["state-add"],
+        `Add a state to an asset's states[].
+
+Usage
+- scriptctl state-add <kind:id> <state_name> [--description <text>] [--state-id <id>]
+
+Required
+- <kind:id>           Asset target.
+- <state_name>        Human-readable state name (must be unique within the asset).
+
+Options
+- --description       Optional description.
+- --state-id          Optional explicit id (auto-assigned otherwise).
+
+Examples
+- scriptctl state-add actor:act_001 "震惊"
+- scriptctl state-add actor:act_001 "震惊" --description "瞠目结舌" --state-id st_shock
+`,
+    ],
+    [
+        ["state-rename"],
+        `Rename a state on an asset.
+
+Usage
+- scriptctl state-rename <kind:id/state_id> <new_name>
+
+Example
+- scriptctl state-rename actor:act_001/st_calm "平静（新）"
+`,
+    ],
+    [
+        ["state-delete"],
+        `Delete a state from an asset's states[]. Refs are handled via --strategy.
+
+Usage
+- scriptctl state-delete <kind:id/state_id> --strategy <replace|remove> [--replacement <state_id>]
+
+Strategy
+- replace --replacement <state_id>   Rewrite all refs to the replacement state, then delete.
+- remove                             Clear refs and delete (scene-initial state becomes null;
+                                     state_changes referencing this state are dropped).
+
+Examples
+- scriptctl state-delete actor:act_001/st_calm --strategy remove
+- scriptctl state-delete actor:act_001/st_calm --strategy replace --replacement actor:act_001/st_default
+`,
+    ],
+    // =========================================================================
+    // Edit verbs — dialogue / speaker
+    // =========================================================================
+    [
+        ["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.
+
+Usage
+- scriptctl overlap <at> --line "<speaker_id>:<content>" [--line ...]
+
+Each --line associates one speaker with one line of dialogue. Repeatable.
+
+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).
+
+Examples
+- scriptctl add-speaker --kind actor --name "陈默" --source-id act_001
+- scriptctl add-speaker --kind system --name "广播员"
+`,
+    ],
+    // =========================================================================
+    // Patch (batch transactions)
+    // =========================================================================
+    [
+        ["patch"],
+        `Apply a batch JSON patch to the current script. Use ONLY for >=3 ops in one transaction;
+single-op edits should use the corresponding atomic verb (replace / type / delete / rename /
+state-add / etc.).
+
+Usage
+- scriptctl patch <file> [options]
+
+Required
+- <file>              JSON patch file. Top-level may be:
+                        an array of ops, or
+                        { "ops": [...] }, or
+                        { "operations": [...] }, or
+                        a single op object.
+
+Op names use dot-style only (state.add / action.delete / asset.rename / etc.).
+The 0.5.0 snake-style ops (set_worldview, rename_actor, merge_scenes, ...) were removed.
+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.
+- --project-group-no / --script-path / --workspace-path / --request-id / --json / --help
+
+Examples
+- scriptctl patch changes.json
+- scriptctl patch changes.json --dry-run
+- scriptctl patch --schema
+- scriptctl patch --schema asset.rename
 `,
     ],
 ];