# [Your Project Title Here]

**Format:** Batch Renderer Canonical Specification
**Target Model:** Nano-Banana

---

<!--
╔══════════════════════════════════════════════════════════════════╗
║  FOR LLMs AND HUMANS: HOW THIS FILE WORKS                       ║
║                                                                  ║
║  The batch-renderer CLI parses this file using specific rules.  ║
║  Read this section before generating or editing concepts.        ║
╚══════════════════════════════════════════════════════════════════╝

PARSER RULES — what you MUST follow:

 1. SECTION HEADINGS must be level-2 and start with a number+period:
      ## 1. Section Name         ✅  (correct)
      ## Section Name            ❌  (no number — section ignored)
      # 1. Section Name          ❌  (wrong level — section ignored)
      ### 1. Section Name        ❌  (wrong level — treated as concept)

 2. CONCEPT HEADINGS must be level-3 and use "### Concept N.M: Title":
      ### Concept 1.1: My Title  ✅  (correct)
      ### Concept 1.1 My Title   ❌  (missing colon — not extracted)
      ## Concept 1.1: My Title   ❌  (wrong level — not extracted)
      ### 1.1: My Title          ❌  (missing "Concept" — not extracted)

 3. WHAT YOU CAN FREELY CHANGE:
      - The section name text after "## N."     → ## 1. Anything here
      - The concept title text after the colon  → ### Concept 1.1: Anything here
      - The numbers themselves (N and M)        → ### Concept 7.23: Title

 4. WHAT WILL BREAK THE PARSER:
      - Removing the "Concept " keyword
      - Removing the colon ":" after "Concept N.M"
      - Changing heading levels (##, ###)
      - Non-numeric N or M

 5. METADATA (optional) appears immediately after the heading:
      ### Concept 1.1: My Title
      - model: GPT-Image-1      ← per-concept model override
      - aspect: 3:2             ← passed directly to API
      - quality: high           ← passed directly to API
      - skip: true              ← skip this concept
      - retries: 5              ← override retry count

      Rules: must be "- key: value" bullets, must be BEFORE the prompt text,
      blank lines between metadata and text are fine.

 6. TAG LIBRARY (optional reusable components) — see section below.

-->

---

## TAG LIBRARY

<!--
  Define reusable text components here. Use them in concept prompts
  with [TAG_NAME] or [TAG_NAME:variant] syntax.

  RULES:
  - Tag names: UPPERCASE_WITH_UNDERSCORES
  - Variants: append :lowercase-variant
  - Reference other tags inside definitions with {TAG_NAME}
  - The TAG LIBRARY ends at the first "---" or numbered section heading
  - Multiple TAG LIBRARY sections allowed; later ones can override earlier

  NAMING PATTERN:  [A-Z_][A-Z0-9_]* (optionally :[A-Za-z0-9_-]+)
    [WORLD_STYLE]              ✅
    [CHARACTER:variant-1]      ✅
    [world_style]              ❌  (lowercase — not recognized as tag)
    [WORLD STYLE]              ❌  (space — not recognized as tag)
-->

## [STYLE_BASE]
Replace this with your base style description. Used across many concepts.

## [STYLE_BASE:variant-a]
{STYLE_BASE} with additional modifications for variant A.

## [CHARACTER_DESCRIPTION]
Replace this with a reusable character description.

---

## 1. First Section

### Concept 1.1: Example Without Metadata

[STYLE_BASE]

A detailed description of the image you want to generate. Tags expand inline — the model receives the full substituted text, not the tag names.

### Concept 1.2: Example With Metadata
- model: GPT-Image-1
- aspect: 3:2
- quality: high

[STYLE_BASE:variant-a]

[CHARACTER_DESCRIPTION]

The metadata above overrides defaults for this specific concept. Tag references expand before the prompt is sent to the model. Write additional context after the tags.

### Concept 1.3: Skip Example
- skip: true

This concept will be skipped during rendering. Useful for work-in-progress prompts.

### Concept 1.4: Minimal Example (No Tags)

You don't need a TAG LIBRARY. Short prompts without tags work fine.

---

## 2. Second Section

### Concept 2.1: Numeric Metadata
- aspect: 1:1
- retries: 5

A square composition. The `retries` key controls retry attempts on API failure.

### Concept 2.2: Model Override
- model: Nano-Banana

This concept uses a specific model regardless of the CLI default.

---

<!--
══════════════════════════════════════════════════════════════════
 QUICK REFERENCE
══════════════════════════════════════════════════════════════════

FILE STRUCTURE:
  [optional TAG LIBRARY section]
  ## N. Section Name
  ### Concept N.M: Concept Title
  - optional: metadata key: value
  - optional: more metadata
  [blank line]
  Prompt text here. Can span multiple paragraphs.
  Tags expand here: [TAG_NAME] becomes the full definition.

STANDARD METADATA KEYS (handled by batch-renderer itself):
  model     Override model for this concept
  format    Override output file format (png, jpg, webp)
  skip      Skip this concept (true/false)
  retries   Number of retry attempts (default: 3)

CUSTOM METADATA KEYS (passed through to API via extra_body):
  aspect    Aspect ratio — values vary by model (e.g. "3:2", "1:1", "auto")
  quality   Image quality (e.g. "low", "medium", "high")
  Any other key-value pair is forwarded to the model API.
  Check your model's documentation for supported parameters.

TAG SYNTAX:
  [TAG_NAME]           Reference a tag (expands to its definition)
  [TAG_NAME:variant]   Reference a variant
  {TAG_NAME}           Reference another tag INSIDE a tag definition
                       (use curly braces within TAG LIBRARY only)

COMMON GOTCHAS FOR LLMs GENERATING THIS FORMAT:
  - Always use "### Concept N.M: Title" — never omit "Concept" or ":"
  - Metadata must use "- key: value" format, not YAML or JSON
  - Tag names in prompts use [SQUARE_BRACKETS], not {curly} or (parens)
  - {Curly braces} are only for tag-within-tag references in definitions
  - Numbers N.M in concept headings don't need to match section numbers
    strictly, but should be unique (1.1, 1.2, 2.1, etc.)

══════════════════════════════════════════════════════════════════
-->
