mureo: Instructions file for Codex

AGENTS.md

Guidelines for AI agents contributing to the mureo codebase.

Project Overview

mureo — your local-first AI ad ops crew. Find waste, audit changes, run ad accounts safely.

Works with Claude Code, Cursor, Codex & Gemini. mureo sits on top of the official ad-platform MCPs and gives your AI a strategy to follow, an outcome to be measured against, and an audit trail you can show to anyone — credentials never leave your machine.

mureo combines strategy context, workflow commands, and domain knowledge to help AI agents achieve marketing goals across platforms. Provides MCP tools for direct platform operations and workflow commands for strategy-driven ad operations via Claude Code slash commands. Designed for AI agents — no database, no LLM SDK, no web framework.

Build & Test

pip install -e ".[dev]"
pytest tests/ -v
pytest tests/ --cov=mureo --cov-report=term-missing

# Browser assets (only when mureo/_data/web/ changes). Node's built-in
# runner — no package.json, no dependencies, no build step.
node --test tests/js/*.test.js

Architecture

mureo/
├── google_ads/          # Google Ads API client (Mixin composition)
│   ├── client.py        # GoogleAdsApiClient (main entry)
│   ├── mappers.py       # Response mapping to structured dicts
│   ├── _enum_names.py   # map_enum_name + SDK-derived int->name maps (raw protobuf has no .name, #588)
│   ├── _placement_mappers.py # Negative-placement + group_placement_view row mappers (#544/#547)
│   ├── _ads.py          # AdsMixin (RSA create/update/status/list)
│   ├── _ads_display.py  # DisplayAdsMixin (RDA create + RDAUploadError)
│   ├── _asset_groups.py # AssetGroupsMixin (Performance Max asset groups: one read for
│   │                    #   text + images, and the text swap via one atomic
│   │                    #   GoogleAdsService.mutate, #590/#626). Owns both field-type
│   │                    #   tables — text width limits and image dimension rules
│   ├── _asset_groups_images.py # AssetGroupImagesMixin (the P-MAX image swap, #626:
│   │                    #   existing asset id or local upload, one atomic mutate)
│   ├── _keywords.py     # KeywordsMixin (add/remove/suggest/diagnose)
│   ├── _placements.py   # PlacementsMixin (negative placements: sites/apps/app categories, #544)
│   ├── _analysis.py     # AnalysisMixin aggregator, composing the split modules below
│   ├── _analysis_auction.py / _analysis_btob.py / _analysis_budget.py    # + _analysis_constants.py
│   ├── _analysis_keywords.py / _analysis_performance.py / _analysis_rsa.py / _analysis_search_terms.py
│   ├── _diagnostics.py  # DiagnosticsMixin (campaign diagnosis)
│   ├── _extensions.py   # ExtensionsMixin aggregator, composing the split modules below
│   ├── _extensions_callouts.py / _extensions_conversions.py / _extensions_sitelinks.py / _extensions_targeting.py
│   ├── _monitoring.py   # MonitoringMixin (anomaly detection/reporting)
│   ├── _creative.py     # CreativeMixin (LP analysis/message match)
│   ├── _media.py        # MediaMixin (image asset upload)
│   ├── _rsa_validator.py     # RSA ad text validator
│   ├── _rda_validator.py     # RDA input validator (display ads)
│   ├── _message_match.py     # LP screenshot capture (Playwright, SSRF-guarded)
│   ├── _gaql_validator.py    # GAQL input validators (ASCII-only ID/date whitelists — see below)
│   ├── _date_ranges.py       # Period-over-period comparison windows (SDK-free, #809)
│   └── accounts.py           # Accessible-customer / account listing
├── meta_ads/            # Meta Ads API client (Mixin composition)
│   ├── client.py        # MetaAdsApiClient (main entry)
│   ├── mappers.py       # Response mapping
│   ├── _campaigns.py    # CampaignsMixin
│   ├── _ad_sets.py      # AdSetsMixin
│   ├── _ads.py          # AdsMixin
│   ├── _creatives.py    # CreativesMixin (image/carousel/collection/dynamic)
│   ├── _videos.py       # VideosMixin (AdVideo upload/status/thumbnails)
│   ├── _audiences.py    # AudiencesMixin
│   ├── _pixels.py       # PixelsMixin
│   ├── _placement_exclusions.py  # PlacementExclusionsMixin (ad-set publisher exclusions, #544)
│   ├── _insights.py     # InsightsMixin
│   ├── _analysis.py     # AnalysisMixin
│   ├── _catalog.py      # CatalogMixin (product catalogs/feeds)
│   ├── _conversions.py  # ConversionsMixin (Conversions API / CAPI)
│   ├── _hash_utils.py   # SHA-256 PII hashing for CAPI
│   ├── _leads.py        # LeadsMixin (lead forms/leads)
│   ├── _page_posts.py   # PagePostsMixin (page posts/boost, page photos for an Instant Form cover)
│   ├── _instagram.py    # InstagramMixin (accounts/media/boost)
│   ├── _split_test.py   # SplitTestMixin (A/B split tests)
│   ├── _ad_rules.py     # AdRulesMixin (automated rules)
│   ├── _conversion_count.py  # Conversion-count parsing helper
│   ├── _period.py       # Date-period resolution helper
│   └── accounts.py      # Ad-account listing
├── search_console/      # Google Search Console API client (reuses Google OAuth2 credentials)
│   └── client.py        # SearchConsoleApiClient
├── mcp/                 # MCP server (Google/Meta/Search Console + Rollback/Analysis + Analytics registry, Creative Studio, Learning, mureo Context)
│   ├── server.py                          # MCP Server entry point (stdio-based)
│   ├── _helpers.py                        # Shared handler utilities
│   ├── journal.py                         # Append-only JOURNAL.jsonl of every tool call + outcome (#758)
│   ├── journal_chain.py                   # The append itself (#758 phase 6): rotation, the `prev`/`h`
│   │                                      #   hash chain across files, and verify_chain. A truncated
│   │                                      #   TAIL is the one thing it cannot prove — say so, always
│   ├── _journal_hook.py                   # Dispatcher hook: family/mutating classification, one record per call (#758)
│   ├── tools_google_ads.py                # Google Ads tool definitions (aggregator)
│   ├── _tools_google_ads_*.py             # Tool definition sub-modules
│   ├── _handlers_google_ads.py            # Google Ads base handlers
│   ├── _google_ads_client.py              # Google Ads client / credential resolution
│   ├── _handlers_google_ads_extensions.py # Extensions handlers
│   ├── _handlers_google_ads_analysis.py   # Analysis handlers
│   ├── tools_meta_ads.py                  # Meta Ads tool definitions (aggregator)
│   ├── _tools_meta_ads_*.py               # Tool definition sub-modules
│   ├── _handlers_meta_ads.py              # Meta Ads base handlers
│   ├── _meta_ads_client.py                # Meta Ads client / credential resolution
│   ├── _handlers_meta_ads_extended.py     # Extended handlers
│   ├── _handlers_meta_ads_other.py        # Other handlers
│   ├── _handlers_meta_ads_creatives.py    # Upload / creative handlers
│   ├── tools_search_console.py            # Search Console tool definitions
│   ├── _handlers_search_console.py        # Search Console handlers
│   ├── tools_rollback.py                  # rollback_plan_get / rollback_apply
│   ├── _handlers_rollback.py              # Rollback handlers (lazy-resolve dispatcher)
│   ├── tools_batch.py                     # mureo_batch_begin / _end / _status (#549)
│   ├── _handlers_batch.py                 # Batch lifecycle handlers
│   ├── tools_change_import.py             # mureo_external_changes_import (#545)
│   ├── _handlers_change_import.py         # Change-import handler
│   ├── tools_analysis.py                  # analysis_anomalies_check / analysis_delivery_collapse_* / analysis_exclusion_impact_preview
│   ├── _handlers_analysis.py              # Anomaly detector composition handler
│   ├── _handlers_delivery_collapse.py     # Delivery-collapse check / diagnose handlers (#546)
│   ├── _handlers_exclusion_impact.py      # analysis_exclusion_impact_preview handler (#547)
│   ├── exclusion_preflight.py             # Pre-dispatch exclusion sizing + refusal + notice (#547)
│   ├── exclusion_sources.py               # Built-in per-platform delivery sources for the above (#547)
│   ├── tools_analytics_registry.py        # mureo_analytics_modules_list / mureo_analytics_run (#440)
│   ├── tools_creative_studio.py           # creative_studio_* (visual generation + compose)
│   ├── tools_learning.py                  # mureo_learning_insights_get / mureo_consult_advisor
│   ├── tools_learning_preflight.py        # mureo_learning_reset_preflight (#548)
│   ├── tools_mureo_context.py             # STRATEGY.md / STATE.json + mureo_outcome_evaluate tools
│   ├── _handlers_mureo_context.py         # Context (STRATEGY/STATE) handlers
│   ├── _tools_decisions.py                # mureo_decision_record (#758 phase 3) — a PARTIAL of the
│   │                                      #   mureo_context family, not a family of its own, so
│   │                                      #   server.py and the journal labels are untouched
│   ├── _auto_evaluation_hook.py           # mureo_state_get's automatic observation closure
│   │                                      #   (#758 phase 5): the `auto_evaluate` switch, the
│   │                                      #   policy-gate check that decides whether the write
│   │                                      #   may happen, and the response fragment
│   ├── _tools_settings.py                 # mureo_state_settings_set (#848) — workspace settings,
│   │                                      #   another PARTIAL of the mureo_context family
│   ├── _ops_history_param.py              # `expected` / `decision_id` on mutating tools (#848):
│   │                                      #   schema injection, the requirement check, the binding
│   ├── _ops_history_records.py            # The same requirement on the two recording tools
│   ├── _history_ops.py                    # The `decisions` / `ops_history` history sources
│   ├── _handlers_decisions.py             # Its handler: mints the id + timestamp, appends
│   ├── _tools_history.py                  # mureo_history_query (#758 phase 4b) — another PARTIAL
│   │                                      #   of the mureo_context family; READ-ONLY, so the
│   │                                      #   dispatcher injects no `reason` into its schema
│   ├── _handlers_history.py               # Its handler: the filters, and one bounded section per
│   │                                      #   source (action_log / journal / daily / reports /
│   │                                      #   decisions / ops_history)
│   ├── journal_read.py                    # Reading JOURNAL.jsonl back — the parse, the date, the
│   │                                      #   filter and the tail reader, shared with `mureo journal`.
│   │                                      #   The *_files forms walk the rotated siblings as one record
│   ├── _client_factory.py                 # Per-platform BYOD-vs-live client factory
│   └── tool_provider.py                   # Third-party plugin → MCP tool exposure layer (#89)
├── cli/                 # Typer CLI (setup + auth + configure + BYOD + providers + rollback + repair + journal; ad ops are via MCP)
│   ├── main.py          # CLI entry point (`mureo` command)
│   ├── setup_cmd.py     # `mureo setup claude-code` / `cursor` / `codex` / `gemini`
│   ├── setup_codex.py   # Codex install-kit: MCP, credential guard, operational + foundation skills
│   ├── setup_gemini.py  # Gemini extension manifest at ~/.gemini/extensions/mureo/
│   ├── native_skills.py # Deploy/remove plugin native slash skills via `mureo.native_skills` group (#439)
│   ├── configure_cmd.py # `mureo configure` — open the local web configuration UI
│   ├── byod_cmd.py      # `mureo byod import` / `status` / `remove` / `clear`
│   ├── providers_cmd.py # `mureo providers list` / `install` / `uninstall` (official MCP catalog)
│   ├── service_cmd.py   # `mureo service` — install/restart the auto-start configure daemon (#241)
│   ├── upgrade_cmd.py   # `mureo upgrade` — pipx venv-aware bulk upgrade of mureo + plugins
│   ├── auth_cmd.py      # `mureo auth setup` / `status` / `check-*` / `upgrade-google`
│   ├── rollback_cmd.py  # `mureo rollback list` / `show` (inspection only; apply routes through MCP)
│   ├── journal_cmd.py   # `mureo journal` — read back JOURNAL.jsonl (last/tool/since/failures/mutations/json/all)
│   ├── _journal_verify.py # `mureo journal --verify` — the hash chain over the live file and its
│   │                    #   rotated siblings; exit 0 ok / 1 broken / 2 no journal (#758 phase 6)
│   ├── repair_cmd.py    # `mureo repair platform-key` — drop a platforms entry the DOCUMENT
│   │                    #   shows to be wrong (duplicate of a resolvable key, or empty stub);
│   │                    #   dry run by default, backs up first (#610/#616).
│   │                    #   `--all` sweeps every client, summary first, one prompt (#614).
│   │                    #   `--key <k> --drop-duplicate` records the operator's OWN decision
│   │                    #   about a duplicate whose two keys both resolve (#636); not with --all
│   ├── _repair_preview.py # What that command prints — the half that has to be TRUE: why an
│   │                    #   entry can go, what is NOT changed (scoped to the plan), every
│   │                    #   same-account sibling, and conversion_action_types (#616/#617/#618).
│   │                    #   Also the not_collected note an entry carries (#643) and both
│   │                    #   entries of a duplicate mureo hands back to decide (#645)
│   ├── _repair_clients.py # Which STATE.json files `--all` sweeps — reuses the Reports tab's
│   │                    #   optional list_clients / state_store_for_client seam, never a second one
│   ├── _state_file.py   # The shared `--state-file` option + workspace default (rollback + repair)
│   ├── _tty.py          # TTY-safe helpers for non-interactive setup + terminal_safe() scrubbing
│   └── web_auth.py      # Browser-based OAuth wizard spawned by `mureo configure` (per-platform creds)
├── context/             # File-based strategy context (no DB)
│   ├── strategy.py      # STRATEGY.md parser/writer
│   ├── state.py         # STATE.json parser/writer
│   ├── models.py        # StrategyEntry, StateDocument, CampaignSnapshot, ActionLogEntry (rollback_of, batch_id), BatchRecord
│   ├── display_models.py # The display contract models (#706), re-exported by models.py
│   ├── batch.py         # Batch id minting + the action_log stamping rule (#549)
│   ├── decisions.py     # The `decisions` section (#758 phase 3): DecisionRecord, its
│   │                    #   bounds, append_decision and the pure queries. Append-only
│   │                    #   — an adoption is a NEW record naming the first in
│   │                    #   `supersedes`, never an edit — because `display.proposals`
│   │                    #   is replaced whole on every dashboard write and so cannot
│   │                    #   be a history
│   ├── _decision_codec.py # That section's two codec halves. Strict like action_log's,
│   │                    #   not tolerant like batches': a decision record IS history
│   ├── expected.py, approval.py, iso_time.py, settings.py, decision_chain.py, ops_intent.py,
│   │   ops_linkage.py, ops_fields.py, ops_history_view.py,
│   │   ops_history_query.py
│   │                    #   Ops history (#848): expected effects, the settings section,
│   │                    #   linking entries to decisions inside the locked append, the
│   │                    #   derived decision → actions → evaluation view, and the
│   │                    #   date-bounded read both MCP and the dashboard use. See
│   │                    #   docs/ops-history.md
│   ├── daily.py         # The day-grain history write MINUS the file (#690/#710):
│   │                    #   `with_platform_daily(doc, ...)` (guard + per-date merge +
│   │                    #   trim) and `capped_platform_daily(daily)` (the 35-day
│   │                    #   retention rule on its own), for a writer that lands
│   │                    #   `daily` inside its OWN atomic document write.
│   │                    #   `set_platform_daily` is the path-based wrapper, so both
│   │                    #   routes keep one set of semantics. Optional `as_of_date`
│   │                    #   = today in the ACCOUNT's timezone: an account closes its
│   │                    #   day locally, so the host clock refused a complete
│   │                    #   yesterday-JST on a UTC host every night
│   ├── observations.py  # What closes an action_log observation, and which are
│   │                    #   past due (#651). ONE rule for `mureo_state_get(
│   │                    #   action_log="pending")` and the Reports triage count;
│   │                    #   two entry shapes (rendered dict / ActionLogEntry)
│   ├── auto_evaluation.py # Closing a past-due observation mureo can decide on
│   │                    #   its own (#758 phase 5): the rule order, the fixed
│   │                    #   skip vocabulary, and ONE locked write for the whole
│   │                    #   pass. Pure decision + write, no MCP imports
│   ├── actor_stamp.py   # `stamp_actor` — the WHO/WHY stamp shared by
│   │                    #   `append_action_log` and the automatic closure, so a
│   │                    #   mureo-written entry carries the same identity on both
│   ├── monthly_budget.py # The `## Custom: Monthly Budget` reader (#652) — the operator's
│   │                     #   INTENDED monthly spend, twin of `guardrails_from_strategy_text`.
│   │                     #   Separate type from `Guardrails` on purpose: a target is not a
│   │                     #   ceiling. "Not set" is a first-class answer (never 0), a total
│   │                     #   derived from `max_total_daily_budget` says so, and the figure
│   │                     #   stays in STRATEGY.md — never copied into STATE.json
│   ├── platform_monthly_budget.py # Rung 2 of that precedence (#656): the sum of the
│   │                     #   per-campaign monthly budgets, for platforms that DECLARED they
│   │                     #   have the concept (`register_monthly_budget_support`; core
│   │                     #   declares none). A third `source`, so a configured sum is never
│   │                     #   shown as an agreed target. No total is stored — it is computed
│   │                     #   on read — and an incomplete or uncollected campaign set is
│   │                     #   withheld rather than summed short, reported as
│   │                     #   `IncompletePlatform(platform, reason)` so an operator is told
│   │                     #   WHICH gap it is (a wrong declaration, a sync behind, a failed
│   │                     #   collection) instead of reading a debug log. The two splits are
│   │                     #   separate fields — `per_platform` is only ever what the operator
│   │                     #   wrote — and the type refuses a split that does not match `source`
│   ├── platform_guards.py # Write-time platform-key guards (#534/#609) — the one "is this key
│   │                      #   real?" answer every other surface asks, including the read-side
│   │                      #   label path (`installed_platform_names`, shared since #631)
│   ├── platform_repair.py # The repair half (#610): plan + drop an entry under an unresolvable
│   │                      #   key. Unresolvable is the FILTER, not the criterion — the document
│   │                      #   must show the entry wrong (#616), and conversion_action_types is
│   │                      #   never dropped (#617). `drop_duplicates` is the one widening: a key
│   │                      #   the OPERATOR named, dropped only against a same-account sibling
│   │                      #   (#636). Drops, never merges; backs up; no action_log
│   ├── action_log_guard.py # A whole-document write that shortens or rewrites action_log leaves a
│   │                      #   timestamped backup and a WARNING first (#758 phase 6). Advisory like
│   │                      #   warn_on_duplicate_accounts — but a backup that FAILS stops the write
│   └── errors.py        # Context-specific errors
├── analysis/            # Analysis utilities
│   ├── lp_analyzer.py   # Landing page analyzer
│   ├── anomaly_detector.py  # Zero-spend / CPA-spike / CTR-drop detection (pure, sample-size-gated)
│   ├── delivery_collapse.py # Delivery-collapse detection (#546) — weekday-aware baseline taken
│   │                        #   from the platform's own daily delivery, never from action_log
│   ├── delivery_collapse_config.py  # ## Guardrails -> CollapseThresholds (the only I/O half)
│   ├── collapse_diagnosis.py        # Change x metric timeline + elimination ladder; reports the
│   │                                #   open questions, never a cause it did not evidence
│   ├── exclusion_impact/    # Delivery-impact preview for bulk exclusions (#547; pure)
│   │   ├── models.py        # DeliveryRecord / ExclusionTarget / ExclusionImpact + coverage verdicts
│   │   ├── matching.py      # Per-entity-kind match rules (host, app id, negative keyword match type)
│   │   ├── estimator.py     # The share itself — incremental and cumulative
│   │   ├── rules.py         # ## Guardrails exclusion keys, the one refusal decision, inert-rule reporting
│   │   └── surfaces.py      # Which tools are exclusion surfaces (mureo's + plugin-registered)
│   └── tracking/        # Tracking-parameter consistency: platform-neutral detector + per-platform URL accessors (#550)
├── rollback/            # Rollback feature (allow-list gated, append-only audit trail)
│   ├── models.py        # RollbackStatus / RollbackPlan + batch verdicts (BatchCoverage, BatchRollbackPlan)
│   ├── planner.py       # plan_rollback(ActionLogEntry) -> RollbackPlan | None
│   ├── batch.py         # plan_batch_rollback(doc, batch_id) -> every member, gaps included (#549)
│   └── executor.py      # execute_rollback(...) -> appends ActionLogEntry(rollback_of=index)
├── adapters/            # Provider adapters wrapping each ad-platform client as a registry Protocol
├── analytics/           # Analytics-module registry for external MCP / plugin platforms (#120)
├── change_import/       # Import changes made OUTSIDE mureo into action_log (#545)
│   ├── models.py        # ExternalChange / ChangeFeedResult / ChangeImportOutcome
│   ├── protocol.py      # ChangeFeedProvider Protocol (`mureo.change_feeds` entry-point group)
│   ├── registry.py      # Discovery + per-plugin fault isolation + lookup
│   ├── dedupe.py        # Already-imported vs mureo's own change (why one is approximate)
│   ├── importer.py      # Watermark, action_log write, per-platform outcome
│   └── builtin/         # Native feeds — google_ads only today; see docs/change-import.md
├── core/                # Extension Protocols + file-backed impls + RuntimeContext; provider & skill discovery
│   └── rotation.py      # Size-bounded append files (#758 phase 6): the one MUREO_JOURNAL_MAX_BYTES
│                        #   reader, the rotated name, and sibling_files (the whole record, oldest first)
├── providers/           # Official MCP provider catalog + one-command install helpers (#86)
├── policy/              # Built-in policy gates (strategy_gate) — ship with OSS, run by default
│   ├── learning_rules.py     # Per-platform learning-period facts + their first-party sources (#548)
│   ├── platform_model.py     # Per-platform delivery-model prose + first-party sources (#648) —
│   │                         #   the ONLY always-on plugin channel: rendered into the MCP
│   │                         #   server's `instructions`, scoped to the platforms served
│   └── learning_reset.py     # Reset-class + learning-state pre-flight the gate refuses on
├── learning/            # Read-side /learn companion: insight federation across configured sources
├── creative_studio/     # Creator-grade ad-creative (image) generation via pluggable providers
├── byod/                # Bring Your Own Data — CSV-backed offline analysis (see BYOD Mode below)
├── web/                 # Local `mureo configure` UI — stdlib http.server on 127.0.0.1 (no web framework)
├── demo/                # `mureo demo init` synthetic-bundle bootstrap (round-trips through BYOD)
├── auth.py              # Credentials management (~/.mureo/credentials.json + env vars + Meta token auto-refresh)
├── auth_setup.py        # Interactive setup wizard (browser OAuth flow)
├── credential_guard.py  # Blocks AI agents from reading ~/.mureo/credentials.json
├── _credential_guard/   # The hook payloads' pieces, one module per step (reasons,
│                        #   path_guard, chars, quoting, spans, braces, bash_guard);
│                        #   import from credential_guard.py
├── logging_setup.py     # Configure-server logging (#581): rotating ~/.mureo/logs/configure.log,
│                        #   MUREO_LOG_LEVEL, and the HTTP access-log query scrubber. Installed by
│                        #   the configure entry point only — never at import time, never on root.
└── throttle.py          # Rate limiting (token bucket + rolling hourly cap)

skills/                       # Native slash skills — one `<name>/SKILL.md` per skill (migrated from
│                             #   .claude/commands in #439; invocable as `/<name>`). Plugins contribute
│                             #   more via the `mureo.native_skills` entry-point group, deployed/removed
│                             #   by `mureo/cli/native_skills.py`.
├── onboard/, daily-check/, rescue/, budget-rebalance/, …   # ~20 operational (workflow) skills
│   └── SKILL.md
└── _mureo-*/                 # 7 foundation skills: _mureo-shared / _mureo-strategy / _mureo-google-ads /
    └── SKILL.md              #   _mureo-meta-ads / _mureo-amazon-ads / _mureo-learning / _mureo-pro-diagnosis
docs/integrations.md          # Platform discovery + external MCP integration guide