> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zap.wzrd.tech/llms.txt
> Use this file to discover all available pages before exploring further.

# Zap: Agent-First Framework for Generative Video Recipes

> Zap is a lightweight content-agent framework for defining, validating, and running AI-powered generative video pipelines as portable recipe files.

Zap is a lightweight content-agent framework where every generative video recipe lives as a self-contained `Zap.md` file — YAML frontmatter that declares inputs, budget, steps, and provider defaults, paired with human-readable prompt files and a `SKILL.md` capability description. The CLI (`@wzrdtech/zap`) and web studio read the same recipe files as coding agents (Codex, Claude Code, Cursor, and others), so a recipe authored by a human works identically when executed autonomously by an agent. Each `zap-<slug>` skill directory is a portable unit of creative capability that travels with your repo.

<CardGroup cols={2}>
  <Card title="Quickstart" icon="bolt" href="/quickstart">
    Scaffold a project, author your first recipe, and run a zero-cost mock pipeline in under five minutes.
  </Card>

  <Card title="Zap Spec" icon="file-code" href="/concepts/zap-spec">
    Full reference for every frontmatter field: inputs, steps, budget, defaults, and output.
  </Card>

  <Card title="Providers" icon="plug" href="/concepts/providers">
    Configure GMI Cloud, fal.ai, or the built-in deterministic mock adapter as your pipeline backend.
  </Card>

  <Card title="CLI Reference" icon="terminal" href="/reference/cli">
    Every command — init, new, validate, lint, run, status, doctor, and more — with flags and examples.
  </Card>
</CardGroup>

## Project & Recipe Structure

A Zap project follows a conventional layout that both humans and coding agents can navigate without configuration:

```text theme={null}
my-app/
├── agent/
│   └── skills/
│       └── zap-<slug>/          # One directory per recipe
│           ├── SKILL.md         # Human + agent capability description
│           ├── Zap.md           # Recipe frontmatter + creative brief
│           └── prompts/
│               ├── initial-frame.md
│               └── initial-gen.md
├── docs/                        # Project documentation
├── .zap/
│   └── runs/                    # Local run results (gitignored)
├── AGENTS.md                    # Agent instructions for the project
├── .env.example                 # Environment variable template
└── package.json                 # npm scripts: zap:docs, zap:new, zap:run, and more
```

`zap init <dir>` scaffolds this layout automatically, including a sample `hello-world` recipe, npm convenience scripts, and an `AGENTS.md` with project-level agent instructions.

### Inside a Recipe Skill

```text theme={null}
zap-<slug>/
├── SKILL.md          # "Use this skill when a creator wants the <Slug> Zap."
├── Zap.md            # YAML frontmatter (inputs, steps, budget) + creative prose
└── prompts/
    ├── initial-frame.md   # Image generation prompt — references {PROMPT}
    └── initial-gen.md     # Video generation prompt — references {PROMPT}
```

The `Zap.md` frontmatter is the single source of truth for the pipeline: step ordering, model selection, provider routing, budget caps, and input schema are all declared there. Prompt files contain the creative instructions passed to each model, with `{INPUT_NAME}` placeholders substituted at run time.

## What Ships

| Layer                  | Contents                                                                                                                       |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| **CLI**                | `init`, `new`, `validate`, `lint`, `run`, `status`, `add`, `docs`, `skills`, `doctor`, `info`, `upgrade`                       |
| **Web studio**         | Creator-friendly Zap runner at `/zap/<slug>` and agent workspace at `/studio`                                                  |
| **Runtime**            | Convex run state, Upstash idempotency + polling queues, GMI Cloud and fal.ai provider adapters, optional HyperFrames stitching |
| **Workspace packages** | `@wzrdtech/zap` (publishable CLI), core schema/planning, provider queues, agent helpers                                        |
| **Registry**           | Curated skill templates installable via `zap add <name>`                                                                       |

<Note>
  **Mock mode is the default — it costs nothing.** Every `zap run` and `npm run zap:run` command uses the deterministic mock adapter unless you explicitly pass `--live`. Mock mode fills required inputs with deterministic placeholders, executes the full step graph, writes a local result to `.zap/runs/`, and returns a `mock://` asset URL. No provider keys, no spend, no surprises. Add `--live` only after provider credentials and a budget cap are in place.
</Note>