Public docs preview

Exactly what you get
in the Space Ads OS package

Full command list, subagents, report templates and creative specs. This is a preview — full docs (PDF + markdown) ship in the package after activation.

Activate subscriptionBack to product page

Channels

What it reads, what it changes

Four channels, two auth models. Google Ads — your own developer token from your own MCC (a regular Google Ads account is not enough; you need a Manager Account, ~10 min to create). The rest run through our OAuth bridge with zero manual config.

ChannelReadMutateAuthAPI
Google AdsyesyesYour MCC developer token + your OAuth clientv24
Meta AdsyesyesOAuth via oauth.spaceads.agency (tokens encrypted client-side)Marketing API v25.0
TikTok AdsyesyesOAuth via oauth.spaceads.agency (auto-refresh)Business API v1.3
GA4yesn/aOAuth or your service account JSONData API

17 slash commands

Full command reference

Every command with a one-line summary and a usage example.

  • /spaceads-check

    360° account audit — 19 diagnostic sections, health score 0–100, list of quick wins.

    /spaceads-check google_ads --period=last_30d
  • /spaceads-overview

    State of every channel for the active client on one screen.

    /spaceads-overview --period=last_7d
  • /spaceads-monitor

    Daily alert check: learning limited, budget pacing off, ROAS drift, no spend, suspension risk.

    /spaceads-monitor --severity=warning
  • /spaceads-changes

    Audit of mutations in the last N days (from per-channel JSONL audit logs).

    /spaceads-changes --days=14
  • /spaceads-strategy

    30-day optimization plan with priorities and KPIs, anchored in the client brief.

    /spaceads-strategy meta --goal=roas
  • /spaceads-keyword-research

    N-gram + intent analysis on search terms, PHRASE/EXACT negative-keyword candidates.

    /spaceads-keyword-research --topic="winter jackets"
  • /spaceads-geo

    Per-region performance (HHI), geo exclusions, spend concentration.

    /spaceads-geo google_ads --period=last_90d
  • /spaceads-modify

    Change with preview, mutation-reviewer (APPROVE/WARN/BLOCK) and confirmation.

    /spaceads-modify "raise tROAS to 4.0 on Search Brand"
  • /spaceads-create

    New campaign / ad set / negative list from a vertical playbook.

    /spaceads-create campaign --vertical=dtc-ecommerce
  • /spaceads-report

    HTML report in client branding — pick from 7 templates.

    /spaceads-report 02_ecommerce_performance --period=last_30d
  • /spaceads-ga4

    GA4-vs-panel attribution gap, landing page health, custom definitions audit.

    /spaceads-ga4 attribution --window=30d
  • /spaceads-brand

    Extract logo, palette, fonts and voice from the client website into brief.yaml.brand_system.

    /spaceads-brand extract --url=https://client.com
  • /spaceads-brief

    Generate a creative brief for a campaign objective — hook angles, value props, proof points, CTA.

    /spaceads-brief --campaign="Spring 2026" --objective=conversions
  • /spaceads-creative

    Per-format wireframe with safety zones + asset validator.

    /spaceads-creative brief --platform=meta_stories
  • /spaceads-onboard

    5-minute conversational setup — operator profile + first client brief.

    /spaceads-onboard --add-client
  • /spaceads-client

    list / switch / add — manage many clients in one CLI.

    /spaceads-client switch acme-saas
  • /spaceads-agency

    Cross-client rollup of spend, ROAS and alerts for the agency weekly.

    /spaceads-agency rollup --period=last_7d

5 AI subagents

Specialized Claude subagents

Each runs in its own context — main Claude orchestrates, agents execute.

  • mutation-reviewer

    Independent review of every mutation before your "yes"

    Inputs
    Change plan, brief.yaml, campaign history, learning-phase status
    Outputs
    APPROVE / WARN / BLOCK + rationale + recommendation
    Model
    Claude Sonnet
  • report-builder

    Generates HTML reports in client branding

    Inputs
    Selected template, period, channel data, brand_system from brief
    Outputs
    Responsive HTML, email-ready, opens in the browser
    Model
    Claude Sonnet
  • brand-extractor

    Extracts the brand system from the client website

    Inputs
    Client website URL
    Outputs
    logo, palette, fonts, voice samples, confidence score 0.0–1.0
    Model
    Claude Sonnet
  • creative-director

    Brief + wireframe + safety-zone validation per platform

    Inputs
    Campaign objective, brand_system, ad_style, format/aspect ratio
    Outputs
    Markdown brief + HTML wireframe with safety overlay + asset validation
    Model
    Claude Sonnet
  • onboarding-coach

    5-minute conversational onboarding — operator + first client

    Inputs
    None (triggered by the SessionStart hook)
    Outputs
    .spaceads/operator.yaml + clients/<slug>/brief.yaml
    Model
    Claude Sonnet

7 report templates

Each template has its own audience

Generate via /spaceads-report <name> --period=<window>.

  • 01_executive_summary
    For whom:
    Decision-maker, C-level client
    Key sections:
    KPI cards, blended ROAS, channel split, top 3 recommendations
    Length:
    2 screens, 3-min read
  • 02_ecommerce_performance
    For whom:
    Performance manager at a DTC store
    Key sections:
    ROAS per channel, top SKUs, RFM, day-N retention, GA4 attribution gap
    Length:
    5 screens, 8-min read
  • 03_leadgen_performance
    For whom:
    B2B / lead-gen manager
    Key sections:
    CPL, MQL→SQL pipeline, source quality scoring, time-to-MQL, CAC/LTV
    Length:
    4 screens, 6-min read
  • 04_brand_awareness
    For whom:
    Brand manager, TOFU campaigns
    Key sections:
    Reach × frequency, brand search lift, share of voice, view-through
    Length:
    3 screens, 5-min read
  • 05_social_engagement
    For whom:
    Social media manager (TikTok/Instagram-first)
    Key sections:
    Hook rate, completion rate, top posts, time-of-day heatmap, sentiment
    Length:
    4 screens, 6-min read
  • 06_content_analysis
    For whom:
    Creative team, content strategist
    Key sections:
    Performance per format, n-gram tables, hook patterns, sentiment
    Length:
    4 screens, 7-min read
  • 07_local_business
    For whom:
    Multi-location, franchises
    Key sections:
    Location league, geo grid, calls heatmap, ratings, store visits
    Length:
    5 screens, 8-min read

Creative specs

Safety zones per platform

The validator checks dimensions, safe-zone, contrast and text-on-image % before upload.

PlatformFormatDimensionsSafe zone
MetaStories / Reels1080×1920 (9:16)top 250px, bottom 350px, side 60px
MetaFeed 1:11080×1080text-on-image ≤ 20% (recommended)
Google Display5 aspect ratios1:1 / 4:5 / 1.91:1 / 9:16 / 16:9logo + headline within central 80% of the canvas
TikTokIn-feed 9:161080×1920top 130px (handle), bottom 484px (CTA + caption)
LinkedInplaceholder—full spec when the channel ships

Full specs in the package: src/spaceads_os/knowledge/creative_specs/{meta,google_ads,tiktok,linkedin}.md.

6-layer safety

Every mutation passes through six layers

Five deterministic + one AI review (mutation-reviewer). Behaves the same on a Friday at 5pm and a Sunday at 3am.

  1. 01

    Input validation

    Types, ranges, account scope — before anything touches the API. Every `*.mutations.*` script has its own pydantic schema that validation must pass first.

  2. 02

    LIMITS check

    safety.LIMITS per channel: budget ±30%, target ROAS ±30% (Google/Meta), bid ±25% (TikTok), max 200 negatives per batch. Hard-blocked: REMOVE. Every LIMIT is a constant in code, not config.

  3. 03

    Preview

    Human-readable diff: which object, which field, before → after, expected impact on spend. Printed in the terminal before any API call.

  4. 04

    mutation-reviewer agent

    A Claude Sonnet subagent reads the plan in the context of campaign history and the playbook, returns APPROVE / WARN / BLOCK. WARN surfaces risk, BLOCK hard-stops execution. Runs before your 'yes', not instead of it.

  5. 05

    Post-mutation verification

    After the change, the system reads the entity back from the API. If the post-state does not match the expected one — status "incomplete" + alert.

  6. 06

    Audit log (JSONL)

    Every mutation → logs/<channel>_changes.jsonl. Append-only. Full audit trail per client.

Every mutation logs as a JSONL row with: timestamp, actor, account, object_type, object_id, field, before, after, reason, reviewer_verdict. Audit log = full rollback in one command.

Vertical playbooks

Five verticals, five different rule sets

The system picks optimization patterns for your vertical — tROAS targets, conversion lag, bidding strategy presets, campaign structure.

  • DTC e-commerce

    PMax + Shopping + Search brand. Stars/Workers/Zombies/Draggers segmentation. Cross-sell tracking. Conversion lag 3–7 days.

  • Lead generation B2C

    Conversion ladder MQL→SQL, source quality scoring, lead value per stage. Conversion lag 7–14 days.

  • B2B / SaaS

    Long sales cycle (14–30+ days), MQL→SQL→Opportunity tracking, brand search incrementality, LinkedIn as a placeholder.

  • Mobile app

    Install→engage→retain funnel, AppsFlyer/Adjust integration, in-app event optimization, ARPU targets.

  • Local / multi-location

    Per-location geo, store visit conversions, local Search, Google Business Profile signals.

Troubleshooting

Top issues and how to recover

Long version in the package: docs/troubleshooting.md.

  • I don't have a Manager Account in Google Ads — what now?

    You need to create an MCC (free, ~10 min). Google does not issue developer tokens from regular Google Ads accounts. Steps: (1) ads.google.com/aw/accounts/managers/ → Create manager account; (2) pick "Manage my own accounts" if solo or "Manage other accounts" if agency; (3) link your existing Google Ads account to the MCC: Sub-account settings → Link existing account, enter the 10-digit Customer ID, accept the invitation from the regular account; (4) inside the MCC: TOOLS → API Center → apply for the developer token (1–2 business days). The CLI setup wizard (spaceads-setup) walks you through every step.

  • I get a 403 from Google Ads API

    Most often: developer token at Test Account level instead of Basic, or missing login-customer-id in the config. Check ~/.config/google-ads/config.yaml — login_customer_id must match the MCC you are calling the API from.

  • Meta OAuth expires after 60 days

    The oauth.spaceads.agency bridge auto-refreshes tokens as long as you do not revoke access in Meta Business Settings. If you see "token expired" — run spaceads-setup --reauth=meta.

  • GA4 returns empty sessions

    Most common mix-up: the config has Measurement ID (G-XXXX) instead of Property ID (numeric). Check clients/<slug>/credentials/ga4.json — property_id must be a number, not a string starting with G-.

  • Smart+ migration is not going through

    Smart+ requires: min 50 conversions/week, EMQ ≥ 6 on the Pixel, 6+ creative variants, ROAS within ±15%. /spaceads-modify migrate-smart-plus shows which conditions fail — most often EMQ or creative variants.

  • CLI says "subscription inactive"

    Subscription expired or was canceled. Visit academy.spaceads.agency/account/subscription and reactivate. The CLI regains access within minutes of the next charge clearing.

  • Audit log timezone differs from the client

    logs/changes.jsonl defaults to UTC. Set SPACEADS_TZ=Europe/Warsaw (or the client IANA timezone) so timestamps are stored in local time.

Time to turn the preview into the product

Monthly subscription, instant invoice, instant access after first payment. Cancel anytime.

Activate subscription