connect

---
name: connect
description: Guided wizard for wiring up data sources. Scans .env for what's already connected, splits sources into 🟢 start-now (GA4, Search Console, MailerLite, PageSpeed) versus 🔴 needs-approval (Google Ads, Meta), links to docs/integrations/*, and walks the user through it step by step — separating one-time developer approvals from per-user OAuth. Use when someone runs /growth-os:connect, says "connect my accounts," "hook up GA4," "wire up analytics," or when an audit is blocked because a data source is missing.
---

# connect

The integration wizard. Connecting analytics and ad accounts is where most tools lose people — the approval flows are confusing, some take weeks, and it's never clear what you can start *right now*. `connect` fixes that by telling you exactly what's fast, what's slow, and walking you through each one in the right order.

## What it does

- **Detects** which credentials are already present in `.env` and which sources are live.
- **Classifies** every source as 🟢 (zero-approval, minutes) or 🔴 (needs an owner-side approval with real lead time).
- **Sequences** the setup so the user gets value today: do all the 🟢 sources now, kick off the 🔴 approvals in parallel so their clock starts.
- **Guides** each connection step by step, linking to the matching `docs/integrations/*` page.
- **Separates** the two very different kinds of approval so nobody waits on the wrong thing.

## The two kinds of approval — this is the key distinction

- **Developer approval (once, ever).** A one-time setup the account *owner* does at the platform level — a developer token, a verified business, an app that passes review. Slow, but you do it once and it's done for the whole org. These are the 🔴 sources.
- **User OAuth (per person, fast).** An individual granting read access to their own data via a consent screen. Seconds to minutes. These are the 🟢 sources (plus, later, the read grant on the 🔴 platforms once the developer approval exists).

Conflating these is why integrations feel painful. `connect` keeps them apart and tells the user which clock they're on.

## The sources

### 🟢 Zero-approval — start now, minutes each
- **GA4 (Data API)** — service-account JSON added to the property, or OAuth with `analytics.readonly`. → `docs/integrations/ga4.md`
- **Google Search Console** — `webmasters.readonly`, the *same service account* added as a user on the property. → `docs/integrations/gsc.md`
- **MailerLite** — Bearer API key generated in the MailerLite UI. → `docs/integrations/mailerlite.md`
- **PageSpeed Insights** — an API key from a Google Cloud project. → `docs/integrations/pagespeed.md`

### 🔴 Needs approval — owner-side, real lead time, start in parallel
- **Google Ads** — a developer token on a Manager (MCC) account. Test/Explorer access works to start; Basic access needs Google's sign-off. → `docs/integrations/google-ads.md`
- **Meta Marketing / Graph (+ Instagram)** — **Business Verification first (~14+ days)**, then App Review for `ads_read` / `instagram_*` scopes. → `docs/integrations/meta.md`

## Steps

1. **Scan `.env`.** Report what's already wired: "GA4 ✅, PageSpeed ✅, MailerLite ❌, Search Console ❌…" so the user sees the current state at a glance.

2. **Explain the two clocks.** Briefly: the 🟢 sources take minutes and unlock most of the audit; the 🔴 sources need owner-side approvals that take days-to-weeks, so we start those in the background and don't wait on them.

3. **Do the 🟢 sources first, one at a time.** For each missing 🟢 source: open its `docs/integrations/*` page, walk the exact steps (create key / add service account / paste into `.env`), then verify the connection with a smoke call (`growth-os ga4 visitors 7`, `growth-os psi <url>`, etc.). Confirm it works before moving to the next. Don't dump all four at once — one clean win at a time.

4. **Kick off the 🔴 approvals.** For Google Ads and Meta, explain what the *owner* needs to start today so the lead-time clock begins — especially Meta Business Verification, which gates everything else and is the long pole. Point them at the docs, note it's a one-time developer approval, and mark the source "pending" in the current state. Make clear they don't need to finish this to keep going.

5. **Summarize the new state.** What's live, what's pending, and what that unlocks: "GA4 + GSC live → the audit now has a real baseline. Meta pending verification → ads reach data lands in ~2 weeks." Route back to `/growth-os:audit` (re-run with the new data) or `/growth-os:dashboard` (see integration status).

## Which adapters / CLI it calls

- Verifies each connection with the matching read-side smoke command: `growth-os ga4 …`, `growth-os gsc …`, `growth-os mailerlite …`, `growth-os psi …`, and (once approved) `growth-os google-ads …`, `growth-os meta …`.
- Reads and writes **`.env` only** for credentials — never the hub, never anywhere remote.
- References `docs/integrations/*` for the human steps.

## How it delegates

- **In:** called by `onboard` during first-run, and by `audit`/`dashboard` when a needed source is missing.
- **Out:** once a source connects, hands control back to whatever needed it (usually `audit`). Doesn't do analysis itself — it's plumbing.

## Guardrails

- **Keys stay local.** Everything goes in the user's `.env`. Growth OS stores no credentials and phones nothing home.
- **Never block on 🔴.** The fast sources always run first and independently; slow approvals proceed in parallel.
- **Verify, don't assume.** A source is only "connected" after a live smoke call succeeds.
- **Read scopes only.** Every scope Growth OS requests is read-only (`analytics.readonly`, `webmasters.readonly`, `ads_read`, etc.). It never asks for write access to a user's accounts.