catence 0.2.0-beta.9 → 0.2.1-beta.1

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, FitnessService, getDataset, hydrateStravaActivity, hydrateStravaSegmentHistory, jsonSafe, loadCatenceConfig, openReadOnlyRepository, queryReadOnlyData, QueryValidationError, ReadOnlyDatabaseError, resolveAthlete, resolveCatalogPaths, searchContext, SlidingWindowLimiter, 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,22 +27,33 @@ 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 or call discover_tools to inventory every available tool before concluding a capability is absent.',
+    'To find a next or upcoming race: list dates with aggregate_data on the events dataset (group or filter by occurred_on), identify the event name via search_context or its payload, then call resolve_event_course(eventId) to resolve the courseId and whether that course geometry is synced.',
+    'For a course elevation/height profile or GPX track: call resolve_event_course(eventId) first (it reports the courseId, synced geometry, and geometry sample count), then read the course_geometry dataset with read_series / aggregate_data / query_read_only_data for per-point altitude_m, lat, lon, and distance_m. Never claim a profile is absent before resolve_event_course returns.',
+    'Never treat a tool error or empty result as a dead end: switch strategy or re-read the routing guidance before re-running the same query.',
+    '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) }] };
 }
 function errorResult(error) {
-    const classified = error instanceof DataWriteBusyError
-        ? { code: 'data_sync_in_progress', message: error.message, retryable: true }
-        : error instanceof StravaRateLimitError
-            ? { code: 'rate_limited', message: error.message, retryable: true, retryAfterSeconds: error.retryAfterSeconds ?? null }
-            : error instanceof StravaEnrichmentError
-                ? { code: 'strava_connection_error', message: error.message }
-                : error instanceof ReadOnlyDatabaseError
-                    ? { code: error.code, message: error.message }
-                    : error instanceof QueryValidationError
-                        ? { code: 'invalid_request', message: error.message }
-                        : { code: 'data_unavailable', message: error instanceof Error ? error.message : String(error) };
+    const classified = error instanceof DetachedSyncBusyError
+        ? { code: 'sync_in_progress', message: error.message, retryable: true, runId: error.runId }
+        : error instanceof DataWriteBusyError
+            ? { code: 'data_sync_in_progress', message: error.message, retryable: true }
+            : error instanceof StravaRateLimitError
+                ? { code: 'rate_limited', message: error.message, retryable: true, retryAfterSeconds: error.retryAfterSeconds ?? null }
+                : error instanceof StravaEnrichmentError
+                    ? { code: 'strava_connection_error', message: error.message }
+                    : error instanceof ReadOnlyDatabaseError
+                        ? { code: error.code, message: error.message }
+                        : error instanceof QueryValidationError
+                            ? { code: 'invalid_request', message: error.message }
+                            : { code: 'data_unavailable', message: error instanceof Error ? error.message : String(error) };
     return { ...textResult({ data: null, provenance: {}, query: {}, caveats: [classified.message], error: classified }), isError: true };
 }
 function hydrationFailure(error) {
@@ -123,6 +134,7 @@ async function activitySegments(repository, activityId, hydratedStravaActivityId
 export function createCatenceMcpServer(paths = resolveCatalogPaths(), dependencies = {}) {
     const server = new McpServer({ name: 'catence', version: '0.1.0' }, { instructions: MCP_INSTRUCTIONS });
     const hydrateActivity = dependencies.hydrateStravaActivity ?? hydrateStravaActivity;
+    const startSync = dependencies.startDetachedSync ?? startDetachedSync;
     const catalogPaths = isCatalogPaths(paths) ? paths : null;
     const staticPaths = isCatalogPaths(paths) ? null : paths;
     const scope = new AsyncLocalStorage();
@@ -130,9 +142,28 @@ 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 ?? '', keywords: config.keywords ?? [] });
+        server.registerTool(name, config, callback);
+    }
+    // Keyword-rich routing map surfacing the recommended tool chain per question
+    // domain. Surfaced in catence://tools so a host can navigate without knowing
+    // every tool name up front.
+    const TOOL_ROUTING = [
+        { question: 'next race / upcoming event', steps: ['aggregate_data (events, by occurred_on)', 'search_context', 'resolve_event_course'] },
+        { question: 'course elevation / height profile / GPX track', steps: ['resolve_event_course', 'read_series / aggregate_data (course_geometry)'] },
+        { question: 'swim per-length analysis (pace / SPL / SWOLF)', steps: ['find_activities', 'get_swim_laps', 'swim_progress_report'] },
+        { question: 'segments / climbs / KOM / PR', steps: ['get_activity_segments', 'hydrate_strava_segment_history'] },
+        { question: 'race readiness / fitness targets', steps: ['readiness_baseline', 'analyze_series', 'aggregate_data'] },
+        { question: 'recovery / daily or weekly load', steps: ['review_daily_recovery_load', 'review_weekly_training', 'wellness_baselines'] },
+        { question: 'cycling FTP / VO₂max / power curve', steps: ['get_ftp_history', 'get_vo2max_history', 'power_coverage_report', 'power_curve_trend'] },
+    ];
     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 () => {
@@ -147,10 +178,29 @@ export function createCatenceMcpServer(paths = resolveCatalogPaths(), dependenci
         const originalRegister = server.registerTool.bind(server);
         server.registerTool = (name, configuration, handler) => {
             const originalInput = configuration.inputSchema;
+            let mergedInputSchema;
+            if (originalInput) {
+                const hasV4 = '_zod' in originalInput;
+                const hasV3 = '_def' in originalInput;
+                if (hasV4 || hasV3) {
+                    // originalInput is already a Zod object schema; extract its shape and
+                    // merge athleteId into a new object of the same Zod version.
+                    const rawShape = originalInput.shape;
+                    const shape = typeof rawShape === 'object' && rawShape !== null ? rawShape : {};
+                    mergedInputSchema = z.object({ ...shape, athleteId: athleteIdSchema });
+                }
+                else {
+                    // originalInput is a raw shape (plain object of Zod schemas).
+                    mergedInputSchema = { athleteId: athleteIdSchema, ...originalInput };
+                }
+            }
+            else {
+                mergedInputSchema = { athleteId: athleteIdSchema };
+            }
             return originalRegister(name, {
                 ...configuration,
                 description: `${String(configuration.description ?? '')} Requires athleteId from list_athletes.`,
-                inputSchema: { athleteId: athleteIdSchema, ...(originalInput ?? {}) },
+                inputSchema: mergedInputSchema,
             }, handler);
         };
     }
@@ -176,7 +226,12 @@ export function createCatenceMcpServer(paths = resolveCatalogPaths(), dependenci
                     ...(demoStore ? { demoStore: { generated: true, seed: demoStore.seed, days: demoStore.days, startDate: demoStore.startDate, endDate: demoStore.endDate }, caveats: [...caveats, 'This response uses Catence generated demo data, not personal measurements.'] } : {}),
                 });
             };
-            return selected ? scope.run(selected, run) : run();
+            // `return await` matters here: a bare `return run()` would let a
+            // rejected promise escape the try block, bypassing the classified
+            // errorResult payload entirely.
+            if (selected)
+                return await scope.run(selected, run);
+            return await run();
         }
         catch (error) {
             return errorResult(error);
@@ -221,17 +276,46 @@ 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('review_daily_recovery_load', {
+    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: [],
+    }))));
+    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: {
+            provider: z.enum(['intervals', 'garmin', 'strava', 'all']).optional(),
+            from: z.string().date().optional(),
+            refresh: z.boolean().optional(),
+        },
+    }, tool('start_detached_sync', async (input) => {
+        const paths = activePaths();
+        const athleteId = activeAthlete()?.id ?? 'local';
+        const handle = await startSync({ paths, athleteId, provider: input.provider, from: input.from, refresh: input.refresh });
+        return {
+            data: { ...handle, progressTool: 'catence_sync_progress' },
+            provenance: { operation: 'detached_sync_spawn' },
+            query: { ...input },
+            caveats: [
+                'The sync runs in its own process and keeps running if this session ends; its log file records the full worker output.',
+                'Only one sync run may be active per athlete store.',
+            ],
+        };
+    }));
+    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() },
@@ -247,7 +331,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() },
@@ -264,7 +348,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) },
@@ -279,14 +363,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) },
@@ -309,10 +393,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),
@@ -320,15 +404,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: {
@@ -336,35 +447,57 @@ 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.',
+        keywords: ['course', 'race course', 'event course', 'elevation profile', 'height profile', 'GPX track', 'course geometry', 'gradient', 'climb', 'GPS track'],
+        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.',
+        keywords: ['race', 'races', 'next race', 'events', 'upcoming event', 'activity list', 'swim sessions', 'pool sessions', 'laps', 'recent runs'],
         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(),
@@ -372,19 +505,22 @@ 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.',
+        keywords: ['swim', 'swimming', 'per-length', 'pace', 'SPL', 'SWOLF', 'pool', 'lengths', 'laps', 'cadence'],
         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.',
+        keywords: ['swim', 'swimming', 'progress', 'SWOLF', 'fastest 100', 'cadence', 'pool length', 'swim trends'],
         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.',
+        keywords: ['segments', 'climbs', 'KOM', 'PR', 'grade by segment', 'Strava segments', 'segment efforts', 'per-segment analysis'],
         inputSchema: { activityId: z.string().min(1), refresh: z.boolean().optional(), limit: z.number().int().min(1).max(500).optional() },
     }, tool('get_activity_segments', async (input) => {
         const hydration = await hydrateActivity(activePaths(), input.activityId, input.refresh ?? false);
@@ -400,35 +536,36 @@ 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.',
+        keywords: ['event name', 'race name', 'course', 'elevation', 'GPX', 'activity summary', 'plan', 'nutrition', 'find the event'],
         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() },
@@ -436,7 +573,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({
@@ -504,7 +641,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() },
@@ -512,6 +649,19 @@ export function createCatenceMcpServer(paths = resolveCatalogPaths(), dependenci
         const data = await hydrateStravaSegmentHistory(activePaths(), input.segmentId, input.refresh ?? false);
         return { data, coverage: await useRepository(activePaths(), (repository) => repository.coverage()), provenance: { provider: 'strava', operation: 'segment_effort_history', archivedBeforeNormalization: true }, caveats: ['Only the authenticated athlete’s historic segment efforts are requested.'] };
     }));
+    // Registered last so every tool above is present in the tool index before its
+    // one-line catalog is baked into this tool's description. Survives host tool
+    // truncation because tool descriptions are always visible to the model.
+    registerTool('discover_tools', {
+        title: 'Discover all Catence tools and routing',
+        description: [
+            'Inventory the full Catence tool surface even when the host truncates its visible tool list. Query by question: next race/upcoming event (aggregate_data on events, search_context, resolve_event_course), course elevation/height profile/GPX (resolve_event_course then read_series or aggregate_data on course_geometry), swim per-length pace/SPL/SWOLF (find_activities, get_swim_laps, swim_progress_report), segments/climbs/KOM/PR (get_activity_segments), race readiness (readiness_baseline), recovery (review_daily_recovery_load, review_weekly_training), cycling FTP/VO₂max/power (get_ftp_history, get_vo2max_history, power_coverage_report, power_curve_trend).',
+            ...TOOL_INDEX.map((entry) => `${entry.name} — ${entry.title}`),
+        ].join('\n'),
+    }, tool('discover_tools', async () => ({
+        data: { count: TOOL_INDEX.length, routing: TOOL_ROUTING, tools: TOOL_INDEX.map((entry) => ({ name: entry.name, purpose: entry.title, keywords: entry.keywords })) },
+        provenance: { catalog: 'Catence tool index' }, query: {}, caveats: ['Use this to map a question to its named tool before falling back to SQL.'],
+    })));
     if (catalogPaths) {
         server.registerResource('athletes', 'catence://athletes', { title: 'Configured athlete roster', mimeType: 'application/json' }, async (uri) => {
             try {
@@ -560,6 +710,14 @@ 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.',
+            routing: TOOL_ROUTING,
+            tools: TOOL_INDEX.map((tool) => ({ name: tool.name, purpose: tool.title, description: tool.description, keywords: tool.keywords })),
+        });
+    });
     return server;
 }
 function variable(value) {

package/dist/runtime/index.d.ts

@@ -23,13 +23,20 @@ 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';
 export { queryReadOnlyData } from '../core/query/sql-guard.js';
 export { createDemoStore, demoStoreMetadata } from '../elt/application/demo.js';
-export { connectStrava, connectStravaWithCallback, dataStatus, disconnectStravaAccount, initializeDataStore, linkActivity, rebuildRetrievalIndex, retryDataSync, syncData, unlinkActivity, } from '../elt/application/management.js';
+export { connectStrava, connectStravaWithCallback, dataStatus, disconnectStravaAccount, initializeDataStore, importStagedFile, linkActivity, rebuildRetrievalIndex, reimportNutrition, resolveExtractionErrors, retryDataSync, syncData, syncProgress, unlinkActivity, } from '../elt/application/management.js';
 export type { ProviderChoice } from '../elt/application/management.js';
-export { openReadOnlyRepository, ReadOnlyDatabaseError } from '../elt/storage/database.js';
+export { DETACHED_SYNC_PROVIDERS, DetachedSyncBusyError, startDetachedSync, } from '../elt/application/detached-sync.js';
+export type { DetachedSyncHandle, DetachedSyncProvider, DetachedSyncRequest, DetachedSyncSpawner } 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 type { OpenCodeGoConsoleProfiles, OpenCodeGoMergeResult, OpenCodeGoRoute } from '../core/runtime/opencode-go.js';
+export type { InterruptedRuns, SyncProgressSnapshot, SyncProgressState } from '../contracts/progress.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,13 +10,17 @@ 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';
 export { queryReadOnlyData } from '../core/query/sql-guard.js';
 export { createDemoStore, demoStoreMetadata } from '../elt/application/demo.js';
-export { connectStrava, connectStravaWithCallback, dataStatus, disconnectStravaAccount, initializeDataStore, linkActivity, rebuildRetrievalIndex, retryDataSync, syncData, unlinkActivity, } from '../elt/application/management.js';
-export { openReadOnlyRepository, ReadOnlyDatabaseError } from '../elt/storage/database.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 { 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/docs/architecture.md

@@ -74,7 +74,7 @@ Normalized tables preserve provenance rather than force an early merge:
 
 ### 3. Queries, tools and methods
 
-The MCP process is a separate stdio consumer. Ordinary tools and resources open DuckDB `READ_ONLY` snapshots. The only write capabilities are the explicit `hydrate_strava_activity`, serial `hydrate_recent_strava_activities`, and `hydrate_strava_segment_history` tools: each acquires the shared data-directory lock, calls only the Strava GET allowlist, archives responses before normalization, commits, and releases the lock. If another writer owns it, the result is retryable `data_sync_in_progress`.
+The MCP process is a separate stdio consumer. Ordinary tools and resources open DuckDB `READ_ONLY` snapshots. The only direct database writers are the explicit `hydrate_strava_activity`, serial `hydrate_recent_strava_activities`, and `hydrate_strava_segment_history` tools: each acquires the shared data-directory lock, calls only the Strava GET allowlist, archives responses before normalization, commits, and releases the lock. If another writer owns it, the result is retryable `data_sync_in_progress`. `start_detached_sync` is also a write tool: it spawns a detached `catence-data sync` child process (which acquires the lock itself) and returns immediately with the run handle.
 
 The query layer has four shared pieces:
 
@@ -87,7 +87,18 @@ The query layer has four shared pieces:
 
 ### 4. Serving and retrieval
 
-The server exposes `catence_status`, `describe_data`, `describe_dataset`, `read_series`, `aggregate_data`, `analyze_series`, `fit_series_model`, `query_read_only_data`, `find_activities`, `get_ftp_history`, `get_vo2max_history`, `power_curve_trend`, `power_coverage_report`, `latest_cycling_activities`, `cycling_progress_report`, `review_daily_recovery_load`, `review_weekly_training`, `review_activity_deep_dive`, `search_context`, `hydrate_strava_activity`, `hydrate_recent_strava_activities`, and `hydrate_strava_segment_history`, plus resources for status, catalog, a single activity, and a date-range summary.
+The server exposes these tools, grouped by purpose:
+
+- Catalog and status: `list_athletes`, `catence_status`, `catence_sync_progress`.
+- Review workflows: `review_daily_recovery_load`, `review_weekly_training`, `review_activity_deep_dive`, plus the matching `daily_recovery_load_review`, `weekly_training_review`, and `activity_deep_dive` prompts.
+- General data and analytics: `describe_data`, `describe_dataset`, `read_series`, `aggregate_data`, `analyze_series`, `fit_series_model`, `query_read_only_data`, `search_context`.
+- Wellness: `wellness_correlate`, `wellness_baselines`, `wellness_anomalies`, `wellness_coverage`.
+- Fitness, readiness, and progress: `get_ftp_history`, `get_vo2max_history`, `readiness_baseline`, `power_curve_trend`, `power_coverage_report`, `activity_decoupling`, `latest_cycling_activities`, `cycling_progress_report`, `get_swim_laps`, `swim_progress_report`.
+- Activity detail and segments: `find_activities`, `get_activity_segments`, `resolve_event_course`.
+- Background sync (write): `start_detached_sync` — spawns a detached `catence-data sync` child process and returns immediately; track progress with `catence_sync_progress`.
+- Strava hydration (the only direct database writers): `hydrate_strava_activity`, `hydrate_recent_strava_activities`, `hydrate_strava_segment_history`.
+
+Resources are mode-dependent. In catalog mode the server registers only `athletes` (`catence://athletes`), the machine-readable roster of configured athlete IDs and labels; in a single-store (non-catalog) deployment it registers resources for status, catalog, a single activity template (`catence://activity/{activityId}`), and a date-range summary template (`catence://summary/{startDate}/{endDate}`). Both modes also register `tools` (`catence://tools`), a machine-readable index of all registered tools — useful when a host truncates the tool list.
 
 `catence serve` is a loopback-only-by-default Streamable HTTP adapter. It creates a stateless MCP server and transport for each `/mcp` request, so the HTTP and stdio surfaces use the same tool implementation. `GET /health` is a versioned client handshake with runtime version, protocol version, and capabilities; distributed Console builds reject an incompatible protocol before starting a chat. The same listener serves a small read-only `/api/v1/dashboard` snapshot for the local Console: canonical daily-health rows, weekly canonical activity aggregates, recent canonical activities, status, coverage, and explicit missing-data caveats.