catence 0.1.0 → 0.2.0-beta.2

package/dist/interfaces/mcp/cli-options.d.ts

@@ -1,6 +1,6 @@
 export type McpCliOptions = {
-    dataDir?: string;
+    home?: string;
     help: boolean;
 };
-export declare const MCP_USAGE = "Usage: catence [--data-dir <directory>]\n       catence demo [--data-dir <directory>]\n\nRun Catence as a local, stdio-only MCP server. Ordinary data access is read-only; only declared Strava hydration tools write through the locked local store.\n\nThe demo command creates safe generated data in ./catence-demo by default, then starts the same MCP server. It refuses to overwrite a non-demo data directory.\n\nOptions:\n  --data-dir <directory>  Catence data directory. Overrides CATENCE_DATA_DIR.\n  -h, --help              Show this help text.";
+export declare const MCP_USAGE = "Usage: catence [--home <directory>]\n       catence demo [--home <directory>]\n\nRun Catence as a local, stdio-only MCP server. Ordinary data access is read-only; only declared Strava hydration tools write through the locked local store.\n\nThe demo command creates safe generated data in ~/.catence-demo by default, then starts the same shared-athlete MCP server. It refuses to overwrite a non-demo athlete store.\n\nOptions:\n  --home <directory>      Catence catalog home. Defaults to CATENCE_HOME or ~/.catence.\n  -h, --help              Show this help text.";
 export declare function parseMcpCliOptions(arguments_: readonly string[]): McpCliOptions;

package/dist/interfaces/mcp/cli-options.js

@@ -1,36 +1,36 @@
-export const MCP_USAGE = `Usage: catence [--data-dir <directory>]
-       catence demo [--data-dir <directory>]
+export const MCP_USAGE = `Usage: catence [--home <directory>]
+       catence demo [--home <directory>]
 
 Run Catence as a local, stdio-only MCP server. Ordinary data access is read-only; only declared Strava hydration tools write through the locked local store.
 
-The demo command creates safe generated data in ./catence-demo by default, then starts the same MCP server. It refuses to overwrite a non-demo data directory.
+The demo command creates safe generated data in ~/.catence-demo by default, then starts the same shared-athlete MCP server. It refuses to overwrite a non-demo athlete store.
 
 Options:
-  --data-dir <directory>  Catence data directory. Overrides CATENCE_DATA_DIR.
+  --home <directory>      Catence catalog home. Defaults to CATENCE_HOME or ~/.catence.
   -h, --help              Show this help text.`;
 export function parseMcpCliOptions(arguments_) {
-    let dataDir;
+    let home;
     for (let index = 0; index < arguments_.length; index++) {
         const argument = arguments_[index];
         if (argument === '-h' || argument === '--help')
-            return { dataDir, help: true };
-        if (argument === '--data-dir') {
+            return { home, help: true };
+        if (argument === '--home') {
             const value = arguments_[index + 1];
             if (!value || value.startsWith('-'))
-                throw new Error('--data-dir requires a directory.');
-            dataDir = value;
+                throw new Error('--home requires a directory.');
+            home = value;
             index++;
             continue;
         }
-        if (argument.startsWith('--data-dir=')) {
-            const value = argument.slice('--data-dir='.length);
+        if (argument.startsWith('--home=')) {
+            const value = argument.slice('--home='.length);
             if (!value)
-                throw new Error('--data-dir requires a directory.');
-            dataDir = value;
+                throw new Error('--home requires a directory.');
+            home = value;
             continue;
         }
         throw new Error(`Unknown option: ${argument}`);
     }
-    return { dataDir, help: false };
+    return { home, help: false };
 }
 //# sourceMappingURL=cli-options.js.map

package/dist/interfaces/mcp/main.js

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
-import { createDemoStore, resolvePaths } from '../../runtime/index.js';
+import { existsSync } from 'node:fs';
+import { addAthlete, athleteStorePaths, 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';
@@ -14,7 +15,7 @@ async function run() {
             return;
         }
         const httpServer = createCatenceHttpServer({
-            paths: resolvePaths(options.dataDir),
+            catalogPaths: resolveCatalogPaths(options.home),
             allowedOrigins: options.allowedOrigins,
         });
         await new Promise((resolve, reject) => {
@@ -38,13 +39,19 @@ async function run() {
         process.stderr.write(`${MCP_USAGE}\n`);
         return;
     }
-    const dataDir = options.dataDir ?? (demo ? process.env.CATENCE_DATA_DIR ?? './catence-demo' : undefined);
-    const paths = resolvePaths(dataDir);
+    const catalogPaths = resolveCatalogPaths(demo && !options.home ? `${defaultCatalogHome()}-demo` : options.home);
     if (demo) {
+        if (!existsSync(catalogPaths.catalog)) {
+            await initializeCatalog(catalogPaths, { id: 'demo', label: 'Generated demo athlete' });
+        }
+        else if (!(await loadCatalog(catalogPaths)).athletes.some((athlete) => athlete.id === 'demo')) {
+            await addAthlete(catalogPaths, { id: 'demo', label: 'Generated demo athlete' });
+        }
+        const paths = athleteStorePaths(catalogPaths, 'demo');
         const result = await createDemoStore(paths);
         process.stderr.write(`${String(result.message)}\n`);
     }
-    const server = createCatenceMcpServer(paths);
+    const server = createCatenceMcpServer(catalogPaths);
     await server.connect(new StdioServerTransport());
     console.error('Catence MCP server is running on stdio; ordinary tools are read-only and Strava hydration is lock-guarded.');
 }

package/dist/interfaces/mcp/server.d.ts

@@ -1,8 +1,8 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-import { hydrateStravaActivity, type CatencePaths } from '../../runtime/index.js';
+import { type CatalogPaths, hydrateStravaActivity, type CatencePaths } from '../../runtime/index.js';
 type StravaActivityHydrator = typeof hydrateStravaActivity;
 type McpDependencies = {
     hydrateStravaActivity?: StravaActivityHydrator;
 };
-export declare function createCatenceMcpServer(paths?: CatencePaths, dependencies?: McpDependencies): McpServer;
+export declare function createCatenceMcpServer(paths?: CatencePaths | CatalogPaths, dependencies?: McpDependencies): McpServer;
 export {};

package/dist/interfaces/mcp/server.js

@@ -1,6 +1,7 @@
 import { McpServer, ResourceTemplate } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { AsyncLocalStorage } from 'node:async_hooks';
 import { z } from 'zod';
-import { ActivityDiscoveryService, AnalyticsService, configuredMcpRateLimit, DataWriteBusyError, DATASET_CATALOG, demoStoreMetadata, FitnessService, getDataset, hydrateStravaActivity, hydrateStravaSegmentHistory, jsonSafe, loadCatenceConfig, openReadOnlyRepository, queryReadOnlyData, QueryValidationError, ReadOnlyDatabaseError, resolvePaths, searchContext, SlidingWindowLimiter, StravaEnrichmentError, StravaRateLimitError, SwimmingService, WELLNESS_METRICS, WellnessService, } from '../../runtime/index.js';
+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';
 const filterSchema = z.object({
     column: z.string().min(1),
     op: z.enum(['eq', 'neq', 'gt', 'gte', 'lt', 'lte', 'in', 'between', 'contains']),
@@ -18,6 +19,9 @@ const seriesInput = {
     cursor: z.string().min(1).optional(),
     pageSize: z.number().int().min(1).max(1_000).optional(),
 };
+function isCatalogPaths(value) {
+    return 'catalog' in value;
+}
 const MCP_INSTRUCTIONS = [
     'For a selected activity\'s Strava segments, climb segments, grade by segment, KOM/PR, or per-segment analysis, call get_activity_segments after identifying the activity.',
     '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.',
@@ -116,29 +120,63 @@ async function activitySegments(repository, activityId, hydratedStravaActivityId
     LIMIT $limit
   `, values);
 }
-export function createCatenceMcpServer(paths = resolvePaths(), dependencies = {}) {
+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 configPromise = loadCatenceConfig(paths);
-    const demoStorePromise = demoStoreMetadata(paths);
+    const catalogPaths = isCatalogPaths(paths) ? paths : null;
+    const staticPaths = isCatalogPaths(paths) ? null : paths;
+    const scope = new AsyncLocalStorage();
+    const activePaths = () => scope.getStore()?.paths ?? staticPaths ?? (() => { throw new Error('athleteId is required. Call list_athletes to inspect the configured catalog.'); })();
+    const activeAthlete = () => scope.getStore()?.athlete;
     const limiter = new SlidingWindowLimiter();
-    const tool = (name, fn) => async (input) => {
+    const athleteIdSchema = z.string().regex(/^[a-z][a-z0-9-]{0,62}$/);
+    const promptAthleteSchema = catalogPaths ? { athleteId: athleteIdSchema } : {};
+    if (catalogPaths) {
+        server.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 () => {
+            try {
+                const catalog = await loadCatalog(catalogPaths);
+                return textResult({ data: { defaultAthleteId: catalog.defaultAthleteId, athletes: catalog.athletes } });
+            }
+            catch (error) {
+                return errorResult(error);
+            }
+        });
+        const originalRegister = server.registerTool.bind(server);
+        server.registerTool = (name, configuration, handler) => {
+            const originalInput = configuration.inputSchema;
+            return originalRegister(name, {
+                ...configuration,
+                description: `${String(configuration.description ?? '')} Requires athleteId from list_athletes.`,
+                inputSchema: { athleteId: athleteIdSchema, ...(originalInput ?? {}) },
+            }, handler);
+        };
+    }
+    const tool = (name, fn) => async (rawInput) => {
         try {
-            const config = await configPromise;
-            const decision = limiter.check(`tool:${name}`, configuredMcpRateLimit(config, 'tools', name));
-            if (!decision.allowed)
-                return { ...textResult({ data: null, error: { code: 'rate_limited', message: `MCP tool ${name} is locally rate limited.`, retryAfterSeconds: decision.retryAfterSeconds } }), isError: true };
-            const value = await fn(input);
-            const demoStore = await demoStorePromise;
-            if (!demoStore || !value || typeof value !== 'object' || Array.isArray(value))
-                return textResult(value);
-            const result = value;
-            const caveats = Array.isArray(result.caveats) ? result.caveats : [];
-            return textResult({
-                ...result,
-                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.'],
-            });
+            const selected = catalogPaths
+                ? await resolveAthlete(catalogPaths, rawInput.athleteId ?? '')
+                : null;
+            const run = async () => {
+                const currentPaths = activePaths();
+                const config = await loadCatenceConfig(currentPaths);
+                const decision = limiter.check(`${activeAthlete()?.id ?? 'local'}:tool:${name}`, configuredMcpRateLimit(config, 'tools', name));
+                if (!decision.allowed)
+                    return { ...textResult({ data: null, ...(activeAthlete() ? { athlete: activeAthlete() } : {}), error: { code: 'rate_limited', message: `MCP tool ${name} is locally rate limited.`, retryAfterSeconds: decision.retryAfterSeconds } }), isError: true };
+                const { athleteId: _athleteId, ...input } = rawInput;
+                const value = await fn(input);
+                const result = value && typeof value === 'object' && !Array.isArray(value) ? value : { data: value };
+                const demoStore = await demoStoreMetadata(currentPaths);
+                const caveats = Array.isArray(result.caveats) ? result.caveats : [];
+                return textResult({
+                    ...result,
+                    ...(activeAthlete() ? { athlete: activeAthlete() } : {}),
+                    ...(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();
         }
         catch (error) {
             return errorResult(error);
@@ -146,7 +184,7 @@ export function createCatenceMcpServer(paths = resolvePaths(), dependencies = {}
     };
     const resourceLimit = async (name, uri) => {
         try {
-            const config = await configPromise;
+            const config = await loadCatenceConfig(activePaths());
             const decision = limiter.check(`resource:${name}`, configuredMcpRateLimit(config, 'resources', name));
             if (!decision.allowed)
                 return resource(uri, { error: { code: 'rate_limited', message: `MCP resource ${name} is locally rate limited.`, retryAfterSeconds: decision.retryAfterSeconds } });
@@ -159,37 +197,37 @@ export function createCatenceMcpServer(paths = resolvePaths(), dependencies = {}
     server.registerPrompt('daily_recovery_load_review', {
         title: 'Daily recovery and load review',
         description: 'Ask for a source-cited recovery and training-load review for one date.',
-        argsSchema: { date: z.string().date().optional() },
-    }, ({ date }) => ({
+        argsSchema: { ...promptAthleteSchema, date: z.string().date().optional() },
+    }, ({ date, ...input }) => ({
         messages: [{
                 role: 'user',
-                content: { type: 'text', text: `Run review_daily_recovery_load for ${date ?? utcDate()}. Summarize only returned evidence, name data gaps, and do not present a training prescription as fact.` },
+                content: { type: 'text', text: `Run review_daily_recovery_load for ${date ?? utcDate()}${typeof input.athleteId === 'string' ? ` with athleteId ${input.athleteId}` : ''}. Summarize only returned evidence, name data gaps, and do not present a training prescription as fact.` },
             }],
     }));
     server.registerPrompt('weekly_training_review', {
         title: 'Weekly training review',
         description: 'Ask for a source-cited seven-day training review ending on an optional date.',
-        argsSchema: { endDate: z.string().date().optional() },
-    }, ({ endDate }) => ({
+        argsSchema: { ...promptAthleteSchema, endDate: z.string().date().optional() },
+    }, ({ endDate, ...input }) => ({
         messages: [{
                 role: 'user',
-                content: { type: 'text', text: `Run review_weekly_training ending on ${endDate ?? utcDate()}. Explain volume, load, and recovery evidence with dates and coverage caveats.` },
+                content: { type: 'text', text: `Run review_weekly_training ending on ${endDate ?? utcDate()}${typeof input.athleteId === 'string' ? ` with athleteId ${input.athleteId}` : ''}. Explain volume, load, and recovery evidence with dates and coverage caveats.` },
             }],
     }));
     server.registerPrompt('activity_deep_dive', {
         title: 'Activity deep dive',
         description: 'Ask for an evidence-first deep dive into one canonical Catence activity.',
-        argsSchema: { activityId: z.string().min(1) },
-    }, ({ activityId }) => ({
+        argsSchema: { ...promptAthleteSchema, activityId: z.string().min(1) },
+    }, ({ activityId, ...input }) => ({
         messages: [{
                 role: 'user',
-                content: { type: 'text', text: `Run review_activity_deep_dive for ${activityId}. 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.` },
             }],
     }));
     server.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(paths, async (repository) => ({
+    }, tool('catence_status', async () => useRepository(activePaths(), async (repository) => ({
         data: { ...(await repository.status()), ...(await repository.coverage()) },
         provenance: { database: 'read-only DuckDB snapshot' }, query: {}, caveats: [],
     }))));
@@ -199,7 +237,7 @@ export function createCatenceMcpServer(paths = resolvePaths(), dependencies = {}
         inputSchema: { date: z.string().date().optional() },
     }, tool('review_daily_recovery_load', async (input) => {
         const date = input.date ?? utcDate();
-        return useRepository(paths, async (repository) => ({
+        return useRepository(activePaths(), async (repository) => ({
             data: { date, ...(await repository.summary(date, date)) },
             provenance: { relations: ['daily_health', 'canonical_activity_training', 'nutrition_days'], database: 'read-only DuckDB snapshot' },
             query: { date },
@@ -216,7 +254,7 @@ export function createCatenceMcpServer(paths = resolvePaths(), dependencies = {}
     }, tool('review_weekly_training', async (input) => {
         const endDate = input.endDate ?? utcDate();
         const startDate = subtractDays(endDate, 6);
-        return useRepository(paths, async (repository) => ({
+        return useRepository(activePaths(), async (repository) => ({
             data: { startDate, endDate, ...(await repository.summary(startDate, endDate)) },
             provenance: { relations: ['daily_health', 'canonical_activity_training', 'nutrition_days'], database: 'read-only DuckDB snapshot' },
             query: { startDate, endDate },
@@ -230,7 +268,7 @@ export function createCatenceMcpServer(paths = resolvePaths(), dependencies = {}
         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) },
-    }, tool('review_activity_deep_dive', async (input) => useRepository(paths, async (repository) => {
+    }, tool('review_activity_deep_dive', async (input) => useRepository(activePaths(), async (repository) => {
         const activity = await repository.activity(input.activityId);
         return {
             data: activity,
@@ -244,7 +282,7 @@ export function createCatenceMcpServer(paths = resolvePaths(), dependencies = {}
     server.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(paths, async (repository) => ({
+    }, 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.'],
     }))));
@@ -252,7 +290,7 @@ export function createCatenceMcpServer(paths = resolvePaths(), dependencies = {}
         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) },
-    }, tool('describe_dataset', async (input) => useRepository(paths, async (repository) => {
+    }, tool('describe_dataset', async (input) => useRepository(activePaths(), async (repository) => {
         const dataset = getDataset(input.dataset);
         const coverage = (await repository.coverage()).coverage;
         const observedValues = dataset.name === 'training_metric_observations'
@@ -273,7 +311,7 @@ export function createCatenceMcpServer(paths = resolvePaths(), dependencies = {}
     })));
     server.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(paths, (repository) => new AnalyticsService(repository).readSeries({ ...input, filters: input.filters }))));
+    }, tool('read_series', async (input) => useRepository(activePaths(), (repository) => new AnalyticsService(repository).readSeries({ ...input, filters: input.filters }))));
     server.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: {
@@ -281,15 +319,15 @@ export function createCatenceMcpServer(paths = resolvePaths(), dependencies = {}
             metrics: z.array(z.object({ column: z.string().min(1), operation: z.enum(['count', 'sum', 'mean', 'min', 'max', 'percentile']), percentile: z.number().gt(0).lt(1).optional(), as: z.string().min(1).max(64).optional() })).min(1).max(12),
             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(paths, (repository) => new AnalyticsService(repository).aggregate({ ...input, filters: input.filters }))));
+    }, tool('aggregate_data', async (input) => useRepository(activePaths(), (repository) => new AnalyticsService(repository).aggregate({ ...input, filters: input.filters }))));
     server.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(paths, (repository) => new AnalyticsService(repository).analyzeSeries({ ...input, filters: input.filters }))));
+    }, tool('analyze_series', async (input) => useRepository(activePaths(), (repository) => new AnalyticsService(repository).analyzeSeries({ ...input, filters: input.filters }))));
     server.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(paths, (repository) => new AnalyticsService(repository).fitSeriesModel({ ...input, filters: input.filters }))));
+    }, tool('fit_series_model', async (input) => useRepository(activePaths(), (repository) => new AnalyticsService(repository).fitSeriesModel({ ...input, filters: input.filters }))));
     server.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.',
@@ -297,32 +335,32 @@ export function createCatenceMcpServer(paths = resolvePaths(), dependencies = {}
             metricA: z.enum(WELLNESS_METRICS), metricB: z.enum(WELLNESS_METRICS), startDate: z.string().date().optional(), endDate: z.string().date().optional(),
             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(paths, (repository) => new WellnessService(repository).correlate(input))));
+    }, tool('wellness_correlate', async (input) => useRepository(activePaths(), (repository) => new WellnessService(repository).correlate(input))));
     server.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(paths, (repository) => new WellnessService(repository).baselines(input))));
+    }, tool('wellness_baselines', async (input) => useRepository(activePaths(), (repository) => new WellnessService(repository).baselines(input))));
     server.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(paths, (repository) => new WellnessService(repository).anomalies(input))));
+    }, tool('wellness_anomalies', async (input) => useRepository(activePaths(), (repository) => new WellnessService(repository).anomalies(input))));
     server.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(paths, (repository) => new WellnessService(repository).coverage(input))));
+    }, tool('wellness_coverage', async (input) => useRepository(activePaths(), (repository) => new WellnessService(repository).coverage(input))));
     server.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(paths, (repository) => new FitnessService(repository).ftpHistory(input))));
+    }, tool('get_ftp_history', async (input) => useRepository(activePaths(), (repository) => new FitnessService(repository).ftpHistory(input))));
     server.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(paths, (repository) => new FitnessService(repository).vo2MaxHistory(input))));
+    }, tool('get_vo2max_history', async (input) => useRepository(activePaths(), (repository) => new FitnessService(repository).vo2MaxHistory(input))));
     server.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.',
@@ -333,25 +371,25 @@ export function createCatenceMcpServer(paths = resolvePaths(), dependencies = {}
             startDate: z.string().date().optional(), endDate: z.string().date().optional(),
             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(paths, (repository) => new ActivityDiscoveryService(repository).findActivities(input))));
+    }, tool('find_activities', async (input) => useRepository(activePaths(), (repository) => new ActivityDiscoveryService(repository).findActivities(input))));
     server.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(paths, (repository) => new SwimmingService(repository).swimLaps(input))));
+    }, tool('get_swim_laps', async (input) => useRepository(activePaths(), (repository) => new SwimmingService(repository).swimLaps(input))));
     server.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(paths, (repository) => new SwimmingService(repository).swimProgressReport(input))));
+    }, tool('swim_progress_report', async (input) => useRepository(activePaths(), (repository) => new SwimmingService(repository).swimProgressReport(input))));
     server.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() },
     }, tool('get_activity_segments', async (input) => {
-        const hydration = await hydrateActivity(paths, input.activityId, input.refresh ?? false);
+        const hydration = await hydrateActivity(activePaths(), input.activityId, input.refresh ?? false);
         const hydratedStravaActivityIds = stravaActivityIds(hydration);
-        const segments = await useRepository(paths, (repository) => activitySegments(repository, input.activityId, hydratedStravaActivityIds, input.limit ?? 200));
+        const segments = await useRepository(activePaths(), (repository) => activitySegments(repository, input.activityId, hydratedStravaActivityIds, input.limit ?? 200));
         return {
             data: { hydration, hydratedStravaActivityIds, segments },
             provenance: { provider: 'strava', relations: ['activity_segments', 'strava_segments'], operation: 'targeted_activity_hydration_then_read' },
@@ -366,37 +404,37 @@ export function createCatenceMcpServer(paths = resolvePaths(), dependencies = {}
         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(paths, (repository) => new FitnessService(repository).powerCurveTrend(input))));
+    }, tool('power_curve_trend', async (input) => useRepository(activePaths(), (repository) => new FitnessService(repository).powerCurveTrend(input))));
     server.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(paths, (repository) => new FitnessService(repository).powerCoverageReport(input))));
+    }, tool('power_coverage_report', async (input) => useRepository(activePaths(), (repository) => new FitnessService(repository).powerCoverageReport(input))));
     server.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(paths, (repository) => new FitnessService(repository).latestCyclingActivities(input))));
+    }, tool('latest_cycling_activities', async (input) => useRepository(activePaths(), (repository) => new FitnessService(repository).latestCyclingActivities(input))));
     server.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(paths, (repository) => new FitnessService(repository).cyclingProgressReport(input))));
+    }, tool('cycling_progress_report', async (input) => useRepository(activePaths(), (repository) => new FitnessService(repository).cyclingProgressReport(input))));
     server.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(paths, (repository) => queryReadOnlyData(repository, input))));
+    }, tool('query_read_only_data', async (input) => useRepository(activePaths(), (repository) => queryReadOnlyData(repository, input))));
     server.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(paths, (repository) => searchContext(repository, input))));
+    }, tool('search_context', async (input) => useRepository(activePaths(), (repository) => searchContext(repository, input))));
     server.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() },
     }, tool('hydrate_strava_activity', async (input) => {
-        const data = await hydrateActivity(paths, input.activityId, input.refresh ?? false);
-        return { data, coverage: await useRepository(paths, (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.'] };
+        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', {
         title: 'Hydrate several recent Strava activities',
@@ -409,7 +447,7 @@ export function createCatenceMcpServer(paths = resolvePaths(), dependencies = {}
     }, tool('hydrate_recent_strava_activities', async (input) => {
         const activityIds = input.activityIds
             ? [...new Set(input.activityIds)]
-            : await useRepository(paths, async (repository) => {
+            : await useRepository(activePaths(), async (repository) => {
                 const values = {
                     startDate: input.startDate, endDate: `${input.endDate}T23:59:59.999Z`, limit: input.limit ?? 20,
                 };
@@ -443,7 +481,7 @@ export function createCatenceMcpServer(paths = resolvePaths(), dependencies = {}
                 continue;
             }
             try {
-                const result = await hydrateStravaActivity(paths, activityId, input.refresh ?? false);
+                const result = await hydrateStravaActivity(activePaths(), activityId, input.refresh ?? false);
                 const status = typeof result.status === 'string' ? result.status : 'completed';
                 outcomes.push({ activityId, status, result });
             }
@@ -471,44 +509,57 @@ export function createCatenceMcpServer(paths = resolvePaths(), dependencies = {}
         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() },
     }, tool('hydrate_strava_segment_history', async (input) => {
-        const data = await hydrateStravaSegmentHistory(paths, input.segmentId, input.refresh ?? false);
-        return { data, coverage: await useRepository(paths, (repository) => repository.coverage()), provenance: { provider: 'strava', operation: 'segment_effort_history', archivedBeforeNormalization: true }, caveats: ['Only the authenticated athlete’s historic segment efforts are requested.'] };
+        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.'] };
     }));
-    server.registerResource('status', 'catence://status', { title: 'Catence status', mimeType: 'application/json' }, async (uri) => {
-        const limited = await resourceLimit('status', uri);
-        if (limited)
-            return limited;
-        try {
-            return resource(uri, await useRepository(paths, (repository) => repository.status()));
-        }
-        catch (error) {
-            return resource(uri, { error: errorResult(error).content[0].text });
-        }
-    });
-    server.registerResource('catalog', 'catence://catalog', { title: 'Catence catalog', mimeType: 'application/json' }, async (uri) => { const limited = await resourceLimit('catalog', uri); if (limited)
-        return limited; return resource(uri, { datasets: Object.values(DATASET_CATALOG) }); });
-    server.registerResource('activity', new ResourceTemplate('catence://activity/{activityId}', { list: undefined }), { title: 'Activity detail', mimeType: 'application/json' }, async (uri, variables) => {
-        const limited = await resourceLimit('activity', uri);
-        if (limited)
-            return limited;
-        try {
-            return resource(uri, await useRepository(paths, (repository) => repository.activity(variable(variables.activityId))));
-        }
-        catch (error) {
-            return resource(uri, { error: errorResult(error).content[0].text });
-        }
-    });
-    server.registerResource('summary', new ResourceTemplate('catence://summary/{startDate}/{endDate}', { list: undefined }), { title: 'Catence date-range summary', mimeType: 'application/json' }, async (uri, variables) => {
-        const limited = await resourceLimit('summary', uri);
-        if (limited)
-            return limited;
-        try {
-            return resource(uri, await useRepository(paths, (repository) => repository.summary(variable(variables.startDate), variable(variables.endDate))));
-        }
-        catch (error) {
-            return resource(uri, { error: errorResult(error).content[0].text });
-        }
-    });
+    if (catalogPaths) {
+        server.registerResource('athletes', 'catence://athletes', { title: 'Configured athlete roster', mimeType: 'application/json' }, async (uri) => {
+            try {
+                const catalog = await loadCatalog(catalogPaths);
+                return resource(uri, { defaultAthleteId: catalog.defaultAthleteId, athletes: catalog.athletes });
+            }
+            catch (error) {
+                return resource(uri, { error: errorResult(error).content[0].text });
+            }
+        });
+    }
+    else {
+        server.registerResource('status', 'catence://status', { title: 'Catence status', mimeType: 'application/json' }, async (uri) => {
+            const limited = await resourceLimit('status', uri);
+            if (limited)
+                return limited;
+            try {
+                return resource(uri, await useRepository(activePaths(), (repository) => repository.status()));
+            }
+            catch (error) {
+                return resource(uri, { error: errorResult(error).content[0].text });
+            }
+        });
+        server.registerResource('catalog', 'catence://catalog', { title: 'Catence catalog', mimeType: 'application/json' }, async (uri) => { const limited = await resourceLimit('catalog', uri); if (limited)
+            return limited; return resource(uri, { datasets: Object.values(DATASET_CATALOG) }); });
+        server.registerResource('activity', new ResourceTemplate('catence://activity/{activityId}', { list: undefined }), { title: 'Activity detail', mimeType: 'application/json' }, async (uri, variables) => {
+            const limited = await resourceLimit('activity', uri);
+            if (limited)
+                return limited;
+            try {
+                return resource(uri, await useRepository(activePaths(), (repository) => repository.activity(variable(variables.activityId))));
+            }
+            catch (error) {
+                return resource(uri, { error: errorResult(error).content[0].text });
+            }
+        });
+        server.registerResource('summary', new ResourceTemplate('catence://summary/{startDate}/{endDate}', { list: undefined }), { title: 'Catence date-range summary', mimeType: 'application/json' }, async (uri, variables) => {
+            const limited = await resourceLimit('summary', uri);
+            if (limited)
+                return limited;
+            try {
+                return resource(uri, await useRepository(activePaths(), (repository) => repository.summary(variable(variables.startDate), variable(variables.endDate))));
+            }
+            catch (error) {
+                return resource(uri, { error: errorResult(error).content[0].text });
+            }
+        });
+    }
     return server;
 }
 function variable(value) {

package/dist/runtime/index.d.ts

@@ -9,6 +9,10 @@
 export type { CatencePaths } from '../contracts/runtime.js';
 export { CATENCE_PROTOCOL_VERSION, CATENCE_RUNTIME_VERSION, catenceRuntimeHealth } from '../contracts/release.js';
 export { configuredMcpRateLimit, loadCatenceConfig, resolvePaths } from '../core/runtime/configuration.js';
+export { addAthlete, athleteStorePaths, defaultAthlete, defaultCatalogHome, initializeCatalog, loadCatalog, resolveAthlete, resolveCatalogPaths, } from '../core/runtime/catalog.js';
+export type { Athlete, CatalogPaths, CatenceCatalog } from '../core/runtime/catalog.js';
+export { athleteProviderEnvironment, providerSecretPath, readAthleteSecrets, setAthleteSecret } from '../core/runtime/secrets.js';
+export type { AthleteSecrets, SecretProvider } from '../core/runtime/secrets.js';
 export { SlidingWindowLimiter } from '../core/runtime/limiter.js';
 export { DashboardSnapshotService } from '../core/dashboard/snapshot.js';
 export { searchContext } from '../core/retrieval/index.js';