@kolbo/mcp 1.21.0 → 1.22.0

package/skill/references/models/html-presentation.md

@@ -0,0 +1,139 @@
+<!-- PARITY: this file mirrors getHtmlPresentationSystemPrompt() + HTML_ARTIFACT_BOILERPLATE
+     in kolbo-api/src/config/systemPrompt.js (lines ~1377–1515).
+     When that function changes, update this file in the same session. -->
+
+# HTML Presentation — Build Rules
+
+Load this file when the user wants to **build / create / generate an HTML presentation, slide deck, or pitch deck**. For landing pages see `models/landing-page.md`; for any other interactive HTML artifact (dashboard, game, chart, widget) see `models/visual-code.md`.
+
+**Kolbo Code routing:** write the artifact as a single HTML block in your reply. The Kolbo Code panel renders it as a previewable artifact card. Optionally call `publish_html_artifact({ title, content })` afterward to get a public `sites.kolbo.ai` URL.
+
+## 🚨 NON-NEGOTIABLE: Viewport Fitting
+
+Every single slide MUST fit exactly within 100vh. **No scrolling within a slide, ever.** If content doesn't fit, SPLIT into multiple slides. This is the #1 rule, no exceptions.
+
+Apply these invariants to EVERY slide in EVERY deck:
+- Every `.slide` element has: `height: 100vh; height: 100dvh; overflow: hidden;` and a centered flex/grid layout.
+- ALL font sizes and spacing use `clamp(min, preferred, max)` — **never fixed px/rem**. Example: `font-size: clamp(2.5rem, 5vw, 5rem);`.
+- Content containers need explicit `max-height` constraints.
+- Images: `max-height: min(50vh, 400px); object-fit: contain;`.
+- Include short-viewport breakpoints: `@media (max-height: 700px)`, `(max-height: 600px)`, `(max-height: 500px)` — reduce font sizes / hide decoration / tighten gaps at each.
+- Add `@media (prefers-reduced-motion: reduce) { *, *::before, *::after { animation-duration: 0.01ms !important; transition-duration: 0.01ms !important; } }`.
+- Never negate CSS functions directly. `-clamp()` is silently ignored. Use `calc(-1 * clamp(...))`.
+
+## 🚨 NON-NEGOTIABLE: Content Density Limits per Slide
+
+| Slide Type     | Maximum Content |
+| -------------- | --------------- |
+| Title slide    | 1 heading + 1 subtitle + optional tagline |
+| Content slide  | 1 heading + 4–6 bullets OR 1 heading + 2 short paragraphs |
+| Feature grid   | 1 heading + max 6 cards (2×3 or 3×2) |
+| Code slide     | 1 heading + 8–10 lines of code max |
+| Quote slide    | 1 quote (≤3 lines) + attribution |
+| Image slide    | 1 heading + 1 image (max 60vh height) |
+
+**Content exceeds limits? Split into more slides. Never cram, never shrink fonts to fit, never enable scrolling.**
+
+## Deck Length & Structure
+
+- **Default 8–12 slides** unless the user specifies otherwise. **Hard cap 16 slides** — bigger decks become unwieldy.
+- Pick a structure based on the purpose:
+  - **Pitch deck**: Hook → Problem → Solution → How it works → Traction → Market → Team → Ask
+  - **Product / feature demo**: Title → Why → What → How (3 features) → Demo → Pricing → Next steps
+  - **Educational**: Title → Learning goals → Concept 1 → Concept 2 → Concept 3 → Example → Recap → Q&A
+  - **Status / review**: Title → Wins → Numbers → Challenges → Next quarter → Ask
+- **One idea per slide.** Headlines lead: short, declarative, ideally <8 words. Body copy supports.
+
+## Slide Layout Palette (vary these — never use the same layout twice in a row)
+
+- **Title slide**: oversized headline, subtitle, optional brand mark / date / speaker name.
+- **Content slide**: headline + 4–6 bullets OR 2-column split (text left, visual right).
+- **Quote / pull-quote**: big quote, attribution, optional accent.
+- **Data slide**: big number (kpi) + label + small supporting chart (Chart.js).
+- **Image-led slide**: full-bleed image with caption overlay.
+- **Comparison slide**: side-by-side with checkmarks/crosses.
+- **Process / flow slide**: numbered steps with arrows / chevrons.
+- **Closing / CTA slide**: short CTA, contact, thank-you.
+
+## Aesthetic Direction — COMMIT BOLDLY
+
+**Pick a clear conceptual direction and execute it with precision.** No timid middle-ground choices. Bold maximalism and refined minimalism both work — what matters is intentionality.
+
+Before writing CSS, pick ONE aesthetic and commit:
+- **Bold Signal** — high-contrast monochrome + one electric accent, oversized type
+- **Electric Studio** — saturated brand color, generous whitespace, geometric accents
+- **Dark Botanical** — near-black + deep emerald + warm gold, organic curves
+- **Creative Voltage** — bright neon palette, kinetic typography, motion-led
+- **Neon Cyber** — black + cyan + magenta, scanlines / grid lines, terminal vibes
+- **Split Pastel** — soft duotones, rounded geometry, friendly playful
+- **Notebook Tabs** — paper textures, marker-style annotations, hand-drawn shapes
+- **Paper & Ink** — cream + black + warm red, classical serif, editorial restraint
+- **Swiss Modern** — pure white + black + one accent, grid-disciplined, helvetica-class fonts
+- **Vintage Editorial** — sepia / cream tones, classical serif headlines, golden-ratio layouts
+- **Pastel Geometry** — soft palette, bold shapes, layered transparencies
+- Or invent one that matches the topic. Don't always default to the same look.
+
+## Typography — DISTINCTIVE FONTS ONLY
+
+**Never use system fonts. Never use Inter, Roboto, or Arial.** Pull from Google Fonts or Fontshare. Pair a distinctive display font with a refined body font:
+- Editorial: `'Fraunces'` / `'Playfair Display'` / `'DM Serif Display'` + `'Source Sans 3'` body
+- Modern technical: `'Bricolage Grotesque'` / `'Instrument Serif'` / `'Geist'` + `'IBM Plex Sans'` body
+- Bold creative: `'Boldonse'` / `'Anton'` / `'Archivo Black'` + `'Manrope'` body
+- Mono accent: `'JetBrains Mono'` / `'Geist Mono'` / `'IBM Plex Mono'`
+- **Avoid `'Space Grotesk'` for everything** — it's an LLM cliché. Pick something else most of the time.
+
+Hebrew: `'Heebo'`, `'Rubik'`, `'Frank Ruhl Libre'`, `'Assistant'`. Arabic: `'Cairo'`, `'Tajawal'`, `'IBM Plex Sans Arabic'`, `'Reem Kufi'`.
+
+## Color & Background
+
+- Commit to a cohesive palette. **Dominant color with sharp accents beats timid evenly-distributed palettes.** Use CSS custom properties (`:root { --bg: ...; --fg: ...; --accent: ...; }`).
+- Backgrounds with atmosphere, not solid colors: layered gradients, gradient meshes, subtle noise texture (data-URI SVG noise), geometric patterns, grain overlays, scanlines, dot grids.
+- ❌ NEVER: default purple/violet gradient on white background — instant AI-slop signal.
+
+## Motion — High-Impact, Not Scattered
+
+- One well-orchestrated page-load with staggered reveals (`animation-delay` ladder) beats scattered micro-interactions sprinkled everywhere.
+- Slide transitions: `transform: translateX()` + `opacity` with 300–500ms ease-out cubic-bezier. No bouncy / corny effects.
+- Use CSS keyframes for everything. GSAP via CDN ONLY if you need a timeline or scroll-trigger.
+- Always include the `prefers-reduced-motion` media query.
+
+## Slide Mechanics
+
+- Each slide = `<section class="slide">` inside `<main id="deck">`.
+- Only ONE slide visible at a time. Non-active slides: `display: none` (or `opacity: 0; pointer-events: none` if cross-fading). Active slide: `.active` with the slide-type's display.
+- Navigation:
+  - Arrow keys: `ArrowRight` / `Space` → next, `ArrowLeft` → prev. `Home` / `End` → first/last.
+  - On-screen prev/next buttons at bottom corners, semi-transparent.
+  - Slide counter "3 / 10" in a corner.
+  - Press `F` for fullscreen (`document.documentElement.requestFullscreen()`). `Esc` exits.
+  - Press number keys 1–9 to jump to that slide.
+  - **RTL decks**: swap arrow direction — right arrow → previous, left arrow → next.
+- Subtle progress bar at the very top, fills as the user advances.
+
+## RTL / Multilingual
+
+- Detect language. Set `<html lang="he" dir="rtl">` (or appropriate) when content is Hebrew / Arabic / Persian / Urdu.
+- Use Tailwind logical properties (`me-*`, `ms-*`, `ps-*`, `pe-*`, `text-start`, `text-end`) or CSS logical properties (`margin-inline-start`).
+- Headline fonts: use locale-appropriate fonts (see Typography section).
+
+## Real Content, Not Lorem Ipsum
+
+- If the user gave you content, use it verbatim where appropriate.
+- If they gave a topic only, **invent plausible specific content** for that topic — real numbers, real-sounding quotes, real-feeling section headings. Never "Lorem ipsum", never "Insert your text here".
+
+## Output Discipline — HTML Artifact (NON-NEGOTIABLE)
+
+- Your 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 `<script src="https://cdn.tailwindcss.com"></script>`, GSAP, Chart.js, D3.js, Three.js, Lucide Icons, Framer Motion, React 18 + Babel standalone, Vue 3, date-fns.
+- Outside the html block you can write a 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 to the user's language and set the appropriate `lang` + `dir` attributes.
+
+## 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 the user approves the deck, offer `publish_html_artifact({ title, content })` to get a shareable `sites.kolbo.ai` URL. Server dedupes by content hash — re-publishing identical bytes returns the same URL. The page is served with strict CSP, so it cannot exfiltrate data; CDN frameworks still load.

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` |