> ## 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.

# Concepts

> The shape of Ralphy: projects, refs, templates, agents, the workspace.

Ralphy has a small surface but an opinionated middle. The agent in your editor reads playbooks and calls verbs. The `ralphy` CLI mutates a workspace on disk. The workspace is append-only and gitignored. Every model call is logged, every regen is a new version, and every brief that names a real-world entity hits a refusal gate until you attach a reference. These pages cover the moving parts so you can reason about what Ralphy will do *before* it spends your money.

## Read these in order

If you are new, start with `What is Ralphy` and `Architecture`. After that the pages stand alone — each one cites its source-of-truth doc in the repo so you can follow the trail.

<CardGroup cols={2}>
  <Card title="What is Ralphy" href="/concepts/what-is-ralphy">
    AI film studio in your terminal. Who it serves, what it replaces, what makes it refuse.
  </Card>

  <Card title="Architecture" href="/concepts/architecture">
    Three moving parts: agent, CLI, workspace. How they pass work back and forth.
  </Card>

  <Card title="Workspace" href="/concepts/workspace">
    Directory layout. What is canonical, what is scratch, what survives a wipe.
  </Card>

  <Card title="Projects" href="/concepts/projects">
    One project equals one video. Lifecycle, on-disk layout, the registry.
  </Card>

  <Card title="Brands and personas" href="/concepts/brands-personas">
    Reusable identity: who the video is from, and who is in it.
  </Card>

  <Card title="References" href="/concepts/references">
    The ref-required gate. When Ralphy refuses, and how the override works.
  </Card>

  <Card title="Templates" href="/concepts/templates">
    Two kinds, five categories, 54 entries. Read this before improvising.
  </Card>

  <Card title="Asset catalog" href="/concepts/asset-catalog">
    The companion-repo pool: brainrot characters, gameplay loops, trend music.
  </Card>

  <Card title="Generation log" href="/concepts/generation-log">
    The append-only contract. Schemas for the three JSONL files. Versioning rules.
  </Card>

  <Card title="Playbooks and skills" href="/concepts/playbooks-and-skills">
    Role docs read on demand vs. slash-invocable workflows. Two namespaces.
  </Card>
</CardGroup>

## What "concepts" means here

A concept page describes a *durable* idea — the workspace layout, the ref gate, the log schema. Concepts do not change between commands. The CLI reference and the cookbook recipes do change — when a verb gets a new flag, the reference page regenerates. When you want to understand why `ralphy generate` writes a `.v2` file instead of overwriting `.v1`, you stay here.

If you came here looking for a verb signature, the CLI reference is at [`/cli/generation-verbs`](/cli/generation-verbs). If you came looking for "how do I make my first video," start with [`/quickstart/first-video`](/quickstart/first-video).

## Related

* [Quickstart: install](/quickstart/install) — get the binary on your machine
* [Quickstart: first video](/quickstart/first-video) — the 10-minute walkthrough
* [AGENTS.md](https://github.com/alecs5am/ralphy/blob/main/AGENTS.md) — the routing contract that ties every concept together
* [MODELS.md](https://github.com/alecs5am/ralphy/blob/main/MODELS.md) — the catalogue of providers and per-stage defaults