@hienlh/ppm 0.9.80 → 0.9.81

package/.opencode/skills/ai-artist/references/character-consistency.md

@@ -0,0 +1,160 @@
+# Character Consistency in Image Generation
+
+Generate multiple images of the same character across different scenes, poses, and contexts while maintaining visual identity.
+
+## When to Use
+
+- Video storyboards with recurring characters
+- Marketing campaigns with brand mascots/personas
+- Comic/illustration series with same characters
+- Product demos featuring consistent human subjects
+
+## Workflow: Portrait-First Approach
+
+### Step 1: Generate Character Portrait
+
+Create a detailed reference portrait first. Use Nano Banana Pro for best quality.
+
+```bash
+# Generate character portrait with Pro model
+.opencode/skills/.venv/bin/python3 .opencode/skills/ai-multimodal/scripts/gemini_batch_process.py \
+  --task generate --model gemini-3-pro-image-preview \
+  --prompt "<character_portrait_prompt>" \
+  --aspect-ratio 2:3 --size 4K --output <character_name>-portrait.png
+```
+
+**Portrait Prompt Template:**
+```
+Professional portrait photograph of [character_name]: [gender], [age range],
+[ethnicity/skin tone], [hair: color, style, length], [eye color],
+[facial features: shape, distinguishing marks], [expression],
+[clothing: detailed description], [accessories].
+Shot on Canon EOS R5, 85mm f/1.4 lens, soft studio lighting,
+neutral gray background, sharp focus on face, 4K resolution.
+```
+
+**Critical Details to Lock:**
+- Hair: exact color, style, length
+- Eyes: color, shape
+- Face: shape, distinguishing features
+- Clothing: specific items, colors, materials
+- Build: body type, height impression
+- Accessories: glasses, jewelry, etc.
+
+### Step 2: Use Portrait as Reference for Scene Frames
+
+Pass the portrait image as reference when generating subsequent frames.
+
+**Method A: CLI with --files (single reference)**
+```bash
+# Generate scene with character reference
+.opencode/skills/.venv/bin/python3 .opencode/skills/ai-multimodal/scripts/gemini_batch_process.py \
+  --task generate --model gemini-3-pro-image-preview \
+  --files <character_name>-portrait.png \
+  --prompt "Same person from the reference image, now [scene_description]. Maintain exact facial features, hair, and clothing." \
+  --aspect-ratio 16:9 --size 4K --output scene-01.png
+```
+
+**Method B: Python API (multiple references)**
+```python
+from google import genai
+from google.genai import types
+from PIL import Image
+
+client = genai.Client(api_key=os.getenv('GEMINI_API_KEY'))
+portrait = Image.open('character-portrait.png')
+
+response = client.models.generate_content(
+    model='gemini-3-pro-image-preview',
+    contents=[
+        'Same person from the reference photo, now standing in a modern office. '
+        'Maintain exact same facial features, hair color/style, eye color, and clothing. '
+        'Medium shot, natural office lighting, 16:9 cinematic composition.',
+        portrait
+    ],
+    config=types.GenerateContentConfig(
+        response_modalities=['IMAGE'],
+        image_config=types.ImageConfig(aspect_ratio='16:9')
+    )
+)
+```
+
+### Step 3: Multi-Character Scenes
+
+For scenes with multiple characters, pass all character portraits as references.
+
+```python
+# Up to 5 human references in Pro model
+char_a = Image.open('character-a-portrait.png')
+char_b = Image.open('character-b-portrait.png')
+
+response = client.models.generate_content(
+    model='gemini-3-pro-image-preview',
+    contents=[
+        'Two people from the reference photos having a conversation in a cafe. '
+        'Person 1 (first reference) sits on the left, Person 2 (second reference) on the right. '
+        'Maintain exact facial features, hair, clothing for both characters. '
+        'Wide shot, warm cafe lighting.',
+        char_a, char_b
+    ],
+    config=types.GenerateContentConfig(
+        response_modalities=['IMAGE'],
+        image_config=types.ImageConfig(aspect_ratio='16:9')
+    )
+)
+```
+
+## Prompt Engineering for Consistency
+
+### Identity Anchors (include in EVERY prompt)
+
+Always repeat key identity descriptors to anchor the character:
+
+```
+Same person from the reference: [hair color] [hair style] hair,
+[eye color] eyes, [clothing description], [key accessories].
+```
+
+### Scene Variation Prompt Template
+
+```
+[Identity anchor from reference image].
+Now [action/pose] in [environment/setting].
+[Lighting description]. [Camera angle and lens].
+[Mood/atmosphere]. Maintain character identity perfectly.
+```
+
+### Anti-Drift Techniques
+
+| Technique | Example |
+|-----------|---------|
+| Repeat identity | "Same silver-haired woman with neon visor" in every prompt |
+| Lock clothing | "Wearing the EXACT same red leather coat from reference" |
+| Specify unchanged | "Face, hair, and build MUST match reference exactly" |
+| Anchor features | Put identity descriptors FIRST in prompt |
+| Use ALL CAPS | "SAME person, IDENTICAL features" for emphasis |
+
+## Model Selection
+
+| Model | Character Consistency | Max Human Refs | Best For |
+|-------|----------------------|----------------|----------|
+| `gemini-3-pro-image-preview` | Excellent | 5 | Final production frames |
+| `gemini-2.5-flash-image` | Good | 3 | Quick iterations, drafts |
+
+**Always use Pro model** for character-consistent storyboard frames.
+
+## Limitations
+
+- Max 5 human reference images per request (Pro model)
+- Clothing changes possible but reduce consistency
+- Extreme pose changes may affect facial similarity
+- Style changes (photorealistic → cartoon) reduce identity preservation
+- No deterministic seed control in Nano Banana API
+
+## Tips
+
+1. **Portrait quality matters** - higher quality reference = better consistency
+2. **Neutral expression first** - generate neutral portrait, then add expressions
+3. **Same style throughout** - keep art style consistent across all frames
+4. **Front-facing portrait** - 3/4 angle works best as reference
+5. **Describe, don't assume** - always describe the character explicitly, don't rely on "same person" alone

package/.opencode/skills/ai-artist/references/domain-code.md

@@ -0,0 +1,66 @@
+# Code Generation Patterns
+
+## Function Implementation
+```
+Write a [language] function:
+- Input: [params with types]
+- Output: [return type]
+- Behavior: [logic]
+
+Requirements:
+- Edge cases: [list]
+- Error handling: [approach]
+- Performance: O([complexity])
+```
+
+## Code Review
+```
+Review for:
+1. Bugs/logic errors
+2. Security vulnerabilities
+3. Performance issues
+4. Style violations
+5. Missing edge cases
+
+Format: Issue, line number, severity, fix.
+```
+
+## Refactoring
+```
+Refactor to:
+- [Improvement goal]
+- Maintain backward compatibility
+- Keep public API
+- Add comments for complex logic
+Show before/after.
+```
+
+## Debugging
+```
+<error>[Error message/behavior]</error>
+<code>[Relevant code]</code>
+<context>[When it occurs]</context>
+
+Analyze:
+1. Root cause
+2. Why it happens
+3. Fix with explanation
+4. Prevention strategy
+```
+
+## Test Generation
+```
+Generate tests for [function/class]:
+- Framework: [jest/pytest/etc]
+- Coverage: happy path, edge cases, errors
+- Include: setup, assertion, cleanup
+- Mock: [external dependencies]
+```
+
+## Documentation
+```
+Document this [function/class/API]:
+- Format: [JSDoc/docstring/OpenAPI]
+- Include: description, params, returns, examples
+- Note: edge cases, errors, deprecations
+```

package/.opencode/skills/ai-artist/references/domain-data.md

@@ -0,0 +1,72 @@
+# Data & Analysis Patterns
+
+## Structured Extraction
+```
+Extract from text:
+<text>[content]</text>
+
+Return JSON:
+{
+  "field1": "value or null",
+  "field2": ["array"]
+}
+
+Rules:
+- Exact matches only
+- Confidence score if uncertain
+- null for missing
+```
+
+## Document Analysis
+```
+Analyze [document type]:
+1. Summary (2-3 sentences)
+2. Key entities (people, orgs, dates)
+3. Main topics (ranked)
+4. Sentiment: positive/neutral/negative
+5. Action items
+```
+
+## Comparison
+```
+Compare [A] and [B]:
+| Criterion | A | B |
+|-----------|---|---|
+| [Factor 1] | | |
+| [Factor 2] | | |
+
+Recommendation: [choice] for [use case]
+```
+
+## Problem Solving
+```
+Problem: [description]
+
+Analyze:
+1. Root cause (5 whys)
+2. Contributing factors
+3. Options (pros/cons)
+4. Recommendation
+5. Implementation steps
+6. Risk mitigation
+```
+
+## Data Transformation
+```
+Transform data:
+- Input format: [CSV/JSON/etc]
+- Output format: [target]
+- Rules: [mapping logic]
+- Validation: [constraints]
+
+Handle: missing values, type mismatches.
+```
+
+## Summarization
+```
+Summarize [content]:
+- Length: [sentences/words]
+- Focus: [key themes]
+- Audience: [technical/general]
+- Preserve: [critical details]
+```

package/.opencode/skills/ai-artist/references/domain-marketing.md

@@ -0,0 +1,66 @@
+# Marketing Copy Patterns
+
+## Headlines
+```
+Write 5 headline variations for [product].
+Frameworks:
+1. How to [benefit]
+2. [Number] ways to [solve problem]
+3. The secret to [outcome]
+4. Why [audience] love [product]
+5. [Timeframe] to [transformation]
+```
+
+## Product Descriptions
+```
+<product>[Name, features]</product>
+<audience>[Demographics, pain points]</audience>
+
+Write description that:
+- Opens with benefit (not feature)
+- Addresses [main objection]
+- Social proof placeholder
+- Clear CTA
+- Tone: [brand voice]
+- Length: [word count]
+```
+
+## Email Subject Lines
+```
+Generate 10 subject lines for [campaign].
+Mix approaches:
+- Curiosity gap
+- Urgency/scarcity
+- Personalization
+- Question format
+- Number/list
+Under 50 chars. Test 2-3 with emojis.
+```
+
+## Ad Copy
+```
+Platform: [Google/Meta/LinkedIn]
+Objective: [awareness/conversion]
+Character limit: [limit]
+
+Create [N] variations with:
+- Hook (first 5 words critical)
+- Value proposition
+- Social proof element
+- CTA matching platform norms
+```
+
+## Landing Pages
+```
+<offer>[Product/service]</offer>
+<goal>[signup/purchase/download]</goal>
+
+Write sections:
+1. Hero headline + subhead
+2. Problem agitation
+3. Solution introduction
+4. 3-5 benefit bullets
+5. Social proof
+6. CTA with urgency
+7. FAQ (3 objections)
+```

package/.opencode/skills/ai-artist/references/domain-patterns.md

@@ -0,0 +1,33 @@
+# Domain-Specific Prompt Patterns
+
+Quick reference index. Load specific domain file for detailed patterns.
+
+## Domains
+
+| Domain | File | Use Cases |
+|--------|------|-----------|
+| Marketing | `domain-marketing.md` | Headlines, product copy, emails, ads |
+| Code | `domain-code.md` | Functions, review, refactoring, debugging |
+| Writing | `domain-writing.md` | Stories, characters, dialogue, editing |
+| Data | `domain-data.md` | Extraction, analysis, comparison, reasoning |
+
+## Universal Pattern
+
+All domain prompts follow:
+```
+<context>
+[Domain-specific background]
+</context>
+
+<task>
+[Specific action]
+</task>
+
+<constraints>
+[Quality criteria, format, length, tone]
+</constraints>
+
+<output>
+[Expected structure]
+</output>
+```

package/.opencode/skills/ai-artist/references/domain-writing.md

@@ -0,0 +1,68 @@
+# Creative Writing Patterns
+
+## Story Outline
+```
+Create [length] story outline:
+- Genre: [genre]
+- Protagonist: [brief]
+- Conflict: [type]
+- Setting: [time/place]
+
+Structure:
+1. Hook/Opening
+2. Inciting incident
+3. Rising action (3 beats)
+4. Climax
+5. Resolution
+```
+
+## Character Voice
+```
+Write as [character]:
+- Background: [history]
+- Speech: [patterns, vocab]
+- Emotion: [current state]
+- Goal: [scene objective]
+
+Maintain voice consistency.
+```
+
+## Dialogue
+```
+Write dialogue between [A] and [B]:
+- Scene: [context]
+- Tension: [conflict source]
+- Subtext: [what's unsaid]
+
+Each character distinct voice. Show don't tell.
+```
+
+## Scene Description
+```
+Describe [scene]:
+- POV: [character/omniscient]
+- Focus: [sensory details]
+- Mood: [atmosphere]
+- Pacing: [fast/slow/measured]
+
+Use active verbs, concrete details.
+```
+
+## Editing Pass
+```
+Edit this [content type]:
+Focus: [clarity/flow/voice/grammar]
+Preserve: [author's style]
+Flag: [major issues only]
+
+Provide tracked changes with rationale.
+```
+
+## Genre Adaptation
+```
+Rewrite [content] as [genre]:
+- Keep: core plot/message
+- Add: genre conventions
+- Tone: [genre-appropriate]
+- Tropes: [use/subvert specific tropes]
+```

package/.opencode/skills/ai-artist/references/image-generation-workflow.md

@@ -0,0 +1,124 @@
+# Image Generation Workflow
+
+Two-option workflow for generating images with Nano Banana models.
+
+## Quick Reference
+
+| Option | Model | Use Case | Speed | Quality |
+|--------|-------|----------|-------|---------|
+| **Standard** | `gemini-2.5-flash-image` | Search-based prompts, fast iteration | Fast | Good |
+| **Creative** | `gemini-3-pro-image-preview` | Out-of-box art direction, complex scenes | Slower | Best |
+
+## Standard Option (Search-Based)
+
+1. Search for relevant prompts from 6000+ examples
+2. Adapt found prompt to user requirements
+3. Generate with Flash model for speed
+
+```bash
+# Step 1: Find similar prompts
+python3 .opencode/skills/ai-artist/scripts/search.py "<keywords>" --domain examples --max-results 3
+
+# Step 2: Generate with Flash
+.opencode/skills/.venv/bin/python3 .opencode/skills/ai-multimodal/scripts/gemini_batch_process.py \
+  --task generate \
+  --model gemini-2.5-flash-image \
+  --prompt "<adapted_prompt>" \
+  --aspect-ratio <ratio> \
+  --size 2K \
+  --output <output_path>
+```
+
+## Creative Option (Art Direction)
+
+1. Craft original prompt with unique art direction
+2. Apply advanced techniques (narrative, emphasis, constraints)
+3. Generate with Pro model for best quality
+
+```bash
+# Generate with Pro model
+.opencode/skills/.venv/bin/python3 .opencode/skills/ai-multimodal/scripts/gemini_batch_process.py \
+  --task generate \
+  --model gemini-3-pro-image-preview \
+  --prompt "<creative_prompt>" \
+  --aspect-ratio <ratio> \
+  --size 4K \
+  --output <output_path>
+```
+
+## Arguments Reference
+
+| Argument | Values | Description |
+|----------|--------|-------------|
+| `--model` | `gemini-2.5-flash-image`, `gemini-3-pro-image-preview` | Model selection |
+| `--aspect-ratio` | `1:1`, `16:9`, `9:16`, `3:4`, `4:3`, etc. | Output dimensions |
+| `--size` | `1K`, `2K`, `4K` | Resolution (4K only with Pro) |
+| `--num-images` | `1-4` | Number of variations |
+| `--output` | path | Output file path |
+
+## Art Direction Styles (Creative Option)
+
+When using Creative option, apply one of these styles:
+
+| Style | Description | Key Elements |
+|-------|-------------|--------------|
+| **Cyberpunk Neon** | Blade Runner aesthetic | Holographic, neon, rain, cityscape, Japanese text |
+| **Vaporwave** | 80s/90s retro | Greek statues, sunset grid, chrome, Windows 95 |
+| **Isometric 3D** | Miniature diorama | Tilt-shift, floating island, cute buildings |
+| **Bento Grid** | Apple liquid glass | Transparent cards, gradient glow, modular layout |
+| **Editorial** | Magazine style | Clean white, bold typography, professional |
+| **Cinematic** | Film still | Dramatic lighting, wide aspect, lens effects |
+
+## Prompt Structure by Style
+
+### Standard (Flash)
+```
+[Subject] in [setting]. [Style keywords]. [Quality modifiers]. [Aspect ratio context].
+```
+
+### Creative (Pro)
+```
+Create a [art_direction_style] [content_type] titled '[TITLE]'.
+Style: [detailed_aesthetic_description].
+Layout: [composition_details].
+
+Main visual: [central_element_description].
+
+Elements/Modules:
+• [element_1]: [description]
+• [element_2]: [description]
+...
+
+Style details: [colors, effects, typography].
+Footer: [attribution].
+[Quality descriptors].
+```
+
+## Example Workflows
+
+### Infographic (Standard)
+```bash
+# Search for similar
+python3 .opencode/skills/ai-artist/scripts/search.py "bento grid infographic" --domain examples
+
+# Generate
+.opencode/skills/.venv/bin/python3 .opencode/skills/ai-multimodal/scripts/gemini_batch_process.py \
+  --task generate --model gemini-2.5-flash-image \
+  --prompt "Premium bento grid infographic titled 'Marketing Trends'. 8 modules with stats. Purple gradient background." \
+  --aspect-ratio 16:9 --size 2K --output output/infographic.png
+```
+
+### Infographic (Creative - Cyberpunk)
+```bash
+.opencode/skills/.venv/bin/python3 .opencode/skills/ai-multimodal/scripts/gemini_batch_process.py \
+  --task generate --model gemini-3-pro-image-preview \
+  --prompt "Create a cyberpunk neon holographic infographic titled 'MARKETING TRENDS 2026'. Style: Blade Runner meets Ghost in Shell, dark cityscape with rain and neon reflections. Main visual: Giant holographic AI head made of data streams. 10 floating data cards with neon glow around the AI head. Footer: 'KANTAR // 2026' in futuristic font." \
+  --aspect-ratio 1:1 --size 4K --output output/infographic-cyberpunk.png
+```
+
+## Tips
+
+1. **Standard**: Best for known formats (quote cards, thumbnails, product shots)
+2. **Creative**: Best for unique visuals, brand differentiation, social media impact
+3. **Combine**: Use Standard to explore, Creative for final polish
+4. **Batch**: Generate multiple variations with `--num-images 4`