setup

# poc-bot Setup Skill Goal: finish with a cloned repo, a filled-in `.env`, and verified read-only access to HubSpot, Metabase, and Slack — so the `poc-analysis` and `poc-not-customer-usage` skills work on the next run. **Security rules for this entire skill:** - Never echo, print, or log token values. Reference them only as `$VAR` after they are in the environment, and let the user paste secrets directly into `.env` themselves whenever possible. - Never commit `.env` (it is gitignored — keep it that way). ## Step 0: Locate or clone the repo Check whether you are already inside a poc-agent-oss checkout (the directory containing `.agents/skills/poc-analysis/SKILL.md` and `.env.example`). Search the current directory and its parents. If found, `cd` to the repo root and continue. If not found, clone it and enter it: ```bash git clone https://github.com/warpdotdev/poc-agent-oss.git cd poc-agent-oss ``` Also confirm `python3 --version` is 3.8+. There are no other dependencies — every script uses the Python standard library only. If the user wants to run poc-bot as an Oz cloud or scheduled agent (skip for purely local runs), also verify the Oz CLI: ```bash oz whoami ``` - **Command not found** → if the [Warp app](https://docs.warp.dev/getting-started/installation-and-setup) is already installed, the CLI ships with it. Otherwise, prefer the standalone Oz CLI — there is no need to install the full Warp app just for the CLI. See [Installing the CLI](https://docs.warp.dev/reference/cli#installing-the-cli); on macOS: `brew tap warpdotdev/warp && brew install --cask oz`. - **Not authenticated** → run `oz login` (interactive), or for CI/headless environments export `WARP_API_KEY`. ## Step 1: Create .env ```bash [ -f .env ] || cp .env.example .env ``` An existing `.env` is never overwritten (and unlike `cp -n`, this exits 0 on all platforms when the file already exists). If `.env` already exists, read it and only work on the required values that are still blank or still hold `.env.example` placeholders (e.g. `https://metabase.example.com`) — this makes the skill safe to re-run to finish a partial setup. When writing values, quote anything containing spaces (`LABEL="two words"`) — unquoted spaces break the `source .env` load step. ## Step 2: Determine scope and collect values Ask the user which skill(s) they plan to run — this decides which variables are required: - **Both skills**: `HUBSPOT_ACCESS_TOKEN`, `METABASE_BASE_URL`, `METABASE_API_KEY`, `METABASE_DASHBOARD_ID`, `METABASE_PARAM_DATE_RANGE_ID`, `METABASE_PARAM_TEAM_ID_ID`, `POC_BOT_SLACK_TOKEN`, `SLACK_CHANNEL` - **poc-analysis only**: add `HUBSPOT_POC_PIPELINE_ID`, `HUBSPOT_POC_STAGE_ID` - **poc-not-customer-usage only**: add `METABASE_DB_ID`, `METABASE_PRIMARY_METRIC_DASHCARD_ID`, `METABASE_PRIMARY_METRIC_CARD_ID` `.env.example` is fully annotated (required vs. optional, and which skill uses what) — treat it as the source of truth for every variable and its default. Ask the user for the credentials first (HubSpot private app token, Metabase URL + API key, Slack bot token with `chat:write`). Have them edit `.env` directly for the secrets. The IDs can then be discovered for them in Step 3. ## Step 3: Discover the IDs First load the credentials into the environment — run Step 4's `source` command now, and again after any later `.env` edit. Then you can look up every ID the user doesn't know, instead of making them hunt through UIs. Use read-only GET requests and never print the tokens: **HubSpot pipeline + stage IDs** (`poc-analysis`): ```bash curl -s "https://api.hubapi.com/crm/v3/pipelines/deals" \ -H "Authorization: Bearer $HUBSPOT_ACCESS_TOKEN" ``` Present the pipelines and their stages by label; let the user pick the POC pipeline and the "Pilot Kicked Off" (or equivalent) stage. **Metabase dashboard parameter, dashcard, and card IDs** (both skills): ```bash curl -s "$METABASE_BASE_URL/api/dashboard/$METABASE_DASHBOARD_ID" \ -H "x-api-key: $METABASE_API_KEY" ``` - `parameters[]` → the `id` of the date-range parameter (`METABASE_PARAM_DATE_RANGE_ID`) and the team-id parameter (`METABASE_PARAM_TEAM_ID_ID`) - `dashcards[]` → each tile's `id` (dashcard_id) and `card_id`; for `poc-not-customer-usage`, ask which tile is the primary metric and set `METABASE_PRIMARY_METRIC_DASHCARD_ID` / `METABASE_PRIMARY_METRIC_CARD_ID` **Metabase database ID** (`poc-not-customer-usage`): ```bash curl -s "$METABASE_BASE_URL/api/database" -H "x-api-key: $METABASE_API_KEY" ``` The dashboard ID itself is visible in the dashboard URL: `https://metabase.example.com/dashboard/<ID>-...`. Write each confirmed ID into `.env` (IDs are not secrets, so editing them in is fine). ## Step 4: Load the environment The scripts read from the process environment — there is **no dotenv auto-loader**: ```bash set -a && source .env && set +a ``` Re-run this after every `.env` edit. Remind the user they will need it in any new shell. ## Step 5: Verify (read-only) Run these checks; none of them write or post anything: 1. **HubSpot**: the pipelines request from Step 3 returns HTTP 200 and, for `poc-analysis`, contains the chosen `HUBSPOT_POC_PIPELINE_ID` / `HUBSPOT_POC_STAGE_ID`. 2. **Metabase**: the dashboard request from Step 3 returns HTTP 200 and its `parameters` array contains both configured parameter IDs. 3. **Slack**: ```bash curl -s https://slack.com/api/auth.test -H "Authorization: Bearer $POC_BOT_SLACK_TOKEN" ``` Expect `"ok": true`. Note that `auth.test` does not prove channel access — remind the user to `/invite` the bot to `$SLACK_CHANNEL` (default `#poc-bot`) or posting will fail with `not_in_channel`. If a check fails, show the error (never the token), help fix the value in `.env`, reload (Step 4), and re-check. ## Step 6: Deployment-specific configuration The repo ships with generic labels and placeholder card wiring. Point the user at what to customize for their product (details in the README's "Adapting to your product" section): - `.agents/skills/poc-analysis/config/metabase_cards.json` — which dashboard cards to query and their exact `parameter_mappings` targets (from the Step 3 dashboard response) - `.agents/skills/poc-analysis/config/methodology.md` — primary metric definition, user tier criteria, summary framing - `.agents/skills/poc-analysis/references/metabase_config.md` — their dashboard's column schemas - `.agents/skills/poc-not-customer-usage/config/data_sources.json` — primary-metric parameter targets plus warehouse table/column names - Optional display vars in `.env`: `PRIMARY_METRIC_LABEL`, `PRIMARY_METRIC_EMOJI` This can be deferred — the environment verification above is the blocking part of setup. ## Step 7: Report and hand off Summarize: repo location, which variables were set (names only, never values), which verification checks passed, and anything deferred from Step 6. Then offer to run a pipeline skill (`poc-analysis` or `poc-not-customer-usage`) as the first real end-to-end test.