File Formats

CutReady stores all project data as files on disk using simple, inspectable formats. This page documents the structure of each file type.

Directory Layout

Workspaces use a flat directory layout in single-project mode. Multi-project workspaces have each project in its own subdirectory:

Single-Project

my-workspace/
├── project.json
├── .cutready/
│   ├── screenshots/
│   ├── visuals/
│   └── settings.json
├── .git/
│   └── cutready/
│       ├── order.json
│       └── workspace.json
├── intro.sk
├── features/
│   ├── dashboard.sk
│   └── analytics.sk
├── demo-flow.sb
└── research.md

Multi-Project

my-workspace/
├── .cutready/
│   └── projects.json
├── .git/
├── project-alpha/
│   ├── project.json
│   ├── .cutready/
│   │   ├── screenshots/
│   │   └── visuals/
│   ├── intro.sk
│   └── demo-flow.sb
└── project-beta/
    ├── project.json
    ├── .cutready/
    │   ├── screenshots/
    │   └── visuals/
    ├── overview.sk
    └── notes.md

CutReady recursively discovers .sk, .sb, and .md files within the project directory.

Sketch Files (.sk)

Sketch files are JSON documents containing a structured planning table:

{
  "title": "Dashboard Tour",
  "locked": false,
  "description": {
    "root": {
      "children": [
        {
          "children": [
            {
              "detail": 0,
              "format": 0,
              "mode": "normal",
              "style": "",
              "text": "Walk through the main dashboard features",
              "type": "text",
              "version": 1
            }
          ],
          "direction": null,
          "format": "",
          "indent": 0,
          "type": "paragraph",
          "version": 1
        }
      ],
      "direction": null,
      "format": "",
      "indent": 0,
      "type": "root",
      "version": 1
    }
  },
  "rows": [
    {
      "locked": false,
      "locks": {
        "time": false,
        "narrative": false,
        "demo_actions": false,
        "screenshot": false,
        "visual": false,
        "design_plan": false
      },
      "time": "0:00",
      "narrative": "Welcome to the dashboard overview",
      "demo_actions": "Navigate to /dashboard",
      "screenshot": ".cutready/screenshots/screenshot-001.png",
      "visual": ".cutready/visuals/a1b2c3d4e5f6.json",
      "design_plan": "Frame the dashboard metrics as three cards."
    },
    {
      "time": "0:30",
      "narrative": "Notice the real-time metrics panel",
      "demo_actions": "Hover over the metrics widget",
      "screenshot": ".cutready/screenshots/screenshot-002.png"
    }
  ],
  "state": "draft",
  "created_at": "2025-01-15T10:30:00Z",
  "updated_at": "2025-01-15T14:22:00Z"
}

Sketch Fields

Field	Type	Description
title	string	Display name of the sketch
locked	boolean	Protects the whole sketch from edits when true
description	object/null	Lexical rich-text editor state, or null when empty
rows	array	Ordered list of planning row objects
state	string	One of: draft, recording_enriched, refined, final
created_at / updated_at	string	ISO timestamps

Planning Row Fields

Field	Type	Description
time	string	Target timing (e.g., "0:30", "1:15")
narrative	string	Voiceover script text
demo_actions	string	Demo action descriptions
screenshot	string/null	Reference screenshot path relative to the project
locked	boolean	Protects the whole row from edits
locks	object	Per-cell locks for time, narrative, demo_actions, screenshot, visual, and design_plan
visual	string/null	External Elucim DSL file in .cutready/visuals/
design_plan	string/null	Plain-English visual brief saved by the Designer agent

Storyboard Files (.sb)

Storyboard files define an ordered sequence of sketch references:

{
  "title": "Product Launch Demo",
  "description": "Complete demo flow for the product launch event",
  "locked": false,
  "items": [
    { "type": "sketch_ref", "path": "intro.sk" },
    {
      "type": "section",
      "title": "Core workflow",
      "sketches": [
        "features/dashboard.sk",
        "features/analytics.sk"
      ]
    },
    { "type": "sketch_ref", "path": "closing.sk" }
  ],
  "created_at": "2025-01-15T10:30:00Z",
  "updated_at": "2025-01-15T16:00:00Z"
}

Storyboards reference sketches by relative file path. Sketches can exist independently or be referenced by multiple storyboards. Storyboard items are either direct sketch_ref entries or named section groups containing sketch paths.

Notes (.md)

Notes are plain markdown files with no special structure. They’re stored alongside sketches and storyboards and can be edited with CutReady’s built-in CodeMirror-based markdown editor.

Sidebar Ordering (.git/cutready/order.json)

This file persists the user’s preferred document order in the Explorer. It lives under .git/cutready/ so it is local UI state rather than versioned project content:

{
  "storyboards": ["demo-flow.sb"],
  "sketches": ["intro.sk", "features/dashboard.sk", "features/analytics.sk"],
  "notes": ["research.md"]
}

When a user drag-and-drops documents in the Explorer, the new order is written to this file. Documents not listed in the order file appear at the end. Older workspaces may still have .cutready-order.json; CutReady migrates it to the new location when read.

Version History (.git/)

Each workspace contains an embedded git repository managed by gitoxide (gix):

• Snapshots are stored as git commits
• The full document state is committed on each save (Ctrl+S)
• The commit graph powers the visual timeline in the Version History panel
• No external git installation is required

Tip

Because project files are plain JSON and markdown, you can inspect or edit them with any text editor. CutReady will pick up external changes the next time you open the project.

Project Manifest (project.json)

The root-level manifest identifies the directory as a CutReady project:

{
  "name": "Product Demo Q1",
  "createdAt": "2025-01-15T10:30:00Z"
}

CutReady checks for this file when opening a folder to confirm it’s a valid project.

Multi-Project Manifest (.cutready/projects.json)

In multi-project workspaces, the .cutready/projects.json file tracks all projects within the workspace:

{
  "projects": [
    {
      "name": "Product Demo",
      "path": "product-demo"
    },
    {
      "name": "Partner Deck",
      "path": "partner-deck"
    }
  ]
}

This file is created automatically when a workspace is migrated from single-project to multi-project mode.

Assets (.cutready/screenshots/ and .cutready/visuals/)

Screenshots are stored as image files under .cutready/screenshots/ and are referenced from sketch rows or markdown notes by relative path. Designer visuals are stored as Elucim DSL JSON under .cutready/visuals/ and referenced by PlanningRow.visual.

CutReady scans these folders to show referenced and orphaned assets in the Assets view. Legacy inline visual JSON in .sk files is migrated to an external visual file when the sketch is read with migration enabled.

Encrypted Vault (vault.hold)

CutReady stores sensitive credentials (API keys, OAuth tokens, personal access tokens) in an IOTA Stronghold encrypted vault file. The vault.hold file lives in the app data directory (not in the workspace), so credentials are never committed to version history.

Tip

The vault is created and managed automatically. You don’t need to interact with it directly — CutReady handles encryption and decryption transparently.