agentcut 0.2.26 → 0.2.27

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 (94) 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/tools.js +7 -0
  18. package/dist/studio/tools.js.map +1 -1
  19. package/package.json +56 -56
  20. package/template/AGENTS.md +14 -14
  21. package/template/components/README.md +70 -70
  22. package/template/components/before-after/BeforeAfter.tsx +89 -89
  23. package/template/components/catalog.ts +107 -107
  24. package/template/components/cinematic/Device3D.tsx +324 -324
  25. package/template/components/cinematic/devices3d/display-model.ts +184 -184
  26. package/template/components/cinematic/devices3d/iphone-model.ts +643 -643
  27. package/template/components/cinematic/devices3d/macbook-model.ts +608 -608
  28. package/template/components/cinematic/devices3d/models.ts +657 -657
  29. package/template/components/cinematic/devices3d/runtime.ts +267 -267
  30. package/template/components/cinematic/math.ts +100 -100
  31. package/template/components/color/grade-effect.ts +650 -650
  32. package/template/components/color/grade.ts +512 -512
  33. package/template/components/color/looks.ts +154 -154
  34. package/template/components/countdown/Countdown.tsx +166 -166
  35. package/template/components/dot-trace-title/DotTraceTitle.tsx +181 -181
  36. package/template/components/dot-trace-title/meta.json +51 -51
  37. package/template/components/generate/GenerateReveal.tsx +381 -381
  38. package/template/components/hook-card/HookCard.tsx +554 -554
  39. package/template/components/index.ts +199 -199
  40. package/template/components/lib.ts +191 -191
  41. package/template/components/line-diagram/LineDiagram.tsx +205 -205
  42. package/template/components/line-diagram/meta.json +215 -215
  43. package/template/components/list-card/ListCard.tsx +104 -104
  44. package/template/components/live-clip.ts +75 -75
  45. package/template/components/looks.tsx +1447 -1447
  46. package/template/components/loops/LoopCanvas.tsx +132 -132
  47. package/template/components/loops/engine.ts +184 -184
  48. package/template/components/loops/library.ts +667 -667
  49. package/template/components/loops/library2.ts +777 -777
  50. package/template/components/motion-loop/MotionLoop.tsx +37 -37
  51. package/template/components/motion-loop/meta.json +311 -311
  52. package/template/components/props.ts +73 -73
  53. package/template/components/quote-card/QuoteCard.tsx +71 -71
  54. package/template/components/style-layer.tsx +233 -233
  55. package/template/components/styles.ts +113 -113
  56. package/template/components/types.ts +66 -66
  57. package/template/components/word-pop/WordPop.tsx +59 -59
  58. package/template/components/word-stack/WordStack.tsx +122 -122
  59. package/template/presets/charcoal-sketch/PROMPT.md +48 -48
  60. package/template/presets/charcoal-sketch/scripts/duck_music.py +34 -34
  61. package/template/presets/punk-cut-paper/scenes/Motif.tsx +376 -376
  62. package/template/presets/punk-cut-paper/scenes/Photo.tsx +73 -73
  63. package/template/presets/punk-cut-paper/scenes/Ransom.tsx +119 -119
  64. package/template/runtime/composition.tsx +1189 -1189
  65. package/template/runtime/helpers.tsx +230 -230
  66. package/template/runtime/index.tsx +22 -22
  67. package/template/runtime/types.ts +315 -315
  68. package/template/skill/SKILL.md +186 -187
  69. package/template/skill/references/broll.md +44 -44
  70. package/template/skill/references/browser-export.md +61 -61
  71. package/template/skill/references/cinematic.md +206 -206
  72. package/template/skill/references/color.md +79 -79
  73. package/template/skill/references/craft.md +97 -97
  74. package/template/skill/references/editing-styles.md +57 -57
  75. package/template/skill/references/feature-launch.md +34 -34
  76. package/template/skill/references/footage.md +72 -72
  77. package/template/skill/references/format.md +142 -142
  78. package/template/skill/references/how-to.md +146 -146
  79. package/template/skill/references/launch-direction.md +89 -89
  80. package/template/skill/references/loops.md +151 -151
  81. package/template/skill/references/mcp-external.md +19 -19
  82. package/template/skill/references/performance.md +93 -93
  83. package/template/skill/references/person-cutout.md +19 -19
  84. package/template/skill/references/presets.md +60 -60
  85. package/template/skill/references/product-launch.md +134 -134
  86. package/template/skill/references/release-capture.md +53 -53
  87. package/template/skill/references/sound.md +167 -166
  88. package/template/skill/references/style-spy.md +160 -160
  89. package/template/skill/references/website-howto.md +45 -45
  90. package/template/starter/.studio/chat.json +1 -1
  91. package/template/starter/layers.json +46 -46
  92. package/template/starter/notes.md +4 -4
  93. package/template/starter/project.json +13 -13
  94. package/template/starter/scenes/Title.tsx +38 -38
@@ -1,142 +1,142 @@
1
- # Project format (v1)
2
-
3
- All times are **integer frames** at `project.fps`. Clip `from` is the timeline frame where the clip
4
- starts; `duration` is its length in frames. Inside a clip (scene code, caption words, fades) frames are
5
- **relative to the clip start**.
6
-
7
- ## project.json
8
-
9
- ```json
10
- {
11
- "version": 1,
12
- "name": "Rolino launch",
13
- "fps": 30,
14
- "durationInFrames": 1800,
15
- "background": "#060a16",
16
- "variants": {
17
- "wide": { "width": 1920, "height": 1080 },
18
- "mobile": { "width": 1080, "height": 1920 }
19
- },
20
- "defaultVariant": "wide",
21
- "fonts": [
22
- "Inter:400;600;800",
23
- { "family": "Brand Onest", "src": "assets/fonts/onest-700.woff2", "weight": "700" }
24
- ]
25
- }
26
- ```
27
-
28
- - `durationInFrames` is the export length; keep it equal to the end of the last clip.
29
- - Fonts: Google Fonts specs (`"Family:400;700"`) or local files (preferred for brand fonts: renders
30
- then never depend on Google Fonts). Reference them by `family` in styles.
31
-
32
- ## layers.json
33
-
34
- ```json
35
- {
36
- "version": 1,
37
- "tracks": [
38
- { "id": "captions", "name": "Captions", "kind": "captions", "clips": [] },
39
- { "id": "text", "name": "Titles", "kind": "text", "clips": [] },
40
- { "id": "grain", "name": "Film grain", "kind": "scene", "clips": [] },
41
- { "id": "scenes", "name": "Scenes", "kind": "scene", "clips": [] },
42
- { "id": "voice", "name": "Voice", "kind": "audio", "clips": [] },
43
- { "id": "music", "name": "Music", "kind": "audio", "clips": [] },
44
- { "id": "sfx", "name": "SFX", "kind": "audio", "clips": [] }
45
- ],
46
- "markers": [
47
- { "id": "m-drop", "frame": 204, "label": "Drop", "kind": "beat" },
48
- { "id": "m-reveal", "frame": 198, "label": "Reveal", "kind": "section" }
49
- ]
50
- }
51
- ```
52
-
53
- `tracks[0]` is drawn **on top**; later tracks are drawn underneath. Clips on a track are sorted by
54
- `from`. Clips may overlap only on `scene` and `audio` tracks (use more tracks otherwise).
55
-
56
- Track fields: `id` (kebab-case, unique), `name`, `kind`, `clips`, optional `hidden` (visual), `muted`
57
- (audio/video), `locked` (user lock — don't move locked clips), `volume` (audio track gain).
58
-
59
- Markers (`section` = scene starts, `cue` = moments sounds/animations hit, `beat` = music beats you rely
60
- on) show on the timeline ruler. Keep section markers in sync with scene clips.
61
-
62
- ### Clip fields (all kinds)
63
-
64
- | field | |
65
- |---|---|
66
- | `id` | unique in the project, stable, readable |
67
- | `name` | timeline label (optional) |
68
- | `from`, `duration` | frames |
69
- | `enter`, `exit` | `{ "preset": "fade" \| "slide-up" \| "slide-down" \| "slide-left" \| "slide-right" \| "pop" \| "scale" \| "blur" \| "none", "frames": 12 }` (visual clips) |
70
- | `opacity` | 0..1 (visual clips) |
71
- | `note` | why the clip is there (cue reason) |
72
- | `variants` | per-variant overrides, e.g. `{ "mobile": { "box": {…}, "style": {…} } }` |
73
-
74
- `box` = `{ "x", "y", "width", "height" }` as fractions of the frame (0..1), top-left origin.
75
-
76
- ### Kinds
77
-
78
- **scene** — `{ "scene": "Hook", "props": { … } }` renders `scenes/Hook.tsx`; or
79
- `{ "component": "text-reveal", "props": { … } }` renders a library component (one of the two per clip;
80
- see `references/components.md`).
81
-
82
- **audio** — `{ "src": "assets/voice.wav", "volume": 1, "trimStart": 0, "fadeIn": 0, "fadeOut": 0, "loop": false, "playbackRate": 1, "role": "voice" | "music" | "sfx" | "ambience" }`.
83
- `trimStart` skips frames of the file. Set `duration` from `agentcut_media_info` (frames). An SFX
84
- clip's `from` is the cue frame minus the file's onset (see sound.md).
85
-
86
- **video** — `{ "src", "trimStart", "volume", "muted", "fit": "cover" | "contain", "box", "playbackRate", "grade" }`.
87
- `grade` — colour: `{ "exposure": 0.2, "contrast": 1.1, "temperature": 0.1, "look": "golden-stock" }` and more (fields and workflow:
88
- `references/color.md`). Leave out what you don't change. `inheritGrade: false` keeps the project grade and adjustment layers off it.
89
- Footage from the editor: see `references/footage.md`.
90
-
91
- **image** — `{ "src", "fit", "box", "radius", "grade", "inheritGrade" }`. `inheritGrade: true` also applies the project grade and adjustment layers.
92
-
93
- **adjustment** — `{ "grade" }`. Draws nothing: it grades the footage below it while it runs (`references/color.md`).
94
-
95
- **text** — `{ "text", "box", "style": { "fontFamily", "fontSize" (px at the variant size), "fontWeight", "color", "align", "lineHeight", "letterSpacing", "textTransform", "shadow" } }`. For styled kinetic type use a scene instead.
96
-
97
- **captions** — `{ "words": [{ "text", "from", "to" }], "style": { "preset": "pop" | "karaoke" | "plain", "fontFamily", "fontSize", "fontWeight", "color", "highlight", "position": "bottom" | "center" | "top", "maxWordsPerLine" } }`.
98
- Word `from`/`to` are frames **relative to the clip start**. Build them from `agentcut_transcribe`
99
- (`fromFrame - clip.from`). For custom caption looks, write a scene that takes `words` in props.
100
-
101
- `src` forms: `assets/<file>`, `library:<path>` (workspace library shared by projects), `https://…` (must
102
- allow CORS).
103
-
104
- ## Scenes
105
-
106
- ```tsx
107
- // scenes/Hook.tsx
108
- import { AbsoluteFill, useCurrentFrame } from "remotion";
109
- import { RadialGlow, SPRING, ease, sp, mix, useStudio, type SceneProps } from "agentcut";
110
-
111
- type Props = SceneProps & { title: string; accent: string };
112
-
113
- export default function Hook({ title, accent, width, height, clip }: Props) {
114
- const f = useCurrentFrame(); // 0 at the clip start
115
- const vertical = height > width;
116
- const s = sp(f, 6, SPRING.pop); // spring starting at local frame 6
117
- const out = ease(f, clip.duration - 8, clip.duration);
118
- return (
119
- <AbsoluteFill style={{ background: "linear-gradient(160deg,#0b0b14,#050507)", opacity: 1 - out }}>
120
- <RadialGlow x={0.5} y={0.45} radius={0.5} color={accent} opacity={0.25} />
121
- <AbsoluteFill style={{ alignItems: "center", justifyContent: "center" }}>
122
- <div style={{ fontFamily: "Inter", fontWeight: 900, fontSize: vertical ? 140 : 120,
123
- transform: `translateY(${mix(60, 0, s)}px)`, color: "#fff" }}>{title}</div>
124
- </AbsoluteFill>
125
- </AbsoluteFill>
126
- );
127
- }
128
- ```
129
-
130
- Scene props: everything in the clip's `props`, plus `clip` (`id`, `from`, `duration`), `variant`,
131
- `width`, `height`, `fps`.
132
-
133
- `agentcut` exports: `useStudio()` (project, variant, width, height, fps), `useIsVertical()`, `usePreviewQuality()`
134
- (cheaper drawing in the live preview, full quality in captures/export),
135
- `asset(path)` (URL for `assets/…` / `library:…`), `clamp`, `mix`, `ease(f, from, to, easing?)`,
136
- `sp(f, start, config?, duration?)`, `SPRING` (smooth, snappy, bouncy, pop, land), `sec(seconds)`,
137
- `<RadialGlow>`, `<FrameBox>`, and the format types.
138
-
139
- Shared helpers for several scenes go in `scenes/lib/*.ts(x)` (files in subfolders aren't scenes).
140
- Available packages: `react`, `remotion`, `@remotion/media`, `@remotion/transitions` (+ presentations),
141
- `@remotion/shapes`, `@remotion/paths`, `@remotion/noise`. Anything else: `npm install` it in the
142
- workspace root and it gets bundled.
1
+ # Project format (v1)
2
+
3
+ All times are **integer frames** at `project.fps`. Clip `from` is the timeline frame where the clip
4
+ starts; `duration` is its length in frames. Inside a clip (scene code, caption words, fades) frames are
5
+ **relative to the clip start**.
6
+
7
+ ## project.json
8
+
9
+ ```json
10
+ {
11
+ "version": 1,
12
+ "name": "Rolino launch",
13
+ "fps": 30,
14
+ "durationInFrames": 1800,
15
+ "background": "#060a16",
16
+ "variants": {
17
+ "wide": { "width": 1920, "height": 1080 },
18
+ "mobile": { "width": 1080, "height": 1920 }
19
+ },
20
+ "defaultVariant": "wide",
21
+ "fonts": [
22
+ "Inter:400;600;800",
23
+ { "family": "Brand Onest", "src": "assets/fonts/onest-700.woff2", "weight": "700" }
24
+ ]
25
+ }
26
+ ```
27
+
28
+ - `durationInFrames` is the export length; keep it equal to the end of the last clip.
29
+ - Fonts: Google Fonts specs (`"Family:400;700"`) or local files (preferred for brand fonts: renders
30
+ then never depend on Google Fonts). Reference them by `family` in styles.
31
+
32
+ ## layers.json
33
+
34
+ ```json
35
+ {
36
+ "version": 1,
37
+ "tracks": [
38
+ { "id": "captions", "name": "Captions", "kind": "captions", "clips": [] },
39
+ { "id": "text", "name": "Titles", "kind": "text", "clips": [] },
40
+ { "id": "grain", "name": "Film grain", "kind": "scene", "clips": [] },
41
+ { "id": "scenes", "name": "Scenes", "kind": "scene", "clips": [] },
42
+ { "id": "voice", "name": "Voice", "kind": "audio", "clips": [] },
43
+ { "id": "music", "name": "Music", "kind": "audio", "clips": [] },
44
+ { "id": "sfx", "name": "SFX", "kind": "audio", "clips": [] }
45
+ ],
46
+ "markers": [
47
+ { "id": "m-drop", "frame": 204, "label": "Drop", "kind": "beat" },
48
+ { "id": "m-reveal", "frame": 198, "label": "Reveal", "kind": "section" }
49
+ ]
50
+ }
51
+ ```
52
+
53
+ `tracks[0]` is drawn **on top**; later tracks are drawn underneath. Clips on a track are sorted by
54
+ `from`. Clips may overlap only on `scene` and `audio` tracks (use more tracks otherwise).
55
+
56
+ Track fields: `id` (kebab-case, unique), `name`, `kind`, `clips`, optional `hidden` (visual), `muted`
57
+ (audio/video), `locked` (user lock — don't move locked clips), `volume` (audio track gain).
58
+
59
+ Markers (`section` = scene starts, `cue` = moments sounds/animations hit, `beat` = music beats you rely
60
+ on) show on the timeline ruler. Keep section markers in sync with scene clips.
61
+
62
+ ### Clip fields (all kinds)
63
+
64
+ | field | |
65
+ |---|---|
66
+ | `id` | unique in the project, stable, readable |
67
+ | `name` | timeline label (optional) |
68
+ | `from`, `duration` | frames |
69
+ | `enter`, `exit` | `{ "preset": "fade" \| "slide-up" \| "slide-down" \| "slide-left" \| "slide-right" \| "pop" \| "scale" \| "blur" \| "none", "frames": 12 }` (visual clips) |
70
+ | `opacity` | 0..1 (visual clips) |
71
+ | `note` | why the clip is there (cue reason) |
72
+ | `variants` | per-variant overrides, e.g. `{ "mobile": { "box": {…}, "style": {…} } }` |
73
+
74
+ `box` = `{ "x", "y", "width", "height" }` as fractions of the frame (0..1), top-left origin.
75
+
76
+ ### Kinds
77
+
78
+ **scene** — `{ "scene": "Hook", "props": { … } }` renders `scenes/Hook.tsx`; or
79
+ `{ "component": "text-reveal", "props": { … } }` renders a library component (one of the two per clip;
80
+ see `references/components.md`).
81
+
82
+ **audio** — `{ "src": "assets/voice.wav", "volume": 1, "trimStart": 0, "fadeIn": 0, "fadeOut": 0, "loop": false, "playbackRate": 1, "role": "voice" | "music" | "sfx" | "ambience" }`.
83
+ `trimStart` skips frames of the file. Set `duration` from `agentcut_media_info` (frames). An SFX
84
+ clip's `from` is the cue frame minus the file's onset (see sound.md).
85
+
86
+ **video** — `{ "src", "trimStart", "volume", "muted", "fit": "cover" | "contain", "box", "playbackRate", "grade" }`.
87
+ `grade` — colour: `{ "exposure": 0.2, "contrast": 1.1, "temperature": 0.1, "look": "golden-stock" }` and more (fields and workflow:
88
+ `references/color.md`). Leave out what you don't change. `inheritGrade: false` keeps the project grade and adjustment layers off it.
89
+ Footage from the editor: see `references/footage.md`.
90
+
91
+ **image** — `{ "src", "fit", "box", "radius", "grade", "inheritGrade" }`. `inheritGrade: true` also applies the project grade and adjustment layers.
92
+
93
+ **adjustment** — `{ "grade" }`. Draws nothing: it grades the footage below it while it runs (`references/color.md`).
94
+
95
+ **text** — `{ "text", "box", "style": { "fontFamily", "fontSize" (px at the variant size), "fontWeight", "color", "align", "lineHeight", "letterSpacing", "textTransform", "shadow" } }`. For styled kinetic type use a scene instead.
96
+
97
+ **captions** — `{ "words": [{ "text", "from", "to" }], "style": { "preset": "pop" | "karaoke" | "plain", "fontFamily", "fontSize", "fontWeight", "color", "highlight", "position": "bottom" | "center" | "top", "maxWordsPerLine" } }`.
98
+ Word `from`/`to` are frames **relative to the clip start**. Build them from `agentcut_transcribe`
99
+ (`fromFrame - clip.from`). For custom caption looks, write a scene that takes `words` in props.
100
+
101
+ `src` forms: `assets/<file>`, `library:<path>` (workspace library shared by projects), `https://…` (must
102
+ allow CORS).
103
+
104
+ ## Scenes
105
+
106
+ ```tsx
107
+ // scenes/Hook.tsx
108
+ import { AbsoluteFill, useCurrentFrame } from "remotion";
109
+ import { RadialGlow, SPRING, ease, sp, mix, useStudio, type SceneProps } from "agentcut";
110
+
111
+ type Props = SceneProps & { title: string; accent: string };
112
+
113
+ export default function Hook({ title, accent, width, height, clip }: Props) {
114
+ const f = useCurrentFrame(); // 0 at the clip start
115
+ const vertical = height > width;
116
+ const s = sp(f, 6, SPRING.pop); // spring starting at local frame 6
117
+ const out = ease(f, clip.duration - 8, clip.duration);
118
+ return (
119
+ <AbsoluteFill style={{ background: "linear-gradient(160deg,#0b0b14,#050507)", opacity: 1 - out }}>
120
+ <RadialGlow x={0.5} y={0.45} radius={0.5} color={accent} opacity={0.25} />
121
+ <AbsoluteFill style={{ alignItems: "center", justifyContent: "center" }}>
122
+ <div style={{ fontFamily: "Inter", fontWeight: 900, fontSize: vertical ? 140 : 120,
123
+ transform: `translateY(${mix(60, 0, s)}px)`, color: "#fff" }}>{title}</div>
124
+ </AbsoluteFill>
125
+ </AbsoluteFill>
126
+ );
127
+ }
128
+ ```
129
+
130
+ Scene props: everything in the clip's `props`, plus `clip` (`id`, `from`, `duration`), `variant`,
131
+ `width`, `height`, `fps`.
132
+
133
+ `agentcut` exports: `useStudio()` (project, variant, width, height, fps), `useIsVertical()`, `usePreviewQuality()`
134
+ (cheaper drawing in the live preview, full quality in captures/export),
135
+ `asset(path)` (URL for `assets/…` / `library:…`), `clamp`, `mix`, `ease(f, from, to, easing?)`,
136
+ `sp(f, start, config?, duration?)`, `SPRING` (smooth, snappy, bouncy, pop, land), `sec(seconds)`,
137
+ `<RadialGlow>`, `<FrameBox>`, and the format types.
138
+
139
+ Shared helpers for several scenes go in `scenes/lib/*.ts(x)` (files in subfolders aren't scenes).
140
+ Available packages: `react`, `remotion`, `@remotion/media`, `@remotion/transitions` (+ presentations),
141
+ `@remotion/shapes`, `@remotion/paths`, `@remotion/noise`. Anything else: `npm install` it in the
142
+ workspace root and it gets bundled.
@@ -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.