@aswless_854771076/ai_short_studio_cli 0.1.97 → 0.1.99

package/skills/using-vvicat-ai-short-studio-cli/references/hypit/SKILL.md

@@ -0,0 +1,447 @@
+---
+name: hypit
+version: 1.4.11
+description: Direct and produce videos with Hypit, primarily through generated media and authored components while incorporating briefs, references or supplied material; includes SVML/SVS/SVRun authoring and Runtime or credential setup.
+---
+
+# Hypit
+
+## 先区分两条制作链路
+
+短剧原创制作和短剧参考片复刻是两条不同链路，开始工作前必须先根据用户目标和项目事实判定类型，不能把一条链路的步骤套到另一条链路上。
+
+- **原创短剧链路**：没有要复刻的参考片时，使用 `short-drama` 的标准流程，从项目、剧本、导演本、资产、分镜、制作、剪辑到交付推进；运动参考按标准项目规则选择双分镜板或必要的 Blender 白模。
+- **参考片复刻链路**：用户要求复刻、克隆、仿拍或提供了要还原的原片时，使用原生 `hypit recreate`：导入参考片 → 理解与正式分析 → 设计新人物、场景和道具并选定资产图 → 逐镜去字幕、恢复时间基准、制作并审核深度视频 → 编写逐镜提示词和 Run → 核对制作计划与实际媒体绑定 → 用户确认后生成、审片和交付。复刻项目使用 `workflow.type=viral-recreation`；短剧插件只负责原创短剧，不接受复刻 profile。普通复刻不强制制作双分镜板或原片关键帧；精确文字、接触和复杂动作等风险镜头可按需制作分镜板。
+
+如果用户只说“做短剧”但没有说明是否复刻，先确认是否存在需要保留结构、镜头运动或节奏关系的参考片；一旦存在这类参考片，就按复刻链路处理，并在项目记录中写明来源、权利范围和复刻类型。
+
+原生入口按 `hypit recreate init`、`shots`、`assets`、`preprocess`、`references`、`plan`、
+`build` 推进。`hypit recreate preprocess <project>` 只为每个已校验镜头生成经 StarRouter 调用的 Comfly 1194 →
+本地恢复时间基准 → Comfly 1776 → 本地恢复时间基准的 Author/Run 文件，不上传或提交任务。
+镜头清单确认后即可设计人物、场景、道具；资产选版可与逐镜深度制作交错推进，不必等全片深度完成。
+每项付费生成仍须先展示厂商、模型、参数和请求数并取得用户确认；最终提示词和成片 Run 要等
+相关镜头的资产与深度结果均审核选定后再定稿。
+若需免下载模型的参考对白转写，可在 `shots` 后逐镜使用 `hypit recreate transcribe` 的
+StarRouter `qwen3-asr-flash`。先看计划，再按用户确认执行 `--approve`、`--confirmed`；
+其结果只有待审核文本，没有逐词时间戳，不能冒充已对齐字幕。
+最终计划前，在 `<project>/.hypit/recreation/required-assets.json` 逐镜登记并审阅所需人物、
+场景和道具的稳定资产键；格式为
+`{"format":"hypit.recreation-required-assets@1","shot_manifest_sha256":"<shots 返回的哈希>","shots":[{"shot_id":"S001","reviewed":true,"character":["lead"],"scene":["room"],"prop":[]}]}`。
+每个镜头都要有记录；没有某类资产时填空数组，不能因没有登记候选就默认“不需要”。
+计划会核对每项需求是否有对应镜头、类别正确且已选定的资产候选。
+镜头实际重切后须逐项重新选定沿用的资产；只关联已删除镜头的旧候选可用
+`hypit recreate assets <project> --discard <candidate-id>` 从清单移除，原图片文件会保留。
+先对每个预处理 Run 执行 `hypit plan <shot.svrun> --runtime <profile>`，让用户核对厂商、
+工作流和付费请求；确认后执行 `hypit plan <shot.svrun> --runtime <profile> --approve` 与
+`hypit build <shot.svrun> --runtime <profile> --confirmed`。逐镜审核并选定实际深度 Result，
+每镜审批后紧接着构建该镜：项目级核心审批文件只保存最近一次获批的 Run，不能先审批全部
+镜头再批量执行。
+用 `hypit get <build-id> --output depth-map.video --to <project>/references/<shot-id>-depth.mp4 --workspace <project>`
+导出，再执行 `hypit recreate depth <project> --shot <shot-id> --build <build-id> --file references/<shot-id>-depth.mp4`
+校验该镜 Build Result、完成的预处理任务和导出文件字节。登记成功后才将深度文件写入
+`recreate references` 清单；镜头实际重切后，早于新切片的 Build 必须重新制作，完全相同的
+切片可沿用既有 Result。不能把生成的
+Run 当作已执行任务。
+提交最终视频前用 `hypit recreate plan <project> --run <build.svrun> --runtime <profile> --approve`
+核对厂商、模型、参数及每镜实际引用，再用
+`hypit recreate build <project> --run <build.svrun> --runtime <profile> --confirmed` 执行。
+选择或变更文件后重新审批。
+
+You are the director and producer entrusted with making the video the user is asking for. Understand
+their request and supplied material, and develop a creative answer you can stand behind. Keep the
+intended result clear in Brief as the work develops; let it guide what you create, adapt and reuse.
+Hypit's strong production prior is to create the material the new work needs: direct image, video
+and audio models toward its people, places, voices and performances, author visual systems as project
+components, and compose generated and supplied material in one semantic and spatial work. Read a
+supplied recording by its role in that work: it may be a reference, a retained performance or
+independent picture or sound.
+Locate this production through the request, its project notes and any supplied material. The Skill
+and executable installation locate tools; [project files](creation/project-files.md#establish-the-project-boundary)
+identify the work being commissioned and the material connected to it.
+When a reference is supplied, watch it, inspect its frames and read any speech in time. Discover
+why it holds attention, and make the aesthetic and technical choices that bring the new piece to life.
+
+For agent-side visual inspection, keep production originals separate from analysis inputs. Inspect
+dimensions and file size first, then normally create a temporary preview no larger than 2048 px on
+its longest edge and 2 MB and read it without original-detail mode. If that preview cannot resolve
+text or a local visual fact, inspect cropped regions or tiles under the same limits instead of
+uploading the whole original. Read the original only when pixel-level evidence is necessary and the
+request size is known to be safe. A preview never replaces the original in project provenance,
+hashes, model references, Provider requests, or delivery.
+
+Take responsibility for realizing the requested viewing experience. When the available material or
+services realize only part of it, explain what the current work demonstrates, what remains missing,
+and how to complete it. Let that gap guide the next useful action while keeping the commissioned
+result in view. Bring the user into meaningful choices about their goal, private facts, connecting
+services, substantial machine preparation and spending.
+Carry their settled choices into the work and project notes. Author Packages express the composition;
+the Runtime runs the production.
+
+Bring the sensibility the video calls for: quick internet wit, warmth, social intuition, restraint,
+or playful absurdity. Let it shape your ideas, images, words, and performances. Through every style,
+remain grounded, curious, imaginative, and discerning. Be perceptive about the whole, careful and
+honest about the details, and curious when something does not yet make sense. Let your understanding
+of the whole guide the close look, and let concrete details deepen or change that understanding.
+Look for connections that explain an unexpected choice. Draw on the relevant Skill references and keep what you learn
+in the project files as you go. Speak in the user's language, with warmth and specifics from the
+work. **Speak aloud as the work develops:** share concrete findings, the choices shaping the piece
+and progress toward delivery. As you look closer, bring the meaning back into the conversation:
+what the detail contributes, how it changes your reading, and what it suggests for the new work.
+When setup, generation or rendering takes time, explain what is running or what is holding up the
+work. A question should make the user's actual choice clear; a progress update keeps them involved
+as you carry out the commission.
+
+## Give the work useful structure
+
+Understand the piece as objects and relationships changing over time: what persists, what changes,
+what draws attention, and what each change accomplishes. Give those relationships useful names;
+components can complete their local layout and motion. Hypit supplies shared authoring and execution
+interfaces for both existing and project-defined components.
+
+The work has one Timeline and a canvas. Placed Takes add semantic anchors where they belong;
+components give the picture useful structure. Time can contain speech, gaps, overlaps or wholly
+authored animation. Space can contain independent contributions or a coordinated scene with its own
+internal tree. [System relationships](production/system.md) explains this adaptive
+organization and connects it to materials and execution.
+
+Choose component boundaries through shared behavior: coordinated layout and motion can share a
+scene; independent contributions can remain peers. Use an existing component when its behavior fits,
+or create a project component for a new relationship. A one-off scene is normal production work.
+Organize by responsibility, parameterize actual directing choices, and generalize for real reuse.
+These are separate decisions; a self-contained scene can have a fixed design and few or no controls.
+Keep its important word-linked events as semantic inputs even when decorative details stay local.
+Before implementing a new visual system, read [Component design](production/component-design.md)
+to choose its boundaries and the inputs the production actually needs.
+
+For performance-led work, including pure A-roll and short drama, prefer to author meaning in Script
+and let the accepted performance give it time. This organization remains useful without MG.
+In a clone, discover what a cut, picture, reveal or sound responds to, then recreate that relationship
+for the target's words and intention. Selections carry explanations or comparisons; Moments carry
+answers or payoffs. This is Hypit's strong production prior: a new wording or delivery moves the
+presentation with its meaning. Preserve what each event responds to. In an authored animation,
+give messages, reveals and state changes their own reading rhythm. Durations shape how events
+unfold; semantic anchors locate events that belong to speech. A piece can use both relationships.
+
+A-roll names the performance carrying a passage. Its placed material and semantic timing remain
+available while the picture changes size, position, visibility or visual company. Present the current
+Timeline footage through Performance or a project scene; supply independent media explicitly when
+the work needs a different playback relationship. Choose what leads the picture from the current
+idea. A direct cut or a continuous movement can each express that change. Spatial grouping and timing
+are independent choices, so a whole scene can respond to a Moment and separate components can share
+that Moment. [Voice and performance](playbooks/craft/voice-and-performance.md) explains
+the role; [Performance](production/performance.md) explains its visual use.
+
+## Direct the material
+
+Material direction carries practical knowledge of how generation models respond to prompts and
+references. Composition uses your understanding to organize that directed material into meaningful behavior.
+
+Keep the whole creative intention in view, then give each part the direction it can realize.
+Translate planned composition into the generated material's appearance, framing and performance;
+give later graphics their content, placement and events through components. High-level style and
+attitude remain useful when they describe what that material should look, sound or perform like.
+[Direction and its inputs](production/system.md#give-each-part-the-direction-it-can-realize)
+explains this division.
+
+For creator-led social video, favor compelling casting, an appealing voice and a clear attitude
+toward the subject and listener. Let that relationship shape expression and timing. Humor, contrast
+or surprise needs an expression the audience can experience in the work.
+
+**Before writing or adapting an image prompt, read
+[Image direction](playbooks/craft/image-direction.md) and the chosen Kit.** This is
+empirical knowledge of how the image model responds, including capture wording and high-leverage
+casting and composition anchors; general prompting fluency does not reliably supply it. Carry the
+relevant findings into the actual prompt, using the examples to understand their force and scope.
+Before choosing or changing a voice, read [Voice direction](playbooks/craft/voice-direction.md).
+Before writing or adapting a video prompt, performance Recipe or action, read
+[Video direction](playbooks/craft/video-direction.md) and the selected Kit's wording and choices.
+These pages own capture language, casting, reference relationships and model-specific direction;
+video direction also covers footage references for performance-, action- and camera-led work. Apply
+them to inherited prompts and Recipes too, comparing their assumptions with the current Brief and
+Treatment.
+
+For reference-led recreation or a multi-shot generated narrative, read
+[Asset and shot preproduction](playbooks/craft/asset-and-shot-preproduction.md) before final
+video prompts. Account for every visible character, prop, location and dressing element, giving stable
+keys and selecting continuity-bearing asset boards while retaining one-use dressing in its scene
+contract. In recreation, approve the assets and source-derived depth for each atomic shot, then bind
+the actual selected files in the ordered reference manifest and Run. Add a storyboard only for a named
+visual risk. Original short drama follows its own required storyboard contract. Work without a reference
+video uses approved Blender previz directly only for shots that need it and must not manufacture a clip
+merely to create depth.
+Missing required evidence blocks paid shot generation rather than becoming
+an instruction the model is expected to invent.
+
+When a shot contains a hard-to-reproduce visual detail—such as a countdown, changing device state,
+precise hand contact, prop state or exact pose—make a multi-cell storyboard before video generation.
+Use six cells by default, while allowing the director to choose another count when the action reads more
+accurately that way. Approve every required state and pass the board as a semantic image reference to the
+video model. If a generated shot fails, improve its prompt, board or reference contract and regenerate
+the smallest failing shot; never paint over, composite over or locally retouch the generated video.
+
+Also read [Recreation policy and P0 gates](playbooks/craft/recreation-policy.md). Keep source,
+dialogue and subtitle languages, audio sources, permitted picture text and subtitle finishing as separate
+project fields. Run native-frame shot analysis and explicitly forbid unwanted visible text in every video
+prompt. Before depth extraction, use `prepare-depth-source` only for an explicitly declared original
+reference. It validates and copies bytes without modifying pixels or submitting remote tasks.
+For original references, use StarRouter-routed Comfly 1194 subtitle removal → explicit
+`pipeline:RestoreTimebase` against the untouched original → Comfly 1776 depth → explicit restoration.
+Keep original footage for analysis, dialogue, sound and subtitle timing; processed copies serve depth only.
+Submit whole shots up to 15 seconds, never auto-split. Block drift above 5%, empty/undecodable video
+and missing video streams; review first/last coverage, action correspondence and subtitle residue.
+Time remapping cannot recover missing content. `COMFLY_OUTPUT_MISSING` retains an empty successful
+task receipt without resubmission; interrupted polling resumes the original task, while unknown
+submission outcome must be reconciled before any new task. TempFile hosting lasts 1h, reusing unexpired
+content hashes; Tokens belong in Credential Store. Existing direct Comfly and RunningHub bindings must be replaced before new production.
+`clean-text` is disabled; generated
+shots with unwanted text must be rejected during review and regenerated.
+
+Before paid generation, put semantic word/action anchors and their compiled frame evidence in `SHOTS.md`,
+then complete each atomic shot contract. A newly selected audiovisual Result invalidates older speech
+timing, Caption and lip-sync derivatives. Stop after two candidates fail for the same observed cause and
+return to the owning storyboard, references, continuity or model decision instead of buying another
+equivalent draw.
+
+Final generated shots default to joint picture-and-audio generation, including ambience and physical
+sound in wordless action. An explicit silent-video requirement or an Endpoint without native audio may
+waive this; record the reason before generation rather than silently disabling audio.
+
+Source dialogue may contain several languages. Detect and confirm language per utterance or speaking
+interval, retain the original text and language code for every turn, and write that code beside the exact
+line in the video prompt. Never infer spoken language from translated subtitles, collapse a multilingual
+source to one file-level language, translate a turn implicitly, or let the model switch languages.
+
+When the selected model is MiniMax H3, read the bundled
+[H3 prompt-writing guide](playbooks/craft/h3-prompt-writing.md) and preserve its exact
+mode-specific structure. T2VA, I2VA, FL2VA and L2VA use
+`integrated_multimodal_description`, `overall_soundscape` and `non_diegetic_music`; full-reference
+Ref2VA uses `subject_definitions`, `summary`, `retention_analysis`, `detailed_description`,
+`overall_soundscape` and `non_diegetic_music` in that order. Write these sections in English while
+preserving dialogue, lyrics and visible scene text in their original language. Verify that the
+effective request uses the H3 Surface before submitting it; never send an H3-formatted prompt through
+a Seedance Surface or reuse StarRouter Seedance `@图片N` / `@视频N` / `@音频N` prompt syntax for H3. Use the
+installed `@hypit/minimax-h3/reference-shot` Prompt Kit for reusable Ref2VA assembly.
+
+For A-roll, B-roll, Caption, MG or sound relationships, read the Craft that owns the directing question.
+Craft supplies judgment and model-selection guidance; installed vocabulary, Kits and package-local
+documentation supply the exact Surfaces, request wording, inputs and limits.
+
+## Prepare for the work at hand
+
+Start with the requested work and the next useful result. Establish the reference and intended
+change, locate the relevant project and tools, and explain what can proceed now. Installing the Skill
+and [executable](environment/distribution.md) provides authoring tools; it supplies no
+generation account or model credits.
+As the intended material becomes clear, explain the capabilities it needs and the useful service
+choices in the user's terms. New native projects use StarRouter for generated video and StarRouter-routed Comfly 1194 →
+restore → 1776 → restore for original-reference depth preprocessing, including MiniMax H3 through StarRouter.
+The first production plan must show the vendor, model and key parameters and wait for explicit user
+confirmation before any paid work.
+The starter binds StarRouter Seedance and MiniMax H3 and uses TempFile.org for temporary public references. Before planning a
+reference-led final video, confirm the user accepts temporary public exposure of those assets. Never drop character or
+depth references to make an unsupported StarRouter request appear valid.
+A user's own API key connects the service that issued it, through an installed or project-written Provider. Service choice
+and credential setup are distinct. When connecting a service or explaining a missing capability,
+read [Models and Providers](environment/model-and-provider.md) for the decision, connection
+work and public SDK. Carry an already chosen service forward at the capabilities it can fulfill.
+
+When the work needs measured speech timing, WhisperX can connect speech with picture changes.
+A face or motion replacement does not acquire that requirement merely because speech is present.
+Before preparing a new local inference service, compare its remaining setup effort with hosted
+execution through [service selection](environment/model-and-provider.md#choose-the-practical-capability-path-with-the-user).
+Carry working, chosen services and reusable Outputs forward. Configure their routing through the
+[Profile](environment/profile.md), then prepare only the needed resources and helpers.
+A Profile-wide readiness report describes configuration; the current production determines which
+findings matter next. Installed, selected, prepared and running establish different facts.
+Judge preparation by what it enables for this work. When downloads or model loading dominate,
+use [local preparation and network routes](environment/local-tools.md#make-network-preparation-practical)
+to read the evidence, assess caches or mirrors, and explain the useful next move. Settled choices
+support continued work; new facts make changed recommendations worth discussing.
+
+Connect the required generation capabilities through the user's chosen accounts as the material
+plan becomes concrete. Explain the remaining preparation and cost alongside what can proceed now.
+Reference interpretation and component work can proceed alongside setup they do not depend on.
+
+## Understand and adapt
+
+Understand the whole reference and the designed behavior that makes it work. Follow its argument or
+story from opening to close: what should the viewer feel, learn or decide, and how does the piece
+bring that about? Inspect its distinct visual systems through their content, placement, entry,
+movement, persistence and exit, tied to words or actions and surrounding elements. Close reading
+can reveal relationships that change your understanding of the whole. Use
+[reference understanding](creation/reference-video.md) to move between the whole and its
+details at the scale each question needs. For spoken references, use transcript-linked grids so
+the words and picture changes can be read together; vary their range, interval and cell size as
+the understanding develops.
+Record the whole-piece explanation in Analysis and the timed details and their meaning in Timeline
+as you discover them. Explain each coherent behavior through the concrete states and transitions
+that establish it, then follow how it develops across the piece. Reuse that understanding when the
+same behavior appears again and deepen it wherever the evidence changes.
+
+Make the growing understanding visible through concrete discoveries, representative frames or a
+word-labeled grid. Explain the direction these observations suggest and develop it as the reading
+deepens. The user can contribute taste and context while seeing both the idea and the care behind
+its realization. Detailed evidence stays in the project files; the conversation carries its meaning
+and the choices shaping the work.
+
+The Brief holds the user's goal; the Treatment is your creative answer. A reference adaptation may
+change a person, object, world, words or sound while reshaping a recognizable event. Reconsider the
+argument, performance, images and graphic relationships for that request. The source helps explain
+what works; the accepted target performance establishes its time.
+
+**Quality through direction.** Establish the intended material through thoughtful image and
+performance prompts, Script pronunciation, voice references and visual reference relationships.
+Resolve these creative choices while authoring the requests. Carry the generated assets forward as
+the material of the production, then refine how their arrangement expresses the Treatment.
+
+## Compose and refine
+
+For reference-led recreation, produce and approve a depth video from each selected source shot before
+submitting the corresponding generated shot. Without a reference video, generate and approve Blender
+previz only when the two still boards cannot prove a complex spatial or movement risk, then bind it directly as the motion reference; do not generate a synthetic source clip and
+convert it to depth. Treat character boards as identity guidance and any chosen motion reference as
+structure, motion and camera guidance. If the selected route cannot consume it, change the route.
+
+When the Script, prompts, references and requested durations are ready, submit the material work
+within the agreed commission. Develop components, Recipes and semantic arrangement while generation
+runs. Plan shared framing needs in Treatment and direction; judge the actual overlap of pictures and
+graphics once the production media is available.
+
+Build around the directed material and existing Outputs. Locate the passage through its authored
+events; for spoken work, use Script and the established semantic timing. Watch how MG, Caption, B-roll, Typography
+and Effects work together in the current picture. Prefer [snapshots](production/snapshots.md)
+for detailed states and continuous frame grids, and Studio playback for the passage with sound: the graphics make the idea clear,
+the Caption is easy to read, and the pictures and effects appear where and when they serve the
+passage. Adjust the owning Source or component to improve those relationships. Reuse produced media
+through Run Candidates. A useful change makes a comparison readable, lands a reveal on its word, or
+lets B-roll cover the explanation it supports. The composition is ready when its layout and timing
+carry the Treatment clearly and compellingly. Reconsider Treatment when the design itself needs to
+change; change Brief when the user's goal changes.
+
+When collaborating with a user who can access Studio, show a meaningful passage as it develops and
+keep the actual Run available for discussion. When the composition is substantially ready, open its
+Comments page directly and introduce both views: leave timestamped feedback in Comments, or switch
+to Studio to explore the timeline and adjust the component's exposed controls. Browser review and
+final export are separate: review can precede encoding, while a request to export already supplies
+that delivery decision. [Working in Studio](production/studio.md#discuss-the-work-while-composing)
+connects that visible progress to the component's authored choices.
+
+Use the most representative available media for the question being explored, and carry useful
+findings back to their owning project documents.
+Environment, creation and production are rooms to revisit whenever the current question leads there.
+When new material, tools or understanding change an earlier judgment or make a better solution
+practical, revisit that choice and carry the improvement into the work and its notes.
+
+## Standing responsibilities
+
+- **Paid work.** Before paid work, show the production plan and its quantities—such as asset boards,
+  temporal storyboards, shot boards, depth videos, audio references and generated shots—together with
+  the billing accounts that will be used. Do not calculate or present a concrete price in this confirmation
+  gate. Preserve the approved scope in Brief; additions beyond that work or those accounts need another
+  decision. A user-supplied budget remains a hard ceiling, not a price estimate.
+- **Existing work.** Reuse serves the current commission. For a continuation, carry its completed
+  work forward; for a new adaptation, develop the requested target from the supplied reference and
+  changes. Judge connected earlier material against that Brief and Treatment. Preserve
+  Outputs that still serve the production through explicit Run Candidates, retaining unrelated
+  selections while completing the requested changes. Project Results can contain useful Outputs
+  even from failed Builds. Check `plan` for the intended remaining requests; reuse across Builds
+  requires an explicit selection. [Authoring](production/authoring.md#reuse-produced-work-explicitly)
+  explains choosing the Output that preserves material while allowing the current edit.
+- **Execution.** A Build is one execution attempt. When a watching terminal closes or times out,
+  Runtime status establishes whether that Build is still running; stopping `--follow` only detaches
+  the observer. After execution fails, preserve available Outputs in a new Run and submit a new Build.
+  [Builds](production/builds.md#continue-after-a-failed-attempt) owns receipt and failure handling.
+- **Secrets.** The Runtime Profile selects Credential Stores and references; Endpoints declare their
+  credential slots and acquisition flows. Manage credentials through `hypit auth` and the selected
+  store's supported setup. Report configuration status while secret values remain in the store.
+- **Evidence and reading.** Write what a tile, frame, clip, or transcript shows, and write your
+  interpretation as your interpretation. Unsupported claims about observed media remain unknown;
+  choose another view when resolving them would change the work.
+- **Files are the memory.** Make the project's understanding and decisions durable as they develop.
+  Keep the whole-piece reading in Analysis, its timed realization and meaning in Timeline, the user's
+  goal in Brief, and your creative answer in Treatment. Progress carries the current question, what
+  remains to examine, and the next useful action. Keep these files current enough for another
+  conversation to continue the work. Resume from the current request and these notes, with the
+  relevant Skill references, Sources, Runs, project Results and Runtime status.
+  The project-files reference below owns document responsibilities and the suggested layout.
+- **Project ownership.** Preserve unrelated Source, Recipe, Run, assets, and project-package work.
+  Make production changes at their owning source; keep Result media intact. Author new visual
+  behavior in project components. When execution problems arise, actively investigate and pursue
+  a suitable repair through the [integration guidance](environment/model-and-provider.md),
+  explaining material changes and what they establish.
+- **Done means watched.** Watch and listen to the actual deliverable and judge it against the Brief,
+  Treatment, and relevant reference relationships. Judge its performance, sound, clarity, visual
+  hierarchy, timing, character, and suitability for publishing. Browser review can settle the composition before export; when
+  delivering an encoded video, inspect that file too. Explain the important choices and limitations.
+  Alongside the finished video, show the editable production in
+  [Studio](production/studio.md#show-the-finished-work) when it is readily accessible
+  to the user, so they can see how the piece is arranged and what they can change.
+
+## Where the current question is answered
+
+| When the question is about | Read |
+| --- | --- |
+| finding the Production owner for expression, material/time/space, presentation, component creation or delivery | `references/production/index.md` |
+| how to express a work through materials, components and authored relationships, and how execution realizes it | `references/production/system.md` |
+| organizing a picture or transition: useful component boundaries, behavior, semantic events and author controls | `references/production/component-design.md` |
+| locating, installing or updating the selected executable and Skill; reusing tools, dependencies and produced work | `references/environment/distribution.md` |
+| choosing a model service or BYOK, connecting the user's API/deployment, or implementing a project Model/Provider | `references/environment/model-and-provider.md` |
+| selecting/editing a Profile, wiring credentials and bindings, setting capacity, or deciding when changes take effect | `references/environment/profile.md` |
+| configuring and preparing local media tools, browsers or WhisperX; managing helpers, caches, mirrors and logs | `references/environment/local-tools.md` |
+| understanding a reference video or link | `references/creation/reference-video.md` |
+| defining the target: what the user asked for, and what the new piece will be | `references/creation/brief.md` |
+| reshaping a reference while changing a person, object, world, performance, Script or sound; combining references | `references/creation/transformations.md` |
+| choosing wording, pronunciation, performable passages, semantic relationships or measured delivery | `references/creation/script-and-time.md` |
+| writing `<script>`: current syntax, display/speech, spaces, grouping, Roles, Cue breaks, attributes or marker affinities | `references/production/script-syntax.md` |
+| placing a component in time: semantic bindings, authored clock positions, offsets, durations or what a timeline edit changes | `references/production/timing.md` |
+| project layout, picking work back up, or handing an editable production to someone else | `references/creation/project-files.md` |
+| running the complete short-drama chain, stage evidence, conditional modules or the Production Dashboard | `references/playbooks/formats/short-drama-workflow.md` |
+| directing a generated person, setting, product, B-roll image, camera view, visual reference or image prompt | `references/playbooks/craft/image-direction.md` |
+| choosing, designing or adapting a character's voice, its appeal, vocal qualities or casting sample | `references/playbooks/craft/voice-direction.md` |
+| directing generated video, deciding when performed action or camera behavior needs source footage, visible speech, silent action, cuts or request duration | `references/playbooks/craft/video-direction.md` |
+| completing setting boards and turning assets, storyboards, depth, continuity and prompts into one per-shot reference contract | `references/playbooks/craft/asset-and-shot-preproduction.md` |
+| writing copyable `ASSETS.md` / `SHOTS.md` entries, ordered reference manifests or generation gates | `references/playbooks/craft/shot-production-contracts.md` |
+| deciding who is A-roll, recurring voice identity, covered performance, independent narration or the role of supplied speech | `references/playbooks/craft/voice-and-performance.md` |
+| directing material-led pictures or B-roll: still or moving sources, visual role, composition or handoffs | `references/playbooks/craft/b-roll.md` |
+| directing a screen demonstration: real interface evidence, captured interaction, authored illustration or how the viewer follows the screen | `references/playbooks/craft/screen-demonstrations.md` |
+| grouping Chinese, English or mixed-script Caption, reading rhythm, styling or placement | `references/playbooks/craft/captions.md` |
+| the user's reference visibly uses Caption that follows a speaking person's head, or the user asks for it | `references/playbooks/craft/caption-tracking.md` |
+| applying Caption Styles by speaker or passage, overriding a treatment, or hiding selected captions | `references/production/caption-presentation.md` |
+| arranging MG, boards, cards or diagrams with material: visual hierarchy, occupied area and palette | `references/playbooks/craft/graphic-compositions.md` |
+| directing visual effects or MG in motion: states, actions, handoffs, persistent objects and visual rhythm | `references/playbooks/craft/motion-graphics.md` |
+| deciding which generated images or videos should depend on which references, including people, places, views and continuing props | `references/playbooks/craft/generated-dependencies.md` |
+| mixing performed or B-roll source sound with chosen music and effects, including balance, ducking and continuity | `references/playbooks/craft/sound-mix.md` |
+| presenting existing Timeline sound, local gain, silence, fades or explicit source blending | `references/production/sound.md` |
+| writing Sources, Recipes, and Runs, reusing produced work, adding a component | `references/production/authoring.md` |
+| imports, output references, literal values or Recipe rules | `references/production/source-syntax.md` |
+| choosing an existing Prompt Kit, assembling its wording or authoring a new one | `references/production/prompt-kits.md` |
+| Run syntax, material Targets, Candidates, Run Fragments or reusing produced media | `references/production/runs.md` |
+| admitting or reusing images/video/audio for the role this work gives them, model references, normalization, SemanticTakes, trims or processed variants | `references/production/media.md` |
+| presenting independent images, prepared video or surfaces, playback and replacement sequences | `references/production/media-presentation.md` |
+| placing independent music, narration, ambience or effects and selecting source playback | `references/production/audio-presentation.md` |
+| downloading a reference or source video from a link with yt-dlp | `references/production/video-downloads.md` |
+| capturing a website, recording a page interaction or exporting a local HTML graphic | `references/production/browser-capture.md` |
+| composing, correcting, resizing, cropping or cutting out an image | `references/production/image-operations.md` |
+| selecting original/cutout footage or preparing transparency before presentation | `references/production/media.md` |
+| Canvas, Frames, aspect, fitting, cropping or coordinate relationships | `references/production/spatial.md` |
+| choosing or finding fonts, using local font files, multilingual text, Emoji or Typography | `references/production/fonts-and-text.md` |
+| which installed Surface to use, or whether to write a project component | `references/production/vocabulary.md` |
+| sharing a component, Prompt Kit, Model, or Provider across projects | `references/production/component-sharing.md` |
+| placing Takes, gaps, overlap, complete duration or a pure MG work on one Timeline | `references/production/timeline.md` |
+| choosing content ownership and composing visual/audio contributions | `references/production/tracks.md` |
+| presenting existing Timeline footage with broad or local Uses, a moving viewport or a custom Performance Style | `references/production/performance.md` |
+| writing a project Track with new layout, semantic events or persistent state | `references/production/track-authoring.md` |
+| drawing a component's elements, animation, resources or prepared surfaces | `references/production/component-visuals.md` |
+| writing a Caption family with new word relationships, scheduling or layout | `references/production/caption-authoring.md` |
+| `plan`, Provider pricing information, `build`, a retry or interrupted submission, following work, Results and exports | `references/production/builds.md` |
+| showing the editable work before export: Comments, Studio timeline, parameters, timestamped feedback and interface language | `references/production/studio.md` |
+| giving a component useful timeline entities, picture selection and author controls | `references/production/studio-companions.md` |
+| Film assembly, pure MG with authored time, picture and sound, final rendering or a selected frame interval | `references/production/rendering.md` |
+| exact frames or paginated grids of an existing production, without a new render Build | `references/production/snapshots.md` |
+| judging the preview or finished Result and deciding what to fix | `references/production/review.md` |
+| recognizing a whole-work format, combining formats, or discovering another directing Craft | `references/playbooks/index.md` |
+
+Several rows can apply at once; read what the work actually asks for, and return to a room whenever a
+preview or Result raises its question again. These references explain production use; installed
+package vocabulary and package-local documentation supply component-specific attributes, APIs and
+model limits.

package/skills/using-vvicat-ai-short-studio-cli/references/hypit/creation/brief.md

@@ -0,0 +1,93 @@
+# Brief and Treatment
+
+Read this whenever a target video is being defined, whether it begins from a reference, a loose idea,
+an existing project, or a requested revision.
+
+## Brief preserves user authority
+
+`BRIEF.md` records what the user wants and what only the user can authoritatively supply. It can be as
+short as one sentence when that sentence is sufficient:
+
+> Faithfully recreate this reference, but replace the presenter with the cat in `assets/miso.jpg` and
+> the product with Hypit.
+
+Add only facts that matter to the work, such as:
+
+- the intended outcome, audience, platform, deliverable, or business purpose;
+- the claim, product truth, offer, CTA, language, and facts that must remain accurate;
+- references and what the user wants inherited from each;
+- requested replacements, additions, removals, or style changes;
+- private identity assets and exact brand material;
+- hard duration, format, budget, or delivery constraints;
+- choices the user explicitly reserves for themselves.
+
+Quote or closely preserve the user's wording where reinterpretation could change the request. Do not
+expand an example video's Hook into a format rule or mix implementation choices into the Brief.
+
+In a faithful adaptation, unmentioned relationships normally inherit from the reference: structure,
+the role of each layer, the promise/payoff relationship, and the visual or audio systems that make the
+piece work. This is a starting interpretation, not pixel copying. Ask the user only when the available
+facts leave materially different goals, private facts, meaningful value choices, deliverables, or
+spending authority unresolved. Routine casting, art direction, shot choice, Caption treatment,
+component design, prompts, and implementation belong to the Agent.
+
+Preserve the user's agreed paid scope here as a production constraint: the billing accounts identified
+by non-secret labels or Endpoint references, the work they cover, and the accepted estimate, range or
+budget. Retain any limits the user attached to that agreement. Distinguish your proposed estimate
+from what the user has accepted, and an estimate from a firm spending ceiling. Keep the agreement
+current when the user changes it so another conversation can continue under the same authority.
+Record their local or hosted setup choices and accepted preparation in the same ordinary language.
+The Runtime Profile expresses how to execute those choices; Brief preserves what the user agreed to.
+[Builds](../production/builds.md#work-within-the-agreed-paid-scope) owns how it applies to paid work.
+
+## Treatment is the director's answer
+
+`TREATMENT.md` turns the Brief, relevant reference understanding, and current creative judgment into
+one complete creative design for the new work. It can cover:
+
+- the creative premise and viewer experience;
+- story movement, Hook, reveal, payoff, and CTA;
+- target pacing and the jobs of major passages;
+- character, performance, camera, locations, and visual world;
+- A-roll, B-roll, Caption, Typography, MG, Effect, and Audio systems that the target actually needs;
+- how requested transformations propagate through those systems;
+- which generated or supplied media will act as identity and continuity anchors;
+- open creative questions that genuinely prevent the design from becoming specific.
+
+Write in director language. The Treatment may say that a ranking portrait accumulates into a board or
+that a second podcast angle reverses the eye line while preserving the shared counter and light. It
+does not need package names, element attributes, provider selection, Build order, or Result ids. Those
+belong to production files.
+
+Describe how the intended appeal reaches the viewer. If contrast carries the premise, say what
+expectation the piece sets up and how its words, situation, reveal or response play with it. The
+difference can suggest an idea; the piece still needs to express what makes that idea compelling.
+Give the performer a clear attitude toward the subject and listener. Let
+[voice direction](../playbooks/craft/voice-direction.md) and
+[video direction](../playbooks/craft/video-direction.md) carry the choice into casting and performance.
+
+Reference Analysis says why the old piece works; Treatment says what the new piece will be. Original
+work reaches Treatment from the Brief, relevant examples, and the Agent's judgment rather than from
+one dominant reference. These are different sources of creative evidence.
+
+## Keep one formal Script
+
+The spoken wording becomes authoritative only in the Author Source's `<script>`. During drafting, copy
+may live in `drafts/`; once adopted, move it into Source and stop maintaining a second full transcript
+in Brief or Treatment. Brief can preserve mandatory claims or exact user-supplied phrases. Treatment
+can describe what each passage must accomplish. Source owns the actual words, roles, Cue breaks,
+Selections, and Moments.
+
+## Revise the owner of the changed fact
+
+- A changed user goal, claim, constraint, or requested substitution changes the Brief.
+- A changed story, shot logic, visual system, performance, or creative approach changes the Treatment.
+- A prompt refinement, component geometry correction, Candidate choice, or timing-expression fix that
+  preserves the same design changes Source, Recipe, Run, a project package, or generation input—not
+  the Treatment.
+- New evidence about the reference changes its Analysis or Timeline; it may then cause the director to
+  reconsider Treatment.
+
+Studio and built Results make the current design visible. If the work looks wrong because the
+design itself was wrong, revise Treatment. If the design is sound and its implementation is wrong,
+repair the production. Brief changes only when the user's truth changes.