Epic: Epoch 2 — External Project Authoring Workflow

[alonshoa]

Goal

Turn Manim Studio from a working rendering foundation into a practical authoring environment for real external Manim presentation projects.

A user should be able to create a separate project, connect it to the reusable Studio runtime and MCP server, add and iterate on scenes, inspect render results, and produce a usable deck artifact without manually assembling Docker commands, catalog metadata, paths, and client configuration.

Epoch outcomes

1. External project creation and Windows-friendly setup

• Provide a Windows-friendly entrypoint for creating a new external Manim Studio project.
• Generate a ready-to-use project structure, including:
  • catalog/scenes.yaml
  • deck and asset directories
  • a registered starter scene
  • compose.yml
  • .gitignore
  • MCP client configuration or a documented generated equivalent
  • project-local usage instructions
• Prompt for required project values and validate generated identifiers and paths.
• Keep the generated project separate from the Manim Studio repository.

2. End-to-end installation verification

The setup flow must verify:

• Docker is available.
• The configured runtime image exists or can be built.
• studio doctor --catalog succeeds.
• The generated catalog is valid.
• The starter scene completes a smoke/draft render.
• The manim-mcp stdio server can start through the external runtime configuration.

Failures should identify the failed stage and leave the generated project inspectable.

3. Convenient project-local commands

• Provide short, documented commands or wrappers for normal Studio operations from an external project.
• Users should not need to reconstruct full docker run commands for routine work.
• Cover at least doctor, list, validate, render, build, inspect, and MCP startup workflows.
• Keep behavior consistent across direct Docker and Docker Compose usage where both are supported.

4. Authoring workflow for new content

Support a clear workflow for:

• creating a deck
• creating a scene
• registering a scene in the catalog
• generating a scene from a template
• validating the new content immediately

Initial templates should cover:

• standard Manim Scene
• manim-slides Slide
• Hebrew/RTL slide content using manim_kit

The exact boundary between installer generation and studio new ... CLI commands should be decided during implementation.

5. Complete project context for Codex and MCP clients

Expose enough structured context for an AI-assisted authoring workflow, including:

• decks and registered scenes
• scene source and metadata
• discovered beats
• referenced assets and relevant dependencies
• project conventions
• available manim_kit components
• latest relevant build, status, logs, and artifacts

All access must remain scoped to the external project and registered Studio concepts.

6. Fast iteration loop

Establish and document the primary authoring loop:

plan scene
-> create or edit
-> validate
-> draft render
-> inspect result
-> revise

The loop should work for a full scene and, where supported, a named beat.

7. Easier build and artifact inspection

• Identify the latest build for a scene, deck, or beat.
• Make the relevant video, review frames, contact sheet, logs, and manifest easy to locate.
• Preserve a clear relationship between every artifact and its source target/profile/beat.
• Provide a simple way for CLI users and MCP clients to retrieve the most relevant result.

8. Actionable diagnostics

Improve error reporting so users and agents receive:

• the primary Manim/Studio failure rather than only a long raw log
• source file and line information when available
• a useful next action
• a stable distinction between code, catalog, asset, font, environment, validation, and render failures

Raw stdout/stderr logs must remain available for deeper inspection.

9. Safe AI-assisted scene editing

Design and implement a staged editing workflow:

1. create a proposed change
2. inspect the diff
3. validate the staged scene
4. draft-render the staged scene
5. apply only after explicit approval

The canonical project must not be modified by a proposal or validation step.

The first specialized workflow should accept scene context and a failed build, identify the likely cause, and produce a minimal reviewable repair proposal.

10. First usable deck export

• Define one initial delivery format based on a real authoring need.
• Implement export through a shared service used by both CLI and MCP.
• Store export outputs as inspectable build artifacts.
• Return stable errors for unsupported formats and failed exports.
• Defer additional formats until the first path works end to end.

The initial format must be selected before the export implementation issue is finalized.

11. Foundation cleanup and verification

• Verify whether Ensure devcontainer PATH exposes /opt/venv/bin in non-interactive Docker runs #13 and [Bug] Devcontainer default Python/PATH points outside the pinned Manim runtime #14 are resolved by the current runtime changes and close or update them accordingly.
• Update Epic: establish Manim Studio as a reproducible local presentation workspace #1 to reflect the phases already completed.
• Update the README project status.
• Complete installed stdio MCP verification in the external runtime.
• Run an end-to-end acceptance test using a genuinely separate generated project.

Definition of done

This epoch is complete when a Windows user can:

1. create a separate Manim Studio project through the supported setup entrypoint
2. open the generated project and run short project-local Studio commands
3. validate and render its starter scene
4. add and register a new scene through the supported authoring workflow
5. connect an MCP client to that external project
6. inspect scene context and the latest render artifacts through CLI and MCP
7. complete the documented edit/validate/draft-review loop
8. safely test an AI-proposed scene repair without modifying canonical code before approval
9. produce the first supported deck delivery artifact
10. repeat the setup successfully from a clean checkout using documented steps

Out of scope

• fully autonomous generation of complete presentations
• unrestricted or silent MCP file editing
• a YAML-only animation language
• cloud rendering or distributed workers
• a full graphical Studio management UI
• support for every export format
• mass migration of legacy scenes
• GPU/OpenGL as the default workflow

Planning notes

The epoch should be split into focused implementation issues before development begins. In particular, resolve these design choices explicitly:

• which operations belong to the installer versus the Studio CLI
• the staging/isolation mechanism for proposed edits
• the first supported export format
• the canonical project-local command surface on Windows