@rubytech/taskmaster 1.0.97 → 1.0.99

package/dist/gateway/chat-sanitize.js

@@ -173,6 +173,29 @@ function extractMediaRefs(text) {
     }
     return refs;
 }
+// Pattern: MEDIA:/absolute/path (used by tool results like image_generate)
+const MEDIA_PREFIX_PATTERN = /\bMEDIA:(\S+)/g;
+/**
+ * Parse MEDIA:/path references from text to extract file paths.
+ * Tool results (e.g. image_generate) use this format instead of
+ * [media attached: ...] annotations.
+ */
+function extractMediaPrefixRefs(text) {
+    if (!text.includes("MEDIA:"))
+        return [];
+    const refs = [];
+    let match;
+    MEDIA_PREFIX_PATTERN.lastIndex = 0;
+    while ((match = MEDIA_PREFIX_PATTERN.exec(text)) !== null) {
+        const absPath = match[1]?.trim();
+        if (absPath) {
+            const ext = absPath.split(".").pop()?.toLowerCase() ?? "";
+            const mimeType = ext === "jpg" || ext === "jpeg" ? "image/jpeg" : "image/png";
+            refs.push({ absPath, mimeType });
+        }
+    }
+    return refs;
+}
 function mediaRefToUrl(ref, workspaceRoot) {
     const relPath = nodePath.relative(workspaceRoot, ref.absPath);
     // Must stay within workspace (no ../ escapes)
@@ -254,8 +277,13 @@ function sanitizeMessageMedia(message, workspaceRoot) {
     if (!message || typeof message !== "object")
         return message;
     const entry = message;
-    // Collect media refs from text content (works for both string and array content)
-    const mediaRefs = extractMediaRefsFromMessage(entry);
+    // Collect media refs from text content (works for both string and array content).
+    // MEDIA: prefix refs are only extracted from tool result messages — assistant text
+    // may echo "MEDIA:" but that should not produce a duplicate image block.
+    const role = typeof entry.role === "string" ? entry.role.toLowerCase() : "";
+    const isToolResult = role === "toolresult" || role === "tool_result" ||
+        typeof entry.toolCallId === "string" || typeof entry.tool_call_id === "string";
+    const mediaRefs = extractMediaRefsFromMessage(entry, isToolResult);
     // Build URL-based image blocks from annotations
     const imageBlocks = [];
     for (const ref of mediaRefs) {
@@ -283,6 +311,28 @@ function sanitizeMessageMedia(message, workspaceRoot) {
         }
         return true;
     });
+    // Strip MEDIA:/path text from ALL messages (tool results AND assistant echoes).
+    // This prevents raw file paths from ever showing in the chat UI.
+    for (let i = 0; i < filtered.length; i++) {
+        const block = filtered[i];
+        if (block.type === "text" && typeof block.text === "string" && block.text.includes("MEDIA:")) {
+            const cleaned = block.text
+                .split(/\r?\n/)
+                .filter((line) => !/\bMEDIA:\S+/.test(line))
+                .join("\n")
+                .trim();
+            if (!cleaned) {
+                filtered.splice(i, 1);
+                i--;
+                didChange = true;
+            }
+            else if (cleaned !== block.text) {
+                filtered[i] = { ...block, text: cleaned };
+                didChange = true;
+            }
+        }
+    }
+    // Add URL-based image blocks from tool result annotations
     if (imageBlocks.length > 0) {
         didChange = true;
         filtered.push(...imageBlocks);
@@ -291,9 +341,12 @@ function sanitizeMessageMedia(message, workspaceRoot) {
         return message;
     return { ...entry, content: filtered };
 }
-function extractMediaRefsFromMessage(entry) {
+function extractMediaRefsFromMessage(entry, includeMediaPrefix) {
     if (typeof entry.content === "string") {
-        return extractMediaRefs(entry.content);
+        const refs = extractMediaRefs(entry.content);
+        if (includeMediaPrefix)
+            refs.push(...extractMediaPrefixRefs(entry.content));
+        return refs;
     }
     if (Array.isArray(entry.content)) {
         const refs = [];
@@ -303,6 +356,8 @@ function extractMediaRefsFromMessage(entry) {
             const b = block;
             if (b.type === "text" && typeof b.text === "string") {
                 refs.push(...extractMediaRefs(b.text));
+                if (includeMediaPrefix)
+                    refs.push(...extractMediaPrefixRefs(b.text));
             }
         }
         return refs;

package/dist/gateway/control-ui.js

@@ -474,26 +474,27 @@ export function handlePublicChatHttpRequest(req, res, opts) {
 /** Widget script content — self-contained JS for embedding. */
 const WIDGET_SCRIPT = `(function(){
   "use strict";
-  var cfg={server:"",accountId:""};
+  var cfg={server:"",accountId:"",color:"#1a1a2e"};
   var isOpen=false;
   var btn,overlay,iframe;
 
   function init(opts){
     if(opts&&opts.server) cfg.server=opts.server.replace(/\\/$/,"");
     if(opts&&opts.accountId) cfg.accountId=opts.accountId;
+    if(opts&&opts.color) cfg.color=opts.color;
     build();
   }
 
   function build(){
     var css=document.createElement("style");
     css.textContent=[
-      ".tm-widget-btn{position:fixed;bottom:20px;right:20px;width:60px;height:60px;",
-      "border-radius:50%;background:#0078ff;color:#fff;border:none;cursor:pointer;",
-      "box-shadow:0 4px 12px rgba(0,0,0,.25);z-index:999999;font-size:28px;",
+      ".tm-widget-btn{position:fixed;bottom:20px;right:20px;width:48px;height:48px;",
+      "border-radius:50%;background:"+cfg.color+";color:#fff;border:none;cursor:pointer;",
+      "box-shadow:0 2px 8px rgba(0,0,0,.3);z-index:999999;font-size:22px;",
       "display:flex;align-items:center;justify-content:center;transition:transform .2s}",
-      ".tm-widget-btn:hover{transform:scale(1.1)}",
-      ".tm-widget-overlay{position:fixed;bottom:90px;right:20px;width:400px;height:600px;",
-      "max-width:calc(100vw - 40px);max-height:calc(100vh - 110px);",
+      ".tm-widget-btn:hover{transform:scale(1.08)}",
+      ".tm-widget-overlay{position:fixed;bottom:78px;right:20px;width:400px;height:600px;",
+      "max-width:calc(100vw - 40px);max-height:calc(100vh - 98px);",
       "border-radius:12px;overflow:hidden;box-shadow:0 8px 30px rgba(0,0,0,.3);",
       "z-index:999998;display:none;background:#1a1a2e}",
       ".tm-widget-overlay.open{display:block}",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rubytech/taskmaster",
-  "version": "1.0.97",
+  "version": "1.0.99",
   "description": "AI-powered business assistant for small businesses",
   "publishConfig": {
     "access": "public"

package/scripts/install.sh

@@ -4,10 +4,10 @@ set -euo pipefail
 # Taskmaster — one-command install for fresh devices (Pi or Mac).
 #
 # Usage:
-#   curl -fsSL https://taskmaster.bot/install.sh | bash
+#   curl -fsSL https://taskmaster.bot/install.sh | sudo bash
 #
 # With custom port:
-#   curl -fsSL https://taskmaster.bot/install.sh | bash -s -- --port 19000
+#   curl -fsSL https://taskmaster.bot/install.sh | sudo bash -s -- --port 19000
 
 PORT=""
 for arg in "$@"; do

package/skills/image-gen/SKILL.md

@@ -0,0 +1,68 @@
+---
+name: image-gen
+description: Generate images using Google AI models (Gemini, Imagen 4). Guides users through model selection, style choices, and expert prompt crafting.
+metadata: {"taskmaster":{"emoji":"🎨"}}
+---
+
+# Image Generation
+
+Generate images from text descriptions using Google AI models. Two model families are available: Gemini (conversational, multi-turn editing) and Imagen 4 (dedicated generation, higher fidelity).
+
+## When to activate
+
+- User asks to create, generate, design, draw, or make an image, illustration, logo, photo, graphic, or visual
+- User sends an image and asks to edit, modify, or create a variation
+- User asks about image generation capabilities or model differences
+
+## Prerequisites
+
+Requires a Google AI API key. If missing, activate the `google-ai` skill to guide the user through setup first.
+
+## Critical rule
+
+Only the `image_generate` tool produces images. Never write file paths, MEDIA: references, or image URLs in text. If you did not call `image_generate`, no image was generated. There is no other mechanism.
+
+## Quick Model Reference
+
+| Model | Speed | Best for |
+|-------|-------|----------|
+| gemini-2.5-flash-image | Fast | Quick drafts, iteration, editing existing images |
+| gemini-3-pro-image-preview | Moderate | Text in images, highest Gemini quality, 4K |
+| imagen-4.0-fast-generate-001 | Fast | Rapid photo-realistic output |
+| imagen-4.0-generate-001 | Moderate | Balanced quality and speed |
+| imagen-4.0-ultra-generate-001 | Slow | Maximum fidelity, hero images |
+
+## References
+
+| Reference | When to load |
+|-----------|-------------|
+| `references/models.md` | Choosing between models, understanding API differences, resolution or feature questions |
+| `references/styles.md` | Discussing style, aspect ratio, mood, lighting, or colour choices with the user |
+| `references/prompting.md` | Crafting the generation prompt, iterating on results, business use cases |
+| `references/troubleshooting.md` | Any generation error — quota, auth, content policy, model availability |
+
+Load the relevant reference before proceeding. For a typical generation request: load `prompting.md` to craft the prompt, consult `models.md` if the user has specific quality/speed needs, and check `styles.md` if style discussion is needed. **On any error**, load `troubleshooting.md` immediately — it has browser-assisted resolution steps for every common failure.
+
+## Workflow
+
+### Phase 1: Gather (conversation with user)
+
+1. **Understand intent** — What does the user want? Product shot, social graphic, logo concept, illustration?
+2. **Recommend model** — Match speed/quality needs to a model. Default to Gemini Flash for quick work, Imagen Standard for quality.
+3. **Discuss style** — Ask about style, mood, and aspect ratio if the user hasn't specified. Suggest options based on use case.
+
+### Phase 2: Generate (MUST call tool)
+
+4. **Craft prompt and generate in a single turn** — Build an expert prompt using `references/prompting.md`. Show the prompt to the user AND call `image_generate` in the same response. Do not show the prompt without calling the tool. Do not wait for approval of the prompt before generating — generate immediately and iterate after.
+
+This step is a hard gate. You MUST call `image_generate` here. The conversation cannot continue past this point without a tool call. If you respond with text only, you have failed this step.
+
+### Phase 3: Deliver (requires tool result)
+
+5. **Present the result** — The tool result contains the generated image. The user sees it inline. Offer to refine: adjust style, change composition, try a different model, or edit specific elements.
+
+You cannot reach this step without the tool result from step 4. If `image_generate` was not called, go back to step 4.
+
+## Error Handling
+
+If generation fails, **load `references/troubleshooting.md` and follow its guidance**. Common issues (quota exceeded, auth errors, content policy) are all resolvable in-session. Use the browser tool to navigate to Google AI Studio with the user and resolve billing, quota, or key issues collaboratively.

package/skills/image-gen/references/models.md

@@ -0,0 +1,83 @@
+# Image Generation Models
+
+Two API backends, five models. Both use the same Google AI API key.
+
+---
+
+## API Backends
+
+### Gemini Native (generateContent)
+
+Conversational image generation built into the Gemini chat API. Supports multi-turn editing — you can generate an image, then ask to modify it in follow-up turns. Also supports image-to-image: send an existing image and ask for edits, style transfers, or variations.
+
+The Gemini backend accepts the same `generateContent` call used for text, with `responseModalities: ["TEXT", "IMAGE"]`. This means image generation is part of a natural conversation flow.
+
+### Imagen 4 (predict)
+
+Dedicated image generation API optimized for fidelity. Single-shot generation only — no multi-turn editing. Can produce 1-4 images per request, enabling the user to pick the best result. Higher baseline quality for photo-realistic output.
+
+---
+
+## Model Details
+
+| Model | API | Speed | Max Resolution | Strengths | Limitations |
+|-------|-----|-------|---------------|-----------|-------------|
+| gemini-2.5-flash-image | Gemini | Fast | 2K | Quick iterations, low cost, multi-turn editing, image-to-image | Lower detail than Pro |
+| gemini-3-pro-image-preview | Gemini | Moderate | 4K | Text rendering in images, thinking mode, accepts up to 14 reference images | Preview model, slower |
+| imagen-4.0-fast-generate-001 | Imagen | Fast | 1K | Rapid photo-realistic generation | Lower resolution than Standard |
+| imagen-4.0-generate-001 | Imagen | Moderate | 2K | Balanced quality and speed, good photo-realism | English only, 480 token prompt limit |
+| imagen-4.0-ultra-generate-001 | Imagen | Slow | 2K | Maximum fidelity, finest detail | Slowest, English only |
+
+---
+
+## Decision Matrix
+
+Choose based on the user's actual need, not the "best" model. Speed and iteration matter more than peak fidelity for most business use cases.
+
+| Use case | Recommended model | Why |
+|----------|-------------------|-----|
+| Quick draft or iteration | gemini-2.5-flash-image | Fastest turnaround, supports editing in follow-up messages |
+| Text in image (menu, sign, infographic) | gemini-3-pro-image-preview | Best text rendering of any model |
+| Photo-realistic product shot | imagen-4.0-generate-001 or ultra | Imagen excels at photo-realism |
+| Social media graphic | gemini-2.5-flash-image or imagen-4.0-fast | Speed matters for social content |
+| Hero image or print material | imagen-4.0-ultra-generate-001 or gemini-3-pro at 4K | Maximum quality for final output |
+| Edit or refine an existing image | gemini-2.5-flash-image | Only Gemini supports multi-turn editing |
+| Multiple options to choose from | Any Imagen model | Imagen can generate 1-4 images per request |
+
+---
+
+## Key Differences Between Backends
+
+**Aspect ratios:**
+- Gemini supports wider ratios including 21:9 (ultrawide banners, website headers)
+- Imagen is limited to 5 aspect ratios: 1:1, 3:4, 4:3, 9:16, 16:9
+
+**Editing:**
+- Gemini supports multi-turn editing — generate, then refine in conversation
+- Imagen is single-shot only — each request is independent
+
+**Batch output:**
+- Imagen supports 1-4 images per request (`numberOfImages` parameter)
+- Gemini generates 1 image per request
+
+**Person generation:**
+- Imagen supports `personGeneration` control ("dont_allow", "allow_adult", "allow_all")
+- Gemini does not have this parameter
+
+**Language:**
+- Gemini accepts prompts in any language
+- Imagen accepts English only, with a 480-token prompt limit
+
+**Watermarking:**
+- All models apply SynthID digital watermark to generated images
+
+---
+
+## Default Recommendations
+
+When the user doesn't specify a preference:
+
+- **Start with Gemini Flash** for exploration and drafting — it's fast, cheap, and the user can iterate conversationally
+- **Switch to Imagen Standard or Ultra** when the user is happy with the concept and wants maximum quality for the final output
+- **Use Gemini Pro** when the image needs readable text (menus, signs, business cards, infographics)
+- **Offer Imagen batch mode** when the user wants options — "I can generate 4 variations for you to pick from"

package/skills/image-gen/references/prompting.md

@@ -0,0 +1,184 @@
+# Expert Prompt Construction
+
+A strong prompt is the difference between a usable image and a generic one. This reference covers prompt structure, quality modifiers, and business-specific examples.
+
+---
+
+## Prompt Structure
+
+Build prompts in this order. Each element adds specificity. Not every element is needed for every image — use judgement based on the request.
+
+```
+Subject → Style → Composition → Lighting → Mood → Quality modifiers
+```
+
+**Subject:** What is in the image. Be concrete — "a golden retriever puppy sitting on grass" beats "a dog." Include materials, textures, and context when relevant.
+
+**Style:** How the image looks. Photorealistic, illustration, watercolour, etc. See `styles.md` for vocabulary.
+
+**Composition:** How the frame is arranged. Camera angle, framing, depth of field, negative space.
+
+**Lighting:** How the scene is lit. Studio, golden hour, dramatic, etc. This has outsized impact on mood.
+
+**Mood:** The emotional feel. Professional, cozy, dramatic, energetic. Guides the overall atmosphere.
+
+**Quality modifiers:** Technical terms that push the model toward higher-quality output.
+
+---
+
+## Quality Modifiers
+
+Append these to improve output quality. Use sparingly — 2-3 is effective, more can cause conflicting signals.
+
+- "highly detailed" — encourages fine detail and texture
+- "professional quality" — steers toward polished, commercial output
+- "sharp focus" — reduces soft or blurry areas
+- "4K" / "8K resolution" — emphasises resolution and clarity in the prompt
+- "award-winning" — biases toward striking, well-composed results
+- "editorial quality" — clean, publication-ready aesthetic
+
+---
+
+## Composition Terms
+
+| Term | Effect |
+|------|--------|
+| "close-up" | Tight framing on subject |
+| "wide angle" | Expansive view, more context |
+| "bird's eye view" | Top-down perspective |
+| "eye level" | Natural, relatable perspective |
+| "rule of thirds" | Subject offset, balanced composition |
+| "centered" | Subject in the middle, symmetrical |
+| "symmetrical" | Mirror balance, architectural feel |
+| "shallow depth of field" | Subject sharp, background blurred |
+| "bokeh background" | Soft, circular blur behind subject |
+| "negative space" | Large empty areas, minimalist feel |
+| "minimalist composition" | Few elements, clean, focused |
+
+---
+
+## Business Use Case Examples
+
+These are starting points. Adapt subject, colours, and details to the user's specific needs.
+
+### Product Photography
+
+```
+Professional product photograph of [item] on a clean white surface, studio lighting,
+shallow depth of field, commercial quality, highly detailed, 4K
+```
+
+```
+Lifestyle product shot of [item] in a modern kitchen, natural window light,
+warm tones, editorial quality, shallow depth of field
+```
+
+```
+Flat lay arrangement of [items] on a marble surface, top-down view,
+soft diffused lighting, minimalist composition, professional quality
+```
+
+### Social Media Graphics
+
+```
+Vibrant flat design illustration of [concept], bold colours, clean lines,
+modern aesthetic, Instagram-ready, 1:1 aspect ratio
+```
+
+```
+Eye-catching social media graphic with [text/concept], gradient background,
+bold typography space, energetic mood, vibrant colours
+```
+
+```
+Minimalist quote background, soft pastel gradient, clean negative space
+for text overlay, calming mood, 1:1
+```
+
+### Logo Concepts
+
+```
+Minimalist logo design for [business type], clean vector style, simple geometric shapes,
+professional, white background, scalable design
+```
+
+```
+Modern logo mark for [business type], flat design, single accent colour on white,
+memorable silhouette, minimalist
+```
+
+Note: Image generation models produce raster images, not vectors. Generated logos work well as concepts and mood boards. For final logo files, the user will need a graphic designer to recreate the chosen concept as a vector.
+
+### Business Headshots
+
+```
+Professional headshot portrait, studio lighting, neutral grey background,
+sharp focus, natural expression, business attire, editorial quality
+```
+
+```
+Approachable business portrait, natural window light, warm tones,
+shallow depth of field, genuine smile, professional quality
+```
+
+### Illustrations
+
+```
+Warm watercolour illustration of [scene], soft edges, pastel palette,
+editorial style, hand-painted feel, gentle mood
+```
+
+```
+Detailed line art illustration of [subject], black ink on white,
+clean lines, technical precision, architectural style
+```
+
+```
+Playful children's book illustration of [scene], bright colours,
+rounded shapes, whimsical mood, hand-drawn style
+```
+
+### Marketing and Print
+
+```
+Hero image for [business type] website, wide angle shot of [scene],
+golden hour lighting, professional quality, 16:9, inviting mood
+```
+
+```
+Business card background, abstract geometric pattern, [brand colours],
+subtle texture, professional, minimalist, 3:2
+```
+
+---
+
+## Iteration Tips
+
+When the first result isn't right, refine systematically rather than starting from scratch.
+
+**Change one thing at a time.** If the lighting is wrong but the composition is good, adjust only the lighting terms. Changing everything at once makes it impossible to learn what works.
+
+**Add specificity to fix vagueness.** Generic subjects produce generic results. "A dog" becomes "a golden retriever puppy sitting on freshly cut grass, looking at camera." Specificity is the most reliable way to improve output.
+
+**Use Gemini models for iterative refinement.** Gemini supports multi-turn editing — generate an image, then ask to change specific elements ("make the background warmer," "remove the text," "zoom in on the product"). This is faster than re-prompting from scratch.
+
+**Switch to Imagen for final output.** Once the concept is right (via Gemini iteration), re-generate with Imagen Standard or Ultra for maximum fidelity. Think of Gemini as the sketch pad and Imagen as the final print.
+
+**Ask the user what to change, not whether they like it.** "What would you change?" gets more useful feedback than "Do you like it?" People find it easier to articulate what's wrong than to rate overall quality.
+
+---
+
+## Imagen-Specific Tips
+
+Imagen models have constraints that affect prompt strategy:
+
+- **English only** — prompts must be in English, even if the user's conversation is in another language. Translate the intent, then prompt in English.
+- **480-token prompt limit** — be concise. Front-load the most important elements (subject, style) and put modifiers at the end so they get trimmed first if the prompt is too long.
+- **Concrete over abstract** — Imagen produces better results with specific, visual descriptions than with abstract concepts. "A sunrise over a calm ocean" works better than "hope and renewal."
+- **Person generation control** — use `personGeneration: "dont_allow"` when people aren't needed in the image. This avoids potential content policy issues and often produces cleaner results for product/object shots.
+
+---
+
+## Showing the Prompt
+
+Show the user the crafted prompt AND call `image_generate` in the same turn. Do not wait for prompt approval before generating — generate immediately, then iterate. This avoids unnecessary round-trips and gives the user a concrete result to react to. Frame it as: "Here's what I'm generating:" followed by the tool call. Iterate after seeing the result.

package/skills/image-gen/references/styles.md

@@ -0,0 +1,113 @@
+# Style, Format & Visual Vocabulary
+
+Use this reference when discussing visual style with the user. Suggest options based on their use case — most users know what they want to feel, not the technical vocabulary to express it.
+
+---
+
+## Style Categories
+
+Each style has distinct strengths. Match the style to the purpose, not personal preference.
+
+| Style | Character | When to suggest |
+|-------|-----------|-----------------|
+| **Photorealistic** | Lifelike, indistinguishable from a photograph | Product photography, headshots, real estate, food |
+| **Illustration** | Hand-drawn feel, artistic interpretation | Editorial content, children's materials, storytelling |
+| **Digital art** | Polished, vibrant, contemporary | Tech marketing, game assets, social media |
+| **Watercolour** | Soft edges, translucent washes, organic | Invitations, fine art prints, greeting cards |
+| **Oil painting** | Rich textures, visible brushwork, classical depth | Portraits, wall art, premium branding |
+| **Minimalist** | Clean, sparse, essential shapes only | Logos, icons, modern branding |
+| **3D render** | Dimensional, material-accurate, product-focused | Product mockups, architectural visualisation, tech |
+| **Pixel art** | Blocky, nostalgic, 8/16-bit aesthetic | Gaming, retro branding, novelty |
+| **Vector / flat** | Clean lines, solid fills, scalable | Infographics, UI elements, icons, print |
+| **Sketch / line art** | Raw, conceptual, structural | Wireframes, concept art, technical illustration |
+| **Pop art** | Bold outlines, high contrast, graphic | Marketing, social media, event posters |
+| **Anime / manga** | Expressive, character-driven, stylised | Character design, storytelling, youth audience |
+| **Vintage / retro** | Aged, film grain, muted tones, nostalgic | Heritage branding, event themes, editorial |
+
+---
+
+## Aspect Ratios
+
+Aspect ratio should match the output medium. Ask the user where the image will be used if they haven't said.
+
+| Ratio | Common uses | Notes |
+|-------|-------------|-------|
+| **1:1** | Social media posts, profile pictures, product shots | Universal default |
+| **16:9** | Presentations, hero images, desktop wallpapers, YouTube thumbnails | Standard widescreen |
+| **9:16** | Instagram/TikTok stories, mobile wallpapers, vertical ads | Vertical video format |
+| **3:4 / 4:3** | Portrait/landscape photos, print | Classic photography |
+| **3:2 / 2:3** | Traditional photo format, DSLR native | Gemini only |
+| **21:9** | Ultrawide banners, website headers, cinematic | Gemini only |
+
+When a requested ratio isn't available for the chosen model (e.g. 21:9 on Imagen), explain the limitation and suggest the closest alternative.
+
+---
+
+## Colour Vocabulary
+
+Use these terms in prompts to steer colour treatment. Combine with style for precision.
+
+| Term | Effect |
+|------|--------|
+| **Warm** | Reds, oranges, yellows — cozy, inviting |
+| **Cool** | Blues, greens, purples — calm, professional |
+| **Muted** | Desaturated, subdued — sophisticated, understated |
+| **Vibrant** | Saturated, bold — energetic, attention-grabbing |
+| **Monochrome** | Single hue or black/white — dramatic, editorial |
+| **Pastel** | Soft, light tints — gentle, approachable |
+| **Neon** | Electric, glowing — nightlife, tech, youth |
+| **Earth tones** | Browns, tans, olive — natural, organic |
+| **Jewel tones** | Deep emerald, sapphire, ruby — rich, luxurious |
+| **Neutral** | Greys, whites, beiges — clean, unobtrusive |
+
+---
+
+## Mood Vocabulary
+
+Mood shapes the overall emotional impression. It influences lighting, colour, composition, and subject expression.
+
+| Mood | Visual impression |
+|------|-------------------|
+| **Dramatic** | High contrast, deep shadows, strong focal point |
+| **Serene** | Soft light, open space, gentle colours |
+| **Energetic** | Bright, dynamic angles, saturated colour |
+| **Mysterious** | Low light, fog, obscured elements, cool tones |
+| **Whimsical** | Playful, unexpected, fantasy elements |
+| **Professional** | Clean, neutral, well-lit, no visual noise |
+| **Playful** | Bright, rounded shapes, warm palette |
+| **Dark** | Low-key lighting, muted palette, heavy shadows |
+| **Ethereal** | Soft focus, glowing light, translucent elements |
+| **Cozy** | Warm tones, soft textures, intimate framing |
+| **Bold** | Strong shapes, high saturation, graphic composition |
+
+---
+
+## Lighting Vocabulary
+
+Lighting is the single most impactful prompt element after subject and style. Specific lighting terms produce dramatically different results.
+
+| Lighting | Character | Best for |
+|----------|-----------|----------|
+| **Golden hour** | Warm, directional, long shadows | Portraits, landscapes, lifestyle |
+| **Studio** | Even, controlled, professional | Product shots, headshots |
+| **Natural** | Ambient, unprocessed, authentic | Documentary, editorial |
+| **Dramatic / chiaroscuro** | Strong contrast between light and shadow | Portraits, moody scenes |
+| **Flat** | Even, shadowless, clean | Product photography, UI mockups |
+| **Rim-lit** | Edge highlighting, subject separation | Silhouettes, athletic, cinematic |
+| **Backlit** | Light behind subject, halo effect | Ethereal, spiritual, romantic |
+| **Soft / diffused** | Gentle, wrapped light, minimal shadows | Beauty, fashion, food |
+| **Neon** | Coloured artificial light, urban | Night scenes, tech, cyberpunk |
+| **Candlelight** | Warm, flickering, intimate | Cozy scenes, romantic, vintage |
+
+---
+
+## Combining Vocabulary
+
+A well-crafted style description combines one element from each category. Examples:
+
+- Product shot: "photorealistic, studio lighting, neutral background, professional mood"
+- Social post: "digital art, vibrant colours, energetic mood, flat lighting, 1:1"
+- Business card: "minimalist, monochrome, clean, professional, 3:2"
+- Event poster: "pop art, neon colours, bold mood, dramatic lighting, 9:16"
+
+The order matters less than specificity. Vague descriptions produce generic results.