macro-pickle: Instructions file for Claude Code

macro-pickle — AI Creative Tooling

Project Overview

Local, database-free AI creative toolkit — image & video generation plus a typed, brand-aware Prompt Engine, driven through Claude (CLI scripts, a desktop MCP server, and Claude Code skills/commands). There is no database and no web app: every rail writes files to disk, and finalized prompts are exported as copy-paste markdown into a notes vault of your choosing.

Brand profiles and campaign prompt packs are intentionally NOT in this repo — it ships one worked example (quiet-desk) and stays brand-agnostic. Keep your own brands in a private directory and point MACRO_PICKLE_BRANDS_DIR at it.

Technology Stack

Common Commands

pnpm install
cp .env.example .env.local      # add GOOGLE_API_KEY + FAL_KEY
pnpm lint                       # tsc --noEmit (type-check the whole toolkit)

# Prompts
pnpm prompt --brands            # list brand profiles
pnpm prompt --image --brand quiet-desk --json '{"subject":"lamp hero shot"}' --save

# Image generation
pnpm img "neon pickle mascot"   # Imagen 4.0 → MACRO_PICKLE_EXPORT_DIR
pnpm fal --model flux-pro "…"   # fal.ai (FLUX / Recraft / Ideogram / SD3.5)
pnpm nano                       # Nano Banana face-lock from reference photos

# Video generation
pnpm veo                        # Google Veo (t2v / i2v / --refs ASSET lock)
pnpm kling                      # Kling via fal.ai (i2v / t2v / start+end)

# Video EDITING — Gemini Omni Flash (PAID, ~$0.10/s output; no free tier)
pnpm omni --video ref.mp4 --prompt "…"    # manipulate a reference video in plain language
pnpm omni --continue <id> --prompt "…"    # chain conversational refinements (multi-turn)
pnpm omni --prompt "…" --dry-run          # prompt + cost estimate, no API call

# Media pipeline (two-stage: idea → reference frames → curate → video)
pnpm scene:new <slug>           # scaffold a scene.json
pnpm scene:refs <slug>          # Stage 1: generate reference frames
pnpm scene:select <slug> <ids>  # curate the keepers
pnpm scene:video <slug>         # Stage 2: selected frames → video (scene.json "model": "omni-flash" routes via Omni, paid)

# Store batch clips (gen5 product refs → clips), spend-gated + resume-safe
pnpm rank-skus --store <dir> --top 8 --ids   # rank a store's SKUs by sales → top-N ids
pnpm gen-clips --store <dir> --dry-run       # generic batch (Veo free + Kling paid); dry-run first
pnpm gen-clips --store <dir> --yes           # live paid run (ENFORCED: --yes + --max-spend cap; existing clips skipped)
#   per-store tuning lives in content/clip-scenes/<store>.json (see example-store.json)

# Vision / UGC
pnpm describe                   # Gemini: product OCR + in-use scene rec (--paddle for sidecar)
pnpm analyze-video              # describe a reference clip
pnpm mcp:image                  # run the desktop MCP server