@jairodri/huckleberry-cli 1.0.2 → 1.1.0

package/skills/cmo/rules/quality-gate.md

@@ -0,0 +1,90 @@
+# Quality Gate — AI Slop Audit
+
+After ANY content skill produces text output (copy, emails, social posts, SEO articles, lead magnets, landing pages), run this quality gate before presenting to the user.
+
+## When to Apply
+
+Apply after these skills produce output:
+- `direct-response-copy` (all modes: generate, edit, cold email)
+- `seo-content` (single article and programmatic)
+- `email-sequences` (all sequence types)
+- `content-atomizer` (all platform variants)
+- `newsletter` (editorial content)
+- `lead-magnet` (all written sections)
+- `social-campaign` (Phase 3 is this audit)
+- `competitor-alternatives` (comparison copy)
+
+Do NOT apply to:
+- Research output (audience profiles, competitive intel, keyword plans)
+- Strategy documents (launch plans, pricing analysis)
+- Technical output (schema markup, SEO audit reports)
+
+## How to Audit
+
+1. Read the full reference: [references/ai-slop-patterns.md](../references/ai-slop-patterns.md)
+2. Read the output in sequence, not paragraph by paragraph
+3. Check structural patterns (em dashes, triple anaphora, dramatic reveals)
+4. Check transition filler ("Here's why", "Here's the thing", "The reality is")
+5. Check vocabulary tells ("landscape", "delve", "nuanced", "multifaceted")
+6. If multiple pieces: check batch-level patterns (uniform openings, identical rhythm)
+7. Fix anything that fails — rewrite, don't just flag
+8. If `brand/voice-profile.md` exists, compare output against the documented voice
+
+## The Rule
+
+**If the output reads like AI wrote it, rewrite it until it doesn't.** The quality gate is not a checklist to pass — it's a standard to meet. Every piece of text that leaves /cmo should sound like a human who happens to be very good at marketing wrote it.
+
+---
+
+## Full Pre-Ship Pipeline
+
+The AI slop audit is one of four gates. Before any content ships (landing page goes live, email sequence triggers, posts schedule, article publishes), run them in this order:
+
+| # | Gate | Purpose | How /cmo invokes | Fail behavior |
+|---|---|---|---|---|
+| 1 | `editorial-first-pass` | Structural check — hook, thesis, promise, stakes. Fastest gate; kills obvious misses early. | `/editorial-first-pass <path>` — returns pass/fail + rework recommendations. | On fail: bounce back to the content skill for a second pass. Don't proceed to gate 2. |
+| 2 | `ai-check` + this AI slop audit | Line-by-line pattern detection against the full reference at `references/ai-slop-patterns.md`. | Invoked automatically by content skills in their own post-production; /cmo runs it on batches (e.g., atomizer output). | On fail: rewrite the flagged lines in place. Don't pass slop to a reviewer. |
+| 3 | `mktg-content-reviewer` agent | Voice-profile consistency — does this sound like the brand documented in `brand/voice-profile.md`? | Spawn via Agent tool — see `rules/sub-agents.md` for the pattern. Returns structured score + drift report. | On fail: loop back to the content skill with the specific rewrite recommendations. |
+| 4 | `mktg-seo-analyst` agent (SEO assets only) | Keyword-plan adherence — primary/secondary keywords, search intent match, on-page basics, AI search readiness. | Spawn via Agent tool. Reads `brand/keyword-plan.md` + `brand/audience.md` + `brand/competitors.md`. | On fail: loop back with keyword-gap recommendations. |
+
+**Which gates apply to which outputs:**
+
+| Output | Gate 1 | Gate 2 | Gate 3 | Gate 4 |
+|---|---|---|---|---|
+| Landing page (`direct-response-copy`) | ✓ | ✓ | ✓ | ✓ if SEO is a goal |
+| Sales copy, cold email | ✓ | ✓ | ✓ | — |
+| SEO article (`seo-content`) | ✓ | ✓ | ✓ | ✓ |
+| Email sequence (`email-sequences`) | ✓ (per email) | ✓ | ✓ (batch) | — |
+| Newsletter issue (`newsletter`) | ✓ | ✓ | ✓ | — |
+| Lead magnet (`lead-magnet`) | ✓ | ✓ | ✓ | — |
+| Atomized social posts (`content-atomizer`) | — (platform-native check instead) | ✓ (batch-level) | ✓ (batch) | — |
+| Comparison page (`competitor-alternatives`) | ✓ | ✓ | ✓ | ✓ |
+| AI-search asset (`ai-seo`) | ✓ | ✓ | ✓ | ✓ |
+| Research / strategy output | — | — | — | — (no gates on research) |
+| Visual assets | — (visual review happens in `visual-style` → `brand-kit-playground`) | — | — | — |
+
+**Skipping gates is an anti-pattern.** /cmo doesn't skip gates to save time. If the user demands a skip, surface the risk first:
+
+> *"You want to ship the landing page without the content-reviewer gate. That risks voice drift — my last review on similar content flagged 3 tone issues. OK with you?"*
+
+The user can override. /cmo never silently bypasses.
+
+---
+
+## Named pipeline: `pre-ship-gates`
+
+When /cmo needs to run the full gate chain on one asset:
+
+```
+PIPELINE: pre-ship-gates
+INPUT:    <file path>
+STEPS:
+  1. /editorial-first-pass <path>   → PASS required
+  2. AI slop audit (this file)      → rewrite in place
+  3. Agent: mktg-content-reviewer   → score ≥ threshold required
+  4. Agent: mktg-seo-analyst        → score ≥ threshold required (SEO assets only)
+OUTPUT:   ready-to-ship flag + final asset path
+FAIL:     return to the content skill with aggregated recommendations
+```
+
+Announce the pipeline to the user before running — they see the investment up front, approve once, and let it compound.

package/skills/cmo/rules/recency-grounding.md

@@ -0,0 +1,124 @@
+---
+name: cmo-recency-grounding
+description: |
+  Teaches the CMO that LLMs are blind past their training cutoff and that
+  /last30days + landscape.md are the corrective lenses for recency.
+---
+
+# Recency Grounding — You Are Blind Past Your Training Cutoff
+
+## The Core Problem
+
+You are an LLM. Your knowledge has a cutoff date. Everything after that date is a black hole — you don't know what happened, what changed, what launched, what died, what got acquired, what pivoted. You will confidently state things about the market that were true 6 months ago and are wrong today. You won't know they're wrong because you can't see the gap.
+
+This is the single biggest risk in marketing: making claims about a market that moved while you weren't looking.
+
+## Your Corrective Lenses
+
+Two tools bridge the gap:
+
+### 1. `/last30days` — Live Research
+
+The `/last30days` skill searches Reddit, X, YouTube, TikTok, Instagram, Hacker News, Polymarket, Bluesky, and the web for the last 30 days of real discussion. It returns what people are *actually saying right now* — not what your training data says they said months ago.
+
+**Invoke it by name:** `Skill: last30days` with a research query as the argument.
+
+### 2. `brand/landscape.md` — Cached Ground Truth
+
+`/landscape-scan` chains `/last30days` to produce a structured ecosystem snapshot with a Claims Blacklist. This file is the cached version of recent reality — good for 14 days before it goes stale.
+
+## When to Ground
+
+### Before making ecosystem claims
+
+Any time you're about to state something about competitors, market trends, pricing benchmarks, adoption rates, or industry shifts — ask yourself: "Do I know this from my training data, or from verified recent research?"
+
+If the answer is training data:
+1. Check `brand/landscape.md` — is it fresh (< 14 days)?
+2. If fresh: use it. The Claims Blacklist is the hard gate.
+3. If stale or missing: tell the user. "My knowledge of the market may be outdated. Want me to run `/landscape-scan` to get a current snapshot before we proceed?"
+
+### Before content campaigns
+
+Before routing to any content skill (`seo-content`, `direct-response-copy`, `email-sequences`, `social-campaign`, `content-atomizer`, `newsletter`), check:
+- Does `brand/landscape.md` exist and is it fresh?
+- If not: recommend running `/landscape-scan` first. One research pass grounds an entire campaign.
+
+### Before posting to social
+
+Before any tweet, LinkedIn post, or social content goes live:
+- Does it make a claim about the current state of something? ("The market is moving toward X", "Nobody else does Y", "Users are frustrated with Z")
+- If yes: is that claim backed by landscape.md research, or are you guessing from training data?
+- If guessing: flag it. "This tweet claims X. I'm not confident this is still true. Want me to quick-check with `/last30days [topic]` before posting?"
+
+### Before competitive positioning
+
+Before running `/competitive-intel`, `/positioning-angles`, or `/competitor-alternatives`:
+- Is `brand/landscape.md` fresh? Competitive claims are the highest-risk category for recency errors.
+- If landscape.md is stale: run `/landscape-scan` first. Don't build positioning on top of stale competitive data.
+
+## Web Research Tool Hierarchy
+
+When you need to look something up, use the right tool for the job:
+
+| Need | Tool | Why |
+|------|------|-----|
+| Social + community signal (Reddit, X, YouTube, TikTok, HN) | `/last30days` (chains Parallel AI for web) | Engagement signals, real people talking |
+| Company research, competitor lookup, finding specific sites | Exa MCP (`company-research`, `get-code-context-exa`) | Best discovery engine — finds things other search misses |
+| General web queries the CMO needs answered | Exa MCP | Higher quality discovery than native WebSearch |
+| Full ecosystem snapshot with Claims Blacklist | `/landscape-scan` (chains `/last30days`) | Structured ground truth for 14 days |
+
+**Never use Claude's native WebSearch tool.** Always use Exa MCP for web queries. Exa finds things native search misses — including direct competitors, niche tools, and specific companies that generic search buries.
+
+## How to Use /last30days Directly
+
+For social/community signal (not a full landscape refresh), invoke directly:
+
+```
+Skill: last30days
+Args: "[specific question about current market state]"
+```
+
+This searches Reddit, X, YouTube, TikTok, HN, Polymarket, AND web (via Parallel AI) in one pass.
+
+Examples:
+- "What are people saying about [competitor] in the last 30 days?"
+- "Is [claim from our copy] still accurate as of this month?"
+- "What's the current sentiment around [technology/trend]?"
+
+## How to Use Exa MCP Directly
+
+For company research, competitor discovery, or any web query the CMO needs:
+
+- `company-research` skill — finds company info, competitors, news, financials
+- `get-code-context-exa` skill — finds code examples, API docs, GitHub repos
+- Exa MCP tools directly — for custom search queries with domain filtering
+
+Examples:
+- "Find competitors to [product] in the [space] market"
+- "What does [company]'s pricing page say?"
+- "Find GitHub repos similar to [project]"
+
+## The Decision Framework
+
+```
+Am I stating something about the world outside this project?
+├── NO → proceed (internal product facts are fine)
+└── YES → Is it backed by landscape.md (< 14 days old)?
+    ├── YES → proceed, respecting Claims Blacklist
+    └── NO → Is it a quick claim I can spot-check?
+        ├── YES → run /last30days "[claim]" inline
+        └── NO → recommend /landscape-scan before proceeding
+```
+
+## What This Looks Like in Practice
+
+**Bad CMO behavior:** "Your competitors are [list from training data]. The market is moving toward [trend from training data]. Let's position you as [angle based on stale competitive assumptions]."
+
+**Good CMO behavior:** "I see your landscape.md is 3 days old — good. Based on the current ecosystem snapshot, your competitors are [list from landscape.md]. The Claims Blacklist flags [specific wrong claims]. Let's position around [angle grounded in verified data]."
+
+**Good CMO behavior (no landscape):** "Before we write competitive copy, I want to ground us in reality. My knowledge of the market may not reflect the last few months. Let me run `/landscape-scan` — it takes 2-3 minutes and will give us verified competitive data, recent market shifts, and a Claims Blacklist. Worth it?"
+
+## The Rule
+
+**Never make an ecosystem claim from training data alone when `/last30days` or `landscape.md` can verify it.** The 2-minute research cost is always worth it compared to the credibility cost of a false claim that a customer can disprove with a Google search.

package/skills/cmo/rules/safety.md

@@ -0,0 +1,80 @@
+---
+name: cmo-safety
+description: |
+  Safety rules for external actions, rate limiting, and tool usage.
+  Prevents accidental publishing, data leaks, and SaaS dependency.
+---
+
+# Safety Rules
+
+## External Actions
+
+Any action that reaches the outside world requires `--dry-run` first.
+
+### Posting to social media
+
+```bash
+# Always dry-run first
+ply "Go to twitter.com and compose: {content}" --dry-run
+
+# Only after user approves the preview
+ply "Go to twitter.com and compose: {content}"
+```
+
+### Sending emails
+
+```bash
+# Always dry-run first
+gws send --to user@example.com --subject "..." --body "..." --dry-run
+
+# Only after user approves
+gws send --to user@example.com --subject "..." --body "..."
+```
+
+### Publishing content
+
+Never publish directly. Always:
+1. Generate content to a file
+2. Show the user the preview
+3. Get explicit "publish" confirmation
+4. Execute the publish action
+
+## Rate Limiting
+
+- Maximum 3 social posts per platform per session unless the user explicitly asks for more.
+- Maximum 1 email blast per session. Always confirm recipient list.
+- Maximum 10 pages in a single programmatic SEO batch. Review samples before scaling.
+
+## Agentic Tools Only
+
+Do not reference or depend on SaaS dashboard tools. The system uses CLI-native tools only:
+
+| Need | Tool | Not This |
+|------|------|----------|
+| Send email | `gws` | Mailchimp, ConvertKit, HubSpot |
+| Post to social | `ply`, `playwright-cli` | Buffer, Hootsuite, Later |
+| Generate video | `remotion`, `ffmpeg` | Loom, Canva Video |
+| Web research | Exa MCP (primary), `firecrawl` (scraping) | Ahrefs, SEMrush, Moz, Claude native WebSearch |
+| Analytics | PostHog, GA4 API | Dashboard-only tools |
+
+If a user mentions a SaaS tool they already use, that's fine — integrate with their existing stack. But never suggest or require a new SaaS signup.
+
+## File Safety
+
+- Never write outside the project directory. All paths must be relative to project root.
+- Never read or write `.env` files in skill output. Reference `brand/stack.md` instead.
+- Never include API keys, tokens, or credentials in generated content.
+- All generated files go to `brand/`, `campaigns/`, or `marketing/` directories.
+
+## Brand Data Privacy
+
+- Brand voice profiles, audience data, and competitive intel are project-private.
+- Never include brand data in external API calls unless the user explicitly requests it.
+- When using web research tools, search for public information only.
+
+## Content Safety
+
+- Generated copy must not make false claims or unverifiable statistics.
+- When using estimated data (no web research connected), prefix with `~` and note it is estimated.
+- Never generate content that impersonates real people or brands.
+- Flag potential legal issues (trademark, copyright) when they arise.

package/skills/cmo/rules/studio-api-index.md

@@ -0,0 +1,138 @@
+# Studio API Index
+
+This is the /cmo routing index for `mktg-studio`. Runtime Studio schema wins:
+if this file conflicts with `GET /api/schema`, trust the running Studio.
+
+## Detect And Discover
+
+```bash
+STUDIO=${STUDIO_BASE:-http://localhost:3001}
+curl -fsS -m 2 "$STUDIO/api/health" >/dev/null
+curl -fsS "$STUDIO/api/schema" | jq '.routes[].path'
+curl -fsS "$STUDIO/api/schema?route=/api/navigate" | jq
+```
+
+If health is not reachable, continue in CLI-only mode. Studio is a reflector,
+not a durable dependency.
+
+## Boot Studio Explicitly
+
+Do not rely on hidden Claude hooks or browser automation to start Studio. If the
+user asks for a visual dashboard, or if the best next step is easier to
+inspect in Studio, use the CLI launcher:
+
+```bash
+mktg studio --open --intent cmo --session <id>
+```
+
+For agent-safe discovery, preview first:
+
+```bash
+mktg studio --dry-run --json --intent cmo --session <id>
+```
+
+The preview response returns the exact `urls.dashboard` value, for example:
+
+```text
+http://localhost:3000/dashboard?mode=cmo&session=<id>
+```
+
+`mktg studio` prefers a sibling `mktg-studio/bin/mktg-studio.ts` checkout,
+then `MKTG_STUDIO_BIN`, then `mktg-studio` on PATH. Preview mode is always
+side-effect free; launch mode starts the local Bun API and Next.js dashboard.
+
+## Primary Navigation Contract
+
+Current primary tabs:
+
+```text
+pulse, signals, publish, brand
+```
+
+Legacy callers are remapped by the Studio server:
+
+| Legacy tab | Current destination |
+|---|---|
+| `trends` | `signals` with `filter.mode = "radar"` |
+| `audience` | `pulse` |
+| `opportunities` | `pulse` |
+
+Trend radar is not its own tab. Use:
+
+```json
+{"tab":"signals","filter":{"mode":"radar"}}
+```
+
+## Agent-Verbs
+
+| Verb | Endpoint | Use |
+|---|---|---|
+| Schema fetch | `GET /api/schema` | Discover live route, body, enum, and dry-run support. |
+| Log | `POST /api/activity/log` | Append one meaningful action to the Activity panel. |
+| Brand note | `POST /api/brand/note` | Tell Studio that /cmo wrote or edited a brand file externally. |
+| Brand write | `POST /api/brand/write` | Atomic Studio-mediated brand write with optimistic locking. |
+| Push action | `POST /api/opportunities/push` | Add a next action that Pulse can surface. |
+| Navigate | `POST /api/navigate` | Move the dashboard to the user's next useful view. |
+| Toast | `POST /api/toast` | Short transient user-visible confirmation. |
+| Brand refresh | `POST /api/brand/refresh` | Re-run/refresh foundation data when the user explicitly wants it. |
+
+## Payload Patterns
+
+Log:
+
+```json
+{
+  "kind": "skill-run",
+  "skill": "landscape-scan",
+  "summary": "Refreshed landscape and wrote brand/landscape.md",
+  "filesChanged": ["brand/landscape.md"]
+}
+```
+
+Push next action:
+
+```json
+{
+  "skill": "seo-content",
+  "reason": "Fresh keyword plan exists but no launch article has been drafted.",
+  "priority": 80
+}
+```
+
+Navigate to Publish:
+
+```json
+{"tab":"publish","filter":{"adapter":"mktg-native"}}
+```
+
+Navigate to Trend radar:
+
+```json
+{"tab":"signals","filter":{"mode":"radar"}}
+```
+
+## What To Mirror
+
+- Skill runs that produce user-visible artifacts.
+- Brand file writes and refreshes.
+- Native, Postiz, Typefully, Resend, or file publish actions.
+- Recommended next actions that should appear on Pulse.
+- One navigation event when the user's attention should move.
+
+## What Not To Mirror
+
+- Read-only setup checks such as `mktg status`, `mktg doctor`, `mktg list`, or `mktg schema`.
+- Dry-runs, unless the user explicitly asked to inspect a preview.
+- Internal scratch work, prompt planning, or failed probes that do not change user-visible state.
+- Repeated navigations during one turn.
+
+## Order Of Operations
+
+1. `POST /api/activity/log` for the start or completion event.
+2. `POST /api/brand/note` or `POST /api/brand/write` if brand memory changed.
+3. `POST /api/opportunities/push` if a next action exists.
+4. `POST /api/navigate` if the user should look somewhere specific.
+5. `POST /api/toast` for the short confirmation.
+
+Keep calls fire-and-forget. If Studio returns non-2xx, continue the real work
+and do not block the user on dashboard reflection.

package/skills/cmo/rules/studio-integration.md

@@ -0,0 +1,147 @@
+# CMO ↔ Studio Integration
+
+The mktg-studio dashboard (Bun API + Next.js UI, default ports 3001 + 3000, or the ports printed by `mktg studio`) is a local visual layer that /cmo *drives* from Claude Code. The studio never initiates skill runs; it reflects state. Every user-visible action the studio shows — an activity row, a tab switch, a toast, a refreshed brand file — is /cmo POSTing to the studio's HTTP surface.
+
+## When the studio is running
+
+Detect with a single HEAD request:
+
+```bash
+STUDIO=${STUDIO_BASE:-http://localhost:3001}
+curl -s -o /dev/null -w "%{http_code}" "$STUDIO/api/health"
+# 200 → studio is live. Anything else → studio is offline or starting.
+```
+
+If 200, /cmo is in **studio-attached mode** and MUST mirror key side effects to the studio via HTTP. If not 200, /cmo is in **standalone mode** — work exactly as before, no HTTP calls.
+
+There is no retry loop. Studio absence is not an error; it's a state.
+
+## When the user wants Studio open
+
+Launch Studio explicitly through `mktg`; do not rely on hidden hooks or
+browser automation:
+
+```bash
+mktg studio --dry-run --json --intent cmo --session <id>
+mktg studio --open --intent cmo --session <id>
+```
+
+The dry-run is side-effect free and returns `urls.dashboard`, usually:
+
+```text
+http://localhost:3000/dashboard?mode=cmo&session=<id>
+```
+
+The launcher prefers the sibling `mktg-studio/bin/mktg-studio.ts` checkout,
+then `MKTG_STUDIO_BIN`, then `mktg-studio` on PATH. Once health returns 200,
+switch to studio-attached mode and use the verbs below.
+
+## The studio verbs
+
+Most are mutating POSTs /cmo sends outbound; schema-fetch is a read-only GET /cmo calls before the first POST of a session to resolve payload schemas at runtime. Never hardcode shapes — the studio's schema is the source of truth.
+
+| Verb | Endpoint | Purpose | When /cmo uses it |
+|---|---|---|---|
+| schema-fetch | `GET /api/schema` | Resolve every endpoint's request + response shape at runtime | Once per session, before the first mutating POST. Cache the result for the rest of the session. |
+| activity | `POST /api/activity/log` | Append a row to the live Activity panel | After any skill run, any brand file write, any publish, any non-trivial CLI invocation |
+| brand-note | `POST /api/brand/note` | Tell Studio that /cmo wrote a brand file externally | After direct edits to `brand/*.md` |
+| brand-write | `POST /api/brand/write` | Atomic Studio-mediated brand write with optimistic locking | When /cmo wants Studio to own the write + refresh event |
+| push-action | `POST /api/opportunities/push` | Add a recommended next action that Pulse can surface | When analysis produces a concrete next move |
+| navigate | `POST /api/navigate` | Switch the active tab + apply filters | When routing a user from one concern to another (e.g., drafted a post → switch to Publish tab) |
+| toast | `POST /api/toast` | Fire a one-off sonner toast | For transient user-facing notifications — "brand voice refreshed", "postiz draft created", etc. |
+| brand-refresh | `POST /api/brand/refresh` | Invalidate brand-backed SWR caches | Immediately after `brand/*.md` is written or appended |
+
+Every body is JSON. `/api/schema` is agent-native by design — same contract as `mktg schema --json` — so a teammate agent extending /cmo can self-discover the studio surface with one curl.
+
+## What to mirror vs what to hide
+
+**Mirror (post to studio):**
+- Skill runs that write brand files → `activity` + `brand/refresh`
+- Publish actions (Typefully / postiz / Resend drafts) → `activity` + `navigate` to Publish tab + `toast`
+- Native publish actions (`mktg-native`) → `activity` + `navigate` to Publish tab + `toast`
+- Signal collection, competitive scans, landscape refreshes → `activity` + `navigate` to Signals or Signals/Trend radar
+- Opportunity recommendations → `activity` + `opportunities/push` so Pulse can surface the next action
+
+**Hide (do not post):**
+- Read-only CLI invocations (`mktg status`, `mktg list`, `mktg plan next`) — these are /cmo's own context gathering, not user-visible events
+- Dry-run previews (`--dry-run` anywhere) — never mirror a preview as if it were an action
+- Failed integration checks that /cmo is about to guide the user through — surface as a toast only after the user opts in to setup
+- Internal learnings appended to `brand/learnings.md` from the `--learning` flag — the brand refresh event will show the file changed, which is enough
+
+## Activity row shape
+
+```jsonc
+{
+  "kind": "skill-run" | "brand-write" | "publish" | "navigate" | "toast",
+  "skill": "seo-content",               // optional, when kind === "skill-run"
+  "summary": "Drafted 3 SEO articles for 'anti-course course' positioning",
+  "filesChanged": ["brand/assets.md"],  // optional
+  "meta": {
+    "result": "success" | "partial" | "failed"
+  }
+}
+```
+
+/cmo NEVER sends the full skill output. The activity log is a log, not a storage layer. Full artifacts live in brand files and the SQLite `skill_runs` table (written by the mktg CLI, not by /cmo directly).
+
+## Navigate payload — use sparingly
+
+```jsonc
+{
+  "tab": "publish" | "signals" | "brand" | "pulse",
+  "filter": { "adapter": "mktg-native" }   // optional, tab-specific
+}
+```
+
+Only navigate when the user's next logical move is on a specific tab. Trend radar lives inside Signals, so use `{"tab":"signals","filter":{"mode":"radar"}}`. Legacy tabs are remapped by Studio (`trends` → Signals/Trend radar, `audience` and `opportunities` → Pulse), but new callers should send only `pulse`, `signals`, `publish`, or `brand`. Do not navigate on every skill run — that thrashes the UI. A good rule: navigate at most once per user turn, at the moment their attention needs to shift.
+
+## Toast — transient only
+
+Toasts disappear. Use them for ephemeral confirmations, never for information the user might need to reference later. "Posted to LinkedIn", "Brand voice refreshed", "Landscape stale — refreshing now" — yes. A 200-word strategic recommendation — no, that goes in the chat (Claude Code terminal) where it persists.
+
+## Order of operations
+
+When a skill run produces a brand file write AND a publish AND a tab switch, the order matters:
+
+1. `POST /api/activity/log` first — records the event, appears in the Activity panel immediately
+2. `POST /api/brand/note`, `POST /api/brand/write`, or `POST /api/brand/refresh` second (if brand file changed) — invalidates SWR so the tab shows fresh data
+3. `POST /api/opportunities/push` third (if a next action should appear on Pulse)
+4. `POST /api/navigate` fourth (if tab should switch) — user arrives on a tab that already has the latest data
+5. `POST /api/toast` last — confirmation on top of the already-correct view
+
+Posting navigate before refresh risks showing the user stale data on the destination tab.
+
+## Failure handling
+
+Every /cmo → studio POST is fire-and-forget. If the studio returns non-2xx, /cmo:
+
+1. Logs a single-line note to stderr — "studio POST failed: {endpoint} {code}"
+2. Continues the skill run to completion
+3. Does NOT retry, does NOT queue, does NOT surface the failure to the user
+
+The studio is a dashboard, not a durable sink. If a row is lost, the skill's actual output (brand files, publish_log SQLite row) is the source of truth and will re-surface on the next dashboard reload.
+
+## Schema introspection (the schema-fetch verb in detail)
+
+First action on a studio-attached session, before any mutating POST:
+
+```bash
+STUDIO=${STUDIO_BASE:-http://localhost:3001}
+curl -s "$STUDIO/api/schema" > /tmp/studio-schema.json
+jq '.routes[] | select(.path == "/api/activity/log")' /tmp/studio-schema.json
+```
+
+The response shape mirrors `mktg schema --json`: every endpoint lists its request body shape, response body shape, enum values, and required-vs-optional fields. /cmo uses this to:
+
+1. Validate its own outbound payloads before POSTing (reject bad payloads locally, don't spam the studio with 400s).
+2. Discover new endpoints added in newer studio versions without a CLI update.
+3. Surface version drift: if /cmo's expected shape and the studio's declared shape diverge, log once to stderr and fall back to the minimal common subset.
+
+Cache for the session — the studio's schema is stable within a single run. Refresh on studio restart or when /cmo itself restarts.
+
+## Never
+
+- Never import `@postiz/*` — AGPL firewall, enforced by test.
+- Never initiate a Claude Code session from the studio. /cmo is always invoked from the user's terminal.
+- Do not delegate intelligence to `POST /api/skill/run` unless explicitly operating Studio's local skill-runner surface. /cmo remains the orchestrator; the studio reflects.
+- Never store API keys in the studio. The mktg CLI reads its own env vars; the studio's settings panel writes to `.env.local` which the next `mktg` invocation picks up.