getting-started

First-run onboarding

This is the first thing a new user runs after installing the plugin. Init asks for the bucket name in chat (the only piece of customer data the plugin needs that isn't already on disk), walks the user through aws configure for their AWS credentials, verifies, and persists the runtime config to bucket.json.

The plugin gives the user direct access to their Parse.ly Data Pipeline (DPL) so they can ask questions of their raw event firehose in chat. More data sources land in future versions; v1 is DPL only.

Output discipline

This is a customer-facing first-run flow. Keep it quiet and on-script.

Verbatim where shown. Blockquoted text (> like this) prescribes the exact words you say to the user. Output those words and nothing else for that step.
Silent steps stay silent. Steps tagged (silent on success) produce no chat output when they succeed. Run the shell command, move on. Don't summarize results, don't announce upcoming actions, don't recap state.
No task lists. Don't surface this flow as a todo/task list.
Off-script questions get short answers, then resume. If the customer interrupts with a question, answer briefly and pick up at the next step.
Bucket name lives in bucket.json. If it's already there from a previous run, reuse it silently. Only ask the customer for it if it isn't.
AWS credentials live in ~/.aws/credentials. They're set up by the user via aws configure --profile agentic-analytics in step 5. Subsequent aws invocations pick them up via --profile agentic-analytics. Never ask for them in chat.

Tone

Welcoming, not robust. The user is a Parse.ly customer, so don't explain Parse.ly or the DPL to them. The goal is a productive first run, not a tutorial.

Steps

Greet briefly. Output this verbatim, then immediately continue to step 2:

Setting up your Parse.ly Data Pipeline access – about thirty seconds.

Do not wait for the user to respond. The customer's "yes" was their request to set up; nothing destructive happens here so no further confirmation is needed.
Get the bucket name. Look at ${XDG_CONFIG_HOME:-$HOME/.config}/agentic-analytics/bucket.json. If it exists and has a bucket field, hold that value and continue silently (subsequent steps reuse it; this is the idempotent re-run path).

If the file doesn't exist or the field is missing, output verbatim and wait for a reply:

What's the bucket name holding your DPL events? Your Parse.ly contact should have provided this – it usually looks like parsely-dw-<publisher>.

Record the user's reply as the bucket value. Don't validate the format (step 6's connectivity check is the real test). If the user doesn't have a bucket name, tell them to reach back out to their Parse.ly contact and stop here.
Detect platform and check prerequisites (silent on success). Run uname -s, python3 --version, and aws --version. If platform is Darwin or Linux-family and both tools resolve, continue without comment. If platform is native Windows (no WSL) or a prerequisite is missing, surface the issue and follow the install guidance in "Cross-platform notes" below.

Then create the plugin's isolated Python venv and install DuckDB into it (silent on success). The venv lives at $AGENTIC_ANALYTICS_DATA_DIR/venv (default ~/.local/share/agentic-analytics/venv); ensure_venv.sh is idempotent — it's a fast no-op if the venv already exists and DuckDB is importable, so this only installs once and is safe to re-run:
```
plugin_root="${CLAUDE_PLUGIN_ROOT:-${CURSOR_PLUGIN_ROOT:-<plugin-root>}}"
bash "$plugin_root/scripts/ensure_venv.sh" \
  "${AGENTIC_ANALYTICS_VENV:-${AGENTIC_ANALYTICS_DATA_DIR:-$HOME/.local/share/agentic-analytics}/venv}" \
  "$plugin_root/requirements.txt"
```
Using an isolated venv (rather than pip install into your system Python) avoids PEP 668 "externally-managed-environment" failures on Homebrew and some distro Pythons — nothing is installed system-wide, and the plugin doesn't make assumptions about your Python install.

Ensure the data directory exists (silent). Safe to run unconditionally:

mkdir -p "${AGENTIC_ANALYTICS_DATA_DIR:-$HOME/.local/share/agentic-analytics}"

Set up AWS credentials. Pre-set region and output format silently (idempotent – safe on re-runs):
```
aws configure set region us-east-1 --profile agentic-analytics
aws configure set output json --profile agentic-analytics
```
Then check whether an access key is already configured for the profile:
```
aws configure get aws_access_key_id --profile agentic-analytics 2>/dev/null
```
If that returns a non-empty value, the user already set up credentials on a previous run. Continue silently to step 6 – no verbatim instruction needed.

If it returns empty (no access key set), the user needs to set up credentials. Output verbatim:
Now your access key and secret. Open a new terminal window and run:
```
aws configure --profile agentic-analytics
```
You'll see four prompts in order. Here's what to do at each:
```
AWS Access Key ID [None]:        # paste your access key, then Enter
AWS Secret Access Key [None]:    # paste your secret, then Enter (input is hidden – that's normal)
Default region name [us-east-1]: # just press Enter (already set)
Default output format [json]:    # just press Enter (already set)
```
When your shell prompt comes back, let me know.
Wait for the user to confirm completion before continuing.
Verify connectivity (silent on success). List the by-apikey parquet prefix, substituting the bucket value held from step 2 for <bucket>:
```
aws --profile agentic-analytics s3 ls "s3://<bucket>/by-apikey/" | head
```
If files come back, continue without comment. If the listing is empty or errors, output verbatim:
I couldn't list files in your bucket. The most likely causes:
- The bucket name has a typo. Want to re-enter it? (Clear the saved configs, then run setup again.)
- Your AWS access key or secret has a typo. Re-run aws configure --profile agentic-analytics in your terminal to redo them.
- The AWS keys haven't propagated on Parse.ly's side yet (can take a minute). Want to wait and retry?
Let me know how you'd like to proceed.
Do not continue until verify passes.
Offer to wire up the email-campaign join key. Reports include "cohort CSVs" – lists of visitors who churned, are at risk of churning, or just became brand lovers. By default these are keyed on a Parse.ly cookie hash that's opaque to your CRM, so they're useful for diagnosis but not for direct re-engagement sends. The fix is for the customer to mint a per-recipient identifier and embed it in URLs in their email campaigns (e.g. ?pid=<id>); the report can then surface that identifier in cohort CSVs and the customer merges results back into their CRM list.

If bucket.json from step 2 already has a join_id_key, hold that value and continue silently.

Otherwise, output verbatim and wait for a reply:

Optional: do your email campaigns embed a per-recipient identifier in URLs (e.g. ?pid=...)? If so, what's the parameter name? Type the name (e.g. pid) or "skip" if you don't have this set up yet – you can configure it later by re-running setup.

Treat any reply of skip, no, none, or empty as "no key configured" and continue without setting one. Otherwise record the reply as the join_id_key value. Don't validate further (the report harmlessly emits empty values until matching ?<key>=... URLs land in cached events).
Persist the runtime config (silent on success). Derive a cache_dir slug from the bucket name by stripping the parsely-dw- prefix (e.g. parsely-dw-acme → acme, parsely-dw-acme-co → acme-co). If the bucket doesn't start with parsely-dw-, use the full bucket name as the slug. Then write ${XDG_CONFIG_HOME:-~/.config}/agentic-analytics/bucket.json (mkdir -p the directory first if needed), substituting the bucket value held from step 2 for <bucket>. Include join_id_key only when step 7 captured a value:
```
{
  "bucket": "<bucket>",
  "profile": "agentic-analytics",
  "cache_dir": "<slug>",
  "join_id_key": "<key>"
}
```
Safe to overwrite on re-runs: this is the file step 2 reads from on subsequent inits.
Show what's available. Output verbatim:
You're all set. Here's what the plugin can do today:

Staircase report – visitor-tier audience report (1 visit / 2-4 / 5+) over a 60-day window, comparing the most recent 30 days against the prior 30. Shows tier counts, deltas, tier-to-tier transitions, and per-channel climb yield (the fraction of each channel's prior-window arrivals whose tier rank rose in the current window).

Two ways to run it:
- /agentic-analytics:staircase runs across every site in your bucket.
- /agentic-analytics:staircase <site> filters to one site (e.g. your-site.com).
Or just ask in chat: "Run the staircase report."

Journey report – how far into the site a single visit gets and where the site loses it. Shows engagement depth (the share of visits that reach depth 2+), a three-level route tree with exit as a first-class branch, a loss map of pages that end visits, and a scoreboard of the site's sections. Offers 7/30/60/90-day windows, each compared against the prior window of equal length.

Two ways to run it:
- /agentic-analytics:journey runs across every site in your bucket.
- /agentic-analytics:journey <site> filters to one site (e.g. your-site.com).
Or just ask in chat: "Run the journey report." or "Run the journey report for your-site.com."
Suggest a first thing to try. Output verbatim:

Want to try it? Just say:
Run the staircase report

Cross-platform notes

macOS (Darwin): primary supported platform. All steps verified there.
- Python 3 missing: offer to run xcode-select --install in the shell. The user has to click through the GUI dialog. Wait for them to confirm.
- AWS CLI missing: point to aws.amazon.com/cli for the installer.
Linux: supported via the same flow with distro-specific package commands.
- Python 3 missing: sudo apt install python3 (Debian/Ubuntu), sudo dnf install python3 (Fedora/RHEL), sudo apk add python3 (Alpine). User runs it themselves.
- AWS CLI missing: distro package (sudo apt install awscli etc.) or Amazon's curl-based installer per aws.amazon.com/cli.
Native Windows: not officially supported in v1. WSL users can follow the Linux path.

Out of scope for v1

No synthetic data fallback. v1 assumes the user has real DPL access; the "first thing to try" runs against their data.
No support for non-S3 DPL delivery formats. v1 assumes S3-direct access.
No multi-bucket configuration. A customer with multiple Parse.ly buckets (rare) can clear the saved configs and re-run setup to switch, but only one bucket is active at a time.