Reel workspaces¶

A reel workspace is a directory that holds everything for one reel — the creative inputs, the selected media, and the finished output. It is the resumable unit of the authoring loop and the unit a scheduled pipeline consumes (spec 0001 §3.2, contract 0002 §2).

keryx is a stateless tool: the workspace (and the project's config, themes, and schedule) lives in the owning project's repo, not in keryx. keryx only requires the internal shape; the exact location within the repo is the project's choice (R-WS-3).

Layout¶

<root>/<slug>/
  workspace.yaml        # meta: slug, theme, bundle, schema_version       [committed]
  storyboard.json       # the creative seed (cards)                       [committed]
  social.json           # per-platform social set + status (Phase 2)      [committed]
  cover.png             # bookend art                                     [committed]
  vo/NN.mp3             # selected narration per card                     [committed]
  cards/NN.{png,mp4}    # selected card media                             [committed]
  music.mp3             # selected bed                                    [committed]
  reel.mp4              # rendered output                                 [committed]
  # disposable, git-ignored (cleared by `keryx reel prune`):
  vo/takes/  cards/takes/  music/takes/  .cache/

Only the selected inputs + the output are committed; candidate takes/ and the generation .cache/ are git-ignored (regenerable) so the repo doesn't bloat (R-WS-22). keryx reel new writes that .gitignore automatically.

workspace.yaml records a schema version so an old workspace fails loudly rather than mis-rendering (R-WS-2).

Where workspaces live¶

The reel root defaults to reels/ and is configurable per project via workspace.root. The CLI scopes to the current folder (the git working copy); you switch projects by cd (R-GIT-1).

Associated content (the bundle)¶

A workspace can be linked to a content directory — a Hugo page bundle or any directory (keryx reel link <slug> <dir>). The association (in workspace.yaml) tells keryx where the finished reel-<slug>.mp4 belongs and gives the chat/draft AI real context to read (R-WS-19/20/21). It's optional — a reel can stand alone.

Managing workspaces¶

Use keryx reel — new, list, rename, duplicate, rm, link — plus build to render. Take management (voice select, cards select) and social/storyboard draft arrive in the rest of Phase 1.5.