agentcut 0.2.26 → 0.2.28

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (97) hide show
  1. package/README.md +177 -177
  2. package/dist/studio/agents/claude.js +3 -2
  3. package/dist/studio/agents/claude.js.map +1 -1
  4. package/dist/studio/chat.js +1 -1
  5. package/dist/studio/chat.js.map +1 -1
  6. package/dist/studio/cli.js +24 -24
  7. package/dist/studio/download.d.ts +24 -0
  8. package/dist/studio/download.js +234 -0
  9. package/dist/studio/download.js.map +1 -0
  10. package/dist/studio/host.js +8 -0
  11. package/dist/studio/host.js.map +1 -1
  12. package/dist/studio/housekeeping.d.ts +2 -2
  13. package/dist/studio/housekeeping.js +18 -17
  14. package/dist/studio/housekeeping.js.map +1 -1
  15. package/dist/studio/release-cursor.js +21 -21
  16. package/dist/studio/release-video.js +10 -10
  17. package/dist/studio/schema.d.ts +102 -0
  18. package/dist/studio/schema.js +5 -0
  19. package/dist/studio/schema.js.map +1 -1
  20. package/dist/studio/tools.js +7 -0
  21. package/dist/studio/tools.js.map +1 -1
  22. package/package.json +56 -56
  23. package/template/AGENTS.md +14 -14
  24. package/template/components/README.md +70 -70
  25. package/template/components/before-after/BeforeAfter.tsx +89 -89
  26. package/template/components/catalog.ts +107 -107
  27. package/template/components/cinematic/Device3D.tsx +324 -324
  28. package/template/components/cinematic/devices3d/display-model.ts +184 -184
  29. package/template/components/cinematic/devices3d/iphone-model.ts +643 -643
  30. package/template/components/cinematic/devices3d/macbook-model.ts +608 -608
  31. package/template/components/cinematic/devices3d/models.ts +657 -657
  32. package/template/components/cinematic/devices3d/runtime.ts +267 -267
  33. package/template/components/cinematic/math.ts +100 -100
  34. package/template/components/color/grade-effect.ts +650 -650
  35. package/template/components/color/grade.ts +512 -512
  36. package/template/components/color/looks.ts +154 -154
  37. package/template/components/countdown/Countdown.tsx +166 -166
  38. package/template/components/dot-trace-title/DotTraceTitle.tsx +181 -181
  39. package/template/components/dot-trace-title/meta.json +51 -51
  40. package/template/components/generate/GenerateReveal.tsx +381 -381
  41. package/template/components/hook-card/HookCard.tsx +554 -554
  42. package/template/components/index.ts +199 -199
  43. package/template/components/lib.ts +191 -191
  44. package/template/components/line-diagram/LineDiagram.tsx +205 -205
  45. package/template/components/line-diagram/meta.json +215 -215
  46. package/template/components/list-card/ListCard.tsx +104 -104
  47. package/template/components/live-clip.ts +75 -75
  48. package/template/components/looks.tsx +1447 -1447
  49. package/template/components/loops/LoopCanvas.tsx +132 -132
  50. package/template/components/loops/engine.ts +184 -184
  51. package/template/components/loops/library.ts +667 -667
  52. package/template/components/loops/library2.ts +777 -777
  53. package/template/components/motion-loop/MotionLoop.tsx +37 -37
  54. package/template/components/motion-loop/meta.json +311 -311
  55. package/template/components/props.ts +73 -73
  56. package/template/components/quote-card/QuoteCard.tsx +71 -71
  57. package/template/components/style-layer.tsx +233 -233
  58. package/template/components/styles.ts +113 -113
  59. package/template/components/types.ts +66 -66
  60. package/template/components/word-pop/WordPop.tsx +59 -59
  61. package/template/components/word-stack/WordStack.tsx +122 -122
  62. package/template/presets/charcoal-sketch/PROMPT.md +48 -48
  63. package/template/presets/charcoal-sketch/scripts/duck_music.py +34 -34
  64. package/template/presets/punk-cut-paper/scenes/Motif.tsx +376 -376
  65. package/template/presets/punk-cut-paper/scenes/Photo.tsx +73 -73
  66. package/template/presets/punk-cut-paper/scenes/Ransom.tsx +119 -119
  67. package/template/runtime/composition.tsx +1207 -1189
  68. package/template/runtime/helpers.tsx +230 -230
  69. package/template/runtime/index.tsx +26 -22
  70. package/template/runtime/types.ts +324 -315
  71. package/template/skill/SKILL.md +188 -187
  72. package/template/skill/references/broll.md +44 -44
  73. package/template/skill/references/browser-export.md +61 -61
  74. package/template/skill/references/cinematic.md +206 -206
  75. package/template/skill/references/color.md +79 -79
  76. package/template/skill/references/craft.md +97 -97
  77. package/template/skill/references/editing-styles.md +57 -57
  78. package/template/skill/references/feature-launch.md +34 -34
  79. package/template/skill/references/footage.md +72 -72
  80. package/template/skill/references/format.md +145 -142
  81. package/template/skill/references/how-to.md +146 -146
  82. package/template/skill/references/launch-direction.md +89 -89
  83. package/template/skill/references/loops.md +151 -151
  84. package/template/skill/references/mcp-external.md +19 -19
  85. package/template/skill/references/performance.md +93 -93
  86. package/template/skill/references/person-cutout.md +19 -19
  87. package/template/skill/references/presets.md +60 -60
  88. package/template/skill/references/product-launch.md +134 -134
  89. package/template/skill/references/release-capture.md +53 -53
  90. package/template/skill/references/sound.md +167 -166
  91. package/template/skill/references/style-spy.md +160 -160
  92. package/template/skill/references/website-howto.md +45 -45
  93. package/template/starter/.studio/chat.json +1 -1
  94. package/template/starter/layers.json +46 -46
  95. package/template/starter/notes.md +4 -4
  96. package/template/starter/project.json +13 -13
  97. package/template/starter/scenes/Title.tsx +38 -38
@@ -1,146 +1,146 @@
1
- # How-to
2
-
3
- Help a viewer complete one real task and recognize success. Use this guide for the How-to action,
4
- tutorial requests and software walkthrough videos. The user's brief, uploaded material, existing edit,
5
- selected style and music take priority. This is not a fixed scene sequence or a promotional film.
6
-
7
- ## Establish the task before searching
8
-
9
- The studio asks locally when the request is empty. If a bare request reaches the agent without a
10
- task, brief, recording or relevant project material, ask immediately: "What should viewers learn to
11
- do? Add a URL, recording, or a short description of the task." Stop before tool calls, source or
12
- library searches, planning or rendering. A project name, generic earlier request, music choice or
13
- unrelated shared stock does not establish a task. A known product alone may still lack a procedure.
14
-
15
- This also applies when How-to is clicked while viewing a finished launch or another populated video.
16
- The old edit, its incidental assets and prior launch conversation do not identify the new tutorial's
17
- task. Ask locally before creating a destination or sending to the agent. An explicit current task,
18
- genuinely established tutorial task, or material deliberately attached for the tutorial can proceed.
19
- Keep project uploads available for inspection after the user answers; do not discard them.
20
-
21
- With material, inspect the current project and attachments first. Read `references/format.md`,
22
- `references/footage.md` for recordings, and `references/website-howto.md` for website execution and
23
- tool recovery. Use media information, source frames and transcripts to find complete actions and
24
- their results. Do not ask the user to repeat facts already in the brief or a visible recording.
25
- If one crucial task detail remains missing, ask that one question and continue work that is clear.
26
- When a user reply is required, state the exact missing input plainly, for example
27
- "Question for you: Which voice should this use?" or "Still blocked: I need a recording of the task."
28
- Do not bury the needed action beneath a long completion update or imply that generation continues.
29
-
30
- ## Obtain the real UI from a task-only brief
31
-
32
- A request such as "how to add a style to Agentcut" supplies a task. Do not make the user also ask
33
- for screenshots, captions or an edited video. Proactively obtain authentic evidence:
34
-
35
- 1. Check relevant captures or recordings already in the target project's assets and its supplied
36
- source material. Reuse them only if they show the current labels, complete actions and success state.
37
- 2. Use the supplied or already-known product URL or an already-running local preview. Read the
38
- relevant routes and control labels from configured source folders if that helps locate the task.
39
- A source-code read locates controls; it is not a visual or proof that an action works. Do not
40
- search the home folder for identity or start/restart the user's services as part of discovery.
41
- 3. Use an available permitted browser capture tool. Prefer a connected browser automation tool
42
- when it supports actual screenshots/recording. Otherwise the helper includes `agent-browser`:
43
- read `agent-browser skills get core` and its video-recording reference for the installed version,
44
- use a named session, open the known URL, inspect the live controls, and take real screenshots or
45
- a recording into the new video's `assets/`. Inspect before each action and re-inspect afterward.
46
- The installed CLI supports `screenshot <path>` and `record start <path.webm> --cursor`, followed
47
- by planned actions and `record stop`. Use only supported commands from its local documentation.
48
- 4. Demonstrate the requested task in prepared safe demo state, retaining the real pointer/action,
49
- response and final success state. Do not modify the user's original video to make tutorial footage.
50
- For Agentcut, use a disposable safe demo video rather than changing the completed launch. Reuse
51
- existing captures if obtaining that safe state is not possible under the current permissions.
52
- 5. If sign-in, access, an unknown URL, blocked network permissions or capture capability prevents
53
- this, ask for the smallest missing link or recording. The user signs in directly; never request
54
- credentials, cookies or tokens. Do not fabricate screens, bypass a block, or claim code proves UI.
55
-
56
- `agentcut_capture_frames` captures the edited composition, not an arbitrary website. The release-job
57
- API still supports announcement only; do not submit a how-to job to it or pretend it captured a task.
58
- After authentic material exists, add accurate captions or step labels without waiting for a separate
59
- request, then build and review the editable tutorial. Preserve all earlier edits and source files.
60
-
61
- ## Plan for someone doing the task
62
-
63
- Record in `notes.md`: the intended viewer, their starting state and prerequisites, the task they
64
- will complete, and the visible evidence that confirms success. Show the direction in a few lines.
65
- For example, "Create a project from a preset" needs the real starting screen, the preset selection,
66
- the creation action and the newly opened project. A title that says "Easy presets" is not instruction.
67
-
68
- Use a task title with a clear action. Start with the useful result or a brief orientation, then give
69
- the minimum context needed to begin. Teach the actual procedure in its dependency order. Put any
70
- necessary account, permission or prepared-file condition before the first action that needs it.
71
- Do not turn the tutorial into a tour of every feature. Split distinct goals when the user requests
72
- several tutorials; do not silently omit a required step to hit an arbitrary duration.
73
-
74
- Build a flexible cue sheet. For each step note the source range or real captured view, exact control
75
- label, action, visible reaction, focus region, text or narration cue and readable hold. Mark the
76
- final state that proves success. Choose length from the requested duration and the time needed to
77
- understand the steps. No duration slider or camera vocabulary is required from the user.
78
-
79
- ## Real actions and useful cues
80
-
81
- - Use real screenshots and recordings from the current app or user material as the procedural
82
- evidence. A screenshot can orient the viewer or show a result; it must not imply that an unseen
83
- click was verified. Capture a missing transition or state clearly what remains unverified.
84
- - Follow the main skill's website safety rules. Inspect before capture. Use safe sample content;
85
- do not submit live messages, change settings or expose credentials to make a tutorial. If a write
86
- action needs user preparation or authorization, explain the missing step. Do not invent it.
87
- - Preserve actual labels, cursor targets, menu state, entry values and system feedback. Do not
88
- replace procedural evidence with an imagined UI or pretend a decorative animation is a capture.
89
- Any explanatory reconstruction must be clearly identified and must not be the only proof.
90
- - Show where to act, the action, then its result. Give the viewer a stable pause at meaningful step
91
- boundaries instead of relying on them to discover where to pause. Trim idle waits but retain
92
- feedback that explains progress and completion. Speed up typing only when the entered value and
93
- result remain clear. Keep important errors and their recovery when relevant to the task.
94
- - Use a brief highlight, pointer or close-up on the relevant control as the instruction reaches it.
95
- Do not cue several competing objects. Start wide enough for orientation, move to the detail,
96
- then hold sharp and readable through the action and reaction. Follow cursor metadata when present
97
- (`references/cursor.md`). Keep the current step and progress clear without excessive labels.
98
- - Narration should explain the action as it appears. Use plain action words and exact UI labels.
99
- Do not narrate a click several seconds before or after the visible action. For a silent tutorial,
100
- place concise step instructions next to the demonstrated action and hold them long enough to read.
101
-
102
- ## Brand, library, motion and sound
103
-
104
- Match the app's actual logos, fonts, colors and spacing. Discover useful existing project images,
105
- B-roll, recordings, music and effects even when they are not chat attachments: list project `assets/`
106
- with `agentcut_list_files`, then relevant shared library folders with `scope: "library"`. Follow
107
- pagination and inspect relevant subfolders. Use `assets/...` and `library:...` media paths. Do not scan
108
- other projects or every source directory to guess the task. Reuse known allowed source locations for
109
- brand checks; if one is missing, ask instead of searching the home folder. Tell the user they can
110
- drop a specific missing asset into the Library panel; a second chat attachment is not required.
111
-
112
- Use B-roll only when it explains the task without hiding an essential step. Reuse existing components
113
- and relevant assets; do not generate replacements by default. With website source available, inspect
114
- the exact relevant components rather than reading the whole repository repeatedly.
115
-
116
- Read `references/cinematic.md` when using camera depth or devices. Use existing `Device3D` hardware
117
- for visible phones and computers. Smooth motion, backgrounds and restrained brand effects can frame
118
- the tutorial, but essential UI must stay sharp, upright enough to read and clear of captions. Blur,
119
- perspective and zoom should lead into a readable hold. Do not carry launch-film energy through every
120
- instructional step. Keep optional backgrounds quiet during the action.
121
-
122
- Read `references/sound.md`. Preserve a selected song; balance it below speech and keep busy music or
123
- effects away from difficult steps. Use a small sound on a meaningful action, not every pointer move.
124
- Caption narration accurately using the transcription workflow. Correct names, numbers and UI labels;
125
- include meaningful non-speech audio when needed to understand the task. Captions must follow the
126
- audio and avoid controls, results and the cursor target. Do not require voice for a silent brief.
127
-
128
- ## Success and review
129
-
130
- Read `references/efficient-review.md`. Group independent file/guide reads and target changed shots
131
- during revisions. Broaden after shared or timing changes; retain the complete final review below.
132
-
133
- End at the real successful state. Tell the viewer what to check, for example the saved item appearing
134
- in its list or an exported file opening correctly. An optional short "Try it with your own project"
135
- prompt can encourage practice. Do not claim that an extra replay or recap guarantees learning.
136
-
137
- Use the normal build and review loop: editable scene, text, footage and audio clips, status after
138
- changes, source-frame checks, wide and mobile contact sheets, audio measurements and heavy-scene
139
- playback checks. Check that a novice could follow every action without guessing a hidden step.
140
- Check the order, cue timing, pointer visibility, label accuracy, reading time, final state and caption
141
- placement. Retain both-format and sound review. Export only when requested.
142
-
143
- Reuse current material and passed checks. Check changed regions first, then review the complete edit
144
- in both formats. Run page-heavy checks in sequence as `website-howto.md` requires. If a tool stalls,
145
- inspect active work before retrying. Record what passed and what remains blocked; do not claim a
146
- build alone proves instructional accuracy.
1
+ # How-to
2
+
3
+ Help a viewer complete one real task and recognize success. Use this guide for the How-to action,
4
+ tutorial requests and software walkthrough videos. The user's brief, uploaded material, existing edit,
5
+ selected style and music take priority. This is not a fixed scene sequence or a promotional film.
6
+
7
+ ## Establish the task before searching
8
+
9
+ The studio asks locally when the request is empty. If a bare request reaches the agent without a
10
+ task, brief, recording or relevant project material, ask immediately: "What should viewers learn to
11
+ do? Add a URL, recording, or a short description of the task." Stop before tool calls, source or
12
+ library searches, planning or rendering. A project name, generic earlier request, music choice or
13
+ unrelated shared stock does not establish a task. A known product alone may still lack a procedure.
14
+
15
+ This also applies when How-to is clicked while viewing a finished launch or another populated video.
16
+ The old edit, its incidental assets and prior launch conversation do not identify the new tutorial's
17
+ task. Ask locally before creating a destination or sending to the agent. An explicit current task,
18
+ genuinely established tutorial task, or material deliberately attached for the tutorial can proceed.
19
+ Keep project uploads available for inspection after the user answers; do not discard them.
20
+
21
+ With material, inspect the current project and attachments first. Read `references/format.md`,
22
+ `references/footage.md` for recordings, and `references/website-howto.md` for website execution and
23
+ tool recovery. Use media information, source frames and transcripts to find complete actions and
24
+ their results. Do not ask the user to repeat facts already in the brief or a visible recording.
25
+ If one crucial task detail remains missing, ask that one question and continue work that is clear.
26
+ When a user reply is required, state the exact missing input plainly, for example
27
+ "Question for you: Which voice should this use?" or "Still blocked: I need a recording of the task."
28
+ Do not bury the needed action beneath a long completion update or imply that generation continues.
29
+
30
+ ## Obtain the real UI from a task-only brief
31
+
32
+ A request such as "how to add a style to Agentcut" supplies a task. Do not make the user also ask
33
+ for screenshots, captions or an edited video. Proactively obtain authentic evidence:
34
+
35
+ 1. Check relevant captures or recordings already in the target project's assets and its supplied
36
+ source material. Reuse them only if they show the current labels, complete actions and success state.
37
+ 2. Use the supplied or already-known product URL or an already-running local preview. Read the
38
+ relevant routes and control labels from configured source folders if that helps locate the task.
39
+ A source-code read locates controls; it is not a visual or proof that an action works. Do not
40
+ search the home folder for identity or start/restart the user's services as part of discovery.
41
+ 3. Use an available permitted browser capture tool. Prefer a connected browser automation tool
42
+ when it supports actual screenshots/recording. Otherwise the helper includes `agent-browser`:
43
+ read `agent-browser skills get core` and its video-recording reference for the installed version,
44
+ use a named session, open the known URL, inspect the live controls, and take real screenshots or
45
+ a recording into the new video's `assets/`. Inspect before each action and re-inspect afterward.
46
+ The installed CLI supports `screenshot <path>` and `record start <path.webm> --cursor`, followed
47
+ by planned actions and `record stop`. Use only supported commands from its local documentation.
48
+ 4. Demonstrate the requested task in prepared safe demo state, retaining the real pointer/action,
49
+ response and final success state. Do not modify the user's original video to make tutorial footage.
50
+ For Agentcut, use a disposable safe demo video rather than changing the completed launch. Reuse
51
+ existing captures if obtaining that safe state is not possible under the current permissions.
52
+ 5. If sign-in, access, an unknown URL, blocked network permissions or capture capability prevents
53
+ this, ask for the smallest missing link or recording. The user signs in directly; never request
54
+ credentials, cookies or tokens. Do not fabricate screens, bypass a block, or claim code proves UI.
55
+
56
+ `agentcut_capture_frames` captures the edited composition, not an arbitrary website. The release-job
57
+ API still supports announcement only; do not submit a how-to job to it or pretend it captured a task.
58
+ After authentic material exists, add accurate captions or step labels without waiting for a separate
59
+ request, then build and review the editable tutorial. Preserve all earlier edits and source files.
60
+
61
+ ## Plan for someone doing the task
62
+
63
+ Record in `notes.md`: the intended viewer, their starting state and prerequisites, the task they
64
+ will complete, and the visible evidence that confirms success. Show the direction in a few lines.
65
+ For example, "Create a project from a preset" needs the real starting screen, the preset selection,
66
+ the creation action and the newly opened project. A title that says "Easy presets" is not instruction.
67
+
68
+ Use a task title with a clear action. Start with the useful result or a brief orientation, then give
69
+ the minimum context needed to begin. Teach the actual procedure in its dependency order. Put any
70
+ necessary account, permission or prepared-file condition before the first action that needs it.
71
+ Do not turn the tutorial into a tour of every feature. Split distinct goals when the user requests
72
+ several tutorials; do not silently omit a required step to hit an arbitrary duration.
73
+
74
+ Build a flexible cue sheet. For each step note the source range or real captured view, exact control
75
+ label, action, visible reaction, focus region, text or narration cue and readable hold. Mark the
76
+ final state that proves success. Choose length from the requested duration and the time needed to
77
+ understand the steps. No duration slider or camera vocabulary is required from the user.
78
+
79
+ ## Real actions and useful cues
80
+
81
+ - Use real screenshots and recordings from the current app or user material as the procedural
82
+ evidence. A screenshot can orient the viewer or show a result; it must not imply that an unseen
83
+ click was verified. Capture a missing transition or state clearly what remains unverified.
84
+ - Follow the main skill's website safety rules. Inspect before capture. Use safe sample content;
85
+ do not submit live messages, change settings or expose credentials to make a tutorial. If a write
86
+ action needs user preparation or authorization, explain the missing step. Do not invent it.
87
+ - Preserve actual labels, cursor targets, menu state, entry values and system feedback. Do not
88
+ replace procedural evidence with an imagined UI or pretend a decorative animation is a capture.
89
+ Any explanatory reconstruction must be clearly identified and must not be the only proof.
90
+ - Show where to act, the action, then its result. Give the viewer a stable pause at meaningful step
91
+ boundaries instead of relying on them to discover where to pause. Trim idle waits but retain
92
+ feedback that explains progress and completion. Speed up typing only when the entered value and
93
+ result remain clear. Keep important errors and their recovery when relevant to the task.
94
+ - Use a brief highlight, pointer or close-up on the relevant control as the instruction reaches it.
95
+ Do not cue several competing objects. Start wide enough for orientation, move to the detail,
96
+ then hold sharp and readable through the action and reaction. Follow cursor metadata when present
97
+ (`references/cursor.md`). Keep the current step and progress clear without excessive labels.
98
+ - Narration should explain the action as it appears. Use plain action words and exact UI labels.
99
+ Do not narrate a click several seconds before or after the visible action. For a silent tutorial,
100
+ place concise step instructions next to the demonstrated action and hold them long enough to read.
101
+
102
+ ## Brand, library, motion and sound
103
+
104
+ Match the app's actual logos, fonts, colors and spacing. Discover useful existing project images,
105
+ B-roll, recordings, music and effects even when they are not chat attachments: list project `assets/`
106
+ with `agentcut_list_files`, then relevant shared library folders with `scope: "library"`. Follow
107
+ pagination and inspect relevant subfolders. Use `assets/...` and `library:...` media paths. Do not scan
108
+ other projects or every source directory to guess the task. Reuse known allowed source locations for
109
+ brand checks; if one is missing, ask instead of searching the home folder. Tell the user they can
110
+ drop a specific missing asset into the Library panel; a second chat attachment is not required.
111
+
112
+ Use B-roll only when it explains the task without hiding an essential step. Reuse existing components
113
+ and relevant assets; do not generate replacements by default. With website source available, inspect
114
+ the exact relevant components rather than reading the whole repository repeatedly.
115
+
116
+ Read `references/cinematic.md` when using camera depth or devices. Use existing `Device3D` hardware
117
+ for visible phones and computers. Smooth motion, backgrounds and restrained brand effects can frame
118
+ the tutorial, but essential UI must stay sharp, upright enough to read and clear of captions. Blur,
119
+ perspective and zoom should lead into a readable hold. Do not carry launch-film energy through every
120
+ instructional step. Keep optional backgrounds quiet during the action.
121
+
122
+ Read `references/sound.md`. Preserve a selected song; balance it below speech and keep busy music or
123
+ effects away from difficult steps. Use a small sound on a meaningful action, not every pointer move.
124
+ Caption narration accurately using the transcription workflow. Correct names, numbers and UI labels;
125
+ include meaningful non-speech audio when needed to understand the task. Captions must follow the
126
+ audio and avoid controls, results and the cursor target. Do not require voice for a silent brief.
127
+
128
+ ## Success and review
129
+
130
+ Read `references/efficient-review.md`. Group independent file/guide reads and target changed shots
131
+ during revisions. Broaden after shared or timing changes; retain the complete final review below.
132
+
133
+ End at the real successful state. Tell the viewer what to check, for example the saved item appearing
134
+ in its list or an exported file opening correctly. An optional short "Try it with your own project"
135
+ prompt can encourage practice. Do not claim that an extra replay or recap guarantees learning.
136
+
137
+ Use the normal build and review loop: editable scene, text, footage and audio clips, status after
138
+ changes, source-frame checks, wide and mobile contact sheets, audio measurements and heavy-scene
139
+ playback checks. Check that a novice could follow every action without guessing a hidden step.
140
+ Check the order, cue timing, pointer visibility, label accuracy, reading time, final state and caption
141
+ placement. Retain both-format and sound review. Export only when requested.
142
+
143
+ Reuse current material and passed checks. Check changed regions first, then review the complete edit
144
+ in both formats. Run page-heavy checks in sequence as `website-howto.md` requires. If a tool stalls,
145
+ inspect active work before retrying. Record what passed and what remains blocked; do not claim a
146
+ build alone proves instructional accuracy.
@@ -1,89 +1,89 @@
1
- # Launch direction: from brief to checked shots
2
-
3
- Use this with `product-launch.md` or `feature-launch.md` for a new film or a major revision.
4
- For a small edit, keep the existing direction and check the changed shots. The user's script,
5
- reference, selected style and format take priority. Keep decisions in the project's `notes.md`.
6
- This guide uses Agentcut tools and frame timing; it does not require another video engine.
7
-
8
- ## Choose a story that the images can tell
9
-
10
- Compare two possible stories using the available evidence, not just two opening titles. For example,
11
- show a finished result and then how it was made, or follow one real input through an action to its
12
- result. Pick the clearest story and record why. Continue without an approval stop unless the user
13
- asked to choose a direction. Do not repeat this exercise for an approved script or storyboard.
14
-
15
- Keep the same recognizable file, query, project or other subject through the demonstration when
16
- the source supports it. A viewer should see what changed. Unrelated screens with benefit labels
17
- do not explain a workflow. Do not fabricate a failure in the old workflow to create tension.
18
-
19
- ## Turn the direction into build decisions
20
-
21
- Before building scenes, add a compact direction and shot table to `notes.md`:
22
-
23
- - **Look:** actual background and text colors, accent use, font files/families, weights, text sizes,
24
- margins and product framing for each output format. Use selected style tokens where available.
25
- Replace vague words such as "premium" with these choices. Keep meaningful product status colors.
26
- - **Motion:** entrance, camera and exit durations in frames, easing or spring settings, and the
27
- settled reading window. Choose motion by purpose; do not give every element the same entrance.
28
- - **Avoid for this film:** identify likely distractions, such as repeated feature cards, tiny UI
29
- inside a large empty stage, or decoration that competes with proof. This is specific to the brief;
30
- do not ban a color, material or effect that the user's style needs.
31
-
32
- | Frames [start, end) | What the viewer learns | Source and visible change | Framing and main move | Exact words and settled read frames | Sound cue | Link to next shot |
33
- | --- | --- | --- | --- | --- | --- | --- |
34
-
35
- Fill one row per shot. Use real asset paths and source ranges, not placeholder evidence. Keep the
36
- table aligned with the timeline after timing changes. Plan the final readable frame before `end`.
37
- Do not add claims, voice or captions just to fill the table.
38
-
39
- For each demonstration, establish where the task happens, bring the relevant action into clear
40
- view, then show its result in context. These can be parts of one shot. A pan across a still image
41
- can explain a layout; it cannot prove an interaction. Keep real footage for the action.
42
-
43
- ## Prove the visual direction early
44
-
45
- Build the opening and the main proof shot first, in story order when possible. Capture their
46
- settled frames in each output format with `agentcut_capture_frames`. Inspect actual words, assets,
47
- framing and contrast before extending that treatment to the rest of the film. A full storyboard
48
- approval step is optional, only when requested; these are working checks in the live project.
49
-
50
- The first frame should give the viewer useful visual context unless the brief calls for darkness.
51
- Give the product enough space for the relevant action to read. At small display size, crop closer
52
- or reduce the words before reducing text size. A full app view establishes context; its incidental
53
- labels do not all need to be readable. Essential labels and results do.
54
-
55
- ## Make motion carry the story
56
-
57
- - Give each shot one main movement. Delay or reduce secondary motion so it does not compete.
58
- Let essential titles and UI settle while the viewer reads. Idle floating is not a demonstration.
59
- - Contrast short transitions with longer action and result holds. As a starting estimate, allow
60
- about `0.5 + 0.3 * wordCount` seconds for a short line after it settles. Validate with the actual
61
- layout and audience; dense UI needs more time. Cut words or decoration to meet a fixed duration.
62
- - Connect shots through a visible action, a continuing subject, matching framing or a deliberate
63
- cut. Name the connection in the shot table. Do not require a transition quota or a new effect at
64
- every cut. A clear hard cut is useful when a morph would distort the evidence.
65
- - Keep important labels sharp during the reading window. Motion blur belongs to movement, not
66
- the proof hold. Use the existing component catalog and `cinematic.md` tools where suitable.
67
- Follow `browser-export.md`; a browser-only effect is not proof that an export works.
68
- - Use source action times, narration timings or analyzed music cues. For a regular beat grid,
69
- calculate each frame from its beat index and round once; repeated rounded intervals cause drift.
70
-
71
- ## Review the cuts and the meaning
72
-
73
- Keep the main skill's full picture, sound and performance review. Add these checks to it:
74
-
75
- 1. Inspect frame 0, the settled proof and the final readable frame in each format. Read the shot
76
- sequence as a new viewer. Without the headline, is the promised change still visible?
77
- 2. For each cut at frame `c`, sample `c - 1` and `c`, plus nearby frames across the transition.
78
- Clamp samples to the video bounds. For a longer move, sample intermediate frames too. Look for
79
- blank gaps, duplicated subjects, jumps in labels, obscured results and conflicting motion.
80
- 3. Inspect essential words and UI at a small display size, about 360 px wide where available.
81
- If a tool cannot show that size, record this limit; do not claim a small-screen check passed.
82
- 4. Record concrete issues as `frame / variant / issue / change / recheck result` in `notes.md`.
83
- Fix wrong claims, unreadable evidence and broken transitions before decorative details. Recheck
84
- changed shots using `efficient-review.md`; timing or shared changes require broader checks.
85
-
86
- At hand-off, state what was checked and any remaining weak shot or missing evidence. A build pass
87
- only proves the project compiles. Do not describe a film as visually verified without viewing its
88
- captures, or say sound was heard when it was only measured.
89
-
1
+ # Launch direction: from brief to checked shots
2
+
3
+ Use this with `product-launch.md` or `feature-launch.md` for a new film or a major revision.
4
+ For a small edit, keep the existing direction and check the changed shots. The user's script,
5
+ reference, selected style and format take priority. Keep decisions in the project's `notes.md`.
6
+ This guide uses Agentcut tools and frame timing; it does not require another video engine.
7
+
8
+ ## Choose a story that the images can tell
9
+
10
+ Compare two possible stories using the available evidence, not just two opening titles. For example,
11
+ show a finished result and then how it was made, or follow one real input through an action to its
12
+ result. Pick the clearest story and record why. Continue without an approval stop unless the user
13
+ asked to choose a direction. Do not repeat this exercise for an approved script or storyboard.
14
+
15
+ Keep the same recognizable file, query, project or other subject through the demonstration when
16
+ the source supports it. A viewer should see what changed. Unrelated screens with benefit labels
17
+ do not explain a workflow. Do not fabricate a failure in the old workflow to create tension.
18
+
19
+ ## Turn the direction into build decisions
20
+
21
+ Before building scenes, add a compact direction and shot table to `notes.md`:
22
+
23
+ - **Look:** actual background and text colors, accent use, font files/families, weights, text sizes,
24
+ margins and product framing for each output format. Use selected style tokens where available.
25
+ Replace vague words such as "premium" with these choices. Keep meaningful product status colors.
26
+ - **Motion:** entrance, camera and exit durations in frames, easing or spring settings, and the
27
+ settled reading window. Choose motion by purpose; do not give every element the same entrance.
28
+ - **Avoid for this film:** identify likely distractions, such as repeated feature cards, tiny UI
29
+ inside a large empty stage, or decoration that competes with proof. This is specific to the brief;
30
+ do not ban a color, material or effect that the user's style needs.
31
+
32
+ | Frames [start, end) | What the viewer learns | Source and visible change | Framing and main move | Exact words and settled read frames | Sound cue | Link to next shot |
33
+ | --- | --- | --- | --- | --- | --- | --- |
34
+
35
+ Fill one row per shot. Use real asset paths and source ranges, not placeholder evidence. Keep the
36
+ table aligned with the timeline after timing changes. Plan the final readable frame before `end`.
37
+ Do not add claims, voice or captions just to fill the table.
38
+
39
+ For each demonstration, establish where the task happens, bring the relevant action into clear
40
+ view, then show its result in context. These can be parts of one shot. A pan across a still image
41
+ can explain a layout; it cannot prove an interaction. Keep real footage for the action.
42
+
43
+ ## Prove the visual direction early
44
+
45
+ Build the opening and the main proof shot first, in story order when possible. Capture their
46
+ settled frames in each output format with `agentcut_capture_frames`. Inspect actual words, assets,
47
+ framing and contrast before extending that treatment to the rest of the film. A full storyboard
48
+ approval step is optional, only when requested; these are working checks in the live project.
49
+
50
+ The first frame should give the viewer useful visual context unless the brief calls for darkness.
51
+ Give the product enough space for the relevant action to read. At small display size, crop closer
52
+ or reduce the words before reducing text size. A full app view establishes context; its incidental
53
+ labels do not all need to be readable. Essential labels and results do.
54
+
55
+ ## Make motion carry the story
56
+
57
+ - Give each shot one main movement. Delay or reduce secondary motion so it does not compete.
58
+ Let essential titles and UI settle while the viewer reads. Idle floating is not a demonstration.
59
+ - Contrast short transitions with longer action and result holds. As a starting estimate, allow
60
+ about `0.5 + 0.3 * wordCount` seconds for a short line after it settles. Validate with the actual
61
+ layout and audience; dense UI needs more time. Cut words or decoration to meet a fixed duration.
62
+ - Connect shots through a visible action, a continuing subject, matching framing or a deliberate
63
+ cut. Name the connection in the shot table. Do not require a transition quota or a new effect at
64
+ every cut. A clear hard cut is useful when a morph would distort the evidence.
65
+ - Keep important labels sharp during the reading window. Motion blur belongs to movement, not
66
+ the proof hold. Use the existing component catalog and `cinematic.md` tools where suitable.
67
+ Follow `browser-export.md`; a browser-only effect is not proof that an export works.
68
+ - Use source action times, narration timings or analyzed music cues. For a regular beat grid,
69
+ calculate each frame from its beat index and round once; repeated rounded intervals cause drift.
70
+
71
+ ## Review the cuts and the meaning
72
+
73
+ Keep the main skill's full picture, sound and performance review. Add these checks to it:
74
+
75
+ 1. Inspect frame 0, the settled proof and the final readable frame in each format. Read the shot
76
+ sequence as a new viewer. Without the headline, is the promised change still visible?
77
+ 2. For each cut at frame `c`, sample `c - 1` and `c`, plus nearby frames across the transition.
78
+ Clamp samples to the video bounds. For a longer move, sample intermediate frames too. Look for
79
+ blank gaps, duplicated subjects, jumps in labels, obscured results and conflicting motion.
80
+ 3. Inspect essential words and UI at a small display size, about 360 px wide where available.
81
+ If a tool cannot show that size, record this limit; do not claim a small-screen check passed.
82
+ 4. Record concrete issues as `frame / variant / issue / change / recheck result` in `notes.md`.
83
+ Fix wrong claims, unreadable evidence and broken transitions before decorative details. Recheck
84
+ changed shots using `efficient-review.md`; timing or shared changes require broader checks.
85
+
86
+ At hand-off, state what was checked and any remaining weak shot or missing evidence. A build pass
87
+ only proves the project compiles. Do not describe a film as visually verified without viewing its
88
+ captures, or say sound was heard when it was only measured.
89
+