product-spy

# Purpose

Identify product opportunities by combining:
1. social momentum,
2. regional demand checks,
3. marketplace competition/sales signals,
4. store deployment readiness.

This is an orchestration skill. It does not guarantee profitability.

# Required Installed Skills

- `tavily-search` (inspected latest: `1.0.0`)
- `goplaces` (inspected latest: `1.0.0`)
- `api-gateway` (inspected latest: `1.0.29`)
- Deployment target:
  - `woocommerce` via `api-gateway` (supported), or
  - `shopify` (inspected latest `1.0.1`, currently under maintenance)

Install/update:

```bash
npx -y clawhub@latest install tavily-search
npx -y clawhub@latest install goplaces
npx -y clawhub@latest install api-gateway
npx -y clawhub@latest install shopify
npx -y clawhub@latest update --all
```

Verify:

```bash
npx -y clawhub@latest list
```

# Required Credentials

- `TAVILY_API_KEY` (trend and web data collection)
- `GOOGLE_PLACES_API_KEY` (regional demand proxy via `goplaces`)
- `MATON_API_KEY` (market/deployment APIs via `api-gateway`)

Preflight:

```bash
echo "$TAVILY_API_KEY" | wc -c
echo "$GOOGLE_PLACES_API_KEY" | wc -c
echo "$MATON_API_KEY" | wc -c
```

Mandatory behavior:
- Never fail silently on missing keys.
- Always return `MissingAPIKeys` with missing variables and blocked stages.
- Continue with non-blocked stages and mark output as `Partial` when needed.

# Inputs the LM Must Collect First

- `product_niche` (example: `pets`)
- `target_region` (country/city scope)
- `target_store` (`woocommerce` or `shopify`)
- `risk_tolerance` (`low`, `medium`, `high`)
- `max_cogs` (maximum source cost)
- `min_margin_target` (percentage)
- `shipping_time_limit_days`
- `ad_angle` (problem-solution, UGC demo, before-after)

Do not propose deployment before constraints are explicit.

# Tool Responsibilities

## tavily-search

Use for trend and sourcing discovery:
- find viral product mentions and trend lists,
- gather social evidence summaries,
- locate supplier listings (AliExpress/Alibaba/web...