@autoaiai/aicut 0.1.7 → 0.1.11

package/skills/manage-storyboard-projects/SKILL.md

@@ -0,0 +1,128 @@
+---
+name: manage-storyboard-projects
+description: "Create, find, inspect, update, or delete Agent Storyboard projects directly through MCP. Use when the user asks the agent (Codex or Claude Code) to write a new video script or storyboard into the local storyboard app, add or revise shots, rename a project, change its aspect ratio, find an existing project, or delete one without browser automation. Runs in AICUT: the film is film.html, a page per shot, drawn by `aicut look` and `aicut render`."
+license: MIT
+source: "Yuuhann1999/codex-storyboard"
+---
+
+# Manage Storyboard Projects
+
+## Running it in AICUT
+
+AICUT's film is `film.html`: it cuts pages, footage, pictures and sound together on tracks. A page is a web page that
+sets `window.film = { frame(t) }` and draws that moment — no framework, no build step, no composition object, no
+`registerRoot`. Five shots are five pages cut together, not one page that changes scene, so each shot stays trimmable
+and replaceable in Studio.
+
+```sh
+npx -y @autoaiai/aicut@latest          # the manual: the format and the commands, always current
+npx -y @autoaiai/aicut@latest open .   # make this folder a film and print Studio's address
+npx -y @autoaiai/aicut@latest look     # a contact sheet of the whole film, its sound, and a determinism check
+npx -y @autoaiai/aicut@latest look 4.5 # one frame, full size — look at the PNG, not at the code
+npx -y @autoaiai/aicut@latest render   # the MP4, beside film.html
+```
+
+Run the manual before the first film: it is authoritative for the format, and this skill is about the method above it.
+
+Where the words below name another program's part, it becomes this:
+
+| elsewhere | in AICUT |
+|---|---|
+| composition, timeline, project file | `film.html`; tracks and clips inside it |
+| a scene, a sequence, a slide | a page (`pages/<name>.html`) cut onto a track |
+| `useCurrentFrame()`, `interpolate()` | `frame(t)` — the picture depends only on `t`, never on state or `Date.now()` |
+| a still, a screengrab | `aicut look <t>` |
+| `render` / `build` / `export` | `aicut render` (the person can also export from Studio) |
+| a dev server, a preview window | `aicut open` and the Studio address it prints |
+
+Hard rules that hold whatever the method says: the picture depends only on `t`; every value in the person's prompt is
+binding; look at the frames `look` writes before saying a film is done.
+
+
+Use the Agent Storyboard MCP project tools. Never control the browser, never run `npm start` manually during normal use, and never edit data files directly.
+
+If the current agent session does not expose Storyboard MCP tools such as `create_storyboard_project`, `list_storyboard_projects`, or `open_storyboard`: in Codex, use `tool_search` to search for `agent storyboard` and load the deferred tools; in Claude Code, check that the `agent-storyboard` MCP server is connected (`/mcp`). Only if they still cannot be found, tell the user to start a new conversation or restart the agent so plugin tools are reloaded. Do not silently fall back to editing local data files directly.
+
+## Open the storyboard
+
+If the user asks to open, start, launch, or show Agent Storyboard:
+
+1. Call `open_storyboard`.
+2. Return the local URL as a clickable link.
+3. Tell the user to open the link in the agent's side panel or in a browser.
+4. Do not launch Chrome, shell `open`, Computer Use, or Browser automation just to open the page.
+
+The plugin starts the bundled local app automatically. Project data is stored outside the plugin cache by default.
+
+## Create a project
+
+1. Turn the user's request into a complete shot list before calling the tool.
+2. Call `create_storyboard_project` once with the project title, aspect ratio, all shots, and optional absolute `designPath`.
+3. Do not create shots one at a time.
+4. Return the created project ID and the project URL from the tool result. Tell the user to open that URL or refresh the storyboard if it is already open.
+5. If any shot uses `remotion` or `hyperframes`, mention that generation requires the corresponding plugin or local toolchain before processing assets.
+
+Each shot should include:
+
+- `rollType`: `A-ROLL` for primary presentation or spoken footage; `B-ROLL` for supporting visuals.
+- `mediaType`: `image` or `video`.
+- `duration`: seconds.
+- `dialogue`: spoken line for the shot.
+- `visualPrompt`: concrete visual description used for asset generation.
+- `generator`: `manual`, `image-gen`, `hyperframes`, or `remotion`.
+- `notes`: editing, pacing, transition, or production notes.
+
+Choose `generator` deliberately:
+
+- `manual`: recorded presenter footage, screen recordings, or existing local material.
+- `image-gen`: a static generated visual.
+- `hyperframes`: designed motion graphics or interface animation.
+- `remotion`: programmatic React-based video composition.
+
+## Find and inspect
+
+- Use `list_storyboard_projects` first when the project ID is unknown. Pass `query` when the user gives a title.
+- Use `get_storyboard_project` only when complete shot content is needed.
+- Do not fetch every full project merely to find one title.
+
+## Update
+
+Use one `update_storyboard_project` call:
+
+- `title` or `aspectRatio` for project metadata.
+- `appendShots` for new shots.
+- `shotUpdates` for specific existing shots.
+- `deleteShotIds` for removed shots.
+- `designPath` to import or replace DESIGN.md.
+- `removeDesign: true` to remove it.
+
+Fetch the complete project first only when shot IDs or existing content are required.
+
+## Apply copied visual-arrangement prompts
+
+When a copied prompt contains a target project ID and asks to generate a director-style visual arrangement, treat it as an execution request that must write back to the storyboard page. Do not answer with a Markdown table only.
+
+1. Call `get_storyboard_project` with the provided project ID.
+2. Build the complete shot list internally, preserving the original dialogue and mapping the arrangement into `visualPrompt` and `notes`.
+3. Call `update_storyboard_project` once to apply `shotUpdates`, `appendShots`, and only necessary `deleteShotIds`; never delete the project or its media for this workflow.
+4. Do not enqueue image, video, HyperFrames, or Remotion generation during the arrangement step.
+5. After the write, return a concise summary of the number of shots written, full-check conclusions, unresolved material decisions, and the project URL. Do not repeat the full table in chat.
+
+If no completed aligned voice timeline is provided, do not invent timestamps. Use `duration: 0` and record `时长待录音后确定` in `notes`; when an aligned timeline exists, derive seconds from its exact millisecond phrase boundaries.
+
+## Delete
+
+Project deletion permanently removes the project and its local media. Ask for explicit confirmation immediately before calling `delete_storyboard_project`.
+
+## Token discipline
+
+- Create the complete project with one MCP call.
+- Prefer project summaries over full project reads.
+- Return concise results instead of repeating the full script after it has been written.
+
+## Source
+
+Rewritten for AICUT from [`Yuuhann1999/codex-storyboard`](https://github.com/Yuuhann1999/codex-storyboard)
+(MIT), plugins/agent-storyboard/skills/manage-storyboard-projects/SKILL.md. The method is that skill's own; the way it runs is AICUT's.
+
+The repository holds 2 skills; this is the one its entry stands for.

package/skills/manim-composer/SKILL.md

@@ -0,0 +1,176 @@
+---
+name: manim-composer
+description: "[Video Title]: the method the original skill taught, run as an AICUT film — pages that draw any moment t, cut on tracks. Runs in AICUT: the film is film.html, a page per shot, drawn by `aicut look` and `aicut render`."
+license: MIT
+source: "adithya-s-k/manim_skill"
+---
+
+# [Video Title]
+
+## Running it in AICUT
+
+AICUT's film is `film.html`: it cuts pages, footage, pictures and sound together on tracks. A page is a web page that
+sets `window.film = { frame(t) }` and draws that moment — no framework, no build step, no composition object, no
+`registerRoot`. Five shots are five pages cut together, not one page that changes scene, so each shot stays trimmable
+and replaceable in Studio.
+
+```sh
+npx -y @autoaiai/aicut@latest          # the manual: the format and the commands, always current
+npx -y @autoaiai/aicut@latest open .   # make this folder a film and print Studio's address
+npx -y @autoaiai/aicut@latest look     # a contact sheet of the whole film, its sound, and a determinism check
+npx -y @autoaiai/aicut@latest look 4.5 # one frame, full size — look at the PNG, not at the code
+npx -y @autoaiai/aicut@latest render   # the MP4, beside film.html
+```
+
+Run the manual before the first film: it is authoritative for the format, and this skill is about the method above it.
+
+Where the words below name another program's part, it becomes this:
+
+| elsewhere | in AICUT |
+|---|---|
+| composition, timeline, project file | `film.html`; tracks and clips inside it |
+| a scene, a sequence, a slide | a page (`pages/<name>.html`) cut onto a track |
+| `useCurrentFrame()`, `interpolate()` | `frame(t)` — the picture depends only on `t`, never on state or `Date.now()` |
+| a still, a screengrab | `aicut look <t>` |
+| `render` / `build` / `export` | `aicut render` (the person can also export from Studio) |
+| a dev server, a preview window | `aicut open` and the Studio address it prints |
+
+Hard rules that hold whatever the method says: the picture depends only on `t`; every value in the person's prompt is
+binding; look at the frames `look` writes before saying a film is done.
+
+
+## Workflow
+
+### Phase 1: Understand the Concept
+
+1. **Research the topic** deeply before asking questions
+   - Use web search to understand the core concepts
+   - Identify the key insights that make this topic interesting
+   - Find the "aha moment" - what makes this click for learners
+   - Note common misconceptions to address
+
+2. **Identify the narrative hook**
+   - What question does this video answer?
+   - Why should the viewer care?
+   - What's the surprising or counterintuitive element?
+
+### Phase 2: Clarify with User
+
+Ask targeted questions (not all at once - adapt based on responses):
+
+**Audience & Scope**
+- What math/science background should I assume? (e.g., "knows calculus" or "high school algebra")
+- Target video length? (short: 5-10min, medium: 15-20min, long: 30min+)
+- Should this be self-contained or part of a series?
+
+**Focus & Depth**
+- Any specific aspects to emphasize or skip?
+- Proof-heavy or intuition-focused?
+- Real-world applications to include?
+
+**Style Preferences**
+- Color scheme preferences?
+- Narration style? (casual, formal, playful)
+- Any specific visual metaphors you have in mind?
+
+### Phase 3: Create scenes.md
+
+Output a comprehensive `scenes.md` file with this structure:
+
+```markdown
+
+# [Video Title]
+
+## Overview
+- **Topic**: [Core concept]
+- **Hook**: [Opening question/mystery]
+- **Target Audience**: [Prerequisites]
+- **Estimated Length**: [X minutes]
+- **Key Insight**: [The "aha moment"]
+
+## Narrative Arc
+[2-3 sentences describing the journey from confusion to understanding]
+
+---
+
+## Scene 1: [Scene Name]
+**Duration**: ~X seconds
+**Purpose**: [What this scene accomplishes]
+
+### Visual Elements
+- [List of mobjects needed]
+- [Animations to use]
+- [Camera movements]
+
+### Content
+[Detailed description of what happens, what's shown, what's explained]
+
+### Narration Notes
+[Key points to convey, tone, pacing notes]
+
+### Technical Notes
+- [Specific Manim classes/methods to use]
+- [Any tricky implementations to note]
+
+---
+
+## Scene 2: [Scene Name]
+...
+
+---
+
+## Transitions & Flow
+[Notes on how scenes connect, recurring visual motifs]
+
+## Color Palette
+- Primary: [color] - used for [purpose]
+- Secondary: [color] - used for [purpose]
+- Accent: [color] - used for [purpose]
+- Background: [color]
+
+## Mathematical Content
+[List of equations, formulas, or mathematical objects that need to be rendered]
+
+## Implementation Order
+[Suggested order for implementing scenes, noting dependencies]
+
+## 3b1b Style Principles
+
+Apply these principles when composing scenes:
+
+### Visual Storytelling
+- **Show, don't just tell** - Every concept needs a visual representation
+- **Progressive revelation** - Build complexity gradually, don't show everything at once
+- **Visual continuity** - Transform objects rather than replacing them when possible
+
+### Pacing & Rhythm
+- **Pause for insight** - Give viewers time to absorb key moments
+- **Vary the pace** - Mix quick sequences with slower explanations
+- **End scenes with resolution** - Each scene should feel complete
+
+### Mathematical Beauty
+- **Emphasize elegance** - Highlight when math is surprisingly simple or beautiful
+- **Connect representations** - Show the same concept multiple ways (algebraic, geometric, intuitive)
+- **Embrace abstraction gradually** - Start concrete, then generalize
+
+### Engagement Techniques
+- **Pose questions** - Make viewers curious before revealing answers
+- **Acknowledge difficulty** - "This might seem confusing at first..."
+- **Celebrate insight** - Make the "aha moment" feel earned
+
+## References
+
+- [references/narrative-patterns.md](references/narrative-patterns.md) - Common 3b1b narrative structures
+- [references/visual-techniques.md](references/visual-techniques.md) - Effective visualization patterns
+- [references/scene-examples.md](references/scene-examples.md) - Example scenes.md excerpts
+
+## Templates
+
+- [templates/scenes-template.md](templates/scenes-template.md) - Blank scenes.md template
+
+## Source
+
+Rewritten for AICUT from [`adithya-s-k/manim_skill`](https://github.com/adithya-s-k/manim_skill)
+(MIT), skills/manim-composer/SKILL.md. The method is that skill's own; the way it runs is AICUT's.
+
+The repository holds 3 skills; this is the one its entry stands for.

package/skills/manim-composer/references/narrative-patterns.md

@@ -0,0 +1,125 @@
+# Narrative Patterns for Math Explainers
+
+Common structures used in effective 3Blue1Brown-style videos.
+
+## Pattern 1: Mystery → Investigation → Resolution
+
+**Structure:**
+1. Present a puzzling result or paradox
+2. Investigate why it's true through visual exploration
+3. Reveal the underlying principle
+4. Show how the principle generalizes
+
+**Example topics:** Euler's identity, Bayes theorem, infinite series paradoxes
+
+**Opening hooks:**
+- "What does it even mean to raise a number to an imaginary power?"
+- "This equation looks wrong, but it's actually true..."
+- "Most people get this probability question wrong..."
+
+---
+
+## Pattern 2: Build Up → Payoff
+
+**Structure:**
+1. Introduce simple building blocks
+2. Combine them to create something complex
+3. Show the beautiful/surprising result
+4. Reflect on why it works
+
+**Example topics:** Fourier series, neural networks, linear algebra
+
+**Opening hooks:**
+- "Let's start with something simple..."
+- "Each piece here is easy, but together they do something remarkable..."
+
+---
+
+## Pattern 3: Two Perspectives → Unity
+
+**Structure:**
+1. Show concept from perspective A (e.g., algebraic)
+2. Show same concept from perspective B (e.g., geometric)
+3. Reveal they're the same thing
+4. Explore implications of this connection
+
+**Example topics:** Dot product, determinants, complex multiplication
+
+**Opening hooks:**
+- "There are two ways to think about this..."
+- "These seem like completely different ideas, but..."
+
+---
+
+## Pattern 4: Wrong → Less Wrong → Right
+
+**Structure:**
+1. Present common misconception or naive approach
+2. Show why it fails
+3. Refine the approach
+4. Arrive at correct understanding
+
+**Example topics:** Limits, probability distributions, definitions
+
+**Opening hooks:**
+- "Your first instinct here is probably wrong..."
+- "The obvious approach doesn't quite work..."
+
+---
+
+## Pattern 5: Specific → General
+
+**Structure:**
+1. Solve a specific concrete example
+2. Notice patterns in the solution
+3. Abstract to general principle
+4. Apply to new situations
+
+**Example topics:** Derivatives, group theory, algorithm analysis
+
+**Opening hooks:**
+- "Let's work through a specific example..."
+- "Once you see the pattern here, it shows up everywhere..."
+
+---
+
+## Pattern 6: History as Narrative
+
+**Structure:**
+1. Present the problem as historically encountered
+2. Follow the journey of discovery
+3. Show key insights that led to breakthroughs
+4. Connect to modern understanding
+
+**Example topics:** Calculus, cryptography, quantum mechanics
+
+**Opening hooks:**
+- "Imagine you're a mathematician in the 1600s..."
+- "This problem stumped the greatest minds for centuries..."
+
+---
+
+## Combining Patterns
+
+Most effective videos combine multiple patterns:
+- Mystery hook + Build Up explanation
+- Two Perspectives + Specific → General examples
+- Wrong → Right + History narrative
+
+## Pacing Guidelines
+
+| Video Length | Intro Hook | Main Content | Recap/Implications |
+|--------------|------------|--------------|-------------------|
+| 5-10 min     | 30-60s     | 4-8 min      | 30-60s            |
+| 15-20 min    | 1-2 min    | 12-16 min    | 1-2 min           |
+| 30+ min      | 2-3 min    | 24-26 min    | 2-4 min           |
+
+## Emotional Arc
+
+Every video should have emotional beats:
+
+1. **Curiosity** (opening) - Why should I care?
+2. **Confusion** (early) - This is harder than it looks
+3. **Partial clarity** (middle) - I'm starting to see...
+4. **Aha moment** (climax) - Oh! That's beautiful!
+5. **Satisfaction** (end) - Now I truly understand

package/skills/manim-composer/references/scene-examples.md

@@ -0,0 +1,216 @@
+# Scene Examples
+
+Example scene breakdowns from 3b1b-style videos.
+
+---
+
+## Example 1: Explaining the Dot Product
+
+### Scene 1: The Question
+**Duration**: ~30 seconds
+**Purpose**: Hook the viewer with the mystery
+
+**Visual Elements**
+- Two vectors a and b drawn as arrows
+- The dot product formula: a · b = |a||b|cos(θ)
+- Question mark animation
+
+**Content**
+Open on two vectors. Show the formula. Pose the question: "Why does multiplying components and adding them give you something related to the angle between vectors?"
+
+**Narration Notes**
+Tone: curious, slightly puzzled. Emphasize that the formula seems arbitrary.
+
+**Technical Notes**
+- Use Arrow for vectors
+- MathTex for formula
+- Indicate() on the cos(θ) term
+
+---
+
+### Scene 2: Geometric Interpretation
+**Duration**: ~90 seconds
+**Purpose**: Show projection interpretation
+
+**Visual Elements**
+- Vector a (horizontal, blue)
+- Vector b (angled, green)
+- Projection of b onto a (dashed line)
+- Right angle marker
+- Length labels
+
+**Content**
+Show that a · b equals |a| times the projection of b onto a. Animate the projection dropping down. Show this equals |a||b|cos(θ) geometrically.
+
+**Narration Notes**
+"The dot product measures how much one vector goes in the direction of another."
+
+**Technical Notes**
+- DashedLine for projection
+- RightAngle mobject
+- animate.rotate() for showing different angles
+
+---
+
+### Scene 3: Numeric Connection
+**Duration**: ~60 seconds
+**Purpose**: Connect geometry to algebra
+
+**Visual Elements**
+- Coordinate grid
+- Vector a = [a₁, a₂]
+- Vector b = [b₁, b₂]
+- Components highlighted
+
+**Content**
+Show vectors on grid with components labeled. Demonstrate why a₁b₁ + a₂b₂ equals the geometric interpretation. Use specific numbers.
+
+**Narration Notes**
+Walk through calculation slowly. "Let's see why the algebra matches the geometry."
+
+**Technical Notes**
+- NumberPlane or Axes
+- Brace for component labels
+- TransformMatchingTex for equation steps
+
+---
+
+## Example 2: Introduction to Fourier Series
+
+### Scene 1: The Hook
+**Duration**: ~45 seconds
+**Purpose**: Show the surprising result
+
+**Visual Elements**
+- A square wave (sharp corners)
+- Sum of smooth sine waves
+- Morphing animation between them
+
+**Content**
+"You can build a square wave—something with sharp corners—from perfectly smooth sine waves." Show the result first, then promise to explain how.
+
+**Narration Notes**
+Tone: wonder, slight disbelief. This should feel surprising.
+
+**Technical Notes**
+- ParametricFunction for waves
+- Transform animation for the morph
+- Consider showing 1, 3, 5 terms building up
+
+---
+
+### Scene 2: Building Blocks
+**Duration**: ~120 seconds
+**Purpose**: Introduce sine waves as basis
+
+**Visual Elements**
+- Single sine wave
+- Frequency visualization (faster oscillation)
+- Amplitude visualization (taller/shorter)
+- Phase visualization (shifting left/right)
+
+**Content**
+Introduce the three parameters: frequency, amplitude, phase. Show each one separately, then combine.
+
+**Narration Notes**
+Go slow. "A sine wave has three knobs we can adjust..."
+
+**Technical Notes**
+- ValueTracker for animating parameters
+- Updaters to make wave respond to trackers
+- Labels for each parameter
+
+---
+
+### Scene 3: Superposition
+**Duration**: ~90 seconds
+**Purpose**: Show waves can be added
+
+**Visual Elements**
+- Two sine waves (different colors)
+- Their sum (third color)
+- Point-by-point addition visualization
+
+**Content**
+Show that adding waves means adding their heights at each point. Demonstrate with two specific frequencies combining.
+
+**Narration Notes**
+"Adding waves is simple—at each point, just add the heights."
+
+**Technical Notes**
+- VGroup of three function graphs
+- Vertical lines showing addition at specific x values
+- Animate the addition happening
+
+---
+
+## Example 3: Matrix as Linear Transformation
+
+### Scene 1: Grid Transformation
+**Duration**: ~60 seconds
+**Purpose**: Visual foundation
+
+**Visual Elements**
+- 2D coordinate grid (NumberPlane)
+- Basis vectors i-hat and j-hat (colored arrows)
+- Grid lines transforming
+
+**Content**
+Show a grid. Highlight i-hat (1,0) and j-hat (0,1). Apply a transformation—watch the entire grid move while tracking where basis vectors land.
+
+**Narration Notes**
+"Watch what happens to the grid when we apply this transformation. Notice how every point moves."
+
+**Technical Notes**
+- NumberPlane with visible grid lines
+- apply_matrix() method
+- Keep basis vectors visually distinct
+
+---
+
+### Scene 2: Basis Vectors Determine Everything
+**Duration**: ~90 seconds
+**Purpose**: Key insight
+
+**Visual Elements**
+- Transformed i-hat and j-hat
+- Arbitrary vector v as combination
+- v = xi + yj visualization
+
+**Content**
+Show that knowing where i-hat and j-hat land tells you where ANY vector lands. Because v = xi + yj, the transformed v = x(new i) + y(new j).
+
+**Narration Notes**
+"Here's the key insight..." Build anticipation before the reveal.
+
+**Technical Notes**
+- Vector addition animation (tip-to-tail)
+- Scaling animation for coefficients
+- TransformMatchingShapes for the combination
+
+---
+
+## Scene Transition Patterns
+
+### Zoom Focus
+```
+Full scene → Zoom into detail → Explain → Zoom out
+```
+
+### Side-by-Side Build
+```
+Empty left | Empty right
+Add to left | Compare
+Add to right | Connect them
+```
+
+### Transform Chain
+```
+Object A → Transform → Object B → Transform → Object C
+(Maintain visual continuity throughout)
+```
+
+### Reset and Rebuild
+```
+Complex scene → Clear/fade most → Focus on one element → Build new complexity
+```