@growthub/cli 0.3.53 → 0.3.55

package/assets/worker-kits/growthub-postiz-social-v1/brands/growthub/brand-kit.md

@@ -0,0 +1,117 @@
+# Brand Kit — Growthub
+
+<!-- Reference example for the Postiz Social Media Studio. Use this to understand the expected format and detail level. -->
+
+---
+
+## Client Identity
+
+| Field | Value |
+|---|---|
+| Client Name | Growthub |
+| Client Slug | `growthub` |
+| Industry | Developer tools / AI agent infrastructure / SaaS |
+| Website | https://growthub.ai |
+| Primary Contact | Internal — Growthub marketing team |
+
+---
+
+## Social Media Presence
+
+| Platform | Handle | Followers | Current Status |
+|---|---|---|---|
+| X/Twitter | @growthubai | 3,200 | Active |
+| LinkedIn | Growthub (company page) | 1,800 | Active |
+| Bluesky | @growthub.ai | 400 | Growing |
+| GitHub | github.com/Growthub-ai | 2,100 stars | Active (open source) |
+
+---
+
+## Target Audience
+
+### Primary Audience
+
+| Attribute | Description |
+|---|---|
+| Age Range | 25–45 |
+| Gender | 60% male, 40% female |
+| Location | North America, Europe, English-speaking global |
+| Interests | AI agents, developer tools, automation, indie hacking, SaaS growth |
+| Pain Points | Complex agent orchestration, lack of open-source local-first alternatives, AI tool fatigue |
+| Content Preferences | Technical tutorials, tool comparisons, workflow examples, behind-the-scenes product builds |
+
+### Secondary Audience
+
+| Attribute | Description |
+|---|---|
+| Age Range | 18–25 |
+| Interests | Open source, hackathons, learning AI development |
+| Platform | GitHub, X/Twitter, Bluesky |
+
+---
+
+## Campaign Objectives
+
+| Objective | Metric | Target | Timeline |
+|---|---|---|---|
+| Developer awareness | GitHub stars | +500/quarter | Q2 2026 |
+| Community growth | Twitter/X followers | +200/month | Ongoing |
+| Thought leadership | LinkedIn impressions | 20,000/month | Q2 2026 |
+| Open-source adoption | CLI downloads | +1,000/month | Q2 2026 |
+
+---
+
+## Brand Voice
+
+| Attribute | Spec |
+|---|---|
+| Tone | Direct, technically credible, approachable. We explain without condescending. We ship without bragging. |
+| Personality | Builder-first. We're in the trenches using the tools we build. |
+| Words to Use | "build", "ship", "run", "local", "open", "agent", "workflow", "kit", "workspace" |
+| Words to Avoid | "disruptive", "AI-powered" (use "agent-native" instead), "revolutionary", "hack" |
+| Emoji Usage | Minimal — 0–1 on LinkedIn; 0–2 on X; 2–4 on Instagram |
+| CTA Style | Action verbs with immediate value: "Try it now", "Clone and run", "Read the docs", "Star on GitHub" |
+
+---
+
+## Content Theme Pillars
+
+| Pillar | Description | Platforms | % of Calendar |
+|---|---|---|---|
+| Product Builds | Behind-the-scenes of building Growthub features — architecture, decisions, tradeoffs | X, LinkedIn, GitHub | 35% |
+| Developer Tutorials | How to use Growthub kits, commands, and workflows in real workflows | X, LinkedIn, Bluesky | 30% |
+| Open Source | Open-source culture, contributions, partner project spotlights | X, Bluesky, GitHub | 20% |
+| Community | User projects, shoutouts, Q&A, polls | X, LinkedIn | 15% |
+
+---
+
+## Competitor Reference Accounts
+
+| Platform | Account | Why Reference |
+|---|---|---|
+| X/Twitter | @langchain | Strong developer community engagement, technical thread format |
+| LinkedIn | Anthropic company page | Consistent educational posting, thought leadership |
+| X/Twitter | @cursor_ai | Product-led content strategy, community responsiveness |
+
+---
+
+## Agency Context
+
+| Field | Value |
+|---|---|
+| Engagement Stage | Internal — first-party reference kit |
+| Monthly Retainer | N/A (internal) |
+| Campaign Budget | N/A |
+| Reporting Cadence | Monthly analytics brief to marketing team |
+
+---
+
+## CRM Notes
+
+Internal reference account. Used to demonstrate the kit's brand kit format and example output quality. Not a live client account.
+
+---
+
+## DELIVERABLES LOG
+
+<!-- - YYYY-MM-DD | Social Media Campaign Package v1 — Growthub Q2 2026 Launch | output/growthub/q2-2026-launch/ -->

package/assets/worker-kits/growthub-postiz-social-v1/bundles/growthub-postiz-social-v1.json

@@ -0,0 +1,52 @@
+{
+  "schemaVersion": 2,
+  "bundle": {
+    "id": "growthub-postiz-social-v1",
+    "version": "1.0.0",
+    "kitId": "growthub-postiz-social-v1",
+    "workerId": "postiz-social-operator"
+  },
+  "briefType": "postiz-social-media-campaign",
+  "publicExampleBrandPaths": [
+    "brands/growthub/brand-kit.md"
+  ],
+  "requiredFrozenAssets": [
+    "QUICKSTART.md",
+    ".env.example",
+    "skills.md",
+    "output-standards.md",
+    "runtime-assumptions.md",
+    "validation-checklist.md",
+    "workers/postiz-social-operator/CLAUDE.md",
+    "brands/_template/brand-kit.md",
+    "brands/growthub/brand-kit.md",
+    "brands/NEW-CLIENT.md",
+    "setup/clone-fork.sh",
+    "setup/verify-env.mjs",
+    "setup/check-deps.sh",
+    "output/README.md",
+    "templates/social-campaign-brief.md",
+    "templates/content-calendar.md",
+    "templates/platform-publishing-plan.md",
+    "templates/caption-copy-deck.md",
+    "templates/analytics-brief.md",
+    "templates/scheduling-manifest.md",
+    "templates/client-proposal.md",
+    "examples/social-campaign-sample.md",
+    "examples/content-calendar-sample.md",
+    "examples/analytics-brief-sample.md",
+    "examples/client-proposal-sample.md",
+    "docs/postiz-fork-integration.md",
+    "docs/platform-coverage.md",
+    "docs/ai-caption-layer.md",
+    "docs/bullmq-queue-layer.md",
+    "growthub-meta/README.md",
+    "growthub-meta/kit-standard.md"
+  ],
+  "optionalPresets": [],
+  "export": {
+    "folderName": "growthub-agent-worker-kit-postiz-social-v1",
+    "zipFileName": "growthub-agent-worker-kit-postiz-social-v1.zip"
+  },
+  "activationModes": ["export"]
+}

package/assets/worker-kits/growthub-postiz-social-v1/docs/ai-caption-layer.md

@@ -0,0 +1,118 @@
+# AI Caption Layer
+
+**Methodology for AI-assisted caption generation in the Postiz Social Media Operator.**
+
+---
+
+## Overview
+
+The AI caption layer produces A/B/C caption variants for every post in the content calendar. This document defines the tone profiles, variant construction rules, and quality bar applied to every caption draft.
+
+The agent generates captions using:
+1. The brand kit's voice guidelines (`brands/<client-slug>/brand-kit.md`)
+2. The platform tone profiles defined in this document
+3. The theme pillar context from the Social Campaign Brief
+4. The character limits and hashtag rules from `docs/platform-coverage.md`
+
+---
+
+## Platform Tone Profiles
+
+| Platform | Tone | Voice | Avoid |
+|---|---|---|---|
+| Instagram | Visual-first, aspirational, authentic | First-person POV, sensory language, short punchy sentences | Corporate jargon, excessive hashtags, stock-photo clichés |
+| LinkedIn | Professional, insight-driven, confident | Data-backed claims, industry terminology, no jargon | Salesy language, superlatives without proof, informal slang |
+| TikTok | Casual, trend-aware, energetic, hook-first | Gen Z cadence, pattern interrupt, hook in first 2 words | Formal tone, long sentences, no emoji, corporate speak |
+| X/Twitter | Concise, punchy, opinionated | Declarative sentences, take-first, thread-opening hooks | Wishy-washy hedging, long-winded intros, excessive hashtags |
+| Pinterest | Aspirational, instructional, keyword-rich | Descriptive, actionable verbs, lifestyle context | Vague descriptions, missing context, non-searchable language |
+| Facebook | Conversational, community-first, warm | Inclusive "we/our", questions, local/personal context | Overly promotional, algorithm-bait language |
+| Bluesky | Direct, open-web-aware, intellectual | Concise, tech-savvy, first-principles reasoning | Overly polished PR-speak, platform-specific references |
+| Mastodon | Community-focused, inclusive, decentralization-aware | Plain language, CamelCase hashtags for accessibility | Algorithmic optimization language, commercial urgency |
+| Reddit | Authentic, community-native, contribution-first | Reddit idioms where appropriate, value-first, no self-promotion optics | Obvious promotional tone, link dumps without context |
+
+---
+
+## Variant Construction Rules
+
+### Variant A — Direct / Factual
+
+- Lead with the core fact, data point, or product statement
+- Second sentence: supporting evidence or context
+- Third sentence (if length allows): CTA
+- Tone: confident, no hedging language
+- Use numbers when available: "78% of marketers say..." outperforms "many marketers say..."
+
+**Structure template:**
+```
+[Core claim or insight.] [Evidence or context.] [CTA verb phrase.]
+```
+
+### Variant B — Storytelling / Narrative
+
+- Open with a scene, scenario, or relatable before-state
+- Middle: transition to the insight or product context
+- Close: resolution or CTA
+- Tone: warm, specific, first-person or second-person
+
+**Structure template:**
+```
+[Scene/scenario that the audience recognizes.] [Transition: "That's when we realized..." / "Here's what changed..."] [Insight or product context.] [CTA.]
+```
+
+### Variant C — Question / Engagement Hook
+
+- Open with a direct question or provocative statement
+- The question must be genuinely answerable in comments
+- Follow with 1–2 supporting sentences before the CTA
+- Tone: curious, conversational, invites participation
+
+**Structure template:**
+```
+[Question the audience wants to answer?] [Context that makes the question worth answering.] [CTA that directs to comment or click.]
+```
+
+---
+
+## Character Limit Compliance
+
+Every caption variant must be checked against the platform character limit before being considered complete. The agent must note the character count in the Caption Copy Deck entry.
+
+| Platform | Hard Limit | Target Range | Notes |
+|---|---|---|---|
+| Instagram | 2,200 | ≤150 (above fold) / up to 500 for educational | First 125 chars are critical — fold cuts here on mobile |
+| LinkedIn | 3,000 | 150–300 for opening hook | Algorithm may suppress posts with very short captions on company pages |
+| TikTok | 2,200 | ≤150 | First 150 chars visible before "more" |
+| X/Twitter | 280 | ≤240 | Leave 40 chars for RT space |
+| Pinterest | 500 | 100–300 | Keyword density matters for discovery |
+| Bluesky | 300 | ≤280 | Hard limit — truncation destroys message |
+| Mastodon | 500 | ≤400 | Instance limits may vary |
+| Reddit | Variable | Long-form (300–1000 words) for text posts | Subreddit rules override; check before drafting |
+
+---
+
+## Emoji Usage Guidelines
+
+| Platform | Usage Level | Notes |
+|---|---|---|
+| Instagram | Moderate (2–5 per caption) | Use as visual separators and tone enhancers |
+| LinkedIn | Minimal (0–2 per post) | Bullets acceptable on company pages; personal posts: 0–1 |
+| TikTok | Liberal (5–10) | Emoji-first hooks are platform-native |
+| X/Twitter | Minimal (0–2) | One emoji at start of tweet is acceptable; more feels crowded |
+| Pinterest | None to minimal (0–2) | Focuses on keyword discoverability |
+| Facebook | Moderate (2–4) | Consistent with casual community tone |
+| Bluesky | Minimal (0–2) | Text-first culture |
+| Mastodon | None to minimal | Accessibility-first: screen readers read emoji alt-text |
+
+---
+
+## AI Caption Quality Bar
+
+A complete caption variant must:
+
+1. **Stay within character limits** — hard requirement, not optional
+2. **Have an explicit CTA** — at minimum: "Learn more", "Link in bio", "Comment below", "Drop your thoughts"
+3. **Match platform tone** — LinkedIn caption must not read like a TikTok caption
+4. **Reference the content** — caption must connect to the media asset or post topic
+5. **Not open with "I"** — Instagram algorithm and general best practice: lead with the hook, not the subject
+6. **Avoid placeholder language** — no "[INSERT BRAND NAME]" fragments in the final copy deck
+7. **Be meaningfully different across A/B/C** — changing one word does not constitute a variant

package/assets/worker-kits/growthub-postiz-social-v1/docs/bullmq-queue-layer.md

@@ -0,0 +1,157 @@
+# BullMQ Queue Layer
+
+**Scheduling manifest format and queue architecture for Postiz API submission.**
+
+---
+
+## Overview
+
+Postiz uses BullMQ (backed by Redis) as its job queue for scheduled post publishing. When this kit generates a scheduling manifest, it produces a JSON file that can be submitted to the Postiz API's bulk scheduling endpoint. The API enqueues each post with a delay calculated from `scheduledAt - now()`.
+
+---
+
+## Scheduling Manifest Format
+
+The full JSON format for the scheduling manifest:
+
+```json
+{
+  "postizSchedulingManifest": {
+    "version": "1.0",
+    "workspaceId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
+    "generatedAt": "2026-04-15T10:00:00-05:00",
+    "dryRun": false,
+    "posts": [
+      {
+        "postId": "urbancycle-20260420-instagram-001",
+        "platform": "instagram",
+        "scheduledAt": "2026-04-20T09:00:00-05:00",
+        "content": "Building for the long game means planting seeds you won't harvest for years. At Urban Cycle, we're still running routes we mapped in 2021. Where are you building today that you won't see pay off until 2028? Share in the comments — we read every one. #urbanmobility #sustainableliving #cycling",
+        "mediaAssets": [
+          {
+            "type": "image",
+            "path": "assets/2026-04-20-instagram-001.jpg",
+            "altText": "Urban Cycle team on a community cycling route, morning light"
+          }
+        ],
+        "tags": ["#urbanmobility", "#sustainableliving", "#cycling"],
+        "status": "pending"
+      }
+    ]
+  }
+}
+```
+
+---
+
+## Field Reference
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `version` | string | Yes | Manifest version — always `"1.0"` for this kit |
+| `workspaceId` | string (UUID) | Yes | Postiz workspace UUID from Settings → Workspace |
+| `generatedAt` | string (ISO 8601) | Yes | Manifest generation timestamp |
+| `dryRun` | boolean | Yes | `true` for agent-only mode (no API submission); `false` for live submission |
+| `posts[].postId` | string | Yes | Unique post identifier — see naming convention below |
+| `posts[].platform` | string | Yes | Postiz platform integration ID (from `docs/platform-coverage.md`) |
+| `posts[].scheduledAt` | string (ISO 8601) | Yes | Target publish timestamp with timezone offset |
+| `posts[].content` | string | Yes | Full caption text (selected A/B/C variant) |
+| `posts[].mediaAssets` | array | No | Media asset references (empty array if text-only post) |
+| `posts[].mediaAssets[].type` | string | Yes | `"image"` \| `"video"` \| `"carousel"` |
+| `posts[].mediaAssets[].path` | string | Yes | Relative path to asset file |
+| `posts[].mediaAssets[].altText` | string | No | Accessibility alt text for images |
+| `posts[].tags` | array | No | Hashtag strings (with `#` prefix) |
+| `posts[].status` | string | Yes | Always `"pending"` in generated manifest |
+
+---
+
+## Post ID Naming Convention
+
+```
+<client-slug>-<YYYYMMDD>-<platform>-<sequence>
+```
+
+| Part | Rule | Example |
+|---|---|---|
+| client-slug | Lowercase, hyphenated, no special chars | `urban-cycle` |
+| YYYYMMDD | Scheduled post date | `20260420` |
+| platform | Postiz platform ID | `instagram` |
+| sequence | 3-digit zero-padded sequence | `001`, `002`, `003` |
+
+**Example:** `urban-cycle-20260420-instagram-001`
+
+---
+
+## Timestamp Format
+
+All `scheduledAt` values must use ISO 8601 format with explicit timezone offset:
+
+```
+YYYY-MM-DDTHH:MM:SS±HH:MM
+```
+
+**Examples:**
+- `2026-04-20T09:00:00-05:00` — 9am CDT
+- `2026-04-20T09:00:00-04:00` — 9am EDT
+- `2026-04-20T14:00:00Z` — 2pm UTC
+
+Never use `Z` for local time unless the workspace timezone is explicitly UTC.
+
+---
+
+## Submission to Postiz API
+
+```bash
+# Submit the scheduling manifest to Postiz bulk scheduling endpoint
+curl -X POST "${POSTIZ_API_URL}/api/v1/posts/bulk" \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer <jwt-token>" \
+  -d @scheduling-manifest.json
+
+# Verify queue health after submission
+curl "${POSTIZ_API_URL}/api/v1/queue/health" \
+  -H "Authorization: Bearer <jwt-token>"
+```
+
+Obtain the JWT token from Postiz admin UI → Settings → API Keys, or via `POST /api/v1/auth/login`.
+
+---
+
+## Queue Monitoring
+
+After submitting the manifest, monitor the BullMQ queue:
+
+1. **Postiz admin UI** → Queue Management: shows pending, active, completed, and failed jobs
+2. **API endpoint**: `GET /api/v1/queue/health` — returns queue stats
+3. **Redis CLI** (advanced): `redis-cli monitor` — raw job events
+
+### Job States
+
+| State | Meaning |
+|---|---|
+| `waiting` | Job is queued, delay has not expired |
+| `active` | Job is currently being processed (publishing now) |
+| `completed` | Post was published successfully |
+| `failed` | Post failed to publish — check error in admin UI |
+| `delayed` | Job is waiting for `scheduledAt` time |
+
+### Retry Logic
+
+Postiz retries failed publish jobs 3 times with exponential backoff by default:
+- Attempt 1: immediately after failure
+- Attempt 2: 5 seconds after first retry
+- Attempt 3: 30 seconds after second retry
+
+Failed jobs after 3 attempts are moved to the dead letter queue and visible in the admin UI → Failed Jobs.
+
+---
+
+## Dry-Run Mode
+
+When `dryRun: true` in the manifest header:
+- The manifest is produced as a JSON file but is **not submitted to the Postiz API**
+- All `status` fields remain `"pending"`
+- The manifest can be reviewed and submitted manually
+- Use `dryRun: true` in all agent-only mode sessions
+
+The agent must set `dryRun: true` automatically when the Postiz API is not reachable or when execution mode is `agent-only`.

package/assets/worker-kits/growthub-postiz-social-v1/docs/platform-coverage.md

@@ -0,0 +1,97 @@
+# Platform Coverage
+
+**Supported Postiz integration IDs, format specs, and character limits.**
+
+**Frozen at kit creation: 2026-04-15. Update when Postiz adds new platform integrations.**
+
+---
+
+## Platform Reference Table
+
+| Platform | Postiz ID | Auth Method | Post Types | Char Limit | Image Spec | Video Spec |
+|---|---|---|---|---|---|---|
+| Instagram | `instagram` | Meta OAuth | image, video, reel, story, carousel | 2,200 | 1080×1080 (square), 1080×1350 (portrait) | 1080×1920 (reels), MP4, ≤90s |
+| LinkedIn | `linkedin` | LinkedIn OAuth | text, image, video, document/carousel | 3,000 | 1200×627, PNG/JPG | MP4, ≤10 min |
+| TikTok | `tiktok` | TikTok OAuth | video only | 2,200 | — | 1080×1920, MP4/MOV, 15s–10min |
+| X (Twitter) | `twitter` | Twitter OAuth 2.0 | text, image, video, thread | 280 | 1200×675, ≤5MB | MP4/MOV, ≤2min 20s |
+| YouTube | `youtube` | Google OAuth | video (long-form), shorts | N/A | Thumbnail: 1280×720 | MP4, any length; Shorts ≤60s, 1080×1920 |
+| Pinterest | `pinterest` | Pinterest OAuth | image, video, idea pin | 500 | 1000×1500 (2:3 ratio) | MP4, 4s–15min |
+| Reddit | `reddit` | Reddit OAuth | text, image, video, link | — subreddit rules | Varies by subreddit | MP4, ≤15min |
+| Facebook | `facebook` | Meta OAuth | text, image, video, reel, story, carousel | 63,206 | 1200×628, PNG/JPG | MP4, ≤240min |
+| Bluesky | `bluesky` | AT Protocol credentials | text, image, video | 300 | Up to 4 images, 1×1 to 3×4 | MP4, ≤60s |
+| Mastodon | `mastodon` | OAuth (instance-specific) | text, image, video, poll | 500 (instance-configurable) | PNG/JPG/GIF/WebP | MP4/WebM/MOV |
+| Slack | `slack` | Slack OAuth | text, image, file | — | PNG/JPG/GIF | MP4 |
+| Telegram | `telegram` | Telegram Bot API token | text, image, video, document | 4,096 | JPEG, ≤10MB | MP4, ≤50MB |
+| Discord | `discord` | Discord Bot token | text, image, video, embed | 2,000 | PNG/JPG/GIF, ≤8MB | MP4, ≤8MB |
+| Threads | `threads` | Meta OAuth | text, image, video | 500 | 1:1 square; 4:5 portrait | MP4, ≤5min |
+| Dribbble | `dribbble` | Dribbble OAuth | image, video | — | PNG/JPG/GIF, ≤30MB | — |
+| Tumblr | `tumblr` | Tumblr OAuth | text, image, video, audio | — | PNG/JPG/GIF | MP4 |
+| Medium | `medium` | Medium OAuth | article (long-form markdown) | — | Embedded images | — |
+| DEV.to | `devto` | DEV API key | article (markdown) | — | Embedded images | — |
+| Hashnode | `hashnode` | Hashnode API key | article (markdown) | — | Embedded images | — |
+| Lemmy | `lemmy` | Lemmy credentials | text, image, link | — | PNG/JPG | — |
+| Nostr | `nostr` | Nostr keypair | text, image | — | URLs (no direct upload) | — |
+
+---
+
+## Platform Selection Guidance
+
+### Audience Demographics (2026 data — update when brand kit specifies more precise data)
+
+| Platform | Primary Demographic | Dominant Use Case |
+|---|---|---|
+| Instagram | 18–34 (55% female) | Visual branding, lifestyle, product showcase |
+| LinkedIn | 25–55 (professional) | B2B, thought leadership, hiring |
+| TikTok | 18–34 | Short-form entertainment, product discovery |
+| X/Twitter | 18–49 (male-skewed) | News, opinion, live commentary |
+| YouTube | All ages (18–49 core) | Education, reviews, entertainment |
+| Pinterest | 25–44 (female-skewed 70%) | Discovery, DIY, home, fashion, recipes |
+| Reddit | 18–49 (male-skewed) | Community discussion, niche interests |
+| Facebook | 35–65 | Community groups, local business, events |
+| Bluesky | 18–40 (tech-forward) | Open protocol social, tech and media |
+| Mastodon | 25–45 (tech-forward) | Open source, decentralized, privacy-aware |
+| LinkedIn | — | — |
+
+---
+
+## Post Type Compatibility Matrix
+
+| Post Type | instagram | linkedin | tiktok | twitter | youtube | pinterest | reddit | facebook | bluesky |
+|---|---|---|---|---|---|---|---|---|---|
+| Static Image | ✓ | ✓ | ✗ | ✓ | ✗ | ✓ | ✓ | ✓ | ✓ |
+| Video | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
+| Carousel / Slides | ✓ | ✓ | ✗ | ✗ | ✗ | ✓ | ✗ | ✓ | ✗ |
+| Text Only | ✗ | ✓ | ✗ | ✓ | ✗ | ✗ | ✓ | ✓ | ✓ |
+| Story | ✓ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✓ | ✗ |
+| Reel / Short | ✓ | ✗ | ✓ | ✗ | ✓ (Shorts) | ✗ | ✗ | ✓ | ✗ |
+| Long-form Article | ✗ | ✓ (newsletter) | ✗ | ✗ | ✗ | ✗ | ✓ | ✗ | ✗ |
+
+---
+
+## Hashtag Best Practices by Platform
+
+| Platform | Recommended Count | Strategy |
+|---|---|---|
+| Instagram | 3–5 | Mix niche + medium-volume (avoid over-tagging) |
+| LinkedIn | 3–5 | Professional and industry-specific |
+| TikTok | 3–6 | Mix trending sounds + niche tags |
+| X/Twitter | 1–2 | In-text placement, campaign hashtags |
+| Pinterest | 2–3 | Keyword-based for discoverability |
+| Bluesky | 0–2 | Contextual only, rarely used |
+| Mastodon | 2–4 | CamelCase for accessibility |
+| Reddit | 0 | Subreddit flair instead |
+
+---
+
+## Posting Time Recommendations
+
+*Based on general industry data. Override with client's own analytics if available.*
+
+| Platform | Weekday Best Times (ET) | Weekend |
+|---|---|---|
+| Instagram | Mon–Fri: 9–11am, 6–8pm | Sat: 10am–12pm |
+| LinkedIn | Tue–Thu: 8–10am, 12pm | Minimal weekend activity |
+| TikTok | Mon–Fri: 7–9am, 7–9pm | Sat–Sun: 11am–1pm |
+| X/Twitter | Mon–Fri: 8–10am, 12–2pm | Limited |
+| Facebook | Tue–Thu: 9am–12pm | Sat: 12–1pm |
+| Pinterest | Sat–Sun: 2–4pm, 8–11pm | All day |

package/assets/worker-kits/growthub-postiz-social-v1/docs/postiz-fork-integration.md

@@ -0,0 +1,143 @@
+# Postiz Fork Integration
+
+**How this kit integrates with the Postiz open-source social media platform.**
+
+---
+
+## What Postiz Is
+
+[Postiz](https://github.com/gitroomhq/postiz-app) is an open-source, self-hosted social media scheduling and automation platform built on NestJS + Next.js. It supports 28+ social media platforms and ships with a BullMQ job queue, multi-workspace management, AI caption generation, media upload, and a public REST API.
+
+GitHub: https://github.com/gitroomhq/postiz-app
+License: MIT
+Stars: ~28,000+ (as of kit creation)
+
+---
+
+## Integration Architecture
+
+```
+growthub-postiz-social-v1 (this kit)
+  │
+  ├── workers/postiz-social-operator/CLAUDE.md
+  │     Agent operating law — drives campaign planning, caption drafts,
+  │     scheduling manifest generation, and analytics briefing
+  │
+  ├── setup/clone-fork.sh
+  │     Clones gitroomhq/postiz-app → ~/postiz-app
+  │     Runs docker compose up -d (starts Postiz + Redis + PostgreSQL)
+  │     Waits for API healthcheck at http://localhost:3000/api/healthcheck
+  │
+  ├── setup/verify-env.mjs
+  │     Checks fork existence, API reachability, POSTIZ_WORKSPACE_ID, ANTHROPIC_API_KEY
+  │
+  └── templates/scheduling-manifest.md
+        BullMQ-compatible JSON manifest format for bulk post scheduling
+        via POST /api/v1/posts/bulk
+```
+
+---
+
+## Service Topology
+
+When running in local-fork mode, Postiz operates as a Docker Compose stack:
+
+```
+postiz-app container (port 3000)
+  ├── NestJS API (apps/backend/)         ← REST API, BullMQ job scheduler
+  └── Next.js Frontend (apps/frontend/)  ← Admin UI, calendar view, analytics
+
+postiz-redis container (port 6379)
+  └── Redis                              ← BullMQ queue backend, session cache
+
+postiz-postgres container (port 5432)
+  └── PostgreSQL                         ← Posts, workspaces, platform credentials, analytics
+```
+
+All services are defined in `docker-compose.yml` at the fork root.
+
+---
+
+## Postiz API — Key Endpoints Used By This Kit
+
+| Endpoint | Method | Purpose |
+|---|---|---|
+| `/api/healthcheck` | GET | Verify Postiz is running |
+| `/api/v1/workspace` | GET | Retrieve workspace ID and metadata |
+| `/api/v1/posts/bulk` | POST | Submit scheduling manifest |
+| `/api/v1/posts/{id}` | GET | Verify a scheduled post |
+| `/api/v1/analytics` | GET | Retrieve engagement analytics |
+| `/api/v1/queue/health` | GET | Check BullMQ queue health |
+| `/api/v1/posts/ai/generate` | POST | AI caption generation (Postiz-side) |
+
+Authentication is via JWT bearer token. Obtain from Postiz admin UI → Settings → API Keys.
+
+---
+
+## Platform Integration Layer
+
+Platform integrations live under `libraries/nestjs-libraries/src/integrations/` in the Postiz repo. Each integration file:
+- Defines the OAuth flow for connecting the platform account
+- Implements `post()` for publishing content
+- Implements `analytics()` for pulling engagement data
+- Declares the integration ID (used as the `platform` field in scheduling manifests)
+
+When this kit generates a scheduling manifest, platform IDs must match the integration IDs in the running Postiz instance. See `docs/platform-coverage.md` for the full list.
+
+---
+
+## AI Caption Generation
+
+Postiz has its own AI caption generation endpoint (`/api/v1/posts/ai/generate`), activated when `OPENAI_API_KEY` or `ANTHROPIC_API_KEY` is set in the Postiz `.env`. This is **separate** from the agent-side caption drafting in this kit.
+
+**This kit's caption workflow:**
+- The `postiz-social-operator` agent drafts A/B/C caption variants using its own reasoning and the AI caption methodology in `docs/ai-caption-layer.md`
+- Postiz's own AI caption feature is available to the user independently in the admin UI
+- The kit does not call the Postiz AI endpoint — it produces its own caption drafts
+
+---
+
+## BullMQ Queue Behavior
+
+When a post is submitted to Postiz via `POST /api/v1/posts/bulk`:
+
+1. Postiz validates the payload against the workspace's connected platforms
+2. Each post is enqueued in BullMQ with a delay calculated from `scheduledAt - now()`
+3. When the delay expires, BullMQ triggers the `publish-post` job
+4. The job calls the platform integration's `post()` method
+5. On success: post marked as `published` in PostgreSQL
+6. On failure: retried up to 3 times (configurable), then moved to dead letter queue
+
+Monitor the queue via Postiz admin UI → Queue Management, or via `GET /api/v1/queue/health`.
+
+---
+
+## Workspace Isolation
+
+Postiz supports multiple workspaces. Each workspace has:
+- Its own set of connected platform accounts
+- Its own posting queue
+- Its own analytics data
+- A UUID (`workspaceId`) required in all API calls
+
+The `POSTIZ_WORKSPACE_ID` in this kit's `.env` must match the workspace configured in the Postiz admin UI. Get it from Settings → Workspace in the admin UI, or from `GET /api/v1/workspace`.
+
+---
+
+## Inspecting the Fork Before Planning
+
+Before generating any campaign or scheduling manifest, inspect the running Postiz instance:
+
+```bash
+# Verify all containers are running
+docker compose ps
+
+# Check API health
+curl http://localhost:3000/api/healthcheck
+
+# List connected platform integrations (requires auth)
+curl http://localhost:3000/api/v1/integrations \
+  -H "Authorization: Bearer <jwt-token>"
+```
+
+Do not generate scheduling manifests for platforms that are not connected and authorized in the Postiz admin UI. Unconnected platform posts will fail at publish time.