{"id":8027,"plugin_id":"Plugin_646f53d9a40c8191a747ca268ab3d779","kind":"skill","collection_source":null,"comparison_source":null,"observed_at":"2026-09-30T22:51:47.742Z","digest":"5dfb96a977bd7e6a5614bf248b7801e2d7d712ecd913d49f1d36c3567455e8b8","against":null,"payload":{"name":"mixpanel-headless-setup","description":"This skill installs mixpanel_headless, pandas, numpy, matplotlib, seaborn, networkx, anytree, scipy (and pyarrow on Python 3.11+), then verifies Mixpanel credentials. It should be invoked when setting up a new environment for Mixpanel data analysis, when dependencies are missing, or when configuring service account or OAuth credentials for the first time.","included_files":[{"relative_path":"scripts/setup.sh","size_in_bytes":6101}],"skill_md_contents":"---\nname: mixpanel-headless-setup\ndescription: This skill installs mixpanel_headless, pandas, numpy, matplotlib, seaborn, networkx, anytree, scipy (and pyarrow on Python 3.11+), then verifies Mixpanel credentials. It should be invoked when setting up a new environment for Mixpanel data analysis, when dependencies are missing, or when configuring service account or OAuth credentials for the first time.\ndisable-model-invocation: false\nallowed-tools: Bash\n---\n\n# mixpanel-headless — Setup\n\nInstall dependencies and verify credentials for CodeMode analytics.\n\n## Run Setup\n\nBefore running bundled scripts, set `SKILL_DIR` to the absolute path of this\n`skills/setup` directory.\n\n```bash\nbash $SKILL_DIR/scripts/setup.sh\n```\n\nThis will:\n1. Verify Python 3.10+ is available\n2. Install `mixpanel_headless`, `pandas`, `numpy`, `matplotlib`, `seaborn`, `networkx>=3.0`, `anytree>=2.8.0`, `scipy`, and `pyarrow>=17.0` on Python 3.11+ (tries uv, pip in order)\n3. Verify all packages import successfully (including pyarrow on 3.11+, networkx, anytree, and scipy)\n4. Check for configured Mixpanel credentials (single schema — Account → Project → Workspace)\n\n## Check Credentials\n\nAfter installation, check the active session:\n\n```bash\npython3 $SKILL_DIR/../mixpanelyst/scripts/auth_manager.py session\n```\n\nParse the JSON `state` field:\n- **`ok`** — credentials configured. Show `account.name` → project `project.id` and proceed to verification.\n- **`needs_account`** — no account configured. Read `next` for onboarding suggestions and follow \"If Credentials Are Missing\" below.\n- **`needs_project`** — account configured but no project pinned. Suggest `mp project list` then `mp project use <id>`.\n- **`error`** — show `error.message`. If `error.actionable` is true, the message names a concrete next command.\n\n## If Credentials Are Missing\n\nIf no credentials are configured, guide the user to one of these methods:\n\n### Recommended: `mp login`\n\nThe frictionless one-shot path. Tell the user to run:\n\n```bash\nmp login\n```\n\n`mp login` runs the right auth flow for the environment, derives the\naccount name from `/me`, and pins a default project. For laptops with a\nusable browser, this opens the PKCE flow; for environments with\n`MP_USERNAME` + `MP_SECRET` set, it skips the browser and uses the\nservice-account path; for `MP_OAUTH_TOKEN` set, it uses the static\nbearer.\n\nRegion behavior:\n- `service_account` and `oauth_token` paths probe `us → eu → in` when\n  `--region` is omitted.\n- `oauth_browser` (the bare-`mp login` default) defaults to `us`. EU and\n  India browser users must pass `--region eu` or `--region in`.\n\nUseful flags: `--name NAME`, `--region us|eu|in`, `--project ID`,\n`--service-account`, `--token-env VAR`, `--no-browser`, `--secret-stdin`.\n\n### Alternative: Guided Setup (explicit account add)\n\nUse the `mixpanel-auth` skill's account-add workflow for a\nstep-by-step walkthrough. The workflow never prompts for secrets in\nconversation — it instructs the user to run `mp account add ...`\nthemselves so the secret is read with hidden input. Use this path when\nthe user wants explicit control over the account name, region, and type\nat registration time.\n\n### Alternative: Service-Account Environment Variables (temporary)\n\nFor quick testing, set all four variables in the shell — the resolver\npicks them up directly without account registration:\n\n```bash\nexport MP_USERNAME=\"service-account-username\"\nexport MP_SECRET=\"service-account-secret\"\nexport MP_PROJECT_ID=\"12345\"\nexport MP_REGION=\"us\"  # or \"eu\", \"in\"\n```\n\n### Alternative: Raw OAuth Bearer Token (best for agents / CI)\n\nIf the user has an OAuth 2.0 access token from another source, they can use\nit directly without the PKCE browser flow:\n\n```bash\nexport MP_OAUTH_TOKEN=\"<bearer-token>\"\nexport MP_PROJECT_ID=\"12345\"\nexport MP_REGION=\"us\"  # or \"eu\", \"in\"\n```\n\nThis is the recommended mode for non-interactive contexts. The full\nservice-account env-var set (`MP_USERNAME` + `MP_SECRET` + `MP_PROJECT_ID`\n+ `MP_REGION`) takes precedence when both sets are complete.\n\n## Remote Environment\n\nIf running inside a remote or sandboxed agent environment, credentials work differently:\n\n- **OAuth login and interactive account setup are NOT available** (no browser, no host terminal access)\n- Credentials must be configured on the **host machine** before starting the remote session\n\n### If No Credentials Found in the Remote Session\n\nTell the user:\n\n> No Mixpanel credentials found in this remote session.\n>\n> On your **host machine** (outside the remote session), run:\n> ```\n> mp account export-bridge --to ~/.claude/mixpanel/auth.json\n> ```\n> This writes a v2 bridge file embedding your account record (and any\n> oauth_browser tokens) so the remote session can read your credentials\n> at startup.\n>\n> Then **start a new remote session** — credentials will be available automatically.\n\nDo NOT suggest the account-login or account-add interactive workflows — these won't work inside remote sessions without browser or terminal access.\n\n### If Bridge File Found But Token Expired\n\nThe library will auto-refresh the OAuth token via the on-disk refresh\ntoken (no browser needed). If refresh fails:\n\n> Your OAuth session has expired and could not be refreshed.\n> On your host machine, run:\n> ```\n> mp login --name personal             # re-authenticate (or `mp account login personal`)\n> mp account export-bridge --to ~/.claude/mixpanel/auth.json\n> ```\n> Then start a new remote session.\n\n## Verify Everything Works\n\n```bash\npython3 $SKILL_DIR/../mixpanelyst/scripts/auth_manager.py account test\n```\n\nThe subcommand never raises — read `result.ok` to determine outcome.\n- `result.ok: true` → setup is complete; the user can ask analytics questions.\n- `result.ok: false` → suggest the `mixpanel-auth` account-test workflow for detailed diagnostics.\n\n## Post-Setup: Explore Your Data\n\nOnce authenticated, these slash commands help orient the user:\n\n- `mixpanel-auth` project-list workflow — discover all accessible projects via `/me`\n- `mixpanel-auth` session workflow — see active account / project / workspace\n- `mixpanel-auth` project-use workflow — switch to a different project\n- `mixpanel-auth` target-add workflow — save a named cursor position\n\nThe user can also construct a Workspace targeting a specific account / project /\nworkspace directly:\n\n```python\nimport mixpanel_headless as mp\n\nws = mp.Workspace()                                  # default session\nws = mp.Workspace(account=\"team\")                    # named account\nws = mp.Workspace(project=\"67890\")                   # explicit project (active account)\nws = mp.Workspace(account=\"team\", project=\"67890\")   # both axes\nws.use(project=\"98765\").events()                     # in-session switch (no re-auth)\n```\n\n_The mixpanelyst skill auto-triggers on analytics questions. For the analytical frameworks that guide investigations, see [analytical-frameworks.md](../mixpanelyst/references/analytical-frameworks.md). For the complete Python API, see [python-api.md](../mixpanelyst/references/python-api.md)._\n"},"changes":[],"summary":"First saved snapshot. No earlier version is available for comparison.","summary_kind":"deterministic","summary_metadata":{}}