onboarding

name: onboarding description: "Orientation skill for new agents and users. Explains what Montaj is and how it works. Use it when the user asks questions about montaj or is getting started"

Montaj — Orientation

What Montaj is

A video editing toolkit that mounts on top of an agent harness. You bring the brain. Montaj gives agents the tools.

Montaj doesn't edit on its own. It provides discrete operations — trim, transcribe, remove fillers, caption, resize, composite overlays — and the agent decides which to call, in what order, with what parameters. The agent is the editor. Montaj is the toolbox.

How it compares

Most programmatic video tools (Remotion, Revideo) have the agent write code that describes a composition. Montaj takes the opposite approach: the agent calls tools against existing footage. Agent can still write code on top of existing footage for overlays and animations, but montaj is desigend to work around and with existing footage. The agent reasons about which steps to apply and executes them.

GUI tools (Premiere, DaVinci, Descript, Runway) are driven by a human. Every decision is a click. Montaj is designed for the agent to drive — the human reviews the result and performs last mile edits, the bulk of the process is agent driven.

Where Montaj is the right choice:

• You have raw footage and want an agent to produce an edited video
• You need captions, overlays, and trim decisions made from the content itself
• You want to define a reusable editing style for an account and apply it automatically
• You want to run locally, no API keys required

Where Montaj is not the right choice:

• You want to generate AI videos from scratch (use Veo, Runway, etc)
• You want a human-driven rich GUI with fine-grained manual control
• You want an agent to edit videos based purely on visuals and not on trascripts / audio

What is a project

A project is one video being made. Everything lives in a single file: project.json.

pending  →  agent edits  →  draft  →  human reviews  →  final  →  render  →  MP4

• pending — created, clips and prompt attached, waiting for the agent
• draft — agent is done; ready for human review
• final — reviewed and approved; ready to render

The agent reads project.json, calls steps, writes it back as it works. The UI watches the file and rerenders the timeline on every write.

Where things live

~/Montaj/                       ← workspace — all projects live here
  2025-04-01-product-demo/
    project.json                ← the project (pending → draft → final)
    clip.mp4
    clip_spec.json              ← trim spec (editing decisions, no re-encode)
    clip_transcript.json        ← word-level timestamps
    overlays/hook.jsx           ← agent-authored overlay components
    output.mp4                  ← final render

~/.montaj/                      ← user config + extensions
  config.json                   ← workspaceDir, model, render settings
  credentials.json              ← API keys (never committed)
  profiles/<name>/              ← account style profiles
  steps/                        ← custom steps
  workflows/                    ← custom workflows

montaj/                         ← built-in (ships with Montaj)
  steps/
  workflows/
  skills/

Account styles (Style Profiles)

A style profile captures the visual and editorial identity of a social media account — pacing, cut frequency, color palette, caption style, tone. Once created, it gets injected into every project for that account so editing decisions stay consistent automatically.

Profiles live at ~/.montaj/profiles/<name>/style_profile.md and are loaded into your agent context when tagged selected in the UI or manually seeked on the prompt.

To create or update one: load skills/style-profile/SKILL.md.

The UI

montaj serve starts a local server and opens http://localhost:3000.

The Editor tab drives the core flow: upload clips + prompt → watch the agent work live → review and tweak → render. The agent writes project.json as it works; the UI reflects every change in real time via SSE.

Four tabs: Editor, Workflows (node graph), Overlays (live JSX preview), Profiles (style profiles).

See docs/UI.md for the full breakdown.

Getting started

Start the server using montaj serve. If you get warnings or errors, bubble them up to the user with the easiest way to fix them (running montaj install ui, etc.).

Ask the user:

"Before we start — do you want to set up a style profile for your account first, or jump straight into editing a video?

Style profile: I'll analyze your existing content (or a URL you paste) and build an editing style that gets applied automatically to every project for that account — pacing, caption style, color palette, tone.

Edit a video: Tell me the location of your clips or drop them in the UI, and I'll run the full edit pipeline for whatever content style you pick. You can always add a style profile later."

• If style profile: load skills/style-profile/SKILL.md and follow it.
• If edit a video: load skills/SKILL.md and follow it.