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

package/README.md

@@ -1,15 +1,19 @@
 # Catence
 
-Catence is a local-first fitness MCP server for Garmin, Intervals.icu, and targeted Strava enrichment. It gives an agent evidence-backed access to normalized training, wellness, activity, stream, segment, and gear data without uploading the underlying dataset to Catence.
+Local MCP server for primary Garmin data, with added Intervals.icu metrics and Strava enrichment.
 
 ![Catence](docs/assets/image.png)
 
+## ... what?
+
+As a context, I'm both an endurance athlete and a data junkie. I already got a coach for all the serious stuff, but I wanted to hook up some—any—LLM to the insane amount of data collected from Garmin, derived on Intervals.icu (I don't pay for TrainingPeaks) and comparable efforts on Strava segments. Naturally, the first answer was a local MCP server for my current tooling.
+
 ## What is included
 
 - Garmin, Intervals.icu, and Strava ingestion with source-aware normalization.
-- Read-only MCP tools, plus explicitly named, lock-guarded Strava hydration tools.
+- Read-only MCP tools, plus explicitly named, lock-guarded write tools for Strava hydration and detached syncs.
 - One shared Catence agent can serve several isolated athlete stores. Every personal-data MCP call names an `athleteId`; Catence never silently combines athletes.
-- A password-protected Chainlit Console with an authenticated dashboard.
+- A password-protected Chainlit Console with an authenticated dashboard, a data-sync button with live progress, and in-app model management.
 - A generated demo catalog for safe evaluation in Glama, desktop MCP clients, or local development.
 
 Catence helps explore recovery, training load, trends, activity detail, swimming/cycling/running progress, segments, gear, and data quality. It reports the evidence and coverage it can see; it does not diagnose or prescribe training.
@@ -22,14 +26,16 @@ Catence helps explore recovery, training load, trends, activity detail, swimming
 
 ## Quick start
 
-Install Catence and create the first athlete. The default catalog home is `~/.catence`; set `CATENCE_HOME` or pass `--home` to use a different location. For the full local or Docker deployment walkthrough, see [deployment notes](docs/deployment.md).
+Install Catence and create the first athlete. The default catalog home is `~/.catence`; set `CATENCE_HOME` or pass `--home` to use a different location.
+
+Every `catence-data` command requires `--athlete <id>`; there is no default athlete. Pair it with `--home <dir>` to select the catalog when not using the default home.
 
 ```sh
-npm install --global catence@0.2.0
+npm install --global catence@latest          # or catence@beta
 catence-data setup --athlete alex --label "Alex"
 ```
 
-Store each provider value through stdin so it does not enter shell history. Values are written to the selected athlete’s owner-only local secret file.
+Store each provider value through stdin so it does not enter shell history. Values are written to the selected athlete's owner-only local secret file.
 
 ```sh
 printf %s 'alex@example.com' | catence-data --athlete alex secret set --provider garmin --field email --value-stdin
@@ -63,68 +69,35 @@ catence-data --athlete sam sync --provider garmin
 catence-data athlete list
 ```
 
-The catalog layout is deliberately simple:
-
-```text
-~/.catence/
-  catalog.json
-  config.json                     # shared Console configuration; no secrets
-  console/chat-history.sqlite3
-  athletes/
-    alex/                         # isolated DuckDB, raw data, and tokens
-      secrets/providers.json      # mode 0600
-    sam/
-      ...
-```
-
-Garmin, Intervals, and Strava client credentials are isolated per athlete. Strava OAuth tokens remain in that athlete’s own store. The old 0.1 single-store directory cannot be migrated safely: create a fresh home and re-sync each athlete.
+Garmin, Intervals, and Strava client credentials are isolated per athlete. Strava OAuth tokens remain in that athlete's own store. The old 0.1 single-store directory cannot be migrated safely: create a fresh home and re-sync each athlete.
 
 ### Common operations
 
 ```sh
-# Incremental or explicit data work for one athlete
 catence-data --athlete alex status
 catence-data --athlete alex sync --provider intervals
 catence-data --athlete alex sync --provider garmin --from 2025-07-29
 catence-data --athlete alex backfill --provider garmin --from 2020-01-01 --refresh
 catence-data --athlete alex retry --run <run-id>
-
-# Strava OAuth uses clientId and clientSecret previously stored for this athlete
+catence-data --athlete alex progress --watch
 catence-data --athlete alex auth strava --callback
 catence-data --athlete alex disconnect strava
-
-# Update the runtime and Console together on the tracked release channel
 catence-data update --check
 catence-data update
-
-# Choose a non-default catalog location
-catence-data --home /srv/catence setup --athlete alex --label "Alex"
-catence --home /srv/catence
 ```
 
-`catence-data update` follows the channel of the installed runtime: a beta
-install tracks the npm `beta` tag and the matching PyPI prereleases, a stable
-install tracks `latest`. Pass `--channel stable` to move off a beta. The command
-replaces the global `catence` package and installs or upgrades
-`catence-console` with `uv tool` when `uv` is available; `--check` only reports.
-
-Register `http://127.0.0.1:8765/strava/callback` with the Strava application for the callback flow. The manual `auth strava --code <authorization-code>` flow remains available for headless environments.
-
-## Safe demo and Glama
-
-Run a clearly marked generated dataset without provider accounts:
-
-```sh
-npx --yes catence@0.2.0 demo
-```
+## Documentation
 
-It creates or reuses `~/.catence-demo` with one `demo` athlete. The generated data has explicit caveats in every tool response and never contains personal measurements. The Glama registry entry uses this command for **Try in Browser**, so the hosted sandbox has no access to local credentials or personal data.
-
-From a checkout:
-
-```sh
-npm run mcp -- demo
-```
+| Document | Covers |
+| --- | --- |
+| [Deployment: local MCP](docs/deployment/local-mcp.md) | Install, catalog, secrets, sync, background progress, stdio/HTTP MCP, demo, common operations |
+| [Deployment: local Console](docs/deployment/local-console.md) | Local web chat setup, model config, doctor, updates, troubleshooting |
+| [Deployment: Docker](docs/deployment/docker.md) | One-container stack: deploy script, `.env`, sync.sh, MCP exposure (SSH/Tailscale), Cloudflare Tunnel |
+| [Configuration](docs/configuration.md) | Complete `config.json` schema: rate limits, Strava budget, Console profiles, environment variables |
+| [LLM providers](docs/llm-providers.md) | Model providers (OpenAI, Anthropic, OpenAI-compatible/Azure, Opencode Go/Zen), reasoning effort |
+| [Architecture](docs/architecture.md) | Design rationale, layers, data flow, serving |
+| [MCP activity retrieval](docs/mcp-activity-retrieval.md) | Implementation contract for answering questions, current tools, planned endpoints |
+| [Distribution](docs/distribution.md) | Release artifacts: npm, PyPI, APM, MCPB |
 
 ## MCP clients and HTTP
 
@@ -147,113 +120,11 @@ Optional local Streamable HTTP MCP and dashboard APIs:
 catence serve --host 127.0.0.1 --port 8787
 ```
 
-`GET /api/v1/athletes` returns IDs and labels only. `GET /api/v1/dashboard` requires `athleteId`, for example `http://127.0.0.1:8787/api/v1/dashboard?athleteId=alex&days=28`. Browser origins must be listed with `--allow-origin`; the packaged Console instead proxies the dashboard through its authenticated same-origin route.
-
-## Catence Console
-
-The Console is a local web chat that starts a matching Catence HTTP server on loopback. It uses Chainlit password login and fails closed unless all three authentication variables are supplied.
-
-```sh
-export CATENCE_HOME="$HOME/.catence"
-export CATENCE_CONSOLE_USERNAME='coach'
-export CATENCE_CONSOLE_PASSWORD_HASH="$(catence-console auth hash-password)"
-export CHAINLIT_AUTH_SECRET="$(openssl rand -hex 32)"
-export OPENAI_API_KEY='…'
-
-uvx catence-console@0.2.0 serve
-```
-
-On the first authenticated visit, the Console wizard asks for an OpenAI-compatible, OpenAI, or Anthropic model and writes only the non-secret model configuration to `~/.catence/config.json`. The `openai-compatible` option covers Azure and Opencode; see [`docs/llm-providers.md`](docs/llm-providers.md). Model-provider keys remain process environment variables. The Console settings include an athlete selector; the server overwrites model-supplied athlete scope with that selected value on every personal-data call.
-
-To preflight the Console and a running runtime:
-
-```sh
-uvx catence-console@0.2.0 doctor --home "$HOME/.catence" --mcp-url http://127.0.0.1:8787/mcp
-```
-
-Console chats and saved tool context are local at `~/.catence/console/chat-history.sqlite3`.
-
-### Docker and Cloudflare Tunnel
-
-The Console image contains the Node runtime, Catence, and Console. Its MCP server remains loopback-only inside the container; only the Console port is exposed.
-
-```sh
-docker build -f console/Dockerfile -t catence-console .
-docker run --rm -p 127.0.0.1:8000:8000 -v catence-data:/data \
-  -e CATENCE_CONSOLE_USERNAME='coach' \
-  -e CATENCE_CONSOLE_PASSWORD_HASH='replace-with-bcrypt-hash' \
-  -e CHAINLIT_AUTH_SECRET='replace-with-a-long-random-secret' \
-  -e OPENAI_API_KEY='…' \
-  catence-console
-```
-
-Initialize the mounted volume before its first production sync, for example:
-
-```sh
-docker run --rm -it -v catence-data:/data --entrypoint catence-data catence-console \
-  setup --athlete alex --label "Alex"
-```
-
-Use the same `--entrypoint catence-data` pattern for `secret set` and `sync`. Route a Cloudflare Tunnel to `http://127.0.0.1:8000`; do not run a tunnel client in this image. Use HTTPS at the tunnel and retain the Console login—the dashboard is fetched through the authenticated Console origin rather than directly from port 8787.
-
-[`scripts/deploy-console.sh`](scripts/deploy-console.sh) deploys this stack from
-the public registries and seeds a starter `config.json` (the Console model
-profiles from [`config.example.json`](config.example.json)) into the data
-volume, so the settings panel works before the first chat. Edit
-`/data/config.json` in the volume (or the bind-mounted `--home` directory) to
-change models and defaults, or discover OpenCode Go profiles from the image:
-
-```sh
-docker compose -f catence-deploy/docker-compose.yml --env-file catence-deploy/.env run --rm \
-  --entrypoint node console \
-  /usr/local/lib/node_modules/catence/scripts/discover-opencode-go.mjs --write /data/config.json
-```
+`GET /api/v1/athletes` returns IDs and labels only. `GET /api/v1/dashboard` requires `athleteId`, for example `http://127.0.0.1:8787/api/v1/dashboard?athleteId=alex&days=28`. Browser origins must be listed with `--allow-origin`; the packaged Console instead proxies the dashboard through its authenticated same-origin route. The MCP server has no authentication of its own.
 
 ## Configuration
 
-[`config.example.json`](config.example.json) documents rate limits, Strava budgets, and Console model profiles. It intentionally contains environment-variable names rather than credential values. Keep per-athlete provider values in `catence-data secret set`, not in `.env` or `config.json`.
-
-### Per-model reasoning effort
-
-Models that support reasoning effort can set a fixed level per model in `config.json`, or expose a per-chat **Thinking effort** dropdown with custom levels via `variants`.
-
-**Fixed level** (all requests for the model use it):
-
-```json
-{
-  "console": {
-    "profiles": {
-      "opencode-zen": {
-        "label": "OpenCode Zen",
-        "defaultModel": "deepseek-v4-flash-free",
-        "models": {
-          "deepseek-v4-flash-free": {
-            "label": "DeepSeek V4 Flash Free",
-            "model": "openai/deepseek-v4-flash-free",
-            "reasoningEffort": "high"
-          }
-        },
-        "apiKeyEnv": "OPENCODE_API_KEY",
-        "apiBaseEnv": "OPENCODE_ZEN_API_BASE"
-      }
-    }
-  }
-}
-```
-
-**Custom variants** (per-chat dropdown): `variants` maps each dropdown label to the value sent to the provider. This is how non-OpenAI models (for example DeepSeek V4 Flash, which uses its own Default/High/Max scheme rather than the OpenAI-standard list) expose their native levels:
-
-```json
-"deepseek-v4-flash-free": {
-  "label": "DeepSeek V4 Flash Free",
-  "model": "openai/deepseek-v4-flash-free",
-  "variants": { "High": "high", "Max": "max" }
-}
-```
-
-With `variants`, the chat **Thinking effort** dropdown shows `Provider default` plus each label; selecting one sends that exact value (e.g. `reasoning_effort: "high"`). Without `variants`, the dropdown falls back to the OpenAI-standard set (`minimal`, `low`, `medium`, `high`, `xhigh`).
-
-A fixed `reasoningEffort` overrides any profile-level `defaultReasoningEffort`; the per-chat dropdown selection (a variant value) overrides both. If nothing is set, the provider default is used.
+[`config.example.json`](config.example.json) documents rate limits, Strava budgets, and Console model profiles. Keep per-athlete provider values in `catence-data secret set`, not in `.env` or `config.json`. The full `config.json` schema —including per-model reasoning effort— is documented in [`docs/configuration.md`](docs/configuration.md) and [`docs/llm-providers.md`](docs/llm-providers.md).
 
 For source development:
 
@@ -264,33 +135,20 @@ npm test
 UV_CACHE_DIR=$PWD/.cache/uv uv run --project console --group dev python -m pytest console/tests -q
 ```
 
-## Beta releases
+## Data and caveats
 
-Registry betas use distinct npm and Python prerelease formats: for example,
-`catence@0.2.0-beta.1` pairs with `catence-console==0.2.0b1` and
-`catence-chainlit==0.2.0b1`. The protected `beta` branch verifies candidates;
-a `v0.2.0-beta.1` tag publishes to npm's `beta` channel and creates a GitHub
-prerelease. Follow [the beta release checklist](release/beta-checklist.md) to
-publish the UI wheel first, deploy the registry artifacts with Compose, and
-test the MCP and authenticated Console on a server without touching production
-data.
+The current available sources respond to my own used platforms. I used some wrappers:
 
-## Data and caveats
+- [cyberjunky/python-garminconnect](https://github.com/cyberjunky/python-garminconnect)
+- [paladini/node-intervals-icu](https://github.com/paladini/node-intervals-icu)
+- [stravalib/stravalib](https://github.com/stravalib/stravalib)
 
-Garmin is the primary source for activity and wellness data; Intervals.icu supplements training analysis; Strava is used for targeted segments, efforts, and gear. Missing fields mean a provider did not supply a value. The source credentials and source APIs determine the data available. Catence does not use the official Garmin API; Garmin sync relies on the selected athlete’s email/password credentials.
+Strava is only used for segments and gear.
 
-See [distribution notes](docs/distribution.md) for release artifacts, including APM and MCPB demo bundles.
+### Caveats
 
-##
+There are two caveats to the data fetching, both coming from the fact that this was created to be used by a single person. Accessing the full Garmin API requires applying via a company—which I don't have—and getting Strava data for multiple users is another headache I don't want to get into.
 
-```bash
-cd catence-deploy
-docker compose -f docker-compose.yml --env-file .env exec console \
-  catence-data sync --athlete martina --provider all --home /data        # incremental sync, all providers
-docker compose -f docker-compose.yml --env-file .env exec console \
-  catence-data backfill --athlete martina --from 2026-01-01 --home /data # full backfill from a date
-docker compose -f docker-compose.yml --env-file .env exec console \
-  catence-data status --athlete martina --home /data                     # coverage/errors
-docker compose -f docker-compose.yml --env-file .env exec console \
-  catence-data athlete list --home /data                                 # list athlete IDs
-```
+- I don't use the official Garmin Connect API. The library uses email/pwd.
+- Connecting Strava requires the user to be a Strava Premium subscriber and create an [API application](https://stravalib.readthedocs.io/en/latest/get-started/authenticate-with-strava.html). The rotating token is stored locally in
+`<data-dir>/secrets/strava.json`.

package/dist/contracts/index.d.ts

@@ -1,3 +1,4 @@
+export * from './progress.js';
 export * from './runtime.js';
 export * from './release.js';
 export * from './staging.js';

package/dist/contracts/index.js

@@ -1,3 +1,4 @@
+export * from './progress.js';
 export * from './runtime.js';
 export * from './release.js';
 export * from './staging.js';

package/dist/contracts/progress.d.ts

@@ -0,0 +1,23 @@
+export declare const STALE_RUN_TIMEOUT_MS: number;
+export declare const SYNC_STAGES: readonly ["starting", "login", "singletons", "daily", "range", "ftp_history", "max_metrics", "hrv_history", "scores", "activities", "collections", "intervals", "importing", "completed", "interrupted", "failed", "timed_out"];
+export type SyncStage = (typeof SYNC_STAGES)[number];
+export interface SyncProgressState {
+    runId: string;
+    provider: string;
+    stage: SyncStage;
+    currentStep: string | null;
+    completedUnits: number;
+    totalUnits: number | null;
+    percentComplete: number;
+    elapsedSeconds: number;
+    estimatedRemainingSeconds: number | null;
+    heartbeatAt: string;
+}
+export interface SyncProgressSnapshot {
+    running: SyncProgressState[];
+    recent: SyncProgressState[];
+}
+export interface InterruptedRuns {
+    runIds: string[];
+}
+export declare function normalizeProgress(value: unknown): SyncProgressState | null;

package/dist/contracts/progress.js

@@ -0,0 +1,49 @@
+export const STALE_RUN_TIMEOUT_MS = 15 * 60 * 1000;
+export const SYNC_STAGES = [
+    'starting',
+    'login',
+    'singletons',
+    'daily',
+    'range',
+    'ftp_history',
+    'max_metrics',
+    'hrv_history',
+    'scores',
+    'activities',
+    'collections',
+    'intervals',
+    'importing',
+    'completed',
+    'interrupted',
+    'failed',
+    'timed_out',
+];
+export function normalizeProgress(value) {
+    if (typeof value !== 'object' || value === null) {
+        return null;
+    }
+    const record = value;
+    const runId = typeof record.runId === 'string' ? record.runId : '';
+    const provider = typeof record.provider === 'string' ? record.provider : '';
+    if (!runId || !provider) {
+        return null;
+    }
+    const stage = SYNC_STAGES.includes(record.stage)
+        ? record.stage
+        : 'starting';
+    const numberOr = (value, fallback) => typeof value === 'number' && Number.isFinite(value) ? value : fallback;
+    const roundOrNull = (value) => typeof value === 'number' && Number.isFinite(value) ? Math.max(0, Math.round(value)) : null;
+    return {
+        runId,
+        provider,
+        stage,
+        currentStep: typeof record.currentStep === 'string' ? record.currentStep : null,
+        completedUnits: Math.max(0, Math.round(numberOr(record.completedUnits, 0))),
+        totalUnits: roundOrNull(record.totalUnits),
+        percentComplete: Math.min(100, Math.max(0, numberOr(record.percentComplete, 0))),
+        elapsedSeconds: Math.max(0, numberOr(record.elapsedSeconds, 0)),
+        estimatedRemainingSeconds: roundOrNull(record.estimatedRemainingSeconds),
+        heartbeatAt: typeof record.heartbeatAt === 'string' ? record.heartbeatAt : new Date().toISOString(),
+    };
+}
+//# sourceMappingURL=progress.js.map

package/dist/contracts/release.d.ts

@@ -3,7 +3,7 @@
  * Keep these values synchronized with release/manifest.json; release checks
  * deliberately reject drift before a package can be published.
  */
-export declare const CATENCE_RUNTIME_VERSION = "0.2.0-beta.9";
+export declare const CATENCE_RUNTIME_VERSION = "0.2.1-beta.1";
 export declare const CATENCE_PROTOCOL_VERSION = 1;
 export type CatenceRuntimeCapabilities = {
     mcp: true;

package/dist/contracts/release.js

@@ -3,7 +3,7 @@
  * Keep these values synchronized with release/manifest.json; release checks
  * deliberately reject drift before a package can be published.
  */
-export const CATENCE_RUNTIME_VERSION = '0.2.0-beta.9';
+export const CATENCE_RUNTIME_VERSION = '0.2.1-beta.1';
 export const CATENCE_PROTOCOL_VERSION = 1;
 export function catenceRuntimeHealth() {
     return {

package/dist/core/query/activity-discovery.d.ts

@@ -1,6 +1,8 @@
 import { ReadOnlyRepository } from './repository.js';
 export type FindActivitiesRequest = {
     sports?: string[];
+    /** Accepted as a convenience alias for `sports: [sport]`. */
+    sport?: string;
     distanceKm?: [number, number];
     nameContains?: string[];
     startDate?: string;

package/dist/core/query/activity-discovery.js

@@ -49,7 +49,7 @@ export class ActivityDiscoveryService {
         this.repository = repository;
     }
     async findActivities(request = {}) {
-        const sports = [...new Set((request.sports ?? []).map((sport) => sport.trim()).filter(Boolean))];
+        const sports = [...new Set((request.sports ?? (request.sport ? [request.sport] : [])).map((sport) => sport.trim()).filter(Boolean))];
         const names = [...new Set((request.nameContains ?? []).map((name) => name.trim()).filter(Boolean))];
         if (sports.length > 12 || names.length > 12)
             throw new QueryValidationError('sports and nameContains each permit at most 12 values.');

package/dist/core/query/analytics.d.ts

@@ -19,6 +19,12 @@ export type SeriesRequest = {
     cursor?: string;
     pageSize?: number;
 };
+export type DeriveDecouplingRequest = {
+    activityId: string;
+};
+export type DeriveGapRequest = {
+    activityId: string;
+};
 export declare function compileFilters(dataset: DatasetDefinition, filters?: DataFilter[], startDate?: string, endDate?: string, activityId?: string): {
     where: string;
     values: QueryValues;
@@ -56,4 +62,8 @@ export declare class AnalyticsService {
         xMetric?: string;
         yMetric?: string;
     }): Promise<Record<string, unknown>>;
+    deriveDecoupling(request: DeriveDecouplingRequest): Promise<Record<string, unknown>>;
+    deriveGap(request: DeriveGapRequest): Promise<Record<string, unknown>>;
+    private resolveActivitySource;
+    private loadActivitySamples;
 }