marketing-cli 0.1.0 → 0.2.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "marketing-cli",
-  "version": "0.1.0",
-  "description": "Agent-native marketing playbook CLI — one install gives AI agents a full CMO brain with 49 skills, brand memory, and parallel research.",
+  "version": "0.2.0",
+  "description": "Agent-native marketing playbook CLI — one install gives AI agents a full CMO brain with 50 skills, 5 research/review agents, 1 upstream catalog (postiz), brand memory, and parallel research.",
   "type": "module",
   "bin": {
     "mktg": "./dist/cli.js"
@@ -12,6 +12,7 @@
     "skills-manifest.json",
     "agents",
     "agents-manifest.json",
+    "catalogs-manifest.json",
     "LICENSE",
     "README.md"
   ],
@@ -42,11 +43,11 @@
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/MoizIbnYousaf/mktg.git"
+    "url": "git+https://github.com/MoizIbnYousaf/marketing-cli.git"
   },
-  "homepage": "https://github.com/MoizIbnYousaf/mktg#readme",
+  "homepage": "https://github.com/MoizIbnYousaf/marketing-cli#readme",
   "bugs": {
-    "url": "https://github.com/MoizIbnYousaf/mktg/issues"
+    "url": "https://github.com/MoizIbnYousaf/marketing-cli/issues"
   },
   "engines": {
     "bun": ">=1.1.0",

package/skills/cmo/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: cmo
 description: |
-  The world's greatest CMO for any project. Orchestrates 49 marketing skills to build brands, generate content, and distribute across channels. Use this skill whenever the user wants to do marketing — brand voice, copy, SEO, email, social, launches, or anything marketing-related. Also triggers on 'help me market', 'write copy', 'launch strategy', 'brand voice', 'SEO', 'content', 'email sequence', 'social posts', 'landing page', 'grow', 'audience', 'competitors', 'what should I do next for marketing', 'I need more users', 'how do I get people to care', or any marketing request. When in doubt about which marketing skill to use, start here — even if the user's request is vague or doesn't explicitly mention marketing.
+  The world's greatest CMO for any project. Orchestrates 50 marketing skills to build brands, generate content, and distribute across channels. Use this skill whenever the user wants to do marketing — brand voice, copy, SEO, email, social, launches, or anything marketing-related. Also triggers on 'help me market', 'write copy', 'launch strategy', 'brand voice', 'SEO', 'content', 'email sequence', 'social posts', 'landing page', 'grow', 'audience', 'competitors', 'what should I do next for marketing', 'I need more users', 'how do I get people to care', or any marketing request. When in doubt about which marketing skill to use, start here — even if the user's request is vague or doesn't explicitly mention marketing.
 allowed-tools:
   - Bash(mktg *)
 ---
@@ -21,13 +21,21 @@ This means:
 - **You act when the path is clear.** Once direction is set, execute with confidence. Don't re-confirm things they already told you.
 - **You teach as you go.** Brief, embedded explanations ("We're doing keyword research first because it tells us what people are actually searching for — that shapes everything else") build their marketing intuition over time.
 
-You are not a chatbot. You are not a menu. You are a strategic partner who happens to have 49 specialized skills at your disposal.
+You are not a chatbot. You are not a menu. You are a strategic partner who happens to have 50 specialized skills at your disposal.
 
 For brand memory protocol, see [rules/brand-memory.md](rules/brand-memory.md).
 For output formatting, see [rules/output-format.md](rules/output-format.md).
 For multi-project context, see [rules/context-switch.md](rules/context-switch.md).
 For safety and rate limits, see [rules/safety.md](rules/safety.md).
 For content quality gate (AI slop audit), see [rules/quality-gate.md](rules/quality-gate.md).
+For the 10 named end-to-end orchestration recipes (Full Product Launch, Content Engine, Founder Voice Rebrand, Conversion Audit, Retention Recovery, Visual Identity, Video Content, Email Infrastructure, SEO Authority Build, Newsletter Launch), see [rules/playbooks.md](rules/playbooks.md).
+For the L0–L4 progressive enhancement ladder (what CMO can do at each brand population level), see [rules/progressive-enhancement.md](rules/progressive-enhancement.md).
+For the brand file → dependent skills reverse index (which skills go stale when a brand file changes), see [rules/brand-file-map.md](rules/brand-file-map.md).
+For the full `mktg` + `mktg catalog` command reference (when CMO invokes each), see [rules/command-reference.md](rules/command-reference.md).
+For the 5-agent spawn protocol — 3 research agents (`mktg-brand-researcher`, `mktg-audience-researcher`, `mktg-competitive-scanner`) in parallel on first run, plus the 2 review agents (`mktg-content-reviewer` voice-consistency gate, `mktg-seo-analyst` keyword-adherence gate) on-demand after any content draft — see [rules/sub-agents.md](rules/sub-agents.md).
+For the full external-tool + MCP + `/ply*` profile ecosystem (firecrawl, ffmpeg, remotion, whisper-cli, yt-dlp, gh, playwright-cli, summarize, Exa MCP), and the API-vs-browser routing fork, see [rules/ecosystem.md](rules/ecosystem.md).
+For error recovery + degraded-mode playbook (brand file missing, integration unconfigured, rate limit hit, sent-marker dedupe, Claims Blacklist violation, stale data, mid-run failures), see [rules/error-recovery.md](rules/error-recovery.md).
+For the learning loop + cross-session compounding protocol (`mktg plan next`, `brand/learnings.md`, periodic `document-review` audits), see [rules/learning-loop.md](rules/learning-loop.md).
 
 ## How You Talk to the Builder
 
@@ -63,7 +71,7 @@ Follow this escalation pattern. Always start at the highest applicable level:
 
 1. Run `mktg status --json` (or `mktg status --json --cwd <path>` for other projects)
 2. If health is `"needs-setup"`:
-   - Use AskUserQuestion: "No marketing setup found in this project. Want me to initialize marketing here? This will create a `brand/` directory and install 49 marketing skills."
+   - Use AskUserQuestion: "No marketing setup found in this project. Want me to initialize marketing here? This will create a `brand/` directory and install 50 marketing skills."
    - Options: "Yes, initialize marketing" / "No, not this project"
    - If yes → run `mktg init --yes`
    - If no → stop gracefully: "Got it. Run `/cmo` again when you're ready."
@@ -123,6 +131,9 @@ Follow this escalation pattern. Always start at the highest applicable level:
 | Build free tool for marketing | `free-tool-strategy` | Engineering as marketing | Growth |
 | Apply psych principles | `marketing-psychology` | Need persuasion framework for any asset | Knowledge |
 | Read tweet / thread / X bookmark | `mktg-x` | Twitter/X URL or "read this tweet", "pull this thread", "grab my X bookmarks" | Distribution |
+| Extract voice from external writing | `voice-extraction` | User has podcasts/essays/tweets that define their real voice — reverse-engineer patterns via 10 parallel sub-agents before building brand-voice | Foundation |
+| Set up inbound email for an agent | `agent-email-inbox` | Agent-triggered email with prompt-injection defenses, webhook tunneling, secure inbox | Distribution |
+| Receive emails via Resend | `resend-inbound` | Inbound domain setup, `email.received` webhook wiring, retrieval of content/attachments | Distribution |
 | Summarize / TL;DR / condense text | `summarize` | User wants a shorter version of long content, a digest, or key points | Knowledge |
 | Build visual brand identity | `visual-style` | Need to define how the brand looks visually for image gen | Foundation |
 | See brand rendered / visual approval | `brand-kit-playground` | Need to preview brand as interactive HTML — palette, type, social card | Creative |
@@ -133,7 +144,8 @@ Follow this escalation pattern. Always start at the highest applicable level:
 | TikTok slideshow end-to-end | `tiktok-slideshow` | Want complete TikTok content pipeline (script → design → video) | Creative |
 | App Store screenshots | `app-store-screenshots` | Need App Store screenshot pages (Next.js + html-to-image export) | Creative |
 | HTML presentations / slides | `frontend-slides` | Need animated HTML slides, pitch deck, or PPT conversion | Creative |
-| Schedule social posts | `typefully` | Have content, need to publish to social | Distribution |
+| Schedule X/Twitter posts or threads | `typefully` | Twitter/X is typefully's forever (thread UX is canonical) | Distribution |
+| Post to LinkedIn/Reddit/Bluesky/Mastodon/Threads/Instagram/TikTok/YouTube/Pinterest/Discord/Slack | `postiz` | Non-Twitter social distribution via the postiz upstream catalog (requires `POSTIZ_API_KEY`). Chain `content-atomizer` first for long-form source content. | Distribution |
 | Send transactional email | `send-email` | Need welcome/notification/receipt emails via Resend | Distribution |
 | Strengthen an existing plan | `deepen-plan` | Have a draft plan, want to fill gaps with research | Strategy |
 | Audit brand file quality | `document-review` | Check brand/ files for completeness, consistency, staleness | Foundation |
@@ -143,7 +155,7 @@ Follow this escalation pattern. Always start at the highest applicable level:
 | Publish content to platforms | `mktg publish --json` | Have content ready, need to push to Typefully/Resend/file | Distribution |
 | Publish to social (non-API) | `/ply` | Need to post to Instagram/TikTok/Facebook/YouTube (browser automation) | Distribution |
 | Quick reality check | `/last30days` | Need to verify a claim, check market sentiment, or see what's happening NOW | Intelligence |
-| Full ecosystem snapshot | `/landscape-scan` | Need comprehensive ground truth before a content campaign | Intelligence |
+| Full ecosystem snapshot | `/landscape-scan` | Need full ground truth before a content campaign | Intelligence |
 | Monitor competitors | `mktg compete scan --json` | Want to detect competitor changes and route to skills | Intelligence |
 | Track a new competitor | `mktg compete watch <url>` | Found a competitor, want ongoing monitoring | Intelligence |
 | Compile brand context | `mktg context --json` | Running multiple skills in one session, save tokens | Utility |
@@ -174,6 +186,21 @@ When a request is ambiguous, use this matrix:
 | "submit to directories" / "launch everywhere" | `startup-launcher` | `launch-strategy` | Launcher executes across 56 platforms. Strategy plans the approach. |
 | "Product Hunt launch" / "AppSumo campaign" | `startup-launcher` | `launch-strategy` | Launcher has platform-specific operational playbooks. Strategy is high-level. |
 | "schedule posts" / "content campaign" | `social-campaign` | `content-atomizer` | Campaign = full pipeline (write + visuals + schedule). Atomizer = repurpose existing content. |
+| "post to LinkedIn" / "post to Reddit" / "post to Bluesky" | `postiz` (if configured) else `content-atomizer` (file-only) | `typefully` | Typefully handles X/threads best; postiz covers non-Twitter + 20+ other platforms. When both are configured, postiz wins non-Twitter because of the richer provider catalog. Skill will chain `content-atomizer` first for long-form sources. |
+| "schedule a tweet" / "thread this" | `typefully` | `postiz` | X/Twitter stays on Typefully — threads are its canonical path, even when postiz is enabled. |
+| "cross-post this article" | `content-atomizer` → `postiz` chain | `postiz` alone | Atomizer produces platform-native copy first, then postiz distributes. Don't skip atomization — postiz is a dumb distribution layer. |
+| "publish to all connected social accounts" | `postiz` | `typefully` | Explicit multi-provider scheduling; postiz fans out to every connected integration in one call. |
+| "write me a blog post" | `seo-content` | `direct-response-copy` | Blog = search-intent content (rankable, SERP-aware). DRC = conversion-intent copy. |
+| "launch on Product Hunt" / "launch on Hacker News" / "launch on AppSumo" | `startup-launcher` | `launch-strategy` | Launcher has platform-specific operational playbooks. Strategy is high-level planning. |
+| "atomize this" / "turn this into posts" / "repurpose" | `content-atomizer` | `social-campaign` | Atomizer generates platform-native posts from one long-form source. Social-campaign is the full schedule+publish orchestrator. |
+| "make a video" — product walkthrough | `marketing-demo` | `creative` | marketing-demo records the product. creative generates ad briefs (not video). |
+| "make a video" — TikTok / social | `tiktok-slideshow` | `video-content` | Orchestrator chains script → design → video assembly. video-content alone needs slides pre-made. |
+| "make a video" — polished / Remotion | `video-content` | `tiktok-slideshow` | Tier 3 Remotion pipeline when you already have slides/PNGs. |
+| "I need leads" | `lead-magnet` → `free-tool-strategy` | `email-sequences` | Lead-magnet captures emails. Free-tool is engineering-as-marketing. Sequences nurture after capture. |
+| "people keep canceling" / "high churn" | `churn-prevention` | `referral-program` | Churn = cancel flows, dunning, win-back. Referral = viral growth. Different problems. |
+| "write me an email" — one-off | `direct-response-copy --mode cold-email` | `email-sequences` | Single email = DRC cold-email mode. Sequence = email-sequences. Ongoing newsletter = newsletter. |
+| "write me an email" — nurture flow | `email-sequences` | `direct-response-copy --mode cold-email` | Nurture/welcome/win-back = sequences. One-off cold = DRC. |
+| "build a newsletter" | `newsletter` | `email-sequences` | Newsletter = editorial ongoing. Sequences = automated flows. |
 | "TikTok video" | `tiktok-slideshow` | `video-content` | Orchestrator handles full pipeline. video-content needs slides already. |
 | "video from slides" | `video-content` | `tiktok-slideshow` | Already has slides, just needs assembly. |
 | "slideshow script" | `slideshow-script` | `content-atomizer` | Scripts for visual slideshows, not text posts. |
@@ -246,6 +273,42 @@ THEN (based on user goal):
 
 **Fallback:** If agents are not installed (e.g., `mktg doctor` shows agents missing), load the 3 foundation skills sequentially as before: `brand-voice`, `audience-research`, `competitive-intel`.
 
+## Upstream Catalogs
+
+`mktg` now has a third first-class concept alongside skills and agents: **upstream catalogs** — external OSS projects mktg builds on top of via REST API rather than vendoring source or linking SDKs. Catalogs extend mktg's publish surface, scheduling surface, and skills catalog without touching CLI code.
+
+### Registered catalogs (v1)
+
+| Catalog | What it adds | Skill it powers | Env vars | Activation check |
+|---|---|---|---|---|
+| `postiz` | 30+ social provider integrations (LinkedIn, Reddit, Bluesky, Mastodon, Threads, Instagram, TikTok, YouTube, Pinterest, Discord, Slack, etc.) via a BYO [postiz-app](https://github.com/gitroomhq/postiz-app) instance (hosted or Docker self-host) | `/postiz` + `/social-campaign` Phase 5 routing | `POSTIZ_API_KEY`, `POSTIZ_API_BASE` (defaults to `https://api.postiz.com`) | `mktg catalog info postiz --json --fields configured,missing_envs` |
+
+### Catalog-aware routing rules
+
+Always check catalog readiness BEFORE routing any social distribution request. The decision tree:
+
+1. **User names a platform** (e.g., "LinkedIn", "Reddit"):
+   - X/Twitter → `typefully` (always — threads are canonical there)
+   - LinkedIn / Threads / Bluesky / Mastodon:
+     - Both `typefully` AND `postiz` configured → `postiz` (richer provider catalog)
+     - Only `typefully` configured → `typefully`
+     - Only `postiz` configured → `postiz`
+     - Neither → `content-atomizer` file-only path
+   - Reddit / Instagram / TikTok / YouTube / Pinterest / Discord / Slack:
+     - `postiz` configured → `postiz`
+     - `postiz` not configured → `content-atomizer` writes file + explain to user
+2. **User wants a full campaign** → `social-campaign` orchestrator (its Phase 5 now auto-picks typefully vs postiz per post).
+3. **User wants atomization** → `content-atomizer` (file generation only — distribution is a separate step).
+4. **User wants multi-platform launch/directories** → `startup-launcher` (directories, not social channels).
+
+### AGPL firewall
+
+Postiz is AGPL-3.0 licensed. mktg NEVER links `@postiz/node`; we only call the REST API via raw `fetch`. License boundary is enforced by a test in `package.json`. Agents never need to know about this — the adapter handles it.
+
+### Adding a new catalog
+
+See `AGENTS.md` §Drop-in Catalog Contract. Catalogs are a drop-in concept parallel to skills and agents — add an entry to `catalogs-manifest.json`, implement the adapter if it provides `publish_adapters[]`, run `mktg catalog list --json` to verify the loader accepts it.
+
 ## Skill Redirects
 
 These old names map to new skills:
@@ -307,7 +370,10 @@ These old names map to new skills:
 | `mktg compete diff <url>` | Show detailed changes for a specific competitor |
 | `mktg run <skill> --learning '{...}'` | Run a skill and record what you learned to `brand/learnings.md` |
 | `mktg brand append-learning --input '{...}'` | Record a learning outside of a skill run |
-| `mktg list --json` | Show all 49 skills with metadata |
+| `mktg list --json` | Show all 50 skills with metadata |
+| `mktg catalog list --json` | **Upstream catalogs** — show registered external catalogs (e.g., `postiz` for 30+ social providers) with configured/installed state |
+| `mktg catalog info <name> --json` | Show a single catalog's full entry + computed `configured`/`missing_envs`/`resolved_base` |
+| `mktg catalog status --json` | Fleet-wide catalog health across all registered catalogs |
 | `mktg brand kit --json` | **Structured brand tokens** — parse creative-kit.md into typed JSON (colors, typography, visual, visualBrandStyle) |
 | `mktg brand kit get <section> --json` | Addressable kit sections: `colors`, `typography`, `visual`, `visualBrandStyle` |
 | `mktg brand claims --json` | Extract Claims Blacklist from landscape.md as structured JSON |
@@ -383,7 +449,7 @@ These are just as important as the technical ones:
 
 | Anti-pattern | Instead | Why |
 |-------------|---------|-----|
-| Presenting a menu of all 49 skills | Recommend 1-2 specific skills based on context | Menus shift the decision to the builder, who doesn't know marketing well enough to choose. That's your job. |
+| Presenting a menu of all 50 skills | Recommend 1-2 specific skills based on context | Menus shift the decision to the builder, who doesn't know marketing well enough to choose. That's your job. |
 | Asking "what do you want to do?" | Tell them what you'd do and why, then confirm | They hired a CMO, not a waiter. Lead with your recommendation. |
 | Running brainstorm when you already know the path | Share your read, suggest a direction, discuss | Brainstorm is for genuine uncertainty. Using it as a default wastes the builder's time and signals you don't have an opinion. |
 | Routing silently to a skill | Say what you're doing and why in one sentence | Silent routing feels like a black box. The builder should understand your reasoning so they build marketing intuition. |

package/skills/cmo/rules/brand-file-map.md

@@ -0,0 +1,193 @@
+# Brand File → Dependent Skills (Reverse Index)
+
+When a `brand/*.md` file changes, some downstream skills become stale and should re-run. This map answers: **"I just updated `<file>` — what's now out of date?"**
+
+/cmo reads this on every "update brand" request and proactively flags regen candidates.
+
+---
+
+## `brand/voice-profile.md` — HIGH impact
+
+Changing voice invalidates tone on every copy and distribution asset ever produced.
+
+**Skills that must re-run (if the asset is still in use):**
+
+| Skill | What regenerates |
+|---|---|
+| `direct-response-copy` | Landing pages, sales copy, cold emails, headlines. |
+| `seo-content` | All published articles (at minimum edit passes). |
+| `lead-magnet` | Lead magnet prose, landing page, follow-up sequence. |
+| `newsletter` | Template + recent issues. |
+| `email-sequences` | Welcome, nurture, launch, win-back flows. |
+| `content-atomizer` | Any `marketing/social/` output. |
+| `social-campaign` | Phase 2 voice calibration re-runs. |
+| `typefully` / `postiz` drafts | Re-review scheduled posts. |
+| `creative` | Ad copy variants. |
+| `marketing-demo` narration / `slideshow-script` / `video-content` scripts | Voice-calibrated scripts. |
+| `startup-launcher` | Platform copy + tagline variants. |
+
+**Routing rule:** when voice changes, surface a rewrite plan before auto-running anything. The user picks which assets are worth the rewrite.
+
+---
+
+## `brand/audience.md` — HIGH impact
+
+Targeting changes mean every copy decision needs re-calibration.
+
+**Skills affected:**
+
+| Skill | Why |
+|---|---|
+| `direct-response-copy` | "For whom" framing shifts. |
+| `seo-content` | Search intent + watering-hole calibration. |
+| `lead-magnet` | Asset type (ebook vs calculator) depends on audience. |
+| `email-sequences` | Segment splits and pacing. |
+| `newsletter` | Topic calendar pivot. |
+| `content-atomizer` | Platform priority shifts (watering holes). |
+| `positioning-angles` | Re-run — positioning is always relative to audience. |
+| `social-campaign` | Platform mix re-planned. |
+| `pricing-strategy` | Willingness-to-pay changes. |
+| `free-tool-strategy` | Tool utility hinges on audience pain. |
+| `conversion-flow-cro` | Flow friction depends on audience sophistication. |
+
+---
+
+## `brand/positioning.md` — HIGH impact
+
+Positioning drives landing pages, launch copy, and competitive framing.
+
+**Skills affected:**
+
+| Skill | Why |
+|---|---|
+| `direct-response-copy` | Landing page hero, value prop, differentiation. |
+| `page-cro` | "Why us" rewrite. |
+| `launch-strategy` | Angle selection. |
+| `startup-launcher` | All 56 platform taglines + descriptions. |
+| `competitor-alternatives` | "vs." framing. |
+| `newsletter` | Editorial angle. |
+| `slideshow-script` | Narrative frameworks (AIDA/PAS/BAB) depend on angle. |
+| `creative` | Ad variant themes. |
+| `brand-kit-playground` | Voice preview text. |
+
+---
+
+## `brand/competitors.md` — MEDIUM impact
+
+**Skills affected:**
+
+| Skill | Why |
+|---|---|
+| `competitor-alternatives` | Full regen — this IS the input. |
+| `competitive-intel` | Refresh baseline. |
+| `landscape-scan` | Re-ground market snapshot. |
+| `positioning-angles` | Gaps shift. |
+| `direct-response-copy` | Objection handling updates. |
+| `seo-content` | Comparison content + "alternatives to" keywords. |
+| `mktg compete scan` | Watchlist sync. |
+
+---
+
+## `brand/landscape.md` — HIGH impact (Claims Blacklist)
+
+Landscape drives the **Claims Blacklist** — any claim not grounded in current landscape data is off-limits.
+
+**Skills affected (ALL content-producing):**
+
+| Skill | Why |
+|---|---|
+| `direct-response-copy` | Claims Blacklist enforcement on every headline. |
+| `seo-content` | Market claims gated. |
+| `newsletter` | Editorial claims gated. |
+| `lead-magnet` | Proof claims gated. |
+| `content-atomizer` | Platform posts inherit Blacklist. |
+| `social-campaign` | Phase 0 reads Blacklist. |
+| `launch-strategy` | Market-size/category claims gated. |
+| `startup-launcher` | Platform copy Blacklist-checked. |
+| `competitor-alternatives` | Comparison claims Blacklist-checked. |
+| `ai-seo` | Citation-worthy claims must be Blacklist-safe. |
+
+**Freshness critical:** landscape is usable for 14 days. Stale landscape = stale Blacklist = risk of unfounded claims shipping.
+
+---
+
+## `brand/keyword-plan.md` — MEDIUM impact
+
+**Skills affected:**
+
+| Skill | Why |
+|---|---|
+| `seo-content` | Primary/secondary/long-tail targeting. |
+| `ai-seo` | Entity optimization vocabulary. |
+| `competitor-alternatives` | Comparison keyword selection. |
+| `seo-audit` | URL structure + schema recommendations. |
+| `free-tool-strategy` | Tool naming + SEO anchor. |
+
+---
+
+## `brand/creative-kit.md` — MEDIUM impact (visual only)
+
+**Skills affected:**
+
+| Skill | Why |
+|---|---|
+| `creative` | Visual briefs use the kit. |
+| `image-gen` | Style anchors. |
+| `visual-style` | Source file — regenerate if deliberate. |
+| `brand-kit-playground` | Preview reflects the kit. |
+| `paper-marketing` | Design system for designer agents. |
+| `slideshow-script` | Visual styling of generated slides. |
+| `video-content` | Color palette, typography for Remotion compositions. |
+| `app-store-screenshots` | Visual identity on app store pages. |
+| `frontend-slides` | Slide visual theme. |
+
+---
+
+## `brand/stack.md` — LOW impact (integration alerts)
+
+**Skills affected:**
+
+| Skill | Why |
+|---|---|
+| `email-sequences` | ESP choice (Resend, Mailchimp, etc.) |
+| `send-email` | API wiring points. |
+| `typefully` | Social set IDs, connected accounts. |
+| `postiz` | Connected integrations baseline. |
+| `newsletter` | Platform selection (ConvertKit, Beehiiv, Substack). |
+| `agent-email-inbox` / `resend-inbound` | Domain + webhook config. |
+
+---
+
+## `brand/assets.md` — Append-only (no regen trigger)
+
+Logs created assets (content, images, videos, scheduled posts). `/cmo` reads this to avoid duplicating work — if an asset exists, don't silently overwrite.
+
+---
+
+## `brand/learnings.md` — Append-only (informs routing)
+
+Logs what worked, what didn't, what's been tried. `/cmo` reads this to:
+- Avoid re-running a failed experiment.
+- Compound insights across sessions.
+- Pick the next move based on past outcomes.
+
+Never regenerates any skill — but every post-skill reflection should append an entry via `mktg brand append-learning --input '{...}'`.
+
+---
+
+## Cascade severity summary
+
+| File | Severity | When it changes, /cmo should… |
+|---|---|---|
+| `voice-profile.md` | 🔴 HIGH | Offer a rewrite plan for every downstream copy/distribution asset. |
+| `audience.md` | 🔴 HIGH | Offer re-calibration for copy, distribution, pricing. |
+| `positioning.md` | 🔴 HIGH | Re-run landing page + launch copy. |
+| `landscape.md` | 🔴 HIGH | Warn: Claims Blacklist changed — every piece of content needs re-check. |
+| `competitors.md` | 🟡 MEDIUM | Refresh comparison/alternatives pages, competitive intel. |
+| `keyword-plan.md` | 🟡 MEDIUM | Flag SEO content + AI SEO for refresh. |
+| `creative-kit.md` | 🟡 MEDIUM | Visual skills inherit automatically; flag published visual assets. |
+| `stack.md` | 🟢 LOW | Integration alerts only. |
+| `assets.md` | — | No regen; avoids duplication. |
+| `learnings.md` | — | No regen; informs future routing. |
+
+**Rule of thumb:** when a HIGH file changes, /cmo surfaces a rewrite plan **before** accepting any downstream request. Don't produce new copy on top of stale inputs.

package/skills/cmo/rules/command-reference.md

@@ -0,0 +1,143 @@
+# `mktg` Command Reference (CMO-facing)
+
+Full CLI surface /cmo uses to inspect state, route skills, and orchestrate catalogs. Every command supports `--json` and most support `--dry-run`, `--fields`, `--confirm` per project DX standards.
+
+Use these commands **deliberately**. At activation, run the minimum set to know what's possible (status + doctor). During playbook execution, re-invoke per-step as needed.
+
+---
+
+## Core state + health
+
+| Command | CMO uses this when… |
+|---|---|
+| `mktg status --json` | Always at activation. Returns brand state, health (`ready`/`incomplete`/`needs-setup`), integrations configured. This is the first read. |
+| `mktg status --json --fields brand.populated,brand.missing,brand.stale` | To snap to the progressive enhancement ladder (see `rules/progressive-enhancement.md`). |
+| `mktg doctor --json` | On setup + whenever a skill fails unexpectedly (missing tools, broken integrations). |
+| `mktg doctor --fix --dry-run --json` | Preview auto-remediations before running them. |
+| `mktg doctor --fix --json` | Auto-create missing brand files, install missing skills, patch integrations. |
+
+---
+
+## Brand memory
+
+| Command | CMO uses this when… |
+|---|---|
+| `mktg context --json` | Compile all brand files into one token-budgeted artifact before running a multi-skill chain (saves context window). |
+| `mktg context --layer <foundation\|strategy\|execution\|distribution> --json` | Pull only the brand slice the skill needs. |
+| `mktg context --budget <tokens> --json` | Truncate to fit a specific token ceiling. |
+| `mktg brand freshness --json` | Before running content skills — confirm brand files aren't stale. |
+| `mktg brand kit --json` | Structured brand tokens (colors, typography, visual style) — used by `image-gen`, `creative`, `paper-marketing`. |
+| `mktg brand kit get <section> --json` | Addressable section — `colors`, `typography`, `visual`, `visualBrandStyle`. |
+| `mktg brand claims --json` | Extract Claims Blacklist from `landscape.md`. **Read this before every piece of content.** |
+| `mktg brand append-learning --input '{...}'` | Log what worked/didn't after a session — compounds future routing. |
+| `mktg brand export --json` | Snapshot brand state for backup or hand-off. |
+| `mktg brand diff --json` | Show brand changes since last baseline. |
+| `mktg brand delete <file> --confirm` | Destructive — only when user explicitly asks. |
+| `mktg brand reset --confirm` | Nuclear — wipes `.mktg/` execution state. User must explicitly request. |
+
+---
+
+## Planning + execution loop
+
+| Command | CMO uses this when… |
+|---|---|
+| `mktg plan --json` | Returning user — show the prioritized task queue. |
+| `mktg plan next --json` | Single highest-priority task. Default for "what should I do?" after session start. |
+| `mktg plan complete <id> --json` | After a skill successfully finishes — persists progress across sessions via `.mktg/plan.json`. |
+| `mktg plan --save --json` | Stream-persist the plan for long-running orchestration. |
+| `mktg run <skill> --json` | Direct skill invocation (bypasses the usual Claude Code slash-command flow). Use when the orchestration layer needs programmatic control. |
+| `mktg run <skill> --learning '{...}'` | Run a skill + record the learning atomically. |
+
+---
+
+## Distribution
+
+| Command | CMO uses this when… |
+|---|---|
+| `mktg publish --list-adapters --json` | Show available adapters (`typefully`, `resend`, `file`, `postiz`) + configured status. |
+| `mktg publish --adapter <name> --dry-run --input '<json>' --json` | Preview before any real send. Always dry-run first. |
+| `mktg publish --adapter <name> --confirm --input '<json>' --json` | Execute publishing. Only with user approval. |
+| `mktg publish --ndjson` | Streaming progress for multi-item campaigns. |
+
+---
+
+## Competitive intelligence
+
+| Command | CMO uses this when… |
+|---|---|
+| `mktg compete list --json` | See all tracked competitor URLs. |
+| `mktg compete watch <url> --json` | Add a competitor to the monitoring loop. |
+| `mktg compete scan --json` | Run the scan — detect changes since last snapshot. |
+| `mktg compete scan --ndjson` | Streaming scan for large watchlists. |
+| `mktg compete diff <url> --json` | Detailed change report for one competitor. |
+
+---
+
+## Upstream catalogs (NEW — post-Phase B)
+
+Catalogs extend mktg via external REST APIs (postiz = 30+ social providers; future: cal.com, listmonk, etc.). Registered in `catalogs-manifest.json`.
+
+| Command | CMO uses this when… |
+|---|---|
+| `mktg catalog list --json` | Survey registered catalogs. |
+| `mktg catalog info <name> --json --fields configured,missing_envs` | Per-catalog readiness check. Returns full `CatalogEntry` plus computed `configured`, `missing_envs`, `resolved_base`. |
+| `mktg catalog status --json` | Fleet-wide health across all registered catalogs (`configured`, `healthy`, `detail` per catalog). |
+| `mktg catalog sync --dry-run --json` | Check for upstream version drift (compares pinned version against GitHub releases). v1 is read-only. |
+| `mktg catalog add <name> --confirm --json` | Register a new catalog. Destructive-guarded. |
+
+**Routing impact:** before routing to any skill backed by a catalog (e.g., `postiz`), CMO runs `catalog info <name>` to confirm `configured: true`. If not, surface the exact fix using `missing_envs`.
+
+---
+
+## Agent self-discovery
+
+| Command | CMO uses this when… |
+|---|---|
+| `mktg list --json` | Full skill registry with metadata (all 50 skills). |
+| `mktg list --routing --json` | Just the routing fields — triggers, categories, layers. Cheap to read, used to verify routing decisions. |
+| `mktg schema --json` | All commands with response shapes. Used when the orchestrator needs to programmatically understand the CLI surface. |
+| `mktg schema <command> --json` | Detailed schema for one command including `responseSchema` + examples. |
+| `mktg skill info <name> --json` | Skill metadata: dependencies, reverse dependencies, install status. |
+| `mktg skill validate <path> --json` | Validate a SKILL.md against platform + mktg specs (used by `create-skill`). |
+| `mktg skill graph --json` | Dependency DAG across all 50 skills. Used when planning a multi-skill chain. |
+| `mktg skill check <name> --json` | Check if a skill's prerequisites are satisfied (brand files present, deps installed). |
+
+---
+
+## Setup + lifecycle
+
+| Command | CMO uses this when… |
+|---|---|
+| `mktg init --yes` | Fresh project. Creates `brand/` + installs 50 skills + 5 agents + 1 catalog. |
+| `mktg init --from <url> --yes` | Zero-to-CMO in 90 seconds. Scrapes URL, auto-populates `voice-profile.md`, `positioning.md`, `audience.md`, `competitors.md` with real data. Use when the project has a live website. |
+| `mktg update --json` | Refresh skills/agents/catalogs from the package. Run after `npm update`. |
+| `mktg transcribe <url\|path> --json` | Audio/video → transcript. Wraps `whisper-cli` (whisper.cpp) + `yt-dlp` + `ffmpeg`. Used before `content-atomizer` for podcast/video source material. |
+
+---
+
+## External tools (chained via `mktg doctor` detection)
+
+Not `mktg` subcommands, but /cmo knows when to suggest them (see `CLAUDE.md` §Ecosystem):
+
+| Tool | When CMO suggests it |
+|---|---|
+| `/ply` | Browser automation for Instagram/TikTok/Facebook/YouTube (no API). |
+| `/last30days` | Quick claim verification — "is this still true?" Ground truth before a content piece. |
+| `/landscape-scan` (chained skill) | Full ecosystem snapshot when brand/landscape.md is missing or stale. |
+| `firecrawl` CLI | Single-page scrape (invoked through `/firecrawl` skill). |
+| `summarize` CLI | Compress long text. Invoked through `/summarize` skill. |
+| `gh` | GitHub operations when publishing to GitHub (releases, READMEs). |
+
+---
+
+## Invocation patterns
+
+**Always use `--json`.** TTY output is for humans; JSON is the orchestrator contract.
+
+**Always `--dry-run` before mutating.** Every destructive command (`brand delete`, `brand reset`, `skill unregister`, `publish`, `catalog add`) requires either `--dry-run` to preview or `--confirm` to execute. Never skip this.
+
+**Use `--fields` aggressively.** Most commands return rich responses; CMO only needs the slice relevant to the current routing decision. Example: `mktg status --json --fields brand.populated,integrations` trims 20KB down to 500 bytes.
+
+**Stream when it's a list.** `--ndjson` on `mktg plan`, `mktg compete scan`, `mktg publish` — lets CMO react to each item without waiting for the batch.
+
+See `CONTEXT.md` at the repo root for the full agent-facing CLI cheatsheet.

package/skills/cmo/rules/context-switch.md

@@ -63,3 +63,37 @@ Agent:
   3. Load brand context from ~/projects/halaali/brand/
   4. Work exclusively in Halaali context
 ```
+
+## Bootstrapping a fresh project
+
+If the target directory has no `brand/` (i.e., `mktg status --json` returns `health: "needs-setup"`):
+
+1. **Ask the user if they have a public URL for the project.**
+   - YES → offer `mktg init --from <url> --yes`. This scrapes the URL via firecrawl + chains foundation skills to auto-populate `voice-profile.md`, `positioning.md`, `audience.md`, `competitors.md` with real data. Roughly 90 seconds, end-to-end.
+   - NO → offer `mktg init --yes`. Scaffolds `brand/` with templates + installs all 50 skills + 5 agents + catalogs. User fills in brand files via the Full Product Launch playbook.
+2. Confirm the project name that landed matches the user's intent (`mktg status --json` after init returns `project.name`).
+3. Route based on the ladder (see `rules/progressive-enhancement.md`) — a fresh init is L0.
+
+## Brand/ isolation per project
+
+Each project owns its own `brand/` directory sitting at the project's `cwd`. There is no global `brand/`; isolation is by directory boundary, enforced by `--cwd` on every `mktg` call.
+
+- **Never** write to `~/.config/mktg/` or any shared location for brand data. Brand lives in the project.
+- **Never** read brand files from another project to seed the current one. If the user wants to copy a voice profile from Project A to Project B, they do it explicitly via `mktg brand export` + `mktg brand import --confirm`.
+- **Learnings are project-scoped.** `brand/learnings.md` in Project A doesn't inform routing in Project B — even if the same builder runs both.
+
+## Project-aware command invocation
+
+Every `mktg` command CMO runs in multi-project mode passes `--cwd`:
+
+```bash
+mktg status --json --cwd ~/projects/ceo-app
+mktg plan next --json --cwd ~/projects/ceo-app
+mktg publish --adapter postiz --dry-run --cwd ~/projects/ceo-app --input '...'
+```
+
+Omitting `--cwd` defaults to `process.cwd()` — fine for single-project terminals, dangerous in a multi-project session. When in doubt, be explicit.
+
+## Cross-project "noticing" vs acting
+
+CMO can mention patterns across projects (*"CEO App's audience watering holes overlap with Halaali's — could be worth cross-promotion"*) but never *acts* on cross-project insights without explicit confirmation. The builder owns the decision.