Step4 References Assets

Each reference directory must contain at least 3 images in .png, .jpg, .jpeg, or .webp format.

Execute

1. Resolve project ID. Default to default if not specified.
2. Read bible/characters.json and extract all character IDs.
3. Read bible/locations.json and extract all location IDs.
4. For each character ID: a. Ensure directory exists at reference/characters/<CHAR_ID>/. b. Verify at least 3 reference images are present. c. Optionally create/update guide.json with invariants and allowed variations.
5. For each location ID: a. Ensure directory exists at reference/locations/<LOC_ID>/. b. Verify at least 3 reference images are present. c. Optionally create/update guide.json.
6. If reference images are missing, flag the gap. The agent can generate reference prompts for Nano Banana Pro 3 (see Platform Best Practices below).

API Endpoints

If the server is running:

• GET /api/references/characters?project=<id> — list character reference directories and image counts
• GET /api/references/locations?project=<id> — list location reference directories and image counts
• POST /api/references/characters/upload?project=<id> — upload a character reference image (multipart form: entityId, file)
• POST /api/references/locations/upload?project=<id> — upload a location reference image (multipart form: entityId, file)

guide.json Schema (Optional)

{
  "invariants": [
    "Always wears the asymmetric draped outer layer",
    "Hair flows past shoulders in every shot",
    "Warm brown skin tone consistent across all lighting"
  ],
  "allowedVariations": [
    "Lighting angle and intensity may change",
    "Expression ranges from neutral to emotional",
    "Camera distance varies from close-up to wide"
  ],
  "notes": "Primary character — highest reference priority in generation"
}

Platform-Specific Best Practices

Reference Image Quality

• Resolution: Minimum 512x512px. Prefer 1024x1024 or higher for better generation quality.
• Format: PNG preferred for lossless quality. JPG acceptable. WEBP supported.
• Consistency: All references for one entity should show the same person/place. Mixed references confuse the model.

Character Reference Strategy

For each character, aim for:

1. Front-facing portrait: Neutral pose, clear face, full lighting
2. Three-quarter angle: Shows depth and profile features
3. Full body or action pose: Shows costume and proportions
4. Optional: Different lighting condition (dramatic vs soft)

Location Reference Strategy

For each location, aim for:

1. Wide establishing shot: Full environment context
2. Detail shots: Close-ups of visual anchor elements
3. Atmosphere sample: Showing lighting quality and color palette

Nano Banana Reference Generation Prompts

If generating reference images via AI, use this structure:

Front-facing, full body portrait, neutral standing pose
[Character physical description from characters.json]
[Face signature from characters.json]
[Costume description with colors]
Framing: centered composition, full body visible
Shot Size: full body portrait
Angle: eye level, straight-on front view
Background: neutral dark studio backdrop
Lighting: soft even studio lighting from front
Style: clean character reference sheet, high detail, cinematic realism
Negative: no text, logos, watermarks, distorted anatomy, motion blur, cartoon style

Generation Reference Collection

During shot generation (Step 5), the system auto-collects references in this priority:

1. Continuity: Previous shot's last frame (for visual flow)
2. Uploaded: User-selected reference images for this shot/variation
3. Canon: Images from reference/characters/ and reference/locations/

Maximum: 14 input reference images per generation call. Primary characters get priority allocation.

Quality Checks

Before marking complete:

1. Every character ID in characters.json has a matching directory under reference/characters/.
2. Every location ID in locations.json has a matching directory under reference/locations/.
3. Each reference directory contains at least 3 images (.png/.jpg/.jpeg/.webp).
4. Images are not placeholder files (each should be > 10KB).
5. No orphaned reference directories (directories without matching canon IDs).

Completeness Check

project=default
node -e "
  const fs = require('fs');
  const path = require('path');
  const base = 'projects/' + process.env.P + '/';
  let ok = true;
  const imgExts = ['.png', '.jpg', '.jpeg', '.webp'];
  function countImages(dir) {
    if (!fs.existsSync(dir)) return 0;
    return fs.readdirSync(dir).filter(f => imgExts.includes(path.extname(f).toLowerCase())).length;
  }
  // Check characters
  try {
    const chars = JSON.parse(fs.readFileSync(base + 'bible/characters.json', 'utf8'));
    for (const c of (chars.characters || [])) {
      const d = base + 'reference/characters/' + c.id;
      const n = countImages(d);
      if (n < 3) { console.error(c.id + ': ' + n + ' images (need 3+)'); ok = false; }
      else { console.log(c.id + ': ' + n + ' images OK'); }
    }
  } catch (e) { console.error('characters.json: ' + e.message); ok = false; }
  // Check locations
  try {
    const locs = JSON.parse(fs.readFileSync(base + 'bible/locations.json', 'utf8'));
    for (const l of (locs.locations || [])) {
      const d = base + 'reference/locations/' + l.id;
      const n = countImages(d);
      if (n < 3) { console.error(l.id + ': ' + n + ' images (need 3+)'); ok = false; }
      else { console.log(l.id + ': ' + n + ' images OK'); }
    }
  } catch (e) { console.error('locations.json: ' + e.message); ok = false; }
  if (!ok) process.exit(1);
  console.log('Step 4 complete.');
" P="$project"

LLM Guidance

• This step primarily involves file system operations (creating directories, placing images) and cannot be fully automated by text generation alone.
• The agent should verify directory structure and image counts, and flag missing references.
• If generating reference prompts for Nano Banana, use the template in Platform-Specific Best Practices above.
• Output format for guide.json: Valid JSON only. No markdown code fences.
• When reporting results, list each entity with its image count and status (OK / missing / insufficient).
• Reference skills/_shared/references/universal-prompt-rules.md for reference image system details.
• Reference references/reference-image-guide.md for detailed curation best practices.

Step 4 is complete only when every canon character and location has a reference directory with 3+ images.