Design and production spec with cut.md

Give people and Agents one validated contract for intent, style, motion, media and review.

cut.md is an optional, canonical design and production brief for Agent-driven JsonCut work. It guides authoring and review; it does not replace the editable project source, change export settings or gate normal Studio/API rendering.

Humans can edit the brief in Studio when they want explicit creative constraints, but they do not have to create or approve one. For long, multi-scene or iterative work, an Agent may create and maintain it as its own planning artifact. The approved status means the brief itself is stable; it does not mean that every render now requires a separate approval.

What belongs in the contract

Section	Purpose
`intent`	Audience, message, outcome, destination and tone
`output`	Kind, dimensions, background and video timing requirements
`governance`	Locked, adaptable and forbidden decisions
`style`	Concept, density, palette, typography and visual rules
`motion`	Character and tempo for video work
`media`	Uniqueness, provenance and inspiration rules
`quality`	Alignment, readability, temporal review and explicit assertions
`technical`	Public production constraints such as native-first authoring
`structure`	Optional narrative and bounded video beats

Compact image contract

---
cut: jsoncut.cut/1
id: launch-cover
name: Launch cover
status: draft
scope: project
kind: image
intent:
  audience: Product teams evaluating visual automation
  message: One approved source stays editable and repeatable
  outcome: Start a free Studio project
  destination: website
  tone: [direct, editorial]
output:
  width: 1200
  height: 630
  background: opaque
governance:
  locked: [logo placement, primary message]
  adaptable: [supporting copy, product image, accent color]
  forbidden: [invented customer logos, unreadable text]
style:
  concept: Technical editorial cover with strong hierarchy
  density: restrained
  palette:
    - { id: base, value: '#031c21', roles: [background] }
    - { id: accent, value: '#42f3d0', roles: [signal, rule] }
  typography:
    - id: display
      family: Inter
      weight: 800
      sizePx: { min: 56, max: 92 }
      lineHeight: 0.95
      tracking: '-0.04em'
      case: upper
      roles: [headline]
  hierarchy:
    focalPoints: 1
    whitespace: 7
    eyePath: Headline first, product context second, API signal last
  layout:
    safeArea: { top: 48, right: 48, bottom: 48, left: 48 }
    anchors: [top-left, bottom-left]
    compositions: [editorial-split]
    aspectBehavior: Preserve hierarchy and re-crop media per aspect
  surfaces:
    radiusPx: [0, 12, 24]
    borderPx: [1, 2]
    shadows: restrained
    depth: flat with one foreground signal
  imagery:
    treatment: [owned-product-media, high-contrast-crop]
    grading: neutral with cool shadows
media:
  uniqueness: { scope: project, reuse: allowed }
  provenanceRequired: true
  inspiration: style-only
  generation: allowed
  stock: allowed
quality:
  alignmentTolerancePx: 4
  minBodyFontPx: 24
  maxUnintendedStaticSec: 0
  contrast: wcag-aa
  emptyFirstFrame: false
  emptyLastFrame: false
  assertions:
    - { kind: text-visible, target: headline }
  review: { fullPlayback: false, sampleTransitions: false, sampleTextEffects: false }
technical:
  nativeFirst: true
  customBlock: exception-only
  finalQuality: high
---

Keep the headline readable at the final output size.

The authoritative JSON schema is available at /schemas/v2/cut.schema.json. Use POST /api/v2/projects/{id}/cut/validate to validate without saving, then PUT /api/v2/projects/{id}/cut to create the next immutable cut version.

Video structure

Video contracts additionally define motion and may define structure.beats. Beat durations must add up inside the declared output duration range. Use beats for editorial intent, not as a replacement for timeline layer timing.

Agent rules

Read and follow the active cut when one exists.
Continue from the user brief when it does not; never block editing, checks or rendering because cut.md is absent.
Do not change a locked decision.
Treat forbidden rules as hard constraints.
Resolve real media and fonts before referencing them.
Validate after meaningful edits and visually review when the delivery risk warrants it.
Update the cut only when the creative contract itself changes.

Reviews and normal exports

Checks can be run with or without cut.md. A normal Studio, API or MCP render never needs a review. When an Agent or integration explicitly needs provenance for a delivery, it can approve a current review and pass its reviewId with the render request. Providing that ID opts into strict project- and cut-version validation; omitting it requests an ordinary render.