# First-Time Setup Guide

When authentication fails (error code `MISSING_ENV`), walk the user through setup interactively.

## Step 1: Explain

> To use this skill, you need a Pangolinfo API account for Amazon product data.
> **Good news**: new users get **60 free credits** (≈60 product lookups), no credit card required.
>
> 使用本技能需要 Pangolinfo API 账号，用于获取亚马逊商品数据。
> **好消息**：新用户注册即送 **60 免费积分**（约 60 次商品查询），无需信用卡。

## Step 2: Register

> 1. Go to [pangolinfo.com](https://tool.pangolinfo.com/?referrer=clawhub_amz) and create an account (30 seconds, email only)
> 2. Find your API Key in the dashboard
>
> 1. 访问 [pangolinfo.com](https://tool.pangolinfo.com/?referrer=clawhub_amz) 注册账号（30 秒，仅需邮箱）
> 2. 在控制台找到你的 API Key

## Step 3: Authenticate

**API key (recommended):**
```bash
export PANGOLINFO_API_KEY="<api_key>"
python3 scripts/pangolinfo.py --auth-only
```

**Email + password (alternative):**
```bash
export PANGOLINFO_EMAIL="user@example.com"
export PANGOLINFO_PASSWORD="their-password"
python3 scripts/pangolinfo.py --auth-only
```

**Optional caching (user must opt in):**
```bash
python3 scripts/pangolinfo.py --auth-only --cache-key
```

This saves the key to `~/.pangolinfo_api_key` (mode 0600) so subsequent runs work without env vars.

## Step 4: Confirm

After `"success": true`:
1. Tell the user authentication succeeded
2. Remind them env vars must remain set for new shells (unless cached)
3. Run a free verification (no credits charged):
   ```bash
   python3 scripts/pangolinfo.py --auth-only
   ```
4. Then retry their original request — credits are charged only on successful scrape calls.

## Credit System

| Operation | Credits |
|---|---|
| Amazon scrape (json) | 1 |
| Amazon scrape (rawHtml/markdown) | 0.75 |
| Follow Seller | 1 |
| Variant ASIN | 1 |
| Review page | 5 per page |

API key is permanent (never expires). Credits consumed on success only.
Top up at [pangolinfo.com](https://pangolinfo.com/?referrer=clawhub_amz) when you need more.