> ## Documentation Index
> Fetch the complete documentation index at: https://ralphy.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Changelog

> What's new in Ralphy.

<Update label="June 2, 2026" description="v0.3.0">
  ## New

  **`ralphy unit` — curated deliverables.** Projects now have an append-only `units/` layer: `ralphy unit create <project> --slug <s> --format <f> --from "<glob>"` copies selected assets into a versioned deliverable with a `unit.json` provenance manifest (template + style + recipes + assets). See [`ralphy unit`](/reference/cli/unit).

  **`ralphy compose` — timeline-aware composition.** Build the HyperFrames timeline from the asset manifest with explicit scene ordering and timing. See [`ralphy compose`](/reference/cli/compose).

  **`ralphy image` — local image ops.** `chromakey`, `cutout`, `fit`, and `svg-rasterize` for sticker cutouts, aspect fitting, and overlay prep — no model call needed. See [`ralphy image`](/reference/cli/image).

  **`ralphy guideline` — prompt-library rules.** `list` and `show <slug>` surface the field-tested prompt guidelines (photoreal humans, anti-AI-slop, broadcast realism) so they can be folded into any generation prompt. See [`ralphy guideline`](/reference/cli/guideline).

  **`ralphy research run` — deep-research engine.** Planner + fan-out retrievers + a deterministic 5-level citation verifier, including native video analysis of TikTok/Shorts via `gemini-3.1-pro-preview`. See [eval & research](/cli/eval-research).

  **`ralphy hyperframes` namespace.** HF utility verbs with gen-log wiring, including `save-version` snapshots of `index.html` before structural edits. See [`ralphy hyperframes`](/reference/cli/hyperframes).

  **More new verbs.** `ref locate` (vision-based bounding boxes), `ref pull-site` (Playwright brand-DNA crawl), `ref pull-bulk` + `assets unpack` (bulk pulls), `template extract` (promote a project to a template), `video frame` / `extend` (i2v anchoring), `generate batch` / `variants` / `image-batch` with cost `--dry-run`, `voice clone`, `editor preflight` / `trim-analyze`, `project assets` / `verify`.

  ## Updates

  **Provider reliability.** Transient errors retry with exponential backoff, per-endpoint concurrency self-throttles, oversized PNG anchors auto-resize for i2v, and ElevenLabs ToS rejections return structured errors with auto-resubmit. Voice/scribe/vision/size preflights run before paid calls.

  **Render flags.** `ralphy render` gains `--grade` / `--quality`, plus a `--from-clip` loudnorm mode for single-clip finishing. New audio/video recipes: grade, VHS, mix-music, compress. See [`ralphy render`](/reference/cli/render).

  **Templates: format → styles taxonomy.** Every template now declares a media format (`video`, `image`, `carousel`, `fb-creative`, `motion-design`, `poster`, `sticker-pack`); `ralphy template suggest` takes `--format`. See [Picking a template](/working/picking-a-template).

  ## Fixes

  **`ralphy new` unified with `project create`.** No more orphan project dirs invisible to `generate` / `render` (#031).

  **Gen-log canonical schema.** Every generation logs a consistent record with a `slot` field; `analyze-video` calls are logged too (#032).

  **Captions per-slot output.** `ralphy generate captions` writes per-slot files, returns a silent empty array for no-speech clips, and wraps to the caption safe zone (#010).
</Update>

<Update label="May 29, 2026">
  ## New

  **Ralphy Desktop (preview).** A new desktop app that drives a Ralphy project through an embedded Claude Code chat — onboarding, live project panel, and a confirm-with-cost permission modal. Runs against your local `claude` install, so it uses your existing subscription credit instead of a separate API key. Ships as an early spike; expect rough edges.

  **`--provider` flag and `ralphy provider list`.** Generation commands (`image`, `video`, `voiceover`, `music`, `sfx`) now accept `--provider <id>` to pin a specific backend, and `ralphy provider list` prints the capability matrix for every connector you have keys for. See [`ralphy provider`](/reference/cli/provider) and [`ralphy generate`](/reference/cli/generate).

  **Skills marketplace.** The public [skills page](https://ralphy.dev/skills) is now a real marketplace — grid, filters, search, per-skill icons, and a detail modal with the full file tree for each skill.

  **New skills.**

  * `ugc-toon-action` — subject-agnostic Spider-Verse/Arcane action-clip skill with style locks and multi-clip continuity.
  * `poster` — fixed poster-as-landing layout (banner → wordmark → hero → sticker collage → copy → footer) with parameterized slots.
  * Four niche UGC skills: `unboxing`, `ad`, `model-swap`, and `rockstar`.

  See [Skill format](/advanced/skill-format) and run `ralphy skill list` to install.

  **`analog-horror-pick-a-door` template.** A full reproduction kit for the "pick a door" brand-comparison format — composition skeleton, monster cutouts, VHS/SFX bed, beep system, font, and a prompt cookbook. See [`ralphy template`](/reference/cli/template).

  **`y2k-streetwear-poster` guideline.** A new image-prompt guideline with three validated square examples, surfaced in the library and referenceable as `@guideline:y2k-streetwear-poster`.

  ## Updates

  **Templates are remix-only.** Generic "make a video about X" prompts now route to a generalized **skill**, not a one-off template. Templates are only applied when you explicitly opt in (e.g. `@template:<slug>, swap X for Y`). See [Picking a template](/working/picking-a-template).

  ## Fixes

  **`gpt-5.4-image-2` honors aspect ratios.** The `--size` flag (`9:16`, `1:1`, etc.) is now passed through correctly for image generation across all flows; previously the model ignored the in-prompt hint and returned 1024² regardless. See [`ralphy generate`](/reference/cli/generate).
</Update>

<Update label="May 26, 2026">
  ## Breaking

  **Removed Remotion legacy engine.** HyperFrames is now the only render engine. The `--engine` flag, the Remotion fallback path, `composition-props.json` auto-detection, `src/videos/*`, and all `@remotion/*` packages are gone. Projects must ship `workspace/projects/<id>/index.html`. See [Rendering](/working/rendering).
</Update>

<Update label="May 22, 2026" description="v0.2.0">
  ## New

  **HyperFrames is the default render engine.** A new HTML + GSAP renderer ships as the default for `ralphy render`. It's faster to iterate on, supports per-render `--fps`, `--quality`, `--format`, and `--resolution` flags. See [`ralphy render`](/reference/cli/render) and the [rendering guide](/working/rendering).

  **Skills gallery.** Browse the full catalog of Ralphy skills on the new [skills page](https://ralphy.dev/skills) — filterable by namespace, with motion-driven previews.

  **Reference-consent gate.** Ralphy now classifies prompts that imply a real person or branded look and asks for a reference image before generating. Pass `--no-ref-consent` to opt out per command. See [brand, persona, refs](/working/brand-persona-refs).

  ## Updates

  **Default image model is now `gemini-3-pro-image-preview`.** New projects pick up the upgraded default automatically. Existing projects keep whatever they've pinned. See [Models](/cli/models).

  **Skill namespaces rebranded to `ralphy:` and `ralphy-dev:`.** Skill IDs now follow a clean kebab namespace. Reinstall via `ralphy skill install` to pick up the new names. See [Skill format](/advanced/skill-format).

  **Render flag surface.** `ralphy render` gained `--fps`, `--quality`, `--format`, and `--resolution`. Run with `--dry-run` to preview the resolved plan without burning a render. See [`ralphy render`](/reference/cli/render).

  ## Fixes

  **Pretty CLI output no longer prints `[object Object]`** for arrays of objects in `generate`, `render`, `doctor`, and the editor flows. See [Output modes](/cli/output-modes).

  **`ralphy skill` now errors cleanly** when run from a directory with no source bundle, instead of failing mid-resolution.
</Update>