@julioventura/opensquad 0.1.17

package/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 squad'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 squad.
+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 squad.
+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 squad'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 squad'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.jpg` not `image1.jpg`
+- 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/skills/imgbb-uploader/SKILL.md

@@ -0,0 +1,73 @@
+---
+name: imgbb-uploader
+description: >
+  Upload local JPG/JPEG/PNG images to imgBB and return public URLs for downstream use.
+  Useful for email HTML, landing pages, and any workflow that needs externally hosted images.
+description_pt-BR: >
+  Faz upload de imagens JPG/JPEG/PNG locais para o imgBB e retorna URLs publicas para uso posterior.
+  Util para email HTML, landing pages e qualquer fluxo que precise de imagens hospedadas externamente.
+description_es: >
+  Sube imagenes JPG/JPEG/PNG locales a imgBB y devuelve URLs publicas para uso posterior.
+  Util para email HTML, landing pages y cualquier flujo que necesite imagenes alojadas externamente.
+type: script
+version: "1.0.0"
+script:
+  path: scripts/upload.js
+  runtime: node
+  invoke: "node --env-file=.env {skill_path}/scripts/upload.js --images \"{images}\" --output \"{output}\""
+env:
+  - IMGBB_API_KEY
+categories: [images, hosting, automation]
+---
+
+# imgBB Uploader
+
+## When to use
+
+Use this skill when a workflow needs public image URLs instead of local files. Typical cases include HTML email, web pages, CMS publishing, or any channel that renders `<img src="https://...">` from a hosted asset.
+
+## Instructions
+
+### Workflow
+
+1. Prepare an ordered list of local JPG/JPEG/PNG files.
+2. Run the upload script with `--images` and an `--output` path.
+3. Read the generated JSON manifest and pass the returned URLs to the next step.
+
+### Command
+
+```bash
+node --env-file=.env {skill_path}/scripts/upload.js \
+  --images "slide-01.jpg,slide-02.png,slide-03.jpg" \
+  --output "output/image-urls.json"
+```
+
+### Output
+
+The script writes a JSON file with one entry per uploaded image:
+
+```json
+{
+  "status": "uploaded",
+  "count": 3,
+  "images": [
+    {
+      "file": "slide-01.jpg",
+      "absolutePath": "C:/repo/output/slide-01.jpg",
+      "url": "https://i.ibb.co/.../slide-01.jpg",
+      "deleteUrl": "https://ibb.co/..."
+    }
+  ]
+}
+```
+
+### Constraints
+
+- Input images: JPG, JPEG, or PNG
+- `IMGBB_API_KEY` must exist in `.env`
+- The script uploads immediately; there is no dry-run mode
+
+## Available operations
+
+- **Upload image batch** -- Upload one or more local JPG/JPEG/PNG files
+- **Manifest generation** -- Save a structured JSON file with public URLs for downstream steps

package/skills/imgbb-uploader/scripts/upload.js

@@ -0,0 +1,125 @@
+#!/usr/bin/env node
+
+import { readFileSync, writeFileSync } from 'node:fs';
+import { basename, extname, resolve } from 'node:path';
+
+export function parseArgs(argv) {
+  const args = {
+    images: [],
+    output: null,
+  };
+
+  for (let index = 2; index < argv.length; index += 1) {
+    const token = argv[index];
+
+    if (token === '--images' && index + 1 < argv.length) {
+      args.images = argv[index + 1]
+        .split(',')
+        .map((imagePath) => imagePath.trim())
+        .filter(Boolean);
+      index += 1;
+      continue;
+    }
+
+    if (token === '--output' && index + 1 < argv.length) {
+      args.output = argv[index + 1];
+      index += 1;
+      continue;
+    }
+
+    if (token === '--help' || token === '-h') {
+      printHelp();
+      process.exit(0);
+    }
+  }
+
+  return args;
+}
+
+function printHelp() {
+  console.log([
+    'Usage: node --env-file=.env upload.js --images "slide-01.jpg,slide-02.png" --output "output/image-urls.json"',
+    '',
+    'Arguments:',
+    '  --images   Comma-separated JPG/JPEG/PNG file list',
+    '  --output   JSON manifest path to write',
+  ].join('\n'));
+}
+
+export function assertSupportedExtension(imagePath) {
+  const extension = extname(imagePath).toLowerCase();
+  if (!['.jpg', '.jpeg', '.png'].includes(extension)) {
+    throw new Error(`Unsupported image format for '${imagePath}'. Use JPG, JPEG, or PNG.`);
+  }
+}
+
+export async function uploadToImgBB(imagePath, apiKey) {
+  const absolutePath = resolve(imagePath);
+  const fileBuffer = readFileSync(absolutePath);
+  const base64Image = fileBuffer.toString('base64');
+  const form = new FormData();
+  form.append('key', apiKey);
+  form.append('image', base64Image);
+
+  const response = await fetch('https://api.imgbb.com/1/upload', {
+    method: 'POST',
+    body: form,
+  });
+
+  if (!response.ok) {
+    throw new Error(`imgBB upload failed [${response.status}]: ${await response.text()}`);
+  }
+
+  const json = await response.json();
+  if (!json.success) {
+    throw new Error(`imgBB upload failed: ${JSON.stringify(json)}`);
+  }
+
+  return {
+    file: basename(imagePath),
+    absolutePath,
+    url: json.data.url,
+    deleteUrl: json.data.delete_url,
+  };
+}
+
+export async function main() {
+  const args = parseArgs(process.argv);
+  const apiKey = process.env.IMGBB_API_KEY;
+
+  if (!apiKey) {
+    throw new Error('IMGBB_API_KEY is not set in environment.');
+  }
+
+  if (!args.images.length) {
+    throw new Error('--images is required.');
+  }
+
+  if (!args.output) {
+    throw new Error('--output is required.');
+  }
+
+  const images = [];
+  for (const imagePath of args.images) {
+    assertSupportedExtension(imagePath);
+    images.push(await uploadToImgBB(imagePath, apiKey));
+  }
+
+  const manifest = {
+    status: 'uploaded',
+    count: images.length,
+    images,
+  };
+
+  writeFileSync(resolve(args.output), `${JSON.stringify(manifest, null, 2)}\n`);
+  console.log(JSON.stringify(manifest, null, 2));
+}
+
+const isMain = process.argv[1] === new URL(import.meta.url).pathname;
+
+if (isMain) {
+  main().catch((error) => {
+    console.error(`\n❌ ${error.message}`);
+    process.exit(1);
+  });
+}

package/skills/instagram-publisher/README.md

@@ -0,0 +1,36 @@
+# Instagram Publisher Operational Notes
+
+## Facebook Page token resolution via INSTAGRAM_ACCESS_TOKEN
+
+In multi-brand workspaces, `FACEBOOK_PAGE_ACCESS_TOKEN` may not belong to the page selected for the current squad. When that happens, Facebook cross-post can fail even if Instagram publishing succeeds.
+
+The supported operational fallback is:
+
+1. Keep `FACEBOOK_PAGE_ID` configured for the target page.
+2. Keep `INSTAGRAM_ACCESS_TOKEN` configured with access to the connected Facebook assets.
+3. Let the publisher resolve the effective Page token dynamically through `GET /me/accounts` using `INSTAGRAM_ACCESS_TOKEN`.
+4. Use the resolved page-specific `access_token` for unpublished photo upload and final `/feed` post creation.
+
+## Why this matters
+
+Facebook unpublished photo uploads must run as the target Page itself. A token from another page, or a generic token that does not resolve to the target page, can lead to failures such as:
+
+- wrong page context
+- text-only posts
+- single-photo posts when an album was expected
+- Graph API permission or object errors during verification
+
+## Recommended operational sequence
+
+1. Publish Instagram normally.
+2. For Facebook cross-post, resolve the target Page token from `INSTAGRAM_ACCESS_TOKEN` through `/me/accounts`.
+3. Upload each approved JPG as unpublished media to `/{page-id}/photos`.
+4. If Facebook rejects the remote image URL with errors such as `Missing or invalid image file`, retry the same unpublished upload with the local JPG binary instead of the hosted URL.
+5. Create the final feed post with `attached_media` as a JSON array in the request body.
+6. Verify the result by checking that the post appears as `media_type: album` with the expected subattachment count.
+
+## Current policy
+
+- Prefer JPG/JPEG assets for publishing flows.
+- Treat `INSTAGRAM_ACCESS_TOKEN` as the bootstrap credential for resolving the effective Facebook Page token when needed.
+- Do not assume the raw `FACEBOOK_PAGE_ACCESS_TOKEN` is already the final token for the selected page in shared workspaces.

package/skills/instagram-publisher/SKILL.md

@@ -0,0 +1,231 @@
+---
+name: instagram-publisher
+description: >
+  Publishes Instagram carousel posts from local images, with optional Facebook Page cross-post.
+  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, retrieves the real post permalink, and can simultaneously
+  post to a connected Facebook Page using --facebook.
+description_pt-BR: >
+  Publica carrosséis do Instagram a partir de imagens locais, com cross-post opcional para Página do Facebook.
+  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, obtém o permalink real, e pode simultaneamente
+  publicar na Página do Facebook conectada usando --facebook.
+description_es: >
+  Publica carruseles de Instagram a partir de imágenes locales, con cross-post opcional a Página de Facebook.
+  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, obtiene el permalink real y puede publicar
+  simultáneamente en la Página de Facebook conectada usando --facebook.
+type: script
+version: "1.1.0"
+script:
+  path: scripts/publish.js
+  runtime: node
+  invoke: "node --env-file=.env {skill_path}/scripts/publish.js --images \"{images}\" --caption \"{caption}\""
+  invoke_facebook: "node --env-file=.env {skill_path}/scripts/publish.js --images \"{images}\" --caption \"{caption}\" --facebook"
+  invoke_facebook_only: "node --env-file=.env {skill_path}/scripts/publish.js --images \"{images}\" --caption \"{caption}\" --facebook --facebook-only"
+  invoke_playwright: "node {skill_path}/scripts/publish-playwright.js --images \"{images}\" --caption \"{caption}\" [--username \"{username}\"] [--password \"{password}\"] [--profile-dir \"{profile_dir}\"]"
+env:
+  - INSTAGRAM_ACCESS_TOKEN       # default key; can be replaced per squad via --instagram-access-token-env
+  - INSTAGRAM_USER_ID           # default key; can be replaced per squad via --instagram-user-id-env
+  - IMGBB_API_KEY
+  - FACEBOOK_PAGE_ID            # default key; can be replaced per squad via --facebook-page-id-env
+  - FACEBOOK_PAGE_ACCESS_TOKEN  # default key; can be replaced per squad via --facebook-page-access-token-env
+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 local JPG/JPEG or PNG 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 images per post.
+
+
+## Instructions
+
+### Workflow
+
+1. List JPG/JPEG or PNG files in `squads/{squad}/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 (add `--facebook` to also post to the connected Facebook Page):
+   ```
+   node --env-file=.env {skill_path}/scripts/publish.js \
+     --images "<comma-separated-ordered-paths>" \
+     --caption "<caption>" \
+     [--instagram-access-token-env "<ENV_VAR_NAME>"] \
+     [--instagram-user-id-env "<ENV_VAR_NAME>"] \
+     [--facebook-page-id-env "<ENV_VAR_NAME>"] \
+     [--facebook-page-access-token-env "<ENV_VAR_NAME>"] \
+     [--facebook]            # optional: also post to Facebook Page
+   ```
+   Add `--dry-run` to test the full flow without actually publishing.
+   If Instagram already published successfully but the Facebook cross-post failed, rerun only the Facebook step with `--facebook --facebook-only` to avoid duplicating the Instagram post.
+  If `createChildContainer` fails with a transient Graph API media error such as `OAuthException`, `Não é possível criar a mídia`, or `Falha ao criar imagem`, retry once before escalating with the same image set but a publish-safe caption: collapse excessive blank lines, strip smart quotes and other decorative punctuation, and remove raw URLs from the Instagram caption body. Validate that retry with `--dry-run` first.
+  If the final `publishMedia` call fails with Meta `code 4`, `error_subcode 2207051`, or `Application request limit reached` after containers were created successfully, stop retrying the live API path. Treat it as a Graph API restriction for the current app/account pair and switch to Meta Business Suite with the same approved assets and caption.
+5. On success: save the post URL and post ID to the step output file.
+6. If this publish belongs to an Opensquad run, treat the dashboard as part of finalization: once the last selected output for the run is complete, regenerate `run-dashboard.html` and `run-dashboard.data.json` for the same run folder. If static publish is enabled in the squad config, it must publish automatically as part of that same finalization pass.
+7. On failure: display the error and ask the user how to proceed.
+
+Do not open a second approval prompt only for the run-dashboard. After the user approves the live publish, publish first and then report that the dashboard finalization was executed.
+
+### Per-squad credential routing
+
+When the same workspace operates multiple brands, do not force all squads to publish through the same account.
+
+The publish script accepts env-variable-name aliases so each squad can point to its own credentials while still loading secrets from the shared `.env` file.
+
+Example for a MusicPlay.club squad:
+
+```
+node --env-file=.env {skill_path}/scripts/publish.js \
+  --images "slide-01.jpg,slide-02.jpg" \
+  --caption "..." \
+  --instagram-access-token-env "MUSICPLAY_INSTAGRAM_ACCESS_TOKEN" \
+  --instagram-user-id-env "MUSICPLAY_INSTAGRAM_USER_ID" \
+  --facebook-page-id-env "MUSICPLAY_FB_PAGE_ID" \
+  --facebook-page-access-token-env "MUSICPLAY_FACEBOOK_PAGE_ACCESS_TOKEN" \
+  --facebook
+```
+
+If the workspace already has brand-specific env keys, use them. Do not default back to generic `INSTAGRAM_ACCESS_TOKEN` or `INSTAGRAM_USER_ID` for a different brand just because the publish command would still run.
+
+If these flags are omitted, the script falls back to the default keys:
+
+- `INSTAGRAM_ACCESS_TOKEN`
+- `INSTAGRAM_USER_ID`
+- `FACEBOOK_PAGE_ID`
+- `FACEBOOK_PAGE_ACCESS_TOKEN`
+
+### Facebook Page token resolution in multi-brand workspaces
+
+In a workspace that operates more than one Facebook Page, do not assume that a single stored `FACEBOOK_PAGE_ACCESS_TOKEN` already belongs to the page selected for the current squad.
+
+The publisher now resolves the effective token for the requested `FACEBOOK_PAGE_ID` before uploading unpublished photos:
+
+1. If the configured Facebook token already identifies as the target Page, it is used directly.
+2. If not, the publisher tries to resolve the target Page through `/me/accounts` using the available shared Instagram/user token.
+3. If a matching page is found, the page-specific `access_token` returned by Meta is used for the Facebook cross-post.
+4. If no token can be resolved for the requested Page, the Facebook step is blocked instead of attempting to post with the wrong page context.
+
+If Facebook rejects an unpublished photo upload with errors such as `Missing or invalid image file`, do not stop at the hosted image URL path. Retry the same `/{page-id}/photos` upload using the local JPG/JPEG or PNG file as binary `source` while keeping the resolved Page token. Treat this as the default recovery path for remote-hosting incompatibilities.
+
+### Manual Meta Business Suite fallback
+
+When the Graph API path is blocked but the content is approved and ready:
+
+1. Open Meta Business Suite for the correct Page/account pair.
+2. Upload the already-approved image list in the same order used for the dry-run.
+3. Paste the approved caption without reintroducing raw source URLs into the Instagram body.
+4. Before the final confirmation click, verify that slide 1 is the cover and that the remaining slides kept the approved order.
+5. After publishing, record the final Instagram/Facebook URLs and post IDs in the run artifacts.
+6. If a wrong-order Instagram post was created, delete it before finalizing the run when permissions allow it. A wrong Facebook post may require stronger Page permissions to remove; document that residual issue instead of blocking closure forever.
+
+This matters because unpublished photo uploads on Facebook must be executed as the target Page itself. A token that belongs to another Page in the same workspace may still be valid, but it will fail with errors such as `Unpublished posts must be posted to a page as the page itself`.
+
+### Automated Browser-Based Fallback (Playwright)
+
+When the Graph API path is blocked by Meta App Review or rate limits (e.g. error `2207051` or `Application request limit reached`), you can automate the web publishing flow using the Playwright fallback script:
+
+```bash
+node skills/instagram-publisher/scripts/publish-playwright.js \
+  --images "{lista-dinamica-de-slides}" \
+  --caption "{legenda_completa}" \
+  [--username "{usuario}"] \
+  [--password "{senha}"] \
+  [--profile-dir "{diretorio_do_perfil_do_navegador}"]
+```
+
+This script:
+1. Launches a headful browser (Chrome) using a persistent profile directory (defaulting to `_opensquad/_browser_profile`).
+2. Leverages the persistent session to avoid daily login checks and cookie dialogs.
+3. Handles standard popup/dialog dismissals automatically (e.g., "Not Now" / "Agora não").
+4. Uploads all images at once as a carousel, and pastes the caption.
+5. Obtains the live URL and Post ID automatically upon successful posting.
+
+### Constraints
+
+- Images: JPG, JPEG, or PNG, 2-10 per carousel
+- Caption: max 2200 characters
+- Prefer a short publish-safe caption for the live Instagram API call: strong hook, practical body, CTA, hashtags at the end, and no raw source URLs in the caption body
+- Requires Instagram Business account (not Personal or Creator)
+- Rate limit: 25 API-published posts per 24 hours
+- Scheduling: not supported by this skill; use manual scheduling after dry-run if needed
+
+### Setup (first-time)
+
+Copy `.env.example` to `.env` and fill in the required variables. You can use the default keys below or namespaced keys per squad and pass their names with the `--*-env` flags:
+
+```
+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`
+   - `pages_manage_posts`    # required for Facebook cross-posting
+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
+- **Publish Carousel + Facebook** -- Same as above, plus cross-post to the connected Facebook Page (use `--facebook` flag)
+- **Facebook-only Recovery** -- Publish only the Facebook cross-post after a partial result, without reposting to Instagram (use `--facebook --facebook-only`)
+- **Dry Run** -- Test the full publishing flow without actually posting (use `--dry-run` flag)
+- **Image Upload** -- Upload local JPG or JPEG images to imgBB (requires API key)
+- **Status Check** -- Monitor media container processing status before publishing
+- **Playwright Fallback Publish** -- Automates publishing carousel posts via headful browser automation when the Graph API is blocked
+
+## Facebook cross-post setup
+
+To enable `--facebook`, add these variables to `.env`:
+
+```
+FACEBOOK_PAGE_ID=your-facebook-page-id
+FACEBOOK_PAGE_ACCESS_TOKEN=
+```
+
+The token must have the `pages_manage_posts` permission and should be a valid Page Access Token.
+
+If the stored token belongs to another Page in the same workspace, keep it only as a bootstrap credential and let the publisher resolve the final token for the target page dynamically via `/me/accounts`.