Docs for humans and agents

Zap Docs

The web docs and `zap docs` CLI topics share the same markdown source. Agents can read these topics offline, then validate each recipe with mock runs before live provider spend.

quick command

zap docs zap-spec
zap docs agents
zap doctor --json

zap docs quickstart

Quickstart

Skill JSON

Quickstart

Create a lightweight Zap project, scaffold a recipe, validate it, and run a zero-spend mock pipeline.

npx @wzrdtech/zap@0.1.0 init demo --non-interactive
cd demo
npm install
npm run zap:validate
npm run zap:new -- my-test
npm run zap:run -- my-test --input PROMPT="A bright launch bumper" --json
npm run zap:status

Mock mode fills missing required inputs with deterministic placeholders. Live provider execution requires --live plus the provider keys and budget approval.

For coding-agent setup, see:

npx @wzrdtech/zap@0.1.0 docs agents

zap docs agents

Agent Quickstart

Skill JSON

Agent Quickstart

Point your coding agent at the Zap project URL or repo, then ask it to install or read the Zap skills before editing recipes.

Machine-readable skill registry:

https://zap.wzrd.tech/api/skills
https://zap.wzrd.tech/api/skills/zap
https://zap.wzrd.tech/api/skills/zap-authoring
https://zap.wzrd.tech/api/skills/zap?format=json

Codex

Use the Zap skills from https://zap.wzrd.tech/api/skills and validate with:
npx @wzrdtech/zap@0.1.0 validate
npx @wzrdtech/zap@0.1.0 run agent/skills/zap-world-cup-entrance/Zap.md --json

Claude Code

Read AGENTS.md, then use skills/zap-authoring/SKILL.md before editing any Zap.md recipe.
Run zap validate and zap lint before committing.

Cursor

Use Zap.md frontmatter as the source of truth. Keep prompt files under the same skill directory.
Default to provider: mock until the user asks for live spend.

OpenClaw and Hermes

Treat each agent/skills/zap-*/ directory as a portable capability.
Use docs/reference/schema.md for recipe fields and docs/reference/cli.md for command behavior.

zap docs zap-spec

Zap Spec

Skill JSON

Zap Spec

Zap.md is the source of truth for a one-shot content recipe. It lives inside an Eve skill directory:

agent/skills/zap-<slug>/
  SKILL.md
  Zap.md
  prompts/*.md

Minimum valid frontmatter:

---
zap: launch-trailer
version: 1
description: A short creator video.
budget:
  estimate_usd: 0
  cap_usd: 5
defaults:
  provider: mock
  aspect: "9:16"
inputs:
  PROMPT:
    type: textarea
    label: Prompt
    required: true
steps:
  - id: initial_frame
    kind: image.gen
    provider: mock
    model: mock-image
    prompt: prompts/initial-frame.md
  - id: initial_gen
    kind: video.gen
    provider: mock
    model: mock-video
    inputs: [initial_frame]
    duration_s: 15
    prompt: prompts/initial-gen.md
  - id: stitch
    kind: stitch
    inputs: [initial_gen]
output: Zap.mp4
---

Rules agents must preserve:

Every steps[].id is unique.
Prompt variables like {PROMPT} must exist in inputs.
budget.estimate_usd must not exceed budget.cap_usd.
Mock provider is valid for tests and demos.
Live provider runs require explicit --live or authenticated web confirmation.

Validate after every recipe edit:

npx @wzrdtech/zap@0.1.0 validate
npx @wzrdtech/zap@0.1.0 lint

zap docs steps

Steps

Skill JSON

Steps

Zap pipelines follow the creative grammar:

InitialFrame -> InitialGen -> InitialGenReViz? -> ExtendGen x N -> Zap.mp4

Supported step kinds:

image.gen: create a first frame, storyboard, character sheet, or reference image.
image.edit: transform an input image while preserving subject identity.
video.gen: animate image or prompt inputs into a clip.
video.extend: continue a clip from its last frame.
video.edit: revise a clip with a prompt or composition layer.
video.upscale: produce a higher-resolution clip.
audio.tts: generate voiceover.
audio.music: generate music.
audio.sfx: generate sound effects.
keyframes: extract, score, or prepare frames for the next step.
stitch: combine assets into the final Zap artifact.

Use inputs to name upstream step dependencies:

steps:
  - id: initial_gen
    kind: video.gen
    inputs: [initial_frame]

Use HyperFrames only when composition is needed:

stitch:
  engine: hyperframes
  format: mp4
  quality: standard

When HyperFrames is unavailable, Zap falls back to the local stitch path and records the fallback on the run step.

zap docs providers

Providers

Skill JSON

Providers

Zap separates recipe planning from provider execution.

Provider priority for v1:

mock: deterministic zero-cost outputs for docs, tests, and unauthenticated demos.
gmi: primary live image/video provider path.
fal: secondary live provider path.
runware, prodia, openrouter, ai_gateway: BYOK-ready secret types.

Provider keys are never required for mock runs:

ZAP_PROVIDER=mock npx @wzrdtech/zap@0.1.0 run world-cup-entrance --json

Live runs require explicit approval:

npx @wzrdtech/zap@0.1.0 run world-cup-entrance --live --input SELFIE=./selfie.png

Web live runs require wallet auth and user-owned provider keys stored in Supabase:

gmi_api_key
gmi_org_id
fal_key
runware_key
prodia_key
openrouter_key
ai_gateway_api_key

Provider adapters must return run-safe metadata: ids, status, URLs, cost, and errors. They should not return large media blobs to the agent context.

zap docs budget

Budget

Skill JSON

Budget

Every Zap declares an estimated cost and a hard cap:

budget:
  estimate_usd: 1.25
  cap_usd: 5

Budget rules:

CLI mock runs quote $0.00.
CLI live plans reject runs whose quote exceeds cap_usd.
Web live runs enforce budget on the server before provider submission.
Provider adapters should attach observed cost to each run step when available.
Repeated video.extend chains must be counted before submission.

Use mock mode while authoring:

npx @wzrdtech/zap@0.1.0 run zap-world-cup-entrance --json

Use live mode only after the creator has approved spend:

npx @wzrdtech/zap@0.1.0 run zap-world-cup-entrance --live --input SELFIE=./selfie.png

If a budget check fails, lower step count, switch models, or raise budget.cap_usd with explicit owner approval.

zap docs agent

Agent Framework

Skill JSON

Agent Framework

Zap is an Eve app convention. Each recipe is a portable skill directory that coding agents can read, edit, validate, and run.

Agent contract:

Read SKILL.md first.
Treat Zap.md frontmatter as executable recipe metadata.
Keep prompts in prompts/*.md.
Use deterministic run_zap or zap run for creator flows.
Use primitive tools only for creative development or new recipe authoring.
Keep provider spend opt-in.

Root flow:

creator request
  -> select zap-<slug> skill
  -> collect declared inputs
  -> validate budget
  -> run mock or live pipeline
  -> return run id and final asset URL

Agent quickstarts:

npx @wzrdtech/zap@0.1.0 docs agents

Remote skill registry:

https://zap.wzrd.tech/api/skills
https://zap.wzrd.tech/api/skills/zap
https://zap.wzrd.tech/api/skills/zap-authoring

zap docs webapp

Web App

Skill JSON

Web App

The Zap web app is the creator and developer surface deployed at zap.wzrd.tech.

Primary routes:

/: public landing page and first product signal.
/gallery: installed Zap gallery.
/docs: docs entry point.
/quickstart: agent quickstarts for Codex, Claude Code, Cursor, OpenClaw, Hermes, and similar tools.
/studio: Eve-powered agent studio.
/zap/[slug]: one-click creator runner.
/runs/[runId]: run progress and output detail.
/settings: wallet auth and BYOK provider secrets.

Auth posture:

Public docs, gallery, and mock demo runs are accessible.
Creator live runs and provider secrets require wallet-authenticated Supabase bearer tokens.
Basic Auth may still protect legacy provider/Eve surfaces where configured.

Smoke production after deploy:

curl -I https://zap.wzrd.tech/
curl -I https://zap.wzrd.tech/docs
curl -I https://zap.wzrd.tech/studio

zap docs convex

Convex

Skill JSON

Convex

Convex is the source of truth for live Zap runtime state.

Tables:

zaps: installed and discoverable recipe metadata.
runs: run status, creator input summary, budget, and provider mode.
steps: ordered pipeline step state.
assets: generated images, clips, audio, and stitched outputs.
feedback: creator ratings, RLHF notes, and eval signals.
cronLogs: poller and drain execution logs.

Runtime flow:

POST /api/zaps/run
  -> validate Zap.md
  -> create run + steps
  -> submit provider job
  -> enqueue Upstash poll job
  -> drain endpoint polls provider
  -> update Convex idempotently

Local checks:

npm run convex:codegen
npm run eve:info

Mock CLI runs do not require Convex. Web live runs do.

zap docs deploy

Deploy

Skill JSON

Deploy

Production target:

Vercel project: zap
Domain: zap.wzrd.tech
Node: 24.x
Supabase project: wzrdstudio / ixkkrousepsiorwlaycp

Vercel app env:

NEXT_PUBLIC_SUPABASE_URL
NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY or NEXT_PUBLIC_SUPABASE_ANON_KEY
ZAP_SECRET_REVEAL_TOKEN
ZAP_WALLET_PROOF_FUNCTION
NEXT_PUBLIC_CONVEX_URL
CONVEX_URL
UPSTASH_REDIS_REST_URL
UPSTASH_REDIS_REST_TOKEN
BLOB_READ_WRITE_TOKEN

Supabase Edge Function secrets:

USER_SECRETS_ENCRYPTION_KEY
ZAP_SECRET_REVEAL_TOKEN
ZAP_WALLET_AUTH_SECRET
ZAP_WALLET_TOKEN_TTL_SECONDS

Deploy sequence:

npm test
npm run typecheck
npm run build
vercel deploy --prod --yes

Apply Supabase migrations before enabling live BYOK runs.

zap docs troubleshooting

Troubleshooting

Skill JSON

Troubleshooting

Node Fails With `simdjson`

Use a working Node 24 runtime. This repo expects Node 24.x.

node --version
npx @wzrdtech/zap@0.1.0 doctor --json

`zap validate` Finds No Recipes

Run from a Zap project root containing:

agent/skills/zap-*/Zap.md

Or pass a recipe directly:

npx @wzrdtech/zap@0.1.0 validate agent/skills/zap-world-cup-entrance/Zap.md

Live Run Refuses To Start

Check three things:

Did you pass --live?
Does the quote exceed budget.cap_usd?
Are provider keys available in Supabase or env?

Supabase Secrets Return Empty

/api/secrets returns configured: true before a user is authenticated. Listing, saving, deleting, or revealing keys requires a Supabase bearer token.

HyperFrames Is Missing

stitch.engine: hyperframes is optional. If npx hyperframes --version fails, Zap falls back to the local stitch path and records the fallback error on the step.

zap docs eve

Eve

Skill JSON

Eve

Zap runs on Eve. Keep Eve pinned for this v1 build unless a blocking bug forces an upgrade.

Before editing Eve agent code, read the matching Eve guide in:

node_modules/eve/docs/

Read order for Zap work:

node_modules/eve/docs/introduction
node_modules/eve/docs/getting-started
node_modules/eve/docs/project-layout
node_modules/eve/docs/agent-config
node_modules/eve/docs/skills
node_modules/eve/docs/tools
node_modules/eve/docs/channels
node_modules/eve/docs/sandbox
node_modules/eve/docs/deployment

Useful commands:

npm run eve:info
npm run eve:build

Zap-specific agent instructions live in:

agent/instructions.md
agent/tools/
agent/skills/zap-*/