@aksp/opencrew 1.0.0

package/templates/skills/image-ai-generator/SKILL.md

@@ -0,0 +1,124 @@
+---
+name: image-ai-generator
+description: >
+  Generates images via Openrouter API using AI image models.
+  Supports two modes: test (cheap model for iteration) and production (high-quality model for final output).
+  Handles prompt construction, API calls, base64 decoding, and file saving.
+  Supports reference images (logos, mascots) for brand-consistent generation.
+description_pt-BR: >
+  Gera imagens via API do Openrouter usando modelos de IA.
+  Suporta dois modos: test (modelo barato para iteração) e production (modelo de alta qualidade para output final).
+  Cuida da construção de prompts, chamadas de API, decodificação base64 e salvamento de arquivos.
+  Suporta imagens de referência (logos, mascotes) para geração consistente com a marca.
+type: script
+version: "1.0.0"
+script:
+  path: scripts/generate.py
+  runtime: python3
+  invoke: "python3 {skill_path}/scripts/generate.py --prompt \"{prompt}\" --output \"{output}\" --mode \"{mode}\""
+env:
+  - OPENROUTER_API_KEY
+categories: [assets, images, ai, generation]
+---
+
+# Image Generator
+
+## When to use
+
+Use the Image Generator when you need to create visual assets from text prompts. This skill calls the Openrouter API with AI image generation models and saves the resulting images locally.
+
+**IMPORTANT: Think twice before generating images.** Image generation costs money and takes time. Before generating:
+1. Check if a suitable image already exists in the crew's assets folder
+2. Check if a web search could find a free/open image that works
+3. Consider if the image is truly necessary for the content quality
+4. Only generate when no existing alternative is good enough
+5. **Generate only what you need** — never batch-generate "test variations". One image is enough to validate a concept.
+
+## Modes
+
+### Test mode (`--mode test`)
+- **Model:** `sourceful/riverflow-v2-fast`
+- **When to use:** During iteration, testing layouts, checking composition, reviewing concepts
+- **Cost:** ~R$0.01-0.02 per image (very low)
+- **Quality:** Good enough for layout validation, not for final output
+
+### Production mode (`--mode production`)
+- **Model:** `google/gemini-3.1-flash-image-preview`
+- **When to use:** Only when generating the final images that will be published or delivered
+- **Cost:** ~R$0.07-0.10 per image
+- **Quality:** High quality, suitable for social media and publishing
+
+**Default mode is `test`.** Only switch to `production` when the user has approved the layout/composition and you are generating the final deliverable images.
+
+## Instructions
+
+### Single image generation
+
+```bash
+python3 skills/image-generator/scripts/generate.py \
+  --prompt "A detailed description of the image to generate" \
+  --output "crews/{crew}/output/{run_id}/assets/image-name.jpg" \
+  --mode test
+```
+
+### With a reference image (logo, mascot, brand asset)
+
+Use `--reference` to send a local image to the model as visual context. The model will incorporate the referenced image (e.g., a logo or mascot) into the generated output.
+
+```bash
+python3 skills/image-generator/scripts/generate.py \
+  --prompt "A social media banner featuring the company logo prominently in the center" \
+  --output "crews/{crew}/output/{run_id}/assets/banner.jpg" \
+  --reference "crews/{crew}/assets/logo.png" \
+  --mode production
+```
+
+Supported reference formats: PNG, JPEG, WEBP, GIF.
+
+### Batch generation
+
+```bash
+python3 skills/image-generator/scripts/generate.py \
+  --batch "crews/{crew}/output/{run_id}/assets/batch.json" \
+  --mode production
+```
+
+The batch JSON file should contain:
+```json
+[
+  {"prompt": "Description of image 1", "output": "path/to/image1.jpg"},
+  {"prompt": "Description of image 2", "output": "path/to/image2.jpg"}
+]
+```
+
+Each item can optionally include a `"reference": "path/to/ref.png"` field.
+
+### Prompt guidelines
+
+- Be specific about composition, lighting, style, and mood
+- Specify aspect ratio or orientation when relevant (e.g., "portrait 3:4", "landscape 16:9")
+- Include "hyper realistic, 4K quality" for photographic styles
+- Include "clean composition" to avoid cluttered outputs
+- Avoid requesting text in images — AI models struggle with text rendering
+
+### Cost awareness
+
+- Each production image costs approximately R$0.07-0.10
+- Each test image costs approximately R$0.01-0.02
+- A typical carousel with 8 images costs ~R$0.60-0.80 in production mode
+- **Always use test mode first**, then regenerate only the approved concepts in production mode
+- When testing, generate **1 image only** — not 3, not 5, just 1
+
+## Available operations
+
+- **Single generation** — Generate one image from a text prompt
+- **Batch generation** — Generate multiple images from a JSON batch file
+- **Mode selection** — Choose between test (cheap) and production (high-quality) models
+- **Reference image** — Send a logo/mascot/brand asset as visual context for the generation
+
+## Error handling
+
+- If `OPENROUTER_API_KEY` is not set, the script exits with an error message. Set it in your `.env` file or environment.
+- If the API returns an error, the script prints the error code and body, then exits with code 1.
+- If no image is found in the API response, the script reports which model was used and exits with code 1.
+- For batch mode, partial failures are reported with a success count summary.

package/templates/skills/image-ai-generator/scripts/generate.py

@@ -0,0 +1,175 @@
+#!/usr/bin/env python3
+"""
+Image Generator — opencrew Skill
+Generates images via Openrouter API using AI image models.
+
+Usage:
+  # Single image
+  python3 generate.py --prompt "description" --output "path/to/image.jpg" --mode test
+
+  # Single image with reference (logo/mascot)
+  python3 generate.py --prompt "description" --output "path/to/image.jpg" --reference "path/to/logo.png" --mode production
+
+  # Batch (JSON file with list of {prompt, output} objects)
+  python3 generate.py --batch "path/to/batch.json" --mode production
+"""
+
+import argparse
+import base64
+import json
+import os
+import sys
+import time
+import urllib.request
+import urllib.error
+
+# Model configuration per mode
+MODELS = {
+    "test": "sourceful/riverflow-v2-fast",
+    "production": "google/gemini-3.1-flash-image-preview",
+}
+
+API_URL = "https://openrouter.ai/api/v1/chat/completions"
+
+
+def load_api_key():
+    """Load OPENROUTER_API_KEY from environment."""
+    key = os.environ.get("OPENROUTER_API_KEY")
+    if not key:
+        # Try loading from .env in project root
+        env_candidates = [
+            os.path.join(os.getcwd(), ".env"),
+            os.path.join(os.path.dirname(__file__), "..", "..", "..", ".env"),
+        ]
+        for env_path in env_candidates:
+            env_path = os.path.abspath(env_path)
+            if os.path.exists(env_path):
+                with open(env_path, "r") as f:
+                    for line in f:
+                        line = line.strip()
+                        if line.startswith("OPENROUTER_API_KEY=") and not line.startswith("#"):
+                            key = line.split("=", 1)[1].strip().strip('"').strip("'")
+                            break
+                if key:
+                    break
+    if not key:
+        print("ERROR: OPENROUTER_API_KEY not found in environment or .env file", file=sys.stderr)
+        sys.exit(1)
+    return key
+
+
+def generate_image(prompt, output_path, mode, api_key, reference_image=None):
+    """Generate a single image and save to output_path."""
+    model = MODELS.get(mode, MODELS["test"])
+
+    os.makedirs(os.path.dirname(os.path.abspath(output_path)), exist_ok=True)
+
+    if reference_image and os.path.exists(reference_image):
+        # Multimodal: send reference image + text prompt
+        ext = os.path.splitext(reference_image)[1].lower()
+        mime_map = {".png": "image/png", ".jpg": "image/jpeg", ".jpeg": "image/jpeg", ".webp": "image/webp", ".gif": "image/gif"}
+        mime = mime_map.get(ext, "image/png")
+        with open(reference_image, "rb") as img_f:
+            img_b64 = base64.b64encode(img_f.read()).decode("utf-8")
+        content = [
+            {"type": "image_url", "image_url": {"url": f"data:{mime};base64,{img_b64}"}},
+            {"type": "text", "text": f"Generate an image using the logo/mascot shown in the reference image above. {prompt}. Only output the image, no text."}
+        ]
+    else:
+        content = f"Generate an image: {prompt}. Only output the image, no text."
+
+    payload = json.dumps({
+        "model": model,
+        "messages": [{
+            "role": "user",
+            "content": content
+        }]
+    }).encode("utf-8")
+
+    req = urllib.request.Request(
+        API_URL,
+        data=payload,
+        headers={
+            "Authorization": f"Bearer {api_key}",
+            "Content-Type": "application/json",
+        },
+    )
+
+    try:
+        with urllib.request.urlopen(req, timeout=120) as resp:
+            data = json.loads(resp.read().decode("utf-8"))
+    except urllib.error.HTTPError as e:
+        error_body = e.read().decode("utf-8", errors="replace")
+        print(f"  API error [{e.code}]: {error_body[:200]}", file=sys.stderr)
+        return False
+    except Exception as e:
+        print(f"  Request error: {e}", file=sys.stderr)
+        return False
+
+    images = data.get("choices", [{}])[0].get("message", {}).get("images", [])
+    if not images:
+        # Some models return image in content as base64
+        content_resp = data.get("choices", [{}])[0].get("message", {}).get("content", "")
+        if content_resp and isinstance(content_resp, str) and content_resp.startswith("data:image"):
+            img_data = content_resp.split(",", 1)[1] if "," in content_resp else content_resp
+        else:
+            print(f"  No image returned by model {model}", file=sys.stderr)
+            return False
+    else:
+        img_data = images[0].get("image_url", {}).get("url", "")
+        if img_data.startswith("data:"):
+            img_data = img_data.split(",", 1)[1]
+
+    with open(output_path, "wb") as f:
+        f.write(base64.b64decode(img_data))
+
+    size_kb = os.path.getsize(output_path) / 1024
+    print(f"  OK: {output_path} ({size_kb:.0f} KB)")
+    return True
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Generate images via Openrouter API")
+    parser.add_argument("--prompt", help="Text prompt for single image generation")
+    parser.add_argument("--output", help="Output file path for single image")
+    parser.add_argument("--batch", help="Path to JSON batch file")
+    parser.add_argument("--mode", choices=["test", "production"], default="test",
+                        help="Generation mode: test (cheap) or production (high-quality)")
+    parser.add_argument("--reference", help="Path to reference image to include in the prompt")
+    args = parser.parse_args()
+
+    if not args.prompt and not args.batch:
+        parser.error("Either --prompt or --batch is required")
+
+    api_key = load_api_key()
+    model = MODELS[args.mode]
+    print(f"Image Generator — Mode: {args.mode} | Model: {model}")
+
+    if args.batch:
+        # Batch mode
+        with open(args.batch, "r") as f:
+            items = json.load(f)
+        print(f"Generating {len(items)} images...\n")
+        success = 0
+        for i, item in enumerate(items, 1):
+            prompt = item["prompt"]
+            output = item["output"]
+            ref = item.get("reference")
+            print(f"[{i}/{len(items)}] {os.path.basename(output)}...")
+            if generate_image(prompt, output, args.mode, api_key, reference_image=ref):
+                success += 1
+            if i < len(items):
+                time.sleep(1)  # Rate limiting
+        print(f"\nDone: {success}/{len(items)} images generated.")
+        sys.exit(0 if success == len(items) else 1)
+    else:
+        # Single mode
+        if not args.output:
+            parser.error("--output is required for single image generation")
+        print(f"Generating: {os.path.basename(args.output)}...")
+        ok = generate_image(args.prompt, args.output, args.mode, api_key, reference_image=args.reference)
+        sys.exit(0 if ok else 1)
+
+
+if __name__ == "__main__":
+    main()

package/templates/skills/image-creator/SKILL.md

@@ -0,0 +1,155 @@
+---
+name: image-creator
+description: >
+  Renders HTML/CSS into production-ready images via Playwright.
+  Accepts complete HTML content, opens it in a headless browser at
+  the specified viewport, and captures a pixel-perfect screenshot.
+  Generic engine -- any visual format is defined by the HTML template.
+description_pt-BR: >
+  Renderiza HTML/CSS em imagens prontas para produção via Playwright.
+  Aceita conteúdo HTML completo, abre em um navegador headless na
+  viewport especificada e captura uma screenshot pixel-perfect.
+  Motor genérico -- qualquer formato visual é definido pelo template HTML.
+description_es: >
+  Renderiza HTML/CSS en imágenes listas para producción vía Playwright.
+  Acepta contenido HTML completo, lo abre en un navegador headless en
+  el viewport especificado y captura una screenshot pixel-perfect.
+  Motor genérico -- cualquier formato visual se define por el template HTML.
+type: mcp
+version: "1.0.0"
+mcp:
+  server_name: playwright
+categories: [design, automation, images]
+---
+
+# Image Creator
+
+## When to use
+
+Use the Visual Renderer when you need to generate production-ready images from HTML/CSS. This skill uses Playwright to render complete, self-contained HTML files in a headless browser and capture pixel-perfect screenshots. It is the primary engine for creating social media graphics, carousel slides, infographics, and any other visual content defined by HTML templates.
+
+## Instructions
+
+### Core Workflow
+
+1. **Generate HTML** -- Write a complete, self-contained HTML file with inline CSS. The HTML IS the design -- all styling, layout, fonts, colors, and content must be embedded.
+
+2. **Save HTML** -- Write the HTML file to the crew's output folder (e.g., `output/slides/slide-01.html`)
+
+3. **Start HTTP server** -- Before rendering, start a local HTTP server in the crew's output folder:
+   ```bash
+   python -m http.server 8765 --directory "OUTPUT_DIR" &
+   for i in $(seq 1 30); do curl -s http://localhost:8765 > /dev/null 2>&1 && break || sleep 0.1; done
+   ```
+   Replace OUTPUT_DIR with the actual absolute path to the output folder (quote paths that contain spaces).
+
+4. **Render** -- Use Playwright to:
+   - `browser_navigate` to `http://localhost:8765/slide-01.html` (filename only, not full path)
+   - `browser_resize` to target viewport dimensions
+   - `browser_take_screenshot` to save as PNG
+
+5. **Verify** -- Read the screenshot to confirm quality. Re-render if needed.
+
+6. **Stop server** -- After all slides are rendered, stop the HTTP server:
+   ```bash
+   pkill -f "http.server 8765" 2>/dev/null || true
+   ```
+
+### Viewport Presets (width x height)
+
+Use these standard dimensions:
+- Instagram Post: 1080 x 1080
+- Instagram Carousel: 1080 x 1440
+- Instagram Story/Reel: 1080 x 1920
+- Facebook Post: 1200 x 630
+- Twitter/X Post: 1200 x 675
+- LinkedIn Post: 1200 x 627
+- YouTube Thumbnail: 1280 x 720
+- Custom: as specified by the crew
+
+### HTML Template Guidelines
+
+The HTML you generate MUST:
+- Be self-contained (inline CSS, no external dependencies)
+- Use web-safe fonts OR Google Fonts via `@import`
+- Embed images as absolute paths or base64 data URIs
+- Set exact body dimensions matching the viewport
+- Use `margin: 0; padding: 0; overflow: hidden` on body
+- Account for device pixel ratio if high-res needed
+
+Example minimal structure:
+```html
+<!DOCTYPE html>
+<html>
+<head>
+  <meta charset="UTF-8">
+  <style>
+    * { margin: 0; padding: 0; box-sizing: border-box; }
+    body { width: 1080px; height: 1440px; overflow: hidden; }
+    /* ... your design ... */
+  </style>
+</head>
+<body>
+  <!-- Your content -->
+</body>
+</html>
+```
+
+### Batch Rendering (Carousels/Multi-slide)
+
+For multi-image outputs like carousels:
+1. Generate one HTML file per slide
+2. Start the HTTP server **once** before the batch (step 3 of Core Workflow)
+3. Render each slide sequentially (step 4 repeated per slide)
+4. Stop the HTTP server **once** after all slides are done (step 6 of Core Workflow)
+5. Name output files with zero-padded numbers: slide-01.png, slide-02.png, slide-03.png
+6. Keep all slides at the same viewport dimensions
+
+### Best Practices
+
+- Always verify the first rendered image before batch rendering
+- Use CSS Grid/Flexbox for layout -- most reliable across renderers
+- Avoid animations/transitions (static screenshot only)
+- For rounded corners on images, use CSS `border-radius` + `overflow`
+- For emoji rendering, rely on system fonts (Windows: Segoe UI Emoji)
+- Test text overflow -- ensure no content is clipped unexpectedly
+- Keep HTML files alongside output PNGs for easy re-rendering
+
+### Typography & Readability Rules
+
+Text must be legible in the target platform's smallest viewing context (mobile feed for social platforms). Text inside linked or embedded image files (JPG, PNG, base64 assets) is decorative and exempt. All HTML text nodes and inline SVG text are subject to these rules.
+
+These are HARD minimums -- never go below them for readable text.
+
+#### Minimum Font Sizes by Platform
+
+| Text Role        | Instagram Post/Carousel | Instagram Story/Reel | LinkedIn/Facebook | YouTube Thumb |
+|------------------|------------------------|----------------------|-------------------|---------------|
+| Hero / Display   | 58px                   | 56px                 | 40px              | 60px          |
+| Heading          | 43px                   | 42px                 | 32px              | 36px          |
+| Body / Bullets   | 34px                   | 32px                 | 24px              | 36px          |
+| Caption / Footer | 24px                   | 20px                 | 20px              | 32px          |
+
+**Universal rule**: No text element meant to be read may use a font size smaller than 20px, on any platform.
+
+#### Font Weight
+
+- Body text and above: use font-weight 500+ (medium/semibold/bold)
+- Caption text: font-weight 500+ strongly recommended; 400 only with explicit high-contrast background (4.5:1 ratio minimum)
+- Avoid thin/light weights (100-300) for any readable text
+
+#### Verification Checklist
+
+Before calling `browser_take_screenshot`, scan your HTML and confirm:
+- All text elements use explicit px sizes (not em/rem that could resolve smaller)
+- No heading is below the Heading minimum for the target platform
+- No body/bullet text is below the Body minimum
+- No footer or metadata text is below the Caption minimum
+- No readable text uses font-weight below 500 (caption at 400 only with 4.5:1 contrast background)
+
+## Available operations
+
+- **Render HTML to PNG** -- Convert self-contained HTML/CSS into a pixel-perfect screenshot
+- **Batch Render** -- Render multiple slides/pages sequentially for carousels and multi-image content
+- **Viewport Resize** -- Set precise viewport dimensions for any target platform
+- **Quality Verification** -- Visually inspect rendered output and re-render if needed

package/templates/skills/image-fetcher/SKILL.md

@@ -0,0 +1,91 @@
+---
+name: image-fetcher
+description: >
+  Acquires visual assets from multiple sources: web image search,
+  live website screenshots via Playwright, and user-provided files.
+  Organizes assets in the crew's reference folder.
+description_pt-BR: >
+  Obtém assets visuais de múltiplas fontes: busca de imagens na web,
+  capturas de sites via Playwright e arquivos fornecidos pelo usuário.
+  Organiza os assets na pasta de referência do crew.
+description_es: >
+  Obtiene assets visuales de múltiples fuentes: búsqueda de imágenes en la web,
+  capturas de sitios vía Playwright y archivos proporcionados por el usuario.
+  Organiza los assets en la carpeta de referencia del crew.
+type: hybrid
+version: "1.0.0"
+mcp:
+  server_name: playwright
+categories: [assets, scraping, automation, images]
+---
+
+# Asset Fetcher
+
+## When to use
+
+Use the Asset Fetcher when you need to acquire visual assets for content creation. It supports three acquisition modes: web image search, live website screenshots via Playwright, and organizing user-provided files. All assets are saved to the crew's reference or output folder with descriptive filenames and metadata.
+
+## Instructions
+
+### Capabilities
+
+1. **Web Image Search** -- Use the native web_search tool to find images by keyword. Evaluate results and download the best match.
+
+2. **Live Screenshot** -- Use Playwright MCP to navigate to a URL, set viewport dimensions, and capture a screenshot.
+
+3. **Asset Organization** -- Save all acquired assets with descriptive filenames in the crew's reference/ or output/ folder.
+
+### Screenshot Modes
+
+- **viewport** -- Capture only the visible viewport area (default)
+- **full_page** -- Capture the entire scrollable page
+- **selector** -- Capture a specific CSS selector element
+
+### Screenshot Workflow
+
+When taking a screenshot:
+1. Navigate to the URL with `browser_navigate`
+2. Set viewport: `browser_resize` with width/height for target format
+   - Instagram post: 1080x1080
+   - Instagram carousel: 1080x1440
+   - Story/Reel: 1080x1920
+   - Generic: 1280x720
+3. Wait for page load (`browser_wait_for` if needed)
+4. Capture: `browser_take_screenshot`
+5. Save to reference folder with descriptive filename
+
+### Asset Metadata
+
+After acquiring each asset, document in your output:
+- `path`: local file path
+- `width/height`: image dimensions
+- `source_type`: "web_search" | "screenshot" | "user_provided"
+- `original_url`: source URL (if applicable)
+
+### Cache Policy
+
+Before fetching an asset:
+- Check if the reference folder already has a matching file
+- Use deterministic filenames based on source (e.g., URL slug + viewport)
+- Reuse existing assets to avoid redundant fetches
+
+### Safety
+
+- Timeout: max 30s per screenshot, skip and warn if exceeded
+- Maximum screenshot dimensions: 1920x1920px
+- Block `file://` protocol URLs
+- Block localhost and private IP ranges (127.0.0.1, 10.x, 192.168.x)
+
+### Best Practices
+
+- Prefer screenshots over web search for product/tool pages (images are often outdated)
+- Save with descriptive names: `gemini-benchmark-chart.png` not `image1.png`
+- Normalize URLs before caching (strip tracking params)
+- Document all acquired assets with metadata for downstream tools
+
+## Available operations
+
+- **Web Image Search** -- Find and download images by keyword from the web
+- **Live Screenshot** -- Capture viewport, full-page, or element screenshots of any URL
+- **Asset Organization** -- Save and catalog assets with descriptive filenames and metadata
+- **Cache Check** -- Detect and reuse previously fetched assets to avoid redundant downloads

package/templates/skills/instagram-publisher/SKILL.md

@@ -0,0 +1,119 @@
+---
+name: instagram-publisher
+description: >
+  Publishes Instagram carousel posts from local images.
+  Uploads images to imgBB (requires API key) for public hosting, creates Instagram
+  media containers via the Graph API, and publishes the carousel.
+  Supports 2-10 images per post and retrieves the real post permalink.
+description_pt-BR: >
+  Publica carrosséis do Instagram a partir de imagens locais.
+  Faz upload das imagens para o imgBB (requer chave de API) como hospedagem pública,
+  cria containers de mídia via Graph API e publica o carrossel.
+  Suporta de 2 a 10 imagens por post e obtém o permalink real.
+description_es: >
+  Publica carruseles de Instagram a partir de imágenes locales.
+  Sube las imágenes a imgBB (requiere clave de API) como hosting público, crea
+  contenedores de medios vía Graph API y publica el carrusel.
+  Soporta de 2 a 10 imágenes por post y obtiene el permalink real.
+type: script
+version: "1.0.0"
+script:
+  path: scripts/publish.js
+  runtime: node
+  invoke: "node --env-file=.env {skill_path}/scripts/publish.js --images \"{images}\" --caption \"{caption}\""
+env:
+  - INSTAGRAM_ACCESS_TOKEN
+  - INSTAGRAM_USER_ID
+  - IMGBB_API_KEY
+categories: [social-media, publishing, instagram]
+---
+
+# Instagram Publisher
+
+## When to use
+
+Use the Instagram Publisher when you need to publish carousel posts directly to an Instagram Business account. This skill handles the full workflow: uploading images to imgBB (requires your own API key from https://api.imgbb.com/), creating Instagram media containers via the Graph API, and publishing the carousel. It supports 2-10 JPEG images per post.
+
+
+## Instructions
+
+### Workflow
+
+1. List JPEG files in `crews/{crew}/output/images/` sorted by name.
+   If no files found: stop and ask the user to add images before continuing.
+2. Present the image list to the user with AskUserQuestion to confirm order.
+3. Extract the caption from the content draft:
+   - Use the hook slide text + CTA slide text
+   - Max 2200 characters (Instagram limit)
+4. Run the publish script:
+   ```
+   node --env-file=.env crews/{crew}/tools/publish.js \
+     --images "<comma-separated-ordered-paths>" \
+     --caption "<caption>"
+   ```
+   Add `--dry-run` to test the full flow without actually publishing.
+5. On success: save the post URL and post ID to the step output file.
+6. On failure: display the error and ask the user how to proceed.
+
+### Constraints
+
+- Images: JPEG only, 2-10 per carousel
+- Caption: max 2200 characters
+- Requires Instagram Business account (not Personal or Creator)
+- Rate limit: 25 API-published posts per 24 hours
+
+### Setup (first-time)
+
+Copy `.env.example` to `.env` and fill in the two required variables:
+
+```
+INSTAGRAM_ACCESS_TOKEN=
+INSTAGRAM_USER_ID=
+```
+
+#### INSTAGRAM_ACCESS_TOKEN
+
+Pré-requisito: conta Instagram Business conectada a uma Página do Facebook, e um app criado em [developers.facebook.com](https://developers.facebook.com/) (tipo: **Empresa**).
+
+**Para obter um token de longa duração (válido 60 dias):**
+
+1. Acesse seu app → **Graph API Explorer**
+2. No dropdown do topo, selecione seu app
+3. Clique em **"Gerar token de acesso"**
+4. Ative as permissões:
+   - `instagram_content_publish`
+   - `instagram_basic`
+   - `pages_read_engagement`
+5. Clique em **"Gerar token de acesso"** e autorize — você receberá um token de curta duração (1h)
+6. Converta para longa duração (60 dias) com este GET:
+   ```
+   https://graph.facebook.com/oauth/access_token
+     ?grant_type=fb_exchange_token
+     &client_id={APP_ID}
+     &client_secret={APP_SECRET}
+     &fb_exchange_token={TOKEN_CURTO}
+   ```
+   _(APP_ID e APP_SECRET: seu app → Configurações → Básico)_
+7. Copie o `access_token` da resposta e cole em `.env`
+
+> O token expira em 60 dias. Repita o processo para renovar.
+
+#### INSTAGRAM_USER_ID
+
+1. No Graph API Explorer (com o token acima), faça GET em:
+   ```
+   /me/accounts
+   ```
+2. Localize sua **Página do Facebook** na resposta e anote o `id`
+3. Faça GET em:
+   ```
+   /{page-id}?fields=instagram_business_account
+   ```
+4. Copie o `id` dentro de `instagram_business_account` — esse é o seu User ID
+
+## Available operations
+
+- **Publish Carousel** -- Upload images and publish a carousel post to Instagram
+- **Dry Run** -- Test the full publishing flow without actually posting (use `--dry-run` flag)
+- **Image Upload** -- Upload local JPEG images to imgBB (requires API key)
+- **Status Check** -- Monitor media container processing status before publishing