architecture.md
1 # Architecture 2 3 mureo is a **marketing orchestration framework** that bridges the gap between marketing strategy and advertising platform execution. Rather than a simple API wrapper, mureo provides a layered system where human-defined goals flow through strategy context, get orchestrated by AI-powered workflows, and execute via pluggable platform connections. 4 5 ## System Architecture 6 7 The system is organized into four layers. Each layer has a clear responsibility and communicates downward through well-defined interfaces. 8 9 ``` 10 ┌─────────────────────────────────────────────────────┐ 11 │ Marketing Goals │ 12 │ (awareness, lead generation, sales, retention) │ 13 ├─────────────────────────────────────────────────────┤ 14 │ Strategy Context │ 15 │ STRATEGY.md: Persona, USP, Brand Voice, Goals, │ 16 │ Operation Mode, Market Context │ 17 │ STATE.json: Campaign snapshots, action log │ 18 ├─────────────────────────────────────────────────────┤ 19 │ Orchestration Layer │ 20 │ Workflow Commands: /daily-check, /rescue, etc. │ 21 │ Domain Knowledge: Skills (analysis, diagnostics) │ 22 │ AI Agent (LLM): Strategic judgment, creative gen │ 23 ├─────────────────────────────────────────────────────┤ 24 │ Tool Connection Layer │ 25 │ ┌──────────┐ ┌──────────┐ ┌────────┐ ┌─────┐ │ 26 │ │Google Ads│ │Meta Ads │ │Search │ │ GA4 │ │ 27 │ │(mureo) │ │(mureo) │ │Console │ │(MCP)│ │ 28 │ │ │ │ │ │(mureo) │ │ │ │ 29 │ └──────────┘ └──────────┘ └────────┘ └─────┘ │ 30 └─────────────────────────────────────────────────────┘ 31 ``` 32 33 ### Marketing Goals (Top Layer) 34 35 The user defines high-level marketing objectives -- awareness, lead generation, sales, retention. These goals drive every decision downstream. mureo does not prescribe goals; it receives them from the marketer and ensures all operations align with them. 36 37 ### Strategy Context 38 39 mureo persists marketing strategy in two files that travel with the project: 40 41 - **STRATEGY.md** captures the durable strategic context: target persona, unique selling proposition (USP), brand voice guidelines, marketing goals, the current operation mode (e.g., EFFICIENCY_STABILIZE, GROWTH_SCALE), and market context including competitors. 42 - **STATE.json** holds ephemeral operational state: campaign snapshots, recent action logs, and metric baselines used for anomaly detection. 43 44 Together these files give the AI agent enough context to make strategy-aware decisions without requiring a database. 45 46 ### Orchestration Layer 47 48 This is where mureo's workflow commands, domain knowledge (skills), and the AI agent converge. Workflow commands like `/daily-check` and `/rescue` define multi-step operational procedures. Skills provide domain-specific reference material (operation mode definitions, diagnostic patterns). The AI agent (LLM) supplies strategic judgment, creative generation, and adaptive decision-making. The orchestration layer reads the strategy context, selects the appropriate tools, and synthesizes results into actionable recommendations. 49 50 #### PDCA Operational Loop 51 52 The workflow commands form a continuous Plan-Do-Check-Act cycle: `/onboard` defines strategy and goals (Plan); `/daily-check` and its downstream commands execute operations (Do); `/goal-review` and `/weekly-report` evaluate progress (Check); and `/goal-review` recommendations feed back into the Do phase by adjusting the Operation Mode, which changes how every command behaves (Act). This loop runs daily (Do) and weekly (Check), with the Act phase closing the loop by updating STRATEGY.md when conditions change. See `skills/mureo-workflows/SKILL.md` for the full PDCA diagram and Operation Mode transition rules. 53 54 ### Tool Connection Layer 55 56 The bottom layer provides concrete connections to advertising platforms and analytics services. mureo ships its own MCP tools for Google Ads, Meta Ads, and Google Search Console. Third-party MCP servers (e.g., GA4) can be composed alongside mureo's tools. This layer is intentionally replaceable -- as platforms release official MCP servers, mureo's built-in connectors can be swapped out without affecting the orchestration layer above. 57 58 ## Package Structure 59 60 ``` 61 mureo/ 62 ├── __init__.py # Package root (version) 63 ├── auth.py # Credential loading & client factory (+ Meta token auto-refresh) 64 ├── auth_setup.py # Interactive setup wizard (OAuth + MCP config + credential guard) 65 ├── throttle.py # Rate limiting (token bucket + rolling hourly cap) 66 ├── google_ads/ # Google Ads API client 67 │ ├── client.py # GoogleAdsApiClient (Mixins) 68 │ ├── mappers.py # Response mapping to structured dicts 69 │ ├── _ads.py # _AdsMixin (create/update/list RSAs) 70 │ ├── _ads_display.py # _DisplayAdsMixin (create RDAs + RDAUploadError) 71 │ ├── _keywords.py # _KeywordsMixin (add/remove/suggest) 72 │ ├── _extensions.py # _ExtensionsMixin (sitelinks, callouts, conversions, targeting) 73 │ ├── _monitoring.py # _MonitoringMixin (anomaly detection, reports) 74 │ ├── _diagnostics.py # _DiagnosticsMixin (campaign diagnosis) 75 │ ├── _analysis.py # _AnalysisMixin (auction insights, CPC trends, device analysis) 76 │ ├── _creative.py # _CreativeMixin (LP analysis, RSA insights) 77 │ ├── _media.py # _MediaMixin (image asset upload) 78 │ ├── _rsa_validator.py # RSA ad text validator 79 │ ├── _rda_validator.py # RDA input validator (display ads) 80 │ └── _gaql_validator.py # GAQL input validators (IDs, dates, date ranges, IN clauses) 81 ├── meta_ads/ # Meta Ads API client 82 │ ├── client.py # MetaAdsApiClient (15 Mixins) 83 │ ├── mappers.py # Response mapping 84 │ ├── _campaigns.py # CampaignsMixin 85 │ ├── _ad_sets.py # AdSetsMixin 86 │ ├── _ads.py # AdsMixin 87 │ ├── _creatives.py # CreativesMixin (carousel, collection, image upload) 88 │ ├── _audiences.py # AudiencesMixin 89 │ ├── _pixels.py # PixelsMixin 90 │ ├── _insights.py # InsightsMixin 91 │ ├── _analysis.py # AnalysisMixin 92 │ ├── _conversions.py # ConversionsMixin (Conversions API / CAPI) 93 │ ├── _leads.py # LeadsMixin (lead forms, lead data) 94 │ ├── _catalog.py # CatalogMixin (product catalogs, feeds, products) 95 │ ├── _split_test.py # SplitTestMixin (A/B tests) 96 │ ├── _ad_rules.py # AdRulesMixin (automated rules) 97 │ ├── _page_posts.py # PagePostsMixin (page posts, boost) 98 │ ├── _instagram.py # InstagramMixin (accounts, media, boost) 99 │ └── _hash_utils.py # SHA-256 hashing utilities for CAPI user data 100 ├── search_console/ # Google Search Console API client (reuses Google OAuth2 credentials) 101 │ └── client.py # SearchConsoleApiClient 102 ├── analysis/ # Cross-platform analysis utilities 103 │ ├── lp_analyzer.py # Landing page analysis 104 │ └── anomaly_detector.py # CPA spike / CTR drop / zero-spend detection with sample-size gates 105 ├── rollback/ # Rollback feature (allow-list gated, append-only) 106 │ ├── models.py # RollbackStatus enum + RollbackPlan dataclass 107 │ ├── planner.py # plan_rollback(ActionLogEntry) -> RollbackPlan | None 108 │ └── executor.py # execute_rollback(...) -> appends ActionLogEntry(rollback_of=index) 109 ├── context/ # File-based context (STRATEGY.md, STATE.json) 110 │ ├── models.py # Immutable dataclasses (ActionLogEntry.rollback_of for audit trail) 111 │ ├── strategy.py # STRATEGY.md parser / renderer 112 │ ├── state.py # STATE.json parser / renderer 113 │ └── errors.py # Context-specific exceptions 114 ├── cli/ # Typer CLI (setup + auth + rollback inspection; ad operations are via MCP) 115 │ ├── main.py # Entry point (mureo command) 116 │ ├── setup_cmd.py # mureo setup claude-code / cursor / codex / gemini (Typer handlers) 117 │ ├── setup_codex.py # Codex install-kit (MCP config, credential guard, workflow-command skills, shared skills) 118 │ ├── setup_gemini.py # Gemini extension manifest (~/.gemini/extensions/mureo/gemini-extension.json) 119 │ ├── auth_cmd.py # mureo auth setup (+ --web) / status / check-* 120 │ ├── rollback_cmd.py # mureo rollback list / show (inspection only; apply routes through MCP) 121 │ ├── _tty.py # TTY-safe helpers (confirm_or_default, is_tty) for non-interactive setup 122 │ └── web_auth.py # mureo auth setup --web — browser-based OAuth wizard (Google + Meta) 123 └── mcp/ # MCP server 124 ├── __main__.py # python -m mureo.mcp entry point 125 ├── server.py # MCP server setup (stdio transport) 126 ├── _helpers.py # Shared handler utilities 127 ├── tools_google_ads.py # Google Ads tool definitions (aggregator) 128 ├── _tools_google_ads_*.py # Tool definition sub-modules 129 ├── _handlers_google_ads.py # Google Ads base handlers 130 ├── _handlers_google_ads_extensions.py # Extensions handlers 131 ├── _handlers_google_ads_analysis.py # Analysis handlers 132 ├── tools_meta_ads.py # Meta Ads tool definitions (aggregator) 133 ├── _tools_meta_ads_*.py # Tool definition sub-modules 134 ├── _handlers_meta_ads.py # Meta Ads base handlers 135 ├── _handlers_meta_ads_extended.py # Extended handlers 136 ├── _handlers_meta_ads_other.py # Other handlers 137 ├── tools_search_console.py # Search Console tool definitions 138 ├── _handlers_search_console.py # Search Console handlers 139 ├── tools_rollback.py # rollback.plan.get / rollback.apply 140 ├── _handlers_rollback.py # Rollback handlers (lazy-resolve dispatcher) 141 ├── tools_analysis.py # analysis.anomalies.check 142 └── _handlers_analysis.py # Anomaly detector composition handler 143 144 .claude/commands/ # Workflow slash commands for Claude Code 145 ├── onboard.md # Account setup + STRATEGY.md generation 146 ├── daily-check.md # Mode-aware daily health monitoring 147 ├── rescue.md # Emergency performance rescue 148 ├── search-term-cleanup.md # Strategy-aligned search term hygiene 149 ├── creative-refresh.md # Persona/USP-driven ad copy refresh 150 ├── budget-rebalance.md # Mode-guided budget reallocation 151 ├── competitive-scan.md # Auction analysis with Market Context 152 ├── sync-state.md # Manual STATE.json synchronization 153 └── learn.md # Save diagnostic insights to knowledge base 154 155 skills/mureo-workflows/ # Workflow skill reference 156 │ └── SKILL.md # Orchestration paradigm + Operation Mode reference 157 skills/mureo-learning/ # Evidence-based decision framework 158 │ └── SKILL.md # Statistical thinking for marketing decisions 159 skills/mureo-pro-diagnosis/ # Learnable diagnostic knowledge base 160 │ └── SKILL.md # Diagnostic insights (grows with /learn) 161 ``` 162 163 ## Design Principles 164 165 ### No Database 166 167 mureo has zero database dependencies. All state lives either in the advertising platform APIs or in optional local files (`STRATEGY.md`, `STATE.json`). This makes it trivially deployable -- `pip install mureo` is all you need. 168 169 ### No Embedded LLM 170 171 mureo does not bundle or call an LLM itself. The tool connection layer wraps advertising APIs and returns structured JSON dictionaries. The orchestration layer relies on an external AI agent (e.g., Claude via Claude Code) for reasoning, planning, and creative generation. This separation keeps mureo lightweight and model-agnostic. 172 173 ### Immutable Data Models 174 175 All dataclasses use `frozen=True` to prevent accidental mutation. Mutable fields like `dict` and `list` are defensively copied in `__post_init__`. 176 177 ```python 178 @dataclass(frozen=True) 179 class CampaignSnapshot: 180 campaign_id: str 181 campaign_name: str 182 status: str 183 bidding_strategy_type: str | None = None 184 # ... 185 ``` 186 187 ### Structured JSON Output 188 189 Every tool and CLI command returns plain Python dicts (serializable to JSON). No custom objects, no ORM models -- just data that any agent or script can consume. 190 191 ### Credentials Stay Local 192 193 Credentials are loaded from `~/.mureo/credentials.json` or environment variables. They are never sent anywhere except the official advertising platform APIs. 194 195 ### Defense-in-Depth for AI Agents 196 197 mureo assumes the caller is an AI agent susceptible to prompt injection, not a trusted human. Three layered controls address that threat model: 198 199 1. **Credential guard** — `mureo setup claude-code` writes a PreToolUse hook to `~/.claude/settings.json` that blocks reads of `~/.mureo/credentials.json`, `.env`, and similar secret files, so a prompt-injection payload cannot exfiltrate tokens via the file-system tools. 200 2. **GAQL input validation** — every ID, date, date-range constant, and string literal entering a Google Ads query flows through a single whitelist-based surface in `mureo/google_ads/_gaql_validator.py`. `_period_to_date_clause`'s `BETWEEN` branch pattern-matches and revalidates its dates instead of passing the raw caller string into GAQL. 201 3. **Anomaly detection** — `mureo/analysis/anomaly_detector.py` compares current campaign metrics against a median-based baseline built from historical `action_log` entries and emits prioritized alerts for zero spend (CRITICAL), CPA spikes (≥1.5×, critical at 2×), and CTR drops (≤0.5×, critical at 0.3×). Sample-size gates (30+ conversions, 1000+ impressions) follow the `mureo-learning` skill's statistical-thinking rules to suppress single-day noise. Baselines tolerate malformed `metrics_at_action` rows; CPA/CTR are medianed per-entry so baseline values reflect a real historical day. 202 4. **Rollback with allow-list gating** — `mureo/rollback/` turns agent-authored `reversible_params` hints into concrete `RollbackPlan` records. `reversible_params` is untrusted input for the rollback executor, so the planner enforces an explicit allow-list of operations (budget update + status toggles across Google/Meta Ads), refuses destructive verbs (`.delete` / `.remove` / `.destroy` / `.purge` / `.transfer`), and rejects unexpected parameter keys — a compromised agent cannot smuggle a privileged call through the rollback path. The `mureo rollback list` / `show` CLI commands are inspection-only; execution stays with the MCP dispatcher so it re-enters the same policy gate as forward actions, and control characters from STATE.json are stripped before terminal output to prevent ANSI-escape spoofing. 203 204 See [SECURITY.md](../SECURITY.md) for the full threat model. 205 206 ## Mixin Architecture 207 208 Both API clients use multiple inheritance with Mixins to organize functionality by domain. This keeps each file focused on a single concern while providing a unified client interface. 209 210 ### Google Ads Client -- Mixins 211 212 ```python 213 class GoogleAdsApiClient( 214 _AdsMixin, # RSA CRUD (create/update/list/status) 215 _DisplayAdsMixin, # RDA creation with auto image upload 216 _KeywordsMixin, # Keyword add/remove/suggest/diagnose 217 _MonitoringMixin, # Anomaly detection, reports, goals 218 _ExtensionsMixin, # Sitelinks, callouts, conversions, targeting 219 _DiagnosticsMixin, # Campaign delivery diagnosis 220 _AnalysisMixin, # Auction insights, CPC trends, device analysis, budget efficiency 221 _CreativeMixin, # LP analysis, RSA insights 222 _MediaMixin, # Image asset upload 223 ): 224 ``` 225 226 The base class (`GoogleAdsApiClient`) provides: 227 - Constructor: accepts `Credentials`, `customer_id`, `developer_token`, `login_customer_id` 228 - `_search(query)`: async GAQL query execution via `run_in_executor` 229 - `_get_service(name)`: access to Google Ads service objects 230 - Input validation: `_validate_id()`, `_validate_status()`, `_validate_match_type()`, `_validate_date()` 231 - Error handling: `_wrap_mutate_error()` decorator that catches `GoogleAdsException` and returns user-friendly messages 232 233 ### Meta Ads Client -- 15 Mixins 234 235 ```python 236 class MetaAdsApiClient( 237 CampaignsMixin, # Campaign CRUD 238 AdSetsMixin, # Ad set CRUD 239 AdsMixin, # Ad CRUD 240 CreativesMixin, # Creative management, image/carousel/collection 241 AudiencesMixin, # Custom/lookalike audiences 242 PixelsMixin, # Pixel stats and events 243 InsightsMixin, # Performance reports, breakdowns 244 AnalysisMixin, # Performance analysis, cost investigation 245 CatalogMixin, # Product catalogs, feeds, products (DPA) 246 ConversionsMixin, # Conversions API (CAPI) event sending 247 LeadsMixin, # Lead forms, lead data retrieval 248 PagePostsMixin, # Page post listing and boosting 249 InstagramMixin, # Instagram accounts, media, boosting 250 SplitTestMixin, # A/B test creation and management 251 AdRulesMixin, # Automated rules (alerts, auto-pause, etc.) 252 ): 253 ``` 254 255 The base class provides: 256 - Constructor: accepts `access_token`, `ad_account_id` (must start with `act_`) 257 - HTTP methods: `_get()`, `_post()`, `_delete()` with rate limit monitoring 258 - Automatic retry with exponential backoff (3 attempts) 259 - Rate limit header parsing (`x-business-use-case-usage`) 260 - Async context manager support (`async with`) 261 262 ## MCP Server Tool Dispatch Flow 263 264 The MCP server uses stdio transport and dispatches tool calls to platform-specific handlers. 265 266 ``` 267 Agent (Claude Code / Cursor / etc.) 268 │ 269 │ stdio (JSON-RPC) 270 ▼ 271 server.py :: _create_server() 272 │ 273 ├── list_tools() → returns _ALL_TOOLS (GOOGLE_ADS_TOOLS + META_ADS_TOOLS + SEARCH_CONSOLE_TOOLS) 274 │ 275 └── call_tool(name, arguments) 276 │ 277 ├── name in _GOOGLE_ADS_NAMES? → handle_google_ads_tool(name, args) 278 │ │ 279 │ └── _HANDLERS[name](args) 280 │ │ 281 │ ├── load_google_ads_credentials() 282 │ ├── create_google_ads_client(creds, customer_id) 283 │ └── client.method() → list[TextContent] 284 │ 285 ├── name in _META_ADS_NAMES? → handle_meta_ads_tool(name, args) 286 │ │ 287 │ └── _HANDLERS[name](args) 288 │ │ 289 │ ├── load_meta_ads_credentials() 290 │ ├── create_meta_ads_client(creds, account_id) 291 │ └── client.method() → list[TextContent] 292 │ 293 ├── name in _SEARCH_CONSOLE_NAMES? → handle_search_console_tool(name, args) 294 │ │ 295 │ └── _HANDLERS[name](args) 296 │ │ 297 │ ├── load_google_ads_credentials() (reuses Google OAuth2) 298 │ ├── create_search_console_client(creds) 299 │ └── client.method() → list[TextContent] 300 │ 301 └── else → ValueError("Unknown tool") 302 ``` 303 304 Key implementation details: 305 306 1. **Tool definitions** are `mcp.types.Tool` objects with `inputSchema` (JSON Schema). 307 2. **Handler dispatch** uses a `dict[str, Callable]` mapping tool names to async handler functions. 308 3. **Error handling**: the `@api_error_handler` decorator catches exceptions and converts them to `TextContent` error messages, so the agent always gets a text response. 309 4. **Credential loading** happens per-request. Each handler call loads credentials from file/env, creates a fresh client, and executes the operation. 310 311 ## Rate Limiting 312 313 mureo includes a built-in rate limiter (`mureo/throttle.py`) to prevent API bans caused by high-speed requests from AI agents. 314 315 ### Algorithm 316 317 Each platform throttler combines two mechanisms: 318 319 1. **Token bucket** -- controls instantaneous QPS (queries per second) with configurable burst allowance. 320 2. **Rolling hourly cap** -- enforces a hard ceiling on total requests per hour. 321 322 ### Default Limits 323 324 | Platform | QPS | Burst | Hourly Limit | Notes | 325 |----------|-----|-------|-------------|-------| 326 | Google Ads | 10 | 5 | *(none)* | Conservative defaults; Google uses dynamic server-side limits | 327 | Meta Ads | 20 | 10 | 50,000 | Tuned to stay within the Business Use Case (BUC) quota | 328 | Search Console | 5 | 5 | *(none)* | Reuses Google OAuth2 credentials | 329 330 ### Integration 331 332 - **Module-level singletons** -- one `Throttler` instance per platform, shared across all MCP tool calls in the same process. 333 - **Transparent** -- tool handlers call `await throttler.acquire()` before making API requests. No configuration is needed from the user. 334 - **Graceful** -- when the token bucket is empty, `acquire()` awaits until a token becomes available rather than raising an error. 335 336 ## Authentication Flow 337 338 ``` 339 1. Handler receives tool call arguments 340 │ 341 2. load_google_ads_credentials() / load_meta_ads_credentials() 342 │ 343 ├── Try ~/.mureo/credentials.json 344 │ └── Parse JSON → extract platform section 345 │ 346 └── Fallback to environment variables 347 └── GOOGLE_ADS_* / META_ADS_* 348 │ 349 3. If credentials found: 350 │ 351 ├── Google Ads: build OAuth2 Credentials → GoogleAdsClient → GoogleAdsApiClient 352 └── Meta Ads: MetaAdsApiClient(access_token, ad_account_id) 353 │ 354 4. If no credentials: return error TextContent (no exception) 355 ``` 356 357 The credential resolution logic is centralized in `mureo/auth.py`. Both the CLI and MCP server use the same `load_*_credentials()` and `create_*_client()` functions. 358 359 ### Meta Ads Token Auto-Refresh 360 361 When loading Meta Ads credentials, `mureo/auth.py` checks the `token_obtained_at` timestamp in `credentials.json`. If the Long-Lived Token is 53+ days old (7-day safety margin before the 60-day expiry), mureo automatically exchanges it for a fresh token via the Meta Graph API. This requires `app_id` and `app_secret` to be present in the credentials. The refresh is protected by an `asyncio.Lock` to prevent concurrent refresh races, and the updated token is written atomically to `credentials.json` with `0600` file permissions. If the refresh fails (network error, invalid app credentials, etc.), mureo falls back to the existing token and logs a warning. 362 363 ## Command-Based Workflow System 364 365 In addition to the 169 individual MCP tools, mureo provides **workflow commands** as Claude Code slash commands (`.claude/commands/`). These commands are **platform-agnostic orchestration instructions** that guide the AI agent to discover platforms, select tools, and synthesize cross-platform insights — all driven by the strategy context in `STRATEGY.md`. 366 367 ### How It Works 368 369 ``` 370 User runs /daily-check in Claude Code 371 │ 372 ├── Read STRATEGY.md → extract Operation Mode, Persona, Data Sources 373 ├── Read STATE.json → discover configured platforms (platforms dict) 374 │ 375 ├── For each configured platform, select appropriate MCP tools based on Operation Mode 376 │ (no hardcoded platform assumptions — adapts to whatever is configured) 377 │ 378 ├── Check availability of enrichment data sources: 379 │ ├── Search Console (built-in) → organic search pulse 380 │ └── GA4 (external MCP) → on-site behavior correlation 381 │ 382 ├── Execute selected tools across all discovered platforms 383 │ 384 └── Synthesize results into a unified, strategy-aware cross-platform report 385 ``` 386 387 ### Commands 388 389 All commands follow the same orchestration pattern: **discover platforms → select tools → correlate data sources → present unified results**. Commands do not hardcode tool names; the AI agent chooses appropriate tools per platform at runtime. 390 391 | Command | Purpose | Strategy Sections Used | 392 |---------|---------|-----------------------| 393 | `/onboard` | Platform discovery + strategy generation | *(generates all sections)* | 394 | `/daily-check` | Cross-platform health monitoring | Operation Mode, Data Sources | 395 | `/rescue` | Emergency performance fix with site-side diagnosis | All sections | 396 | `/search-term-cleanup` | Keyword hygiene with paid/organic overlap | Persona, USP, Data Sources | 397 | `/creative-refresh` | Multi-platform creative refresh | Persona, USP, Brand Voice, Data Sources | 398 | `/budget-rebalance` | Cross-platform budget optimization | Operation Mode, Goals, Data Sources | 399 | `/competitive-scan` | Paid + organic competitive analysis | Market Context, Data Sources | 400 | `/goal-review` | Multi-source goal evaluation | Operation Mode, Goals, Data Sources | 401 | `/weekly-report` | Cross-platform weekly report | All sections | 402 | `/sync-state` | Multi-platform state synchronization | *(writes STATE.json)* | 403 | `/learn` | Save diagnostic insights to knowledge base | *(writes SKILL.md)* | 404 405 The workflow skill reference (`skills/mureo-workflows/SKILL.md`) documents the full set of Operation Modes and their behavioral implications for each command, as well as cross-platform data correlation patterns.