Add setup skill and How to deploy README section

.agents/skills/setup/SKILL.md

@@ -0,0 +1,170 @@
+---
+name: setup
+description: >
+  Set up and deploy the fraud-bot agent end to end: clone the repo (or reuse an
+  existing clone), configure the schema mapping for the adopter's warehouse,
+  register secrets, create an Oz environment, and launch a first run or daily
+  schedule. Use whenever someone asks to "set up fraud-bot", "run the setup
+  skill", "deploy the fraud detection agent", "install this agent", or is
+  getting started with this repo for the first time. Part of the fraud-bot
+  skill suite.
+---
+
+# Fraud Bot Setup
+
+Take a fresh adopter from zero to a working fraud-bot deployment. Work through the
+steps in order, but check the current state first — every step is skippable if it's
+already done. Ask the user for values you can't discover yourself (project names,
+API keys, channel IDs); never invent them.
+
+**Security note:** you will handle API keys in this flow. Never echo, log, or write
+secret values to disk. Let `oz secret create` prompt for values interactively, or have
+the user export environment variables themselves.
+
+## Step 0: Get the repo
+
+Check whether you're already inside a clone (look for `config/schema.json`,
+`instructions.md`, and `queries/` in the current directory or a nearby parent).
+
+If not cloned yet:
+```bash
+git clone https://github.com/warpdotdev/fraud-detection-agent-oss.git
+cd fraud-detection-agent-oss
+```
+
+Run all subsequent steps from the repo root.
+
+## Step 1: Check prerequisites
+
+- **Oz CLI**: `oz --version`. If missing, direct the user to
+  [the Oz CLI docs](https://docs.warp.dev/reference/cli) to install it.
+- **Authentication**: run a harmless authenticated command like `oz environment list`.
+  If it fails with an auth error, ask the user to run `oz login` (or set `WARP_API_KEY`
+  in CI) and re-check.
+- **Python 3**: `python3 --version`. The helper scripts are standard-library only —
+  no `pip install` needed at runtime.
+
+This repo ships **no credentials and no data sources**. The user brings their own
+Metabase instance, a BigQuery warehouse satisfying the contract in `SCHEMA.md`, and
+Slack (optionally Front / Verisoul) tokens. Confirm early which of these they have —
+Metabase + the warehouse are required for detection; Slack is required for reporting;
+Front / Verisoul are only needed for the ban-appeal enrichment skills.
+
+## Step 2: Point the schema config at their warehouse
+
+The queries use **logical** table names resolved from a config file (see `SCHEMA.md`
+for the full contract).
+
+1. Copy the template to the git-ignored local override:
+   ```bash
+   cp config/schema.json config/schema.local.json
+   ```
+2. Ask the user for, and fill in:
+   - `project` — their GCP project ID
+   - `metabase_databases.warehouse` and `.ugc` — their Metabase database IDs
+   - each entry in `tables` — the physical `dataset` / `name` for every logical table
+     they plan to use (they can leave defaults for tables they don't have yet, but warn
+     them which skills/queries depend on which tables per `SCHEMA.md`)
+3. If their columns don't match the contract in `SCHEMA.md`, recommend creating views
+   that alias columns to the expected names rather than editing the SQL.
+4. Verify the config resolves:
+   ```bash
+   python3 scripts/schema.py show
+   python3 scripts/schema.py render queries/known_patterns.sql
+   ```
+   The rendered SQL should show their real dataset/table names and Metabase database
+   ids. Note the GCP project only appears for `{{ fq.* }}` placeholders, which the
+   stock queries don't use — don't let its absence suggest the config isn't applied.
+
+## Step 3: Register secrets
+
+Create team-scoped Oz secrets (injected as environment variables into cloud agent runs).
+Each command prompts interactively for the value — do not pass values on the command line:
+
+```bash
+# Required
+oz secret create --team METABASE_API_KEY
+oz secret create --team SLACK_BOT_TOKEN      # needs chat:write and files:write scopes
+
+# Optional — only for the appeals / verification skills
+oz secret create --team BOT_FRONT_API_KEY
+oz secret create --team SLACK_COMMUNITY_BOT_TOKEN
+oz secret create --team VERISOUL_API_KEY
+```
+
+Skip any secret that already exists (`oz secret list`). Only create the optional ones
+if the user wants the corresponding skills (`front-appeals-inbox`,
+`slack-community-check`, `verisoul-lookup`).
+
+If the user plans to run **locally** instead of on Oz, have them export the same names
+as environment variables in their shell; the scripts read them directly.
+
+## Step 4: Create an Oz environment
+
+The agent needs an [Oz environment](https://docs.warp.dev/agent-platform/cloud-agents/environments)
+that includes this repo (and optionally the user's own server / data-model repos for
+extra context).
+
+1. Check whether a suitable environment already exists: `oz environment list`.
+2. If not, help the user create one that clones this repo (their fork, if they made
+   local schema/config changes they want cloud runs to see — remind them that
+   `config/schema.local.json` is git-ignored, so cloud runs on the upstream repo fall
+   back to the placeholder `config/schema.json` unless they commit a config to a fork
+   or set the `FRAUD_BOT_SCHEMA` env var to the path of a config file — it takes
+   precedence over both config files, per `scripts/schema.py`).
+3. Record the environment ID for the next step.
+
+## Step 5: Verify (optional but recommended)
+
+If the user exported `METABASE_API_KEY` locally, smoke-test the pipeline before the
+first cloud run:
+
+```bash
+python3 scripts/api_client.py query -d warehouse \
+  -s "SELECT user_id FROM {{ tables.core_user_facts }} WHERE signup_date >= CURRENT_DATE() - 1 LIMIT 5"
+```
+
+A JSON result means schema config + Metabase auth both work. If they exported
+`SLACK_BOT_TOKEN`, they can also test posting:
+```bash
+python3 scripts/api_client.py slack -m "fraud-bot setup test"
+```
+
+## Step 6: Run
+
+Ask which cadence the user wants and pick the matching instructions file:
+- `instructions.md` — daily fraud report (24h window → CSV + Slack summary)
+- `instructions_v2.md` — in-depth investigation workflow (~8h cadence)
+- `instructions_signup_spike.md` — lightweight signup-spike monitor (every 30 min)
+
+One-off cloud run:
+```bash
+oz agent run-cloud \
+  --environment <ENV_ID> \
+  --prompt "Read instructions.md and run daily fraud detection analysis"
+```
+
+Or a recurring schedule:
+```bash
+oz schedule create \
+  --name "Daily Fraud Detection" \
+  --cron "0 9 * * *" \
+  --environment <ENV_ID> \
+  --prompt "Read instructions.md and run daily fraud detection analysis"
+```
+
+In cloud runs the repo is checked out under `/workspace/<repo-name>`; if the agent has
+trouble finding the file, use the full path in the prompt (e.g.
+`Read /workspace/fraud-detection-agent-oss/instructions.md ...`).
+
+Point the user at the [Oz web app](https://oz.warp.dev/runs) and
+`oz schedule list` / `oz schedule get <SCHEDULE_ID>` for monitoring.
+
+## Wrap-up checklist
+
+Confirm with the user before declaring setup done:
+- [ ] Repo cloned, `oz` authenticated
+- [ ] `config/schema.local.json` (or fork/`FRAUD_BOT_SCHEMA`) resolves to their warehouse
+- [ ] Required secrets registered (`METABASE_API_KEY`, `SLACK_BOT_TOKEN`)
+- [ ] Environment created and its ID known
+- [ ] First run launched or schedule created

README.md

@@ -9,16 +9,30 @@ This repo contains instructions and SQL queries that an AI agent uses to:
 2. Look for new/emerging fraud clusters
 3. Report findings to Slack
 
-## Setup
+## How to deploy
+
+The fastest path is to let an agent do the setup. Paste this prompt into Warp (or any
+agent runtime that supports skills):
+
+> Clone https://github.com/warpdotdev/fraud-detection-agent-oss.git (or use my existing
+> clone) and run the setup skill at `.agents/skills/setup/SKILL.md` to deploy fraud-bot.
+
+The [setup skill](.agents/skills/setup/SKILL.md) handles cloning, schema config, secret
+registration, environment creation, and the first run — interactively, asking you only
+for the values it can't discover.
+
+Prefer to do it by hand? The same steps follow as a human-readable reference.
+
+### Manual setup (reference)
 
 > **Prerequisites:** the [Oz CLI](https://docs.warp.dev/reference/cli) (`oz`), authenticated with `oz login` (or `WARP_API_KEY` in CI). You bring your own data sources — a Metabase instance, a BigQuery warehouse matching [`SCHEMA.md`](SCHEMA.md), and Slack (optionally Front/Verisoul) tokens. **This repo ships no credentials.**
 
-### 1. Point the schema config at your warehouse
+#### 1. Point the schema config at your warehouse
 Copy `config/schema.json` to `config/schema.local.json` (git-ignored) and set your project,
 datasets, tables, and Metabase database IDs. See [`SCHEMA.md`](SCHEMA.md) for the column
 contract each logical table must satisfy.
 
-### 2. Register secrets
+#### 2. Register secrets
 Store these as team-scoped [Oz agent secrets](https://docs.warp.dev/agent-platform/cloud-agents/secrets)
 (injected as environment variables at runtime):
 ```bash
@@ -32,15 +46,15 @@ oz secret create --team VERISOUL_API_KEY
 Running locally instead of on Oz? Export the same names as environment variables — the scripts
 read them directly (e.g. `export METABASE_API_KEY=...`).
 
-### 3. Create an environment
+#### 3. Create an environment
 Create an [Oz environment](https://docs.warp.dev/agent-platform/cloud-agents/environments) that
 includes this repo (optionally your own server / data-model repos for extra context), then find
 its ID:
 ```bash
 oz environment list
 ```
 
-### 4. Run
+#### 4. Run
 One-off cloud run:
 ```bash
 oz agent run-cloud \
@@ -80,6 +94,7 @@ oz schedule create \
 
 Two complementary skill formats ship with this repo; use whichever your agent runtime supports:
 - `.agents/skills/` — a granular suite, one directory per capability:
+  - Deployment: `setup` — end-to-end install/deploy walkthrough (see [How to deploy](#how-to-deploy))
   - Detection / investigation: `ip-cluster-analysis`, `prompt-injection-denylist`,
     `user-graph-traversal`, `user-convo-summary`
   - Ban-appeal enrichment (optional Front / Slack / Verisoul integrations):