spaceads-os 0.3.0__tar.gz

spaceads_os-0.3.0/LICENSE

@@ -0,0 +1,81 @@
+SPACE ADS OS — COMMERCIAL LICENSE AGREEMENT
+
+Copyright (c) Space Ads Sp. z o.o. All rights reserved.
+
+This software is licensed, not sold. Use of this software requires an active,
+paid monthly subscription managed at https://academy.spaceads.agency/space-ads-os.
+
+1. GRANT
+   Subject to an active monthly subscription, Space Ads Sp. z o.o. ("Licensor")
+   grants Licensee a non-exclusive, non-transferable, revocable right to install
+   and run this software on a reasonable number of personal devices controlled
+   by the Licensee.
+
+2. SUBSCRIPTION & BILLING
+   The license is delivered on a monthly subscription basis with auto-renewal.
+   The subscription continues until canceled by Licensee through the customer
+   dashboard at https://academy.spaceads.agency/account/subscription. Cancellation
+   takes effect at the end of the then-current paid billing cycle; no proration
+   applies. Failure to pay a renewal invoice (e.g. card declined) places the
+   subscription in a suspended state at the end of the paid cycle.
+
+3. RUNTIME GATING
+   At every CLI entry point this software verifies an unexpired license
+   against Licensor's verification endpoint. When the subscription is canceled
+   or payment fails, the CLI ceases accepting commands at the end of the paid
+   cycle. Licensee's local data, audit logs, client briefs, and credentials
+   are NOT touched by license expiry — only the runtime is blocked. Reactivating
+   the subscription restores access without re-onboarding.
+
+4. RESTRICTIONS
+   Licensee shall not: (a) sublicense, sell, lease, or otherwise distribute the
+   software or any derivative; (b) remove or alter license-verification code;
+   (c) reverse engineer the software except as expressly permitted by applicable
+   law; (d) use the software to provide services to third parties under a
+   white-label or reseller arrangement without a separate written agreement.
+
+5. UPDATES
+   While the subscription is active, Licensee is entitled to all software
+   updates published on the stable channel — including new API version
+   integrations (e.g. Google Ads v24 → v25), new playbooks, agents, and
+   report templates. There is no separate fee for version bumps.
+
+6. CREDENTIALS
+   The software stores third-party API tokens (Google, Meta, TikTok, GA4) on
+   Licensee's machine and, in encrypted form, on Licensor's servers solely for
+   recovery on a new device. Tokens are encrypted at rest with AES-256-GCM.
+   Licensor will not access plaintext tokens except as required to investigate
+   a support ticket initiated by Licensee. Licensee retains full ownership of
+   the underlying ad accounts; Licensor never assumes ad-account access in its
+   own name.
+
+7. REFUNDS
+   Monthly invoices are non-refundable except as required by applicable consumer
+   protection law. EU consumers waive the 14-day withdrawal right at checkout
+   in exchange for immediate access (Art. 38 pkt 13 ustawy o prawach konsumenta).
+
+8. DISCLAIMER
+   THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+   IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+   FITNESS FOR A PARTICULAR PURPOSE, AND NONINFRINGEMENT.
+
+9. LIMITATION OF LIABILITY
+   IN NO EVENT SHALL LICENSOR BE LIABLE FOR ANY CLAIM, DAMAGES, OR OTHER
+   LIABILITY ARISING FROM ADVERTISING SPEND, ACCOUNT SUSPENSION, OR ANY OTHER
+   USE OF OR INABILITY TO USE THE SOFTWARE. LICENSEE IS SOLELY RESPONSIBLE FOR
+   REVIEWING AND CONFIRMING EVERY MUTATION BEFORE EXECUTION. THE SIX-LAYER
+   SAFETY FRAMEWORK IS A SAFEGUARD, NOT A GUARANTEE.
+
+10. TERMINATION
+    Licensor may terminate this license immediately if Licensee breaches any
+    term, upon which the license is revoked and the CLI hard-blocks. Upon
+    termination Licensee must cease all use and remove the software from all
+    devices.
+
+11. GOVERNING LAW
+    This Agreement is governed by the laws of the Republic of Poland.
+
+For questions: legal@spaceads.agency
+
+This LICENSE file is intended to be reviewed and finalized by counsel before
+public release.

spaceads_os-0.3.0/PKG-INFO

@@ -0,0 +1,335 @@
+Metadata-Version: 2.4
+Name: spaceads-os
+Version: 0.3.0
+Summary: Space Ads OS — multi-channel ads management for Google Ads, Meta, TikTok, and GA4 driven through Claude Code.
+Author-email: Space Ads <support@spaceads.agency>
+License: SPACE ADS OS — COMMERCIAL LICENSE AGREEMENT
+        
+        Copyright (c) Space Ads Sp. z o.o. All rights reserved.
+        
+        This software is licensed, not sold. Use of this software requires an active,
+        paid monthly subscription managed at https://academy.spaceads.agency/space-ads-os.
+        
+        1. GRANT
+           Subject to an active monthly subscription, Space Ads Sp. z o.o. ("Licensor")
+           grants Licensee a non-exclusive, non-transferable, revocable right to install
+           and run this software on a reasonable number of personal devices controlled
+           by the Licensee.
+        
+        2. SUBSCRIPTION & BILLING
+           The license is delivered on a monthly subscription basis with auto-renewal.
+           The subscription continues until canceled by Licensee through the customer
+           dashboard at https://academy.spaceads.agency/account/subscription. Cancellation
+           takes effect at the end of the then-current paid billing cycle; no proration
+           applies. Failure to pay a renewal invoice (e.g. card declined) places the
+           subscription in a suspended state at the end of the paid cycle.
+        
+        3. RUNTIME GATING
+           At every CLI entry point this software verifies an unexpired license
+           against Licensor's verification endpoint. When the subscription is canceled
+           or payment fails, the CLI ceases accepting commands at the end of the paid
+           cycle. Licensee's local data, audit logs, client briefs, and credentials
+           are NOT touched by license expiry — only the runtime is blocked. Reactivating
+           the subscription restores access without re-onboarding.
+        
+        4. RESTRICTIONS
+           Licensee shall not: (a) sublicense, sell, lease, or otherwise distribute the
+           software or any derivative; (b) remove or alter license-verification code;
+           (c) reverse engineer the software except as expressly permitted by applicable
+           law; (d) use the software to provide services to third parties under a
+           white-label or reseller arrangement without a separate written agreement.
+        
+        5. UPDATES
+           While the subscription is active, Licensee is entitled to all software
+           updates published on the stable channel — including new API version
+           integrations (e.g. Google Ads v24 → v25), new playbooks, agents, and
+           report templates. There is no separate fee for version bumps.
+        
+        6. CREDENTIALS
+           The software stores third-party API tokens (Google, Meta, TikTok, GA4) on
+           Licensee's machine and, in encrypted form, on Licensor's servers solely for
+           recovery on a new device. Tokens are encrypted at rest with AES-256-GCM.
+           Licensor will not access plaintext tokens except as required to investigate
+           a support ticket initiated by Licensee. Licensee retains full ownership of
+           the underlying ad accounts; Licensor never assumes ad-account access in its
+           own name.
+        
+        7. REFUNDS
+           Monthly invoices are non-refundable except as required by applicable consumer
+           protection law. EU consumers waive the 14-day withdrawal right at checkout
+           in exchange for immediate access (Art. 38 pkt 13 ustawy o prawach konsumenta).
+        
+        8. DISCLAIMER
+           THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+           IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+           FITNESS FOR A PARTICULAR PURPOSE, AND NONINFRINGEMENT.
+        
+        9. LIMITATION OF LIABILITY
+           IN NO EVENT SHALL LICENSOR BE LIABLE FOR ANY CLAIM, DAMAGES, OR OTHER
+           LIABILITY ARISING FROM ADVERTISING SPEND, ACCOUNT SUSPENSION, OR ANY OTHER
+           USE OF OR INABILITY TO USE THE SOFTWARE. LICENSEE IS SOLELY RESPONSIBLE FOR
+           REVIEWING AND CONFIRMING EVERY MUTATION BEFORE EXECUTION. THE SIX-LAYER
+           SAFETY FRAMEWORK IS A SAFEGUARD, NOT A GUARANTEE.
+        
+        10. TERMINATION
+            Licensor may terminate this license immediately if Licensee breaches any
+            term, upon which the license is revoked and the CLI hard-blocks. Upon
+            termination Licensee must cease all use and remove the software from all
+            devices.
+        
+        11. GOVERNING LAW
+            This Agreement is governed by the laws of the Republic of Poland.
+        
+        For questions: legal@spaceads.agency
+        
+        This LICENSE file is intended to be reviewed and finalized by counsel before
+        public release.
+        
+Project-URL: Homepage, https://academy.spaceads.agency/space-ads-os
+Project-URL: Documentation, https://academy.spaceads.agency/space-ads-os/docs
+Project-URL: Support, https://academy.spaceads.agency/support
+Keywords: advertising,google-ads,meta-ads,tiktok-ads,ga4,claude-code
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: Other/Proprietary License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Office/Business
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: facebook-business>=25.0.1
+Requires-Dist: google-ads<32.0.0,>=31.0.0
+Requires-Dist: google-analytics-data>=0.22.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: pydantic-settings>=2.0.0
+Requires-Dist: python-dotenv>=1.0.0
+Requires-Dist: pandas>=2.0.0
+Requires-Dist: rich>=13.0.0
+Requires-Dist: questionary>=2.0.0
+Requires-Dist: pyyaml>=6.0.0
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: platformdirs>=4.0.0
+Requires-Dist: cryptography>=42.0.0
+Requires-Dist: beautifulsoup4>=4.12.0
+Requires-Dist: requests>=2.32.0
+Requires-Dist: holidays>=0.50
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0.0; extra == "dev"
+Requires-Dist: pytest-cov>=5.0.0; extra == "dev"
+Requires-Dist: ruff>=0.4.0; extra == "dev"
+Requires-Dist: mypy>=1.10.0; extra == "dev"
+Requires-Dist: build>=1.2.0; extra == "dev"
+Provides-Extra: ga4
+Requires-Dist: google-analytics-admin>=0.29.0; extra == "ga4"
+Provides-Extra: reporting
+Requires-Dist: markdown>=3.6; extra == "reporting"
+Requires-Dist: weasyprint>=62.0; extra == "reporting"
+Provides-Extra: sheets
+Requires-Dist: gspread>=6.0.0; extra == "sheets"
+Requires-Dist: google-auth>=2.30.0; extra == "sheets"
+Provides-Extra: docs
+Requires-Dist: mkdocs>=1.6.0; extra == "docs"
+Requires-Dist: mkdocs-material>=9.5.0; extra == "docs"
+Requires-Dist: mkdocstrings[python]>=0.25.0; extra == "docs"
+Provides-Extra: all
+Requires-Dist: google-analytics-admin>=0.29.0; extra == "all"
+Requires-Dist: markdown>=3.6; extra == "all"
+Requires-Dist: weasyprint>=62.0; extra == "all"
+Requires-Dist: gspread>=6.0.0; extra == "all"
+Requires-Dist: google-auth>=2.30.0; extra == "all"
+Requires-Dist: mkdocs>=1.6.0; extra == "all"
+Requires-Dist: mkdocs-material>=9.5.0; extra == "all"
+Requires-Dist: mkdocstrings[python]>=0.25.0; extra == "all"
+Dynamic: license-file
+
+# Space Ads OS
+
+Multi-channel paid media management for Google Ads, Meta Ads, TikTok Ads, and Google Analytics 4 — driven through Claude Code in natural language.
+
+> Commercial software. An active monthly subscription is required to operate the CLI. See [Pricing](https://academy.spaceads.agency/space-ads-os).
+
+## What it does
+
+Space Ads OS is a Python toolkit plus a set of Claude Code slash commands. You talk to Claude in plain language, and Claude calls verified scripts that read and (with confirmation) modify your ad accounts.
+
+- **Google Ads v24.1** — full audits, search-term mining, negative-keyword recommendations, budget and tROAS adjustments, Performance Max diagnostics, iOS vs Android segmentation, frequency-of-reach (`unique_users_*_plus`), and safe terminal mutations on `PMAX_REPLACEMENT_SHOPPING` experiments (`end_experiment` / `graduate_experiment`) gated on the v24.1 direct-stats safety layer.
+- **Meta Ads v25** — campaign health checks, creative analysis, audience overlap, budget pacing, budget / bid mutations with ±30% / ±25% guardrails.
+- **TikTok Ads v1.3** — Smart+ readiness, daily diagnostics, advertiser-level performance, budget / bid mutations matching the Google + Meta surface.
+- **Google Analytics 4** — cross-platform conversion attribution, audience cohorts.
+- **Six-layer safety framework** — every mutation is validated against `LIMITS`, reviewed by the `mutation-reviewer` subagent, previewed, confirmed by the user, executed, verified post-mutation, and logged to `logs/<channel>_changes.jsonl`.
+- **Five subagents** for the long-running flows: `mutation-reviewer`, `report-builder`, `onboarding-coach`, `brand-extractor`, `creative-director`. Each isolates a multi-step task in its own context window.
+- **Per-client brief** — each account you manage carries its own `brief.yaml` (goals, target ROAS, audience, ad-style do/don't, **brand_system** for logo / palette / typography / voice) and `voice.md` (brand voice). Both auto-inject into every slash command so recommendations stay on-brand.
+
+## What's included
+
+| Layer                | Surface                                                                  |
+| -------------------- | ------------------------------------------------------------------------ |
+| User entry points    | 23 slash commands in `.claude/commands/` ([catalog](docs/commands.md))   |
+| Agent orchestration  | 5 subagents in `.claude/agents/` ([catalog](docs/agents.md))             |
+| Channel libraries    | `spaceads_os.{google_ads, meta_ads, tiktok_ads, ga4}` (read + mutate)    |
+| Multi-channel views  | `spaceads_os.multichannel.*` (overview, budget allocation, attribution)  |
+| Brand system         | `spaceads_os.brand.*` — auto-extract from website, persist to brief.yaml |
+| Creative pipeline    | `spaceads_os.creative.*` — briefs, wireframes, safety-zone validator     |
+| Reports              | `spaceads_os.reports.*` + 13 brand-styled HTML templates                 |
+| License + telemetry  | `spaceads_os.license.*` (warm-cache fast path, opt-in telemetry)         |
+| Knowledge base       | `spaceads_os.knowledge/` — 30+ markdown files, shipped in the wheel      |
+
+Full docs at [academy.spaceads.agency/space-ads-os/docs](https://academy.spaceads.agency/space-ads-os/docs).
+
+## First run
+
+**Prerequisite:** Python 3.10+ and [Claude Code](https://docs.claude.com/claude-code) installed.
+
+### Recommended — install as a Claude Code plugin
+
+Inside Claude Code:
+
+```
+/plugin marketplace add rafalch62/space-ads-os-plugin
+/plugin install space-ads-os@space-ads
+```
+
+On the next session start the plugin installs the `spaceads-os` engine from PyPI automatically, drops the operator guide into your project, and greets you. No terminal required.
+
+### Alternative — install with pip
+
+```bash
+# Requires Python 3.10+
+pip install spaceads-os
+mkdir ~/spaceads && cd ~/spaceads
+spaceads init        # writes CLAUDE.md + .claude/ slash commands, agents, SessionStart hook
+claude
+```
+
+`spaceads init` is idempotent — it never overwrites a file you already have unless you pass `--force`. The `spaceads-setup` wizard also runs `init` automatically as its first step, so if you start there instead you can skip the standalone command.
+
+Either way, the first time Claude Code opens the folder, the SessionStart hook detects that no operator profile exists yet and Claude greets you with a suggestion to run:
+
+```
+/spaceads-onboard
+```
+
+That command is a five-minute conversation. It captures who you are (single business owner or agency operator), the businesses you manage, their websites, goals, and ad-style preferences. Everything is saved locally to `.spaceads/operator.yaml` and `clients/<slug>/brief.yaml` — these files survive `pip install -U` because they live outside the package.
+
+If the hook does not auto-fire (for example you used a custom `claude` config), run `/spaceads-onboard` manually — same result.
+
+## Wiring up API access
+
+Once onboarding is complete, Claude tells you to open a terminal and run:
+
+```bash
+spaceads-setup --skip-brief
+```
+
+That walks you through:
+
+1. License activation
+2. Per-channel authentication: Meta, TikTok, and GA4 go through the OAuth bridge at `oauth.spaceads.agency` — the academy hosts the apps server-side, encrypts the resulting tokens in its `oauth_vault` table, and serves them to your CLI on demand against your license key. All three apps are **production-verified** with their respective providers (Google for the `analytics.readonly` GA4 scope, Meta as a Facebook Login for Business System User app, TikTok as a verified Marketing API app), so the consent screen is the normal blue-checkmark flow with no "unverified app" warning. Google Ads is the exception: Google's policy requires every heavy API user to hold their own developer token, so the wizard walks you through registering an MCC + OAuth client.
+3. Vault mirror — a redundant encrypted copy at `clients/<slug>/credentials/<channel>.json.enc` lets you recover after a license-key file loss without re-running OAuth.
+
+The `--skip-brief` flag tells the wizard you have already filled in operator and client briefs through `/spaceads-onboard`. Without that flag the wizard runs an extra inline brief walkthrough — useful if you skipped onboarding entirely.
+
+## Slash commands
+
+Back in Claude Code, every slash command auto-injects your operator profile and the active client's brief, so recommendations stay on-brand:
+
+```
+/spaceads-check meta
+/spaceads-strategy google_ads --client acme-sneakers
+/spaceads-brief view
+/spaceads-onboard --add-client      # add another client later
+/spaceads-report 01_executive_summary --period last_30d
+```
+
+### Strategic and operational commands
+
+Beyond the per-channel check / strategy / modify trio, Space Ads OS ships
+five higher-level workflows:
+
+| Command | What it does |
+|---|---|
+| `/spaceads-bucketing` | Segments a Shopping / PMax feed into 4 performance tiers (Platinum / Gold / Silver / Bronze) and proposes 4 separate campaigns with budgets and tROAS sized per tier. |
+| `/spaceads-seasonal` | Cross-references the seasonal calendar against the feed and impressions. Flags categories whose season is live but the account is not promoting them. |
+| `/spaceads-grow` | 90-day strategic review per client — Socratic walk through 7 axes, ranked hypothesis backlog, 3 / 6 / 12-month roadmap. |
+| `/spaceads-cadence` | Reports overdue / due / scheduled tasks across every client (growth reviews, seasonal setup, monthly reports, brief completeness). |
+| `/spaceads-intel` | Weekly industry pulse — Reddit, top PPC blogs, Google Ads Developer Blog. Scored, deduplicated, grouped into topic libraries. |
+
+The last command renders a brand-styled HTML report from a Space Ads OS template, fills it with live data from every channel the client uses, and opens it in your browser. **Thirteen deliverable templates** ship in the package — executive summary, e-commerce, lead-gen, brand awareness, social, content analysis, local business, growth roadmap, bucketing proposal, experiment verdict (v24.1), competitive landscape, feed health, seasonal calendar. See [Generating reports](src/spaceads_os/knowledge/reference/quickstart.md#5-generate-a-report) for the full workflow.
+
+For new ad creatives, run `/spaceads-brand extract` once per client to capture logo, palette, fonts, and voice samples from the website, then `/spaceads-creative brief --platform meta_stories --campaign "<name>" --objective "<text>"`. You'll get a markdown brief plus a wireframe HTML preview that overlays the platform's safety zones (Meta Stories top 14% / bottom 20%, TikTok in-feed top 130 px / bottom 484 px, Google Display 5-aspect set, etc.). The brief is platform-spec-compliant by construction; the validator (`/spaceads-creative validate <asset> --platform <slug>`) checks the rendered file before upload.
+
+## Generating images
+
+Space Ads OS produces creative briefs and wireframes in-house, but does not bundle an image-gen model — pick the one you trust. Claude Code natively supports MCP image-gen servers; add one to your `.mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "image-gen": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "@your-org/your-image-gen-mcp"]
+    }
+  }
+}
+```
+
+When configured, the `creative-director` agent passes the brief content as the prompt and saves the result into `clients/<slug>/creatives/<campaign>/<variant>/asset.<ext>`. Without one, the agent produces the brief + preview and you generate the asset in your preferred tool — same end result, manual handoff in the middle.
+
+## Channels
+
+| Channel       | Diagnostic | Read | Mutate | Auth model                                                                        |
+| ------------- | :--------: | :--: | :----: | --------------------------------------------------------------------------------- |
+| Google Ads    | yes        | yes  | yes    | Your own developer token (issued from a Google Ads **Manager Account / MCC** — a regular Google Ads account cannot issue one) + your own GCP OAuth client. If you don't have an MCC yet, create one first (free, ~10 min) and link your existing account; the wizard walks you through every step. |
+| Meta Ads      | yes        | yes  | yes    | OAuth via `oauth.spaceads.agency` → System User access token (Facebook Login for Business, non-expiring) → encrypted in `oauth_vault`. CLI fetches on demand by license key; nothing plaintext on disk. |
+| TikTok Ads    | yes        | yes  | yes    | OAuth via `oauth.spaceads.agency` → access token (verified Marketing API app, non-expiring) → encrypted in `oauth_vault`. Same on-demand fetch model as Meta. |
+| GA4           | yes        | yes  | n/a    | OAuth via `oauth.spaceads.agency`, or upload your own service-account JSON.        |
+| LinkedIn Ads  | not yet    | n/a  | n/a    | Placeholder; spec sheet at `src/spaceads_os/knowledge/creative_specs/linkedin.md`. |
+
+> Why is Google Ads different on auth? Google's policy requires every heavy API user to hold their own developer token with `basic_access` or higher, and that token can only be issued from a Manager Account (MCC). Sharing a single token across customers does not pass review. Solo operators with only a regular Google Ads account: create an MCC at <https://ads.google.com/aw/accounts/managers/> (free, ~10 min) and link your existing account before applying for the developer token.
+
+## License model
+
+- **Monthly subscription with auto-renewal.** Pay monthly, the CLI keeps running while the subscription is active. When the subscription is canceled or a renewal payment fails, the CLI hard-blocks at the end of the paid cycle.
+- **Updates included** for the lifetime of the subscription — new channels, new safety patterns, schema migrations are pulled automatically while the subscription is active.
+- **Hardware-soft-bound.** Moving to a new laptop is fine; the system flags unusual fingerprint churn for review but does not block.
+- **License recovery** by email at any time from the customer dashboard at `https://academy.spaceads.agency/account/subscription`.
+- **Cancel anytime.** End-of-cycle cancellation, no proration. Local data, audit logs, briefs and credentials stay untouched on disk after cancellation.
+
+## Documentation
+
+Full docs at [academy.spaceads.agency/space-ads-os/docs](https://academy.spaceads.agency/space-ads-os/docs). The site is built from `docs/` with mkdocs-material; install the `[docs]` extra to build it locally:
+
+```bash
+pip install "spaceads-os[docs]"
+mkdocs build --strict
+```
+
+Local entry points:
+
+- [Buyer quickstart](docs/sales/buyer-quickstart.md) — five minutes from install to first audit, first report, first creative, first mutation
+- [Slash commands catalog](docs/commands.md) — auto-generated from the live `.claude/commands/`
+- [Subagents catalog](docs/agents.md) — auto-generated from the live `.claude/agents/`
+- [Troubleshooting](docs/troubleshooting.md) — first-run failures and how to recover
+
+The full knowledge base ships inside the package at `src/spaceads_os/knowledge/`. Each channel and analytics tool gets one self-contained file with setup, structure, bidding, audience, creative, measurement, KPIs, deprecated features, and Space Ads OS automation in one place:
+
+- [Quickstart](src/spaceads_os/knowledge/reference/quickstart.md) — five minutes from install to first audit
+- [Writing a client brief](src/spaceads_os/knowledge/reference/client_brief.md)
+- [Agent catalog](src/spaceads_os/knowledge/reference/agent_catalog.md) — when each subagent activates and what files it can touch
+- Channels: [Google Ads](src/spaceads_os/knowledge/channels/google_ads.md), [Meta Ads](src/spaceads_os/knowledge/channels/meta_ads.md), [TikTok Ads](src/spaceads_os/knowledge/channels/tiktok_ads.md)
+- Analytics: [GA4](src/spaceads_os/knowledge/analytics/ga4.md), [Merchant Center](src/spaceads_os/knowledge/analytics/merchant_center.md), [GTM / server-side GTM](src/spaceads_os/knowledge/analytics/gtm.md)
+- Creative specs: [overview](src/spaceads_os/knowledge/concepts/creative_specs.md), [Meta](src/spaceads_os/knowledge/creative_specs/meta.md), [Google Ads](src/spaceads_os/knowledge/creative_specs/google_ads.md), [TikTok](src/spaceads_os/knowledge/creative_specs/tiktok.md)
+- Cross-cutting concepts: attribution windows, learning phase, creative testing, dual Pixel+CAPI tracking, blended ROAS, consent / privacy / ATT, budget bands — see `src/spaceads_os/knowledge/concepts/`
+- Vertical playbooks: DTC e-commerce, lead-gen B2C, B2B / SaaS, mobile app, local / multi-location — see `src/spaceads_os/knowledge/playbooks/`
+
+## Support
+
+Email `support@spaceads.agency`.
+
+## License
+
+Commercial. See [LICENSE](LICENSE).

spaceads_os-0.3.0/README.md

@@ -0,0 +1,188 @@
+# Space Ads OS
+
+Multi-channel paid media management for Google Ads, Meta Ads, TikTok Ads, and Google Analytics 4 — driven through Claude Code in natural language.
+
+> Commercial software. An active monthly subscription is required to operate the CLI. See [Pricing](https://academy.spaceads.agency/space-ads-os).
+
+## What it does
+
+Space Ads OS is a Python toolkit plus a set of Claude Code slash commands. You talk to Claude in plain language, and Claude calls verified scripts that read and (with confirmation) modify your ad accounts.
+
+- **Google Ads v24.1** — full audits, search-term mining, negative-keyword recommendations, budget and tROAS adjustments, Performance Max diagnostics, iOS vs Android segmentation, frequency-of-reach (`unique_users_*_plus`), and safe terminal mutations on `PMAX_REPLACEMENT_SHOPPING` experiments (`end_experiment` / `graduate_experiment`) gated on the v24.1 direct-stats safety layer.
+- **Meta Ads v25** — campaign health checks, creative analysis, audience overlap, budget pacing, budget / bid mutations with ±30% / ±25% guardrails.
+- **TikTok Ads v1.3** — Smart+ readiness, daily diagnostics, advertiser-level performance, budget / bid mutations matching the Google + Meta surface.
+- **Google Analytics 4** — cross-platform conversion attribution, audience cohorts.
+- **Six-layer safety framework** — every mutation is validated against `LIMITS`, reviewed by the `mutation-reviewer` subagent, previewed, confirmed by the user, executed, verified post-mutation, and logged to `logs/<channel>_changes.jsonl`.
+- **Five subagents** for the long-running flows: `mutation-reviewer`, `report-builder`, `onboarding-coach`, `brand-extractor`, `creative-director`. Each isolates a multi-step task in its own context window.
+- **Per-client brief** — each account you manage carries its own `brief.yaml` (goals, target ROAS, audience, ad-style do/don't, **brand_system** for logo / palette / typography / voice) and `voice.md` (brand voice). Both auto-inject into every slash command so recommendations stay on-brand.
+
+## What's included
+
+| Layer                | Surface                                                                  |
+| -------------------- | ------------------------------------------------------------------------ |
+| User entry points    | 23 slash commands in `.claude/commands/` ([catalog](docs/commands.md))   |
+| Agent orchestration  | 5 subagents in `.claude/agents/` ([catalog](docs/agents.md))             |
+| Channel libraries    | `spaceads_os.{google_ads, meta_ads, tiktok_ads, ga4}` (read + mutate)    |
+| Multi-channel views  | `spaceads_os.multichannel.*` (overview, budget allocation, attribution)  |
+| Brand system         | `spaceads_os.brand.*` — auto-extract from website, persist to brief.yaml |
+| Creative pipeline    | `spaceads_os.creative.*` — briefs, wireframes, safety-zone validator     |
+| Reports              | `spaceads_os.reports.*` + 13 brand-styled HTML templates                 |
+| License + telemetry  | `spaceads_os.license.*` (warm-cache fast path, opt-in telemetry)         |
+| Knowledge base       | `spaceads_os.knowledge/` — 30+ markdown files, shipped in the wheel      |
+
+Full docs at [academy.spaceads.agency/space-ads-os/docs](https://academy.spaceads.agency/space-ads-os/docs).
+
+## First run
+
+**Prerequisite:** Python 3.10+ and [Claude Code](https://docs.claude.com/claude-code) installed.
+
+### Recommended — install as a Claude Code plugin
+
+Inside Claude Code:
+
+```
+/plugin marketplace add rafalch62/space-ads-os-plugin
+/plugin install space-ads-os@space-ads
+```
+
+On the next session start the plugin installs the `spaceads-os` engine from PyPI automatically, drops the operator guide into your project, and greets you. No terminal required.
+
+### Alternative — install with pip
+
+```bash
+# Requires Python 3.10+
+pip install spaceads-os
+mkdir ~/spaceads && cd ~/spaceads
+spaceads init        # writes CLAUDE.md + .claude/ slash commands, agents, SessionStart hook
+claude
+```
+
+`spaceads init` is idempotent — it never overwrites a file you already have unless you pass `--force`. The `spaceads-setup` wizard also runs `init` automatically as its first step, so if you start there instead you can skip the standalone command.
+
+Either way, the first time Claude Code opens the folder, the SessionStart hook detects that no operator profile exists yet and Claude greets you with a suggestion to run:
+
+```
+/spaceads-onboard
+```
+
+That command is a five-minute conversation. It captures who you are (single business owner or agency operator), the businesses you manage, their websites, goals, and ad-style preferences. Everything is saved locally to `.spaceads/operator.yaml` and `clients/<slug>/brief.yaml` — these files survive `pip install -U` because they live outside the package.
+
+If the hook does not auto-fire (for example you used a custom `claude` config), run `/spaceads-onboard` manually — same result.
+
+## Wiring up API access
+
+Once onboarding is complete, Claude tells you to open a terminal and run:
+
+```bash
+spaceads-setup --skip-brief
+```
+
+That walks you through:
+
+1. License activation
+2. Per-channel authentication: Meta, TikTok, and GA4 go through the OAuth bridge at `oauth.spaceads.agency` — the academy hosts the apps server-side, encrypts the resulting tokens in its `oauth_vault` table, and serves them to your CLI on demand against your license key. All three apps are **production-verified** with their respective providers (Google for the `analytics.readonly` GA4 scope, Meta as a Facebook Login for Business System User app, TikTok as a verified Marketing API app), so the consent screen is the normal blue-checkmark flow with no "unverified app" warning. Google Ads is the exception: Google's policy requires every heavy API user to hold their own developer token, so the wizard walks you through registering an MCC + OAuth client.
+3. Vault mirror — a redundant encrypted copy at `clients/<slug>/credentials/<channel>.json.enc` lets you recover after a license-key file loss without re-running OAuth.
+
+The `--skip-brief` flag tells the wizard you have already filled in operator and client briefs through `/spaceads-onboard`. Without that flag the wizard runs an extra inline brief walkthrough — useful if you skipped onboarding entirely.
+
+## Slash commands
+
+Back in Claude Code, every slash command auto-injects your operator profile and the active client's brief, so recommendations stay on-brand:
+
+```
+/spaceads-check meta
+/spaceads-strategy google_ads --client acme-sneakers
+/spaceads-brief view
+/spaceads-onboard --add-client      # add another client later
+/spaceads-report 01_executive_summary --period last_30d
+```
+
+### Strategic and operational commands
+
+Beyond the per-channel check / strategy / modify trio, Space Ads OS ships
+five higher-level workflows:
+
+| Command | What it does |
+|---|---|
+| `/spaceads-bucketing` | Segments a Shopping / PMax feed into 4 performance tiers (Platinum / Gold / Silver / Bronze) and proposes 4 separate campaigns with budgets and tROAS sized per tier. |
+| `/spaceads-seasonal` | Cross-references the seasonal calendar against the feed and impressions. Flags categories whose season is live but the account is not promoting them. |
+| `/spaceads-grow` | 90-day strategic review per client — Socratic walk through 7 axes, ranked hypothesis backlog, 3 / 6 / 12-month roadmap. |
+| `/spaceads-cadence` | Reports overdue / due / scheduled tasks across every client (growth reviews, seasonal setup, monthly reports, brief completeness). |
+| `/spaceads-intel` | Weekly industry pulse — Reddit, top PPC blogs, Google Ads Developer Blog. Scored, deduplicated, grouped into topic libraries. |
+
+The last command renders a brand-styled HTML report from a Space Ads OS template, fills it with live data from every channel the client uses, and opens it in your browser. **Thirteen deliverable templates** ship in the package — executive summary, e-commerce, lead-gen, brand awareness, social, content analysis, local business, growth roadmap, bucketing proposal, experiment verdict (v24.1), competitive landscape, feed health, seasonal calendar. See [Generating reports](src/spaceads_os/knowledge/reference/quickstart.md#5-generate-a-report) for the full workflow.
+
+For new ad creatives, run `/spaceads-brand extract` once per client to capture logo, palette, fonts, and voice samples from the website, then `/spaceads-creative brief --platform meta_stories --campaign "<name>" --objective "<text>"`. You'll get a markdown brief plus a wireframe HTML preview that overlays the platform's safety zones (Meta Stories top 14% / bottom 20%, TikTok in-feed top 130 px / bottom 484 px, Google Display 5-aspect set, etc.). The brief is platform-spec-compliant by construction; the validator (`/spaceads-creative validate <asset> --platform <slug>`) checks the rendered file before upload.
+
+## Generating images
+
+Space Ads OS produces creative briefs and wireframes in-house, but does not bundle an image-gen model — pick the one you trust. Claude Code natively supports MCP image-gen servers; add one to your `.mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "image-gen": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "@your-org/your-image-gen-mcp"]
+    }
+  }
+}
+```
+
+When configured, the `creative-director` agent passes the brief content as the prompt and saves the result into `clients/<slug>/creatives/<campaign>/<variant>/asset.<ext>`. Without one, the agent produces the brief + preview and you generate the asset in your preferred tool — same end result, manual handoff in the middle.
+
+## Channels
+
+| Channel       | Diagnostic | Read | Mutate | Auth model                                                                        |
+| ------------- | :--------: | :--: | :----: | --------------------------------------------------------------------------------- |
+| Google Ads    | yes        | yes  | yes    | Your own developer token (issued from a Google Ads **Manager Account / MCC** — a regular Google Ads account cannot issue one) + your own GCP OAuth client. If you don't have an MCC yet, create one first (free, ~10 min) and link your existing account; the wizard walks you through every step. |
+| Meta Ads      | yes        | yes  | yes    | OAuth via `oauth.spaceads.agency` → System User access token (Facebook Login for Business, non-expiring) → encrypted in `oauth_vault`. CLI fetches on demand by license key; nothing plaintext on disk. |
+| TikTok Ads    | yes        | yes  | yes    | OAuth via `oauth.spaceads.agency` → access token (verified Marketing API app, non-expiring) → encrypted in `oauth_vault`. Same on-demand fetch model as Meta. |
+| GA4           | yes        | yes  | n/a    | OAuth via `oauth.spaceads.agency`, or upload your own service-account JSON.        |
+| LinkedIn Ads  | not yet    | n/a  | n/a    | Placeholder; spec sheet at `src/spaceads_os/knowledge/creative_specs/linkedin.md`. |
+
+> Why is Google Ads different on auth? Google's policy requires every heavy API user to hold their own developer token with `basic_access` or higher, and that token can only be issued from a Manager Account (MCC). Sharing a single token across customers does not pass review. Solo operators with only a regular Google Ads account: create an MCC at <https://ads.google.com/aw/accounts/managers/> (free, ~10 min) and link your existing account before applying for the developer token.
+
+## License model
+
+- **Monthly subscription with auto-renewal.** Pay monthly, the CLI keeps running while the subscription is active. When the subscription is canceled or a renewal payment fails, the CLI hard-blocks at the end of the paid cycle.
+- **Updates included** for the lifetime of the subscription — new channels, new safety patterns, schema migrations are pulled automatically while the subscription is active.
+- **Hardware-soft-bound.** Moving to a new laptop is fine; the system flags unusual fingerprint churn for review but does not block.
+- **License recovery** by email at any time from the customer dashboard at `https://academy.spaceads.agency/account/subscription`.
+- **Cancel anytime.** End-of-cycle cancellation, no proration. Local data, audit logs, briefs and credentials stay untouched on disk after cancellation.
+
+## Documentation
+
+Full docs at [academy.spaceads.agency/space-ads-os/docs](https://academy.spaceads.agency/space-ads-os/docs). The site is built from `docs/` with mkdocs-material; install the `[docs]` extra to build it locally:
+
+```bash
+pip install "spaceads-os[docs]"
+mkdocs build --strict
+```
+
+Local entry points:
+
+- [Buyer quickstart](docs/sales/buyer-quickstart.md) — five minutes from install to first audit, first report, first creative, first mutation
+- [Slash commands catalog](docs/commands.md) — auto-generated from the live `.claude/commands/`
+- [Subagents catalog](docs/agents.md) — auto-generated from the live `.claude/agents/`
+- [Troubleshooting](docs/troubleshooting.md) — first-run failures and how to recover
+
+The full knowledge base ships inside the package at `src/spaceads_os/knowledge/`. Each channel and analytics tool gets one self-contained file with setup, structure, bidding, audience, creative, measurement, KPIs, deprecated features, and Space Ads OS automation in one place:
+
+- [Quickstart](src/spaceads_os/knowledge/reference/quickstart.md) — five minutes from install to first audit
+- [Writing a client brief](src/spaceads_os/knowledge/reference/client_brief.md)
+- [Agent catalog](src/spaceads_os/knowledge/reference/agent_catalog.md) — when each subagent activates and what files it can touch
+- Channels: [Google Ads](src/spaceads_os/knowledge/channels/google_ads.md), [Meta Ads](src/spaceads_os/knowledge/channels/meta_ads.md), [TikTok Ads](src/spaceads_os/knowledge/channels/tiktok_ads.md)
+- Analytics: [GA4](src/spaceads_os/knowledge/analytics/ga4.md), [Merchant Center](src/spaceads_os/knowledge/analytics/merchant_center.md), [GTM / server-side GTM](src/spaceads_os/knowledge/analytics/gtm.md)
+- Creative specs: [overview](src/spaceads_os/knowledge/concepts/creative_specs.md), [Meta](src/spaceads_os/knowledge/creative_specs/meta.md), [Google Ads](src/spaceads_os/knowledge/creative_specs/google_ads.md), [TikTok](src/spaceads_os/knowledge/creative_specs/tiktok.md)
+- Cross-cutting concepts: attribution windows, learning phase, creative testing, dual Pixel+CAPI tracking, blended ROAS, consent / privacy / ATT, budget bands — see `src/spaceads_os/knowledge/concepts/`
+- Vertical playbooks: DTC e-commerce, lead-gen B2C, B2B / SaaS, mobile app, local / multi-location — see `src/spaceads_os/knowledge/playbooks/`
+
+## Support
+
+Email `support@spaceads.agency`.
+
+## License
+
+Commercial. See [LICENSE](LICENSE).