@julioventura/opensquad 0.1.17

package/skills/template-designer/SKILL.md

@@ -0,0 +1,201 @@
+---
+name: template-designer
+description: Visual template selection for image design agents. Generates template variations, renders them as images for user review, and saves the approved visual identity.
+type: prompt
+version: "2.0.0"
+categories: [design, visual, templates]
+---
+
+# Template Designer
+
+Visual template selection and refinement for squad creation and editing.
+
+## When to Use
+
+- During squad creation: when the Design phase identifies an image design agent and the user opts to choose a template
+- During squad editing: when the user asks to define, edit, or change the visual identity / template of a design agent
+- Trigger: presence of `image-creator` skill (or similar image-producing skill) in the squad's skill list
+
+## Prerequisites
+
+- A squad with a design agent that produces images (uses `image-creator` skill)
+- Squad's `_build/` directory must exist (created during Discovery/Design phases)
+- `image-creator` skill installed (for rendering HTML to JPG)
+
+## How It Works
+
+1. You read context and base templates
+2. You generate 3 adapted HTML template variations
+3. You render each as a JPG image using the `image-creator` skill
+4. You present the image file paths to the user for review
+5. You iterate with feedback until approval
+6. You save the approved template as HTML reference + structured style rules
+
+## Generating Templates
+
+### Step 0: Read Design Guidelines (MANDATORY)
+
+Before generating any template, read and internalize the design best practices:
+- `_opensquad/core/best-practices/image-design.md` — **REQUIRED reading**. Contains platform-specific minimum font sizes, typography rules, spacing guidelines, color palette constraints, contrast requirements, and layout methodology. Every template you generate MUST comply with these rules.
+
+Key rules to always follow:
+- **Font sizes**: Hero 58px, Heading 43px, Body 34px, Caption 24px minimum for Instagram carousel (1080x1440). Absolute minimum 20px for any readable text on any platform.
+- **Font weight**: 500 or higher for body text and above.
+- **Colors**: Maximum 5 colors per design system (primary, secondary, accent, background, text).
+- **Contrast**: WCAG AA minimum 4.5:1 for all text against background.
+- **Layout**: CSS Grid or Flexbox only. No absolute positioning for primary content.
+- **Self-contained HTML**: Inline CSS only. Only Google Fonts @import allowed as external resource.
+- **No slide counters**: Never include "1/7" or similar. Instagram has native navigation.
+
+You should also apply general web design best practices: proper white space, visual hierarchy through scale and weight, consistent spacing rhythm, and balanced composition.
+
+### HARD RULES — Dimensions and Typography
+
+These rules are NON-NEGOTIABLE. Every template must comply:
+
+**Fixed Dimensions (never use height: auto or flexible height):**
+- Instagram Carousel: `width: 1080px; height: 1440px` (3:4 portrait)
+- Instagram Story/Reel: `width: 1080px; height: 1920px` (9:16 portrait)
+- Instagram Post: `width: 1080px; height: 1080px` (1:1 square)
+- LinkedIn Post: `width: 1200px; height: 627px` (1.91:1 horizontal)
+
+The root container of every template MUST set explicit `width` and `height` in pixels. The template must render at exactly these dimensions — no overflow, no scrolling, no flexible height.
+
+**Minimum Font Sizes (Instagram at 1080px width):**
+- Hero/Title: **58px** minimum
+- Heading: **43px** minimum
+- Body text: **34px** minimum
+- Caption/small text: **24px** minimum
+- Absolute minimum for ANY readable text on ANY platform: **20px**
+
+**Font Weight:** 500 or higher for body text and above. Never use font-weight below 400 for any visible text.
+
+Templates that violate these rules are rejected — no exceptions.
+
+### Step 1: Read Context
+
+Read these files to understand the squad:
+- `squads/{code}/_build/discovery.yaml` — platform, domain, tone, language
+- `squads/{code}/_build/design.yaml` — agents, purpose, skills
+- `squads/{code}/_investigations/consolidated-analysis.md` (if exists) — visual patterns from reference profiles
+- `_opensquad/_memory/company.md` — company name, brand, industry, target audience
+- `_opensquad/_memory/preferences.md` — user preferences (language, style, tone)
+
+Use the company context and user preferences to adapt template content: example text should reflect the company's domain and audience, colors should align with brand if available, and language should match the user's Output Language preference.
+
+### Step 2: Read Base Templates
+
+Read the 3 base templates from `skills/template-designer/base-templates/`:
+- `model-a.html`
+- `model-b.html`
+- `model-c.html`
+
+### Step 3: Generate Adapted Variations
+
+For each base template, create an adapted version:
+- Adjust colors to match the squad's domain/brand (use Sherlock palette if available, company brand colors from company.md if available)
+- Adjust typography following the platform-specific minimum font sizes from `image-design.md`
+- Replace example content with domain-relevant content that reflects the company's industry, audience, and language
+- Set the root container to the exact fixed dimensions from HARD RULES above. Never use percentage heights or auto heights.
+- Add any visual elements that match the squad's personality
+- Apply proper white space, visual hierarchy, and spacing rhythm per `image-design.md` methodology
+
+Write each adapted template as a **complete, self-contained HTML file** (with `<!DOCTYPE html>`, inline CSS, and Google Fonts imports if needed).
+
+Save to:
+- `squads/{code}/_build/template-a.html`
+- `squads/{code}/_build/template-b.html`
+- `squads/{code}/_build/template-c.html`
+
+### Step 4: Render as Images
+
+Use the `image-creator` skill to render each HTML template as a JPG image:
+
+1. Read `skills/image-creator/SKILL.md` for rendering instructions
+2. Render each template HTML to JPG using the image-creator workflow
+3. Save rendered images to:
+   - `squads/{code}/_build/template-a.jpg`
+   - `squads/{code}/_build/template-b.jpg`
+   - `squads/{code}/_build/template-c.jpg`
+
+### Step 5: Present to User
+
+Present the 3 template options to the user using **clickable markdown links with absolute file paths** so they can open and review:
+
+> "Here are 3 template options for your squad's visual identity:
+>
+> - [preview-a.jpg]({absolute_path}/squads/{code}/_build/template-a.jpg) — Template A
+> - [preview-b.jpg]({absolute_path}/squads/{code}/_build/template-b.jpg) — Template B
+> - [preview-c.jpg]({absolute_path}/squads/{code}/_build/template-c.jpg) — Template C
+>
+> Click the links above to open each image. Tell me which one you prefer. I can also mix elements from different templates or adjust colors, fonts, and layout."
+
+**Important:** Always use the full absolute path (e.g., `d:\Coding Projects\opensquad\squads\my-squad\_build\template-a.jpg`) inside the markdown link — relative paths are not clickable in the IDE.
+
+## Iteration Loop
+
+1. Present template images with clickable markdown links using absolute file paths
+2. Wait for user feedback in terminal
+3. Generate new version based on feedback — save as `template-v2.html`, render as `template-v2.jpg`, etc.
+4. Present updated image with clickable markdown link using absolute file path
+5. Repeat until user approves
+
+## Saving the Approved Template
+
+When the user approves, create two files:
+
+### 1. Template Reference HTML
+
+Save to: `squads/{code}/pipeline/data/template-reference.html`
+
+The complete, self-contained HTML/CSS of the approved template at full resolution (e.g., 1080x1440). This is the literal example the design agent will use.
+
+### 2. Visual Identity Rules
+
+Save to: `squads/{code}/pipeline/data/visual-identity.md`
+
+Extract structured rules from the approved template:
+
+~~~markdown
+# Visual Identity
+
+## Color Palette
+- **Primary:** #HEXCODE — usage description
+- **Secondary:** #HEXCODE — usage description
+- **Background:** #HEXCODE
+- **Text:** #HEXCODE
+- **Accent:** #HEXCODE — usage description
+
+## Typography
+- **Headings:** Font Family, weight, size range
+- **Body:** Font Family, weight, size range
+- **Caption:** Font Family, weight, size range
+- **Minimum sizes:** body 32px, caption 24px, heading 48px
+
+## Layout
+- **Viewport:** WIDTHxHEIGHT px
+- **Padding:** value
+- **Grid:** description
+- **Spacing rules:** description
+
+## Composition Rules
+- Logo/profile placement: description
+- Image treatment: description
+- Visual hierarchy: description
+- Footer/CTA pattern: description
+
+## Adaptation Rules
+- How to handle different viewport sizes
+- What stays fixed vs. what adapts
+- Color usage rules (when to use primary vs accent)
+~~~
+
+### 3. Update Squad Files
+
+If the squad is being created (Build phase hasn't run yet):
+- The design.yaml context now includes the template data — Build will pick it up
+
+If the squad already exists (editing flow):
+- Add `pipeline/data/template-reference.html` and `pipeline/data/visual-identity.md` to `squad.yaml` `data:` list
+- Update the design agent's `.agent.md` to reference both files
+- Update the design agent's tasks to include the rule: "always follow visual-identity.md and use template-reference.html as the base model"

package/skills/template-designer/base-templates/model-a.html

@@ -0,0 +1,27 @@
+<!-- Model A: Twitter Editorial — approved 2026-03-28 -->
+<!-- Style: Black background, tweet-style layout with avatar, verified badge, editorial text, contextual image -->
+<!-- Fonts: Inter (body), weight 400-700 -->
+<!-- Colors: #000 bg, #fff text, #1D9BF0 verified, #71767B muted, #2a2a2a borders/avatar, #1a1a2e image gradient -->
+<div style="width:1080px;height:1440px;background:#000;color:#fff;font-family:'Inter',sans-serif;display:flex;flex-direction:column;padding:72px;gap:0;position:relative;overflow:hidden;">
+  <!-- Tweet header -->
+  <div style="display:flex;gap:24px;align-items:center;">
+    <div style="width:80px;height:80px;border-radius:50%;background:#2a2a2a;flex-shrink:0;"></div>
+    <div>
+      <div style="display:flex;align-items:center;gap:8px;">
+        <span style="font-weight:700;font-size:34px;">Nome Sobrenome</span>
+        <svg width="28" height="28" viewBox="0 0 24 24" fill="#1D9BF0"><path d="M22.25 12c0-1.43-.88-2.67-2.19-3.34.46-1.39.2-2.9-.81-3.91s-2.52-1.27-3.91-.81c-.66-1.31-1.91-2.19-3.34-2.19s-2.67.88-3.34 2.19c-1.39-.46-2.9-.2-3.91.81s-1.27 2.52-.81 3.91C2.63 9.33 1.75 10.57 1.75 12s.88 2.67 2.19 3.34c-.46 1.39-.2 2.9.81 3.91s2.52 1.27 3.91.81c.66 1.31 1.91 2.19 3.34 2.19s2.67-.88 3.34-2.19c1.39.46 2.9.2 3.91-.81s1.27-2.52.81-3.91c1.31-.67 2.19-1.91 2.19-3.34zm-11.08 4.71c-.22.22-.58.22-.8 0L7.4 13.74c-.22-.22-.22-.58 0-.8.22-.22.58-.22.8 0l2.57 2.57 6.03-6.03c.22-.22.58-.22.8 0 .22.22.22.58 0 .8l-6.43 6.43z"/></svg>
+      </div>
+      <span style="font-size:28px;color:#71767B;">@username</span>
+    </div>
+  </div>
+  <!-- Tweet text -->
+  <div style="font-size:38px;line-height:1.45;font-weight:400;margin-top:48px;">
+    Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed ut perspiciatis unde omnis iste natus error sit voluptatem accusantium doloremque laudantium.
+    <br><br>
+    Nemo enim ipsam voluptatem quia voluptas sit aspernatur aut odit aut fugit. Neque porro quisquam est qui dolorem.
+  </div>
+  <!-- Image -->
+  <div style="width:100%;height:35%;background:linear-gradient(180deg,#1a1a2e,#0d0d0d);border-radius:24px;display:flex;align-items:center;justify-content:center;border:1px solid #2a2a2a;flex-shrink:0;margin-top:auto;">
+    <span style="color:#555;font-size:34px;">Imagem contextual</span>
+  </div>
+</div>

package/skills/template-designer/base-templates/model-b.html

@@ -0,0 +1,31 @@
+<!-- Model B: Clean Visual — approved 2026-03-28 -->
+<!-- Style: Warm cream background, bold uppercase title, numbered cards with warm gradient progression -->
+<!-- Fonts: Montserrat 900 (title), Inter 500-700 (body) -->
+<!-- Colors: #FDF6EE bg, #E85D2A primary orange, #D4742A/#C05A1A/#A04010 gradient steps, #FFF5E6-#D07030 card backgrounds -->
+<div style="width:1080px;height:1440px;background:#FDF6EE;color:#111;font-family:'Inter',sans-serif;display:flex;flex-direction:column;padding:72px;justify-content:center;gap:48px;position:relative;overflow:hidden;">
+  <!-- Title -->
+  <div style="text-align:center;">
+    <h1 style="font-size:58px;font-weight:900;line-height:1.15;margin:0;text-transform:uppercase;font-family:'Montserrat',sans-serif;">
+      <span style="color:#E85D2A;">LOREM IPSUM</span> DOLOR SIT AMET CONSECTETUR
+    </h1>
+  </div>
+  <!-- Items -->
+  <div style="display:flex;flex-direction:column;gap:20px;">
+    <div style="display:flex;align-items:center;gap:28px;background:#FFF5E6;border-radius:20px;padding:28px 32px;">
+      <div style="width:64px;height:64px;border-radius:50%;border:3px solid #E85D2A;display:flex;align-items:center;justify-content:center;font-size:28px;font-weight:800;color:#E85D2A;flex-shrink:0;">1</div>
+      <div><div style="font-size:34px;font-weight:700;">Proin tempus vehicula</div><div style="font-size:26px;color:#888;font-weight:500;">Sed ut perspiciatis unde omnis iste natus error.</div></div>
+    </div>
+    <div style="display:flex;align-items:center;gap:28px;background:linear-gradient(90deg,#FDEBD0,#F5C89A);border-radius:20px;padding:28px 32px;">
+      <div style="width:64px;height:64px;border-radius:50%;border:3px solid #D4742A;display:flex;align-items:center;justify-content:center;font-size:28px;font-weight:800;color:#D4742A;flex-shrink:0;">2</div>
+      <div><div style="font-size:34px;font-weight:700;">Vestibulum ante ipsum</div><div style="font-size:26px;color:#666;font-weight:500;">Nemo enim ipsam voluptatem quia voluptas sit.</div></div>
+    </div>
+    <div style="display:flex;align-items:center;gap:28px;background:linear-gradient(90deg,#F5C89A,#E8A065);border-radius:20px;padding:28px 32px;">
+      <div style="width:64px;height:64px;border-radius:50%;border:3px solid #C05A1A;display:flex;align-items:center;justify-content:center;font-size:28px;font-weight:800;color:#C05A1A;flex-shrink:0;">3</div>
+      <div><div style="font-size:34px;font-weight:700;">Maecenas dignissim justo</div><div style="font-size:26px;color:#555;font-weight:500;">Ut enim ad minima veniam nostrum exercitationem.</div></div>
+    </div>
+    <div style="display:flex;align-items:center;gap:28px;background:linear-gradient(90deg,#E8A065,#D07030);border-radius:20px;padding:28px 32px;">
+      <div style="width:64px;height:64px;border-radius:50%;border:3px solid #A04010;display:flex;align-items:center;justify-content:center;font-size:28px;font-weight:800;color:#A04010;flex-shrink:0;">4</div>
+      <div><div style="font-size:34px;font-weight:700;color:#fff;">Curabitur pretium tincidunt</div><div style="font-size:26px;color:#ffffffcc;font-weight:500;">Quis autem vel eum iure reprehenderit voluptate.</div></div>
+    </div>
+  </div>
+</div>

package/skills/template-designer/base-templates/model-c.html

@@ -0,0 +1,42 @@
+<!-- Model C: Data Dashboard — approved 2026-03-28 -->
+<!-- Style: Purple-dark gradient, data metric cards, decorative glow effects -->
+<!-- Fonts: Montserrat 900 (title, metrics), Inter 500 (body, labels) -->
+<!-- Colors: gradient #0f0326-#1a0a3e-#0d0d0d bg, #F59E0B yellow, #EC4899 pink, #7C3AED purple, #4ADE80 green accents -->
+<div style="width:1080px;height:1440px;background:linear-gradient(160deg,#0f0326,#1a0a3e 40%,#0d0d0d);color:#fff;font-family:'Inter',sans-serif;display:flex;flex-direction:column;padding:72px;position:relative;overflow:hidden;">
+  <!-- Glow effects -->
+  <div style="position:absolute;top:-120px;right:-120px;width:480px;height:480px;background:radial-gradient(circle,#7C3AED33,transparent 70%);pointer-events:none;"></div>
+  <div style="position:absolute;bottom:-100px;left:-100px;width:400px;height:400px;background:radial-gradient(circle,#F59E0B22,transparent 70%);pointer-events:none;"></div>
+  <!-- Tag + Title -->
+  <div style="position:relative;z-index:1;">
+    <div style="display:inline-block;background:#F59E0B33;border-radius:8px;padding:8px 20px;font-size:24px;color:#F59E0B;font-weight:800;text-transform:uppercase;letter-spacing:3px;margin-bottom:28px;">Lorem Ipsum</div>
+    <h1 style="font-size:52px;font-weight:900;line-height:1.2;margin:0 0 24px 0;font-family:'Montserrat',sans-serif;">
+      Sed ut perspiciatis <span style="background:linear-gradient(90deg,#F59E0B,#EC4899);-webkit-background-clip:text;-webkit-text-fill-color:transparent;">unde omnis</span> iste natus error sit
+    </h1>
+    <p style="font-size:34px;color:#bbb;line-height:1.55;margin:0;font-weight:500;letter-spacing:0.01em;">Nemo enim ipsam voluptatem quia voluptas sit aspernatur aut odit aut fugit, sed quia consequuntur magni dolores.</p>
+  </div>
+  <!-- Data cards -->
+  <div style="position:relative;z-index:1;display:flex;flex-direction:column;gap:16px;margin:40px 0;flex:1;justify-content:center;">
+    <div style="background:#ffffff08;border:1px solid #ffffff10;border-radius:16px;padding:28px 32px;display:flex;justify-content:space-between;align-items:center;">
+      <span style="font-size:28px;color:#888;font-weight:500;">Lorem ipsum</span>
+      <span style="font-size:40px;font-weight:800;color:#F59E0B;font-family:'Montserrat',sans-serif;">U$3.4B</span>
+    </div>
+    <div style="background:#ffffff08;border:1px solid #ffffff10;border-radius:16px;padding:28px 32px;display:flex;justify-content:space-between;align-items:center;">
+      <span style="font-size:28px;color:#888;font-weight:500;">Dolor sit amet</span>
+      <span style="font-size:40px;font-weight:800;color:#EC4899;font-family:'Montserrat',sans-serif;">-U$5B</span>
+    </div>
+    <div style="background:#ffffff08;border:1px solid #ffffff10;border-radius:16px;padding:28px 32px;display:flex;justify-content:space-between;align-items:center;">
+      <span style="font-size:28px;color:#888;font-weight:500;">Consectetur</span>
+      <span style="font-size:40px;font-weight:800;color:#7C3AED;font-family:'Montserrat',sans-serif;">U$157B</span>
+    </div>
+    <div style="background:#ffffff08;border:1px solid #ffffff10;border-radius:16px;padding:28px 32px;display:flex;justify-content:space-between;align-items:center;">
+      <span style="font-size:28px;color:#888;font-weight:500;">Adipiscing elit</span>
+      <span style="font-size:40px;font-weight:800;color:#4ADE80;font-family:'Montserrat',sans-serif;">3.500+</span>
+    </div>
+  </div>
+  <!-- Footer -->
+  <div style="position:relative;z-index:1;display:flex;align-items:center;gap:20px;padding-top:24px;border-top:1px solid #ffffff12;">
+    <div style="width:48px;height:48px;border-radius:50%;background:linear-gradient(135deg,#F59E0B,#EC4899);"></div>
+    <span style="font-size:24px;color:#777;">@username</span>
+    <span style="margin-left:auto;font-size:24px;color:#555;">ARRASTE →</span>
+  </div>
+</div>

package/skills/youtube-publisher/SKILL.md

@@ -0,0 +1,232 @@
+---
+name: youtube-publisher
+description: >
+  Publishes simple YouTube videos from a local image sequence.
+  Builds an MP4 slideshow with ffmpeg using 10-second still intervals,
+  applies the repository background soundtrack by default when available,
+  validates OAuth credentials, uploads via the YouTube Data API,
+  and can set a custom thumbnail plus richer video metadata.
+description_pt-BR: >
+  Publica videos simples no YouTube a partir de uma sequencia local de imagens.
+  Monta um slideshow MP4 com ffmpeg usando 10 segundos por imagem,
+  aplica por padrao a trilha de fundo do repositorio quando disponivel,
+  valida as credenciais OAuth, faz upload pela YouTube Data API
+  e pode definir thumbnail customizada e metadados mais completos.
+description_es: >
+  Publica videos simples en YouTube a partir de una secuencia local de imagenes.
+  Genera un slideshow MP4 con ffmpeg usando 10 segundos por imagen,
+  aplica por defecto la pista de fondo del repositorio cuando esta disponible,
+  valida credenciales OAuth y sube el video con la YouTube Data API.
+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}\" --title \"{title}\" --description \"{description}\""
+env:
+  - YOUTUBE_CLIENT_ID
+  - YOUTUBE_CLIENT_SECRET
+  - YOUTUBE_REFRESH_TOKEN
+  - YOUTUBE_CHANNEL_ID
+categories: [social-media, publishing, youtube, video]
+---
+
+# YouTube Publisher
+
+## When to use
+
+Use the YouTube Publisher when you need an initial proof of publishing to YouTube from content already rendered as local images. This version turns ordered JPG/JPEG or PNG slides into a simple MP4 slideshow with **10 seconds per image**, applies the repository soundtrack from `public/Trilha sonora de slides.mp3` when that file exists, validates OAuth access, uploads the video to the target YouTube channel, and can optionally apply a custom thumbnail plus richer video metadata.
+
+## Instructions
+
+### Workflow
+
+1. List JPG/JPEG or PNG files in the squad output folder and confirm their order with the user.
+2. Build the YouTube metadata package for the upload:
+  - title and description
+  - tags and category
+  - privacy status (default: `public`; use `private` only for approved scheduling flows)
+  - optional thumbnail, otherwise auto-generate one from slide 2 in 16:9 when available
+  - optional scheduling/language/recording fields
+  - normalize wrapped communication-channel values from `content-package.md` before composing the description; strip surrounding `< >`, quotes, or backticks so YouTube receives plain-text URLs/emails only
+  - for Opensquad slide/news runs, ensure the description ends with a `FONTES VERIFICADAS` section listing the main verified sources with source name, valid URL, and consultation date
+3. Run a **dry-run first** to validate:
+   - local image files exist
+  - `ffmpeg` is resolvable either from `FFMPEG_PATH`/`FFMPEG_BIN`, the current `PATH`, or the validated local WinGet install on Windows
+  - the default background soundtrack is detected, or a custom `--audio-track` path resolves correctly when provided
+   - OAuth refresh token can be exchanged for an access token
+   - authenticated account can access the target channel
+   - slideshow MP4 can be generated successfully
+  - if the refresh-token exchange fails with `invalid_grant`, stop the live upload path and refresh the OAuth grant before retrying
+4. Present the preview and wait for explicit user confirmation before a live upload.
+5. On live upload, call the script without `--dry-run`, then save the resulting YouTube video ID, URL, thumbnail status, and effective metadata.
+6. If this upload belongs to an Opensquad run, keep the run-dashboard in the closing checklist. If `jornal-matutino` is not pending, regenerate the run dashboard immediately after the last selected output completes. If `jornal-matutino` is still pending, defer dashboard regeneration until that complementary step finishes. When static publish is enabled in squad config, publishing the dashboard is automatic and does not require a second confirmation prompt.
+
+### OAuth recovery when `invalid_grant` appears
+
+If Google returns `invalid_grant` during the refresh-token exchange, treat the stored refresh token as expired or revoked.
+
+Recovery procedure:
+
+1. Generate a fresh consent URL for the brand's desktop OAuth client with `access_type=offline` and `prompt=consent`.
+2. Open the URL in the browser and complete the Google approval flow with the correct brand account.
+3. If the browser lands on `http://127.0.0.1:3000/?code=...` and shows `ERR_CONNECTION_REFUSED`, do not treat that page as a blocker. The `code` query parameter is still valid.
+4. Exchange that authorization code manually against `https://oauth2.googleapis.com/token` using the same desktop client id, client secret, and redirect URI.
+5. Update the squad-specific refresh token in `.env`, rerun the YouTube dry-run, and only then proceed to the live upload.
+
+### Command
+
+```
+node --env-file=.env {skill_path}/scripts/publish.js \
+  --images "slide-01.jpg,slide-02.png,slide-03.jpg" \
+  --title "Teste inicial do pipeline no YouTube" \
+  --description "Video de validacao gerado automaticamente a partir das imagens do post." \
+  [--thumbnail "squads/{squad}/output/thumbs/youtube-thumb.jpg"] \
+  [--privacy-status "public"] \
+  [--tags "opensquad,teste,youtube"] \
+  [--category-id "22"] \
+  [--made-for-kids "false"] \
+  [--embeddable "true"] \
+  [--public-stats-viewable "true"] \
+  [--license "youtube"] \
+  [--publish-at "2026-05-18T15:00:00Z"] \
+  [--default-language "pt-BR"] \
+  [--default-audio-language "pt-BR"] \
+  [--recording-date "2026-05-17"] \
+  [--playlist-name "Posts automáticos"] \
+  [--playlist-privacy "private"] \
+  [--video-output "squads/{squad}/output/videos/youtube-validation.mp4"] \
+  [--audio-track "public/Trilha sonora de slides.mp3"] \
+  [--youtube-client-id-env "CUSTOM_YOUTUBE_CLIENT_ID"] \
+  [--youtube-client-secret-env "CUSTOM_YOUTUBE_CLIENT_SECRET"] \
+  [--youtube-refresh-token-env "CUSTOM_YOUTUBE_REFRESH_TOKEN"] \
+  [--youtube-channel-id-env "CUSTOM_YOUTUBE_CHANNEL_ID"] \
+  [--no-narration] \
+  [--dry-run]
+```
+
+### Per-squad credential routing
+
+If the workspace operates multiple brands, prefer per-squad environment aliases instead of a single shared YouTube credential set.
+
+Example:
+
+```
+node --env-file=.env {skill_path}/scripts/publish.js \
+  --images "slide-01.jpg,slide-02.png" \
+  --title "MusicPlay Club - teste de upload" \
+  --description "Validacao do fluxo de YouTube" \
+  --youtube-client-id-env "MUSICPLAY_YOUTUBE_CLIENT_ID" \
+  --youtube-client-secret-env "MUSICPLAY_YOUTUBE_CLIENT_SECRET" \
+  --youtube-refresh-token-env "MUSICPLAY_YOUTUBE_REFRESH_TOKEN" \
+  --youtube-channel-id-env "MUSICPLAY_YOUTUBE_CHANNEL_ID" \
+  --dry-run
+```
+
+If these flags are omitted, the script uses the default env keys:
+
+- `YOUTUBE_CLIENT_ID`
+- `YOUTUBE_CLIENT_SECRET`
+- `YOUTUBE_REFRESH_TOKEN`
+- `YOUTUBE_CHANNEL_ID`
+
+### Constraints
+
+- Input images: JPG, JPEG, or PNG
+- Thumbnail: JPG, JPEG, or PNG, max 2MB
+- If `--thumbnail` is omitted, the script auto-generates a 1280x720 thumbnail from slide 2 when available, otherwise from slide 1
+- If the channel is not eligible for custom thumbnails yet, the video upload still succeeds and the run reports the thumbnail upload error separately
+- Minimum image count: 1
+- Slide duration: determined dynamically based on slide narration length. The narrated default is 1s pause at the start of each slide + Title voice + 1s pause + Text voice + 2s pause at the end of the slide, plus 1 extra second of dwell before the transition timing begins. The visual transition must start only after that full narrated block ends; it must never overlap the slide narration itself. If narration is disabled via `--no-narration`, slide duration defaults to a fixed 10 seconds per image.
+- Background audio: mixed automatically with narration. Background soundtrack volume is `0.12` when voice is present (otherwise `0.3`), narration volume is `1.2`, with a 2-second fade-in and 5-second fade-out. **Audio mix uses `amix` with `normalize=0`** — obrigatório para evitar aumento de volume no último slide quando o SFX de transição termina antes da narração e música.
+- Slide transitions: by default, consecutive slides use a `fade-out-to-black` + `fade-in-from-black` transition (`fadeblack`) lasting 2 seconds.
+- Transition SFX: by default, each slide change uses the shared asset `public/sfx/slide-transition-sfx.mp3` (warm whoosh, canonical since 2026-05). If that shared asset is unavailable, the publisher falls back to Eleven Labs generation. **Never recriar o arquivo a cada run** — reuse the shared copy. This is the standard transition sound for all squads unless explicitly overridden.
+- Video ending: the final slide remains visible to the end while the soundtrack fades out during the last 5 seconds.
+- Video-only progress indicator: only active and displayed for fixed-duration slideshows (when `--no-narration` is used). It overlays a circular progress marker in a corner of the MP4 that loops every 10 seconds. For dynamic voice-synchronized slideshows, the progress ring is hidden to ensure a clean design.
+- Narration: Enabled by default and uses Eleven Labs with the "Dani" voice (`PznTnBc8X6pvixs9UkQm`) for both title (expressive parameters) and text description. Can be disabled via `--no-narration` (which falls back to a fixed 10s duration and silence narration track).
+- Narration source discipline: for every slide, synthesize only the text that is actually visible on the slide canvas and relevant to the slide itself, prioritizing the visible title plus the primary body copy. Do not let narration spill into off-slide editorial support text, QR/link instructions, channel lists, source appendices, or any longer `content-package.md` context that is not on the card.
+- Last-slide guardrail: when `content-package.md` continues with sections such as `## Legenda`, `## Hashtags`, `## Saiba mais`, or compliance notes after the final `## Slide N`, the narration parser must stop at the next markdown heading. Never let the final slide absorb trailing document sections just because it is the last slide in the file.
+- Description sources: for Opensquad slide/news runs, the YouTube description should carry a final `FONTES VERIFICADAS` block with the verified source entries actually used in the story, each one with a valid URL and consultation date.
+- Description sanitation: communication-channel values imported from `content-package.md` must be emitted as plain text. Remove decorative wrappers such as `<https://...>` or `<email@brand.com>` before upload.
+- Video format: MP4 (`libx264`, `yuv420p`) rendered in 1280x720 landscape to avoid Shorts-style square output
+- `ffmpeg` must be installed and resolvable by the shared publisher logic (`FFMPEG_PATH`/`FFMPEG_BIN`, `PATH`, or the local WinGet install on Windows)
+- On Windows, prefer the full WinGet build from `Gyan.FFmpeg`; incomplete bundled builds may miss filters required by the slideshow fallback
+- OAuth scopes required:
+  - `https://www.googleapis.com/auth/youtube.upload`
+  - `https://www.googleapis.com/auth/youtube.force-ssl`
+  - `https://www.googleapis.com/auth/youtube.readonly`
+- `--publish-at` requires `--privacy-status private`
+
+### Setup (first-time)
+
+1. Create a dedicated Google account for the brand/channel. Prefer one Gmail per brand.
+2. Create or choose a YouTube channel owned by that Google account.
+3. Create a Google Cloud project and enable **YouTube Data API v3**.
+4. Create an **OAuth Client ID** of type **Desktop app**.
+5. Obtain a refresh token with the scopes `https://www.googleapis.com/auth/youtube.upload`, `https://www.googleapis.com/auth/youtube.force-ssl`, and `https://www.googleapis.com/auth/youtube.readonly`.
+6. Fill `.env` with the generated values.
+7. Install `ffmpeg` locally and confirm `where.exe ffmpeg` plus `ffmpeg -version` work in a fresh terminal. On Windows, the validated install command is `winget install --id Gyan.FFmpeg --silent --accept-package-agreements --accept-source-agreements`. If corporate shell policy prevents global PATH propagation, set `FFMPEG_PATH` to the resolved `ffmpeg.exe` as a stable fallback.
+
+Detailed authorization steps are documented in `DOC_YOUTUBE.md`.
+
+### Operational note
+
+Do not rely on an `ffmpeg.exe` inherited from another workspace, a third-party `node_modules` folder, or a temporary `PATH` change in one shell only. The preferred operating state is that a new terminal can resolve `ffmpeg`, but the shared publisher also supports an explicit `FFMPEG_PATH` or the validated local WinGet install as a recovery path.
+
+## Available operations
+
+- **Build slideshow video** -- Converts ordered images into a 1280x720 landscape MP4 slideshow with 10 seconds per image
+- **Dry Run** -- Validates files, thumbnail constraints, ffmpeg, OAuth token exchange, channel access, and video generation without uploading
+- **Upload Video** -- Performs resumable upload to YouTube and returns the video ID and URL
+- **Upload Thumbnail** -- Applies a custom YouTube thumbnail after the video is created
+- **Playlist routing** -- Creates or reuses a target playlist and adds the uploaded video to it
+- **Rich Metadata** -- Sets privacy, category, tags, kids setting, embeddability, visibility of stats, license, scheduling, language, and recording date
+- **Per-squad env routing** -- Reads credentials from default keys or custom env-variable aliases
+
+## Output expectations
+
+Successful live runs should report:
+
+- `Status: published`
+- `YouTube Video ID`
+- `YouTube URL`
+- effective channel title/id
+- generated local MP4 path
+- `Thumbnail Uploaded`
+- `Thumbnail Upload Error` when the video upload succeeds but the channel rejects custom thumbnails
+- metadata summary (privacy, category, tags, kids flag, schedule/language when present)
+
+Dry-runs should report:
+
+- `Status: dry-run`
+- validated channel title/id
+- generated local MP4 path
+- validated thumbnail path when provided
+- normalized metadata summary
+- confirmation that upload was skipped intentionally
+
+## Pre-publish checklist (mandatory for all squads)
+
+Before executing a YouTube publish command for any squad, the pipeline runner or agent must verify every item below. This checklist applies globally unless the squad's local step file explicitly overrides a specific item.
+
+- [ ] `ELEVEN_LABS_API` is set in `.env` and valid (narration is **enabled by default**)
+- [ ] Narration uses the Dani voice (`PznTnBc8X6pvixs9UkQm`) via Eleven Labs for title + body text of each slide
+- [ ] `--no-narration` is **not used** unless the user or the squad's local pipeline step explicitly requests silent mode
+- [ ] Background soundtrack (`public/Trilha sonora de slides.mp3`) is present and mixed at volume `0.12` (with voice) or `0.3` (without voice)
+- [ ] Slide transition SFX (`public/sfx/slide-transition-sfx.mp3`) is present and reused (not regenerated per run)
+- [ ] `ffmpeg` is resolvable (`where.exe ffmpeg` or `FFMPEG_PATH`)
+- [ ] OAuth refresh token exchange succeeds (dry-run validates this)
+- [ ] Thumbnail is auto-generated from slide 2 (or slide 1 if slide 2 is unavailable), unless a custom thumbnail is approved
+- [ ] Title is short, clear, and aligned with the editorial theme
+- [ ] Description ends with `FONTES VERIFICADAS` block (for Opensquad news/slide runs)
+- [ ] Hashtags are reviewed and content-coherent
+- [ ] Content is in the squad's target language with proper accentation
+- [ ] Slide order matches the approved editorial sequence
+- [ ] Video output is 1280x720 landscape MP4, not square/vertical (to avoid Shorts misclassification)
+
+> **Why narration is mandatory by default:** The Dani voice narration is a core brand differentiator for Opensquad video content. Publishing a slideshow without narration produces a silent video that feels incomplete and harms engagement metrics. Any agent that skips narration without explicit user approval is committing a pipeline violation.
+
+## Default visibility policy
+
+- Default live visibility is `public`.
+- Use `private` only when the user explicitly wants scheduling or a restricted pre-release flow.