catence 0.2.0-beta.21 → 0.2.0-beta.24

package/dist/interfaces/mcp/main.js

@@ -1,11 +1,42 @@
 #!/usr/bin/env node
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { existsSync } from 'node:fs';
-import { addAthlete, athleteStorePaths, createDemoStore, defaultCatalogHome, initializeCatalog, loadCatalog, resolveCatalogPaths } from '../../runtime/index.js';
+import { addAthlete, athleteStorePaths, CatenceDatabase, createDemoStore, defaultCatalogHome, initializeCatalog, loadCatalog, resolveCatalogPaths } from '../../runtime/index.js';
 import { parseServeCliOptions, SERVE_USAGE } from '../http/cli-options.js';
 import { createCatenceHttpServer } from '../http/server.js';
 import { MCP_USAGE, parseMcpCliOptions } from './cli-options.js';
 import { createCatenceMcpServer } from './server.js';
+async function migrateCatalogStores(home) {
+    // On Docker image bumps the DuckDB schema version increases. The
+    // read-only MCP health probe would otherwise report "version X required"
+    // until the next manual sync. Proactively opening each athlete store in
+    // writable mode runs the idempotent migrations (database.ts:migrate)
+    // before the HTTP server starts listening, so a plain `docker compose up`
+    // after `deploy-console.sh beta` heals existing installs without an extra
+    // manual `catence-data migrate --all` step. Failures are best-effort:
+    // a missing catalog or a store still locked by another process is retried
+    // on the next sync or health check.
+    try {
+        const catalogPaths = resolveCatalogPaths(home);
+        const catalog = await loadCatalog(catalogPaths).catch(() => null);
+        if (!catalog || catalog.athletes.length === 0)
+            return;
+        for (const athlete of catalog.athletes) {
+            const paths = athleteStorePaths(catalogPaths, athlete.id);
+            try {
+                const database = await CatenceDatabase.open(paths);
+                await database.close();
+            }
+            catch {
+                // Best-effort: a lock or a corrupted store must not prevent the
+                // server from starting; the next sync will retry the migration.
+            }
+        }
+    }
+    catch {
+        // Catalog read failures are non-fatal for startup.
+    }
+}
 async function run() {
     const arguments_ = process.argv.slice(2);
     if (arguments_[0] === 'serve') {
@@ -14,6 +45,7 @@ async function run() {
             process.stderr.write(`${SERVE_USAGE}\n`);
             return;
         }
+        await migrateCatalogStores(options.home);
         const httpServer = createCatenceHttpServer({
             catalogPaths: resolveCatalogPaths(options.home),
             allowedOrigins: options.allowedOrigins,

package/dist/interfaces/mcp/server.js

@@ -1,7 +1,7 @@
 import { McpServer, ResourceTemplate } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { AsyncLocalStorage } from 'node:async_hooks';
 import { z } from 'zod';
-import { ActivityDiscoveryService, AnalyticsService, loadCatalog, configuredMcpRateLimit, DataWriteBusyError, DATASET_CATALOG, demoStoreMetadata, DetachedSyncBusyError, FitnessService, getDataset, hydrateStravaActivity, hydrateStravaSegmentHistory, jsonSafe, loadCatenceConfig, openReadOnlyRepository, queryReadOnlyData, QueryValidationError, ReadOnlyDatabaseError, resolveAthlete, resolveCatalogPaths, searchContext, SlidingWindowLimiter, startDetachedSync, StravaEnrichmentError, StravaRateLimitError, SwimmingService, WELLNESS_METRICS, WellnessService, } from '../../runtime/index.js';
+import { ActivityDiscoveryService, AnalyticsService, loadCatalog, configuredMcpRateLimit, DataWriteBusyError, DATASET_CATALOG, demoStoreMetadata, DetachedSyncBusyError, EventsService, FitnessService, getDataset, hydrateStravaActivity, hydrateStravaSegmentHistory, jsonSafe, loadCatenceConfig, openReadOnlyRepository, queryReadOnlyData, QueryValidationError, ReadOnlyDatabaseError, resolveAthlete, resolveCatalogPaths, searchContext, SlidingWindowLimiter, startDetachedSync, StravaEnrichmentError, StravaRateLimitError, SwimmingService, WELLNESS_METRICS, WellnessService, } from '../../runtime/index.js';
 const filterSchema = z.object({
     column: z.string().min(1),
     op: z.enum(['eq', 'neq', 'gt', 'gte', 'lt', 'lte', 'in', 'between', 'contains']),
@@ -27,6 +27,12 @@ const MCP_INSTRUCTIONS = [
     'That tool performs the targeted Strava hydration itself. Do not say segment data is unavailable before it returns; if it reports not_found, ambiguous, authorization, throttling, or an error, report that exact outcome instead.',
     'For Garmin running VO₂max, call get_vo2max_history with sport: running. Garmin stores the source value as generic; returned rows preserve that source label.',
     'Aggregate elevation alone cannot support an individual-climb conclusion. Use source-specific facts and their stated coverage.',
+    'For race-readiness / fitness-target questions, establish a trend-first baseline (readiness_baseline, analyze_series, aggregate_data time buckets) before comparing any single activity.',
+    'Never conclude from VO2max alone; pull full indicator set (LT/FTP/power/race-prediction).',
+    'When summary metric is NULL (e.g. avg_power), fall through to FIT-derived/samples layer before declaring absence.',
+    'Before reusing any prior course/elevation profile, resolve event\'s courseId and diff it against past activity\'s course; different courseId => different profile.',
+    'If a needed tool is not visible in your current tool list (the host may truncate it to a subset), read the catence://tools resource to discover all available tools before concluding a capability is absent.',
+    'For swim analysis: use find_activities (sports: ["lap_swimming"] or sport: "lap_swimming") to list pool sessions. Use get_swim_laps for per-length data (pace from duration_s/pool_length_m, SPL from stroke_count, SWOLF from duration_s+stroke_count). Use swim_progress_report for session-level SWOLF, fastest-100, and stroke cadence. Per-length SWOLF is derived when the provider does not supply it. Per-length distance is typically null in Garmin FIT; use pool_length_m for pace calculations.',
 ].join(' ');
 function textResult(value) {
     return { content: [{ type: 'text', text: JSON.stringify(jsonSafe(value), null, 2) }] };
@@ -133,9 +139,16 @@ export function createCatenceMcpServer(paths = resolveCatalogPaths(), dependenci
     const activeAthlete = () => scope.getStore()?.athlete;
     const limiter = new SlidingWindowLimiter();
     const athleteIdSchema = z.string().regex(/^[a-z][a-z0-9-]{0,62}$/);
+    // Discoverability: record every registered tool so the catence://tools resource can
+    // enumerate all tools even when the host harness truncates the visible tool list.
+    const TOOL_INDEX = [];
+    function registerTool(name, config, callback) {
+        TOOL_INDEX.push({ name, title: config.title ?? name, description: config.description ?? '' });
+        server.registerTool(name, config, callback);
+    }
     const promptAthleteSchema = catalogPaths ? { athleteId: athleteIdSchema } : {};
     if (catalogPaths) {
-        server.registerTool('list_athletes', {
+        registerTool('list_athletes', {
             title: 'List configured athletes',
             description: 'List athlete IDs and labels available to this shared Catence agent. No personal metrics are returned.',
         }, async () => {
@@ -229,24 +242,24 @@ export function createCatenceMcpServer(paths = resolveCatalogPaths(), dependenci
     }, ({ activityId, ...input }) => ({
         messages: [{
                 role: 'user',
-                content: { type: 'text', text: `Run review_activity_deep_dive for ${activityId}${typeof input.athleteId === 'string' ? ` with athleteId ${input.athleteId}` : ''}. Use its source records and intervals first; load read_series only if a specific sampled metric is needed.` },
+                content: { type: 'text', text: `Run review_activity_deep_dive for ${activityId}${typeof input.athleteId === 'string' ? ` with athleteId ${input.athleteId}` : ''}. Use its source records and intervals first; load read_series only if a specific sampled metric is needed. Use as anchor for current form only after trend baseline exists.` },
             }],
     }));
-    server.registerTool('catence_status', {
+    registerTool('catence_status', {
         title: 'Catence data status',
         description: 'Read sync state, data coverage, entity counts, stream availability, unresolved errors, and retrieval-index freshness. Read-only.',
     }, tool('catence_status', async () => useRepository(activePaths(), async (repository) => ({
         data: { ...(await repository.status()), ...(await repository.coverage()) },
         provenance: { database: 'read-only DuckDB snapshot' }, query: {}, caveats: [],
     }))));
-    server.registerTool('catence_sync_progress', {
+    registerTool('catence_sync_progress', {
         title: 'Catence sync progress',
         description: 'Read live progress heartbeats for active sync runs, plus the most recent completed or interrupted runs. Read-only.',
     }, tool('catence_sync_progress', async () => useRepository(activePaths(), async (repository) => ({
         data: await repository.progress(),
         provenance: { database: 'read-only DuckDB snapshot' }, query: {}, caveats: [],
     }))));
-    server.registerTool('start_detached_sync', {
+    registerTool('start_detached_sync', {
         title: 'Start a detached data sync',
         description: 'Write-only sync trigger, named like the other explicit lock-guarded write tools. Spawns one detached catence-data sync process for this athlete and returns immediately with the run handle and log file; it refuses while another sync run is active. Track the run with catence_sync_progress; this tool never waits for completion.',
         inputSchema: {
@@ -268,7 +281,7 @@ export function createCatenceMcpServer(paths = resolveCatalogPaths(), dependenci
             ],
         };
     }));
-    server.registerTool('review_daily_recovery_load', {
+    registerTool('review_daily_recovery_load', {
         title: 'Review daily recovery and training load',
         description: 'Return source-cited daily health, training, and nutrition facts for a recovery/load review. It does not prescribe a training plan.',
         inputSchema: { date: z.string().date().optional() },
@@ -284,7 +297,7 @@ export function createCatenceMcpServer(paths = resolveCatalogPaths(), dependenci
             ],
         }));
     }));
-    server.registerTool('review_weekly_training', {
+    registerTool('review_weekly_training', {
         title: 'Review seven days of training',
         description: 'Return source-cited health, training, and nutrition facts for the seven-day period ending on an optional date. It does not prescribe a training plan.',
         inputSchema: { endDate: z.string().date().optional() },
@@ -301,7 +314,7 @@ export function createCatenceMcpServer(paths = resolveCatalogPaths(), dependenci
             ],
         }));
     }));
-    server.registerTool('review_activity_deep_dive', {
+    registerTool('review_activity_deep_dive', {
         title: 'Review one activity in depth',
         description: 'Return canonical activity identity, source summaries, and structured intervals. Call read_series separately only when a specific sampled metric is required.',
         inputSchema: { activityId: z.string().min(1) },
@@ -316,14 +329,14 @@ export function createCatenceMcpServer(paths = resolveCatalogPaths(), dependenci
                 : ['No canonical activity matched this activityId. Use find_activities before drawing conclusions.'],
         };
     })));
-    server.registerTool('describe_data', {
+    registerTool('describe_data', {
         title: 'Describe available Catence datasets',
         description: 'List cataloged datasets, fields, units, permitted filters/groupings, providers, and time coverage. Read-only.',
     }, tool('describe_data', async () => useRepository(activePaths(), async (repository) => ({
         data: { datasets: repository.catalog(), ...(await repository.coverage()) },
         provenance: { catalog: 'Catence catalog, restricted to analytical views' }, query: {}, caveats: ['activity_samples is available only through read_series or aggregate_data and only reads registered Parquet stream manifests.'],
     }))));
-    server.registerTool('describe_dataset', {
+    registerTool('describe_dataset', {
         title: 'Describe one Catence dataset',
         description: 'Read a compact schema, permitted filters/groupings, provenance fields, and coverage for one cataloged dataset. Read-only.',
         inputSchema: { dataset: z.string().min(1) },
@@ -346,10 +359,10 @@ export function createCatenceMcpServer(paths = resolveCatalogPaths(), dependenci
             provenance: { catalog: 'Catence catalog', database: 'read-only DuckDB snapshot' }, query: input, caveats: [],
         };
     })));
-    server.registerTool('read_series', {
+    registerTool('read_series', {
         title: 'Read a bounded time series', description: 'Read cataloged numeric series with deterministic cursor pagination and automatic stream downsampling. metrics must be numeric catalog columns; place identifiers and other strings in filters. Call describe_dataset first if the fields are uncertain.', inputSchema: seriesInput,
     }, tool('read_series', async (input) => useRepository(activePaths(), (repository) => new AnalyticsService(repository).readSeries({ ...input, filters: input.filters }))));
-    server.registerTool('aggregate_data', {
+    registerTool('aggregate_data', {
         title: 'Aggregate cataloged data', description: 'Declarative aggregation over one cataloged dataset. A timeBucket adds a time_bucket field, which can be used in orderBy. No joins, arbitrary expressions, or file paths.',
         inputSchema: {
             dataset: z.string().min(1),
@@ -357,15 +370,42 @@ export function createCatenceMcpServer(paths = resolveCatalogPaths(), dependenci
             dimensions: z.array(z.string().min(1)).max(8).optional(), filters: z.array(filterSchema).max(50).optional(), startDate: z.string().date().optional(), endDate: z.string().date().optional(), timeBucket: z.enum(['day', 'week', 'month']).optional(), orderBy: z.object({ column: z.string().min(1), direction: z.enum(['asc', 'desc']).optional() }).optional(), limit: z.number().int().min(1).max(500).optional(),
         },
     }, tool('aggregate_data', async (input) => useRepository(activePaths(), (repository) => new AnalyticsService(repository).aggregate({ ...input, filters: input.filters }))));
-    server.registerTool('analyze_series', {
+    registerTool('analyze_series', {
         title: 'Analyze a descriptive series', description: 'Run deterministic rolling statistics, baselines, correlations, seasonal comparisons, or trends on a cataloged series.',
         inputSchema: { ...seriesInput, analysis: z.enum(['rolling_mean', 'rolling_median', 'baseline_change', 'z_score', 'pearson', 'spearman', 'seasonal_comparison', 'linear_trend', 'theil_sen_trend']), compareMetric: z.string().min(1).optional(), window: z.number().int().min(2).max(100).optional() },
     }, tool('analyze_series', async (input) => useRepository(activePaths(), (repository) => new AnalyticsService(repository).analyzeSeries({ ...input, filters: input.filters }))));
-    server.registerTool('fit_series_model', {
+    registerTool('fit_series_model', {
         title: 'Fit a descriptive series model', description: 'Fit a bounded OLS, Theil–Sen, quadratic, or cubic descriptive model. Not a sport-performance model.',
         inputSchema: { ...seriesInput, model: z.enum(['ols_linear', 'theil_sen_linear', 'polynomial_2', 'polynomial_3']), xMetric: z.string().min(1).optional(), yMetric: z.string().min(1).optional() },
     }, tool('fit_series_model', async (input) => useRepository(activePaths(), (repository) => new AnalyticsService(repository).fitSeriesModel({ ...input, filters: input.filters }))));
-    server.registerTool('wellness_correlate', {
+    registerTool('activity_decoupling', {
+        title: 'Derive aerobic decoupling and GAP for one activity',
+        description: 'Derive aerobic decoupling (Pa:Hr for running using speed/HR, Pw:Hr for cycling using power/HR — drift across steady first/second halves) and grade-adjusted pace (GAP, Minetti 2002 cost model) from stored activity_samples for one activity. Returns null with explanatory caveats when samples are insufficient, walk-heavy, or stop-heavy. Derived values are descriptive only and never overwrite provider-supplied decoupling/GAP. Read-only.',
+        inputSchema: { activityId: z.string().min(1), includeGap: z.boolean().optional() },
+    }, tool('activity_decoupling', async (input) => useRepository(activePaths(), async (repository) => {
+        const analytics = new AnalyticsService(repository);
+        const decoupling = await analytics.deriveDecoupling({ activityId: input.activityId });
+        const gap = input.includeGap === false ? null : await analytics.deriveGap({ activityId: input.activityId });
+        const decouplingData = decoupling;
+        const gapData = gap;
+        const combinedCaveats = [
+            ...(decouplingData.caveats ?? []),
+            ...(gapData?.caveats ?? []),
+        ];
+        return jsonSafe({
+            data: { decoupling: decouplingData.data ?? null, gap: gapData?.data ?? null, decouplingRaw: decouplingData, gapRaw: gapData },
+            provenance: {
+                decoupling: decouplingData.provenance,
+                gap: gapData?.provenance ?? null,
+                derivation: 'derived',
+                note: 'Both metrics are derived from activity_samples (Parquet lake) when provider summaries do not supply them; provider values remain authoritative.',
+            },
+            query: { activityId: input.activityId, includeGap: input.includeGap ?? true, decouplingQuery: decouplingData.query, gapQuery: gapData?.query ?? null },
+            caveats: combinedCaveats.length ? combinedCaveats : ['Derived metrics are descriptive only; not a physiological performance model.'],
+            inputs: { decouplingInput: decouplingData.input, gapInput: gapData?.input ?? null },
+        });
+    })));
+    registerTool('wellness_correlate', {
         title: 'Correlate recovery and training metrics',
         description: 'Calculate a compact daily Pearson or Spearman correlation between curated wellness and training metrics, with an optional -7 through +7 day lag scan. Descriptive only.',
         inputSchema: {
@@ -373,35 +413,55 @@ export function createCatenceMcpServer(paths = resolveCatalogPaths(), dependenci
             method: z.enum(['pearson', 'spearman']).optional(), lagDays: z.number().int().min(-30).max(30).optional(), scanLags: z.boolean().optional(),
         },
     }, tool('wellness_correlate', async (input) => useRepository(activePaths(), (repository) => new WellnessService(repository).correlate(input))));
-    server.registerTool('wellness_baselines', {
+    registerTool('wellness_baselines', {
         title: 'Read personal wellness baselines',
         description: 'Return trailing means, standard-deviation bands, latest values, and latest z-scores for common recovery and training metrics. Missing values remain missing.',
         inputSchema: { metrics: z.array(z.enum(WELLNESS_METRICS)).min(1).max(12).optional(), endDate: z.string().date().optional(), windowDays: z.number().int().min(7).max(365).optional() },
     }, tool('wellness_baselines', async (input) => useRepository(activePaths(), (repository) => new WellnessService(repository).baselines(input))));
-    server.registerTool('wellness_anomalies', {
+    registerTool('wellness_anomalies', {
         title: 'Find statistical wellness anomalies',
         description: 'Find daily recovery and wellness outliers by z-score and group dates with anomalies across multiple signals. This does not diagnose or prescribe.',
         inputSchema: { metrics: z.array(z.enum(WELLNESS_METRICS)).min(1).max(12).optional(), startDate: z.string().date().optional(), endDate: z.string().date().optional(), zThreshold: z.number().min(1).max(5).optional() },
     }, tool('wellness_anomalies', async (input) => useRepository(activePaths(), (repository) => new WellnessService(repository).anomalies(input))));
-    server.registerTool('wellness_coverage', {
+    registerTool('wellness_coverage', {
         title: 'Inspect wellness data coverage',
         description: 'Report present and missing dates for curated wellness/training metrics, plus unresolved extraction errors. Missing data is never interpreted as rest or a health outcome.',
         inputSchema: { metrics: z.array(z.enum(WELLNESS_METRICS)).min(1).max(12).optional(), startDate: z.string().date().optional(), endDate: z.string().date().optional() },
     }, tool('wellness_coverage', async (input) => useRepository(activePaths(), (repository) => new WellnessService(repository).coverage(input))));
-    server.registerTool('get_ftp_history', {
+    registerTool('get_ftp_history', {
         title: 'Get dated FTP history',
         description: 'Return normalized cycling FTP settings and activity-summary observations with source-aware preferred daily values. Read-only.',
         inputSchema: { sport: z.string().min(1).optional(), startDate: z.string().date().optional(), endDate: z.string().date().optional(), sourcePreference: z.enum(['settings', 'settings_then_activity', 'all']).optional() },
     }, tool('get_ftp_history', async (input) => useRepository(activePaths(), (repository) => new FitnessService(repository).ftpHistory(input))));
-    server.registerTool('get_vo2max_history', {
+    registerTool('readiness_baseline', {
+        title: 'Read a running/race readiness baseline',
+        description: 'Combine the full performance-indicator set — running lactate threshold (pace/power/HR), VO₂max, race predictions, fitness trend, endurance score, and FIT-derived power bests/coverage — as trends in one call. Use this before any single-activity comparison for race-readiness or fitness-target questions.',
+        inputSchema: { sport: z.string().min(1).optional(), startDate: z.string().date().optional(), endDate: z.string().date().optional() },
+    }, tool('readiness_baseline', async (input) => useRepository(activePaths(), (repository) => new FitnessService(repository).readinessBaseline(input))));
+    registerTool('resolve_event_course', {
+        title: 'Resolve a race event course and its synced geometry',
+        description: 'Given a Garmin/Intervals eventId, return the courseId it references and whether that course geometry has been synced. When geometry is absent, the result carries an explicit caveat so a prior course profile is never reused. Optionally pass pastActivityId to diff the event course against that activity\'s course.',
+        inputSchema: { eventId: z.string().min(1), pastActivityId: z.string().min(1).optional() },
+    }, tool('resolve_event_course', async (input) => useRepository(activePaths(), async (repository) => {
+        const events = new EventsService(repository);
+        const resolved = await events.resolveEventCourse(input.eventId);
+        const diff = input.pastActivityId ? await events.diffCourseProfiles(resolved.courseId, input.pastActivityId) : null;
+        return {
+            data: { event: resolved, courseDiff: diff },
+            provenance: { relation: 'source_entities' },
+            caveats: [...resolved.caveats, ...(diff?.caveats ?? [])],
+        };
+    })));
+    registerTool('get_vo2max_history', {
         title: 'Get sport-specific VO₂max history',
         description: 'Return normalized Garmin VO₂max observations for exactly one sport. For running, pass sport: running (or run): Garmin supplies that series with raw sport generic, which is preserved in each row. Cycling remains separate. Omit sport only to inspect available source labels. Read-only.',
         inputSchema: { sport: z.string().min(1).optional(), startDate: z.string().date().optional(), endDate: z.string().date().optional() },
     }, tool('get_vo2max_history', async (input) => useRepository(activePaths(), (repository) => new FitnessService(repository).vo2MaxHistory(input))));
-    server.registerTool('find_activities', {
+    registerTool('find_activities', {
         title: 'Find activities and likely races',
         description: 'Find canonical activities by sport, distance, name, and date. Results are paginated and transparently flag likely-race signals without claiming provider-confirmed race metadata. Read-only.',
         inputSchema: {
+            sport: z.string().min(1).optional(),
             sports: z.array(z.string().min(1)).min(1).max(12).optional(),
             distanceKm: z.tuple([z.number().min(0), z.number().min(0)]).optional(),
             nameContains: z.array(z.string().min(1)).min(1).max(12).optional(),
@@ -409,17 +469,17 @@ export function createCatenceMcpServer(paths = resolveCatalogPaths(), dependenci
             sort: z.enum(['date_desc', 'date_asc']).optional(), limit: z.number().int().min(1).max(100).optional(), cursor: z.string().min(1).optional(),
         },
     }, tool('find_activities', async (input) => useRepository(activePaths(), (repository) => new ActivityDiscoveryService(repository).findActivities(input))));
-    server.registerTool('get_swim_laps', {
+    registerTool('get_swim_laps', {
         title: 'Read explicit swim lengths and grouped sets',
         description: 'Return source-aware swim lengths when a provider actually supplied them, plus Garmin detected and Intervals.icu auto-detected sets. A missing length list is reported as unavailable; laps are never reconstructed from samples.',
         inputSchema: { activityId: z.string().min(1), provider: z.enum(['garmin', 'intervals']).optional() },
     }, tool('get_swim_laps', async (input) => useRepository(activePaths(), (repository) => new SwimmingService(repository).swimLaps(input))));
-    server.registerTool('swim_progress_report', {
+    registerTool('swim_progress_report', {
         title: 'Build a source-aware swim progress report',
         description: 'Compare Garmin swimming summaries and data completeness over a date range, optionally within one pool length. It does not derive pace trends from moving time divided by distance.',
         inputSchema: { startDate: z.string().date().optional(), endDate: z.string().date().optional(), poolLengthM: z.number().positive().max(200).optional() },
     }, tool('swim_progress_report', async (input) => useRepository(activePaths(), (repository) => new SwimmingService(repository).swimProgressReport(input))));
-    server.registerTool('get_activity_segments', {
+    registerTool('get_activity_segments', {
         title: 'Hydrate and read an activity’s Strava segments',
         description: 'For a selected activity’s segments, climbs, KOM/PRs, or per-segment analysis: automatically hydrate the matching Strava activity before returning its persisted segment efforts. Use this before saying segment data is unavailable.',
         inputSchema: { activityId: z.string().min(1), refresh: z.boolean().optional(), limit: z.number().int().min(1).max(500).optional() },
@@ -437,35 +497,35 @@ export function createCatenceMcpServer(paths = resolveCatalogPaths(), dependenci
             ],
         };
     }));
-    server.registerTool('power_curve_trend', {
+    registerTool('power_curve_trend', {
         title: 'Read labelled power-curve trends',
         description: 'Return monthly bests for selected power durations from an explicit sport or sport family, including the supporting activity and source type. Read-only.',
         inputSchema: { sport: z.string().min(1).optional(), sportFamily: z.enum(['cycling', 'running']).optional(), durations: z.array(z.number().int().min(1).max(86_400)).min(1).max(12).optional(), startDate: z.string().date().optional(), endDate: z.string().date().optional(), sourceQuality: z.enum(['all', 'garmin_fit_derived']).optional() },
     }, tool('power_curve_trend', async (input) => useRepository(activePaths(), (repository) => new FitnessService(repository).powerCurveTrend(input))));
-    server.registerTool('power_coverage_report', {
+    registerTool('power_coverage_report', {
         title: 'Inspect FIT-derived power coverage',
         description: 'Report powered activities and the complete duration-best inventory for an explicit sport or sport family. Uses Garmin FIT-derived power, not sparse activity summaries. Read-only.',
         inputSchema: { sport: z.string().min(1).optional(), sportFamily: z.enum(['cycling', 'running']).optional(), startDate: z.string().date().optional(), endDate: z.string().date().optional(), sourceQuality: z.enum(['all', 'garmin_fit_derived']).optional() },
     }, tool('power_coverage_report', async (input) => useRepository(activePaths(), (repository) => new FitnessService(repository).powerCoverageReport(input))));
-    server.registerTool('latest_cycling_activities', {
+    registerTool('latest_cycling_activities', {
         title: 'List latest cycling activities',
         description: 'List Garmin cycling source records without duplicate Intervals summaries, optionally flagging multisport parent records. Read-only.',
         inputSchema: { startDate: z.string().date().optional(), endDate: z.string().date().optional(), includeMultisport: z.boolean().optional(), limit: z.number().int().min(1).max(100).optional() },
     }, tool('latest_cycling_activities', async (input) => useRepository(activePaths(), (repository) => new FitnessService(repository).latestCyclingActivities(input))));
-    server.registerTool('cycling_progress_report', {
+    registerTool('cycling_progress_report', {
         title: 'Build a cycling progress report',
         description: 'Combine source-aware FTP and VO₂max histories with monthly canonical volume/load and labelled power-curve trends. Read-only and descriptive.',
         inputSchema: { startDate: z.string().date().optional(), endDate: z.string().date().optional() },
     }, tool('cycling_progress_report', async (input) => useRepository(activePaths(), (repository) => new FitnessService(repository).cyclingProgressReport(input))));
-    server.registerTool('query_read_only_data', {
+    registerTool('query_read_only_data', {
         title: 'Query cataloged read-only data', description: 'Advanced fallback after describe_data/describe_dataset: one parameterized SELECT or WITH … SELECT over cataloged views only. Do not query information_schema, DuckDB system tables, or uncataloged physical relations. Results use deterministic cursor pagination and always report whether they are incomplete. Filesystem access, extensions, DDL, and mutation are rejected.',
         inputSchema: { sql: z.string().min(1).max(20_000), values: z.record(z.string(), z.union([z.string(), z.number(), z.boolean(), z.null()])).refine((value) => Object.keys(value).length <= 100, 'At most 100 bind values are allowed.').optional(), cursor: z.string().min(1).optional(), pageSize: z.number().int().min(1).max(500).optional() },
     }, tool('query_read_only_data', async (input) => useRepository(activePaths(), (repository) => queryReadOnlyData(repository, input))));
-    server.registerTool('search_context', {
+    registerTool('search_context', {
         title: 'Search generated context', description: 'Search compact generated activity, plan, nutrition, and message context. Results identify authoritative follow-up tools rather than making numerical claims.',
         inputSchema: { query: z.string().min(2).max(500), filters: z.array(z.object({ column: z.enum(['provider', 'entity_type', 'occurred_on']), op: z.enum(['eq', 'in', 'between']), value: z.unknown() })).max(20).optional(), limit: z.number().int().min(1).max(50).optional() },
     }, tool('search_context', async (input) => useRepository(activePaths(), (repository) => searchContext(repository, input))));
-    server.registerTool('hydrate_strava_activity', {
+    registerTool('hydrate_strava_activity', {
         title: 'Hydrate one activity from Strava',
         description: 'Write-only targeted enrichment. Safely matches exactly one Catence activity/source to Strava, then archives and persists its activity detail, gear assignment, and segment efforts. For a segment/climb request, prefer get_activity_segments, which invokes this prerequisite automatically.',
         inputSchema: { activityId: z.string().min(1), refresh: z.boolean().optional() },
@@ -473,7 +533,7 @@ export function createCatenceMcpServer(paths = resolveCatalogPaths(), dependenci
         const data = await hydrateActivity(activePaths(), input.activityId, input.refresh ?? false);
         return { data, coverage: await useRepository(activePaths(), (repository) => repository.coverage()), provenance: { provider: 'strava', operation: 'activity_detail', archivedBeforeNormalization: true }, caveats: ['Segment verification is unavailable from Strava public segment data and is never inferred.'] };
     }));
-    server.registerTool('hydrate_recent_strava_activities', {
+    registerTool('hydrate_recent_strava_activities', {
         title: 'Hydrate several recent Strava activities',
         description: 'Write-only targeted batch enrichment. Select an explicit list or a bounded date/sport window; Catence hydrates one activity at a time and reports every outcome.',
         inputSchema: z.object({
@@ -541,7 +601,7 @@ export function createCatenceMcpServer(paths = resolveCatalogPaths(), dependenci
             caveats: ['Each write is intentionally awaited before the next one, preventing data-directory lock contention.', 'not_found and ambiguous results include match diagnostics when Strava supplied them.'],
         };
     }));
-    server.registerTool('hydrate_strava_segment_history', {
+    registerTool('hydrate_strava_segment_history', {
         title: 'Hydrate one Strava segment history',
         description: 'Write-only targeted enrichment. Fetches a persisted Strava segment and the authenticated athlete’s paged historic efforts; interrupted or throttled work is resumable.',
         inputSchema: { segmentId: z.string().min(1), refresh: z.boolean().optional() },
@@ -597,6 +657,13 @@ export function createCatenceMcpServer(paths = resolveCatalogPaths(), dependenci
             }
         });
     }
+    server.registerResource('tools', 'catence://tools', { title: 'Catence tool index', mimeType: 'application/json' }, async (uri) => {
+        return resource(uri, {
+            count: TOOL_INDEX.length,
+            note: 'If a needed tool is not visible in your current tool list (the host may truncate it), use this index to discover all available tools before concluding a capability is absent. SQL-only tables training_metric_observations and source_entities are reachable via query_read_only_data / describe_data.',
+            tools: TOOL_INDEX.map((tool) => ({ name: tool.name, purpose: tool.title, description: tool.description })),
+        });
+    });
     return server;
 }
 function variable(value) {

package/dist/runtime/index.d.ts

@@ -23,6 +23,7 @@ export type { DataFilter } from '../core/query/analytics.js';
 export { ActivityDiscoveryService } from '../core/query/activity-discovery.js';
 export { DATASET_CATALOG, getDataset, QueryValidationError } from '../core/query/catalog.js';
 export { FitnessService } from '../core/query/fitness.js';
+export { EventsService, extractCourseId } from '../core/query/events.js';
 export { SwimmingService } from '../core/query/swimming.js';
 export { WELLNESS_METRICS, WellnessService } from '../core/query/wellness.js';
 export { jsonSafe, ReadOnlyRepository } from '../core/query/repository.js';
@@ -35,6 +36,7 @@ export type { DetachedSyncHandle, DetachedSyncProvider, DetachedSyncRequest, Det
 export { buildOpenCodeGoConsoleProfiles, classifyOpenCodeGoModel, fetchOpenCodeGoModelIds, mergeOpenCodeGoConsoleProfiles, OPENCODE_GO_API_BASE_ENV, OPENCODE_GO_API_KEY_ENV, OPENCODE_GO_DEFAULT_BASE_URL, OPENCODE_GO_MESSAGES_API_BASE_ENV, } from '../core/runtime/opencode-go.js';
 export type { OpenCodeGoConsoleProfiles, OpenCodeGoMergeResult, OpenCodeGoRoute } from '../core/runtime/opencode-go.js';
 export type { InterruptedRuns, SyncProgressSnapshot, SyncProgressState } from '../contracts/progress.js';
-export { openReadOnlyRepository, ReadOnlyDatabaseError } from '../elt/storage/database.js';
+export { CatenceDatabase, openReadOnlyRepository, ReadOnlyDatabaseError } from '../elt/storage/database.js';
 export { DataWriteBusyError } from '../elt/storage/write-lock.js';
+export { migrations } from '../elt/storage/migrations.js';
 export { hydrateStravaActivity, hydrateStravaSegmentHistory, StravaEnrichmentError, StravaRateLimitError, } from '../elt/ingestion/providers/strava/service.js';

package/dist/runtime/index.js

@@ -10,6 +10,7 @@ export { AnalyticsService } from '../core/query/analytics.js';
 export { ActivityDiscoveryService } from '../core/query/activity-discovery.js';
 export { DATASET_CATALOG, getDataset, QueryValidationError } from '../core/query/catalog.js';
 export { FitnessService } from '../core/query/fitness.js';
+export { EventsService, extractCourseId } from '../core/query/events.js';
 export { SwimmingService } from '../core/query/swimming.js';
 export { WELLNESS_METRICS, WellnessService } from '../core/query/wellness.js';
 export { jsonSafe, ReadOnlyRepository } from '../core/query/repository.js';
@@ -18,7 +19,8 @@ export { createDemoStore, demoStoreMetadata } from '../elt/application/demo.js';
 export { connectStrava, connectStravaWithCallback, dataStatus, disconnectStravaAccount, initializeDataStore, importStagedFile, linkActivity, rebuildRetrievalIndex, reimportNutrition, resolveExtractionErrors, retryDataSync, syncData, syncProgress, unlinkActivity, } from '../elt/application/management.js';
 export { DETACHED_SYNC_PROVIDERS, DetachedSyncBusyError, startDetachedSync, } from '../elt/application/detached-sync.js';
 export { buildOpenCodeGoConsoleProfiles, classifyOpenCodeGoModel, fetchOpenCodeGoModelIds, mergeOpenCodeGoConsoleProfiles, OPENCODE_GO_API_BASE_ENV, OPENCODE_GO_API_KEY_ENV, OPENCODE_GO_DEFAULT_BASE_URL, OPENCODE_GO_MESSAGES_API_BASE_ENV, } from '../core/runtime/opencode-go.js';
-export { openReadOnlyRepository, ReadOnlyDatabaseError } from '../elt/storage/database.js';
+export { CatenceDatabase, openReadOnlyRepository, ReadOnlyDatabaseError } from '../elt/storage/database.js';
 export { DataWriteBusyError } from '../elt/storage/write-lock.js';
+export { migrations } from '../elt/storage/migrations.js';
 export { hydrateStravaActivity, hydrateStravaSegmentHistory, StravaEnrichmentError, StravaRateLimitError, } from '../elt/ingestion/providers/strava/service.js';
 //# sourceMappingURL=index.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "catence",
-  "version": "0.2.0-beta.21",
+  "version": "0.2.0-beta.24",
   "description": "Local MCP access to normalized Garmin, Intervals.icu, and targeted Strava fitness data.",
   "license": "AGPL-3.0-or-later",
   "repository": {

package/python/catence/providers/garmin/registry.py

@@ -33,6 +33,7 @@ GARMIN_READ_METHODS = {
     ),
     "workouts": ("get_workouts", "get_scheduled_workouts"),
     "events": ("get_events",),
+    "course": ("connectapi",),
     "goals": ("get_goals",),
     "gear": ("get_gear",),
     "golf": ("get_golf_summary",),

package/python/catence/providers/garmin/worker.py

@@ -8,7 +8,7 @@ from typing import Any, Callable, Mapping
 
 from .progress import ProgressReporter
 from .registry import GARMIN_READ_METHODS, assert_read_only_registry
-from .staging import StagingWriter
+from .staging import StagingWriter, safe_segment
 from .streams import SAMPLE_COLUMNS, activity_details_to_samples, activity_power_bests, fit_archive_to_samples, fit_archive_to_swim_lengths, write_parquet
 
 
@@ -794,9 +794,37 @@ class GarminStagingWorker:
         if self.progress is not None:
             self.progress.advance(completed=len(calls) + len(months) + 1)
 
+    def stage_course(self, course_id: str) -> None:
+        """Fetch one Garmin course by id and stage it as a source entity.
+
+        garminconnect 0.3.x exposes no first-class course method, so this uses
+        the authenticated Connect API directly:
+        ``connectapi("course-service/course/{course_id}")``. Validated against a
+        live account (returns course metadata plus a ``geoPoints`` geometry array).
+        Failures are captured per call and reported as extraction errors without
+        aborting the rest of the sync.
+
+        The course is staged with remote_id == course_id (not an auto-derived
+        id) so event resolution can match the courseId an event references.
+        """
+        payload, raw_hash = self._capture(
+            "course",
+            lambda course_id=course_id: self.api.connectapi(f"course-service/course/{course_id}"),
+            course_id,
+        )
+        if payload is not None:
+            self.writer.source_entity("course", course_id, payload, raw_hash, course_id)
+
     def _fetch_garmin_events(self, start_date: str) -> None:
-        """Fetch calendar events from start_date, following pagination."""
+        """Fetch calendar events from start_date, following pagination.
+
+        Any event that references a Garmin course (``courseId``/``course_id``)
+        triggers an automatic course fetch via stage_course, so a race's
+        geometry is synced without a manual recon run. Already-archived courses
+        are skipped to avoid re-fetching unchanged geometry every sync.
+        """
         page = 1
+        discovered_course_ids: set[str] = set()
         while True:
             payload, raw_hash = self._capture(
                 "garmin_events",
@@ -806,6 +834,20 @@ class GarminStagingWorker:
             items = payload if isinstance(payload, list) else []
             if items:
                 self._entity("garmin_events", "event", items, raw_hash)
+                for item in items:
+                    if isinstance(item, Mapping):
+                        course_id = item.get("courseId") or item.get("course_id")
+                        if course_id:
+                            discovered_course_ids.add(str(course_id))
             if len(items) < 100:
-                return
+                break
             page += 1
+        for course_id in sorted(discovered_course_ids):
+            self._check_interrupted()
+            if not self._course_archived(course_id):
+                self.stage_course(course_id)
+
+    def _course_archived(self, course_id: str) -> bool:
+        """True when a course archive already exists under raw/garmin/course/{id}."""
+        directory = self.data_dir / "raw" / "garmin" / "course" / safe_segment(course_id)
+        return directory.is_dir() and any(directory.glob("*.json"))