@jairodri/huckleberry-cli 1.0.2 → 1.1.0

package/skills/cmo/rules/brand-memory.md

@@ -0,0 +1,158 @@
+---
+name: cmo-brand-memory
+description: |
+  Brand memory protocol for reading and writing persistent brand context.
+  How skills interact with the brand/ directory.
+---
+
+# Brand Memory Protocol
+
+Brand memory lives in `./brand/` at the project root. It accumulates as skills run and persists across sessions.
+
+## Directory Structure
+
+```
+./brand/
+  voice-profile.md     ← Written by brand-voice
+  positioning.md       ← Written by positioning-angles
+  audience.md          ← Written by audience-research
+  competitors.md       ← Written by competitive-intel
+  landscape.md         ← Written by landscape-scan
+  creative-kit.md      ← Written by creative (setup mode)
+  stack.md             ← Written by mktg init
+  keyword-plan.md      ← Written by keyword-research
+  assets.md            ← Append-only (all skills)
+  learnings.md         ← Append-only (all skills)
+```
+
+## File Ownership
+
+Each file has a primary owner — the skill that creates and maintains it. Other skills may read any file but never overwrite a file they do not own.
+
+**Profile files** (create-or-overwrite): voice-profile, positioning, audience, competitors, landscape, creative-kit, stack, keyword-plan.
+**Append-only files** (never overwrite): assets.md, learnings.md.
+
+## Reading Protocol
+
+### 1. Check for the directory
+
+On every skill invocation, check whether `./brand/` exists.
+
+- **Exists**: Load relevant files (step 2).
+- **Does not exist**: Skip brand loading. Do not error. Note: "No brand profile yet. Run /cmo or mktg init to set one up, or I'll work without it."
+
+### 2. Load only what you need
+
+Each skill declares which brand files it reads. Do not load everything.
+
+| Skill | Reads |
+|-------|-------|
+| brand-voice | positioning.md, audience.md |
+| positioning-angles | audience.md, competitors.md |
+| direct-response-copy | voice-profile.md, positioning.md, audience.md, landscape.md |
+| seo-content | voice-profile.md, keyword-plan.md, audience.md, landscape.md |
+| email-sequences | voice-profile.md, positioning.md, audience.md, landscape.md |
+| content-atomizer | voice-profile.md, creative-kit.md, landscape.md |
+| keyword-research | positioning.md, audience.md, competitors.md |
+| lead-magnet | voice-profile.md, positioning.md, audience.md |
+| newsletter | voice-profile.md, audience.md, learnings.md |
+| creative | voice-profile.md, positioning.md, creative-kit.md |
+
+### 3. Handle missing files gracefully
+
+If a file does not exist, do not error. Instead:
+
+- Note what is missing internally.
+- Consolidate into a single status line: "Brand profile partial (loaded voice-profile.md; positioning and audience not yet created)."
+- Proceed with reasonable defaults or ask the user the questions that file would have answered.
+- Suggest one high-impact next step: "Running brand-voice would give me your tone profile."
+
+### 4. Show context use visibly
+
+When loading brand context, show the user:
+
+- "Using your brand voice: conversational-but-sharp, short sentences."
+- "Your positioning is 'The Anti-Course Course' — building this around that angle."
+- "Found 3 competitor profiles. Differentiating against them."
+
+### 5. Detect stale data
+
+If a file seems outdated or conflicts with what the user is saying:
+
+- Flag it: "Your voice profile says you avoid humor, but your brief is playful. Update the voice profile?"
+- Never silently override brand memory with session context. Always confirm.
+
+## Writing Protocol
+
+### Profile files (create-or-overwrite)
+
+1. Generate content through the skill's workflow.
+2. If file exists: read it first, show what will change, ask for confirmation.
+3. Write to `./brand/{filename}.md`.
+4. Include a `## Last Updated` line with date and skill name.
+5. Confirm: "Created brand/voice-profile.md."
+
+### Append-only files (assets.md, learnings.md)
+
+1. Read existing file to understand current entries.
+2. Append new entries at the bottom of the appropriate section.
+3. Never overwrite or truncate.
+4. Confirm: "Added 3 new entries to brand/assets.md."
+
+## Respect the Claims Blacklist
+
+`brand/landscape.md` contains a **Claims Blacklist** — a table of ecosystem claims that are factually wrong, outdated, or unverifiable. This is a hard gate:
+
+1. Before any content skill makes a claim about the market, ecosystem, competitors, or industry trends, check the Claims Blacklist in `brand/landscape.md`.
+2. If a claim appears in the blacklist, **DO NOT make it.** Use the "What To Say Instead" column for the approved alternative.
+3. If `landscape.md` does not exist or is stale (>14 days), warn the user before making ecosystem claims: "I don't have a current ecosystem snapshot. Any market claims I make may be outdated. Run /landscape-scan to ground my output in current reality."
+4. The blacklist is append-only within a landscape scan cycle. Skills never remove entries — only `/landscape-scan` refreshes the full file.
+
+This prevents the most common marketing failure mode: confidently stating things about the market that are no longer true.
+
+## Use the Visual Brand Style
+
+`brand/creative-kit.md` may contain a `## Visual Brand Style` section — the visual identity for image generation. When routing to `/image-gen`:
+
+1. If the Visual Brand Style section exists and is populated, image-gen will use it automatically (L3 enhancement).
+2. If it doesn't exist, suggest: "You don't have a visual brand style defined yet. Run `/visual-style` first for consistent on-brand images, or I can generate without it."
+3. If `creative-kit.md` doesn't exist at all, image-gen still works at L0 (generic) — it will ask the user directly.
+
+## Progressive Enhancement Levels
+
+- **L0**: Zero context. Skill works by asking the user 3-5 key questions.
+- **L1**: Voice profile only. Output matches brand tone.
+- **L2**: Voice + positioning + audience. Output is targeted and differentiated.
+- **L3**: Full brand + keyword plan + landscape — output strategic, data-informed, and grounded in current ecosystem reality.
+- **L4**: Full brand + learnings + campaign history. Output compounds on past results.
+
+Every skill must work at L0. Brand memory enhances output — it never gates it.
+
+## Learnings Journal Format
+
+```markdown
+## What Works
+- [YYYY-MM-DD] [/skill-name] Specific, actionable finding with numbers
+
+## What Doesn't Work
+- [YYYY-MM-DD] [/skill-name] Specific finding with numbers
+
+## Audience Insights
+- [YYYY-MM-DD] [/skill-name] Behavioral or preference insight
+```
+
+Always include date, skill name, and specific numbers. Not "emails worked well" but "subject lines under 40 chars had 15% higher open rates."
+
+## Feedback Collection
+
+After any major deliverable, collect feedback:
+
+```
+How did this perform?
+a) Great — shipped as-is
+b) Good — made minor edits
+c) Rewrote significantly
+d) Haven't used yet
+```
+
+Log (a) and (b) to learnings.md. For (c), ask what changed and log the diff. For (d), remind next session.

package/skills/cmo/rules/cli-runtime-index.md

@@ -0,0 +1,95 @@
+# CLI Runtime Index
+
+This is the /cmo operator index for the `mktg` CLI. Runtime schema wins:
+if this file conflicts with `mktg schema --json`, trust the live schema and
+update this file.
+
+## Refresh Commands
+
+Use these at the start of any deep CLI wiring task:
+
+```bash
+mktg schema --json --fields commands.name,commands.flags,commands.subcommands
+mktg status --json --fields health,brandSummary,integrations,nextActions
+mktg doctor --json --fields passed,checks
+mktg list --routing --json --fields skills.name,skills.triggers,skills.requires,skills.unlocks
+```
+
+Use command-specific schema before constructing a new payload:
+
+```bash
+mktg schema publish --json
+mktg schema studio --json
+mktg schema verify --json
+mktg schema ship-check --json
+mktg schema cmo --json
+```
+
+For Studio startup, prefer the CMO-aware launcher:
+
+```bash
+mktg studio --dry-run --json --intent cmo --session <id>
+mktg studio --open --intent cmo --session <id>
+```
+
+The launcher resolves the sibling Studio checkout first, then
+`MKTG_STUDIO_BIN`, then PATH. The dry-run response's `urls.dashboard` is the
+canonical URL to show or open.
+
+## Top-Level Commands
+
+Current runtime command set:
+
+| Command | /cmo use |
+|---|---|
+| `schema` | Discover command flags, subcommands, response shapes, and examples. |
+| `init` | Bootstrap brand files, skills, agents, and optional website import. |
+| `doctor` | Check local tools, skills, brand state, and integrations. |
+| `status` | Read the project marketing state and next setup actions. |
+| `list` | Inspect installed skills and routing metadata. |
+| `update` | Reinstall bundled skills/agents (default), check npm for newer mktg releases (`--check`), or upgrade the installed package (`--upgrade`). |
+| `skill` | Inspect, validate, register, add, log, and analyze skills. |
+| `brand` | Read/write/export/import/diff/reset brand memory. |
+| `run` | Load a skill for agent consumption and record execution. |
+| `transcribe` | Download and transcribe audio/video sources. |
+| `context` | Compile token-budgeted brand context. |
+| `plan` | Get or persist the prioritized execution loop. |
+| `publish` | Route content to native, Postiz, Typefully, Resend, or file adapters. |
+| `compete` | Watch, scan, list, and diff competitor pages. |
+| `dashboard` | Read typed dashboard contracts for local command-center views. |
+| `catalog` | Inspect and sync upstream service catalogs such as Postiz. |
+| `studio` | Launch or preview the companion local Studio, including CMO startup sessions. |
+| `verify` | Run ecosystem verification suites. |
+| `ship-check` | Aggregate go/no-go verdicts for release readiness. |
+| `cmo` | Invoke headless `/cmo` through the CLI with timeout and dry-run safety. |
+
+## Subcommand Families
+
+| Family | Subcommands |
+|---|---|
+| `skill` | `info`, `validate`, `graph`, `check`, `register`, `evaluate`, `unregister`, `add`, `history`, `log` |
+| `brand` | `export`, `import`, `update`, `freshness`, `diff`, `append-learning`, `claims`, `kit`, `delete`, `reset` |
+| `plan` | `next`, `complete` |
+| `compete` | `scan`, `watch`, `list`, `diff` |
+| `dashboard` | `snapshot`, `action`, `plan`, `outputs`, `publish`, `system`, `compete` |
+| `catalog` | `list`, `info`, `sync`, `status`, `add` |
+| `update` | flags: `--check` (npm version probe, read-only), `--upgrade` (run `npm i -g marketing-cli@latest`, honors `--dry-run`). Default = re-sync skills/agents. |
+
+## Discovery Discipline
+
+- Prefer `--json` for every command. TTY output is for humans.
+- Prefer `--fields` when the response is only for routing decisions.
+- Prefer `--dry-run` before every mutation.
+- Use `--ndjson` for long list or batch operations where incremental progress matters.
+- Never hardcode command counts, skill counts, route counts, or tab enums in agent logic.
+- If a static rule and runtime schema disagree, treat that as doc drift and follow runtime.
+
+## Safe Startup Sequence
+
+1. `mktg status --json --fields health,brandSummary,integrations,nextActions`
+2. `mktg doctor --json --fields passed,checks`
+3. `mktg list --routing --json --fields skills.name,skills.triggers,skills.requires,skills.unlocks`
+4. `mktg schema --json --fields commands.name,commands.flags,commands.subcommands`
+
+This gives /cmo the project state, broken dependencies, routing map, and
+current CLI contract before it takes action.

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

@@ -0,0 +1,167 @@
+# `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.
+
+Runtime schema is authoritative. If this hand-written reference differs from
+`mktg schema --json`, trust the live schema and update this file. For the full
+runtime command index, see `rules/cli-runtime-index.md`; for distribution
+routing, see `rules/publish-index.md`.
+
+---
+
+## 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 (`mktg-native`, `postiz`, `typefully`, `resend`, `file`) + configured status. |
+| `mktg publish --native-account --json` | Show or auto-provision the local mktg-native workspace account. |
+| `mktg publish --native-upsert-provider --input '{...}' --json` | Create/update an X, TikTok, Instagram, Reddit, or LinkedIn native provider. |
+| `mktg publish --adapter mktg-native --list-integrations --json` | List local native providers before targeting them in a manifest. |
+| `mktg publish --native-list-posts --json` | Read local native queue/history state. |
+| `mktg publish --adapter postiz --list-integrations --json` | List connected Postiz providers before creating external drafts. |
+| `mktg publish --adapter postiz --diagnose --json` | Verify hosted or self-hosted Postiz auth, `/api` routing, and active provider state. |
+| `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 update --check --json` | Read-only probe: ask the npm registry for the latest `marketing-cli` version and compare to the installed one. Returns `{ current, latest, upgradeAvailable, upgradeCommand }`. Use this before suggesting an upgrade. |
+| `mktg update --upgrade --dry-run --json` | Preview the npm upgrade command without spawning. Returns the planned `upgradeCommand`. |
+| `mktg update --upgrade --json` | Run `npm i -g marketing-cli@latest`. Surfaces EACCES guidance when the npm prefix is root-owned (suggest `sudo` or a user-owned prefix via nvm/fnm/volta). The package's postinstall re-syncs skills/agents automatically. |
+| `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. |
+| `mktg studio` | Launch the studio dashboard (Bun API + Next.js UI). Prefers sibling `mktg-studio/bin/mktg-studio.ts`, then `MKTG_STUDIO_BIN`, then PATH. |
+| `mktg studio --open` | Same, plus open the dashboard in the default browser. |
+| `mktg studio --open --intent cmo --session <id>` | Launch Studio into a CMO-aware dashboard session at `/dashboard?mode=cmo&session=<id>`. Use this for visual command-center startup. |
+| `mktg studio --dry-run --json --intent cmo --session <id>` | Structured preview envelope: resolved launcher, version, forwarded argv, ports, URLs. Zero side effects. Agent-safe for self-discovery. |
+| `mktg verify --dry-run --json` | Preview ecosystem verification suites before running them. |
+| `mktg verify --suite <name> --json` | Run a targeted verification suite. |
+| `mktg ship-check --dry-run --json` | Preview the release go/no-go checks. |
+| `mktg ship-check --fresh true --json` | Run the fresh aggregate ship verdict. |
+| `mktg cmo --dry-run --json` | Preview headless `/cmo` invocation without launching Claude. |
+| `mktg cmo --timeout <seconds> --json` | Run `/cmo` through the CLI with a hard wall-clock cap. |
+
+---
+
+## 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 |
+|---|---|
+| Browser profile | Browser automation for Instagram/TikTok/Facebook/YouTube when no API path is configured. |
+| `/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/communication.md

@@ -0,0 +1,15 @@
+# /cmo Communication — How You Talk to the Builder
+
+The builder doesn't speak marketing jargon. They say things like "I need more users" or "how do I get people to care" or "idk what to do next." Your job is to translate that into a marketing plan and explain it in builder terms.
+
+**When they're vague:**
+Don't route to `brainstorm` mechanically. First, share what you see. "Looking at your brand profile, you've got solid positioning but zero distribution. Here's what I'd do: write 3 SEO articles targeting your best keywords, then atomize them into social posts. That gives you a content engine. Want to start there, or do you have something else in mind?"
+
+**When they're specific:**
+Move fast. "You want a landing page, got it. I see your positioning is 'the anti-course course.' I'll write conversion copy around that angle. Your audience is indie hackers who hate traditional online courses. Give me 5 minutes."
+
+**When they're wrong (respectfully):**
+They might ask for the wrong thing. A builder who says "I need social posts" when they have no positioning, no audience research, and no content to repurpose, that's a red flag. Say so: "I can write social posts, but they won't land without knowing who we're talking to. Let me spend 10 minutes building your audience profile first, then the posts will actually convert."
+
+**When you need more context:**
+Ask ONE good question, not five. Bundle related questions into a single ask. Explain why you need the answer. "Before I write this email sequence, I need to know: what happens after someone signs up? Do they hit a paywall, a free trial, or an open product? That determines the entire nurture strategy."

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

@@ -0,0 +1,101 @@
+---
+name: cmo-context-switch
+description: |
+  Multi-project context switch protocol. How to safely switch between
+  projects without contaminating brand context.
+---
+
+> **Note:** Examples below use fictional brands (Acme, Lumi, Helm). Replace with your own brand context.
+
+# Context Switch Protocol
+
+The /cmo skill supports multiple projects. Each project has its own `brand/` directory with its own voice, audience, and positioning. Brand context must never leak between projects.
+
+## Rules
+
+### 1. Always verify project identity first
+
+Before any marketing work, run:
+
+```bash
+mktg status --json --cwd <target-path>
+```
+
+Verify the project name in the output matches the user's intent.
+
+### 2. Never carry brand context across projects
+
+When switching from Project A to Project B:
+
+- Do not apply Project A's voice profile to Project B's content.
+- Do not assume Project B's audience matches Project A's.
+- Do not reuse positioning angles, keywords, or competitive data.
+- Run a fresh `mktg status --json --cwd <path>` for the new project.
+
+### 3. Explicit project declaration
+
+If the user mentions multiple projects in one session:
+
+- Confirm which project they want to work on: "I see you've mentioned both Helm and Acme. Which one are we working on right now?"
+- Prefix all brand file reads with the correct project path.
+- When generating output, note which project context was used.
+
+### 4. Cross-project opportunities
+
+It is fine to notice patterns across projects:
+
+- "Your Helm audience overlaps with Acme's — you could cross-promote."
+- "The SEO keywords that work for Lumi might apply to Acme too."
+
+But never act on cross-project insights without explicit confirmation.
+
+## Multi-Project Session Pattern
+
+```
+User: "Let's work on marketing for Helm"
+Agent:
+  1. Run: mktg status --json --cwd ~/projects/helm
+  2. Load brand context from ~/projects/helm/brand/
+  3. Work exclusively in that context
+
+User: "Now switch to Acme"
+Agent:
+  1. Clear Helm context from working memory
+  2. Run: mktg status --json --cwd ~/projects/acme
+  3. Load brand context from ~/projects/acme/brand/
+  4. Work exclusively in Acme 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/helm
+mktg plan next --json --cwd ~/projects/helm
+mktg publish --adapter postiz --dry-run --cwd ~/projects/helm --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 (*"Helm's audience watering holes overlap with Acme's — could be worth cross-promotion"*) but never *acts* on cross-project insights without explicit confirmation. The builder owns the decision.

package/skills/cmo/rules/ecosystem.md

@@ -0,0 +1,125 @@
+# Ecosystem — External Tools, MCP, and Browser Variants
+
+/cmo doesn't re-implement tools mktg has already chained. It routes to the skill that wraps the tool. This file documents every external tool in the mktg ecosystem, when /cmo invokes it, and which skill owns the wrapping.
+
+**Detection:** always start with `mktg doctor --json` to see which tools are installed and which are missing. Don't route to a tool the user hasn't installed — surface the install hint first.
+
+---
+
+## External CLIs
+
+| Tool | What it does | CMO uses when… | Wrapped by |
+|---|---|---|---|
+| `firecrawl` | Web scrape, search, crawl of known URLs | User provides a URL + "scrape this"; `competitive-intel` / `landscape-scan` need current data from competitor sites. | `competitive-intel`, `landscape-scan`, `/firecrawl` skill directly |
+| `ffmpeg` | Video assembly, encoding (ffmpeg Quick + Enhanced tiers) | Any video output that doesn't need React/Remotion — slides → mp4, Ken Burns effects, audio mux. | `video-content` (tiers 1 + 2) |
+| `remotion` | Programmatic React video compositions | Polished animated video with precise timing, typography, and brand-calibrated visual system. | `video-content` (tier 3) |
+| `whisper-cli` (whisper.cpp) | Speech-to-text | Transcribe audio/video for atomization. Source for `content-atomizer` on podcasts, videos, voicemails. | `mktg transcribe` |
+| `yt-dlp` | Media download | Pull YouTube/TikTok/podcast sources for transcription. | `mktg transcribe` |
+| `gh` | GitHub CLI | Release notes, launch announcements, open-source project metadata for launch submissions. | `startup-launcher`, `app-store-changelog` |
+| `summarize` (steipete/summarize) | Token-bounded text compression | Compress long pasted content before passing to downstream skills. | `/summarize` skill directly |
+| `playwriter` / `opencli` | Browser automation backend (authenticated Chrome) | Whenever a configured browser profile is the distribution path. Standalone Playwright/Chromium is banned (Jairo directive 2026-08-28). | Browser profile skills |
+
+---
+
+## Browser distribution profiles
+
+When a platform has no usable API, /cmo routes to the browser. Multiple browser profiles may exist — each with its own logged-in session set. Pick the profile that matches the account the user wants to post from.
+
+| Profile | Accounts / services | CMO uses when… |
+|---|---|---|
+| Default browser profile | Shared local browser session | Generic automation, no specific account matters. |
+| Project browser profile | Project-specific logged-in accounts | The project declares a browser profile in `brand/stack.md`. |
+| Maintainer browser profile | Maintainer-owned services | Local maintainer workflows only; not part of the public package contract. |
+
+**Routing rule per project (cross-ref `rules/context-switch.md`):** project's `brand/stack.md` should name the canonical browser profile if the project has browser-distribution needs. CMO reads stack.md to pick the right profile.
+
+---
+
+## MCP servers
+
+### Exa MCP — semantic web research
+
+**What it is:** Managed Context Protocol server for deep web search. Distinct from firecrawl:
+- `firecrawl` — fetch a **known URL** (you have the link, want the content).
+- `Exa` — **semantic search** across the web with citations (you have a question, want grounded answers with sources).
+
+**CMO routes to Exa (via skill chains) when:**
+- `landscape-scan` needs current market data — top players, recent moves, category trends. Exa returns cited sources.
+- `competitive-intel` needs competitor discovery beyond a known list. Exa surfaces competitors the user hasn't named.
+- `audience-research` needs audience watering holes + professional bios. Exa finds LinkedIn profiles, podcast guests, community signals.
+- `keyword-research` needs live SERP gap analysis.
+- Any "is this still true?" claim check — `/last30days` chains Exa under the hood.
+
+**Wired via:** `.mcp.json` at the repo root. If `mktg doctor` shows Exa MCP unavailable, the skills that depend on it degrade to `firecrawl` + manual sourcing (lower quality, but not blocked).
+
+---
+
+## The API-vs-Browser Fork (critical routing decision)
+
+For every distribution request, /cmo picks one of two paths. Get this wrong and you silently fail.
+
+| Platform | Path | Skill |
+|---|---|---|
+| X / Twitter | Local queue/API | `mktg publish --adapter mktg-native` for local queue; `typefully` for real threads |
+| LinkedIn | Local queue/API | `mktg publish --adapter mktg-native`; Postiz or Typefully when connected externally |
+| Bluesky / Mastodon / Threads | API | `postiz` or `typefully` |
+| Reddit | Local queue/API/browser | `mktg publish --adapter mktg-native`; Postiz or browser profile for external posting |
+| Instagram | Local queue/API/browser | `mktg publish --adapter mktg-native`; Postiz or browser profile for external posting |
+| TikTok | Local queue/API/browser | `mktg publish --adapter mktg-native`; Postiz or browser profile for external posting |
+| YouTube | API (via postiz) OR browser | `postiz` if configured, else browser profile |
+| Pinterest | API | `postiz` |
+| Discord | API | `postiz` |
+| Slack | API | `postiz` |
+| Facebook | **Browser only** (no postiz, no Typefully) | browser profile |
+| Any transactional email | API | `send-email` (Resend) |
+| Any marketing email sequence | API | `email-sequences` (to the project's configured ESP from `stack.md`) |
+| Any App Store marketing | Hybrid — `asc` CLI for metadata, browser profile for screenshots upload | `app-store-screenshots`, `app-store-changelog` |
+
+**Decision flow:**
+
+1. Is the platform in the native rollout (`x`, `tiktok`, `instagram`, `reddit`, `linkedin`)?
+   - YES → use `mktg publish --adapter mktg-native` for local queue/history and Studio-native workflow.
+2. Does the user need real external network posting now?
+   - YES → check Postiz/Typefully/browser availability before claiming anything shipped.
+3. Is the user's `POSTIZ_API_KEY` set?
+   - YES → use Postiz for supported external social providers; keep Typefully reserved for X/threads specialist flows and fallback.
+   - NO → fall back to Typefully for X/LinkedIn/Threads/Bluesky/Mastodon where it fits; fall back to browser profile or file for Reddit/IG/TikTok.
+4. Is this an X thread?
+   - YES → always Typefully (thread UX is canonical there).
+5. Does `brand/stack.md` specify a browser profile?
+   - YES → use that profile for browser path.
+   - NO → ask for the browser profile to use before external posting.
+
+---
+
+## Skills that ARE the wrappers (don't re-implement)
+
+Anytime a user asks for something that an ecosystem tool does, don't call the tool directly — route to the skill that wraps it. The wrapping skill handles error cases, auth, retries, and brand calibration.
+
+| User says… | Route to | Don't… |
+|---|---|---|
+| "scrape this site" | `/firecrawl` | …call `firecrawl` CLI directly from `/cmo`. |
+| "transcribe this video" | `mktg transcribe` | …pipe `yt-dlp \| whisper-cli` manually. |
+| "make a video from slides" | `video-content` | …shell out to ffmpeg inline. |
+| "summarize this" | `/summarize` | …ask the LLM to compress; use the `summarize` CLI for token-bounded output. |
+| "post to Instagram" | `postiz` (if configured) else configured browser profile | …tell the user to do it manually. |
+| "research this market" | `landscape-scan` | …call Exa MCP directly; landscape-scan does the full chain with Claims Blacklist. |
+
+---
+
+## Install hints
+
+`mktg doctor` surfaces install commands per missing tool. If any of these fail at invocation time, `/cmo` tells the user exactly what to install before retrying:
+
+| Tool | Install |
+|---|---|
+| `firecrawl` | `npm i -g firecrawl` + `FIRECRAWL_API_KEY` |
+| `ffmpeg` | `brew install ffmpeg` |
+| `remotion` | `npm i -g @remotion/cli` |
+| `playwright-cli` | **BANNED (Jairo directive 2026-08-28)** — use `playwright` snippets through Playwriter (`npx -y playwriter@latest`) or `opencli` instead |
+| `gh` | `brew install gh` |
+| `whisper-cli` | `brew install whisper-cpp` |
+| `yt-dlp` | `brew install yt-dlp` |
+| `summarize` | `npm i -g @steipete/summarize` |
+
+Ecosystem table authoritative source: `CLAUDE.md` at repo root. This rules file mirrors the CMO-relevant slice; when they drift, CLAUDE.md wins.