---
title: "Changelog"
description: "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>
