@growthub/cli 0.3.56 → 0.3.58

package/assets/worker-kits/growthub-zernio-social-v1/output-standards.md

@@ -0,0 +1,132 @@
+# Output Standards
+
+**All Zernio Social Media Operator outputs must meet these standards before being delivered to a client.**
+
+---
+
+## Output Directory Structure
+
+```
+output/
+  <client-slug>/
+    <project-slug>/
+      SocialCampaignBrief_v<N>_<YYYYMMDD>.md
+      ContentCalendar_v<N>_<YYYYMMDD>.md
+      PlatformPublishingPlan_v<N>_<YYYYMMDD>.md
+      CaptionCopyDeck_v<N>_<YYYYMMDD>.md
+      SchedulingManifest_v<N>_<YYYYMMDD>.md    (if scheduling requested)
+      AnalyticsBrief_v<N>_<YYYYMMDD>.md        (if analytics data available)
+      ClientProposal_v<N>_<YYYYMMDD>.md        (if requested)
+      scheduling-manifest.json                  (always when scheduling — powers Zernio POST /api/v1/posts)
+```
+
+---
+
+## File Naming Convention
+
+```
+<ClientSlug>_<OutputType>_v<N>_<YYYYMMDD>.md
+```
+
+| Part | Rules | Example |
+|---|---|---|
+| ClientSlug | TitleCase, no spaces, no special chars | `UrbanCycle` |
+| OutputType | CamelCase from the list below | `ContentCalendar` |
+| Version | `v` + integer, starting at 1 | `v1` |
+| Date | `YYYYMMDD` format | `20260415` |
+
+**Output type names:**
+
+| Artifact | OutputType string |
+|---|---|
+| Social Campaign Brief | `SocialCampaignBrief` |
+| Content Calendar | `ContentCalendar` |
+| Platform Publishing Plan | `PlatformPublishingPlan` |
+| Caption Copy Deck | `CaptionCopyDeck` |
+| Scheduling Manifest | `SchedulingManifest` |
+| Analytics Brief | `AnalyticsBrief` |
+| Client Proposal | `ClientProposal` |
+
+---
+
+## Required Sections Per Artifact
+
+Each artifact must include all sections from its template. Incomplete sections must be marked `<!-- data-gap: reason -->` — never left blank without explanation.
+
+| Artifact | Minimum Required Sections |
+|---|---|
+| SocialCampaignBrief | Project Overview, Campaign Objective, Target Platforms, Audience Profile, KPI Targets, Content Theme Pillars, Brand Voice |
+| ContentCalendar | Calendar Header (client, period, platforms, profile id), Calendar Table (all rows with all columns), Posting Cadence Summary |
+| PlatformPublishingPlan | Per-platform rows (all selected platforms), Format spec, Frequency, Best posting times, Content mix ratio |
+| CaptionCopyDeck | Per-post entries (A/B/C variants each), Hashtag sets, Character counts, Media asset notes |
+| SchedulingManifest | Manifest header (profileId, timezone, dryRun), All post entries (clientPostId, content, scheduledFor, platforms[], media[], status) |
+| AnalyticsBrief | Period summary, Per-platform metrics table, Top 3 posts, Bottom 3 posts, Recommendations |
+| ClientProposal | Campaign Overview, Platform Mix rationale, Content Strategy, Deliverables scope, Pricing (3 tiers), ROI Projection |
+
+---
+
+## Quality Bar
+
+### Platform-Accurate
+
+- All platform IDs must match the official list in `docs/platform-coverage.md`
+- Character limits must be respected for every caption variant
+- Post types must be valid for the target platform (e.g., no carousels on TikTok or X)
+
+### Caption Quality
+
+- Every caption must have an explicit CTA — "Learn more" is acceptable; blank is not
+- All 3 variants (A/B/C) must be meaningfully different — not minor word swaps
+- Hashtags must be relevant to the content — no generic filler unless platform context demands it
+
+### Scheduling Manifest
+
+- `scheduledFor` timestamps must be ISO 8601 format with timezone offset
+- `clientPostId` must follow the naming convention: `<client-slug>-<YYYYMMDD>-<sequence>`
+- All posts in the manifest must have a corresponding entry in the ContentCalendar
+- `profileId` must be present (non-empty) — never hardcode to a placeholder string without also setting `dryRun: true`
+- Every `platforms[].platform` value must exist in `docs/platform-coverage.md`
+- Every `platforms[].accountId` must either be a real Zernio account id (live mode) or a documented placeholder tagged with the handle (agent-only mode)
+
+### No Filler
+
+- Every sentence must either present data, explain a constraint, or specify an action
+- Remove phrases like "Great content is key" — replace with the actual content specification
+- Recommendations must be specific: name the exact platform, posting time, content format, and expected impact
+
+### Actionable
+
+- Every post entry in the ContentCalendar must have a ready-to-use caption variant
+- Every platform in the PlatformPublishingPlan must have a posting time recommendation
+- Every finding in the AnalyticsBrief must have a corresponding action item
+
+### Consistent
+
+- Platform names in all artifacts must use the same slug format from `docs/platform-coverage.md`
+- Dates must be consistent across all artifacts
+- Client name must match the brand kit exactly
+
+---
+
+## Versioning Rules
+
+| Scenario | Action |
+|---|---|
+| First campaign for a client | All files at v1 |
+| Campaign revised post-approval | Increment all files to v2 |
+| Partial update (one artifact revised) | Increment only the revised artifact's version |
+| New campaign, same client | Start new project-slug, all files at v1 |
+
+---
+
+## scheduling-manifest.json
+
+This file must always be written to the output directory when scheduling is requested. It is the machine-readable record required for:
+
+- Zernio API scheduled post creation (one `POST /api/v1/posts` per entry or a batched sequence)
+- Manual review before submitting to Zernio
+- Campaign audit trail
+
+See `templates/scheduling-manifest.md` and `docs/posts-and-queues-layer.md` for the complete format with all required fields.
+
+Every write request to Zernio must include an `Idempotency-Key` header — the operator must instruct the downstream executor to use the `clientPostId` as that key so re-submissions are safe.

package/assets/worker-kits/growthub-zernio-social-v1/runtime-assumptions.md

@@ -0,0 +1,170 @@
+# Runtime Assumptions
+
+**Frozen at kit creation: 2026-04-15. Update this file when Zernio API behavior changes.**
+
+---
+
+## Execution Mode Overview
+
+| Mode | Requirements | Zernio API? | Live scheduling? | Caption AI? |
+|---|---|---|---|---|
+| `api-live` | Valid `ZERNIO_API_KEY` with `read-write` scope | Yes | Yes | Built-in (optional Anthropic enhancement) |
+| `agent-only` | Nothing (Claude Code only) | No | Dry-run JSON only | Yes |
+| `hybrid` | `ANTHROPIC_API_KEY` + valid `ZERNIO_API_KEY` | Yes | Yes | Enhanced via Anthropic |
+
+### Choosing a Mode
+
+- **Use `api-live`** when you want real Zernio scheduling, queue management, and analytics pull-back.
+- **Use `agent-only`** when you only need campaign planning, content calendars, and caption drafts, or when no Zernio key is available.
+- **Use `hybrid`** for the highest-quality caption drafting plus live Zernio scheduling.
+
+---
+
+## Zernio API Assumptions (frozen at kit creation)
+
+These are the assumptions frozen at kit creation time about the Zernio API at `https://zernio.com/api/v1`.
+
+### Base URL + versioning
+
+| Field | Value |
+|---|---|
+| Base URL | `https://zernio.com/api/v1` |
+| Version prefix | `v1` in the path |
+| Content-Type | `application/json` for all JSON endpoints |
+| Media upload | `multipart/form-data` on `/api/v1/media` |
+
+### Authentication
+
+- Header: `Authorization: Bearer ${ZERNIO_API_KEY}`
+- Key format: `sk_` + 64 hex characters (67 total)
+- Scopes: `read` or `read-write`
+- Scope per key: `full` or `profiles-specific`
+- Rotate keys via `POST /api/v1/api-keys` / `DELETE /api/v1/api-keys/<id>`
+
+### Core resources
+
+| Resource | Endpoint | Purpose |
+|---|---|---|
+| Profiles | `/api/v1/profiles` | Containers that group social accounts together |
+| Accounts | `/api/v1/accounts` | Connected social accounts on a profile |
+| Posts | `/api/v1/posts` | Schedulable content, fan-out to multiple accounts |
+| Queues | `/api/v1/queues` | Recurring time-slot schedules |
+| Media | `/api/v1/media` | Upload images, videos, carousels |
+| Inbox | `/api/v1/inbox` | Unified DMs, comments, reviews |
+| Analytics | `/api/v1/analytics` | Per-post and per-account metrics |
+| API Keys | `/api/v1/api-keys` | Key lifecycle management |
+| Connect | `/api/v1/connect/<platform>` | OAuth / credential flow entrypoint |
+
+### 14 platforms (at time of freeze)
+
+| Platform | Zernio platform id | Auth method (Zernio-managed) |
+|---|---|---|
+| X/Twitter | `twitter` | Twitter OAuth 2.0 |
+| Instagram | `instagram` | Meta OAuth |
+| Facebook | `facebook` | Meta OAuth |
+| LinkedIn | `linkedin` | LinkedIn OAuth |
+| TikTok | `tiktok` | TikTok OAuth |
+| YouTube | `youtube` | Google OAuth |
+| Pinterest | `pinterest` | Pinterest OAuth |
+| Reddit | `reddit` | Reddit OAuth |
+| Bluesky | `bluesky` | AT Protocol |
+| Threads | `threads` | Meta OAuth |
+| Google Business | `googlebusiness` | Google OAuth |
+| Telegram | `telegram` | Bot API token |
+| Snapchat | `snapchat` | Snapchat Marketing API |
+| WhatsApp | `whatsapp` | WhatsApp Business API |
+
+*Additional platforms may be added in newer Zernio releases. Always confirm against `GET /api/v1/platforms` for the live list.*
+
+### Rate limits (assumed)
+
+| Limit | Value |
+|---|---|
+| Default plan | 60 requests/minute per API key |
+| Posts burst | ≤30 scheduled posts per single `POST /api/v1/posts` call |
+| Media uploads | ≤10 media objects per minute per profile |
+| Analytics pull | ≤10 calls/minute per profile |
+
+If a 429 is returned, back off using the `Retry-After` header. Treat rate-limit retries as idempotent only when a client-provided `Idempotency-Key` header is attached.
+
+### Idempotency
+
+- Include `Idempotency-Key: <uuid>` on every write (`POST /posts`, `POST /queues`, `POST /media`)
+- Use `clientPostId` values from the manifest as the idempotency key when creating scheduled posts — this makes manifest re-submission safe
+
+### Optional AI caption enhancement
+
+Zernio ships its own caption-enhancement endpoint, but this kit uses the operator's Anthropic key directly for caption drafting. Zernio's built-in caption service is treated as secondary.
+
+- Kit caption source: Anthropic (via the agent calling Claude)
+- Zernio caption service: documented but not used as the primary source
+
+---
+
+## Execution Surface Flows
+
+### Api-Live Mode
+
+```
+User request → Environment gate (Step 0)
+  ↓
+Read skills.md + brand kit (Step 1)
+  ↓
+Read runtime docs (Step 2)
+  ↓
+Inspect Zernio account: profiles, accounts, queues, scheduled posts (Step 3)
+  ↓
+4-question gate (Step 4)
+  ↓
+Select /zernio command (Step 5)
+  ↓
+Phase 1: Campaign strategy + platform selection (Step 6)
+  ↓
+Phase 2: Content calendar + caption copy deck (Step 7)
+  ↓
+Phase 3: Scheduling manifest → POST /api/v1/posts (Step 8)
+  ↓
+Optional queue definition → POST /api/v1/queues (Step 8b)
+  ↓
+Artifact package: 5–7 Markdown files + scheduling-manifest.json (Step 9)
+  ↓
+Log deliverable → brand kit DELIVERABLES LOG (Step 10)
+```
+
+### Agent-Only Mode
+
+```
+User request → Environment gate (Step 0 — confirm agent-only)
+  ↓
+Read skills.md + brand kit (Step 1)
+  ↓
+Read runtime docs (Step 2)
+  ↓
+Skip live account inspection (Step 3 — N/A)
+  ↓
+4-question gate (Step 4)
+  ↓
+Select /zernio command (Step 5)
+  ↓
+Phase 1: Campaign strategy + platform selection (Step 6)
+  ↓
+Phase 2: Content calendar + caption copy deck (Step 7)
+  ↓
+Phase 3: Dry-run scheduling manifest (JSON, dryRun: true) (Step 8)
+  ↓
+Artifact package: 5–7 Markdown files + scheduling-manifest.json (Step 9)
+  ↓
+Log deliverable → brand kit DELIVERABLES LOG (Step 10)
+```
+
+---
+
+## Output Assumption
+
+All outputs are Markdown files written to:
+
+```
+output/<client-slug>/<project-slug>/
+```
+
+The scheduling manifest is a JSON file (`scheduling-manifest.json`) written alongside the Markdown artifacts. It is the machine-readable record for Zernio API submission and stays aligned to the `POST /api/v1/posts` body shape documented in `docs/posts-and-queues-layer.md`.

package/assets/worker-kits/growthub-zernio-social-v1/setup/check-deps.mjs

@@ -0,0 +1,117 @@
+#!/usr/bin/env node
+// check-deps.mjs — cross-platform dependency check for the Zernio Social Media Studio
+//
+// Works identically on macOS, Linux, and Windows (PowerShell, cmd, WSL, git-bash).
+// Functional parity with setup/check-deps.sh (bash, unix-only) so Windows users
+// get a first-class experience without bash.
+//
+// Usage:
+//   node setup/check-deps.mjs
+
+import { spawn } from "node:child_process";
+import { platform, release } from "node:os";
+
+const RED = "\x1b[31m";
+const GREEN = "\x1b[32m";
+const YELLOW = "\x1b[33m";
+const BOLD = "\x1b[1m";
+const RESET = "\x1b[0m";
+
+let pass = 0;
+let warn = 0;
+let fail = 0;
+
+function ok(msg) { console.log(`  ${GREEN}\u2713${RESET}  ${msg}`); pass += 1; }
+function warning(msg) { console.log(`  ${YELLOW}!${RESET}  ${msg}`); warn += 1; }
+function failure(msg) { console.log(`  ${RED}\u2717${RESET}  ${msg}`); fail += 1; }
+
+function which(binary) {
+  return new Promise((resolve) => {
+    const isWin = platform() === "win32";
+    const lookup = isWin ? "where" : "which";
+    const child = spawn(lookup, [binary], { shell: false });
+    let out = "";
+    child.stdout?.on("data", (d) => (out += String(d)));
+    child.on("close", (code) => resolve(code === 0 ? out.trim().split(/\r?\n/)[0] : null));
+    child.on("error", () => resolve(null));
+  });
+}
+
+function version(binary, args = ["--version"]) {
+  return new Promise((resolve) => {
+    const child = spawn(binary, args, { shell: false });
+    let out = "";
+    child.stdout?.on("data", (d) => (out += String(d)));
+    child.stderr?.on("data", (d) => (out += String(d)));
+    child.on("close", (code) => resolve(code === 0 ? out.trim() : null));
+    child.on("error", () => resolve(null));
+  });
+}
+
+console.log("");
+console.log(`${BOLD}Growthub Zernio Social Media Studio — Dependency Check${RESET}`);
+console.log(`host: ${platform()} ${release()}  ·  node: ${process.version}`);
+console.log("");
+
+// --- Node.js (required, built-in check) ---
+const nodeMajor = Number.parseInt(process.versions.node.split(".")[0], 10);
+if (Number.isFinite(nodeMajor) && nodeMajor >= 18) {
+  ok(`node ${process.version} (>= 18 required)`);
+} else {
+  failure(`node ${process.version} — version 18+ required. Install from https://nodejs.org`);
+}
+
+// --- Built-in fetch (Node 18+ has it) ---
+if (typeof fetch === "function") {
+  ok("Node built-in fetch() is available — no curl dependency required");
+} else {
+  failure("Node built-in fetch() is not available — upgrade to Node 18+");
+}
+
+// --- npm (optional but expected) ---
+{
+  const path = await which("npm");
+  if (path) {
+    const v = await version("npm");
+    ok(`npm ${v ?? ""} at ${path}`);
+  } else {
+    warning("npm not found — usually ships with Node.js; only needed if you install additional CLIs");
+  }
+}
+
+// --- curl (optional — useful for manual API smoke tests) ---
+{
+  const path = await which("curl");
+  if (path) {
+    ok(`curl at ${path} — optional, useful for ad-hoc API tests`);
+  } else {
+    warning("curl not found — optional. Node's fetch() handles everything the kit needs.");
+  }
+}
+
+// --- git (optional) ---
+{
+  const path = await which("git");
+  if (path) {
+    ok(`git at ${path}`);
+  } else {
+    warning("git not found — optional for this kit. Install from https://git-scm.com/downloads if you want repo versioning.");
+  }
+}
+
+// --- Summary ---
+console.log("");
+console.log(`${BOLD}Summary${RESET}`);
+console.log(`  Passed:   ${pass}`);
+if (warn > 0) console.log(`  ${YELLOW}Warnings: ${warn}${RESET}`);
+if (fail > 0) console.log(`  ${RED}Failed:   ${fail}${RESET}`);
+console.log("");
+
+if (fail > 0) {
+  console.log(`${RED}${BOLD}Install the missing required dependencies and re-run.${RESET}`);
+  process.exit(1);
+} else if (warn > 0) {
+  console.log(`${YELLOW}Dependencies OK with warnings. All warnings are optional.${RESET}`);
+} else {
+  console.log(`${GREEN}All dependencies satisfied.${RESET}`);
+}

package/assets/worker-kits/growthub-zernio-social-v1/setup/check-deps.sh

@@ -0,0 +1,86 @@
+#!/usr/bin/env bash
+# check-deps.sh — Verify system dependencies for the Zernio Social Media Studio
+# Usage: bash setup/check-deps.sh
+set -e
+
+GREEN="\033[0;32m"
+RED="\033[0;31m"
+YELLOW="\033[0;33m"
+RESET="\033[0m"
+
+PASS=0
+FAIL=0
+WARN=0
+
+ok() {
+  echo -e "  ${GREEN}✓${RESET}  $1"
+  PASS=$((PASS + 1))
+}
+
+fail() {
+  echo -e "  ${RED}✗${RESET}  $1"
+  FAIL=$((FAIL + 1))
+}
+
+warn() {
+  echo -e "  ${YELLOW}⚠${RESET}  $1"
+  WARN=$((WARN + 1))
+}
+
+echo "=== Growthub Zernio Social Media Studio — Dependency Check ==="
+echo ""
+
+# --- Node.js ---
+if command -v node &>/dev/null; then
+  NODE_VER=$(node --version | sed 's/v//')
+  NODE_MAJOR=$(echo "$NODE_VER" | cut -d. -f1)
+  if [ "$NODE_MAJOR" -ge 18 ]; then
+    ok "node v${NODE_VER} (18+ required)"
+  else
+    fail "node v${NODE_VER} — version 18+ required. Install from https://nodejs.org"
+  fi
+else
+  fail "node — not found. Install from https://nodejs.org"
+fi
+
+# --- npm ---
+if command -v npm &>/dev/null; then
+  ok "npm $(npm --version)"
+else
+  warn "npm — not found. Usually installed with Node.js."
+fi
+
+# --- curl ---
+if command -v curl &>/dev/null; then
+  ok "curl $(curl --version | head -1 | awk '{print $2}')"
+else
+  fail "curl — not found. Required for Zernio healthchecks. Install from https://curl.se/download.html"
+fi
+
+# --- Git ---
+if command -v git &>/dev/null; then
+  ok "git $(git --version | awk '{print $3}')"
+else
+  warn "git — not found. Not strictly required for this kit but strongly recommended."
+fi
+
+# --- Summary ---
+echo ""
+echo "=== Summary ==="
+echo "  Passed:   $PASS"
+if [ "$WARN" -gt 0 ]; then
+  echo -e "  ${YELLOW}Warnings: $WARN${RESET}"
+fi
+if [ "$FAIL" -gt 0 ]; then
+  echo -e "  ${RED}Failed:   $FAIL${RESET}"
+  echo ""
+  echo "Install missing dependencies and re-run this script."
+  exit 1
+else
+  echo ""
+  if [ "$WARN" -gt 0 ]; then
+    echo -e "${YELLOW}Dependencies OK with warnings.${RESET}"
+  else
+    echo -e "${GREEN}All dependencies satisfied.${RESET}"
+  fi
+fi

package/assets/worker-kits/growthub-zernio-social-v1/setup/install-mcp.mjs

@@ -0,0 +1,177 @@
+#!/usr/bin/env node
+// install-mcp.mjs — print the per-IDE Zernio MCP server config JSON
+//
+// This is a print-only helper. It does NOT run `pip install zernio-sdk[mcp]`
+// for you, and it does NOT mutate any config file. It prints the exact
+// copy-paste JSON blocks you need to wire Zernio's official MCP server into
+// each MCP-compatible IDE.
+//
+// Cross-platform (macOS, Linux, Windows). Pure Node stdlib — no deps.
+//
+// Usage:
+//   node setup/install-mcp.mjs                 # print all IDE configs
+//   node setup/install-mcp.mjs claude-desktop  # one IDE only
+//   node setup/install-mcp.mjs cursor
+//   node setup/install-mcp.mjs claude-code
+//   node setup/install-mcp.mjs generic
+
+import { platform } from "node:os";
+import { join } from "node:path";
+import { homedir } from "node:os";
+
+const BOLD = "\x1b[1m";
+const DIM = "\x1b[2m";
+const GREEN = "\x1b[32m";
+const YELLOW = "\x1b[33m";
+const BLUE = "\x1b[34m";
+const RESET = "\x1b[0m";
+
+const arg = (process.argv[2] ?? "all").toLowerCase();
+const osPlatform = platform();
+
+// ---- Config path hints (cross-platform) ----
+function claudeDesktopConfigPath() {
+  const home = homedir();
+  if (osPlatform === "darwin") return join(home, "Library", "Application Support", "Claude", "claude_desktop_config.json");
+  if (osPlatform === "win32") return join(process.env.APPDATA ?? join(home, "AppData", "Roaming"), "Claude", "claude_desktop_config.json");
+  return join(home, ".config", "Claude", "claude_desktop_config.json");
+}
+
+function claudeCodeConfigPath() {
+  return join(homedir(), ".claude", "mcp.json");
+}
+
+function cursorConfigPath() {
+  return join(homedir(), ".cursor", "mcp.json");
+}
+
+// ---- MCP server definition ----
+// Zernio's official MCP server ships inside the zernio-python SDK:
+//   pip install zernio-sdk[mcp]
+// The server entrypoint is the Python module. Auth is via ZERNIO_API_KEY env var.
+const ZERNIO_MCP_BLOCK = {
+  command: "python",
+  args: ["-m", "zernio.mcp"],
+  env: {
+    ZERNIO_API_KEY: "${ZERNIO_API_KEY}",
+  },
+};
+
+function header(label) {
+  console.log("");
+  console.log(`${BOLD}${BLUE}${label}${RESET}`);
+  console.log("-".repeat(Math.max(24, label.length)));
+}
+
+function note(msg) {
+  console.log(`${DIM}${msg}${RESET}`);
+}
+
+function codeBlock(obj) {
+  console.log("```json");
+  console.log(JSON.stringify(obj, null, 2));
+  console.log("```");
+}
+
+function printPreamble() {
+  console.log("");
+  console.log(`${BOLD}Zernio MCP Server — per-IDE config${RESET}`);
+  note(`host: ${osPlatform}  ·  pre-req: pip install zernio-sdk[mcp]  ·  env: ZERNIO_API_KEY`);
+  console.log("");
+  console.log(`${GREEN}1.${RESET} Install Zernio's MCP server (one-time):`);
+  console.log(`   ${BOLD}pip install zernio-sdk[mcp]${RESET}`);
+  console.log("");
+  console.log(`${GREEN}2.${RESET} Ensure ZERNIO_API_KEY is set in your shell profile (or pass it via the IDE):`);
+  if (osPlatform === "win32") {
+    console.log(`   ${DIM}setx ZERNIO_API_KEY "sk_..."${RESET}                  ${DIM}# PowerShell, persistent${RESET}`);
+  } else {
+    console.log(`   ${DIM}echo 'export ZERNIO_API_KEY="sk_..."' >> ~/.zshrc${RESET}    ${DIM}# or ~/.bashrc${RESET}`);
+  }
+  console.log("");
+  console.log(`${GREEN}3.${RESET} Paste one of the JSON blocks below into the matching IDE's MCP config.`);
+  console.log("");
+}
+
+function printClaudeDesktop() {
+  header("Claude Desktop");
+  note(`Config file: ${claudeDesktopConfigPath()}`);
+  console.log(`Add the ${BOLD}zernio${RESET} server under the top-level ${BOLD}mcpServers${RESET} object:`);
+  console.log("");
+  codeBlock({
+    mcpServers: {
+      zernio: ZERNIO_MCP_BLOCK,
+    },
+  });
+  console.log(`${YELLOW}Restart Claude Desktop${RESET} after editing the config.`);
+}
+
+function printClaudeCode() {
+  header("Claude Code");
+  note(`Config file: ${claudeCodeConfigPath()}`);
+  console.log(`Add to ${BOLD}.claude/mcp.json${RESET} (or use ${BOLD}claude mcp add${RESET}):`);
+  console.log("");
+  codeBlock({
+    mcpServers: {
+      zernio: ZERNIO_MCP_BLOCK,
+    },
+  });
+  console.log(`Alternative one-liner:`);
+  console.log(`  ${BOLD}claude mcp add zernio -- python -m zernio.mcp${RESET}`);
+}
+
+function printCursor() {
+  header("Cursor");
+  note(`Config file: ${cursorConfigPath()}`);
+  console.log(`Add the ${BOLD}zernio${RESET} entry under the top-level ${BOLD}mcpServers${RESET} object:`);
+  console.log("");
+  codeBlock({
+    mcpServers: {
+      zernio: ZERNIO_MCP_BLOCK,
+    },
+  });
+  console.log(`${YELLOW}Restart Cursor${RESET} after editing the config.`);
+}
+
+function printGeneric() {
+  header("Generic MCP-compatible IDE");
+  note("Use this shape for any IDE that speaks MCP (Codex-mcp, n8n MCP nodes, custom clients).");
+  console.log("");
+  codeBlock({
+    mcpServers: {
+      zernio: ZERNIO_MCP_BLOCK,
+    },
+  });
+  console.log("Adjust the top-level key if your IDE uses a different name (e.g. `servers` vs `mcpServers`).");
+}
+
+function printFooter() {
+  console.log("");
+  header("What this enables");
+  console.log("- The agent can call Zernio endpoints as typed MCP tools instead of raw HTTP.");
+  console.log("- Works alongside this kit's Working Directory pattern — strictly additive.");
+  console.log("- All writes still use Idempotency-Key = clientPostId for safe re-submission.");
+  console.log("- See docs/local-adapters.md for the full matrix of supported IDEs.");
+  console.log("");
+  console.log(`${DIM}Zernio's MCP server lives in the zernio-python SDK:${RESET}`);
+  console.log(`  ${DIM}https://github.com/zernio-dev/zernio-python${RESET}`);
+  console.log("");
+}
+
+// ---- Dispatch ----
+printPreamble();
+
+switch (arg) {
+  case "claude-desktop": printClaudeDesktop(); break;
+  case "claude-code": printClaudeCode(); break;
+  case "cursor": printCursor(); break;
+  case "generic": printGeneric(); break;
+  case "all":
+  default:
+    printClaudeDesktop();
+    printClaudeCode();
+    printCursor();
+    printGeneric();
+    break;
+}
+
+printFooter();