Add setup skill and rework README deploy docs

.agents/skills/setup/SKILL.md

@@ -0,0 +1,166 @@
+---
+name: setup
+description: |
+  Sets up poc-bot end to end: clone (or reuse an existing clone of) the repo, create
+  `.env` from `.env.example`, interactively collect HubSpot/Metabase/Slack credentials,
+  discover pipeline/dashboard/parameter IDs via each service's API, load the environment,
+  and run read-only verification checks against every service. Use this skill whenever the
+  user asks to "run the setup skill", set up, install, configure, bootstrap, or deploy
+  poc-bot (or this repo), and also when a pipeline skill fails because of missing or
+  invalid environment variables.
+---
+
+# 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.
+
+## 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.

.env.example

@@ -10,6 +10,9 @@
 #
 # Never commit your real .env — only this .env.example belongs in version control.
 #
+# Quote any value containing spaces (e.g. LABEL="two words") — unquoted spaces
+# break the `source .env` load step.
+#
 # Legend:  [required]  must be set    [optional]  has a default / can be left blank
 #          Skills:  [poc-analysis]  [poc-not-customer-usage]  [both]
 # ------------------------------------------------------------------------------
@@ -63,14 +66,14 @@ DATA_SOURCES_CONFIG=
 # Primary metric display  [poc-not-customer-usage]
 # ==============================================================================
 # Display label + emoji for your primary value metric (e.g. "API calls", "pipeline runs", "MAU").
-PRIMARY_METRIC_LABEL=primary metric
+PRIMARY_METRIC_LABEL="primary metric"
 PRIMARY_METRIC_EMOJI=:bar_chart:
 
 # ==============================================================================
 # Cohort / filters  [poc-not-customer-usage]
 # ==============================================================================
 # pipeline_label value that marks PoC deals in the deals table.
-POC_PIPELINE_LABEL=poc pipeline
+POC_PIPELINE_LABEL="poc pipeline"
 # Comma-separated internal demo/test team names to exclude (empty by default).
 INTERNAL_TEAM_NAMES=
 # Comma-separated internal domains whose admin emails are flagged as internal/test (empty by default).

README.md

@@ -11,7 +11,7 @@ library only.
 - [How it works](#how-it-works)
 - [Skills](#skills)
 - [Requirements](#requirements)
-- [Setup](#setup)
+- [How to deploy](#how-to-deploy)
 - [Configuration](#configuration)
   - [Finding Metabase IDs](#finding-metabase-ids)
   - [Finding HubSpot IDs](#finding-hubspot-ids)
@@ -42,10 +42,12 @@ skill's `SKILL.md`.
 
 ## Skills
 
-This repo ships two independent skills under `.agents/skills/`:
+This repo ships three skills under `.agents/skills/` — one for deployment and
+two independent reporting pipelines:
 
 | Skill | What it does |
 |---|---|
+| `setup` | Guided deployment — clones the repo if needed, builds `.env`, discovers IDs, verifies API access. |
 | `poc-analysis` | End-to-end POC health analysis — one detailed Slack message per company. |
 | `poc-not-customer-usage` | 30-day primary-metric usage for active-enterprise PoCs not yet closed-won — one ranked Slack summary. |
 
@@ -55,14 +57,34 @@ This repo ships two independent skills under `.agents/skills/`:
 - No third-party packages
 - API credentials for HubSpot, Metabase, and Slack (see [Configuration](#configuration))
 
-## Setup
+## How to deploy
+
+### With an agent (recommended)
+
+Paste this prompt into Warp (or any agent that supports `.agents/skills/`):
+
+```
+Set up poc-bot: clone https://github.com/warpdotdev/poc-agent-oss.git if it
+isn't already cloned, then run the setup skill.
+```
+
+The [`setup` skill](.agents/skills/setup/SKILL.md) walks the agent through the
+whole deployment: cloning (or reusing an existing clone), creating `.env`,
+collecting credentials, discovering your HubSpot/Metabase IDs via their APIs,
+loading the environment, and running read-only verification checks against
+each service. It is safe to re-run to finish a partial setup.
+
+### Manually
+
+The same steps, by hand:
 
 1. Clone the repo:
    ```bash
    git clone https://github.com/warpdotdev/poc-agent-oss.git
    cd poc-agent-oss
    ```
-2. Create your environment file from the example and fill in your values:
+2. Create your environment file from the example and fill in your values
+   (see [Configuration](#configuration) for what goes where):
    ```bash
    cp .env.example .env
    # then edit .env
@@ -202,6 +224,8 @@ JSON file in its `config/` directory:
 ├── README.md
 ├── SECURITY.md
 └── .agents/skills/
+    ├── setup/
+    │   └── SKILL.md                   # guided deployment (see How to deploy)
     ├── poc-analysis/
     │   ├── SKILL.md
     │   ├── config/                    # metabase_cards.json, methodology.md