catence 0.2.0 → 0.2.1-beta.10

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.
 
@@ -31,7 +31,7 @@ Install Catence and create the first athlete. The default catalog home is `~/.ca
 Every `catence-data` command requires `--athlete <id>`; there is no default athlete. Pair it with `--home <dir>` to select the catalog when not using the default home.
 
 ```sh
-npm install --global catence@beta          # or catence@latest for stable
+npm install --global catence@latest          # or catence@beta
 catence-data setup --athlete alex --label "Alex"
 ```
 
@@ -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
 
@@ -114,13 +114,13 @@ For a source checkout:
 codex mcp add catence -- npm --prefix /absolute/path/to/catence run mcp
 ```
 
-Optional local Streamable HTTP MCP and dashboard APIs:
+Optional local Streamable HTTP MCP and HTTP APIs:
 
 ```sh
 catence serve --host 127.0.0.1 --port 8787
 ```
 
-`GET /api/v1/athletes` returns IDs and labels only. `GET /api/v1/dashboard` requires `athleteId`, for example `http://127.0.0.1:8787/api/v1/dashboard?athleteId=alex&days=28`. Browser origins must be listed with `--allow-origin`; the packaged Console instead proxies the dashboard through its authenticated same-origin route. The MCP server has no authentication of its own.
+`GET /api/v1/athletes` returns IDs and labels only. `GET /api/v1/dashboard` requires `athleteId`, for example `http://127.0.0.1:8787/api/v1/dashboard?athleteId=alex&days=28`. Browser origins must be listed with `--allow-origin`; the packaged Console instead proxies the dashboard through its authenticated same-origin route. `POST /api/v1/athletes` creates a catalog athlete (`{"id": "sam", "label": "Sam", "setDefault": false}`); the packaged Console exposes the same call to admins from **Settings → Athletes**. The MCP server has no authentication of its own.
 
 ## Configuration
 

package/config.example.json

@@ -28,6 +28,7 @@
       "toolRounds": 8,
       "toolResultCharacters": 24000
     },
+    "mcpServers": {},
     "profiles": {
       "openai": {
         "label": "OpenAI",

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.0";
+export declare const CATENCE_RUNTIME_VERSION = "0.2.1-beta.10";
 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.0';
+export const CATENCE_RUNTIME_VERSION = '0.2.1-beta.10';
 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';
+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,17 +113,21 @@ 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,
         columns: [column('provider', 'VARCHAR', { filterable: true, groupable: true }), column('content_hash', 'VARCHAR', { filterable: true, groupable: true }), column('activity_source_id', 'VARCHAR', { filterable: true, groupable: true }), column('timestamp_utc', 'TIMESTAMPTZ', { filterable: true }), column('elapsed_s', 'DOUBLE', { unit: 's', metric: true }), column('distance_m', 'DOUBLE', { unit: 'm', metric: true }), column('latitude', 'DOUBLE', { unit: 'degrees', metric: true }), column('longitude', 'DOUBLE', { unit: 'degrees', metric: true }), column('altitude_m', 'DOUBLE', { unit: 'm', metric: true }), column('heart_rate_bpm', 'DOUBLE', { unit: 'bpm', metric: true }), column('power_w', 'DOUBLE', { unit: 'W', metric: true }), column('cadence_rpm', 'DOUBLE', { unit: 'rpm', metric: true }), column('speed_mps', 'DOUBLE', { unit: 'm/s', metric: true }), column('temperature_c', 'DOUBLE', { unit: 'C', metric: true }), column('grade_pct', 'DOUBLE', { unit: '%', metric: true }), column('left_right_balance_pct', 'DOUBLE', { unit: '%', metric: true }), column('left_torque_effectiveness_pct', 'DOUBLE', { unit: '%', metric: true }), column('right_torque_effectiveness_pct', 'DOUBLE', { unit: '%', metric: true }), column('left_pedal_smoothness_pct', 'DOUBLE', { unit: '%', metric: true }), column('right_pedal_smoothness_pct', 'DOUBLE', { unit: '%', metric: true }), column('left_power_phase_start_deg', 'DOUBLE', { unit: 'degrees', metric: true }), column('left_power_phase_end_deg', 'DOUBLE', { unit: 'degrees', metric: true }), column('right_power_phase_start_deg', 'DOUBLE', { unit: 'degrees', metric: true }), column('right_power_phase_end_deg', 'DOUBLE', { unit: 'degrees', metric: true }), column('left_power_phase_peak_start_deg', 'DOUBLE', { unit: 'degrees', metric: true }), column('left_power_phase_peak_end_deg', 'DOUBLE', { unit: 'degrees', metric: true }), column('right_power_phase_peak_start_deg', 'DOUBLE', { unit: 'degrees', metric: true }), column('right_power_phase_peak_end_deg', 'DOUBLE', { unit: 'degrees', metric: true }), column('left_platform_center_offset_mm', 'DOUBLE', { unit: 'mm', metric: true }), column('right_platform_center_offset_mm', 'DOUBLE', { unit: 'mm', metric: true }), column('extras_json', 'JSON')],
     },
+    course_geometry: {
+        name: 'course_geometry', relation: 'course_geometry', description: 'Per-point Garmin course/route geometry (lat/lon/altitude_m/distance_m) normalized from a race event course. Resolve a courseId first with resolve_event_course, then query these rows for an elevation/height profile, gradient, or GPX-style track.', provenanceColumns: ['course_id', 'raw_object_hash'], permittedGroupings: ['course_id'],
+        columns: [column('course_id', 'VARCHAR', { filterable: true, groupable: true }), column('seq', 'INTEGER', { metric: true }), column('lat', 'DOUBLE', { unit: 'degrees', metric: true }), column('lon', 'DOUBLE', { unit: 'degrees', metric: true }), column('altitude_m', 'DOUBLE', { unit: 'm', metric: true }), column('distance_m', 'DOUBLE', { unit: 'm', metric: true }), column('raw_object_hash', 'VARCHAR')],
+    },
 };
 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/query/sql-guard.js

@@ -44,6 +44,26 @@ function normalizeRelation(name) {
     const relation = name.trim().replace(/\s+(?:as\s+)?(?:"[^"]+"|[A-Za-z_][A-Za-z0-9_]*)\s*$/i, '');
     return relation.replaceAll('"', '').split('.').at(-1).toLowerCase();
 }
+// Physical base tables that are reachable only through cataloged views
+// (e.g. the events/workouts/routes/… domain projections over domain_entities).
+// They must be accepted when DuckDB resolves a cataloged view down to its base
+// table after tableNames(), but must never be writable directly by name.
+const INDIRECT_BASE_TABLES = new Set(['domain_entities']);
+// dataset->named tool hints for the common dead-end relations, so a rejected
+// query tells the agent where to go instead of just that it was denied.
+const RELATION_HINTS = {
+    events: 'events is a domain projection; use aggregate_data on events or resolve_event_course(eventId) / search_context to read events and races.',
+    workouts: 'workouts is a domain projection; use aggregate_data on workouts or search_context to read workouts.',
+    workout_documents: 'workout_documents is a domain projection; use aggregate_data on workout_documents or search_context to read workout documents.',
+    training_plans: 'training_plans is a domain projection; use aggregate_data on training_plans or search_context to read training plans.',
+    routes: 'routes is a domain projection; use aggregate_data on routes or search_context to read routes.',
+    gear: 'gear is a domain projection; use aggregate_data on gear or search_context to read saved gear.',
+    devices: 'devices is a domain projection; use aggregate_data on devices or search_context to read devices.',
+    goals: 'goals is a domain projection; use aggregate_data on goals or search_context to read goals and challenges.',
+    achievements: 'achievements is a domain projection; use aggregate_data on achievements or search_context to read badges and personal records.',
+    messages: 'messages is a domain projection; use aggregate_data on messages or search_context to read provider messages.',
+    course_geometry: 'course_geometry is the per-point course track (lat/lon/altitude_m/distance_m); resolve a race course first with resolve_event_course, then query it for elevation/height profiles.',
+};
 export async function queryReadOnlyData(repository, request) {
     const sql = safeSql(request.sql);
     let relations;
@@ -53,16 +73,28 @@ export async function queryReadOnlyData(repository, request) {
     catch (error) {
         throw new QueryValidationError(`SQL could not be inspected: ${error instanceof Error ? error.message : String(error)}`);
     }
-    const allowed = new Set(Object.values(DATASET_CATALOG).filter((dataset) => !dataset.samplesOnly && dataset.relation).map((dataset) => dataset.relation.toLowerCase()));
+    // The catalog relation names form the strict allow-list for what a query may
+    // name directly (Check B below). Base tables reached only through cataloged
+    // views are additionally permitted after DuckDB resolves views for Check A,
+    // but they are never valid relation names in the SQL text.
+    const allowedNamed = new Set(Object.values(DATASET_CATALOG).filter((dataset) => !dataset.samplesOnly && dataset.relation).map((dataset) => dataset.relation.toLowerCase()));
+    const allowedForExpansion = new Set([...allowedNamed, ...INDIRECT_BASE_TABLES]);
+    const rejected = [];
     for (const relation of relations) {
-        if (!allowed.has(normalizeRelation(relation)))
-            throw new QueryValidationError(`Relation ${relation} is not in the read-only catalog.`);
+        const normalized = normalizeRelation(relation);
+        if (!allowedForExpansion.has(normalized))
+            rejected.push(relation);
+    }
+    if (rejected.length > 0) {
+        const name = normalizeRelation(rejected[0]);
+        throw new QueryValidationError(`Relation ${rejected[0]} is not in the read-only catalog.${RELATION_HINTS[name] ? ` ${RELATION_HINTS[name]}` : ''}`);
     }
     const ctes = new Set([...sql.matchAll(/(?:\bwith|,)\s*([A-Za-z_][A-Za-z0-9_]*)\s+as\s*\(/gi)].map((match) => match[1].toLowerCase()));
     for (const match of sql.matchAll(/\b(?:from|join)\s+([A-Za-z_][A-Za-z0-9_.]*)/gi)) {
         const relation = normalizeRelation(match[1]);
-        if (!allowed.has(relation) && !ctes.has(relation))
-            throw new QueryValidationError(`Relation ${match[1]} is not in the read-only catalog.`);
+        if (!allowedNamed.has(relation) && !ctes.has(relation)) {
+            throw new QueryValidationError(`Relation ${match[1]} is not in the read-only catalog.${RELATION_HINTS[relation] ? ` ${RELATION_HINTS[relation]}` : ''}`);
+        }
     }
     const values = request.values ?? {};
     if ('__catence_page_size' in values || '__catence_offset' in values)

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.d.ts

@@ -37,4 +37,11 @@ export declare function resolveExtractionErrors(paths: CatencePaths, opts?: {
  * previously mis-parsed nutrition_days/nutrition_items from stored payloads.
  */
 export declare function reimportNutrition(paths: CatencePaths): Promise<Record<string, unknown>>;
+/**
+ * Re-run normalization over already-captured Garmin weigh-in entities without
+ * contacting any provider. Stores synced before beta.5 staged weigh_ins
+ * payloads but never projected them to daily_metrics, so this backfills
+ * weight_kg from stored payloads. Idempotent upserts make it safe to re-run.
+ */
+export declare function reimportWeight(paths: CatencePaths): Promise<Record<string, unknown>>;
 export {};