cue-ai 0.3.0

package/resources/skills/skills/higgsfield/higgsfield-generate/references/model-catalog.md

@@ -0,0 +1,143 @@
+# Model Catalog
+
+The full lineup of generation models available through Higgsfield. Each entry has its own sweet spot — pick the one that matches your brief. For the actual `--model` ID to pass to `higgsfield generate create`, run `higgsfield model list --json` and look up by display name.
+
+Preferred defaults for examples and quick-start guidance in this repo:
+- **Images:** `gpt_image_2` (general/high-fidelity) and `nano_banana_2` (character/cartoon).
+- **Video:** `seedance_2_0` (all-purpose serious video).
+
+---
+
+## Image models
+
+| Model | Provider | What it's for |
+|---|---|---|
+| Nano Banana 2 | Google | **Fast everyday default for character work.** Edits, general generation, character / cartoon / animated-style outputs. The reach-for-this model when the brief calls for character or cartoon-style image generation. |
+| Nano Banana Pro | Google | **Top-tier Nano Banana.** Same canvas as Nano Banana 2 with extra fidelity and accuracy on harder briefs. Pick when 2 isn't getting there. |
+| Nano Banana | Google | Reliable, budget-friendly entry in the Nano Banana family — picks up the same realistic look at a lighter price point. |
+| Higgsfield Soul 2.0 | Higgsfield | **Aesthetic UGC, fashion editorial, character generation.** When the brief leans editorial, lifestyle, or "looks like a magazine cover". Soul-aware (accepts a Soul Character reference). |
+| Soul Cinema | Higgsfield | **Cinematic stills, film-grade lighting.** The pick when the user asks for "cinematic" or wants concept-art mood. |
+| Soul Cast | Higgsfield | **Distinctive, characterful personas.** When the brief calls for a creative, expressive character rather than photoreal default. Text-only (no reference image). |
+| Soul Location | Higgsfield | **Best-in-class environments and locations.** Unmatched for pure scene and place generation without a person in frame. |
+| Seedream 4.5 | Bytedance | **Vector illustrations and complex scene edits with faces.** When the brief is a face-anchored photo edit into a complex new scene (more than an outfit change), without heavy filters. |
+| Seedream 5.0 Lite | Bytedance | Same Seedream lineage as 4.5 with faster turnaround for visual-reasoning and instruction-based edits. |
+| Z Image | Tongyi-MAI | **Fastest in the catalog.** Built for speed, drafts, and LoRA-driven stylization. The pick when the brief is "fast and cheap, let me iterate". |
+| Flux 2.0 | Black Forest Labs | Precise prompt adherence with multiple variants (pro, flex, max). A strong creative alternative when the user wants a different look from the Banana family. |
+| Flux Kontext Max | Black Forest Labs | **Context-aware editing and style transfer.** Strong for anime, stylized looks, typography remix — when defaults feel too generic. |
+| Kling O1 Image | Kling | Versatile photorealistic image generation with broad aspect-ratio support. |
+| GPT Image 1.5 | OpenAI | Earlier-generation OpenAI image model with editing and text-rendering capabilities. |
+| GPT Image 2 | OpenAI | **Default high-fidelity image generation.** Graphic design, UI, banners, typography, and any brief with on-image text. Used by `higgsfield-product-photoshoot` under the hood. |
+| Grok Imagine | xAI | Expressive, high-contrast, bold creative outputs. Worth trying for anime and stylized looks. |
+| Cinema Studio Image 2.5 | Higgsfield | Cinematic still frames up to 4K, dramatic film look. |
+| Marketing Studio Image | Higgsfield | **Branded image ads.** Retrieval-augmented over the user's avatars and products — runs inside the Marketing Studio flow. |
+| Auto | Higgsfield | **Smart routing layer.** Picks the best image model from the prompt automatically. Use when the user's intent is open and you don't want to commit to a specific model. |
+
+## Video models
+
+| Model | Provider | What it's for |
+|---|---|---|
+| Seedance 2.0 | Bytedance | **SOTA all-purpose video.** Crisp, consistent identity, multi-shot capable. The default for any serious motion / cinematic / production brief. |
+| Kling 3.0 | Kling | **Cheaper Seedance 2.0 substitute** for single-plane scenes that don't need heavy motion. Multi-shot, audio sync, motion transfer. |
+| Seedance 1.5 Pro | Bytedance | A budget-friendly Seedance for clean single-take shots. |
+| Marketing Studio | Higgsfield | **All advertising and commercial video** — UGC, unboxing, TV spot, product showcase. The default whenever the brief is "make an ad". See `marketing-modes.md`. |
+| Cinema Studio Video 3.0 | Higgsfield | **Top-tier cinema-grade execution.** The pick for film-look briefs at the highest fidelity. |
+| Veo 3.1 Lite | Google | **Fast and cost-effective Veo.** Built for batch and volume work. |
+| Google Veo 3.1 | Google | Ultra-realistic, top-tier cinematic quality. Quality tiers basic/high/ultra. Format set is constrained — verify accepted aspect ratio and duration before submitting. |
+| Google Veo 3 | Google | Reliable cinematic with broad creative range and audio support. |
+| Minimax Hailuo | Hailuo | **Cheap with strong physics.** Solid budget pick when natural-physics motion matters; no audio in current variants. |
+| Wan 2.7 | Wan | Synchronized audio with character-consistent video. The newer Wan release. |
+| Wan 2.6 | Wan | Open-weight, stylized, experimental creative. Cheap option when the brief is intentionally artistic. |
+| Kling 2.6 | Kling | Cinematic motion with advanced physics — earlier Kling release alongside 3.0. |
+| Grok Imagine (video) | xAI | Text and image-to-video with audio support. Worth trying for stylized creative briefs. |
+| Cinema Studio Video | Higgsfield | Cinematic compositions with dramatic mood. Use Cinema Studio Video 3.0 as the modern default. |
+| Cinema Studio Video v2 | Higgsfield | Refined cinematic camera and color with genre control. Use Cinema Studio Video 3.0 as the modern default. |
+
+---
+
+## Picking flow
+
+Practical defaults from production use. Match by intent, not surface keyword. When two could apply, the higher entry wins.
+
+### Image — pick this default
+
+1. **Brand product visual (Pinterest pin, lifestyle, hero banner, ad pack, virtual try-on, restyle)** → use `higgsfield-product-photoshoot` instead. NOT this skill.
+2. **Branded ad image with presenter avatar + product (Marketing Studio shape with RAG over user assets)** → Marketing Studio Image.
+3. **Aesthetic UGC / fashion editorial / lifestyle character** → Soul 2.0.
+4. **Cinematic still frame** → Soul Cinema.
+5. **Highly characterful, creative character (text-only, distinctive persona, no reference photo)** → Soul Cast.
+6. **Locations / environments / no-people scenes** → Soul Location. Best in class — nothing else matches.
+7. **Vector illustrations OR face edit + complex scene swap (more than outfit change, no heavy filters)** → Seedream 4.5. Seedream 5.0 Lite for the same niche but faster.
+8. **Soul Character (reference id from `higgsfield-soul-id`)** → Soul 2.0 for stills; Soul Cinema for cinematic vibe.
+9. **Anime / stylized / non-default look where defaults feel flat** → Flux Kontext Max or Grok Imagine. Worth trying.
+10. **Character or cartoon-style work** → Nano Banana 2; step up to Nano Banana Pro on hard cases.
+11. **Fast and cheap iteration / drafts / LoRA work** → Z Image.
+12. **Default for everything else** → GPT Image 2. High-fidelity general generation, graphic design, UI, banners, anything with on-image text.
+13. **Intent-only request, no preference, want auto-routing** → Auto.
+
+### Video — pick this default
+
+1. **All advertising / commercial video (UGC, unboxing, TV spot, product showcase, branded ad)** → Marketing Studio. See `marketing-modes.md`.
+2. **Default all-purpose serious video (multi-shot, consistent identity, motion-heavy, production work)** → Seedance 2.0. SOTA.
+3. **Single-plane scene without strong dynamics, cheaper** → Kling 3.0. Substitute for Seedance 2.0 when motion isn't critical.
+4. **Cheap clean shot without cuts** → Seedance 1.5 Pro.
+5. **Image-to-video with explicit first frame** → Kling 3.0 with a start frame, or Seedance 2.0 with a start frame for higher motion.
+6. **Cinema-grade execution (highest fidelity, film look)** → Cinema Studio Video 3.0.
+7. **Cheap with strong physics, audio not needed** → Minimax Hailuo.
+8. **Fast batch / volume** → Veo 3.1 Lite.
+9. **Veo-format-bound work (specific aspect / duration set Veo accepts)** → Veo 3.1; Veo 3 is slightly behind.
+10. **Stylized / animation-style edit-driven work** → Wan 2.7.
+11. **Stylized cheap experimental** → Wan 2.6.
+12. **Anime / bold-style outputs where defaults feel flat** → Grok Imagine (video). Worth trying.
+
+### Things to keep in mind
+
+- **Don't invent model names.** Run `higgsfield model list` if you're unsure — submitting an unknown model returns `unknown model "..."`.
+- **Audio reference for Seedance 2.0** comes through the media inputs with role `audio`, not via a separate `generate_audio` flag.
+- **Text-only models reject reference images.** Z Image, Soul Cast, Soul Location, and some Wan configs are text-only; pass no media flags to them.
+- **Route branded product visuals through `higgsfield-product-photoshoot`** — its prompt enhancer adds 10 mode-specific templates on top of GPT Image 2. Direct GPT Image 2 generation here is the right call for everything that isn't a product photoshoot.
+- **For cinema video, prefer Cinema Studio Video 3.0** as the modern default; reach for the earlier Cinema Studio Video variants only when the user names them.
+- **When the user names a specific model, use it.** The defaults above cover the common intents — the rest of the catalog exists for users who know what they want.
+
+---
+
+## Media role conventions
+
+Each model accepts a fixed set of media roles. When unsure, run `higgsfield model get <model>` and inspect the `medias[].roles` field.
+
+| Model | Accepted media roles |
+|---|---|
+| Seedance 2.0 | `image`, `start_image`, `end_image`, `video`, `audio` |
+| Kling 3.0 | `start_image`, `end_image` |
+| Kling 2.6 | `start_image` |
+| Veo 3.1 | `start_image` (max 1) |
+| Veo 3 | `image` (max 1) |
+| Marketing Studio (video) | `image`, `start_image`, `end_image` |
+| Most image models | `image` (1+) |
+| Z Image, Soul Cast, Soul Location | (no media — text-only) |
+
+For simple image-to-video, the `start_image` role is what you want. For pure video models that only declare `image`, the `image` flag is auto-remapped to `start_image` by the CLI.
+
+## Aspect ratios and durations
+
+These are model-specific. The CLI clamps unsupported values to the nearest allowed one (with a `Note: adjustments applied` warning) when the model declares a closed set. When in doubt:
+
+```bash
+higgsfield model get <model>
+```
+
+Common patterns:
+
+- **Seedance 2.0** image: `auto`, `21:9`, `16:9`, `4:3`, `1:1`, `3:4`, `9:16`. Duration 4–15s.
+- **Kling 3.0**: `16:9`, `9:16`, `1:1`. Duration 3–15s. Modes `pro`/`std`. Sound `on`/`off`.
+- **Soul 2.0**: `1:1`, `16:9`, `9:16`, `4:3`, `3:4`, `3:2`, `2:3`. Quality `1.5k` or `2k` maps to backend `720p`/`1080p`.
+- **Soul Cinema**: same as Soul 2.0 plus `21:9`. Quality `1.5k` or `2k`.
+- **Soul Location**: `1:1`, `4:3`, `3:4`, `16:9`, `9:16`, `3:2`, `2:3`, `21:9`, `9:21`. No quality/resolution selector; dimensions are fixed by aspect ratio.
+- **Veo 3.1**: `16:9` or `9:16`. Duration `4`, `6`, or `8` only. Quality `basic`/`high`/`ultra`.
+- **Marketing Studio (video)**: `auto`/`21:9`/`16:9`/`4:3`/`1:1`/`3:4`/`9:16`. Resolution `480p` or `720p`.
+
+## When you submit an unknown value
+
+The CLI reports two kinds of feedback:
+
+- **Adjustments** — a non-fatal coercion. E.g. you passed `aspect_ratio=99:99` and the model accepts a closed set; the CLI picks the closest match and continues. The adjustments map is included in the response.
+- **Validation error** — a fatal mismatch. E.g. an unknown declared parameter, or a media role the model doesn't accept. The CLI returns an error and does not submit.

package/resources/skills/skills/higgsfield/higgsfield-generate/references/prompt-engineering.md

@@ -0,0 +1,47 @@
+# Prompt Engineering
+
+## Basics
+
+Higgsfield models reward concrete, sensory prompts.
+
+- **Subject + setting + style**: "a red fox curled in a snowy pine forest, golden hour, cinematic"
+- **Camera**: lens (35mm, 85mm), angle (low, overhead), motion (dolly in, tracking shot)
+- **Lighting**: rim light, neon glow, moody backlight
+- **Style/medium**: oil painting, watercolor, photograph, anime, 3D render
+
+Keep it under ~200 tokens. Models distort with very long prompts.
+
+## Image-to-image
+
+When passing `--image`, the prompt should describe what changes, not redescribe the input.
+
+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"
+
+## Image-to-video
+
+`--start-image` anchors the first frame. Prompt describes motion.
+
+- Verbs: zooms in, dollies left, sweeping pan, slow push, fast whip
+- Subject motion: "the dancer spins", "smoke rises slowly"
+- Don't redescribe the static frame — model already has it.
+
+## Negative phrasing
+
+Most models don't expose a `negative_prompt`. Phrase positively:
+- Instead of "no blur" → "tack sharp"
+- Instead of "no people" → "uninhabited landscape"
+
+## Aspect ratio guidance
+
+- `16:9` — landscape, cinematic
+- `9:16` — vertical, social
+- `1:1` — square, profile / icon
+- `4:3`, `3:4`, `21:9` — model-dependent, check `higgsfield model get <jst>`
+
+## Safety
+
+Models reject prompts with `nsfw` or `ip_detected` terminal status. Avoid:
+- Real public figures
+- Sexual content
+- Trademarks / branded characters

package/resources/skills/skills/higgsfield/higgsfield-generate/references/troubleshooting.md

@@ -0,0 +1,31 @@
+# Troubleshooting
+
+## Authentication
+
+- `Session expired.` → `higgsfield auth login`
+- `Stored credentials are for ... but current environment ...` → `higgsfield auth login` for the current API URL.
+- `Not authenticated.` → first `higgsfield auth login`.
+
+## Validation
+
+- `Missing required params: prompt` — user gave no prompt. Ask.
+- `Invalid values: <param>=<v> (allowed: ...)` — pick from allowed enum.
+- `Unknown params: <name>` — schema doesn't accept this flag. Run `higgsfield model get <jst>` and check.
+
+## Job lifecycle
+
+- `Job ended with status "failed"` — server-side failure. Often prompt content / safety. Try rephrasing.
+- `nsfw` / `ip_detected` — content policy. Rephrase.
+- `Timeout after 10m` — model is slow today. Bump `--timeout 30m` or retry.
+
+## Rate limits
+
+`Higgsfield API error (HTTP 429)` — too many requests. Back off.
+
+## CloudFlare / DataDome
+
+If `Failed to decode response. Body: <html>...captcha-delivery...` appears, the server's anti-bot fired. Wait 30s and retry. If persistent, ping the team.
+
+## Cost
+
+`higgsfield generate cost <jst> ...` returns credit estimate without submitting. Useful when the user asks "how much will this cost?".

package/resources/skills/skills/higgsfield/higgsfield-marketplace-cards/SKILL.md

@@ -0,0 +1,79 @@
+---
+version: 0.3.0
+name: higgsfield-marketplace-cards
+description: >-
+  Use when user asks for "marketplace listing images", "product detail cards", "A+ content", or "Amazon/Shopee/eBay images". Compliant main + secondary + A+ modules. NOT for brand photography.
+argument-hint: "[--scope main|product-images|aplus|full-set] [prompt]"
+allowed-tools: Bash
+---
+
+# Marketplace Cards
+
+Create marketplace-ready product visuals with `higgsfield marketplace-cards create`.
+The CLI first calls the backend enhancer, where marketplace rules and templates are kept private, then creates `nano_banana_2` jobs and prints result URLs.
+
+## Bootstrap
+
+1. If `higgsfield` is not on `$PATH`, install it by running the official installer with Bash: `curl -fsSL https://raw.githubusercontent.com/higgsfield-ai/cli/main/install.sh | sh`.
+2. If `higgsfield account status` fails with authentication errors, ask the user to run `higgsfield auth login`.
+
+## UX Rules
+
+1. Respond in the user's language.
+2. Ask at most one concise confirmation question before running.
+3. Prefer a product image. If the user provides only text or a URL, proceed only when the product details are clear.
+4. Do not write final image-generation prompts yourself. Backend enhancement owns that.
+5. Final answer should contain only the ready image URLs and short labels.
+
+## Scope Selection
+
+Use `--scope` when the user asks for a common bundle:
+
+| Scope | Creates |
+|---|---|
+| `main` | 1 marketplace main image |
+| `product-images` | main image + 5 secondary images |
+| `aplus` | main image + 7 A+ modules |
+| `full-set` | main image + 5 secondary images + 7 A+ modules |
+
+Use repeated `--asset` only for custom subsets:
+
+- `main_image`
+- `infographic`
+- `multi_angle`
+- `detail_shot`
+- `lifestyle`
+- `whats_in_box`
+- `aplus_hero_banner`
+- `aplus_pain_points`
+- `aplus_features`
+- `aplus_ingredients`
+- `aplus_efficacy`
+- `aplus_how_to_use`
+- `aplus_endorsement`
+
+## Command
+
+Build and run one `higgsfield marketplace-cards create` command from the user's request.
+
+For common bundles, use `--scope <main|product-images|aplus|full-set>`, `--prompt "<short product and listing intent>"`, optional repeated `--image <path-or-upload-id>`, and optional context flags: `--product_context`, `--brand_context`, `--category`, `--visual_style`.
+
+Examples to mirror when choosing arguments:
+
+- Product images: `higgsfield marketplace-cards create --scope product-images --prompt "sparkling peach lemonade can for marketplace listing" --image ./can.png --category "beverage"`
+- Full set: `higgsfield marketplace-cards create --scope full-set --prompt "premium skincare serum, clean clinical marketplace visual system" --image ./serum.jpg --brand_context "minimal white and sage palette"`
+- Custom subset: repeat `--asset`, for example `--asset main_image --asset infographic --asset lifestyle`.
+- Existing completed main image job: use `--main-job <completed_main_job_id>` with the requested secondary or A+ `--asset` values.
+
+## Delivery
+
+Print URLs with labels:
+
+```text
+Marketplace cards ready:
+- Main image: https://...
+- Infographic: https://...
+- Lifestyle: https://...
+```
+
+Avoid JSON, job IDs, internal model names, or enhanced prompt text unless the user explicitly asks.

package/resources/skills/skills/higgsfield/higgsfield-product-photoshoot/SKILL.md

@@ -0,0 +1,200 @@
+---
+version: 0.3.0
+name: higgsfield-product-photoshoot
+description: >-
+  Use when user says "product photo", "studio shot", "lifestyle image", "hero banner", or "virtual try-on". Backend-enhanced prompts on GPT Image 2. NOT for marketplace cards or generic image-gen.
+argument-hint: "[--mode <mode>] [--count N] [prompt]"
+allowed-tools: Bash
+---
+
+# Product Photoshoot
+
+Brand-image generation via the `higgsfield product-photoshoot create` command. The CLI calls a backend prompt enhancer that holds mode-specific photography vocabulary and structural templates, then submits to `gpt_image_2` and returns image URLs.
+
+## Step 0 — Bootstrap
+
+Before any other command:
+
+1. If `higgsfield` is not on `$PATH`, install it:
+   ```bash
+   curl -fsSL https://raw.githubusercontent.com/higgsfield-ai/cli/main/install.sh | sh
+   ```
+2. If `higgsfield account status` fails with `Session expired` / `Not authenticated`, ask the user to run `higgsfield auth login` (interactive) and wait for confirmation.
+
+## UX Rules
+
+1. Be concise. Print only image URLs in the final reply.
+2. Detect language, respond in it. Mode names and CLI flags stay English.
+3. Ask at most 4 short questions before submitting. Use labeled options, never open-ended.
+4. Skip questions whose answer is obvious from context (uploaded image, prior turn, brand memory).
+5. Never write the gpt_image_2 prompt yourself — backend assembles it.
+6. Polling is silent. Wait until URLs are ready, then deliver.
+
+## Modes
+
+| Mode | When user wants… |
+|---|---|
+| `product_shot` | Product on neutral / studio / catalog background |
+| `lifestyle_scene` | Product in real-world environment, hands, action, atmosphere |
+| `closeup_product_with_person` | Tight crop with hands / partial face — beauty application, holding, demonstrating |
+| `moodboard_pin` | Vertical 2:3 Pinterest-native aesthetic, moodboard feel |
+| `hero_banner` | Wide-format website / email / campaign header |
+| `social_carousel` | 3–10 connected slides for IG / LinkedIn / Facebook |
+| `ad_creative_pack` | Coordinated pack of static ad variants for Meta / TikTok / Pinterest / Google Ads |
+| `virtual_model_tryout` | Product worn or used by an AI-rendered model |
+| `conceptual_product` | Surreal / CGI-style / levitating / splash / sculptural product |
+| `restyle` | Transform an existing image's aesthetic, mood, or seasonal context |
+
+## Mode selection
+
+Pick by intent, not surface keyword. When two modes could apply, prefer the more specific one.
+
+- product + neutral / clean / white / studio / catalog / Shopify → `product_shot`
+- product + scene / in use / kitchen / outdoor / cafe / gym → `lifestyle_scene`
+- hands holding / face with product / beauty application / demonstrating → `closeup_product_with_person`
+- Pinterest, pin, vertical pin → `moodboard_pin`
+- hero, banner, website header, landing page, email header, wide format → `hero_banner`
+- carousel, slide post, multi-slide, swipeable → `social_carousel`
+- ads, ad pack, paid social, Meta / TikTok / Pinterest ads → `ad_creative_pack`
+- model wearing, virtual try-on, on body, fashion shoot, lookbook → `virtual_model_tryout`
+- levitating, floating, splash, frozen motion, surreal, CGI, sculptural → `conceptual_product`
+- modify EXISTING image's aesthetic, mood, season — without changing subject → `restyle`
+
+Tie-breakers:
+- "Pinterest pin of my product on a kitchen counter" → `moodboard_pin` (Pinterest is the platform)
+- "Hero banner showing my product in use" → `hero_banner` (banner format wins)
+- "Carousel of my product in different scenes" → `social_carousel` (multi-slide wins)
+- "Closeup of person applying my serum" → `closeup_product_with_person` (specific genre wins)
+
+## Pre-generation interview
+
+Ask 3–4 short questions before submitting. Always labeled options, never open-ended. Skip a question whose answer is obvious from context.
+
+### Type A — uploaded a product photo, "make me images / photoshoots"
+
+1. How many? `[1 / 3 / 5]`
+2. What style/mood? `[Clean studio / Lifestyle / Conceptual / With a model / Other]`
+3. Where will you use them? `[Shopify / Instagram / Pinterest / Paid ads / Website hero]`
+4. Brand colors to match? (skip if obvious)
+
+### Type B — uploaded a product photo, named a use case
+
+E.g. "make ads for my product", "make a Pinterest pin", "make a hero banner". Mode is obvious. Ask only the gaps:
+
+1. How many? (if multi-output mode)
+2. What's the offer / mood / hook?
+3. Anything in particular to emphasize?
+
+### Type C — text only, no product photo
+
+1. Can you upload a product photo? (preferred — much higher fidelity)
+2. If not, describe the product — category, packaging, color, distinctive features.
+3. What style? (same options as Type A)
+4. Where will you use it?
+
+### Type D — uploaded existing image, "redo / change vibe / different version"
+
+→ `restyle`
+
+1. What aesthetic? `[Clean girl / Cottagecore / Quiet luxury / Dark academia / Y2K / Other]`
+2. Seasonal context? `[Christmas / Valentine's / Halloween / Black Friday / None]`
+3. What to preserve, what to change? (only if ambiguous)
+
+### Type E — model wearing a product (fashion, accessories)
+
+→ `virtual_model_tryout`
+
+1. Model archetype? (suggest 2–3 based on brand audience)
+2. Environment? `[Studio clean / Outdoor natural / Street style / Editorial / Home cozy]`
+3. Framing? `[Full body / Three-quarter / Waist up / Closeup on product area]`
+
+### Type F — vague request, unclear subject
+
+E.g. "make me something cool for my brand".
+
+1. What product or topic?
+2. Goal? `[Sell on a marketplace / Build awareness / Run paid ads / Update website]`
+3. Upload a reference image?
+
+After answers → return to the relevant Type A–E.
+
+## Generation
+
+Single command. Backend assembles the final prompt and submits to `gpt_image_2`. URLs print on stdout.
+
+```bash
+higgsfield product-photoshoot create \
+  --mode <mode> \
+  --prompt "<short user-intent description from interview answers>" \
+  [--image <path-or-upload-id>]... \
+  [--count <1-10>] \
+  [--aspect_ratio <override>]
+```
+
+Examples:
+
+```bash
+higgsfield product-photoshoot create \
+  --mode lifestyle_scene \
+  --prompt "bottle of cold-brew on a sunlit kitchen counter, IG feed" \
+  --image bottle.jpg \
+  --count 3
+```
+
+```bash
+higgsfield product-photoshoot create \
+  --mode moodboard_pin \
+  --prompt "vertical pin for my candle brand, cottagecore mood" \
+  --image candle.jpg
+```
+
+```bash
+higgsfield product-photoshoot create \
+  --mode restyle \
+  --prompt "Christmas version, quiet-luxury aesthetic" \
+  --image existing-shot.jpg
+```
+
+## Image inputs
+
+`--image` accepts a local file path (auto-uploaded) OR an existing upload UUID. Repeat the flag for multiple references.
+
+## Multi-variant
+
+`--count 3` returns 3 distinct image URLs. Backend asks the enhancer to vary preset, lighting, angle, and palette across variants — they will not be paraphrased copies of one another.
+
+For `social_carousel` and `ad_creative_pack`, count = number of slides / variants in the pack. Backend locks the visual system across all slides automatically.
+
+## Aspect ratio
+
+Backend picks a sensible default per mode. Override with `--aspect_ratio` only if the user explicitly asks for a different one. Allowed values: `1:1`, `4:5`, `5:4`, `3:4`, `4:3`, `2:3`, `3:2`, `9:16`, `16:9`.
+
+## Resolution
+
+Use `2k` for every product-photoshoot job.
+
+## Delivering results
+
+Print the image URLs as a short bulleted list. No JSON, no IDs, no internal model names, no enhanced prompt text. If a job failed, mention it briefly with the failure status.
+
+```
+3 lifestyle shots ready:
+- https://cdn.higgsfield.ai/.../job_abc.jpg
+- https://cdn.higgsfield.ai/.../job_def.jpg
+- https://cdn.higgsfield.ai/.../job_ghi.jpg
+```
+
+## What this skill does NOT do
+
+- Does not write gpt_image_2 prompts directly. Backend owns prompt assembly.
+- Does not auto-pick a different image-gen model. Always `gpt_image_2`.
+- Does not replace `higgsfield-generate` Marketing Studio for branded video / avatar workflows.
+- Does not replace `higgsfield-generate` for raw text-to-image without a product or brand context.
+
+## Common mistakes to avoid
+
+- Asking more than 4 interview questions in a single message.
+- Picking the wrong mode (e.g. `product_shot` when the user wants a Pinterest pin).
+- Calling `higgsfield generate create gpt_image_2 --prompt ...` directly instead of `higgsfield product-photoshoot create` — bypasses the prompt enhancer and produces noticeably worse output.
+- Pasting the assembled prompt back to the user — they want the URLs.
+- Using a `--mode` value not in the table above.

package/resources/skills/skills/higgsfield/higgsfield-soul-id/SKILL.md

@@ -0,0 +1,74 @@
+---
+version: 0.3.0
+name: higgsfield-soul-id
+description: >-
+  Use when user says "train my face", "create my Soul", "digital twin", or "build my avatar". One-time Soul Character training; returns reference_id for higgsfield-generate. NOT for one-shot face swaps.
+argument-hint: "[name] [photo paths...]"
+allowed-tools: Bash
+---
+
+# Higgsfield Soul Character
+
+Train a face-faithful identity model. Reusable across all Soul-powered generations.
+
+## Step 0 — Bootstrap
+
+Before any other command:
+
+1. If `higgsfield` is not on `$PATH`, install it:
+   ```bash
+   curl -fsSL https://raw.githubusercontent.com/higgsfield-ai/cli/main/install.sh | sh
+   ```
+2. If `higgsfield account status` fails with `Session expired` / `Not authenticated`, ask the user to run `higgsfield auth login` (interactive) and wait for confirmation.
+3. Soul training requires a paid plan (Basic+). If `higgsfield account status` shows free plan, tell the user before submitting.
+
+## UX Rules
+
+1. Be concise. No raw IDs in chat. Just say "Soul ready" with a name reference.
+2. Detect language and respond in it. CLI flags stay English.
+3. Ask for the smallest set of inputs: name + photos. Pick a sensible model variant.
+4. Polling is silent — training takes minutes. Don't repeat status updates.
+
+## Workflow
+
+1. **Get name.** One word, used for later reference. Ask if missing.
+2. **Get photos.** 5–20 face photos, varied angles and lighting. Local paths or already-uploaded IDs both work — `--image` accepts either.
+3. **Pick variant.**
+   - `--soul-2` — for image generation (default)
+   - `--soul-cinematic` — for cinematic / video work
+   Choose based on user's stated downstream use. Default to `--soul-2`.
+4. **Submit.**
+   ```bash
+   higgsfield soul-id create --name "<name>" --soul-2 --image ./photo1.png --image ./photo2.png ...
+   higgsfield soul-id create --name "<name>" --soul-2 --image <upload_id> --image <upload_id> ...
+   ```
+   CLI auto-uploads paths. Captures returned reference id.
+5. **Wait.** `higgsfield soul-id wait <id>`. Silent. Default timeout 30m.
+6. **Deliver.** "Soul `<name>` ready. Use in generate with `--soul-id <id>`."
+
+## Use the Soul
+
+Once trained, pass to `higgsfield-generate`:
+
+```bash
+higgsfield generate create text2image_soul_v2 --prompt "..." --soul-id <ref_id> --quality 2k --wait
+higgsfield generate create soul_cinematic --prompt "..." --soul-id <ref_id> --quality 2k --wait
+```
+
+## Listing existing Souls
+
+```bash
+higgsfield soul-id list                   # all references
+higgsfield soul-id get <id>               # one by id
+```
+
+## Errors
+
+- `Minimum Basic plan required` — user is on free plan; tell them.
+- `Training failed` — check photos quality (5+ unique faces, well-lit).
+- `Session expired` → `higgsfield auth login`.
+
+## Reference docs
+
+- `references/photo-guide.md` — what photos work best
+- `references/troubleshooting.md` — common training failures

package/resources/skills/skills/higgsfield/higgsfield-soul-id/references/photo-guide.md

@@ -0,0 +1,37 @@
+# Photo Guide
+
+What to upload for Soul training.
+
+## Quantity
+
+- Minimum 5, maximum 20.
+- 8–12 is the sweet spot.
+
+## Content
+
+- Clear face, eyes visible.
+- Single person per photo.
+- No heavy filters, no sunglasses.
+
+## Variety
+
+Higher variety = better identity capture.
+
+- Multiple angles: front, 3/4 left, 3/4 right, slight up/down.
+- Different lighting: indoor, outdoor, soft, harsh.
+- Different expressions: neutral, smiling, talking.
+- Different distances: head shot, head-and-shoulders, full body.
+
+## Quality
+
+- Sharp, in-focus.
+- Resolution ≥ 1024×1024 ideal.
+- JPEG or PNG.
+
+## Avoid
+
+- Group photos.
+- Heavy makeup not normally worn.
+- Costumes / cosplay.
+- Hats covering the face.
+- Same pose repeated.

package/resources/skills/skills/higgsfield/higgsfield-soul-id/references/troubleshooting.md

@@ -0,0 +1,24 @@
+# Soul Troubleshooting
+
+## `Minimum Basic plan required`
+
+Soul training needs a paid plan. Tell the user to upgrade.
+
+## `Training failed`
+
+Common causes:
+
+- Too few photos (<5) or too uniform.
+- Heavy occlusion (sunglasses, hats).
+- Group photos confusing identity.
+- Upload type mismatch (must be image uploads, not video).
+
+Action: ask user to swap in better photos, retrain.
+
+## `Session expired`
+
+`higgsfield auth login`.
+
+## Slow training
+
+Default timeout is 30m. If still in progress: `higgsfield soul-id wait <id> --timeout 60m`.