Dokumentacja publiczna

Co dokładnie dostajesz
w pakiecie Space Ads OS

Pełna lista komend, agentów, raportów i specyfikacji kreacji. To podgląd — kompletna dokumentacja (PDF + markdown) ląduje w paczce po aktywacji subskrypcji.

Aktywuj subskrypcjęWróć do strony produktu

Kanały

Co czyta i co zmienia

Cztery kanały, dwa modele auth. Google Ads — Twój developer token z Twojego MCC (zwykłe konto Google Ads nie wystarczy, trzeba mieć Manager Account; setup ~10 min). Pozostałe kanały — OAuth przez nasz bridge, zero ręcznej konfiguracji.

KanałReadMutateAuthAPI
Google AdstaktakTwój developer token z MCC + Twój OAuth clientv24.1
Meta AdstaktakOAuth przez oauth.spaceads.agency (tokeny szyfrowane lokalnie)Marketing API v25.0
TikTok AdstaktakOAuth przez oauth.spaceads.agency (auto-refresh)Business API v1.3
GA4takn/aOAuth lub Twój service account JSONData API

22 slash commands

Pełna lista komend

Każda komenda z jednolinijkowym opisem i przykładem wywołania.

  • /spaceads-check

    Audyt 360° wybranego konta — 19 sekcji diagnostyki, health score 0–100, lista quick wins.

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

    Stan wszystkich kanałów aktywnego klienta na jednym ekranie.

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

    Daily alert check: learning limited, budget pacing off, drift ROAS, brak spendu, suspension risk.

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

    Audyt mutacji w ostatnich N dniach (z plików JSONL audit log per kanał).

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

    Plan optymalizacji na 30 dni z priorytetami i KPI, zakotwiczony w briefie klienta.

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

    N-gram + intent analysis na search terms, propozycje negatywów PHRASE/EXACT.

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

    Performance per region (HHI), wykluczenia geo, koncentracja spendu.

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

    Zmiana z preview, mutation-reviewerem (APPROVE/WARN/BLOCK) i confirmem.

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

    Nowa kampania / ad set / negative list z playbooka branżowego.

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

    Raport HTML w branding klienta — wybierasz z 13 szablonów.

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

    Attribution gap GA4 vs panele, landing page health, custom definitions audit.

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

    Wyciąga logo, paletę, fonty i głos ze strony klienta, zapisuje do brief.yaml.brand_system.

    /spaceads-brand extract --url=https://klient.pl
  • /spaceads-brief

    Generuje brief kreatywny pod cel kampanii — hook angles, value props, proof points, CTA.

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

    Wireframe per format z safety zones + walidator gotowych assetów.

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

    90-dniowy review strategiczny — 4-fazowy Socratic (7 osi), ranked backlog hipotez, roadmap 3/6/12 mc.

    /spaceads-grow --slug=acme-apparel
  • /spaceads-bucketing

    PMax: podział feedu na 4 tier (Platinum/Gold/Silver/Bronze) z osobnym budżetem i tROAS per tier.

    /spaceads-bucketing --customer-id=1234567890
  • /spaceads-seasonal

    Luki sezonowe — kategoria w peak (sandały latem, kurtki zimą), a Ty jej nie promujesz.

    /spaceads-seasonal --client-slug=acme
  • /spaceads-cadence

    Co zaległe / due / planowane na dziś — wszystkie taski review per klient i per CID.

    /spaceads-cadence overdue
  • /spaceads-intel

    Tygodniowy digest branżowy — Reddit (PPC/GoogleAds), 10 top blogów PPC, Google Ads Developer Blog.

    /spaceads-intel --since=7d
  • /spaceads-onboard

    5-minutowy setup rozmową — operator profile + pierwszy klient brief.

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

    list / switch / add — zarządzanie wieloma klientami w jednym CLI.

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

    Cross-client rollup spendu, ROAS i alertów do tygodniówki agencyjnej.

    /spaceads-agency rollup --period=last_7d

5 agentów AI

Wyspecjalizowani agenci Claude

Każdy z osobnym kontekstem — main Claude orkiestruje, agenci wykonują.

  • mutation-reviewer

    Niezależny review każdej mutacji przed Twoim "TAK"

    Inputy
    Plan zmiany, brief.yaml, historia kampanii, learning-phase status
    Outputy
    APPROVE / WARN / BLOCK + uzasadnienie + rekomendacja
    Model
    Claude Sonnet
  • report-builder

    Generuje raporty HTML w branding klienta

    Inputy
    Wybrany template, period, dane z kanałów, brand_system z briefu
    Outputy
    HTML responsywny, email-ready, otwiera się w przeglądarce
    Model
    Claude Sonnet
  • brand-extractor

    Wyciąga brand system ze strony klienta

    Inputy
    URL strony klienta
    Outputy
    logo, paleta, fonty, voice samples, confidence score 0.0–1.0
    Model
    Claude Sonnet
  • creative-director

    Brief + wireframe + walidacja safety zones per platforma

    Inputy
    Cel kampanii, brand_system, ad_style, format/aspect ratio
    Outputy
    markdown brief + HTML wireframe z safety overlay + walidacja assetu
    Model
    Claude Sonnet
  • onboarding-coach

    5-minutowy onboarding rozmową — operator + pierwszy klient

    Inputy
    Brak (uruchamiany SessionStart hookiem)
    Outputy
    .spaceads/operator.yaml + clients/<slug>/brief.yaml
    Model
    Claude Sonnet

13 szablonów raportów

Każdy szablon ma swoją publiczność

Generujesz komendą /spaceads-report <nazwa> --period=<okres>.

  • 01_executive_summary
    Dla kogo:
    Decision maker, klient C-level
    Główne sekcje:
    KPI cards, blended ROAS, channel split, top 3 rekomendacje
    Długość:
    2 ekrany, 3 min czytania
  • 02_ecommerce_performance
    Dla kogo:
    Performance manager sklepu DTC
    Główne sekcje:
    ROAS per kanał, top SKU, RFM, day-N retention, attribution gap GA4
    Długość:
    5 ekranów, 8 min czytania
  • 03_leadgen_performance
    Dla kogo:
    B2B / lead gen manager
    Główne sekcje:
    CPL, MQL→SQL pipeline, source quality scoring, time-to-MQL, CAC/LTV
    Długość:
    4 ekrany, 6 min czytania
  • 04_brand_awareness
    Dla kogo:
    Brand manager, kampanie TOFU
    Główne sekcje:
    Reach × frequency, brand search lift, share of voice, view-through
    Długość:
    3 ekrany, 5 min czytania
  • 05_social_engagement
    Dla kogo:
    Social media manager (TikTok/Instagram-first)
    Główne sekcje:
    Hook rate, completion rate, top posty, time-of-day heatmap, sentiment
    Długość:
    4 ekrany, 6 min czytania
  • 06_content_analysis
    Dla kogo:
    Creative team, content strategist
    Główne sekcje:
    Performance per format, n-gram tables, hook patterns, sentiment
    Długość:
    4 ekrany, 7 min czytania
  • 07_local_business
    Dla kogo:
    Multi-location, franczyzy
    Główne sekcje:
    League per lokalizacja, geo grid, calls heatmap, ratings, store visits
    Długość:
    5 ekranów, 8 min czytania
  • 08_growth_roadmap
    Dla kogo:
    Klient strategiczny + zespół wewnętrzny
    Główne sekcje:
    Snapshot KPI (30d/prev/YoY), 7-osiowa siatka decyzji, ranked backlog hipotez, 12-tyg Gantt, milestones 6/12 mc
    Długość:
    6 ekranów, 10 min czytania
  • 09_bucketing_proposal
    Dla kogo:
    Klient e-commerce przed launchem 4-tier PMax
    Główne sekcje:
    Tier cards Platinum/Gold/Silver/Bronze, treemap dystrybucji produktów, donut budżetu, 6-krok migration, ryzyka + rollback
    Długość:
    5 ekranów, 7 min czytania
  • 10_experiment_verdict
    Dla kogo:
    Klient po pilocie PMAX_REPLACEMENT_SHOPPING (v24.1)
    Główne sekcje:
    Verdict badge SHIP/HOLD/ROLL BACK, 95% CI bars per metryka, tabela p-value, gate checklist (≥14d, p ≤ 0.05, uplift ≥ +5%), trend ROAS challenger vs incumbent, gotowy fragment graduate_experiment()
    Długość:
    4 ekrany, 6 min czytania
  • 11_competitive_landscape
    Dla kogo:
    Klient zainteresowany pozycją wobec konkurencji
    Główne sekcje:
    Trend SOV 12 tyg., matryca konkurentów (imp share, overlap, position-above, top-of-page, outranking), bid posture per cluster, rekomendowane ruchy
    Długość:
    4 ekrany, 6 min czytania
  • 12_feed_health
    Dla kogo:
    E-commerce z dużym asortymentem / agencyjny audyt feedu
    Główne sekcje:
    Macierz halo-effect STAR/MAGNET/DRIVER/NICHE (v24 cart_data_sales_view), tablica Stars/Workers/Zombies/Draggers, disapprovals breakdown, completion pól, top Magnet SKU do Platinum
    Długość:
    5 ekranów, 7 min czytania
  • 13_seasonal_calendar
    Dla kogo:
    Klient sezonowy / e-commerce z kalendarzem kategorii
    Główne sekcje:
    Heatmap kategoria × tydzień na 90 dni (peak / shoulder / running / gap-peak / gap-shoulder), karty priority gaps z revenue-at-risk + asset SLA, shoulder gaps, donut coverage, asset prep timeline
    Długość:
    4 ekrany, 6 min czytania

Specyfikacje kreacji

Safety zones per platforma

Walidator sprawdza wymiary, safe-zone, contrast i text-on-image % przed uploadem.

PlatformaFormatWymiarySafe zone
MetaStories / Reels1080×1920 (9:16)top 250px, bottom 350px, side 60px
MetaFeed 1:11080×1080text-on-image ≤ 20% (rekomendacja)
Google Display5 aspect ratios1:1 / 4:5 / 1.91:1 / 9:16 / 16:9logo + headline w centralnych 80% ramki
TikTokIn-feed 9:161080×1920top 130px (handle), bottom 484px (CTA + caption)
LinkedInplaceholder—pełna spec po uruchomieniu kanału

Pełne specyfikacje w pakiecie: src/spaceads_os/knowledge/creative_specs/{meta,google_ads,tiktok,linkedin}.md.

6-warstwowy safety

Każda mutacja przechodzi przez sześć warstw

Pięć deterministycznych + jedna AI review (mutation-reviewer). Działa tak samo w piątek o 17 i niedzielę o 3.

  1. 01

    Input validation

    Typy, zakresy, scope konta — zanim cokolwiek dotknie API. Każdy script `*.mutations.*` ma własny schemat pydantic, który walidacja musi przejść jako pierwsza.

  2. 02

    LIMITS check

    safety.LIMITS per kanał: budżet ±30%, target ROAS ±30% (Google/Meta), bid ±25% (TikTok), max 200 negatywów per batch. Hard-blocked: REMOVE. Każdy LIMIT jest stałą w kodzie, nie configiem.

  3. 03

    Preview

    Human-readable diff: jaki obiekt, jakie pole, before → after, szacowany wpływ na spend. Wyświetlany w terminalu przed jakimkolwiek wywołaniem API.

  4. 04

    mutation-reviewer agent

    Subagent Claude Sonnet czyta plan w kontekście historii kampanii i playbooka, zwraca APPROVE / WARN / BLOCK. WARN podświetla ryzyko, BLOCK fizycznie blokuje. Działa przed Twoim "TAK", nie zamiast niego.

  5. 05

    Post-mutation verification

    Po wykonaniu zmiany system robi read-back z API. Jeżeli wartość po nie zgadza się z oczekiwaną, status "incomplete" + alert.

  6. 06

    Audit log (JSONL)

    Każda mutacja → logs/<channel>_changes.jsonl. Append-only. Pełen audit trail per klient.

Każda mutacja loguje się jako JSONL row z polami: timestamp, actor, account, object_type, object_id, field, before, after, reason, reviewer_verdict. Audit log = pełen rollback w jednej komendzie.

Playbooki branżowe

Pięć branż, pięć różnych zestawów reguł

System wybiera wzorce optymalizacji pod Twoją branżę — tROAS targets, conversion lag, bidding strategy presety, struktura kampanii.

  • DTC e-commerce

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

  • Lead generation B2C

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

  • B2B / SaaS

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

  • Mobile app

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

  • Local / multi-location

    Per-lokalizacja geo, store visit conversions, lokalne Search, Google Business Profile signals.

Troubleshooting

Najczęstsze problemy i jak je rozwiązać

Dłuższa wersja w pakiecie: docs/troubleshooting.md.

  • Nie mam Manager Account w Google Ads — co teraz?

    Trzeba założyć MCC (free, ~10 min). Google nie wystawia developer tokenów ze zwykłych kont Google Ads. Kroki: (1) ads.google.com/aw/accounts/managers/ → Create manager account; (2) wybierz "Manage my own accounts" jeśli solo, "Manage other accounts" jeśli agencja; (3) podlinkuj swoje istniejące konto do MCC: Sub-account settings → Link existing account, wpisz 10-cyfrowy Customer ID, zaakceptuj zaproszenie z poziomu zwykłego konta; (4) z MCC: TOOLS → API Center → wnioskuj o developer token (1–2 dni roboczych). Setup-wizard CLI (spaceads-setup) prowadzi krok po kroku.

  • Dostaję 403 z Google Ads API

    Najczęściej: developer token na poziomie Test Account zamiast Basic, albo brak login-customer-id w configu. Sprawdź ~/.config/google-ads/config.yaml — pole login_customer_id musi pasować do MCC, z którego ruszasz API.

  • OAuth do Meta wygasa po 60 dniach

    OAuth bridge oauth.spaceads.agency robi refresh automatycznie tak długo, jak nie cofniesz przyznania w Meta Business Settings. Jeśli widzisz "token expired" — uruchom spaceads-setup --reauth=meta.

  • GA4 zwraca puste sesje

    Najczęstsza pomyłka: w configu wpisany Measurement ID (G-XXXX) zamiast Property ID (numeryczny). Sprawdź clients/<slug>/credentials/ga4.json — pole property_id musi być numerem, nie stringiem zaczynającym się od G-.

  • Smart+ migration nie idzie

    Smart+ wymaga: min 50 konwersji/tydzień, EMQ ≥ 6 dla Pixela, 6+ wariantów kreacji, ROAS w przedziale ±15%. /spaceads-modify migrate-smart-plus pokaże, które warunki nie są spełnione — najczęściej brakuje EMQ albo wariantów kreacji.

  • CLI mówi "subscription inactive"

    Subskrypcja wygasła lub została anulowana. Wejdź na academy.spaceads.agency/account/subscription i reaktywuj. CLI odzyska dostęp w ciągu kilku minut po pobraniu kolejnej opłaty.

  • Audit log w innym timezone niż klient

    Domyślnie logs/changes.jsonl używa UTC. Ustaw zmienną środowiskową SPACEADS_TZ=Europe/Warsaw (lub IANA timezone klienta), żeby timestampy były w lokalnym czasie.

Czas zamienić podgląd na produkt

Subskrypcja miesięczna, faktura natychmiast, dostęp od razu po pierwszym opłaceniu. Anulujesz w każdej chwili.

Aktywuj subskrypcję