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 — komplet dokumentacji (pliki markdown: komendy, agenci, baza wiedzy) instaluje się razem z pakietem i jest czytelny wprost w Claude Code.

Aktywuj subskrypcję Wróć do strony produktu

Historia wersji systemu (changelog) →

Kanały

Co czyta i co zmienia

Sześć powierzchni, trzy 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). Meta, TikTok i GA4 — OAuth przez nasz bridge, zero ręcznej konfiguracji. Search Console i Merchant Center — service account.

Kanał	Read	Mutate	Auth	API
Google Ads	tak	tak	Twój developer token z MCC + Twój OAuth client	v25
Meta Ads	tak	tak	OAuth przez oauth.spaceads.agency (token szyfrowany AES-256-GCM w vaulcie po stronie serwera, pobierany na żądanie — nie leży na Twoim dysku)	Marketing API v25.0
TikTok Ads	tak	tak	OAuth przez oauth.spaceads.agency (auto-refresh)	Business API v1.3
GA4	tak	n/a	OAuth lub Twój service account JSON	Data API
Search Console	tak	n/a	Service account dodany jako użytkownik property (scope webmasters)	Search Console API
Merchant Center	tak	tak	Service account ze scope content (ten sam może obsłużyć GA4)	Merchant API v1

Google Ads

Pełny zestaw narzędzi pod aktualne API v25

17+ skryptów mutacji + diagnostyka, atrybucja, monitoring multi-account dla Google Ads API v25. Każdy z konkretnym celem, każdy do uruchomienia jedną komendą. Wsparcie v24.1: iOS vs Android (segments.mobile_device_platform), frequency-of-reach (unique_users_*_plus), eksperymenty z bezpośrednimi statystykami (point estimate, MoE, p-value) i bramkowane mutacje PMAX_REPLACEMENT_SHOPPING.

Audyt 360° konta
19 sekcji diagnostyki w jednym przebiegu: struktura kampanii, słowa kluczowe, tracking, quality score, ustawienia konta, alerty learning phase. Wynik z health score 0–100.
google_ads.scripts.full_audit
Search terms i bezpieczne negatywy
N-gram analysis (1/2/3 słów) wykrywa wzorce zmarnowanego budżetu na poziomie statystyki, nie pojedynczych zapytań. Sugeruje negatywy w PHRASE i EXACT — BROAD match jest hardkodowo zablokowany.
google_ads.scripts.search_terms_analyzer
Shopping + Merchant Center
Product-level ROAS z podziałem Stars / Workers / Zombies / Draggers. Diagnostyka feedu (błędy, brakujące pola, policy violations) przez Merchant Center Content API v2.1.
google_ads.scripts.feed_optimizer + google_ads.merchant_center
Performance Max — pełen wgląd
Breakdown SEARCH / CONTENT / YOUTUBE / DISCOVERY per asset group. Wykluczenia gender (v24), retail filter shared sets (v24), VTC toggle. iOS vs Android per kampania (v24.1, segments.mobile_device_platform). To, czego sam panel nie pokazuje.
google_ads.scripts.pmax_channel_performance + device_performance
Tworzenie kampanii PMax od zera
Nie tylko analiza — system buduje całą kampanię Performance Max: budżet, kampanię (PAUSED, Maximize Conversion Value z docelowym ROAS) i osobną grupę zasobów per tier z filtrem produktowym po item_id. To silnik /spaceads-bucketing: od segmentacji feedu (Platinum/Gold/Silver/Bronze) do gotowej struktury, w całości pod 6 warstwami ochrony i domyślnie w trybie podglądu.
google_ads.mutations.create_pmax_campaign + create_asset_group_with_listing_filter
Cart data — co kupują, co dokładają
Nowy widok z Google Ads v24: lead_revenue (produkt, który przyciągnął klik) vs cross_sell_revenue (co dosypał do koszyka). Kluczowe dla e-commerce z szerokim asortymentem.
google_ads.scripts.cart_data_analysis
Bidding (tROAS / tCPA) z guardrails
Zmiana target ROAS w zakresie 0,5×–20×, max ±30% per zmiana. Preview pokazuje historię ROAS kampanii, system blokuje skoki, które wybiją learning phase.
google_ads.scripts.update_troas
Geo, device, daypart
Wydajność per kraj (z indeksem koncentracji HHI), per urządzenie, per godzina dnia. Identyfikuje wasted spend po regionach i porach, sugeruje wykluczenia geo.
google_ads.scripts.geo_analysis + google_ads.scripts.device_performance
Attribution gap GA4
Konfrontuje kliknięcia z Google Ads z sesjami w GA4. Pokazuje, gdzie ścieżka konwersji się rozjeżdża (utracone parametry UTM, problemy z tagiem, multi-domain). Plus landing page health: bounce, engagement, czas sesji per kampania.
google_ads.ga4_helper + google_ads.scripts.landing_page_check
Monitoring i alerty
Daily alert check pod całym MCC: learning limited, budget pacing off, drastyczna zmiana ROAS, brak spendu, suspension risk. Email digest, JSONL audit trail, opcjonalnie integracja przez webhook.
google_ads.scripts.alert_check + google_ads.scripts.campaign_watchdog
Frequency-of-reach (v24.1)
Nowy widok z Google Ads v24.1: unique_users_two_plus … ten_plus na poziomie konta. Pokazuje, ilu unikalnych użytkowników widziało reklamę 2×, 3×, 5×, 10×. Diagnostyka flaguje thin frequency (<30% widzi 2×), sweet-spot (avg 3–5, 5+ udział 40–65%) i saturation (≥20% widzi 10×). Domyka warstwę reach × frequency w raporcie brand awareness.
google_ads.scripts.frequency_reach
Eksperymenty: bezpośrednie statystyki + bramkowane shippowanie (v24.1)
PMAX_REPLACEMENT_SHOPPING + 6 pozostałych nowych typów eksperymentów z v24.1. Skrypt experiment_stats czyta point estimate, margin of error i p-value dla 7 metryk (ROAS change, conversions, cost, CPA, …) prosto z API. Bramkowane mutacje end_experiment (rollback) i graduate_experiment (ship) blokują się przed wywołaniem API, jeśli któryś z trzech progów nie przechodzi: ≥14 dni runtime, ROAS p ≤ 0.05, uplift ≥ +5%.
google_ads.experiments + scripts.experiment_stats + mutations.graduate_experiment

Meta Ads

Diagnostyka, optymalizacja i bezpieczne zmiany dla Facebook + Instagram

5 skryptów mutacji + diagnostyka, recommendation engine i blended GA4 dla Marketing API v25.0. Czytasz, optymalizujesz i wykonujesz zmiany w jednym miejscu — z mandatory confirm wrapper, który nie pozwoli wykonać niczego bez Twojej akceptacji.

Insights z trzech poziomów
Campaign / AdSet / Ad — wszystko dostępne w jednym przebiegu. Akcje ekstrahowane z tablicy actions[], policzone CPA/ROAS/CTR z dokładnością do typu konwersji (Purchase, Lead, custom).
insights.py + analysis.py
Diagnostyka i alerty
Reguły progowe na frequency cap, CPA, CTR, ROAS — z poziomami CRITICAL / WARNING / INFO. Wykrywa kampanie w stagnacji learning, frequency ≥2.5× (warning) i ≥4× (critical), drift ROAS poniżej targetu.
diagnostics.py
Recommendation engine
Realokacja budżetu między adsets na podstawie mediany ROAS, sugestie tuningu frequency, identyfikacja audiences do testu. Każda rekomendacja z liczbami i uzasadnieniem.
optimization.py
Blended Meta + GA4
Łączenie insights Meta z GA4 po nazwie kampanii. Pokazuje, ile konwersji Meta liczy "u siebie", a ile GA4 widzi naprawdę po stronie sklepu — czyli prawdziwy attribution gap, nie spór o pixela.
blended.py
Bezpieczne zmiany kampanii
Pause / update budget / update ROAS target — z mandatory .confirm() wrapper. Nigdy delete (operacja zablokowana). Limity: budżet max ±30% per zmiana, odstęp 3–5 dni między tuningami.
campaigns.py + adsets.py + safety.py
Trendy WoW / MoM i anomalie
Tygodniowe i miesięczne porównania ze statystycznym wykrywaniem anomalii. Wskazuje, czy spadek to sezon, weekend, czy faktyczny problem z kampanią.
trends.py

TikTok Ads

Pełna integracja z TikTok Business API v1.3

4 skrypty mutacji + diagnostyka kreacji, Smart+ migration i CAPI z EMQ dla TikTok Business API v1.3. Mutacje przez ten sam wzorzec dry-run + .confirm() co w Meta.

Insights na 4 poziomach
Advertiser / Campaign / AdGroup / Ad — plus breakdown godzinowy. Domyślnie 26 metryk: spend, conversions, total_purchase_value, video_watched_2s, video_views_p100, ROAS, CPA, CTR. Wszystko z jednego endpointu /report/integrated/get/.
insights.py + analysis.py
Diagnostyka kreacji TikToka
Metryki, które TikTok faktycznie nagradza: hook rate (próg 30%), completion rate (próg 10%), frequency fatigue (warning 2.5×, critical 3.5×), creative decay po 10 dniach. Alerty z severity CRITICAL / WARNING / INFO.
diagnostics.py + rules.py
Smart+ migration według reguł
Sprawdza, czy kampania spełnia warunki Smart+: min. 50 konwersji/tydzień, EMQ ≥ 6 dla Pixela, 6+ wariantów kreacji, ROAS w przedziale ±15%. Jeśli tak — przygotowuje migration plan; jeśli nie — wskazuje, czego brakuje.
optimization.py
Pixel + Events API (CAPI)
Pełna obsługa server-side: POST /event/track/ z hashowaniem SHA-256 dla email/phone/external_id, dedup window 5 min, walidacja Event Match Quality (cel ≥ 6, ostrzeżenie poniżej 5). Smart+ i VBO wymagają Pixel + CAPI razem.
pixel.py
Bezpieczne mutacje + bulk
pause / resume / update_budget / update_bid — każda przez PendingAction z dry_run domyślnie. Limity: budżet ±30%, bid ±25%, min. 3 dni między zmianami w learning, blokada delete. Dla wielu kampanii naraz: bulk_pause_campaigns().
campaigns.py + adgroups.py + safety.py
Async reports + GA4 blended
Raporty powyżej 180 dni / 10k wierszy idą przez async flow (create → poll → download). Plus blended.py: merge insights TikToka z GA4 po nazwie kampanii — prawdziwy attribution gap między „TikTok mówi" a „GA4 widzi".
reports_async.py + blended.py

GA4 + multichannel attribution

Jedna prawda po stronie sklepu, nie trzy spory o pixela

GA4 czyta read-only — system łączy go z Google Ads, Meta i TikTokiem po nazwie kampanii i pokazuje, kto naprawdę przyniósł konwersje.

Attribution gap GA4 vs panele
Pokazuje różnicę między tym, co Meta liczy „u siebie", a co GA4 widzi w Twoim sklepie. Pixel argument zamknięty liczbami.
multichannel.attribution_compare
Landing page health
Bounce, engagement rate, czas sesji per kampania. Wyłapuje LP, które ciągną CPA w górę bez Twojej wiedzy.
ga4.scripts.landing_page_quality
Cross-channel blended view
Google + Meta + TikTok + GA4 w jednym CSV/HTML — wreszcie ujednolicona atrybucja w raporcie tygodniowym.
multichannel.attribution_compare + multichannel.overview

24 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-organic
Search Console: zapytania w striking distance (pozycje 5–20) i pokrycie indeksem per URL. Tylko odczyt — Search Console nie ma mutacji.
```
/spaceads-organic --days=28
```
/spaceads-whitelabel
White-label branding raportów — logo, nazwa, paleta i stopka operatora lub per-klient.
```
/spaceads-whitelabel set --logo=logo.svg --name="Twoja Agencja"
```
/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
Podgląd, edycja i przeładowanie briefu klienta oraz pliku voice.md — briefu, który zasila każdą rekomendację. Brief kreatywny pod kampanię generuje /spaceads-creative brief.
```
/spaceads-brief view
```
/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.

Platforma	Format	Wymiary	Safe zone
Meta	Stories / Reels	1080×1920 (9:16)	top 250px, bottom 350px, side 60px
Meta	Feed 1:1	1080×1080	text-on-image ≤ 20% (rekomendacja)
Google Display	5 aspect ratios	1:1 / 4:5 / 1.91:1 / 9:16 / 16:9	logo + headline w centralnych 80% ramki
TikTok	In-feed 9:16	1080×1920	top 130px (handle), bottom 484px (CTA + caption)
LinkedIn	placeholder	—	pełna spec po uruchomieniu kanału

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

Brand + creative pipeline

Od strony klienta do gotowej specyfikacji kreacji

Cztery kroki, każdy z własnym agentem lub komendą. Bez „wyślij mi PDF z księgą znaku" i bez 24h bana po review.

01
Brand extract
Agent brand-extractor pobiera logo, paletę, fonty i głos z URL klienta i zapisuje do brief.yaml.brand_system. Bez ręcznego briefingu.
02
Brief
/spaceads-brief generuje brief kreatywny pod cel kampanii — hook angles, value props, proof points, CTA — w głosie marki, nie w korpomowie.
03
Wireframe
Agent creative-director składa wireframe per format (Meta Story 1080×1920, Reel, Feed 1:1, Google Display 5 ratios, TikTok in-feed 9:16) z bezpiecznymi strefami i miejscami na text overlay.
04
Validator
Sprawdza, czy wymiary, safe-zone, contrast i text-on-image % są zgodne z polityką platformy. Co nie przejdzie review — wraca do iteracji od razu, nie po 24h banie.

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.

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.
02
LIMITS check
safety.LIMITS per kanał: budżet ±30%, target ROAS ±30% (Google/Meta), bid ±25% (TikTok), max negatywów w jednym batchu — 200 na Google Ads, 50 na TikToku. Hard-blocked: REMOVE. Każdy LIMIT jest stałą w kodzie, nie configiem.
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.
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.
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.
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, platform, account, operation, entity_type, entity_id, before, after, reason, status (ok / failed / dry_run), actor oraz run_id wspólny dla jednej operacji. Zapisany stan „before" jest tym, co pozwala zmianę odwrócić i zmierzyć jej efekt — a wpisy dla porażek i dry-runów odróżniają „API odmówiło" od „nikt nie próbował".

Tryb agencyjny

Wielu klientów, jedno CLI, izolowane audit logi

Każdy klient ma własny brief.yaml, własny voice.md, własny logs/changes.jsonl. /spaceads-agency dorzuca rollup cross-client — bez mieszania danych.

clients/registry.yaml — jedno źródło prawdy o aktywnych klientach
Per-klient brief.yaml: cele, ICP, voice, brand_system, vertical playbook
Per-klient credentials/ — Twój Google Ads token, Meta business, TikTok account są od siebie odseparowane
Per-klient logs/changes.jsonl — pełen audit trail dla każdego klienta osobno (RODO-friendly)
/spaceads-agency — cross-client rollup spendu, ROAS, alertów, do tygodniówki agencyjnej

clients/registry.yaml

clients:
  - id: acme-store
    name: Acme Store
    vertical: dtc-ecommerce
    channels: [google, meta, ga4]
  - id: acme-saas
    name: Acme SaaS
    vertical: b2b-saas
    channels: [google, meta]

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.

Wgrana wiedza

To nie generyczne AI — to skodyfikowana wiedza marketingowa

Space Ads OS wstrzykuje do kontekstu Claude Code własną bazę wiedzy: ok. 30 utrzymywanych plików w 6 kategoriach — od integracji per kanał, przez przekrojowe koncepty, po branżowe playbooki. Rekomendacje opierają się na realiach platform i doświadczeniu zespołu, nie na zgadywaniu modelu. Każdy plik możesz przeczytać i dostosować pod swój biznes.

Ile to wiedzy?

60+

stron A4 gęstej wiedzy

33 000+

słów skodyfikowanej praktyki

~30

plików w 6 kategoriach

Objętość krótkiego podręcznika branżowego — i całość trafia do kontekstu Claude Code przy każdej sesji, zamiast być zgadywana przez model.

Kanały
Google Ads, Meta, TikTok — każdy plik w 11 stałych sekcjach: struktura konta, bidding, audiencje, kreacja, pomiar, raportowanie, funkcje wycofywane.
Analityka
GA4, Merchant Center, GTM — model danych, schemat zdarzeń i tagowanie, atrybucja po stronie sklepu.
Koncepty
Learning phase, okna atrybucji, testowanie kreacji, Pixel + CAPI, blended ROAS, zgody/ATT — przekrojowo, opisane raz i linkowane z kanałów.
Playbooki branżowe
DTC e-commerce, lead-gen B2C, B2B/SaaS, aplikacje mobilne, local — jak kanały płatne i GA4 grają razem, z benchmarkami KPI i rytmem pracy na 6 miesięcy.
Specyfikacje kreacji
Google, Meta, TikTok, LinkedIn — formaty, wymiary i strefy bezpieczne, których pilnuje agent creative-director.
Referencje operatora
Słownik, szablon briefu klienta, quickstart, tryb agencyjny, katalog agentów i mapa multichannel.

tROAS ramp-up
Jak bezpiecznie podnosić target ROAS bez zabijania learning phase: max ±30% co 5–7 dni, monitoring window minimum 14 dni, oczekuj spadku liczby konwersji w pierwszych 3 dniach po zmianie.
Meta Andromeda — full-funnel na poziomie ad seta
Andromeda optymalizuje na poziomie ad seta, nie pojedynczych kreacji. Spend rozkłada się intencjonalnie nierówno — jeden ad bierze często 60–80% budżetu. Oceniasz portfel ad seta jako całość, nie pauzujesz po metrykach pojedynczej kreacji. Testuj 10+ konceptualnie odmiennych kreacji, nie wariacje tej samej.
Conversion lag awareness
E-commerce: 3–7 dni od kliknięcia do realnej konwersji. B2B / lead gen: 14–30 dni. System nie panikuje, gdy „dzisiejszy" ROAS jest niski — wie, kiedy ocenić wynik.
PMax vs Search ROAS comparison
Jak porównać Performance Max i Search uczciwie, gdy PMax kanibalizuje search brand: wymuszenie breakdown SEARCH-only, korekty na brand traffic, real incremental ROAS.
Learning-phase respect
Kampania w learning to święta krowa: ±30% to absolutny limit zmiany, brak edytowania creative, brak zmian audiences, ad scheduling tylko w trybie ekstremalnym.

To realna przewaga nad generycznym AI. System nie improwizuje odpowiedzi z tego, co model kiedyś przeczytał w sieci — pracuje na strategiach, które nasz zespół sprawdził na żywych kontach reklamowych, spisał i wgrał do narzędzia. Sprawdzona praktyka, nie pewnie brzmiące zgadywanie.

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
Nie w tym modelu. Token wydawany przez naszą zweryfikowaną aplikację to System User token — nie ma daty wygaśnięcia, więc klasyczny limit 60 dni Cię nie dotyczy. Przestaje działać tylko wtedy, gdy cofniesz zgodę w Meta Business Settings. Jeśli widzisz "token expired" — uruchom spaceads-setup --channel meta, co przechodzi ponownie tylko ten jeden kanał dla aktywnego klienta.
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%. Raport gotowości pokaże, których warunków nie spełniasz: python -m spaceads_os.tiktok_ads.scripts.smart_plus_readiness — 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
Pole `ts` zapisuje czas lokalny maszyny, która wykonała zmianę — bez offsetu strefy. Przy pracy z dwóch maszyn albo dla klienta w innej strefie zestawiaj wpisy po `run_id` i `actor.host`, nie po samej godzinie. Nie ma zmiennej środowiskowej, która to przestawia; jeśli potrzebujesz jednej strefy dla całego zespołu, ustaw ją na poziomie systemu na maszynach wykonujących zmiany.

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ę

Co dokładnie dostajeszw pakiecie Space Ads OS

Co czyta i co zmienia

Pełny zestaw narzędzi pod aktualne API v25

Audyt 360° konta

Search terms i bezpieczne negatywy

Shopping + Merchant Center

Performance Max — pełen wgląd

Tworzenie kampanii PMax od zera

Cart data — co kupują, co dokładają

Bidding (tROAS / tCPA) z guardrails

Geo, device, daypart

Attribution gap GA4

Monitoring i alerty

Frequency-of-reach (v24.1)

Eksperymenty: bezpośrednie statystyki + bramkowane shippowanie (v24.1)

Diagnostyka, optymalizacja i bezpieczne zmiany dla Facebook + Instagram

Insights z trzech poziomów

Diagnostyka i alerty

Recommendation engine

Blended Meta + GA4

Bezpieczne zmiany kampanii

Trendy WoW / MoM i anomalie

Pełna integracja z TikTok Business API v1.3

Insights na 4 poziomach

Diagnostyka kreacji TikToka

Smart+ migration według reguł

Pixel + Events API (CAPI)

Bezpieczne mutacje + bulk

Async reports + GA4 blended

Jedna prawda po stronie sklepu, nie trzy spory o pixela

Attribution gap GA4 vs panele

Landing page health

Cross-channel blended view

Pełna lista komend

Wyspecjalizowani agenci Claude

Każdy szablon ma swoją publiczność

Safety zones per platforma

Od strony klienta do gotowej specyfikacji kreacji

Brand extract

Brief

Wireframe

Validator

Każda mutacja przechodzi przez sześć warstw

Input validation

LIMITS check

Preview

mutation-reviewer agent

Post-mutation verification

Audit log (JSONL)

Wielu klientów, jedno CLI, izolowane audit logi

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

DTC e-commerce

Lead generation B2C

B2B / SaaS

Mobile app

Local / multi-location

To nie generyczne AI — to skodyfikowana wiedza marketingowa

Kanały

Analityka

Koncepty

Playbooki branżowe

Specyfikacje kreacji

Referencje operatora

tROAS ramp-up

Meta Andromeda — full-funnel na poziomie ad seta

Conversion lag awareness

PMax vs Search ROAS comparison

Learning-phase respect

Najczęstsze problemy i jak je rozwiązać

Czas zamienić podgląd na produkt

Co dokładnie dostajesz
w pakiecie Space Ads OS