Update vision.md with full detailed content

docs/vision.md

@@ -1,28 +1,99 @@
-# SCADA for Small Water Systems - Vision
+# Product Vision Document – Water System Monitoring Platform
 
-**Status**: Draft
+**Status**: Draft (Pre-MVP)  
+**Date**: June 2026  
+**Scope**: V1 / Beta
 
-## Overview
+## 1. Core Vision & Philosophy
 
-A modern, affordable monitoring and alerting platform for small water systems that combines edge computing, hybrid AI, and thoughtful multi-tenancy design.
+- The product helps small water systems (particularly volunteer-run or lightly staffed systems) monitor their infrastructure, detect problems early, and maintain regulatory compliance.
+- The system is designed around **three layers of intelligence**:
+  1. Static thresholds (Yellow/Red)
+  2. Contextual / seasonal baselines
+  3. Relationship-based anomaly detection
+- The platform minimizes data egress by doing heavy summarization and intelligent monitoring locally on the edge device.
+- The long-term vision includes a specialized AI model trained on water system domain knowledge as a core differentiator.
 
-## Target Users
+## 2. Target Personas & Use Cases
 
-- Small water system board members (non-technical)
+The product targets three primary personas:
-- Licensed water system operators managing multiple systems
-- Homeowners with private wells serving multiple connections
 
-## Core Value Propositions
+| Persona                  | Technical Level | Primary Needs                                      | Dashboard Preference     |
+|--------------------------|------------------|----------------------------------------------------|--------------------------|
+| **Board Member / Owner** | Low             | Quick health status, alerts, confidence            | Basic (default)         |
+| **Licensed Operator**    | High            | Operational visibility, configuration, multi-system management | Advanced (default)      |
+| **Regulatory / Compliance** | Medium       | Automated reporting, record keeping, audit readiness | Basic + Compliance views |
 
-- Significantly lower ongoing data costs through intelligent local processing
+**Key Insight**: Licensed operators are expected to be the primary go-to-market entry point. They will often install and configure the system on behalf of their clients.
-- Usable by both technical and non-technical stakeholders
-- Proactive alerting instead of reactive monitoring
-- Designed specifically for the economic realities of small systems
 
-## Key Architectural Principles
+## 3. Multi-Tenancy & Access Control (MVP)
 
-- Low-egress by default
+- **Owner** → One water system (1:1 relationship)
-- Hybrid AI (edge + cloud)
+- **Operator** → Can manage multiple water systems
-- Strong multi-tenancy with clear RBAC
+- **Water System** → One primary Operator (1:1)
-- Tamper-evident field hardware
+- **Field Tech** → Tied to an Operator; inherits access to the Operator’s systems (with potential future granularity)
-- Practical reliability over theoretical perfection
+- Roles for MVP:
+  - **Owner**: Full access including all account/billing management
+  - **Operator**: High access (everything except billing/account management)
+  - **User / Field Tech**: Lower privileged (mostly read-only, can dismiss alerts)
+- Owners and Operators can both act on alerts.
+- Field Techs will have a simple boolean for temporary elevated permissions during setup/configuration (MVP).
+
+## 4. Alert System (MVP)
+
+### High-Level Lifecycle
+- **Created** → **Managed** → **Resolved**
+
+### Alert Creation
+- Primary method: AI-assisted interview during sensor onboarding **[MVP]**
+- Secondary method: Simple manual alert editor **[MVP]**
+- Every alert includes:
+  - Title
+  - Description
+  - Troubleshooting / Next Steps (human-readable guidance)
+- Alerts support chronological annotations/notes with authorship **[MVP]**
+
+### Alert Behavior
+- Two severity levels: **Critical (Red)** and **Warning (Yellow)** **[MVP]**
+- Alerts are visible to both Owner and Operator **[MVP]**
+- Both roles can act on alerts (Dismiss/Acknowledge or Mark as Fixed) **[MVP]**
+- Contextual telemetry relationships are defined at alert creation time **[MVP]**
+- Deep links provide additional context when needed **[MVP]**
+
+**Post-MVP**: External notifications (email/SMS), advanced suppression logic, per-user notification preferences.
+
+## 5. Dashboard Strategy (MVP)
+
+### Two Dashboard Modes
+- **Basic Dashboard** (10,000 ft view) **[MVP]**
+  - Designed primarily for Owners/Board Members
+  - Shows overall system health at a glance
+  - Uses **Monitored Objects** as the primary building block
+  - Fixed top section with universal system metrics
+  - Lower section contains cards for Monitored Objects
+
+- **Advanced Dashboard** (2,000 ft view) **[MVP]**
+  - Designed primarily for Operators
+  - More data-dense with trends and deeper visibility
+
+Users can override their default dashboard preference.
+
+### Monitored Objects (Key Concept) **[MVP]**
+- A **Monitored Object** is a logical grouping of related sensors.
+- This is a first-class concept in the system.
+- The Basic Dashboard primarily displays Monitored Objects rather than raw individual sensors.
+
+**Post-MVP**: More advanced dashboard customization, widget system, and complex visualizations.
+
+## 6. Data Modeling Concepts
+
+Two important first-class concepts:
+
+1. **Monitored Objects**
+   - Logical groupings of sensors
+   - Used for dashboard organization and visualization
+
+2. **Contextual Telemetry Relationships**
+   - Defined at alert creation time (with AI assistance)
+   - Used to provide relevant surrounding data when an alert fires
+   - Static per alert rule