@growthub/cli 0.3.56 → 0.3.58

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

@@ -0,0 +1,132 @@
+# AI Caption Layer
+
+The AI caption layer is the operator's methodology for drafting platform-adapted captions at volume while preserving brand voice.
+
+The kit produces **A/B/C variants** for every post. Each variant is meaningfully different. This document defines what "meaningfully different" means and how to get there.
+
+---
+
+## Caption Source
+
+- Primary source: Claude (the agent running the operator). Uses the local `ANTHROPIC_API_KEY` only when explicitly configured for enhanced drafting.
+- Secondary source: Zernio's own caption service (not used by this kit).
+
+The kit produces captions deterministically from the agent. The Zernio account's AI configuration is never invoked as part of scheduled manifest creation.
+
+---
+
+## Variant Contract
+
+Every post in the Caption Copy Deck has exactly three variants:
+
+| Variant | Hook style | When to pick it |
+|---|---|---|
+| A — Direct | Declarative fact or benefit in the first line | Product announcements, educational content, lead gen |
+| B — Narrative | Story beat, anecdote, or "I / we used to..." opening | Brand building, founder voice, community posts |
+| C — Question | Question or provocation as the opener | Engagement-driven posts, polls, community prompts |
+
+Variants must differ in:
+
+- Opening hook
+- Structural rhythm (list vs. paragraph vs. question-answer)
+- Called-out angle (data, emotion, curiosity)
+
+Minor word swaps (e.g., "great" → "excellent") do not count as separate variants. If three variants cannot be meaningfully differentiated for a post, collapse it to one and note the reason in the Caption Copy Deck.
+
+---
+
+## Per-Platform Character Targets
+
+| Platform | Hard limit | Optimal target | Notes |
+|---|---|---|---|
+| `twitter` | 280 | 200–240 | Reserve space for quote-share |
+| `instagram` | 2,200 | 125–150 above the "more" fold | Emoji usage moderate |
+| `facebook` | 63,206 | 100–250 | Longer works but engagement peaks under 250 |
+| `linkedin` | 3,000 | 1,200–2,000 for thought leadership | First 210 chars are the preview |
+| `tiktok` | 2,200 | 100–150 | First 150 chars decide watch-through |
+| `youtube` | Title 100 / Description 5,000 | Title 55–65 / Description 1,500 | Put key benefit in title |
+| `pinterest` | 500 | 200–300 | Keyword-dense; no emoji |
+| `reddit` | Varies | Subreddit-native (read mods' pinned post) | No marketing voice |
+| `bluesky` | 300 | 180–240 | No hashtags, context only |
+| `threads` | 500 | 200–350 | Text-first, image secondary |
+| `googlebusiness` | 1,500 | 150–250 | Lead with action or offer |
+| `telegram` | 4,096 | 300–800 (channel posts) | Preview shows first 2 lines |
+| `snapchat` | 80 (snap overlay) | ≤60 | Must read without audio |
+| `whatsapp` | 1,024 | ≤200 | Personal tone |
+
+---
+
+## Hashtag Rules
+
+| Platform | Count | Rule |
+|---|---|---|
+| `instagram` | 3–5 | Mix branded + niche; skip filler (#love, #instagood) |
+| `linkedin` | 3–5 | Professional and topical only |
+| `tiktok` | 3–6 | Mix trending + niche; avoid banned tags |
+| `pinterest` | 2–3 | Keyword hashtags matched to pin description |
+| `twitter` | 1–2 | One branded max; one topical max |
+| `bluesky` | 0 | Platform convention is no hashtags |
+| `threads` | 0–1 | Hashtags used sparingly |
+| `reddit` | 0 | Hashtags read as marketing; remove them |
+| `googlebusiness` | 0 | Not used by platform |
+| `facebook` | 1–2 | Optional; brand-specific |
+| `youtube` | 3–5 in description, 1 in title if relevant | Descriptions tolerate more |
+| `telegram` | 0–2 | Channel-culture dependent |
+| `snapchat` | 0 | Not used by platform |
+| `whatsapp` | 0 | Not used by platform |
+
+---
+
+## Brand Voice Preservation
+
+Every variant must pass these guardrails drawn from the active brand kit (`brands/<client-slug>/brand-kit.md`):
+
+1. Tone matches the brand's voice spec (e.g., "direct, technically credible")
+2. No blocked words (from the brand kit's "Words to Avoid")
+3. Preferred words are represented where natural (from "Words to Use")
+4. Emoji usage respects per-platform limits from the brand kit
+5. CTA matches the client's approved CTA style
+
+If a variant cannot satisfy all five guardrails, regenerate — do not ship it.
+
+---
+
+## CTA Catalog
+
+Pick one CTA per post. "Learn more" is acceptable; blank is not. Examples mapped to common objectives:
+
+| Objective | CTA options |
+|---|---|
+| Brand awareness | "Follow for more", "Save for later", "Share with your team" |
+| Lead generation | "Get the guide", "Request a demo", "Join the waitlist" |
+| Engagement | "What's your take?", "Drop a comment", "Tag a friend" |
+| Product launch | "Try it today", "See what's new", "Book a walkthrough" |
+| Community | "Join the conversation", "Share your build", "Introduce yourself" |
+| Local (Google Business) | "Visit us today", "Claim the offer", "Call to book" |
+
+---
+
+## Media Notes in Captions
+
+If a post depends on a media asset (image, video, carousel, reel, short, story):
+
+- Include one line in the Media Notes column of the Content Calendar
+- Cite: dimensions, duration, required overlays, brand safe zones, version (landscape/portrait)
+- For carousels, note slide count and order of slides (1 = hook, last = CTA)
+- For videos, note captions-on-by-default requirement and soundtrack licensing status
+
+Captions must never describe content that the media does not contain.
+
+---
+
+## AI Enhancement Workflow
+
+When `ANTHROPIC_API_KEY` is present and the user asks for enhanced drafting:
+
+1. Draft the three variants with the rules above
+2. Run a quality pass asking: "which variant would an experienced social editor ship?"
+3. Revise the other two so they represent genuinely different angles — not alternate phrasings
+4. Score each variant against the brand voice guardrails
+5. Store scores in the Caption Copy Deck table
+
+This workflow runs entirely inside the agent. No calls go to Zernio for caption content generation.

package/assets/worker-kits/growthub-zernio-social-v1/docs/local-adapters.md

@@ -0,0 +1,123 @@
+# Local Adapters — IDE Matrix
+
+This kit is **IDE-agnostic by design**. The agent entrypoint (`workers/zernio-social-operator/CLAUDE.md`) is plain Markdown, the runtime calls Zernio's hosted REST API via Node's built-in `fetch()`, and no module inside the kit depends on any particular IDE's SDK.
+
+That means you can drive the operator from any local coding agent that supports either:
+
+1. A **Working Directory** config field (the canonical growthub-local primitive — see `docs/WORKER_KITS.md` at the repo root for details), or
+2. An **MCP server** config (for IDEs that speak the Model Context Protocol)
+
+---
+
+## Why no "new adapter" for this kit
+
+- **Zernio is hosted SaaS.** There is no self-hostable Zernio component, so a local adapter on the Zernio side would just wrap `fetch()`.
+- The `@paperclipai/adapter-*` packages registered in `server/src/adapters/registry.ts` implement the `ServerAdapterModule` interface — they are **agent executors** (Claude / Codex / Cursor / Gemini / OpenCode / Pi / Hermes), not downstream REST API wrappers. Adding Zernio to that registry would be a category error.
+- Zernio itself ships an official **MCP server** (bundled inside the `zernio-python` SDK: `pip install zernio-sdk[mcp]`) and a **Claude Code skill** (`npx clawhub@latest install zernio-api`). Both are complementary, not required.
+
+The result: this kit runs as-is under every local IDE listed below.
+
+---
+
+## Adapter Matrix
+
+| IDE / Adapter | Integration path | How to set up |
+|---|---|---|
+| **Claude Code** (CLI) | Working Directory + slash-command conventions | Point `--working-dir` at the exported kit folder; open the session and talk to `zernio-social-operator`. |
+| **Claude Desktop** | MCP server | Add Zernio's MCP server block (see `setup/install-mcp.mjs` for the JSON) to `~/Library/Application Support/Claude/claude_desktop_config.json` (Mac) or `%APPDATA%/Claude/claude_desktop_config.json` (Windows). |
+| **Codex** (OpenAI) | Working Directory | Point Codex at the exported kit folder. The operator law in `CLAUDE.md` works identically under Codex's reading model. |
+| **Cursor** | Working Directory + optional MCP | Open the exported folder as the Cursor workspace. Optionally add Zernio's MCP server to Cursor's MCP config (`~/.cursor/mcp.json`). |
+| **Gemini CLI** | Working Directory | Point Gemini at the exported kit folder. |
+| **OpenCode** | Working Directory | Point OpenCode at the exported kit folder. |
+| **Qwen Code CLI** | Working Directory | Point Qwen at the exported kit folder. |
+| **Open Agents** | Working Directory + durable runs | Wire the kit folder as the agent's workspace; `/zernio` flows map to Open Agents' prompt-session model. |
+| **Any MCP-compatible IDE** | MCP server | Use `setup/install-mcp.mjs` to print the Zernio MCP server config JSON; drop it into your IDE's MCP config file. |
+
+---
+
+## The Three Integration Layers (in order of simplicity)
+
+### Layer 1 — Working Directory only (always works, zero extra install)
+
+```
+growthub kit download growthub-zernio-social-v1
+# ⇒ ~/paperclip/kits/exports/growthub-agent-worker-kit-zernio-social-v1/
+
+# Mac / Linux
+open ~/paperclip/kits/exports/growthub-agent-worker-kit-zernio-social-v1
+# Windows PowerShell
+start $HOME\paperclip\kits\exports\growthub-agent-worker-kit-zernio-social-v1
+```
+
+Then:
+
+1. Open your IDE (Claude Code, Codex, Cursor, Gemini, OpenCode, Qwen)
+2. Point the Working Directory at that folder
+3. Tell the operator: *"Plan a 30-day Instagram + LinkedIn campaign for [brand]"*
+
+That's it. The 10-step workflow in `workers/zernio-social-operator/CLAUDE.md` runs regardless of which IDE is reading it.
+
+### Layer 2 — Zernio's official MCP server (opt-in, one-time install)
+
+When your IDE supports MCP (Claude Desktop, Cursor, any MCP-compatible client), plug in Zernio's own MCP server so the agent can call Zernio endpoints directly as tool calls instead of curl.
+
+```bash
+# Python runtime needed
+pip install zernio-sdk[mcp]
+
+# Print the per-IDE MCP config JSON:
+node setup/install-mcp.mjs
+```
+
+The installer prints copy-paste blocks for:
+
+- Claude Desktop (`claude_desktop_config.json`)
+- Claude Code (`~/.claude/mcp.json`)
+- Cursor (`~/.cursor/mcp.json`)
+- Generic `servers.mcp` JSON (other MCP-compatible IDEs)
+
+Then the agent's Zernio API calls can go through MCP tool invocations in addition to — or instead of — raw HTTP fetch. Either path produces the same manifest-submission result.
+
+### Layer 3 — Zernio's Claude Code skill (Claude Code only, optional)
+
+For Claude Code users who want Zernio's API surface taught as a first-class Claude skill:
+
+```bash
+npx clawhub@latest install zernio-api
+```
+
+This installs Zernio's official Claude Code skill (docs + examples) alongside this kit. The skill teaches Claude the API shape; this kit provides the operator law, templates, and output contract. They complement each other.
+
+---
+
+## Which layer should you use?
+
+| If you want... | Use |
+|---|---|
+| Simplest possible setup; agent-only mode included | Layer 1 (Working Directory) |
+| Typed tool calls from the agent to Zernio | Layer 1 + Layer 2 (MCP) |
+| First-class Zernio knowledge baked into Claude Code | Layer 1 + Layer 3 (Claude Code skill) |
+| Postiz UI shell with Zernio as the engine | See `docs/postiz-ui-shell-integration.md` |
+
+All four paths work from the same kit folder. You can layer them — they are strictly additive.
+
+---
+
+## What the kit does NOT do
+
+- Does **not** ship any Zernio SDK (Node, Python, Go, Ruby, Java, PHP, .NET, Rust). The agent uses raw REST via `fetch()` so nothing is installed transitively.
+- Does **not** register a new entry in `server/src/adapters/registry.ts` or `cli/src/adapters/registry.ts`. Those registries implement the `ServerAdapterModule` / `CLIAdapterModule` contracts for agent executors; Zernio is a REST API, not an executor.
+- Does **not** fork the externally-maintained `@paperclipai/adapter-claude-local` / `adapter-codex-local` / `adapter-cursor-local` / `adapter-gemini-local` / `adapter-opencode-local` / `adapter-pi-local` / `hermes-paperclip-adapter` packages. They remain untouched.
+- Does **not** add a new entry to the `Agent Harness` discovery menu. This kit is a Worker Kit, not a harness.
+
+This keeps the diff surface minimal and the kit strictly reusable across every local IDE already supported by growthub-local.
+
+---
+
+## See also
+
+- `../QUICKSTART.md` — one-command setup + per-OS notes
+- `../setup/setup.mjs` — cross-platform bootstrap
+- `../setup/install-mcp.mjs` — per-IDE MCP config printer
+- `./zernio-api-integration.md` — Zernio REST contract
+- `./postiz-ui-shell-integration.md` — pair the kit with the Postiz UI kit

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

@@ -0,0 +1,112 @@
+# Platform Coverage
+
+**Supported Zernio platform IDs, format specs, and character limits.**
+
+**Frozen at kit creation: 2026-04-15. Confirm live with `GET /api/v1/platforms` when Zernio adds new integrations.**
+
+---
+
+## Platform Reference Table
+
+| Platform | Zernio ID | Auth (Zernio-managed) | Post Types | Char Limit | Image Spec | Video Spec |
+|---|---|---|---|---|---|---|
+| X/Twitter | `twitter` | Twitter OAuth 2.0 | text, image, video, thread | 280 | 1200×675, ≤5MB | MP4/MOV, ≤2min 20s |
+| Instagram | `instagram` | Meta OAuth | image, video, reel, story, carousel | 2,200 | 1080×1080 or 1080×1350 | 1080×1920 (reels), MP4, ≤90s |
+| Facebook | `facebook` | Meta OAuth | text, image, video, reel, story, carousel | 63,206 | 1200×628, PNG/JPG | MP4, ≤240min |
+| 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 |
+| YouTube | `youtube` | Google OAuth | video (long-form), shorts | N/A (title + description) | Thumbnail: 1280×720 | MP4, any length; Shorts ≤60s, 1080×1920 |
+| Pinterest | `pinterest` | Pinterest OAuth | image, video, idea pin | 500 | 1000×1500 (2:3) | MP4, 4s–15min |
+| Reddit | `reddit` | Reddit OAuth | text, image, video, link | Subreddit-specific | Varies by subreddit | MP4, ≤15min |
+| Bluesky | `bluesky` | AT Protocol | text, image, video | 300 | Up to 4 images, 1×1 to 3×4 | MP4, ≤60s |
+| Threads | `threads` | Meta OAuth | text, image, video, thread | 500 | 1:1 square; 4:5 portrait | MP4, ≤5min |
+| Google Business | `googlebusiness` | Google OAuth | update, offer, event | 1,500 | 720×720 minimum | MP4, ≤30s |
+| Telegram | `telegram` | Bot API token | text, image, video, document | 4,096 | JPEG, ≤10MB | MP4, ≤50MB |
+| Snapchat | `snapchat` | Snapchat Marketing API | image, video, story | 80 | 1080×1920 | MP4, ≤60s |
+| WhatsApp | `whatsapp` | WhatsApp Business API | text, image, video, document | 1,024 | JPEG/PNG, ≤5MB | MP4, ≤16MB |
+
+**Source for IDs:** Zernio platform id is the canonical slug used inside every `POST /api/v1/posts` body's `platforms[].platform` field and every `/api/v1/connect/<platform>` OAuth entrypoint.
+
+---
+
+## Platform Selection Guidance
+
+### Audience Demographics (2026 data — refine per client brand kit)
+
+| Platform | Primary Demographic | Dominant Use Case |
+|---|---|---|
+| X/Twitter | 18–49 (male-skewed) | News, opinion, live commentary |
+| Instagram | 18–34 (55% female) | Visual branding, lifestyle, product showcase |
+| Facebook | 35–65 | Community groups, local business, events |
+| LinkedIn | 25–55 (professional) | B2B, thought leadership, hiring |
+| TikTok | 18–34 | Short-form entertainment, product discovery |
+| 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 |
+| Bluesky | 25–45 (tech-skewed) | Tech commentary, open-source community |
+| Threads | 18–34 | Text-first companion to Instagram audiences |
+| Google Business | Local search audience | Local business discovery, reviews |
+| Telegram | 18–44 (international) | Channels, bots, direct community |
+| Snapchat | 13–34 | Short-form, ephemeral content |
+| WhatsApp | 18+ (international, business) | Direct conversations, business messaging |
+
+### Recommended posting cadence per platform
+
+| Platform | Min / Max per week | Notes |
+|---|---|---|
+| X/Twitter | 5 / 30 | Highest-cadence platform. Multiple per day is acceptable. |
+| Instagram | 3 / 10 | Feed posts 3–5/week; Stories daily acceptable. |
+| Facebook | 3 / 10 | Mirror Instagram for B2C. |
+| LinkedIn | 3 / 5 | Never post more than 1x/day for a brand. |
+| TikTok | 3 / 21 | Daily posting drives algorithm signal. |
+| YouTube | 1 / 3 | Long-form is weekly; Shorts can be daily. |
+| Pinterest | 3 / 15 | Batch-pin from hero assets. |
+| Reddit | 1 / 5 | Subreddit etiquette outranks brand cadence. |
+| Bluesky | 3 / 14 | Text-forward; 1–2x/day is common. |
+| Threads | 3 / 14 | Pair with Instagram rhythm. |
+| Google Business | 1 / 3 | Updates + offers + events; don't over-post. |
+| Telegram | 1 / 7 | Channels tolerate quality over quantity. |
+| Snapchat | 3 / 14 | Short daily pulses work well. |
+| WhatsApp | 0 / 2 broadcast | Direct conversation first; broadcast sparingly. |
+
+### Carousel support
+
+Carousel posts are supported on: `instagram`, `linkedin`, `pinterest`, `facebook`.
+They are **not** supported on: `tiktok`, `twitter`, `bluesky`, `threads`, `youtube`, `googlebusiness`, `telegram`, `snapchat`, `whatsapp`, `reddit`.
+
+### Thread support
+
+Native thread posts are supported on: `twitter`, `bluesky`, `threads`. Everywhere else, use carousel or long-form caption.
+
+### Messaging-only platforms
+
+`telegram` and `whatsapp` require follower opt-in through the Zernio-connected account. Do not plan broadcast-style campaigns on these platforms without confirming consent flows with the client.
+
+---
+
+## Per-platform Tone Snapshot
+
+| Platform | Tone | Opening-hook rule |
+|---|---|---|
+| `twitter` | Concise, punchy, declarative | First 80 chars decide re-share |
+| `instagram` | Visual-first; caption secondary | First 150 chars above the "more" fold |
+| `facebook` | Conversational, community-oriented | First sentence is the hook |
+| `linkedin` | Professional, credibility-first | Lead with outcome or lesson, not greeting |
+| `tiktok` | Casual, trend-aware | First 150 chars drive completion rate |
+| `youtube` | Benefit + specificity in title; hook in first 8 seconds of video | Title carries the weight |
+| `pinterest` | Descriptive, keyword-dense | Pin title is the hook |
+| `reddit` | Subreddit-native — no marketing voice | First line must read like a genuine user post |
+| `bluesky` | Honest, tech-fluent, link-sparse | Skip hashtags; context carries it |
+| `threads` | Casual, text-forward | Treat as "tweets for Instagram audiences" |
+| `googlebusiness` | Operational, benefit-first, local | Include location or offer specifics |
+| `telegram` | Long-form friendly, channel voice | First two lines in notification preview |
+| `snapchat` | Playful, immediate | Hook must work without audio |
+| `whatsapp` | Direct, 1:1 voice | Treat as personal message, not broadcast |
+
+---
+
+## Cross-reference
+
+For caption character limits and variant rules see `docs/ai-caption-layer.md`.
+For scheduling + queue format see `docs/posts-and-queues-layer.md`.
+For API auth, endpoints, rate limits, and error codes see `docs/zernio-api-integration.md`.

package/assets/worker-kits/growthub-zernio-social-v1/docs/postiz-ui-shell-integration.md

@@ -0,0 +1,166 @@
+# Postiz UI Shell + Zernio Engine — Integration Recipe
+
+This document is the canonical recipe for running `growthub-zernio-social-v1` as the engine layer underneath the stable `growthub-postiz-social-v1` kit's UI shell.
+
+**Read order:** `../runtime-assumptions.md` → `./zernio-api-integration.md` → this file.
+
+---
+
+## Architectural split
+
+| Layer | Owned by | What it does |
+|---|---|---|
+| Presentation | `growthub-postiz-social-v1` (Postiz UI) | Calendar, compose, analytics shell, team workspace |
+| Engine | `growthub-zernio-social-v1` (this kit) | Posts, queues, media, inbox, analytics transport against Zernio REST API |
+
+**Core principle:** Postiz stays the UI. Zernio replaces Postiz's native provider/posting engine. Nothing in Postiz's own database schema, Redis queue runner, React app, or auth/team/workspace system changes. The diff surface is the provider + publish-bridge layers only.
+
+---
+
+## The 7 Module Integration Map
+
+### Module 1 — Provider Override (Zernio as the transport)
+
+Postiz's provider system is where per-platform OAuth and posting normally live. Replace it with a single `ZernioProvider`:
+
+- `baseUrl` → `https://zernio.com/api/v1`
+- `authHeader` → `Authorization: Bearer ${ZERNIO_API_KEY}`
+- All 14 platforms route through this one provider — no per-platform OAuth apps on the Postiz side
+- Postiz's "Connect Account" UI validates `ZERNIO_API_KEY` instead of OAuth dancing — Zernio handles all OAuth upstream
+
+The config for this provider mirrors exactly `buildZernioSocialConfig()` in `cli/src/kits/core/index.ts`:
+
+```ts
+{
+  providerId: "zernio",
+  providerName: "Zernio (hosted)",
+  providerBaseUrl: "https://zernio.com/api/v1",
+  providerAuthField: "Authorization",
+  apiKeyEnvVar: "ZERNIO_API_KEY",
+  additionalRequiredEnvVars: ["ZERNIO_API_URL"],
+}
+```
+
+### Module 2 — Post Submission Bridge
+
+The Zernio operator already produces manifests shaped as valid `POST /api/v1/posts` bodies. The bridge:
+
+1. Intercepts Postiz's internal `publishPost()` call
+2. Transforms the Postiz post into a Zernio manifest entry (see `./posts-and-queues-layer.md`)
+3. Fires `POST ${ZERNIO_API_URL}/posts` with `Authorization: Bearer ${ZERNIO_API_KEY}` and `Idempotency-Key: <clientPostId>`
+4. Feeds Zernio's response back into Postiz's job tracker
+
+`clientPostId` format stays `<client-slug>-<YYYYMMDD>-<sequence>`. Re-submitting the same manifest under the same key is safe.
+
+### Module 3 — Queue Sync Layer
+
+Postiz's queue concept maps 1:1 onto Zernio queues (`POST /api/v1/queues`):
+
+- Postiz queue scheduler → Zernio `queues` endpoint (create) / `queues/<queueId>` (update)
+- `Idempotency-Key: queue-<name>` prevents double-fire on retry
+- Posts attached to a queue omit `scheduledFor` and include `queueId`
+- The 10-step `zernio-social-operator` workflow becomes the execution contract for each queue job
+
+### Module 4 — AI Caption Layer Surface
+
+The agent-side `/zernio` command surface replaces Postiz's native AI composer:
+
+- Postiz compose textarea → `/zernio captions` (or `/zernio campaign` for full scope)
+- Caption drafts come from the A/B/C variant rules in `./ai-caption-layer.md`
+- Claude Code runs as a background operator session; Postiz compose UI is the front-end trigger
+- The 10 `/zernio` subcommands wire into Postiz's compose surface as slash-quick-actions
+
+### Module 5 — Platform Coverage Config
+
+`./platform-coverage.md` is the source of truth for Postiz channel configuration:
+
+- Disable native Postiz channel handlers
+- Register 14 channels pointing to the Zernio transport from Module 1
+- The per-platform format spec (char limits, aspect ratios, post types, carousel eligibility, thread support, cadence) drives Postiz's per-channel validation + preview rendering
+- `skills.md` per-platform tone rules feed the compose UI's voice hints
+
+### Module 6 — ENV + Secret Surface
+
+Direct alignment — the cleanest module:
+
+| Kit env var | Postiz field |
+|---|---|
+| `ZERNIO_API_KEY` | provider credentials field (replaces all per-platform OAuth tokens) |
+| `ZERNIO_API_URL` | provider baseUrl override (regional/proxy deployments only) |
+| `ZERNIO_PROFILE_ID` | default profile scope for all write requests |
+| `ZERNIO_TIMEZONE` | default posting timezone when the profile's timezone isn't used |
+
+`setup/verify-env.mjs` and `setup/check-deps.sh` run as Postiz's pre-start health checks. The secret-hygiene scan (`sk_` + 64-hex leak detection from the kit test suite) is the canonical gate on any output or log line.
+
+### Module 7 — Workspace CLI Entry Point
+
+`@growthub/cli >= 0.3.57` is the operator terminal that sits beside Postiz:
+
+- `growthub kit download growthub-zernio-social-v1` — materialize the kit
+- `growthub kit path growthub-zernio-social-v1` — print the working-directory path
+- Point a Claude Code session at that folder; the operator handles the full 10-step workflow
+- Postiz UI reflects the output — scheduled posts, queue runs, generated captions, analytics
+- The 7 artifacts declared by `buildZernioSocialConfig()` (brief, calendar, publishing plan, caption deck, scheduling manifest, analytics brief, client proposal) are the canonical source of truth for what the UI shows
+
+---
+
+## Integration Sequence (request path)
+
+```
+Postiz UI (compose / schedule)
+        ↓
+Module 2 — Post Submission Bridge
+        ↓
+Module 1 — ZernioProvider (Authorization: Bearer ZERNIO_API_KEY)
+        ↓
+Zernio API  →  POST /api/v1/posts
+            +  POST /api/v1/queues
+            +  POST /api/v1/media
+            +  GET  /api/v1/inbox
+            +  GET  /api/v1/analytics/*
+        ↑
+Module 3 — Queue Sync reads back status
+        ↑
+Postiz Calendar / Analytics shell renders state
+```
+
+Claude Code + the `/zernio` surface sits **laterally** — it feeds the compose box in Postiz before submission, not inside the request path. This keeps the agent lane non-blocking for end-user UI latency.
+
+---
+
+## What Stays Untouched in Postiz
+
+| Layer | Status |
+|---|---|
+| Postgres schema | Unchanged |
+| Redis queue runner | Unchanged (different job payloads, same runner) |
+| React frontend | Unchanged (except the compose AI hook in Module 4) |
+| Auth / team / workspace | Unchanged |
+| Existing Postiz kit payload (`growthub-postiz-social-v1`) | Unchanged — it remains valid for self-hosted-only operators |
+
+This keeps the diff surface minimal and keeps `growthub-zernio-social-v1` fully isolated as the engine layer.
+
+---
+
+## Operator Setup Order (when paired with Postiz UI shell)
+
+1. Stand up Postiz via its own kit (`growthub kit download growthub-postiz-social-v1`) — optional if only the UI layer is desired
+2. Download this kit: `growthub kit download growthub-zernio-social-v1`
+3. Fill `.env` — `ZERNIO_API_KEY`, `ZERNIO_API_URL`, `ZERNIO_PROFILE_ID`
+4. Run `node setup/verify-env.mjs` (kit-level) and the Postiz pre-start checks
+5. Apply Modules 1–3 inside the Postiz fork (provider override, publish bridge, queue sync). Everything else stays default.
+6. Open Claude Code at the Zernio kit's exported folder for the `/zernio` surface
+
+Standalone (without Postiz UI): everything still works — the kit is self-contained, and Modules 1–3 are optional.
+
+---
+
+## Validation Before Go-Live
+
+- [ ] Zernio API key scope is `read-write`
+- [ ] `GET /api/v1/accounts?profileId=...` returns at least one connected platform
+- [ ] A dry-run manifest round-trips through Module 2 with a successful 2xx from `POST /api/v1/posts`
+- [ ] A queue definition round-trips through Module 3 with a returned `queueId`
+- [ ] Postiz channel list surfaces all 14 Zernio platform slugs from `./platform-coverage.md`
+- [ ] Compose surface calls into `/zernio captions` and renders A/B/C variants
+- [ ] Kit secret-hygiene scan on the Postiz fork's logs is clean