@dataworks-technology/cli 1.5.0 → 1.6.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dataworks-technology/cli",
-  "version": "1.5.0",
+  "version": "1.6.1",
   "description": "The official command-line interface for the Dataworks Data Engine",
   "type": "module",
   "license": "MIT",
@@ -22,7 +22,6 @@
     "dist",
     "plugins",
     "schema",
-    "skills",
     "oclif.manifest.json",
     "README.md",
     "LICENSE"

package/plugins/dataworks/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "dataworks",
-  "version": "1.5.0",
-  "description": "Query athlete metrics from Dataworks using the authenticated local CLI session.",
+  "version": "1.6.1",
+  "description": "Query Dataworks athlete metrics and operate the Dataworks platform using the authenticated local CLI session.",
   "author": { "name": "Dataworks Technology" },
   "homepage": "https://github.com/Dataworks-Technology/Dataworks-CLI",
   "repository": "https://github.com/Dataworks-Technology/Dataworks-CLI",

package/plugins/dataworks/.codex-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "dataworks",
-  "version": "1.5.0",
-  "description": "Query athlete metrics from Dataworks using the authenticated local CLI session.",
+  "version": "1.6.1",
+  "description": "Query Dataworks athlete metrics and operate the Dataworks platform using the authenticated local CLI session.",
   "author": { "name": "Dataworks Technology", "url": "https://dataworks.live/" },
   "homepage": "https://github.com/Dataworks-Technology/Dataworks-CLI",
   "repository": "https://github.com/Dataworks-Technology/Dataworks-CLI",
@@ -12,7 +12,7 @@
   "interface": {
     "displayName": "Dataworks",
     "shortDescription": "Query athlete metrics safely",
-    "longDescription": "Resolve athletes and return normalized GPS, heart-rate, and other Dataworks metric values through one read-only tool.",
+    "longDescription": "Resolve athletes and events, return normalized metric values and server-side aggregates through read-only tools, and drive the full Dataworks CLI for everything else.",
     "developerName": "Dataworks Technology",
     "category": "Data",
     "capabilities": ["Read"],

package/{skills → plugins/dataworks/skills}/dataworks-cli/SKILL.md

@@ -5,11 +5,16 @@ description: Route operational requests to inspect, query, create, update, delet
 
 # Dataworks CLI
 
-Use `dw` as the operational interface for Dataworks actions. When the
-`query_metrics` tool is available, use it for historical athlete metric requests;
-it is the read-only, CLI-authenticated interface over Data Explorer. Do not call a
-Dataworks HTTP or GraphQL endpoint directly, or use an SDK instead, when the CLI
-or this tool can perform the action.
+Use `dw` as the operational interface for Dataworks actions. Do not call a
+Dataworks HTTP or GraphQL endpoint directly, or use an SDK, when the CLI or the
+Dataworks MCP tools can perform the action.
+
+The MCP tools, when available, own a narrow slice: `query_metrics` for historical
+metric values and aggregates, and `list_athletes` / `list_events` for resolving
+the IDs those queries need. Everything else is the CLI's job — full entity
+records, teams, datasets, participants, ingestion, subscriptions, and every
+create, update or delete. Use the CLI for those directly; it is not a fallback
+for when a tool fails.
 
 If a request needs `query_metrics` but the tool is unavailable, tell the user to
 run `dw agents install` once, then start a new Codex thread or run
@@ -23,7 +28,9 @@ the restarted or reloaded agent exposes the tool.
 2. Run `dw commands --json` to discover the installed command contract.
 3. Run `dw <command> --help` before constructing the exact call.
 4. Prefer the narrowest matching command:
-   - Historical athlete metrics: `query_metrics` when available
+   - Historical metric values or aggregates: `query_metrics` when available
+   - An athlete or event ID for such a query: `list_athletes` / `list_events`
+   - A full athlete, event, dataset or participant record: `dw data ...`
    - Data Engine entities: `dw data ...`
    - Authentication and session state: `dw auth ...`
    - Tenant discovery and persistence: `dw tenant list` and `dw tenant select ...`

package/plugins/dataworks/skills/query-dataworks-metrics/SKILL.md

@@ -9,7 +9,18 @@ Three read-only tools use the current authenticated `dw` session and tenant:
 
 - `query_metrics` — metric values, scoped to an athlete, an event, or a datasource.
 - `list_athletes` — find an athlete ID, or confirm someone is not in this tenant.
-- `list_events` — find an event ID for a race.
+- `list_events` — find an event ID for a race, by name.
+
+These cover historical metrics and the IDs needed to ask for them, and nothing
+else. They are deliberately narrow: `list_athletes` returns only an ID, a name
+and an external ID. For anything beyond that — an athlete's full record, teams,
+datasets, participants, events as entities, ingestion, live subscriptions, or any
+create, update or delete — use the `dw` CLI, which covers the whole Data Engine
+API. See the `dataworks-cli` skill, and run `dw commands --json` to discover the
+exact command rather than exploring with `dw help`.
+
+Reach for the CLI as readily as these tools; it is the same authenticated
+session, not a fallback.
 
 If `query_metrics` is unavailable, tell the user to run `dw agents install`
 once in their terminal, then start a new Codex thread or run `/reload-plugins`
@@ -25,6 +36,10 @@ in Claude Code. Do not substitute raw GraphQL or guess that setup succeeded.
 - For a question about a race or feed — "the latest heart rate at T100 San
   Francisco" — omit the athlete entirely and pass `event_id`. Do not invent an
   athlete to satisfy the call. Rows still carry `athlete_id` per value.
+- To compare people, pass `athlete_ids` rather than one query each; combined
+  with `aggregate` it returns one value per athlete. Use `event_ids` likewise to
+  span a series of races. Resolve names to IDs with `list_athletes` first, and
+  note an athlete with no data simply has no rows rather than an error.
 - Map the user's wording onto a canonical metric name from the catalogue below.
   Case, spaces, hyphens and underscores are ignored, so "Heart Rate" resolves to
   `heartrate`. Do not invent a metric name.
@@ -36,6 +51,19 @@ in Claude Code. Do not substitute raw GraphQL or guess that setup succeeded.
   pattern, or a row count is a guess: say you could not resolve it instead.
 - For a genuinely custom metric absent from the catalogue, pass its exact name
   and an explicit `metric_category`.
+- Rows carry every column the metric's category provides. Heart rate and power
+  add rolling `max`, `min`, `avg` and a seven-zone breakdown, all under `extra`
+  on each row — read zones from there rather than computing them.
+- To find high or low readings, pass `min_value` or `max_value` rather than
+  fetching everything and filtering; the server applies the bound.
+- To rank by value rather than recency, pass `order_by: "current"`. It defaults
+  to `timestamp`, and `order` controls the direction either way.
+- For a maximum, minimum, average, sum, or count, pass `aggregate` instead of
+  fetching rows and computing it yourself. The server aggregates over every
+  matching sample; taking a maximum over returned rows only covers the rows
+  `limit` allowed through. Results arrive in `aggregate.groups` and `rows` is
+  empty. `group_by` defaults to `athletepublicid`, so an event-scoped aggregate
+  returns one value per athlete; pass `eventpublicid` for one value per event.
 
 ## Metric catalogue
 
@@ -68,6 +96,17 @@ Haigh"`, `metric: "GPS"`, `limit: 30`, `order: "newest"`.
 - “Latest 10 heart rate values for T100 San Francisco” → `list_events` with
   `search: "T100 San Francisco"` to get the ID, then `query_metrics` with
   `event_id: <that ID>`, `metric: "heartrate"`, `limit: 10`, and no athlete.
+- “Hayden Wilde's maximum heart rate” → `query_metrics` with
+  `athlete_name: "Hayden Wilde"`, `metric: "heartrate"`, `aggregate: "max"`.
+  Read the answer from `aggregate.groups`; do not fetch rows and compare them.
+- “When was Sam above 180bpm?” → `metric: "heartrate"`, `min_value: 180`.
+- “Sam's highest heart rate readings” → `metric: "heartrate"`,
+  `order_by: "current"`, which ranks by value instead of recency.
+- “Sam's heart rate zones” → an ordinary query; read `extra.z1_percentage`
+  through `extra.z7_percentage` from any returned row.
+- “Compare Hayden and Sam's peak heart rate” → `list_athletes` for both IDs,
+  then one call with `athlete_ids: [<both>]`, `metric: "heartrate"`,
+  `aggregate: "max"`; each athlete appears once in `aggregate.groups`.
 
 ## Handle results
 
@@ -76,8 +115,10 @@ environment, tenant, canonical metric, order, and returned count. GPS rows inclu
 decoded `position.latitude` and `position.longitude`; heart-rate values are
 numeric with unit `bpm` when the source value is valid.
 
-Every error carries a `recovery` field. Follow it rather than improvising, and
-never fall back to raw GraphQL or `dw data ...` to work around a failure.
+Every error carries a `recovery` field. Follow it rather than improvising. Do not
+reach for raw GraphQL to work around a metric failure — but the `dw` CLI is a
+first-class route for anything these tools do not cover, and the `dataworks-cli`
+skill explains how to drive it.
 
 - `ATHLETE_AMBIGUOUS` — present the candidates and ask the user to choose.
 - `ATHLETE_NOT_FOUND` — the athlete is not in this tenant. Do not retry with
@@ -86,9 +127,10 @@ never fall back to raw GraphQL or `dw data ...` to work around a failure.
   `dataset_datasource_id`.
 - `METRIC_CATEGORY_REQUIRED` — retry with one of the returned `suggestions`.
 
-If `list_events` returns `unavailable: true`, the event API returned nothing for
-this session. That is a permissions problem, not proof that no events exist.
-Report it and stop; do not identify an event by any other route. For `AUTH_REQUIRED` or `TENANT_REQUIRED`, follow the recovery command
+`list_events` reports where its results came from in `source`: the events API,
+or each dataset's event relation. Either is authoritative. Only when
+`unavailable: true` did both routes yield nothing — report that and stop rather
+than identifying an event some other way. For `AUTH_REQUIRED` or `TENANT_REQUIRED`, follow the recovery command
 in the error and retry. For `METRIC_CATEGORY_REQUIRED`, the error's `suggestions`
 list the closest canonical names — retry with one rather than asking the user to
 spell the metric. Never expose credentials or session material.