catence 0.2.0-beta.16 → 0.2.0-beta.18

package/dist/elt/storage/database.js

@@ -271,6 +271,24 @@ export class CatenceDatabase {
         const rows = await this.rows('SELECT remote_activity_id, summary_hash FROM activity_sync_state WHERE provider = $provider', { provider });
         return Object.fromEntries(rows.map((row) => [row.remote_activity_id, row.summary_hash]));
     }
+    async hasGarminLactateThresholdHistory() {
+        const rows = await this.rows("SELECT count(*) AS n FROM training_metric_observations WHERE observation_id LIKE 'garmin:lactate_threshold:daily:%'");
+        return (rows[0]?.n ?? 0) > 0;
+    }
+    async earliestActivityStartDate(provider) {
+        const rows = await this.rows(`SELECT min(cast(started_at_utc AS DATE)) AS earliest FROM activities activity
+         JOIN activity_sources source USING (activity_id) WHERE source.provider = $provider`, { provider });
+        return toIsoDate(rows[0]?.earliest ?? null);
+    }
+    async garminSwimActivitySources() {
+        const sports = ['lap_swimming', 'swimming', 'open_water_swimming', 'openwaterswimming'];
+        return this.rows(`SELECT source.remote_activity_id, cast(activity.started_at_utc AS VARCHAR) AS started_on
+         FROM activity_sources AS source
+         JOIN activities AS activity USING (activity_id)
+        WHERE source.provider = 'garmin'
+          AND lower(coalesce(activity.sport, '')) IN (${sports.map((sport) => `'${sport}'`).join(', ')})
+        ORDER BY activity.started_at_utc`);
+    }
     async latestSourceDate(provider, cursorName) {
         const observations = cursorName === 'daily'
             ? `SELECT max(metric_date) AS observed_date FROM daily_metrics WHERE provider = $provider

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

@@ -1,11 +1,17 @@
 import { type Server } from 'node:http';
-import { type CatalogPaths, type CatencePaths } from '../../runtime/index.js';
+import { type DetachedSyncSpawner, mergeOpenCodeGoConsoleProfiles, startDetachedSync, type CatalogPaths, type CatencePaths } from '../../runtime/index.js';
 export type CatenceHttpServerOptions = {
     /** A shared catalog for public servers. All data APIs then require athleteId. */
     catalogPaths?: CatalogPaths;
     /** Internal compatibility hook for tests and embedded single-store callers. */
     paths?: CatencePaths;
     allowedOrigins?: readonly string[];
+    /** Internal compatibility hook for tests: override the detached sync spawner. */
+    startSync?: typeof startDetachedSync;
+    /** Internal compatibility hook for tests: passed into the default startDetachedSync. */
+    syncSpawnProcess?: DetachedSyncSpawner;
+    /** Internal compatibility hook for tests: override OpenCode Go model discovery. */
+    mergeModels?: typeof mergeOpenCodeGoConsoleProfiles;
 };
 /**
  * Create Catence's local Streamable HTTP server.

package/dist/interfaces/http/server.js

@@ -1,6 +1,6 @@
 import { createServer } from 'node:http';
 import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
-import { catenceRuntimeHealth, DashboardSnapshotService, jsonSafe, loadCatalog, openReadOnlyRepository, resolveAthlete, resolveCatalogPaths } from '../../runtime/index.js';
+import { catenceRuntimeHealth, DashboardSnapshotService, dataStatus, DetachedSyncBusyError, DETACHED_SYNC_PROVIDERS, jsonSafe, loadCatalog, mergeOpenCodeGoConsoleProfiles, openReadOnlyRepository, ReadOnlyDatabaseError, resolveAthlete, resolveCatalogPaths, startDetachedSync, syncProgress, } from '../../runtime/index.js';
 import { createCatenceMcpServer } from '../mcp/server.js';
 const MAX_REQUEST_BYTES = 1_000_000;
 function json(response, statusCode, value) {
@@ -85,6 +85,65 @@ async function dashboardPaths(catalogPaths, staticPaths, url) {
         return staticPaths;
     throw new Error('No Catence data store is configured.');
 }
+function parseSyncBody(body) {
+    if (body === undefined)
+        return {};
+    if (typeof body !== 'object' || body === null || Array.isArray(body))
+        throw new Error('Request body must be a JSON object.');
+    const raw = body;
+    for (const key of Object.keys(raw)) {
+        if (!['athleteId', 'provider', 'from', 'refresh', 'refreshModels'].includes(key)) {
+            throw new Error(`Unknown sync field: ${key}.`);
+        }
+    }
+    if (raw.athleteId !== undefined && typeof raw.athleteId !== 'string')
+        throw new Error('athleteId must be a string.');
+    if (raw.provider !== undefined && (typeof raw.provider !== 'string' || !DETACHED_SYNC_PROVIDERS.includes(raw.provider))) {
+        throw new Error('provider must be intervals, garmin, strava, or all.');
+    }
+    if (raw.from !== undefined && (typeof raw.from !== 'string' || !/^\d{4}-\d{2}-\d{2}$/.test(raw.from))) {
+        throw new Error('from must use YYYY-MM-DD.');
+    }
+    for (const flag of ['refresh', 'refreshModels']) {
+        if (raw[flag] !== undefined && typeof raw[flag] !== 'boolean')
+            throw new Error(`${flag} must be a boolean.`);
+    }
+    return raw;
+}
+async function resolveSyncPaths(catalogPaths, staticPaths, body) {
+    if (catalogPaths) {
+        if (!body.athleteId)
+            throw new Error('athleteId is required. Call /api/v1/athletes to inspect the configured catalog.');
+        return (await resolveAthlete(catalogPaths, body.athleteId)).paths;
+    }
+    if (staticPaths)
+        return staticPaths;
+    throw new Error('No Catence data store is configured.');
+}
+/** Best-effort last-success timestamps; null while a run holds the write lock. */
+async function lastSyncSummary(paths) {
+    try {
+        const status = await dataStatus(paths);
+        const runs = Array.isArray(status.syncRuns) ? status.syncRuns : [];
+        const completed = runs.filter((run) => typeof run.completed_at === 'string' && String(run.status).startsWith('completed'));
+        const providers = {};
+        let lastCompletedAt = null;
+        for (const run of completed) {
+            const completedAt = String(run.completed_at);
+            const provider = String(run.provider ?? 'unknown');
+            if (!providers[provider] || providers[provider] < completedAt)
+                providers[provider] = completedAt;
+            if (!lastCompletedAt || lastCompletedAt < completedAt)
+                lastCompletedAt = completedAt;
+        }
+        return { lastCompletedAt, providers, recentRuns: runs.slice(0, 5) };
+    }
+    catch (error) {
+        if (error instanceof ReadOnlyDatabaseError)
+            return null;
+        throw error;
+    }
+}
 async function handleMcpRequest(request, response, paths) {
     if (request.method !== 'POST') {
         methodNotAllowed(response);
@@ -143,6 +202,8 @@ export function createCatenceHttpServer(options = {}) {
     const catalogPaths = options.catalogPaths ?? (options.paths ? null : resolveCatalogPaths());
     const staticPaths = options.paths ?? null;
     const allowedOrigins = options.allowedOrigins ?? [];
+    const startSync = options.startSync ?? startDetachedSync;
+    const mergeModels = options.mergeModels ?? mergeOpenCodeGoConsoleProfiles;
     return createServer((request, response) => {
         void (async () => {
             if (!addCorsHeaders(request, response, allowedOrigins)) {
@@ -182,6 +243,48 @@ export function createCatenceHttpServer(options = {}) {
                 }
                 return;
             }
+            if (pathname === '/api/v1/sync' && request.method === 'POST') {
+                let body;
+                try {
+                    body = parseSyncBody(await readJsonBody(request));
+                    const paths = await resolveSyncPaths(catalogPaths, staticPaths, body);
+                    // Optional model self-discovery runs before the data sync so new
+                    // OpenCode Go models appear without a manual script run. Failure is
+                    // non-fatal: it must never block or fail a data sync.
+                    let discoveryWarning = null;
+                    if (body.refreshModels) {
+                        try {
+                            await mergeModels({ configPath: paths.config, setDefault: false });
+                        }
+                        catch (error) {
+                            discoveryWarning = `OpenCode Go model discovery failed; profiles were left unchanged (${error instanceof Error ? error.message : String(error)}).`;
+                        }
+                    }
+                    const handle = await startSync({ paths, athleteId: body.athleteId ?? 'local', provider: body.provider, from: body.from, refresh: body.refresh }, { spawnProcess: options.syncSpawnProcess });
+                    json(response, 202, { ...handle, ...(discoveryWarning ? { warning: discoveryWarning } : {}), progressEndpoint: '/api/v1/sync/status' });
+                }
+                catch (error) {
+                    json(response, error instanceof DetachedSyncBusyError ? 409 : 400, {
+                        error: {
+                            code: error instanceof DetachedSyncBusyError ? 'sync_in_progress' : 'sync_start_failed',
+                            message: error instanceof Error ? error.message : String(error),
+                        },
+                    });
+                }
+                return;
+            }
+            if (pathname === '/api/v1/sync/status' && request.method === 'GET') {
+                try {
+                    const url = new URL(request.url ?? '/', 'http://localhost');
+                    const paths = await dashboardPaths(catalogPaths, staticPaths, url);
+                    const athleteId = catalogPaths ? (await resolveAthlete(catalogPaths, url.searchParams.get('athleteId') ?? '')).athlete.id : 'local';
+                    json(response, 200, { athleteId, progress: await syncProgress(paths), lastSync: await lastSyncSummary(paths) });
+                }
+                catch (error) {
+                    json(response, 400, { error: { code: 'sync_status_unavailable', message: error instanceof Error ? error.message : String(error) } });
+                }
+                return;
+            }
             if (pathname === '/mcp') {
                 await handleMcpRequest(request, response, catalogPaths ?? staticPaths ?? resolveCatalogPaths());
                 return;

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

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

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, 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']),
@@ -32,17 +32,19 @@ 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 +125,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();
@@ -176,7 +179,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);
@@ -238,6 +246,28 @@ export function createCatenceMcpServer(paths = resolveCatalogPaths(), dependenci
         data: await repository.progress(),
         provenance: { database: 'read-only DuckDB snapshot' }, query: {}, caveats: [],
     }))));
+    server.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.',
+            ],
+        };
+    }));
     server.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.',

package/dist/runtime/index.d.ts

@@ -30,6 +30,10 @@ export { queryReadOnlyData } from '../core/query/sql-guard.js';
 export { createDemoStore, demoStoreMetadata } from '../elt/application/demo.js';
 export { connectStrava, connectStravaWithCallback, dataStatus, disconnectStravaAccount, initializeDataStore, importStagedFile, linkActivity, rebuildRetrievalIndex, reimportNutrition, resolveExtractionErrors, retryDataSync, syncData, syncProgress, unlinkActivity, } from '../elt/application/management.js';
 export type { ProviderChoice } from '../elt/application/management.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 { openReadOnlyRepository, ReadOnlyDatabaseError } from '../elt/storage/database.js';
 export { DataWriteBusyError } from '../elt/storage/write-lock.js';

package/dist/runtime/index.js

@@ -16,6 +16,8 @@ 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, importStagedFile, linkActivity, rebuildRetrievalIndex, reimportNutrition, resolveExtractionErrors, retryDataSync, syncData, syncProgress, unlinkActivity, } from '../elt/application/management.js';
+export { DETACHED_SYNC_PROVIDERS, DetachedSyncBusyError, startDetachedSync, } from '../elt/application/detached-sync.js';
+export { buildOpenCodeGoConsoleProfiles, classifyOpenCodeGoModel, fetchOpenCodeGoModelIds, mergeOpenCodeGoConsoleProfiles, OPENCODE_GO_API_BASE_ENV, OPENCODE_GO_API_KEY_ENV, OPENCODE_GO_DEFAULT_BASE_URL, OPENCODE_GO_MESSAGES_API_BASE_ENV, } from '../core/runtime/opencode-go.js';
 export { openReadOnlyRepository, ReadOnlyDatabaseError } from '../elt/storage/database.js';
 export { DataWriteBusyError } from '../elt/storage/write-lock.js';
 export { hydrateStravaActivity, hydrateStravaSegmentHistory, StravaEnrichmentError, StravaRateLimitError, } from '../elt/ingestion/providers/strava/service.js';

package/docs/configuration.md

@@ -160,6 +160,12 @@ Precedence for reasoning effort: per-chat dropdown selection > model
 `reasoningEffort` > profile `defaultReasoningEffort` > provider default. See
 [`llm-providers.md`](llm-providers.md#reasoning-effort) for the full behavior.
 
+The Console's **Models** page edits this section in place (enable/disable,
+add custom variants, remove, set defaults). Disabled choices are stored in the
+Console database rather than here; every write preserves all non-console
+sections and is re-validated with the same strict parser before the file is
+replaced.
+
 ### The Console wizard
 
 On the first authenticated chat, the Console wizard (`write_provider_setup`)
@@ -185,6 +191,22 @@ into the provider worker environment, and inherited `GARMIN_*`/`INTERVALS_*`/
 `STRAVA_*` variables are stripped first so an athlete without a provider cannot
 inherit its credentials.
 
+For local and Docker development you can also keep credentials in env without
+`secret set` — see the two fallback modes below. File values always win over
+env, so a `providers.json` entry overrides any env fallback for that field.
+
+### Provider credentials via env (dev fallback)
+
+Two opt-in env fallbacks are checked **only when a `providers.json` field is
+missing** — file values always win. See `src/core/runtime/secrets.ts:51`.
+
+| Mode | Variables | When allowed | Example for athlete `alex` |
+|------|-----------|--------------|----------------------------|
+| **Per-athlete scoped** (recommended, multi-athlete safe) | `CATENCE_ATHLETE_<ID>_<PROVIDER_VAR>` — prefix is `CATENCE_ATHLETE_` + upper-cased athlete id with `-` → `_` + `_` | **Always** — checked even when the generic flag is off. Only maps to that one athlete. | `CATENCE_ATHLETE_ALEX_GARMIN_EMAIL=alex@example.com` `CATENCE_ATHLETE_ALEX_INTERVALS_API_KEY=…` |
+| **Generic** (single-athlete dev, opt-in) | `GARMIN_EMAIL`, `GARMIN_PASSWORD`, `INTERVALS_API_KEY`, `INTERVALS_ATHLETE_ID`, `STRAVA_CLIENT_ID`, `STRAVA_CLIENT_SECRET` | Only when `CATENCE_ALLOW_ENV_SECRETS` (or alias `CATENCE_SECRETS_FROM_ENV`) is `1`/`true`/`yes`/`on` in the worker's env. Without the flag, bare provider env vars are stripped. | `CATENCE_ALLOW_ENV_SECRETS=1` + `GARMIN_EMAIL=…` |
+
+Resolution order per field: `providers.json` → `CATENCE_ATHLETE_<ID>_<VAR>` → (if flag set) `VAR`. Set `CATENCE_ALLOW_ENV_SECRETS=1` in `.env.dev` / `docker-compose.dev.yml` for single-athlete Docker dev, or prefer per-athlete vars for a shared catalog.
+
 ### Console auth and serving
 
 | Variable | Purpose |

package/docs/deployment/local-console.md

@@ -119,6 +119,30 @@ Preflight with:
 catence-console doctor
 ```
 
+### Manage models in the Console
+
+The **Models** page (header button) manages the model list without editing
+`config.json` by hand:
+
+- Enable/disable toggles hide models from the chat's Model dropdown. Disabled
+  choices are stored per machine in the Console database
+  (`console/chat-history.sqlite3`), never in `config.json`, and the Console
+  refuses to disable the only enabled model.
+- **Add a custom model** appends one deployment to an existing profile — id,
+  display label, LiteLLM reference (`openai/…`, `anthropic/…`,
+  `openai/responses/…`), and optional fixed reasoning effort or a custom
+  variants map.
+- **Remove / Make default** edit `config.json`'s console section directly;
+  every other section is preserved, the result is re-validated with the same
+  strict parser used at startup before it replaces the file, and secrets stay
+  forbidden (only environment-variable names are ever stored).
+
+The dashboard header has a **Sync data** button that starts the same detached
+sync as `catence-data sync --provider all` through the authenticated Console
+origin, shows live progress while the run is active, and displays the last
+completed sync afterwards. Each manual sync also refreshes OpenCode Go model
+profiles first; a discovery failure never blocks the data sync.
+
 ## Console serve options
 
 `catence-console serve` accepts:

package/docs/deployment/local-mcp.md

@@ -100,6 +100,11 @@ athletes never leak into each other.
 - Rate limits are tracked **per athlete**: each athlete has its own sliding
   window for server, tool, and resource limits.
 - MCP responses carry an `athlete` field identifying which store served them.
+- `start_detached_sync` is the one explicitly named write tool besides the
+  Strava hydration tools: it spawns a detached `catence-data sync` child for
+  the selected athlete and returns immediately with the run handle and log
+  file. It refuses to start while another sync run is active (`sync_in_progress`);
+  follow the run with `catence_sync_progress`.
 
 ### Adding another athlete
 
@@ -298,6 +303,17 @@ override the host and port when the flags are omitted.
 - `GET /api/v1/dashboard` requires `athleteId`, for example
   `http://127.0.0.1:8787/api/v1/dashboard?athleteId=alex&days=28` (`endDate`
   is an optional `YYYY-MM-DD`; `days` ranges 1-90 and defaults to 28).
+- `POST /api/v1/sync` starts a detached data sync for one athlete:
+  `{"athleteId": "alex", "provider": "all", "from": "2026-01-01", "refresh": false}`.
+  The spawned child outlives the request, logs to `<home>/logs/`, and the call
+  returns `202` with the run handle immediately; an already-active run is
+  refused with `409 sync_in_progress`. Pass `"refreshModels": true` to also
+  refresh OpenCode Go model profiles first (failure is a non-fatal warning in
+  the response).
+- `GET /api/v1/sync/status?athleteId=alex` reports live progress heartbeats,
+  recent runs, and best-effort last-completion timestamps per provider. It
+  keeps working while a sync holds the write lock (`lastSync` becomes `null`
+  then).
 - Browser origins must be listed with `--allow-origin` (repeatable). The
   packaged Console instead proxies the dashboard through its authenticated
   same-origin route.