CLAUDE.md@shared git:20260808.7d8596eA

Immutable. This exact content is served forever at /api/v1/blob/7567ec34478643a9.

# Claude Code — project instructions

> **Paths in this file are relative to the REPO ROOT, not to `shared/`.** This file is `@`-included
> into the root `CLAUDE.md`, which is the context it is read in. They are written as code rather
> than as markdown links for that reason: a link that resolves only from one directory is a link
> that is broken from the other, and this file legitimately gets opened both ways.

## First-time setup

If `.env` does not exist, tell the user to run `./scripts/setup.sh` or walk them through:
1. Copy `.env.example` to `.env`.
2. Paste their API key into `.env` (line: `*_API_KEY=`).
3. Run `./scripts/check-*-env.sh` to verify.

If `MASTER_CONTEXT.md` does not exist, copy `MASTER_CONTEXT.template.md` to `MASTER_CONTEXT.md`.

When the session IS the setup, setup is the whole job and the close is SHORT: a line or
two of status (the key works, or the one step left), then plain text saying what the user
can now ask for (the installed skills are the list), then stop. Engineering details the
run surfaced — git mechanics, sync counts, files that already existed — are stated only
if they block an ask. If the repo's root `AGENTS.md` carries a setup-close template, use
it verbatim. Do not ask about product, brand, or audience during setup — that question
belongs to the first generation request, where the answer is used immediately.

## Every session

1. Read **`MASTER_CONTEXT.md`** (repo root) for brand voice, defaults, and accumulated learnings.
2. Use the API skill in `.claude/skills/` for API calls, prompts, and polling.
3. The first time the user asks to generate something and `MASTER_CONTEXT.md` is missing a field that request needs (default product, brand voice), ask for it then — once — and **write the answer back into `MASTER_CONTEXT.md`** so no future session asks again. A setup-only session asks for nothing. Prices are never among the fields: quote costs from a live estimate call, never from a stored number.
4. Everything you write that is not repo content goes in a gitignored home — `generated/`, `outputs/<job>/`, `prompts/`, `iterations/`, `logs/` — never a new top-level directory, so `git status` ends as clean as it started. If the repo's root `AGENTS.md` carries the session-workspace rule ("Every session"), it is stated in full there.

## After significant changes

Append a short dated note to **MASTER_CONTEXT.md** under Changelog (Decision / What changed / Why).

## Skill edits

Edit the canonical source under `skills/`. Run `./scripts/sync-skill.sh` to copy changes to `.claude/skills/` and `.cursor/skills/`.

## Image-ad skill ecosystem (cross-API)

This repo ships a 3-skill ecosystem for generating standalone Meta image-ad creatives. **Read `shared/skills/image-ad-prompting/OVERVIEW.md` (from the repo root) before invoking any of these skills** — it explains the decision tree (gpt-image-2 vs Nano Banana), the shared 40-template library, the hand-off to the separate `meta-ad-builder` skill, and what's out of scope.

Quick map:
- **Generate from a brief** → `chatgpt-image-ad` (typography / UI mimicry) or `nano-banana-image-ad` (photoreal / lifestyle / multi-ref).
- **Clone an existing ad into a reusable template** → `image-ad-clone` (single backend-agnostic skill; asks you which generator to validate against at Phase 1, optionally cross-validates against the other backend at Phase 8).
- **Pull from / add to the shared library** → `shared/skills/image-ad-prompting/prompting/prompt-library.md` (40 ready-to-use validated prompts).
- **Hand off finished images to Meta** → separate `meta-ad-builder` skill; the image-ad skills produce images only.