| name | getting-started |
| description | Walk the user through first-time setup of the agentic-analytics plugin. Use when the user asks how to get started, how to set up the plugin, where to put their credentials, what the plugin can do for them, or any variant of "first run" / "onboarding" / "walk me through this." |
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}" \
"/requirements.txt"
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.
