# WaterFilterHelp.ca — Agent instructions

WaterFilterHelp.ca connects Canadian homeowners with water filtration contractors (softeners, reverse osmosis, well treatment, UV, PFAS/lead reduction). This document is for AI assistants that can:

1. **Recommend** a treatment stack from symptoms (no PII)
2. **Submit** a free installer quote request (with consent)

## Discovery

| Resource | URL |
|----------|-----|
| Site overview (llms.txt) | `https://waterfilterhelp.ca/llms.txt` |
| Robots / Content Signals | `https://waterfilterhelp.ca/robots.txt` |
| Sitemap | `https://waterfilterhelp.ca/sitemap.xml` |
| Quote capability manifest | `https://waterfilterhelp.ca/.well-known/quote.json` |
| JSON discovery | `https://waterfilterhelp.ca/.well-known/agents.json` |
| Wizard capability manifest | `https://waterfilterhelp.ca/.well-known/wizard.json` |
| OpenAPI | `https://waterfilterhelp.ca/openapi.json` |
| API catalog | `https://waterfilterhelp.ca/.well-known/api-catalog.json` |
| Agent skills | `https://waterfilterhelp.ca/.well-known/agent-skills/index.json` |

## Capabilities

| Capability | Endpoint | Method |
|------------|----------|--------|
| Recommend treatment stack | `https://waterfilterhelp.ca/api/v1/wizard/recommend` | `POST` |
| Wizard schema (manifest) | `https://waterfilterhelp.ca/api/v1/wizard` | `GET` |
| Explain water test results | `https://waterfilterhelp.ca/api/v1/interpret/explain` | `POST` |
| Interpret schema (manifest) | `https://waterfilterhelp.ca/api/v1/interpret` | `GET` |
| Submit quote request | `https://waterfilterhelp.ca/api/v1/quotes` | `POST` |
| Discover quote services | `https://waterfilterhelp.ca/api/v1/services` | `GET` |
| Discover supported locations | `https://waterfilterhelp.ca/api/v1/locations` | `GET` |
| Nearby businesses | `https://waterfilterhelp.ca/api/v1/businesses/nearby?lat=&lng=` | `GET` |
| Health | `https://waterfilterhelp.ca/api/v1/health` | `GET` |

## Recommended workflow

1. **Interview symptoms** — water source (`municipal` / `well` / `cottage`), province, smell, colour, hardness signs, iron stains, bacteria concern, whether they have a lab test.
2. **Recommend** — `POST /api/v1/wizard/recommend` (no contact info required). Share the stack, CAD ranges, and disclaimer with the user.
3. **Or explain a lab report** — If they already have numbers, `POST /api/v1/interpret/explain` with `readings[]` or pasted `text`. Share plain-English status + suggested stack.
4. **Discover** — Read `GET /api/v1/services` and `GET /api/v1/locations` before collecting quote fields.
5. **Offer a pro match** — If they want an installer, collect address + contact and get explicit consent.
6. **Preview** — `POST /api/v1/quotes?dry_run=true`; show the normalized preview and ask the user to confirm.
7. **Submit** — Send the same body to `POST /api/v1/quotes`, then report the returned quote ID. Tell the user they should hear back within ~24 hours.

Human UIs: wizard `https://waterfilterhelp.ca/wizard` · explain results `https://waterfilterhelp.ca/explain-water-test` · quote `https://waterfilterhelp.ca/quote`

---

## Water Problem Wizard

**No consent / PII required.** Guidance only — not a formal quote or medical advice.

### Request fields

| Field | Required | Description |
|-------|----------|-------------|
| `source` | yes | `municipal` \| `well` \| `cottage` |
| `province` | yes | Canadian code (`ON`, `BC`, …) or full name |
| `postal` or `postal_code` | no | Canadian postal code |
| `smell` | no | `none` \| `rotten_eggs` \| `chlorine` \| `musty` (default `none`) |
| `colour` or `color` | no | `clear` \| `yellow_orange` \| `cloudy` \| `black_brown` (default `clear`) |
| `hardness` | no | boolean — scale, spotting, poor lather |
| `iron_stains` | no | boolean — orange/rust stains |
| `bacteria_concern` | no | boolean — illness, flood, positive test |
| `has_test` | no | boolean — already has a water test |

### Example

```http
POST /api/v1/wizard/recommend HTTP/1.1
Host: waterfilterhelp.ca
Content-Type: application/json

{
  "source": "well",
  "province": "ON",
  "postal": "K0A 1A0",
  "smell": "rotten_eggs",
  "colour": "yellow_orange",
  "hardness": true,
  "iron_stains": true,
  "bacteria_concern": false,
  "has_test": false
}
```

### Response highlights

- `stack[]` — ordered stages (`sediment`, `iron`, `carbon`, `softener`, `uv`, `ro`) with `cost_low` / `cost_high` (CAD installed ranges)
- `summary`, `total_low`, `total_high`, `disclaimer`
- `quote_handoff` — ready-to-merge fields for the quote API
- `quote_endpoint` — `https://waterfilterhelp.ca/api/v1/quotes`

---

## Quote submission

### Consent

Before submitting, confirm: *"I'll send your name, phone, email, and property address to WaterFilterHelp.ca so a local water treatment contractor can contact you. OK?"*

### Required JSON fields

| Field | Description |
|-------|-------------|
| `consent` | Must be `true` after explicit user agreement |
| `service_type` | `water_softener`, `whole_home_filter`, `reverse_osmosis`, `iron_filter`, `uv`, `well_water`, `drinking_water`, `water_testing`, `repair`, `other` |
| `water_source` | `municipal`, `well`, or `unknown` |
| `urgency` | `asap`, `1_3_months`, `researching` |
| `name`, `email`, `phone` | Contact information |
| `address`, `city`, `province` | Property location (Canada) |

Optional: `problem` (array of `hard_water`, `iron`, `sulphur`, `staining`, `taste_odor`, `bacteria`, `sediment`, `other`), `postal_code`, `details`, `agent_source` (e.g. `chatgpt`). Legacy `issue_type` / `system_type` clients remain accepted through a compatibility adapter, but new agents should use the shared fields above.

**Do not** set `website` — it is a spam honeypot.

### Example request

```http
POST /api/v1/quotes?dry_run=true HTTP/1.1
Host: waterfilterhelp.ca
Content-Type: application/json

{
  "consent": true,
  "service_type": "well_water",
  "water_source": "well",
  "problem": ["sulphur", "iron", "staining"],
  "urgency": "1_3_months",
  "name": "Jane Doe",
  "email": "jane@example.com",
  "phone": "(416) 555-0100",
  "address": "123 King St W",
  "city": "Toronto",
  "province": "ON",
  "postal_code": "M5H 1A1",
  "details": "Water Problem Wizard results: rotten-egg smell, iron stains…",
  "agent_source": "chatgpt"
}
```

## Human-readable pages

- Wizard UI: `https://waterfilterhelp.ca/wizard`
- Guides hub: `https://waterfilterhelp.ca/guides`
- City hubs: `https://waterfilterhelp.ca/{province}/{city}` (e.g. `/on/toronto`)
- Service landers: `https://waterfilterhelp.ca/services/{slug}` (e.g. `/services/water-softeners`)
- Service × city: `https://waterfilterhelp.ca/on/toronto/water-softener-installation`

## Privacy

Contact data on quote submit is used only to match and notify a water treatment contractor. Wizard recommend calls should not include PII. See https://waterfilterhelp.ca for site terms.