# Poolside

Homeowner-first saltwater pool maintenance planner. `AGENTS.md` is a symlink to
this file.

## Product Rules

- Safety and water appearance outrank chemistry optimization.
- A balanced test must produce a $0 "No chemicals today" result.
- Use deterministic formulas for doses. LLMs may normalize inputs, explain, or
  ask follow-up questions, but may not invent chemistry.
- Require product-label or equipment-manual confirmation when product strength,
  manufacturer range, or buffering inputs materially affect the answer.
- Price corrections from homeowner-entered unit prices; do not assume a store
  markup.

## Testing

```bash
npm test
npm run typecheck
npm run lint
```

`tests/pool-plan.test.mjs` covers calculations, ordering, safety stops, and
invalid inputs. `tests/rendered-html.test.mjs` verifies the production worker
serves the homeowner workspace rather than the starter preview.

## Algorithm Notes

- Liquid chlorine: a gallon raises FC by approximately its strength percentage
  in ppm per 10,000 US gallons. Output is fluid ounces.
- Salt: ppm mass uses 8.34 pounds per US gallon of water and adjusts for stated
  product purity.
- Sodium bicarbonate: 1.4 pounds per 10 ppm TA per 10,000 US gallons.
- Dry stabilizer: 13 ounces per 10 ppm CYA per 10,000 US gallons.
- All calculated additions start at 50% of the mathematical correction. This is
  the rollback guardrail for volume uncertainty, test error, product age, and
  irreversible overdosing.
- Current routine targets are 4 ppm FC and 70 ppm TA. CYA defaults to 40 ppm
  and salt to 3,200 ppm, but both are homeowner-configured from the generator
  manual because manufacturers disagree.
- Invariant: cloudy or green water returns diagnosis and a swim stop, not
  routine balancer doses.
- Invariant: pH and calcium corrections never receive an invented generic dose.
- Tradeoff: the first version favors conservative staged work over the smallest
  number of homeowner visits.

## Local Tools

- `npm run dev`: local vinext preview
- `npm test`: production build plus all deterministic and rendered tests
- `npm run typecheck`: strict TypeScript check
- `npm run lint`: source lint