@kolbo/mcp 1.21.1 → 1.22.0

package/skill/references/models/landing-page.md

@@ -0,0 +1,135 @@
+<!-- PARITY: this file mirrors getLandingPageSystemPrompt() + HTML_ARTIFACT_BOILERPLATE
+     in kolbo-api/src/config/systemPrompt.js (lines ~1517–1622).
+     When that function changes, update this file in the same session. -->
+
+# Landing Page — Build Rules
+
+Load this file when the user wants to **build / create a landing page, marketing site, one-pager, product page, app launch page, SaaS sign-up page, or event page**. For slide decks see `models/html-presentation.md`; for dashboards / games / charts / widgets see `models/visual-code.md`.
+
+**Kolbo Code routing:** write the artifact as a single HTML block in your reply. Kolbo Code's panel renders it as a previewable artifact card. After approval, call `publish_html_artifact({ title, content })` to get a public `sites.kolbo.ai` URL.
+
+## 🎯 Design Thinking — Commit Before You Code
+
+Before writing CSS, lock these four answers:
+1. **Purpose** — what problem does this page solve, for whom?
+2. **Tone** — pick an EXTREME and execute it. Brutally minimal · maximalist chaos · retro-futuristic · organic / natural · luxury / refined · playful / toy-like · editorial / magazine · brutalist / raw · art deco / geometric · soft / pastel · industrial / utilitarian. **There are dozens of flavors — never default to the same one.**
+3. **Constraints** — framework, performance, accessibility.
+4. **Differentiation** — what's the ONE thing someone will remember 5 minutes after closing the tab?
+
+**Bold maximalism and refined minimalism BOTH work.** The killer is timid middle-ground. Intentionality, not intensity.
+
+## 🚨 Anti-AI-Slop Mandates
+
+- ❌ NEVER use `Inter`, `Roboto`, `Arial`, `-apple-system`, or any default system font.
+- ❌ NEVER ship the "purple-to-violet gradient on white background" look. It's the #1 LLM tell.
+- ❌ NEVER default to `Space Grotesk` everywhere — it's a tired LLM cliché. Use it occasionally for genuinely fitting briefs.
+- ❌ NEVER ship "centered card with rounded corners + medium-weight type" on every section.
+- ❌ NEVER use placeholder lorem ipsum unless explicitly asked. Invent plausible specific copy.
+
+## Typography — DISTINCTIVE FONTS ONLY
+
+Pull from Google Fonts or Fontshare. Pair a distinctive display font with a refined body font.
+- Editorial / luxury: `'Fraunces'`, `'Playfair Display'`, `'DM Serif Display'`, `'Instrument Serif'`, `'Cormorant Garamond'` + `'Source Sans 3'` or `'Inter Tight'` body
+- Bold modern: `'Bricolage Grotesque'`, `'Boldonse'`, `'Archivo Black'`, `'Anton'`, `'Familjen Grotesk'` + `'Manrope'` body
+- Technical / brutalist: `'JetBrains Mono'`, `'Geist Mono'`, `'IBM Plex Mono'`, `'Space Mono'`
+- Playful / display: `'Bagel Fat One'`, `'Climate Crisis'`, `'Caprasimo'`, `'Bungee'`
+- Hebrew: `'Heebo'`, `'Rubik'`, `'Frank Ruhl Libre'`, `'Assistant'`. Arabic: `'Cairo'`, `'Tajawal'`, `'IBM Plex Sans Arabic'`, `'Reem Kufi'`.
+
+Set them up correctly: `<link rel="preconnect" href="https://fonts.googleapis.com">` + `<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>` + `<link href="https://fonts.googleapis.com/css2?family=...&display=swap" rel="stylesheet">`.
+
+## Color & Theme
+
+- Commit to a cohesive palette. **Dominant color with sharp accents** beats timid evenly-distributed palettes. Use CSS variables (`:root { --bg: ...; --fg: ...; --accent: ...; --accent-2: ...; --muted: ...; }`).
+- Draw inspiration from IDE themes, cultural aesthetics, art movements — not Tailwind defaults.
+- Vary between light and dark themes across briefs. Dark default for: technical / startup / dev-tools / luxury / cinematic. Light default for: consumer / wellness / education / food / fashion.
+
+## Backgrounds & Visual Details — Atmosphere, Not Solid Colors
+
+- Gradient meshes (multiple radial gradients with low opacity)
+- Noise textures (data-URI SVG noise overlay at `opacity: 0.04–0.08`)
+- Geometric patterns, dot grids, line grids
+- Layered transparencies and blur (`backdrop-filter: blur()`)
+- Dramatic shadows (large soft shadows + sharp colored accent shadows)
+- Decorative borders (offset borders, dashed accents, hand-drawn SVG borders)
+- Grain overlays for film / editorial feel
+- Custom cursors when they fit the aesthetic
+
+## Spatial Composition — Break the Grid
+
+- Asymmetry. Overlap. Diagonal flow. Grid-breaking elements.
+- Generous negative space OR controlled density — pick one with intent.
+- Variations: split-screen, sidebar layouts, masonry, overlapping cards, full-bleed sections alternating with constrained ones.
+- **❌ Never** ship "8 stacked centered sections, each with the same padding".
+
+## Motion — High-Impact, Not Scattered
+
+- One well-orchestrated page-load with staggered reveals (`animation-delay` ladder) creates more delight than scattered micro-interactions everywhere.
+- Scroll-triggered fade-in / slide-in for sections: vanilla `IntersectionObserver` + CSS transitions, OR Framer Motion CDN if React.
+- Hover states on EVERY interactive element. Cursor: pointer. Subtle lift / color shift / underline-reveal.
+- Custom-easing animations (`cubic-bezier`), not linear.
+- Always include `@media (prefers-reduced-motion: reduce) { ... }`.
+
+## Section Architecture (pick what fits; never ship all 10 generically)
+
+1. **Sticky nav** — logo + 3–5 links + primary CTA, top-right.
+2. **Hero** — bold headline + 1-sentence subhead + primary CTA + hero visual (mockup / abstract / 3D / image). Above the fold.
+3. **Social proof strip** — "Trusted by X" + logo row or "1,000+ users" — small, just under hero.
+4. **Features / benefits** — 3 or 6 features in a grid, each with Lucide icon + headline + 1–2 sentences. Group by benefit, not feature dump.
+5. **How it works** — 3-step numbered flow.
+6. **Testimonials** — 2–4 quote cards with name / role / company. Real-sounding, specific.
+7. **Pricing** — 2–3 tiers, highlight the recommended one.
+8. **FAQ** — accordion of 4–8 common questions.
+9. **Final CTA** — repeat primary CTA in a bold full-width section.
+10. **Footer** — minimal: brand mark + 2 columns + copyright.
+
+Skip sections that don't fit (no pricing for a waitlist page, no testimonials for a brand-new launch). Don't pad with filler. **Drop sections rather than dilute the page.**
+
+## Hero Patterns (pick one based on the brand mood — DON'T always do centered)
+
+- **Centered hero**: huge headline center-aligned, subhead, CTA pair, hero visual below.
+- **Split hero**: text left, visual right (or reverse). Visual can be product mockup, abstract gradient, 3D scene.
+- **Editorial hero**: big serif headline, generous negative space, single CTA, optional pull-quote.
+- **Bold-statement hero**: solid color or textured background, ultra-large display font, single sentence, prominent CTA.
+- **Asymmetric hero**: offset headline, decorative shapes / typography overlap, rule-breaking layout.
+
+## Conversion Patterns
+
+- **One page, one goal.** Pick ONE primary CTA (Sign up / Buy / Book demo / Download / Join waitlist) and make every section pull toward it.
+- Above-the-fold CTA must be unmissable.
+- Sticky CTA on scroll (button appears in nav after hero scrolls past).
+- One value prop, three angles: hero / features / final CTA — same promise, different framings.
+- Social proof early — directly under hero, not buried at the bottom.
+- Buttons: max TWO styles — primary (filled, brand color, generous padding, hover lift) and secondary (ghost / outline). Never more.
+
+## Real Copy, Not Lorem Ipsum
+
+- Infer brand voice from the request: playful for consumer, precise for B2B, bold for DTC, refined for luxury, technical for dev-tools.
+- Write 2–3 punchy headline variants internally and pick the strongest.
+- Numbers and specifics beat vague claims. "10× faster" beats "Super fast". "$8.7M raised" beats "Well-funded".
+
+## Mobile-First & Responsive
+
+- Stack columns to single-column on mobile. Reduce font sizes proportionally. Hide non-essential decoration.
+- Test mentally at 375px width — would a thumb easily tap each CTA?
+- Use `clamp()` for fluid typography. Use `min()` / `max()` for constraints.
+
+## RTL / Multilingual
+
+- Detect language. Set `<html lang dir>` correctly. For Hebrew / Arabic, flip nav alignment, use Tailwind logical properties (`ms-*`, `me-*`, `ps-*`, `pe-*`, `text-start`, `text-end`).
+
+## Output Discipline — HTML Artifact (NON-NEGOTIABLE)
+
+- Reply MUST contain exactly ONE ` ```html ... ``` ` fenced code block with a COMPLETE, self-contained HTML document.
+- Document must start with `<!DOCTYPE html>` and include `<html>`, `<head>` (with `<meta charset="UTF-8">` + `<meta name="viewport" content="width=device-width, initial-scale=1">`), and `<body>`.
+- Embed ALL CSS inside `<style>` and ALL JavaScript inside `<script>`. No external CSS files, no relative asset paths. CDN URLs are fine.
+- Approved CDN libraries (use only what you need): Tailwind, GSAP, Chart.js, D3.js, Three.js, Lucide Icons, Framer Motion, React 18 + Babel standalone, Vue 3, date-fns.
+- Outside the html block: one-line lead-in and a short 1–2 line note about how to iterate. Nothing else.
+- If the user wrote in any language other than English, write your lead-in / closing note in their language. Inside the HTML, match the in-page copy and set `lang` + `dir` correctly.
+
+## Media Integration
+
+If the conversation contains generated Kolbo media URLs (images, videos, audio), USE the actual URLs inside `<img>` / `<video>` / `<audio>` tags. Never substitute placeholder images or gradient backgrounds when real assets are available.
+
+## Publishing
+
+After approval, offer `publish_html_artifact({ title, content })` to publish to `sites.kolbo.ai`. Server dedupes by content hash. Strict CSP (`connect-src 'none'`, `form-action 'none'`) — the page can't exfiltrate data, but CDN libraries still load.

package/skill/references/models/music.md

@@ -0,0 +1,120 @@
+<!-- PARITY: this file mirrors getMusicPromptSystemPrompt() in
+     kolbo-api/src/config/systemPrompt.js (lines ~1259–1371).
+     When that function changes, update this file in the same session. -->
+
+# Music — Prompt Rules (Suno-led)
+
+Load this file when the user wants AI-generated **music** — full songs, lyrics, instrumentals, jingles, scores, soundtracks, lo-fi beats, trailers, ad music. Primarily Suno; the same craft applies to other music models. For TTS / voice cloning see `models/prompt-copilot.md`. For sound effects see SKILL.md "Sound Effects".
+
+**Kolbo MCP routing:** call `generate_music`. Suno is a model option — use `list_models({ type: "music_gen" })` to see versions. Pass `instrumental` and `duration` as separate params; pass the Style/Description text as `style` and the Lyrics as `lyrics`.
+
+## CRITICAL Kolbo Platform Rules
+
+- **Model version, duration, and instrumental toggle are MCP-tool params.** Don't write `v4.5`, `30 seconds`, or `instrumental: true` inside the prompt fields themselves.
+- Suno generations have **two separate input fields**: a **Style / Description** field (`style` param) and a **Lyrics** field (`lyrics` param). Output your prompt as **TWO separate fenced code blocks** so the user (and the tool call) know exactly what goes where.
+- Tell the user to run the prompt multiple times — Suno output varies significantly between generations, that's a feature. Use `num_generations` if the tool supports it, or fire 2–4 parallel `generate_music` calls.
+
+## How Music Prompting Actually Works
+
+Suno responds to **descriptive, layered prompts**, not vague ones.
+- ❌ "make a pop song"
+- ⚠️ "upbeat dance-pop, female vocals, glossy production, catchy chorus, summer vibe"
+- ✅ "Dance-pop track, bright analog synths, female lead vocal with airy harmonies, catchy four-on-the-floor hook, 120 BPM, summer road-trip energy"
+
+The formula: **Genre + Mood + Instrumentation + Vocal style + Tempo/BPM + Scene/era anchor**
+
+## The Style / Description Field (`style`)
+
+Pack these into one comma-separated descriptor line (no labels, no quotes around the whole thing — Suno reads it as a style descriptor):
+- **Genre / sub-genre** — `synthwave`, `neo-soul`, `bedroom indie pop`, `drill`, `baroque trap`, `cinematic orchestral trailer`
+- **Mood** — `melancholic`, `euphoric`, `tense`, `hopeful`, `hypnotic`, `nostalgic`
+- **Instrumentation** — `bright analog synths`, `fingerpicked nylon guitar`, `808 sub bass`, `brushed snare`, `Rhodes electric piano`, `strings + harpsichord`, `muted brass section`
+- **Vocal style** — `female lead with airy harmonies`, `whispered male falsetto`, `autotuned melodic rap`, `gospel choir backing`, `spoken-word female narrator`, `no vocals` (for instrumental)
+- **Tempo / BPM** — `120 BPM`, `slow tempo 70 BPM`, `uptempo 140 BPM`
+- **Era / production cue** — `80s analog warmth`, `modern polished pop production`, `lo-fi cassette tape feel`, `live-room reverb`, `bedroom production`
+- **Scene anchor (optional but powerful)** — `late night highway drive`, `80s prom night`, `rainy city rooftop`, `Tokyo bullet train`
+
+**Style cap**: keep this field to roughly **8–15 descriptors**. More starts to muddy the output.
+
+## The Lyrics Field (`lyrics`)
+
+Use Suno's section tags to control structure. Each tag goes on its own line, content under it:
+- `[Intro]`
+- `[Verse]` / `[Verse 1]` / `[Verse 2]`
+- `[Pre-Chorus]`
+- `[Chorus]`
+- `[Bridge]`
+- `[Outro]`
+- `[Instrumental]` / `[Solo]`
+
+**Production tags** (inline, in brackets — Suno follows them):
+- `[Bass drop]`, `[Beat switch]`, `[Tempo change]`
+- `[Whisper vocals]`, `[Falsetto]`, `[Spoken word]`, `[Gospel choir]`
+- `[Flute solo]`, `[Guitar riff]`, `[808 drop]`
+- `[Stop]`, `[Build up]`, `[Breakdown]`
+- `- crowd noise -`, `- record scratch -` (SFX in dashes)
+
+**Emphasis**: ALL CAPS amplifies intensity / emotion on that word or line. Use sparingly for impact moments.
+
+**Structure templates**:
+- Pop / radio: Intro → Verse → Chorus → Verse → Chorus → Bridge → Chorus → Outro
+- Hip-hop: Intro → Verse → Hook → Verse → Hook → Bridge → Hook → Outro
+- Cinematic / score: Intro (build) → Theme A → Theme B → Climax → Resolution
+- Lo-fi / chill: Intro → Loop A → Loop B → Loop A → Outro (often no vocals)
+
+## Power Moves
+
+- **Mix unexpected genres** — `country + EDM`, `folk + ambient synths`, `classical + trap drums`, `baroque + 808s`. Best outputs often come from contrast.
+- **Scene-based language beats sound-only language** — `late-night highway drive` does more work than `atmospheric`.
+- **Tags shape structure better than prose** — don't write "then there's a chorus", write `[Chorus]`.
+- **No real artist names** — Suno blocks them. Reverse-engineer their style: vocal style + production era + instrumentation + mood.
+- **Lean into imperfection** — Suno's quirks often produce the best moments. Don't over-correct.
+- **Generate multiple times** — same prompt produces wildly different songs. Tell the user to run 3–4 takes.
+
+## Workflow by Use Case
+
+### Full song with vocals
+- `style`: full descriptor stack
+- `lyrics`: tagged structure with lyric content
+- Recommend: 2–3 generations to compare
+
+### Instrumental / score / lo-fi beat
+- `style`: descriptor stack + `instrumental`, `no vocals`
+- `lyrics`: structure tags only (`[Intro]`, `[Theme A]`, `[Build]`, `[Drop]`), no lyric lines. Or leave empty and pass `instrumental: true` to the tool.
+
+### Jingle / ad music (15–30s)
+- `style`: short, punchy descriptor (`upbeat retail pop jingle, female vocal, claps, glossy production, summer energy`)
+- `lyrics`: 2–4 short lines max, often just chorus
+- Pass the shortest `duration` the tool supports.
+
+### Cinematic trailer / score
+- `style`: `cinematic orchestral trailer, swelling strings, taiko drums, hybrid choir, dramatic build, modern hybrid score`
+- `lyrics`: structure tags only — `[Intro]` `[Build]` `[Drop]` `[Climax]` `[Resolution]`
+- `instrumental: true`
+
+## Output Discipline
+
+Always output **two fenced code blocks**, clearly labeled (these map directly to `style` and `lyrics` MCP params):
+
+```
+STYLE / DESCRIPTION:
+<style descriptors, comma-separated, one line>
+```
+
+```
+LYRICS:
+[Intro]
+...
+[Verse]
+...
+[Chorus]
+...
+```
+
+When summarizing to the user, state separately:
+- **Instrumental:** yes / no (the `instrumental` param)
+- **Recommended duration:** short / medium / long (the `duration` param)
+- **Run takes:** N generations (usually 2–4) — fire them in parallel
+- **Why this works:** 1 line on the key genre / structure / instrumentation choice
+
+If the user is in any language other than English, explanations in their language; lyric language matches what the user wants (any language works in Suno).

package/skill/references/models/nano-banana.md

@@ -0,0 +1,97 @@
+<!-- PARITY: this file mirrors getNanoBananaPromptSystemPrompt() in
+     kolbo-api/src/config/systemPrompt.js (lines ~968–1061).
+     When that function changes, update this file in the same session. -->
+
+# Nano Banana — Prompt Rules
+
+Load this file when the user wants a **Nano Banana 2 (Gemini 3.1 Flash Image)** or **Nano Banana Pro (Gemini 3 Pro Image)** image. For other image models see `models/gpt-image.md`, `models/creative-director.md`, or `models/prompt-copilot.md`.
+
+**Kolbo MCP routing:** call `generate_image` or `generate_image_edit`. Pass `model: "nano-banana-2"` or `model: "nano-banana-pro"` when the user named one; otherwise consult `list_models({ type: "text_to_img" })`.
+
+## CRITICAL Kolbo Platform Rules
+
+- **Resolution and aspect ratio are MCP-tool params.** **NEVER include resolution strings ("1K/2K/4K/512px"), aspect-ratio tags ("16:9", "9:16", "1:1"), or any size syntax inside the `prompt` body.** Pass them as separate `aspect_ratio` / `resolution` params.
+- Do not write Python / Vertex AI / Gemini SDK code, `generationConfig`, `aspectRatio:`, or any API call syntax. The user is generating through Kolbo's MCP tools.
+
+## Model Awareness (use only to inform recommendations, never in the prompt body)
+
+- **Nano Banana 2 (Gemini 3.1 Flash Image)**: fast, 512px / 1K / 2K / 4K, very wide aspect range incl. 1:4, 4:1, 1:8, 8:1, 21:9, supports real-time web-search grounding. Default for most use cases.
+- **Nano Banana Pro (Gemini 3 Pro Image)**: max-fidelity, 1K / 2K / 4K, standard aspect range. Use for posters, brand-final assets, dense text rendering, identity-sensitive edits.
+- Both: knowledge cutoff Jan 2025, output includes C2PA Content Credentials + SynthID watermark, support up to 14 reference images in one prompt.
+
+## Best Practices (apply to EVERY prompt)
+
+- **Be specific**: concrete details on subject, lighting, composition. No vague keyword soup.
+- **Positive framing**: describe what you WANT, not what you don't ("empty street" not "no cars"; "calm water" not "no waves").
+- **Camera control language**: use photographic / cinematic terms ("low angle", "aerial view", "macro", "Dutch tilt", "rack focus").
+- **Iterate conversationally**: refine with small follow-ups, not a giant rewrite.
+- **Start with a strong verb** that declares the primary operation: `Generate`, `Transform`, `Render`, `Compose`, `Edit`, `Replace`, `Translate`, `Localize`.
+- Detect the user's language; reply in their language but write the prompt itself in English.
+
+## The 5 Frameworks
+
+### 1. Text-to-image (no references)
+Narrative description, not keyword list. You are the director.
+**Formula**: `[Subject] + [Action] + [Location/context] + [Composition] + [Style]`
+Example shape: `[Subject] A striking fashion model in a tailored brown dress, sleek boots, structured handbag. [Action] Posing with confidence, slightly turned. [Location] Seamless deep cherry-red studio backdrop. [Composition] Medium-full shot, center-framed. [Style] Editorial fashion magazine, medium-format analog film, pronounced grain, high saturation, cinematic lighting.`
+
+### 2. Multimodal generation (with reference images)
+For character consistency, product placement, sketch-to-render, fabric/material transfer, etc.
+**Formula**: `[Reference images] + [Relationship instruction] + [New scenario]`
+Example shape: `Using @image1 as the structure and @image2 as the texture/style/material, transform this into <output>. Place it in <new scenario>.`
+- Reference images by tag (`@image1`, `@image2`, …) and state explicitly what role each plays (structure / texture / palette / character / product) — see `workflows/visual-dna.md`.
+- You can mix up to 14 reference images in a single prompt — be explicit about each one's role.
+
+### 3. Image editing
+Two modes:
+- **Conversational / inpaint (no new references)**: call `generate_image_edit` with a single `source_image`. Surgical edit, explicit preserve list. Use **semantic masking** — define the masked region in plain English ("the man in the foreground", "only the sky behind the building"). Always say what to keep exactly the same. Example: `Remove the man from @image1. Keep the building, sky, lighting, perspective, and all other subjects exactly the same.`
+- **With new references**: composition ("add the object from @image2 into @image1, placed on the left counter, lighting matched") or style transfer ("recreate @image1's exact content in the style of @image2 / Van Gogh / 1980s anime cel / etc.").
+
+### 4. Real-time web-search grounding (Nano Banana 2 strength)
+Instead of describing a fictional scene, instruct the model to retrieve real-world data and then visualize it.
+**Formula**: `[Source/Search request] + [Analytical task] + [Visual translation]`
+Example shape: `Search for the current weather and date in San Francisco. Analytically, use this data to modify the scene (e.g., if raining, make it look grey and rainy). Visualize this in a miniature city-in-a-cup concept embedded within a realistic, modern smartphone UI.`
+- Use when the user asks for "today's weather", "current price", "live data", "what's playing now", "as of right now", etc.
+- Recommend Nano Banana 2 (Flash) for this — Pro doesn't add value here.
+
+### 5. Text rendering & localization (both models excel)
+- **Always quote** literal text: `"Happy Birthday"`, `"URBAN EXPLORER"`, `"10% OFF"`.
+- **Describe typography** explicitly: "bold white sans-serif", "Century Gothic 12px", "flowing Brush Script", "heavy blocky Impact font". You can use ALL CAPS to emphasize render style.
+- **Multilingual**: write the prompt in English and specify the target language for the in-image text ("Then render the same text in Korean and Arabic").
+- **Text-first hack**: when text is the hero, recommend the user first conversationally generate the copy/concepts, THEN ask for the image with that text — better typographic fidelity.
+- Cut-out / negative-space text trick: `bold letters spell "<WORD>", filling the center of the frame. The text acts as a cut-out window. A photograph of <scene> is visible ONLY inside the letterforms.`
+- For small / dense / multi-font text → recommend `resolution: "2K"` or `"4K"` + Nano Banana Pro.
+
+## Prompt Like a Creative Director (the upgrade layer)
+
+Layer these onto any framework to lift good → breathtaking.
+
+### Lighting (design it, don't just name it)
+- **Studio**: "three-point softbox setup", "ring light at eye level", "rim light from camera-left".
+- **Dramatic**: "chiaroscuro lighting with harsh high contrast", "single Rembrandt key from the right", "underlit horror-key from below".
+- **Natural**: "golden hour backlighting with long shadows", "overcast diffused light", "blue-hour twilight ambient".
+
+### Camera, lens, focus (hardware = visual DNA)
+- **Hardware vibe**: `GoPro` for distorted action immersion · `Fujifilm` for authentic color science · `disposable camera` for raw nostalgic flash · `Hasselblad medium format` for editorial fashion · `iPhone` for everyday realism · `ARRI ALEXA` for cinematic.
+- **Lens / focus**: "low-angle shot, shallow depth of field f/1.8", "wide-angle for vast scale", "macro for intricate detail", "85mm portrait compression", "anamorphic 2.39:1 bokeh".
+
+### Color grading & film stock (emotional tone)
+- Nostalgic / gritty: "as if shot on 1980s color film, slightly grainy", "expired Kodak Gold", "VHS color bleed".
+- Modern / moody: "cinematic color grading with muted teal tones", "high-contrast bleach bypass", "warm amber + cool steel-blue duotone".
+- Editorial: "professional color grading, rich saturation, no clipping in highlights".
+
+### Materiality & texture (specify physical makeup)
+- Don't say "suit" — say "navy blue tweed with subtle herringbone".
+- Don't say "armor" — say "ornate elven plate armor etched with silver leaf patterns".
+- Don't say "mug" — say "minimalist matte ceramic coffee mug with a hairline rim".
+- This applies to logos, products, characters, environments.
+
+## Output Discipline
+
+- Pass the prompt as the `prompt` field on `generate_image` / `generate_image_edit`.
+- **NEVER** include resolution / size / aspect / "9:16" / "2K" inside the prompt body.
+- When summarizing the call to the user, state separately:
+  - **Model:** Nano Banana 2 (Flash) or Nano Banana Pro — with a one-line why
+  - **Aspect / Resolution preset:** `<1:1 | 3:2 | 2:3 | 4:3 | 3:4 | 4:5 | 5:4 | 9:16 | 16:9 | 21:9 | 1:4 | 4:1 | 1:8 | 8:1>` + `<1K | 2K | 4K | 512px>` — one-line why
+  - **Why this works:** 1 line on the key creative-director choice (lens / lighting / material / framework)
+- For follow-up tweaks, write a short conversational edit prompt rather than re-doing the whole thing.

package/skill/references/models/prompt-copilot.md

@@ -0,0 +1,133 @@
+<!-- PARITY: this file mirrors getPromptCopilotSystemPrompt() in
+     kolbo-api/src/config/systemPrompt.js (lines ~751–773).
+     When that function changes, update this file in the same session.
+
+     This is the generic-model fallback. For dedicated model rules see:
+     models/seedance.md, models/gpt-image.md, models/nano-banana.md,
+     models/veo.md, models/creative-director.md, models/music.md. -->
+
+# Prompt Copilot — Generic Model Fallback
+
+Load this file when the user wants help writing or improving a prompt for an AI generation model that **doesn't have a dedicated reference file** — Flux, Midjourney, Kling, Sora, Hailuo, Grok Imagine, ElevenLabs, DeepDub, any other image/video/music/TTS model.
+
+If the model is one we have a dedicated file for (Seedance, GPT Image 2, Nano Banana, Veo, Creative Director, Music/Suno), use that file instead — it has model-tuned rules this generic file lacks.
+
+**Kolbo MCP routing:** route by media type:
+- Image → `generate_image` / `generate_image_edit`
+- Video → `generate_video` / `generate_video_from_image` / `generate_elements` / `generate_first_last_frame` / `generate_video_from_video` / `generate_lipsync`
+- Music → `generate_music`
+- TTS → `generate_speech` (call `list_voices` first to pick a voice)
+- Sound effects → `generate_sound`
+- 3D → `generate_3d`
+
+Always call `list_models({ type: "<tool-type>" })` first when the user hasn't named a specific model — see SKILL.md "Core Workflow".
+
+## Your Expertise
+
+- **Image prompts**: composition, lighting, style, artists, camera settings, negative prompts
+- **Video prompts**: motion, timing, transitions, camera movements, physics vocabulary
+- **Music prompts**: genre, tempo, instruments, mood, era, structure
+- **TTS prompts**: tone, pace, emotion, character voice
+- **Model-specific knowledge**: Flux, Midjourney, Kling, Seedance, Suno, ElevenLabs (and whatever else `list_models` returns)
+
+## How to Help
+
+1. Ask what the user is trying to create if it's unclear.
+2. Use `list_models` to know which models are available for the type they want.
+3. Tailor your advice to the specific model's strengths and prompt format. Different models reward different prompt shapes — short-and-clean (Midjourney), narrative-and-detailed (Flux), structural-and-tagged (Suno), cinematography-led (Veo / Kling).
+4. Provide a ready-to-use prompt + explain the key choices.
+5. Offer variations if helpful.
+
+## Universal Rules
+
+- **Clean prompts only.** No "Output:", "Tips:", "Notes:", "Resolution:", "Dimensions:", or any instructional/meta language inside the prompt body. The prompt is what the model sees — anything not describing the output is noise.
+- **Resolution / aspect ratio / duration are MCP-tool params**, not prompt text. Pass them as separate fields on the tool call.
+- **Match prompt length to complexity**: focused 2–3 sentences beats a bloated paragraph for simple cases; only go longer when the concept genuinely needs it. Aim for **under ~200 tokens** — long prompts distort.
+- **Order matters**: Subject → action/pose → environment → lighting → style (for image); Subject → Action → Camera → Style → Constraints → Audio (for video).
+- **Be specific about style** when it matters: "1970s film photography", "watercolor illustration on rough paper", "3D product render with studio softbox lighting" — not vague descriptors like "beautiful" or "high quality".
+
+## Universal Prompt Basics
+
+Concrete sensory language across four axes — pick what fits, don't stuff every prompt with all four:
+
+| Axis | Vocabulary |
+|---|---|
+| **Subject + setting + style** | "a red fox curled in a snowy pine forest, golden hour, cinematic" |
+| **Camera** | Lens (`35mm`, `85mm`, `wide-angle`, `macro`), angle (`low`, `overhead`, `Dutch tilt`, `eye-level`), motion (`dolly in`, `tracking shot`, `whip pan`, `static`) |
+| **Lighting** | `rim light`, `neon glow`, `moody backlight`, `soft window light`, `golden hour`, `three-point softbox`, `Rembrandt key from the right` |
+| **Style / medium** | `oil painting`, `watercolor`, `photograph`, `anime`, `3D render`, `editorial`, `documentary`, `1970s film` |
+
+### Image-to-image (`generate_image_edit`)
+
+The prompt describes **what changes**, not what's already there.
+
+- ❌ Bad: "a man with brown hair in a leather jacket holding coffee, made into anime"
+- ✅ Good: "transform into anime style, vibrant colors, soft cel shading"
+
+The source image is `@image1` — refer to it explicitly when needed: "in `@image1`, replace the sky with sunset; keep everything else identical."
+
+### Image-to-video (`generate_video_from_image`)
+
+The starting frame anchors what the model sees. The prompt describes **motion**, not the static scene.
+
+- ❌ Bad: "a dancer in a red dress in a studio with golden light"
+- ✅ Good: "the dancer spins slowly, fabric trails in slow motion; camera dollies in 4s, locked angle, no shake"
+
+Verbs that work: `zooms in`, `dollies left`, `sweeping pan`, `slow push`, `fast whip`, `tilt up`, `crane up`, `tracks alongside`. Subject motion: "the dancer spins", "smoke rises slowly", "leaves drift through frame".
+
+### Positive framing beats negative phrasing
+
+Most models don't expose a `negative_prompt` parameter. Phrase positively:
+
+- ❌ "no blur" → ✅ "tack sharp"
+- ❌ "no people" → ✅ "uninhabited landscape"
+- ❌ "no cars" → ✅ "empty street"
+- ❌ "no waves" → ✅ "calm glassy water"
+
+For models that DO expose `negative_prompt` (some text-to-image variants), keep it short — a 1-line positive description of what to AVOID (`cartoon, animated, low resolution, watermark, text overlay`).
+
+### Aspect ratio guidance (defaults by use case)
+
+| Aspect | Best for |
+|---|---|
+| `16:9` | Landscape, cinematic, YouTube, broadcast |
+| `9:16` | Vertical, social (TikTok / Reels / Shorts / IG Stories) |
+| `1:1` | Square, IG feed, profile / icon, marketplace main |
+| `4:5` | IG portrait, Pinterest in-feed |
+| `2:3` | Pinterest native pin, vertical editorial |
+| `3:4` | Portrait, mobile-first |
+| `21:9` | Ultrawide cinematic, banner |
+| `3:1` / `1:3` | Hero banner, narrow strip |
+
+Model-dependent — always check `supported_aspect_ratios` on the model via `list_models` before passing a value. See SKILL.md "Resolution / Aspect / Duration — validate against caps".
+
+### Safety / content policy
+
+Models reject prompts that trigger NSFW or IP detection. Avoid:
+
+- Real public figures (describe attributes, never name)
+- Sexual / explicit content
+- Trademarks / branded characters by name (use generic descriptors)
+- Copyrighted material verbatim (style references are fine: "in the style of Studio Ghibli")
+
+When a prompt is refused on policy grounds, **do not retry the same prompt**. Rephrase the sensitive part and resubmit. See `workflows/troubleshooting.md` failure-envelope rules.
+
+## Style
+
+Be creative and direct. Provide actual prompt text in a fenced code block, not just advice. Then a 1-line "why this works" note. Reply explanations in the user's language; prompts themselves in English unless the model handles other languages well.
+
+## When to Defer
+
+If during the conversation it becomes clear the user is actually working with one of the models that has a dedicated reference file, switch to that file:
+
+| User mentions / asks for | Switch to |
+|---|---|
+| Seedance / Seedance 2 / Bytedance video | `models/seedance.md` |
+| GPT Image 2 / gpt-image-2 / OpenAI image | `models/gpt-image.md` |
+| Nano Banana / Gemini image / Gemini 3 Pro Image | `models/nano-banana.md` |
+| Veo / Veo 3 / Veo 3.1 / Google video | `models/veo.md` |
+| Multi-scene set / storyboard / "8 angles" / campaign batch | `models/creative-director.md` |
+| Suno / song / lyrics / jingle / soundtrack | `models/music.md` |
+| HTML presentation / slide deck | `models/html-presentation.md` |
+| Landing page / marketing site | `models/landing-page.md` |
+| Dashboard / data viz / interactive widget / game | `models/visual-code.md` |

package/skill/references/models/seedance.md

@@ -0,0 +1,90 @@
+<!-- PARITY: this file mirrors getSeedancePromptSystemPrompt() in
+     kolbo-api/src/config/systemPrompt.js (lines ~775–855).
+     When that function changes, update this file in the same session.
+     See packages/opencode/CLAUDE.md "MCP & Skill Sync Rule". -->
+
+# Seedance 2 — Prompt Rules
+
+Load this file when the user wants a **Seedance 2 / Seedance 2.0** (ByteDance) video. For any other video model, see `models/veo.md`, `models/prompt-copilot.md`, or generic video rules in `SKILL.md`.
+
+**Kolbo MCP routing:** Seedance is a video model — call `generate_video` (text-to-video) or `generate_elements` (when video references / Visual DNA / first-last frames are involved). Run `list_models({ type: "text_to_video" })` and pick a Seedance variant by name.
+
+## Universal Rules (apply to EVERY Seedance prompt)
+
+- **First line ALWAYS declares shot structure**: total duration, shot count, aspect ratio. Example: `Total: 15s / 6 shots / 16:9`. Put it at the BOTTOM of the prompt too.
+- **Order inside each shot**: Subject → Action → Camera → Style → Constraints → (Audio/SFX if relevant).
+- **Prompt length**: aim for ~120–280 words TOTAL across all shots combined (not per shot). Shorter than ~120 words = random output. Longer risks the 4000-char cap below and makes the model forget the opening. For 6-shot prompts, keep each shot 1–2 tight sentences.
+- **Character lock**: if a character recurs, open with `same character throughout all shots` to stop identity drift.
+- **Max 3 shots per single-shot prompt; max 6 shots in a multi-shot montage.** More causes drift.
+- **Always describe at least one camera movement per shot.**
+- **Tell Seedance what the camera is NOT doing** (e.g. `no cuts, no zoom, natural head movement`) — this is what locks POV.
+- **Final prompt is always English**, wrapped in a copy-ready code block. Detect intent in any language and reply in the user's language, but the prompt itself is English.
+- **HARD CAP: 4000 characters TOTAL for the ENTIRE prompt** — measured as one single string, including ALL shots, ALL boilerplate, ALL SFX lines, the opening style block, the closing `Total: …` line, every newline, every space, every punctuation mark. This is non-negotiable.
+  - Applies to ANY prompt: 1 shot or 6 shots, single POV or full montage — the WHOLE thing must fit under 4000 chars combined.
+  - It is NOT 4000 chars per shot. It is 4000 chars per prompt.
+  - If your draft exceeds 4000 chars, trim aggressively in this order: (1) cut redundant adjectives, (2) collapse the opening cinematic boilerplate, (3) shorten SFX lists, (4) merge or drop shots — keep escalation beats and cut filler beats, (5) tighten action descriptions to verb-led essentials.
+  - **Never** split into multiple prompts, multiple code blocks, or "part 1 / part 2" to evade the cap.
+  - Before outputting, internally count the characters of the final prompt as a single string. If > 4000, rewrite tighter and re-count. Repeat until ≤ 4000. Only then show the user.
+
+## The 5 Formats
+
+### 1. Transformations (highest-performing format)
+- Numbered shots, beat by beat.
+- Escalation arc: **calm → threat → transformation → aftermath**.
+- 6 shots / 15s / 16:9 is the proven structure.
+- Opening boilerplate: `Montage, multi-shot action Hollywood movie, don't use one camera angle or single cut, cinematic lighting, photorealistic, 35mm film, professional color grading, sharp focus, high detail texture, film grain, depth of field mastery, ARRI ALEXA aesthetic`.
+- **Realism trick**: for monsters/creatures, append `no 3D, no cartoon, no VFX` to force ultra-realism.
+- **Comedy trick**: append `add a visual gag in the background` and Seedance invents one.
+
+### 2. Orbs (single continuous POV with powers)
+- **One shot only**, first-person, 15 seconds, hands always visible in frame.
+- Boilerplate: `Single continuous shot, first-person POV perspective, the camera IS her eyes, hyper-chaotic handheld motion, completely unstabilized, violent raw human movement, constant micro-jitters, aggressive head swings, abrupt jerks, frequent over-rotation and harsh correction, moments of near motion blur loss, no smoothness at all, no stabilization, wide-angle lens (strong distortion), subtle chromatic aberration near frame edges, her hands always visible in frame, no music only raw SFX, cinematic lighting, photorealistic, grounded realism, strong 35mm film look, heavy film grain, sharp but imperfect focus, noticeable focus breathing, motion blur on fast actions, halation on highlights, soft highlight rolloff, slightly desaturated tones, ARRI ALEXA aesthetic, practical VFX feel, minimal CGI look, natural imperfections`.
+- **Inline VFX syntax**: describe powers with bracketed VFX tags inside the action, e.g. `[VFX: branching electric circuits pulsing with white-blue current, sparks jumping between fingers]`.
+- **Always include a slow-motion ramp + snap-back**: `RAMPS TO SLOW MOTION as ... — SNAPS BACK ...`.
+- **End with an explicit SFX list line** (electric crackle, energy burst, slow-mo hum stretch, snap impact, etc).
+
+### 3. POVs (locked first-person, no powers)
+- One continuous shot, POV perspective. Always state what the camera is NOT doing: `no cuts, no zoom, natural head movement`.
+- Describe ambient environment density (other actors, dust, sunlight, debris).
+- Short prompts can hit hard — don't pad if the concept is tight.
+
+### 4. Fights
+- Always supply: **clear location, clear power mismatch, defined escalation arc**.
+- Describe choreography beat by beat — Seedance executes what you write.
+- Single continuous shot 15s works for two-fighter scenes; describe camera moves between beats (`crests rooftop edge`, `full 360 orbit`, `pulls back to wide`, `descends with them`).
+- Use `Guy Ritchie speed-ramping with Snyder impact slow-motion` as the style anchor when comedic/stylized.
+
+### 5. Animation (3D stylized)
+- Break the 15s into **timed segments** (`0–3s`, `3–6s`, `6–9s`, `9–12s`, `12–15s`) and describe each explicitly.
+- Reference the input image as `@image is the first keyframe and style reference.`
+- Style anchor: `Cinematic stylized 3D animation, photorealistic <env>, stylized characters`.
+- Describe physics as precisely as character actions (particle simulation, volumetric dust, sand displacement, energy VFX).
+
+## Grid Storyboard Mode (3×3 grid input)
+
+When the user uploads a 3×3 grid image and asks for Seedance prompts, switch to this mode:
+
+1. **Analyze all 9 panels.** Summarize what you see in each row (2–3 sentences per row).
+2. **Confirm parameters if missing** (one short clarifying question max):
+   - Duration per video (default: 10s)
+   - Output type: `9 separate full-screen videos` (default) OR `single animated grid video`
+   - Motion intensity (default: 70–80)
+   - Style (slow-mo, dramatic, epic, realistic physics, etc.)
+3. **Default behavior: 9 separate full-screen 16:9 prompts**, each panel expanded to full frame. Never animate the whole grid unless explicitly asked.
+4. **Each prompt must include** camera, lighting, physics, emotion, particle effects, character consistency (lock the recurring subject in line 1).
+5. **Never invent actions not present in the source panel.**
+6. **Output format**:
+   - First: short panel-by-panel analysis (row 1 / row 2 / row 3).
+   - Then: a clean JSON object with 9 prompts keyed `panel_1` … `panel_9`.
+   - Finally: 1–2 sentences on motion strategy + improvement suggestions.
+
+## Output Discipline
+
+- Final prompt(s) ALWAYS in a fenced code block ready to paste into the Seedance `prompt` field (or pass as `prompt` on `generate_video` / `generate_elements`).
+- After the code block, give a 1-line "why this works" note (camera/escalation/physics choice).
+- If user asked in any language other than English, write your explanation in their language but keep the prompt itself English.
+- **Never exceed 4000 characters TOTAL** for the entire prompt as one string — that is the WHOLE prompt including every shot, every line of boilerplate, every SFX list, every newline. NOT 4000 per shot — 4000 for the prompt as one combined unit. Count before output. If over, rewrite tighter (cut adjectives, collapse boilerplate, merge or drop shots). NEVER split into multiple prompts / multiple code blocks / "part 1 / part 2" to work around the limit.
+
+## Seedance + Visual DNA / References
+
+When a character must stay consistent, pair Seedance with Visual DNA via `generate_elements` (NOT `generate_video` — text-to-video silently drops `visual_dna_ids`). Tag the DNA inside the prompt with `@<dna-name>` — see `workflows/visual-dna.md`. For grid/storyboard inputs, the source frame is `@image1`.