# Poolside

Poolside turns homeowner-supplied pool readings into a safe, ordered,
cost-conscious maintenance plan. The first version is intentionally
deterministic: it accepts readings from any test source, recommends only the
next measured action, prices the staged dose with the homeowner's own shelf
prices, and explains why and when to retest.

## Product Position

The market already has capable pieces:

- PoolMath provides calculators, logging, maintenance tracking, and a bleach
  price calculator.
- WaterGuru and iopool pair proprietary hardware with automated readings and
  in-app recommendations.
- Taylor sureTREAT provides free brand-oriented treatment calculations.

Poolside's wedge is not "LLM chemistry." It is an independent decision layer:

1. Accept readings from a drop kit, strip, store, or sensor.
2. Treat water appearance as a separate safety signal.
3. Order corrections so the homeowner does not stack chemicals.
4. Split reversible additions into a first dose and a retest checkpoint.
5. Show $0 when no product is needed.
6. Teach the reason inside the action, not in a separate course.

See [docs/research.md](docs/research.md) for the competitor and safety research.

## First Version

- One saltwater, plaster pool profile
- Homeowner-entered CYA and salt targets from the generator manual
- Manual entry for FC, pH, TA, CYA, CH, and salt
- Clear, cloudy, or green appearance check
- Deterministic safety and treatment plan
- Staged liquid chlorine, baking soda, stabilizer, and salt calculations
- Product-label or acid-demand stops where generic pH dosing would be false
  precision
- Homeowner-entered unit prices and estimated first-dose cost
- Device-local test history
- Contextual parameter education

The app does not yet read test photos, integrate sensor APIs, diagnose equipment,
or autonomously control a pump, salt cell, or chemical feeder.

## Optimization Contract

**Real objective metric:** monthly maintenance cost per verified swim-ready day,
while maintaining zero preventable unsafe-swim recommendations. Cost alone is a
bad objective because the cheapest pool is an untreated pool.

**Current proxy:** planned chemical spend from staged first doses and the count
of test records classified swim-ready. It proxies actual spend and safe
availability, but does not yet prove either; actual purchases, completed doses,
and follow-up readings remain instrumentation gaps.

1. **Measurement mechanism:** locally stored test results, generated plan cost,
   safety classification, completed actions, and future follow-up readings.
2. **Action space:** recommend no action, cleaning/circulation checks, a staged
   commodity-chemical dose, a retest, or escalation.
3. **Stopping condition:** readings and appearance are acceptable, or a safety
   stop/escalation blocks further generic treatment. Each dose also stops at
   50% until the specified retest.
4. **Rollback / guardrail:** never mix products, never infer an acid or calcium
   dose without sufficient product-specific inputs, never recommend routine
   balancers for unexplained cloudy/green water, and defer to labels and
   equipment manuals.
5. **Objective metric:** the cost-per-verified-ready-day metric above. A future
   autonomous tier must not launch until actual outcome measurement replaces the
   current proxy.

## Agentic Version

### Tier 1: Simple Automation

The current deterministic calculator. The homeowner enters readings, reviews
the plan, performs one action, and retests.

### Tier 2: Semi-Agentic

Normalize readings from a sensor API, test-kit photo, or pool-store report; ask
for missing evidence; compare current and prior trends; propose a plan; require
the homeowner to confirm each physical action. Store the evidence and outcome.

### Tier 3: Fully Agentic

Adjust salt-cell output or pump runtime only for a compatible system with signed
commands, explicit operating limits, verified recent sensors, and a manual
circuit breaker. Optimize cost per verified swim-ready day, stop on stable
readings or diminishing improvement, and roll back to the last known-safe
setting when the metric degrades. Chemical additions remain human-confirmed.

## Development

```bash
npm install
npm run dev
npm test
npm run typecheck
npm run lint
```

The app stores pool preferences, unit prices, and up to 20 recent tests in the
browser on the current device.