Make stats DSL primary with highlighted editor, completion and live diagnostics

README.md

@@ -49,17 +49,37 @@ migrations. SQLite and deployed PostgreSQL migrations have been verified; see
 
 ### Exploring running stats
 
-Open **Stats** for the guided question builder: select up to two metrics, filter
-by distance and run-average heart rate, group by week or month, and compare an
-equally long preceding period. Periods use your account timezone and end today
-unless you choose an end date. The explorer covers whole runs and uses persisted
-summaries without loading recording samples. Metric definitions and the number
-of runs with usable data appear alongside each result.
+Open **Stats** for the query editor with syntax highlighting, contextual
+autocomplete, and live validation from the execution parser. Use **Ctrl+Space**
+for suggestions and **Ctrl/Cmd+Enter** to run. **Format** normalizes a valid query;
+invalid drafts retain the displayed results. Guided controls and the language
+reference remain available below the editor. CodeMirror 5.65.20 and its completion
+addon are vendored locally under the MIT license; the editor needs no CDN access.
 
-**Show query** exposes the same question as an editable DSL. Applying it updates
-the guided controls. Select a chart point or use the evidence period picker to
-inspect contributing runs. Save named views in this browser, or bookmark the
-results URL; saved views follow relative dates as new runs are imported.
+Queries support up to six metrics, numeric comparisons and inclusive ranges,
+case-insensitive title search, `has`/`missing` sensor filters, daily/weekly/monthly
+grouping, and evidence sorting. Periods use your account timezone: rolling days,
+weeks, calendar months, or inclusive explicit dates. Comparisons cover an equally
+long preceding period. Pace filters accept values such as `5:30 /km`; duration
+accepts `h`, `min`, or `s`, and distance accepts `km` or `m`.
+
+```text
+runs
+  during last 6 months
+  where distance between 8 and 20 km
+  and pace <= 5:30 /km
+  and has cadence
+  summarize pace, heart_rate, cadence
+  by month
+  compare previous period
+  sort by pace asc
+```
+
+The explorer covers whole runs and uses persisted summaries without loading
+recording samples. Metric definitions and usable-run coverage appear with each
+result. Select a chart point or the evidence period picker to inspect contributing
+runs. Save named views in this browser, or bookmark the results URL; relative
+queries follow the calendar as new runs are imported.
 
 ### Bringing in more activities