catence 0.2.1-beta.6 → 0.2.1-beta.8

package/README.md

@@ -12,7 +12,7 @@ As a context, I'm both an endurance athlete and a data junkie. I already got a c
 
 - Garmin, Intervals.icu, and Strava ingestion with source-aware normalization.
 - Read-only MCP tools, plus explicitly named, lock-guarded write tools for Strava hydration and detached syncs.
-- One shared Catence agent can serve several isolated athlete stores. Every personal-data MCP call names an `athleteId`; Catence never silently combines athletes.
+- One Catence MCP server serves several athlete stores side by side. Every personal-data MCP call names an `athleteId`; tools act only on that store and never merge athletes implicitly. The MCP server does not authenticate callers — it trusts the `athleteId` each call names.
 - A password-protected Chainlit Console with an authenticated dashboard, a data-sync button with live progress, and in-app model management.
 - A generated demo catalog for safe evaluation in Glama, desktop MCP clients, or local development.
 
@@ -57,7 +57,7 @@ Start the stdio MCP server:
 catence
 ```
 
-An agent first calls `list_athletes`, then includes `athleteId` with every data tool. This is intentional: a shared agent may access the stores you configured, but no tool implicitly aggregates or crosses between athletes.
+An agent first calls `list_athletes`, then includes `athleteId` with every data tool. Tools act only on the named athlete store and never merge athletes implicitly. The MCP server does not authenticate callers — it trusts the `athleteId` each call names — so keep it on loopback or restrict it at the network layer (see [MCP clients and HTTP](#mcp-clients-and-http)).
 
 ### Add another athlete
 

package/dist/contracts/release.d.ts

@@ -3,7 +3,7 @@
  * Keep these values synchronized with release/manifest.json; release checks
  * deliberately reject drift before a package can be published.
  */
-export declare const CATENCE_RUNTIME_VERSION = "0.2.1-beta.6";
+export declare const CATENCE_RUNTIME_VERSION = "0.2.1-beta.8";
 export declare const CATENCE_PROTOCOL_VERSION = 1;
 export type CatenceRuntimeCapabilities = {
     mcp: true;

package/dist/contracts/release.js

@@ -3,7 +3,7 @@
  * Keep these values synchronized with release/manifest.json; release checks
  * deliberately reject drift before a package can be published.
  */
-export const CATENCE_RUNTIME_VERSION = '0.2.1-beta.6';
+export const CATENCE_RUNTIME_VERSION = '0.2.1-beta.8';
 export const CATENCE_PROTOCOL_VERSION = 1;
 export function catenceRuntimeHealth() {
     return {

package/dist/contracts/runtime.d.ts

@@ -8,4 +8,8 @@ export type CatencePaths = {
     config: string;
     secrets: string;
     lock: string;
+    /** Athlete-authored markdown document shared by the athlete and the agent. */
+    athleteFile: string;
+    /** Rolling snapshots of prior athlete-file content. Created on first write. */
+    athleteFileHistory: string;
 };

package/dist/core/query/catalog.d.ts

@@ -1,4 +1,4 @@
-export type DatasetName = 'activities' | 'canonical_activities' | 'canonical_activity_facts' | 'activity_sources' | 'activity_summaries' | 'activity_intervals' | 'swim_lengths' | 'swim_sets' | 'activity_quality_flags' | 'daily_metrics' | 'daily_health' | 'training_metrics' | 'training_metric_observations' | 'wellness_samples' | 'health_sessions' | 'power_bests' | 'activity_decoupling' | 'nutrition_days' | 'nutrition_items' | 'events' | 'workouts' | 'workout_documents' | 'training_plans' | 'routes' | 'gear' | 'devices' | 'goals' | 'achievements' | 'messages' | 'source_entities' | 'activity_samples' | 'activity_links' | 'activity_segments' | 'segments' | 'segment_effort_history' | 'strava_gear' | 'course_geometry';
+export type DatasetName = 'activities' | 'canonical_activities' | 'canonical_activity_facts' | 'activity_sources' | 'activity_summaries' | 'activity_intervals' | 'swim_lengths' | 'swim_sets' | 'activity_quality_flags' | 'daily_metrics' | 'daily_health' | 'training_metrics' | 'training_metric_observations' | 'wellness_samples' | 'health_sessions' | 'power_bests' | 'activity_decoupling' | 'run_dynamics' | 'nutrition_days' | 'nutrition_items' | 'events' | 'workouts' | 'workout_documents' | 'training_plans' | 'routes' | 'gear' | 'devices' | 'goals' | 'achievements' | 'messages' | 'source_entities' | 'activity_samples' | 'activity_links' | 'activity_segments' | 'segments' | 'segment_effort_history' | 'strava_gear' | 'course_geometry';
 export type CatalogColumn = {
     name: string;
     type: string;

package/dist/core/query/catalog.js

@@ -1,4 +1,6 @@
 const column = (name, type, options = {}) => ({ name, type, ...options });
+const PAYLOAD_JSON_DESCRIPTION = 'Raw provider object retained for identifier and string lookups; its structure varies by provider and endpoint and is not a stable schema.';
+const EXTENSION_JSON_DESCRIPTION = 'Provider extension object retained alongside payload_json for identifier and string lookups; its structure varies by provider and endpoint.';
 export const DATASET_CATALOG = {
     activities: {
         name: 'activities', relation: 'activities', description: 'Logical activities linked by provider IDs, unique high-confidence fuzzy evidence, or an explicit manual correction.', dateColumn: 'started_at_utc', provenanceColumns: ['activity_id', 'link_state'], permittedGroupings: ['sport', 'link_state'],
@@ -17,8 +19,8 @@ export const DATASET_CATALOG = {
         columns: [column('activity_source_id', 'VARCHAR', { filterable: true, groupable: true }), column('activity_id', 'VARCHAR', { filterable: true, groupable: true }), column('provider', 'VARCHAR', { filterable: true, groupable: true }), column('remote_activity_id', 'VARCHAR', { filterable: true }), column('external_id', 'VARCHAR', { filterable: true }), column('raw_object_hash', 'VARCHAR')],
     },
     activity_summaries: {
-        name: 'activity_summaries', relation: 'activity_summary_facts', description: 'Provider activity summary metrics with activity and timestamp provenance. A NULL avg_power does not mean no power; FIT-derived power is in power_best_facts. Prefer power_coverage_report or read_series over inferring absence. NULL avg_power here does not mean no power; running/cycling power is in power_best_facts (FIT-derived). Use power_coverage_report / read_series.', dateColumn: 'started_at_utc', provenanceColumns: ['activity_source_id', 'activity_id', 'provider', 'raw_object_hash'], permittedGroupings: ['provider', 'sport'],
-        columns: [column('activity_source_id', 'VARCHAR', { filterable: true, groupable: true }), column('activity_id', 'VARCHAR', { filterable: true, groupable: true }), column('provider', 'VARCHAR', { filterable: true, groupable: true }), column('started_at_utc', 'TIMESTAMPTZ', { filterable: true }), column('sport', 'VARCHAR', { filterable: true, groupable: true }), column('name', 'VARCHAR', { filterable: true }), column('distance_m', 'DOUBLE', { unit: 'm', metric: true }), column('moving_s', 'DOUBLE', { unit: 's', metric: true }), column('elapsed_s', 'DOUBLE', { unit: 's', metric: true }), column('elevation_gain_m', 'DOUBLE', { unit: 'm', metric: true }), column('calories', 'DOUBLE', { unit: 'kcal', metric: true }), column('avg_hr', 'DOUBLE', { unit: 'bpm', metric: true }), column('max_hr', 'DOUBLE', { unit: 'bpm', metric: true }), column('avg_power', 'DOUBLE', { unit: 'W', metric: true }), column('weighted_power', 'DOUBLE', { unit: 'W', metric: true }), column('avg_cadence', 'DOUBLE', { unit: 'rpm', metric: true }), column('training_load', 'DOUBLE', { metric: true }), column('rpe', 'DOUBLE', { metric: true }), column('feel', 'DOUBLE', { metric: true })],
+        name: 'activity_summaries', relation: 'activity_summary_facts', description: 'Provider activity summary metrics with activity and timestamp provenance. A NULL avg_power does not mean no power; FIT-derived power is in power_best_facts. Prefer power_coverage_report or read_series over inferring absence. Running form metrics (vertical oscillation, ground contact time, flight time, stride length, vertical ratio, cadence) are not columns here; use the run_dynamics dataset for those. metrics_json is the source-specific provider payload and its keys vary by provider: single Garmin activities carry flat keys (for example avgVerticalOscillation), while multisport legs nest the same values under summaryDTO.*. Never treat an absent key as a zero value.', dateColumn: 'started_at_utc', provenanceColumns: ['activity_source_id', 'activity_id', 'provider', 'raw_object_hash'], permittedGroupings: ['provider', 'sport'],
+        columns: [column('activity_source_id', 'VARCHAR', { filterable: true, groupable: true }), column('activity_id', 'VARCHAR', { filterable: true, groupable: true }), column('provider', 'VARCHAR', { filterable: true, groupable: true }), column('started_at_utc', 'TIMESTAMPTZ', { filterable: true }), column('sport', 'VARCHAR', { filterable: true, groupable: true }), column('name', 'VARCHAR', { filterable: true }), column('distance_m', 'DOUBLE', { unit: 'm', metric: true }), column('moving_s', 'DOUBLE', { unit: 's', metric: true }), column('elapsed_s', 'DOUBLE', { unit: 's', metric: true }), column('elevation_gain_m', 'DOUBLE', { unit: 'm', metric: true }), column('calories', 'DOUBLE', { unit: 'kcal', metric: true }), column('avg_hr', 'DOUBLE', { unit: 'bpm', metric: true }), column('max_hr', 'DOUBLE', { unit: 'bpm', metric: true }), column('avg_power', 'DOUBLE', { unit: 'W', metric: true }), column('weighted_power', 'DOUBLE', { unit: 'W', metric: true }), column('avg_cadence', 'DOUBLE', { unit: 'rpm', metric: true }), column('training_load', 'DOUBLE', { metric: true }), column('rpe', 'DOUBLE', { metric: true }), column('feel', 'DOUBLE', { metric: true }), column('metrics_json', 'JSON', { description: 'Source-specific provider payload; keys vary by provider and are not a stable schema. Flat keys for single activities; multisport legs nest values under summaryDTO.*. Use run_dynamics for normalized running form metrics.' })],
     },
     activity_intervals: {
         name: 'activity_intervals', relation: 'activity_interval_facts', description: 'Structured intervals attached to an activity source.', dateColumn: 'started_at_utc', provenanceColumns: ['activity_source_id', 'activity_id', 'provider'], permittedGroupings: ['provider', 'sport', 'label'],
@@ -54,7 +56,7 @@ export const DATASET_CATALOG = {
     },
     health_sessions: {
         name: 'health_sessions', relation: 'health_sessions', description: 'Garmin sleep, nap, daily-event, and Body Battery event records with their source payload retained.', dateColumn: 'occurred_on', provenanceColumns: ['provider', 'source_type', 'source_remote_id', 'raw_object_hash'], permittedGroupings: ['provider', 'session_type', 'source_type'],
-        columns: [column('session_id', 'VARCHAR', { filterable: true }), column('provider', 'VARCHAR', { filterable: true, groupable: true }), column('session_type', 'VARCHAR', { filterable: true, groupable: true }), column('occurred_on', 'DATE', { filterable: true, groupable: true }), column('started_at', 'TIMESTAMPTZ', { filterable: true }), column('ended_at', 'TIMESTAMPTZ', { filterable: true }), column('source_type', 'VARCHAR', { filterable: true, groupable: true }), column('source_remote_id', 'VARCHAR', { filterable: true }), column('payload_json', 'JSON'), column('raw_object_hash', 'VARCHAR')],
+        columns: [column('session_id', 'VARCHAR', { filterable: true }), column('provider', 'VARCHAR', { filterable: true, groupable: true }), column('session_type', 'VARCHAR', { filterable: true, groupable: true }), column('occurred_on', 'DATE', { filterable: true, groupable: true }), column('started_at', 'TIMESTAMPTZ', { filterable: true }), column('ended_at', 'TIMESTAMPTZ', { filterable: true }), column('source_type', 'VARCHAR', { filterable: true, groupable: true }), column('source_remote_id', 'VARCHAR', { filterable: true }), column('payload_json', 'JSON', { description: PAYLOAD_JSON_DESCRIPTION }), column('raw_object_hash', 'VARCHAR')],
     },
     power_bests: {
         name: 'power_bests', relation: 'power_best_facts', description: 'Power-duration bests derived from Garmin FIT streams; they are labelled derived while retaining the Garmin activity provenance.', dateColumn: 'started_at_utc', provenanceColumns: ['provider', 'activity_source_id', 'source_type', 'raw_object_hash'], permittedGroupings: ['provider', 'sport', 'duration_s', 'source_type'],
@@ -64,19 +66,23 @@ export const DATASET_CATALOG = {
         name: 'activity_decoupling', relation: 'activity_decoupling_facts', description: 'Persisted per-activity aerobic decoupling (Pa:Hr, pct) and grade-adjusted pace (s/km) with provenance. source_type provider means the provider payload supplied the value (authoritative); derived values are tagged locally. Values never overwrite provider output. Not a physiological performance model.', dateColumn: 'started_at_utc', provenanceColumns: ['provider', 'activity_source_id', 'raw_object_hash'], permittedGroupings: ['provider', 'sport', 'metric', 'source_type'],
         columns: [column('provider', 'VARCHAR', { filterable: true, groupable: true }), column('activity_source_id', 'VARCHAR', { filterable: true, groupable: true }), column('sport', 'VARCHAR', { filterable: true, groupable: true }), column('started_at_utc', 'TIMESTAMPTZ', { filterable: true }), column('metric', 'VARCHAR', { filterable: true, groupable: true }), column('value_number', 'DOUBLE', { metric: true }), column('unit', 'VARCHAR', { filterable: true, groupable: true }), column('source_type', 'VARCHAR', { filterable: true, groupable: true }), column('raw_object_hash', 'VARCHAR')],
     },
+    run_dynamics: {
+        name: 'run_dynamics', relation: 'run_dynamics', description: 'Provider-normalized running form metrics per activity source: vertical oscillation (cm), ground contact time (ms), flight time (ms), stride length (cm), vertical ratio (%), and running cadence (spm). Only activities with at least one reported value have a row, and a null column means the provider did not report that metric; never treat null as zero or derive it from other metrics. Values come from the provider payload (flat keys for single activities, summaryDTO for multisport legs) and never overwrite provider output. Rows are per provider source and carry activity_id; when an activity is linked across providers, filter provider or group by activity_id before averaging.', dateColumn: 'started_at_utc', provenanceColumns: ['provider', 'activity_source_id', 'raw_object_hash'], permittedGroupings: ['provider', 'sport', 'source_type'],
+        columns: [column('provider', 'VARCHAR', { filterable: true, groupable: true }), column('activity_source_id', 'VARCHAR', { filterable: true, groupable: true }), column('activity_id', 'VARCHAR', { filterable: true, groupable: true }), column('sport', 'VARCHAR', { filterable: true, groupable: true }), column('started_at_utc', 'TIMESTAMPTZ', { filterable: true }), column('name', 'VARCHAR', { filterable: true }), column('vertical_oscillation_cm', 'DOUBLE', { unit: 'cm', metric: true }), column('ground_contact_time_ms', 'DOUBLE', { unit: 'ms', metric: true }), column('flight_time_ms', 'DOUBLE', { unit: 'ms', metric: true }), column('stride_length_cm', 'DOUBLE', { unit: 'cm', metric: true }), column('vertical_ratio_pct', 'DOUBLE', { unit: '%', metric: true }), column('cadence_spm', 'DOUBLE', { unit: 'spm', metric: true }), column('source_type', 'VARCHAR', { filterable: true, groupable: true }), column('raw_object_hash', 'VARCHAR')],
+    },
     nutrition_days: {
-        name: 'nutrition_days', relation: 'nutrition_days', description: 'Daily nutrition totals, never a replacement for the item-level food log.', dateColumn: 'nutrition_date', provenanceColumns: ['provider', 'raw_object_hash'], permittedGroupings: ['provider'],
-        columns: [column('provider', 'VARCHAR', { filterable: true, groupable: true }), column('nutrition_date', 'DATE', { filterable: true, groupable: true }), column('energy_kcal', 'DOUBLE', { unit: 'kcal', metric: true }), column('carbohydrates_g', 'DOUBLE', { unit: 'g', metric: true }), column('protein_g', 'DOUBLE', { unit: 'g', metric: true }), column('fat_g', 'DOUBLE', { unit: 'g', metric: true }), column('hydration_ml', 'DOUBLE', { unit: 'ml', metric: true }), column('raw_object_hash', 'VARCHAR')],
+        name: 'nutrition_days', relation: 'nutrition_days', description: 'Daily nutrition totals, never a replacement for the item-level food log. metrics_json is the source-specific provider payload; its keys vary by provider and are not a stable schema.', dateColumn: 'nutrition_date', provenanceColumns: ['provider', 'raw_object_hash'], permittedGroupings: ['provider'],
+        columns: [column('provider', 'VARCHAR', { filterable: true, groupable: true }), column('nutrition_date', 'DATE', { filterable: true, groupable: true }), column('energy_kcal', 'DOUBLE', { unit: 'kcal', metric: true }), column('carbohydrates_g', 'DOUBLE', { unit: 'g', metric: true }), column('protein_g', 'DOUBLE', { unit: 'g', metric: true }), column('fat_g', 'DOUBLE', { unit: 'g', metric: true }), column('hydration_ml', 'DOUBLE', { unit: 'ml', metric: true }), column('metrics_json', 'JSON', { description: 'Source-specific provider payload; keys vary by provider and are not a stable schema.' }), column('raw_object_hash', 'VARCHAR')],
     },
     nutrition_items: {
         name: 'nutrition_items', relation: 'nutrition_items', description: 'Meal and food-item detail retained from the provider.', dateColumn: 'nutrition_date', provenanceColumns: ['provider', 'remote_item_id', 'raw_object_hash'], permittedGroupings: ['provider', 'meal', 'food_name'],
-        columns: [column('provider', 'VARCHAR', { filterable: true, groupable: true }), column('remote_item_id', 'VARCHAR', { filterable: true }), column('nutrition_date', 'DATE', { filterable: true, groupable: true }), column('meal', 'VARCHAR', { filterable: true, groupable: true }), column('consumed_at', 'TIMESTAMPTZ', { filterable: true }), column('food_name', 'VARCHAR', { filterable: true, groupable: true }), column('quantity', 'DOUBLE', { metric: true }), column('energy_kcal', 'DOUBLE', { unit: 'kcal', metric: true }), column('carbohydrates_g', 'DOUBLE', { unit: 'g', metric: true }), column('protein_g', 'DOUBLE', { unit: 'g', metric: true }), column('fat_g', 'DOUBLE', { unit: 'g', metric: true }), column('raw_object_hash', 'VARCHAR')],
+        columns: [column('provider', 'VARCHAR', { filterable: true, groupable: true }), column('remote_item_id', 'VARCHAR', { filterable: true }), column('nutrition_date', 'DATE', { filterable: true, groupable: true }), column('meal', 'VARCHAR', { filterable: true, groupable: true }), column('consumed_at', 'TIMESTAMPTZ', { filterable: true }), column('food_name', 'VARCHAR', { filterable: true, groupable: true }), column('quantity', 'DOUBLE', { metric: true }), column('energy_kcal', 'DOUBLE', { unit: 'kcal', metric: true }), column('carbohydrates_g', 'DOUBLE', { unit: 'g', metric: true }), column('protein_g', 'DOUBLE', { unit: 'g', metric: true }), column('fat_g', 'DOUBLE', { unit: 'g', metric: true }), column('payload_json', 'JSON', { description: PAYLOAD_JSON_DESCRIPTION }), column('raw_object_hash', 'VARCHAR')],
     },
     events: domain('events', 'event_id', 'Planned and completed calendar events.', 'occurred_on'),
     workouts: domain('workouts', 'workout_id', 'Provider workouts and scheduled workouts.', 'occurred_on'),
     workout_documents: {
         name: 'workout_documents', relation: 'workout_documents', description: 'Structured workout documents.', provenanceColumns: ['provider', 'workout_id'], permittedGroupings: ['provider'],
-        columns: [column('provider', 'VARCHAR', { filterable: true, groupable: true }), column('workout_id', 'VARCHAR', { filterable: true, groupable: true }), column('workout_doc', 'JSON'), column('payload_json', 'JSON')],
+        columns: [column('provider', 'VARCHAR', { filterable: true, groupable: true }), column('workout_id', 'VARCHAR', { filterable: true, groupable: true }), column('workout_doc', 'JSON'), column('payload_json', 'JSON', { description: PAYLOAD_JSON_DESCRIPTION })],
     },
     training_plans: domain('training_plans', 'training_plan_id', 'Training plans and plan hierarchy.', 'occurred_on'),
     routes: domain('routes', 'route_id', 'Saved routes.'),
@@ -87,7 +93,7 @@ export const DATASET_CATALOG = {
     messages: domain('messages', 'message_id', 'Provider chat/messages.', 'occurred_on'),
     source_entities: {
         name: 'source_entities', relation: 'source_entities', description: 'All raw-normalized source entities, including fields not modelled elsewhere.', dateColumn: 'occurred_on', provenanceColumns: ['provider', 'entity_type', 'remote_id', 'raw_object_hash'], permittedGroupings: ['provider', 'entity_type'],
-        columns: [column('provider', 'VARCHAR', { filterable: true, groupable: true }), column('entity_type', 'VARCHAR', { filterable: true, groupable: true }), column('remote_id', 'VARCHAR', { filterable: true }), column('parent_remote_id', 'VARCHAR', { filterable: true }), column('occurred_on', 'DATE', { filterable: true, groupable: true }), column('source_updated_at', 'TIMESTAMPTZ', { filterable: true }), column('raw_object_hash', 'VARCHAR'), column('payload_json', 'JSON'), column('extension_json', 'JSON')],
+        columns: [column('provider', 'VARCHAR', { filterable: true, groupable: true }), column('entity_type', 'VARCHAR', { filterable: true, groupable: true }), column('remote_id', 'VARCHAR', { filterable: true }), column('parent_remote_id', 'VARCHAR', { filterable: true }), column('occurred_on', 'DATE', { filterable: true, groupable: true }), column('source_updated_at', 'TIMESTAMPTZ', { filterable: true }), column('raw_object_hash', 'VARCHAR'), column('payload_json', 'JSON', { description: PAYLOAD_JSON_DESCRIPTION }), column('extension_json', 'JSON', { description: EXTENSION_JSON_DESCRIPTION })],
     },
     activity_links: {
         name: 'activity_links', relation: 'activity_links', description: 'Auditable source-to-logical activity links and their evidence.', provenanceColumns: ['activity_source_id', 'method', 'evidence_json'], permittedGroupings: ['method'],
@@ -107,7 +113,7 @@ export const DATASET_CATALOG = {
     },
     strava_gear: {
         name: 'strava_gear', relation: 'strava_gear', description: 'Current Strava bikes and shoes, refreshed from the authenticated athlete profile.', provenanceColumns: ['gear_id', 'raw_object_hash'], permittedGroupings: ['provider'],
-        columns: [column('provider', 'VARCHAR', { filterable: true, groupable: true }), column('gear_id', 'VARCHAR', { filterable: true, groupable: true }), column('payload_json', 'JSON'), column('extension_json', 'JSON'), column('raw_object_hash', 'VARCHAR')],
+        columns: [column('provider', 'VARCHAR', { filterable: true, groupable: true }), column('gear_id', 'VARCHAR', { filterable: true, groupable: true }), column('payload_json', 'JSON', { description: PAYLOAD_JSON_DESCRIPTION }), column('extension_json', 'JSON', { description: EXTENSION_JSON_DESCRIPTION }), column('raw_object_hash', 'VARCHAR')],
     },
     activity_samples: {
         name: 'activity_samples', description: 'Registered normalized activity samples from immutable Parquet; callers cannot supply file paths.', dateColumn: 'timestamp_utc', provenanceColumns: ['provider', 'activity_source_id', 'content_hash'], permittedGroupings: ['provider', 'activity_source_id'], samplesOnly: true,
@@ -121,7 +127,7 @@ export const DATASET_CATALOG = {
 function domain(name, id, description, dateColumn) {
     return {
         name, relation: name, description, dateColumn, provenanceColumns: ['provider', id, 'raw_object_hash'], permittedGroupings: ['provider'],
-        columns: [column('provider', 'VARCHAR', { filterable: true, groupable: true }), column(id, 'VARCHAR', { filterable: true, groupable: true }), ...(dateColumn ? [column(dateColumn, 'DATE', { filterable: true, groupable: true })] : []), column('payload_json', 'JSON'), column('extension_json', 'JSON'), column('raw_object_hash', 'VARCHAR')],
+        columns: [column('provider', 'VARCHAR', { filterable: true, groupable: true }), column(id, 'VARCHAR', { filterable: true, groupable: true }), ...(dateColumn ? [column(dateColumn, 'DATE', { filterable: true, groupable: true })] : []), column('payload_json', 'JSON', { description: PAYLOAD_JSON_DESCRIPTION }), column('extension_json', 'JSON', { description: EXTENSION_JSON_DESCRIPTION }), column('raw_object_hash', 'VARCHAR')],
     };
 }
 export function getDataset(name) {

package/dist/core/query/repository.d.ts

@@ -14,7 +14,7 @@ export declare class ReadOnlyRepository {
     progress(): Promise<SyncProgressSnapshot>;
     coverage(): Promise<Record<string, unknown>>;
     activity(activityId: string): Promise<Record<string, unknown> | null>;
-    summary(startDate: string, endDate: string): Promise<Record<string, unknown>>;
+    summary(startDate: string, endDate: string, detail?: 'summary' | 'columns'): Promise<Record<string, unknown>>;
     catalog(): DatasetDefinition[];
 }
 /** Converts DuckDB's Date/BigInt values into MCP-safe JSON values. */

package/dist/core/query/repository.js

@@ -172,12 +172,39 @@ export class ReadOnlyRepository {
         return mergeProgress(running.map(toSyncProgressState), recent.map(toSyncProgressState), runningSidecars);
     }
     async coverage() {
+        // One UNION keeps the per-relation min/max/count in a single metadata
+        // query. Every cataloged dataset with a usable date axis gets a row;
+        // segments and course_geometry are dictionaries without a data date, so
+        // they report a count and null dates rather than inventing a timeline from
+        // ingestion timestamps.
         const rows = await this.rows(`
       SELECT 'activities' AS dataset, min(cast(started_at_utc AS DATE)) AS start_date, max(cast(started_at_utc AS DATE)) AS end_date, count(*)::INTEGER AS row_count FROM activities
+      UNION ALL SELECT 'canonical_activities', min(cast(started_at_utc AS DATE)), max(cast(started_at_utc AS DATE)), count(*)::INTEGER FROM canonical_activity_training
+      UNION ALL SELECT 'canonical_activity_facts', min(cast(started_at_utc AS DATE)), max(cast(started_at_utc AS DATE)), count(*)::INTEGER FROM canonical_activity_facts
+      UNION ALL SELECT 'activity_summaries', min(cast(started_at_utc AS DATE)), max(cast(started_at_utc AS DATE)), count(*)::INTEGER FROM activity_summary_facts
+      UNION ALL SELECT 'activity_intervals', min(cast(started_at_utc AS DATE)), max(cast(started_at_utc AS DATE)), count(*)::INTEGER FROM activity_interval_facts
+      UNION ALL SELECT 'swim_lengths', min(cast(started_at_utc AS DATE)), max(cast(started_at_utc AS DATE)), count(*)::INTEGER FROM swim_length_facts
+      UNION ALL SELECT 'swim_sets', min(cast(started_at_utc AS DATE)), max(cast(started_at_utc AS DATE)), count(*)::INTEGER FROM swim_set_facts
+      UNION ALL SELECT 'activity_quality_flags', min(cast(started_at_utc AS DATE)), max(cast(started_at_utc AS DATE)), count(*)::INTEGER FROM activity_quality_flag_facts
+      UNION ALL SELECT 'power_bests', min(cast(started_at_utc AS DATE)), max(cast(started_at_utc AS DATE)), count(*)::INTEGER FROM power_best_facts
+      UNION ALL SELECT 'activity_decoupling', min(cast(started_at_utc AS DATE)), max(cast(started_at_utc AS DATE)), count(*)::INTEGER FROM activity_decoupling_facts
+      UNION ALL SELECT 'run_dynamics', min(cast(started_at_utc AS DATE)), max(cast(started_at_utc AS DATE)), count(*)::INTEGER FROM run_dynamics_facts
       UNION ALL SELECT 'daily_metrics', min(metric_date), max(metric_date), count(*)::INTEGER FROM daily_metrics
+      UNION ALL SELECT 'daily_health', min(metric_date), max(metric_date), count(*)::INTEGER FROM daily_health
       UNION ALL SELECT 'training_metric_observations', min(cast(observed_at AS DATE)), max(cast(observed_at AS DATE)), count(*)::INTEGER FROM training_metric_observations
+      UNION ALL SELECT 'wellness_samples', min(cast(observed_at AS DATE)), max(cast(observed_at AS DATE)), count(*)::INTEGER FROM wellness_samples
+      UNION ALL SELECT 'health_sessions', min(occurred_on), max(occurred_on), count(*)::INTEGER FROM health_sessions
       UNION ALL SELECT 'nutrition_days', min(nutrition_date), max(nutrition_date), count(*)::INTEGER FROM nutrition_days
+      UNION ALL SELECT 'nutrition_items', min(nutrition_date), max(nutrition_date), count(*)::INTEGER FROM nutrition_items
+      UNION ALL SELECT 'events', min(occurred_on), max(occurred_on), count(*)::INTEGER FROM events
+      UNION ALL SELECT 'workouts', min(occurred_on), max(occurred_on), count(*)::INTEGER FROM workouts
+      UNION ALL SELECT 'training_plans', min(occurred_on), max(occurred_on), count(*)::INTEGER FROM training_plans
+      UNION ALL SELECT 'messages', min(occurred_on), max(occurred_on), count(*)::INTEGER FROM messages
       UNION ALL SELECT 'source_entities', min(occurred_on), max(occurred_on), count(*)::INTEGER FROM source_entities
+      UNION ALL SELECT 'activity_segments', min(cast(started_at AS DATE)), max(cast(started_at AS DATE)), count(*)::INTEGER FROM activity_segments
+      UNION ALL SELECT 'segment_effort_history', min(cast(started_at AS DATE)), max(cast(started_at AS DATE)), count(*)::INTEGER FROM segment_effort_history
+      UNION ALL SELECT 'segments', CAST(NULL AS DATE), CAST(NULL AS DATE), count(*)::INTEGER FROM strava_segments
+      UNION ALL SELECT 'course_geometry', CAST(NULL AS DATE), CAST(NULL AS DATE), count(*)::INTEGER FROM course_geometry
     `);
         return { coverage: rows, providers: await this.rows(`SELECT provider, count(*)::INTEGER AS activity_sources FROM activity_sources GROUP BY provider ORDER BY provider`) };
     }
@@ -190,10 +217,12 @@ export class ReadOnlyRepository {
         const intervals = await this.rows(`SELECT * FROM activity_interval_facts WHERE activity_id = $activityId ORDER BY CASE provider WHEN 'garmin' THEN 0 WHEN 'intervals' THEN 1 ELSE 2 END, provider, start_s`, { activityId });
         return { activity: activity[0], sources, summaries, intervals };
     }
-    async summary(startDate, endDate) {
+    async summary(startDate, endDate, detail = 'summary') {
         const training = await this.rows(`SELECT cast(started_at_utc AS DATE) AS date, count(*)::INTEGER AS activities, sum(distance_m) AS distance_m, sum(moving_s) AS moving_s, sum(training_load) AS training_load FROM canonical_activity_training WHERE cast(started_at_utc AS DATE) BETWEEN cast($startDate AS DATE) AND cast($endDate AS DATE) GROUP BY 1 ORDER BY 1`, { startDate, endDate });
         const health = await this.rows(`SELECT * FROM daily_health WHERE metric_date BETWEEN cast($startDate AS DATE) AND cast($endDate AS DATE) ORDER BY metric_date, provider`, { startDate, endDate });
-        const nutrition = await this.rows(`SELECT * FROM nutrition_days WHERE nutrition_date BETWEEN cast($startDate AS DATE) AND cast($endDate AS DATE) ORDER BY nutrition_date, provider`, { startDate, endDate });
+        const nutrition = detail === 'columns'
+            ? await this.rows(`SELECT nutrition_date, provider, energy_kcal, carbohydrates_g, protein_g, fat_g, hydration_ml FROM nutrition_days WHERE nutrition_date BETWEEN cast($startDate AS DATE) AND cast($endDate AS DATE) ORDER BY nutrition_date, provider`, { startDate, endDate })
+            : await this.rows(`SELECT count(*)::INTEGER AS days_logged, min(nutrition_date) AS first_date, max(nutrition_date) AS last_date, sum(energy_kcal) AS energy_kcal, sum(carbohydrates_g) AS carbohydrates_g, sum(protein_g) AS protein_g, sum(fat_g) AS fat_g, sum(hydration_ml) AS hydration_ml FROM nutrition_days WHERE nutrition_date BETWEEN cast($startDate AS DATE) AND cast($endDate AS DATE)`, { startDate, endDate });
         return { training, health, nutrition };
     }
     catalog() {

package/dist/core/runtime/athlete-file.d.ts

@@ -0,0 +1,49 @@
+import type { CatencePaths } from '../../contracts/runtime.js';
+/**
+ * One athlete-authored markdown document per athlete store. Both the athlete
+ * (Console/UI) and the agent (MCP tools) may write it; every write is guarded
+ * by an optimistic compare-and-swap on the sha256 of the current content so
+ * neither side silently clobbers the other. Prior content is snapshotted into
+ * a small rolling revision history.
+ */
+export declare const ATHLETE_FILE_MAX_CHARACTERS = 32768;
+export declare const ATHLETE_FILE_TEMPLATE = "# Athlete file\n\nThis file is shared by the athlete and the Catence agent. Keep durable facts here:\nprofile, goals, constraints, injuries, preferences, and standing notes.\nDo not store credentials, provider configuration, or transient daily status.\n\n## Profile\n\n## Goals\n\n## Constraints and injuries\n\n## Preferences\n\n## Notes\n";
+export type AthleteFileSnapshot = {
+    exists: boolean;
+    /** Stored content, or the starter template while the file does not exist yet. */
+    content: string;
+    /** sha256 of the stored content; null while the file does not exist. */
+    hash: string | null;
+    updatedAt: string | null;
+};
+export type AthleteFileOperation = 'replace' | 'append' | 'replace_section';
+export type AthleteFileUpdate = {
+    operation: AthleteFileOperation;
+    /** Required when operation is replace_section. */
+    section?: string;
+    content: string;
+    /** Hash the caller read before this update; null when creating the file. */
+    expectedHash: string | null;
+};
+export type AthleteFileRevision = {
+    revisionId: string;
+    hash: string;
+    savedAt: string;
+};
+export declare class AthleteFileConflictError extends Error {
+    readonly currentHash: string;
+    readonly currentContent: string;
+    constructor(currentHash: string, currentContent: string);
+}
+export declare class AthleteFileTooLargeError extends Error {
+    readonly characters: number;
+    constructor(characters: number);
+}
+export declare class AthleteFileValidationError extends Error {
+    constructor(message: string);
+}
+export declare function hashAthleteFileContent(content: string): string;
+export declare function readAthleteFile(paths: CatencePaths): Promise<AthleteFileSnapshot>;
+export declare function updateAthleteFile(paths: CatencePaths, update: AthleteFileUpdate): Promise<AthleteFileSnapshot>;
+export declare function listAthleteFileRevisions(paths: CatencePaths): Promise<AthleteFileRevision[]>;
+export declare function readAthleteFileRevision(paths: CatencePaths, revisionId: string): Promise<string | null>;

package/dist/core/runtime/athlete-file.js

@@ -0,0 +1,177 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { mkdir, readdir, readFile, rename, stat, unlink, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+/**
+ * One athlete-authored markdown document per athlete store. Both the athlete
+ * (Console/UI) and the agent (MCP tools) may write it; every write is guarded
+ * by an optimistic compare-and-swap on the sha256 of the current content so
+ * neither side silently clobbers the other. Prior content is snapshotted into
+ * a small rolling revision history.
+ */
+export const ATHLETE_FILE_MAX_CHARACTERS = 32_768;
+const ATHLETE_FILE_HISTORY_LIMIT = 10;
+const REVISION_PATTERN = /^(\d{1,20})-([0-9a-f]{8})\.md$/;
+export const ATHLETE_FILE_TEMPLATE = `# Athlete file
+
+This file is shared by the athlete and the Catence agent. Keep durable facts here:
+profile, goals, constraints, injuries, preferences, and standing notes.
+Do not store credentials, provider configuration, or transient daily status.
+
+## Profile
+
+## Goals
+
+## Constraints and injuries
+
+## Preferences
+
+## Notes
+`;
+export class AthleteFileConflictError extends Error {
+    currentHash;
+    currentContent;
+    constructor(currentHash, currentContent) {
+        super('The athlete file changed since it was read. Read it again before writing.');
+        this.currentHash = currentHash;
+        this.currentContent = currentContent;
+        this.name = 'AthleteFileConflictError';
+    }
+}
+export class AthleteFileTooLargeError extends Error {
+    characters;
+    constructor(characters) {
+        super(`Athlete file would be ${characters} characters; the limit is ${ATHLETE_FILE_MAX_CHARACTERS}. Shorten the write or split it into sections.`);
+        this.characters = characters;
+        this.name = 'AthleteFileTooLargeError';
+    }
+}
+export class AthleteFileValidationError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'AthleteFileValidationError';
+    }
+}
+export function hashAthleteFileContent(content) {
+    return createHash('sha256').update(content).digest('hex');
+}
+function normalizeContent(content) {
+    return `${content.replace(/\r\n?/g, '\n').replace(/\n+$/, '')}\n`;
+}
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+function applySection(content, section, replacement) {
+    const name = section.trim();
+    if (!name)
+        throw new AthleteFileValidationError('replace_section requires a non-empty section name.');
+    const body = normalizeContent(replacement).trim();
+    const match = new RegExp(`^##\\s+${escapeRegExp(name)}\\s*$`, 'im').exec(content);
+    if (!match) {
+        const base = normalizeContent(content).trimEnd();
+        return body ? `${base}\n\n## ${name}\n\n${body}\n` : `${base}\n\n## ${name}\n`;
+    }
+    const bodyStart = content.indexOf('\n', match.index) + 1;
+    const rest = content.slice(bodyStart);
+    const nextHeading = /^##\s+/m.exec(rest);
+    const bodyEnd = nextHeading ? bodyStart + nextHeading.index : content.length;
+    const before = content.slice(0, bodyStart);
+    const after = content.slice(bodyEnd).replace(/^\n+/, '');
+    const combined = body ? `${before}\n${body}\n\n${after}` : `${before}\n${after}`;
+    return normalizeContent(combined).replace(/\n{3,}/g, '\n\n');
+}
+export async function readAthleteFile(paths) {
+    let stored;
+    try {
+        stored = await readFile(paths.athleteFile, 'utf8');
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT')
+            throw error;
+        stored = null;
+    }
+    if (stored === null)
+        return { exists: false, content: ATHLETE_FILE_TEMPLATE, hash: null, updatedAt: null };
+    const content = normalizeContent(stored);
+    const stats = await stat(paths.athleteFile);
+    return { exists: true, content, hash: hashAthleteFileContent(content), updatedAt: stats.mtime.toISOString() };
+}
+async function writeAtomically(filePath, content) {
+    const temporaryPath = `${filePath}.${randomUUID()}.tmp`;
+    await writeFile(temporaryPath, content, { encoding: 'utf8', mode: 0o600 });
+    try {
+        await rename(temporaryPath, filePath);
+    }
+    catch (error) {
+        await unlink(temporaryPath).catch(() => undefined);
+        throw error;
+    }
+}
+async function listRevisionNames(paths) {
+    const names = await readdir(paths.athleteFileHistory).catch((error) => {
+        if (error.code === 'ENOENT')
+            return [];
+        throw error;
+    });
+    return names
+        .map((name) => ({ name, match: REVISION_PATTERN.exec(name) }))
+        .filter((entry) => entry.match !== null)
+        .map((entry) => ({ name: entry.name, epoch: Number(entry.match[1]) }))
+        .sort((left, right) => right.epoch - left.epoch);
+}
+async function snapshotRevision(paths, content) {
+    await mkdir(paths.athleteFileHistory, { recursive: true, mode: 0o700 });
+    const name = `${Date.now()}-${hashAthleteFileContent(content).slice(0, 8)}.md`;
+    await writeFile(path.join(paths.athleteFileHistory, name), content, { encoding: 'utf8', mode: 0o600 });
+    const revisions = await listRevisionNames(paths);
+    for (const stale of revisions.slice(ATHLETE_FILE_HISTORY_LIMIT)) {
+        await unlink(path.join(paths.athleteFileHistory, stale.name)).catch(() => undefined);
+    }
+}
+export async function updateAthleteFile(paths, update) {
+    if (!['replace', 'append', 'replace_section'].includes(update.operation)) {
+        throw new AthleteFileValidationError(`Unknown athlete-file operation: ${String(update.operation)}.`);
+    }
+    const sparse = update.content.trim();
+    if (update.operation !== 'replace_section' && !sparse) {
+        throw new AthleteFileValidationError(`${update.operation} requires non-empty content.`);
+    }
+    const current = await readAthleteFile(paths);
+    if (current.hash !== update.expectedHash) {
+        throw new AthleteFileConflictError(current.hash ?? 'absent', current.content);
+    }
+    let next;
+    if (update.operation === 'replace')
+        next = normalizeContent(update.content);
+    else if (update.operation === 'append')
+        next = normalizeContent(`${current.content.trimEnd()}\n\n${update.content.trim()}`);
+    else
+        next = applySection(current.content, update.section ?? '', update.content);
+    next = normalizeContent(next);
+    if (next.length > ATHLETE_FILE_MAX_CHARACTERS)
+        throw new AthleteFileTooLargeError(next.length);
+    if (current.exists)
+        await snapshotRevision(paths, current.content);
+    await writeAtomically(paths.athleteFile, next);
+    return readAthleteFile(paths);
+}
+export async function listAthleteFileRevisions(paths) {
+    const revisions = await listRevisionNames(paths);
+    return revisions.map((revision) => ({
+        revisionId: revision.name,
+        hash: REVISION_PATTERN.exec(revision.name)[2],
+        savedAt: new Date(revision.epoch).toISOString(),
+    }));
+}
+export async function readAthleteFileRevision(paths, revisionId) {
+    if (!REVISION_PATTERN.test(revisionId))
+        throw new AthleteFileValidationError('Unknown athlete-file revision identifier.');
+    try {
+        return normalizeContent(await readFile(path.join(paths.athleteFileHistory, revisionId), 'utf8'));
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return null;
+        throw error;
+    }
+}
+//# sourceMappingURL=athlete-file.js.map

package/dist/core/runtime/configuration.js

@@ -14,6 +14,8 @@ export function resolvePaths(root = process.env.CATENCE_DATA_DIR ?? '.catence')
         config: path.join(absoluteRoot, 'config.json'),
         secrets: path.join(absoluteRoot, 'secrets'),
         lock: path.join(absoluteRoot, '.catence-write.lock'),
+        athleteFile: path.join(absoluteRoot, 'athlete.md'),
+        athleteFileHistory: path.join(absoluteRoot, 'athlete-revisions'),
     };
 }
 export async function ensurePaths(paths) {

package/dist/elt/application/management.js

@@ -207,7 +207,21 @@ function runGarminWorker(runId, arguments_, environment, pump, log, onInterruptR
             }
             log.info(`[garmin] ${line}`);
         });
-        buffer(child.stderr, (line) => log.error(`[garmin] ${line}`));
+        buffer(child.stderr, (line) => {
+            let parsed;
+            try {
+                parsed = JSON.parse(line);
+            }
+            catch {
+                log.error(`[garmin] ${line}`);
+                return;
+            }
+            if (typeof parsed === 'object' && parsed !== null && parsed.kind === 'stage_timings') {
+                log.info('Garmin staging worker stage timings', parsed);
+                return;
+            }
+            log.error(`[garmin] ${line}`);
+        });
         child.on('error', (error) => {
             if (killTimer)
                 clearTimeout(killTimer);
@@ -310,7 +324,9 @@ async function syncProvider(database, paths, provider, options, log) {
             // streams even when the list-summary hash is unchanged.
             await writeFile(knownActivities, JSON.stringify(options.refreshActivities ? {} : await database.knownActivitySummaryHashes('garmin')));
             extractionStarted = true;
-            const arguments_ = ['run', 'python', '-m', 'python.catence.providers.garmin.cli', '--from', fromDate, '--to', options.toDate, '--data-dir', paths.root, '--output', output, '--run-id', runId, '--known-activities', knownActivities];
+            const requestedConcurrency = Number.parseInt(process.env.CATENCE_GARMIN_CONCURRENCY ?? '5', 10);
+            const workerConcurrency = Number.isFinite(requestedConcurrency) && requestedConcurrency > 0 ? Math.trunc(requestedConcurrency) : 5;
+            const arguments_ = ['run', 'python', '-m', 'python.catence.providers.garmin.cli', '--from', fromDate, '--to', options.toDate, '--data-dir', paths.root, '--output', output, '--run-id', runId, '--known-activities', knownActivities, '--concurrency', String(workerConcurrency)];
             if (dailyWindow)
                 arguments_.push('--daily-from', dailyWindow.fromDate, '--daily-to', dailyWindow.toDate);
             else
@@ -340,6 +356,7 @@ async function syncProvider(database, paths, provider, options, log) {
             if (needsEventBackfill && earliestActivity && earliestActivity < eventsShortFrom) {
                 arguments_.push('--events-from', earliestActivity);
             }
+            const workerStartedAt = Date.now();
             let interruptChild = null;
             await runWithInterruptGuard(runId, database, () => interruptChild?.(), guard, async () => {
                 const outcome = await runGarminWorker(runId, arguments_, {
@@ -350,14 +367,21 @@ async function syncProvider(database, paths, provider, options, log) {
                     throw new Error(`Garmin staging worker exited with code ${outcome.code}${outcome.signal ? ` (${outcome.signal})` : ''}.`);
                 }
             });
+            log.info('Garmin staging worker finished', { runId, durationMs: Date.now() - workerStartedAt, concurrency: workerConcurrency });
             if (!guard.interrupted) {
                 if (!existsSync(output))
                     throw new Error('Garmin staging worker completed without writing a JSONL manifest.');
+                let phaseStartedAt = Date.now();
                 await importJsonl(database, runId, output, log);
+                log.info('Garmin staging import finished', { runId, durationMs: Date.now() - phaseStartedAt });
+                phaseStartedAt = Date.now();
                 await reconcileGarminCalendarEntities(database, output);
+                log.info('Garmin calendar reconciliation finished', { runId, durationMs: Date.now() - phaseStartedAt });
                 if (provider === 'garmin') {
                     try {
+                        phaseStartedAt = Date.now();
                         await backfillGarminSwimLengths(database, paths, runId, log);
+                        log.info('Garmin swim-length backfill finished', { runId, durationMs: Date.now() - phaseStartedAt });
                     }
                     catch (error) {
                         log.warn('Garmin swim-length backfill after sync failed', {
@@ -457,8 +481,9 @@ export async function syncData(paths, provider, explicitFrom, advanceCursor = tr
                 indexingKeepalive.unref?.();
             }
             try {
+                const indexStartedAt = Date.now();
                 const index = await buildRetrievalIndex(database);
-                log.info('Rebuilt retrieval index after sync', { documents: index.documents, mode: index.mode, watermark: index.watermark });
+                log.info('Rebuilt retrieval index after sync', { documents: index.documents, mode: index.mode, watermark: index.watermark, durationMs: Date.now() - indexStartedAt });
             }
             finally {
                 if (indexingKeepalive)