catence 0.1.0 → 0.2.0-beta.1

package/README.md

@@ -1,389 +1,217 @@
 # Catence
 
-Local MCP server for primary Garmin data, with added Intervals.icu metrics and Strava enrichment.
+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.
 
-![](docs/assets/image.png)
+![Catence](docs/assets/image.png)
 
-## What?
+## What is included
 
-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.
+- Garmin, Intervals.icu, and Strava ingestion with source-aware normalization.
+- Read-only MCP tools, plus explicitly named, lock-guarded Strava hydration tools.
+- 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 generated demo catalog for safe evaluation in Glama, desktop MCP clients, or local development.
 
-## Scope
+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.
 
-Currently a bit limited but I'd like to expand it:
+## Requirements
 
-- [x] Garmin, Intervals.icu, Strava data fetching
-- [x] Data normalization and storage
-- [x] Read-only local MCP server
-- [x] Local Streamable HTTP server
-- [x] Release-ready npm, [APM](https://github.com/microsoft/apm), and MCPB distribution artifacts
-- [x] Generated demo store for safe MCP evaluation
-- [x] Bundled local Chainlit Console with persisted chat history
-- [ ] Data writing (training sessions, plans)
-  - [ ] TrainingPeaks support?
-- [ ] Limited multi-user support (see Caveats)
+- Node.js 22+
+- Python 3.12+ and [uv](https://docs.astral.sh/uv/) for Garmin and Strava provider workers
+- Provider credentials for the athletes you choose to sync
 
-## What Catence can help you do
+## Quick start
 
-Catence is most useful when a question benefits from checking several local signals instead of reacting to a single score. The Console and MCP tools can help you explore questions such as:
-
-- **Recovery and readiness:** “What changed in my sleep, HRV, resting heart rate, stress, and recent load before today’s session?”
-- **Training load:** “Is this week harder than my recent baseline, and which sessions contributed most?”
-- **Performance trends:** “How has my threshold pace, cycling power, or swim efficiency changed across the season?”
-- **Session review:** “Compare this long run or interval set with similar recent efforts, including pace/power, heart rate, terrain, and recovery.”
-- **Segments and gear:** “Show my history on this climb,” or “which shoes and bikes have carried the most recent training volume?”
-- **Data-quality review:** “Which recent activities lack streams, power, health context, or a matching provider record?”
-
-## Sources
-
-The current available sources respond to my own used platforms. I used some wrappers:
-
-- [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)
-
-Strava is only used for segments and gear.
-
-### 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.
-
-- 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`.
-
-What I mean by multi-user is being able to manage and serve various users' data on the same server.
-
-## Data
-
-Priority is assigned per data type. Missing values mean the provider did not supply that metric.
-
-| Data group | Priority and provenance | Data available per activity or date | Aggregated data |
-| --- | --- | --- | --- |
-| Generic activity data | <ol><li>Garmin (canonical activity data)</li><li>Intervals.icu (supplemental analysis)</li></ol> | Date/time, timezone, sport, name, distance, elapsed/moving time, elevation, calories, average/max HR, source identity, and quality flags | Activity count, distance, duration, elevation, and calories by date range |
-| Running — indoor and outdoor | <ol><li>Garmin (activity facts and streams)</li><li>Intervals.icu (analysis values)</li></ol> | Pace/speed, cadence, HR, power when available, GPS, elevation, grade, splits, intervals, VO₂max, lactate-threshold metrics, and race predictions | Running volume, pace/load trends, and training-metric history |
-| Cycling — indoor and outdoor | <ol><li>Garmin (activity facts, FIT streams, and settings)</li><li>Intervals.icu (load, RPE, feel, and weighted power)</li></ol> | Average/weighted power, cadence, speed, HR, GPS, elevation, grade, temperature, cycling dynamics, splits, and FTP observations | Power-duration bests, power coverage, cycling volume/load, and FTP trends |
-| Swimming — pool and open water | <ol><li>Garmin (explicit lengths and summaries)</li><li>Intervals.icu (auto-detected sets)</li></ol> | Lengths/laps, pool length, distance, duration, stroke count/rate, SWOLF, average/max HR, sets, and GPS when supplied | Swim volume, session comparisons, and data-completeness summaries |
-| Structured intervals and sets | <ol><li>Intervals.icu (Intervals-based intervals)</li><li>Garmin (Garmin splits and sets)</li></ol> | Interval labels, repetitions, duration, moving time, distance, pace, power, HR, intensity, and swim-set details | Interval volume, intensity, and provider-specific comparisons |
-| Daily health and wellness | <ol><li>Garmin (primary health data)</li></ol> | HR, resting HR, HRV, sleep, sleep score, stress, Body Battery, readiness, SpO₂, weight, steps, hydration, and nutrition | Daily, weekly, and monthly health and nutrition trends |
-| Strava segments and gear | <ol><li>Strava (source of record)</li></ol> | Segment names, grades, climb category, elevation, effort time/distance, power, HR, cadence, PR/KOM ranks, bikes, shoes, and historic efforts | Segment, climb, effort-history, and gear comparisons |
-| Derived and cross-source analytics | <ol><li>Garmin (canonical inputs)</li><li>Intervals.icu (interval inputs)</li><li>Strava (segment and gear inputs)</li><li>Catence (derived results)</li></ol> | Reconciled activity values and source-quality flags | Rolling statistics, baselines, correlations, seasonal comparisons, trends, descriptive model fits, and progress reports |
-
-## Set up
-
-Catence exposes the same local MCP server over stdio and optional Streamable HTTP. A tagged release publishes the `catence` npm package, platform-specific MCPB demo bundles, and an APM package. Until that first public release is available, the source-checkout commands below remain fully supported.
-
-### Safe one-command demo
-
-After publication, start a no-account MCP server with generated data:
+Install Catence and create the first athlete. The default catalog home is `~/.catence`; set `CATENCE_HOME` or pass `--home` to use a different location.
 
 ```sh
-npx --yes catence@0.1.0 demo
+npm install --global catence@0.2.0
+catence-data setup --athlete alex --label "Alex"
 ```
 
-It creates `./catence-demo` by default and refuses to replace a directory that is not already marked as a Catence demo. The synthetic store deliberately
-contains lagged training-load/recovery effects, a multi-signal anomaly period, and some missing sleep-score dates. Every MCP result includes a generated-data disclaimer, so it cannot be mistaken for a personal health record.
-
-From a source checkout, the equivalent command is:
+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
-npm run catence-data -- demo
-npm run mcp -- demo --data-dir ./catence-demo
+printf %s 'alex@example.com' | catence-data --athlete alex secret set --provider garmin --field email --value-stdin
+printf %s 'your-garmin-password' | catence-data --athlete alex secret set --provider garmin --field password --value-stdin
+printf %s 'intervals-api-key' | catence-data --athlete alex secret set --provider intervals --field apiKey --value-stdin
+printf %s '12345' | catence-data --athlete alex secret set --provider intervals --field athleteId --value-stdin
 ```
 
-### Install for live data
-
-After publication, install the package once, then create and synchronize a store that you own:
+Sync and create retrieval context:
 
 ```sh
-npm install --global catence@0.1.0
-catence-data --data-dir /absolute/path/to/catence-data init
-catence-data --data-dir /absolute/path/to/catence-data sync --provider all
-catence-data --data-dir /absolute/path/to/catence-data build-retrieval-index
-catence --data-dir /absolute/path/to/catence-data
+catence-data --athlete alex sync --provider all
+catence-data --athlete alex build-retrieval-index
 ```
 
-### Prerequisites
-
-- Node.js 22 or later
-- Python 3.12 or later and [uv](https://docs.astral.sh/uv/) for Garmin and Strava provider syncs
-
-Clone the repository, install the Node and Python dependencies, and create your local `.env` with the following credentials:
-
-- Garmin email/password
-- Intervals.icu [API Key and Athlete ID](https://forum.intervals.icu/t/api-access-to-intervals-icu/609)
-- Strava [Client ID and Secret](https://stravalib.readthedocs.io/en/latest/get-started/authenticate-with-strava.html)
-
-### Create and sync a local data store
-
-By default, runtime data is placed in `.catence/` inside the checkout. You can also choose an absolute path outside the repository and supply it consistently with `--data-dir` (or set `CATENCE_DATA_DIR`). The examples below use an absolute path.
+Start the stdio MCP server:
 
 ```sh
-npm run catence-data -- --data-dir /absolute/path/to/catence-data init
-npm run catence-data -- --data-dir /absolute/path/to/catence-data sync --provider all
-npm run catence-data -- --data-dir /absolute/path/to/catence-data build-retrieval-index
+catence
 ```
 
-The retrieval index is derived context for agent search; rebuild it after a sync. Syncs are incremental after the first import. Use `backfill` only for an explicit historical range, and add `--refresh` only when you intentionally want to re-fetch already covered Garmin activity details, files, and streams.
+An agent first calls `list_athletes`, then includes `athleteId` with every data tool. This is intentional: a shared agent may access the stores you configured, but no tool implicitly aggregates or crosses between athletes.
 
-### Common commands
-
-Run these from the repository root. Omit `--data-dir` to use the checkout's `.catence/` directory.
+### Add another athlete
 
 ```sh
-# Inspect local coverage and sync individual providers
-npm run catence-data -- status
-npm run catence-data -- sync --provider intervals
-npm run catence-data -- sync --provider garmin --from 2025-07-29
-npm run catence-data -- sync --provider strava
-npm run catence-data -- sync --provider all
-
-# Recover or import a specific historical range
-npm run catence-data -- retry --run <run-id>
-npm run catence-data -- backfill --from 2020-01-01
-npm run catence-data -- backfill --provider garmin --from 2026-07-01 --refresh
-
-# Refresh derived search context and launch the local MCP server
-npm run catence-data -- build-retrieval-index
-npm run mcp
-npm run mcp -- --data-dir /absolute/path/to/catence-data
-
-# Optional local Streamable HTTP MCP and dashboard API
-npm run mcp -- serve --data-dir /absolute/path/to/catence-data --allow-origin http://127.0.0.1:8000
-npm run mcp -- serve --allow-origin http://127.0.0.1:8000
+catence-data athlete add --id sam --label "Sam"
+printf %s 'sam@example.com' | catence-data --athlete sam secret set --provider garmin --field email --value-stdin
+printf %s 'sam-password' | catence-data --athlete sam secret set --provider garmin --field password --value-stdin
+catence-data --athlete sam sync --provider garmin
+catence-data athlete list
 ```
 
-The first manual sync uses the previous 12 months only when there is no local normalized coverage. `sync --provider strava` refreshes gear data. Strava activity segments and gear are enriched on demand by the MCP tools.
-
-### Connect Strava
+The catalog layout is deliberately simple:
 
-With `STRAVA_CLIENT_ID` and `STRAVA_CLIENT_SECRET` in `.env`, the local callback flow avoids copying a code out of the browser URL. Register `http://127.0.0.1:8765/strava/callback` as the authorization callback in the Strava application, then run:
-
-```sh
-npm run catence-data -- auth strava --callback
+```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/
+      ...
 ```
 
-The command prints the authorization URL to the terminal, waits up to five minutes for the browser callback, validates OAuth state, and stores the resulting token only in `<data-dir>/secrets/strava.json`.
+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.
 
-The existing manual flow remains available for headless use:
+### Common operations
 
 ```sh
-npm run catence-data -- auth strava
-npm run catence-data -- auth strava --code <authorization-code>
-```
+# 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>
 
-Catence requests `read`, `activity:read_all`, and `read_all`. To remove the stored Strava connection later, run:
+# Strava OAuth uses clientId and clientSecret previously stored for this athlete
+catence-data --athlete alex auth strava --callback
+catence-data --athlete alex disconnect strava
 
-```sh
-npm run catence-data -- disconnect strava
+# Choose a non-default catalog location
+catence-data --home /srv/catence setup --athlete alex --label "Alex"
+catence --home /srv/catence
 ```
 
-## Run the local Console
-
-The Console is Catence’s local chat experience. It sends model calls through LiteLLM in-process and calls the same Streamable HTTP MCP tools that a coding agent uses. Provider keys are never written to Catence configuration or chat storage.
+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.
 
-### Install and launch
+## Safe demo and Glama
 
-After publication, the Console is a separate Python distribution. It includes the Catence-maintained Chainlit frontend and starts the matching npm runtime on loopback automatically:
+Run a clearly marked generated dataset without provider accounts:
 
 ```sh
-uvx catence-console@0.1.0 serve --data-dir /absolute/path/to/catence-data
+npx --yes catence@0.2.0 demo
 ```
 
-The command needs Node.js 22 and `npx`, but does not require a Catence or `catence-ui` checkout. Pass `--mcp-url http://127.0.0.1:8787/mcp` when you intentionally want to use an already-running compatible Catence runtime.
-
-For source development, install the locally built `catence-chainlit` wheel and run `uv run --project console catence-console serve` from this repository.
-
-### First-run setup
+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.
 
-Launch the Console once with your selected provider’s environment variables in the terminal. If `<data-dir>/config.json` has no Console section, the browser walks through provider and model selection (Azure, OpenAI, or Anthropic) and writes only non-secret configuration. For example:
+From a checkout:
 
 ```sh
-# Azure OpenAI / Foundry: use the Azure resource root and the Responses API route.
-export AZURE_API_KEY='…'
-export AZURE_API_BASE='https://your-resource.openai.azure.com'
-export AZURE_API_VERSION='preview'
-
-uvx catence-console@0.1.0 serve --data-dir /absolute/path/to/catence-data
-```
-
-For an existing configuration or an automated setup, add a `console` section to `<data-dir>/config.json`. It defines named providers and deployments and environment-variable *names*, never credential values. The complete shape is in [`config.example.json`](config.example.json). For the two common direct providers, the minimal profiles are:
-
-```json
-{
-  "openai": {
-    "label": "OpenAI",
-    "model": "openai/gpt-5-mini",
-    "apiKeyEnv": "OPENAI_API_KEY"
-  },
-  "anthropic": {
-    "label": "Anthropic",
-    "model": "anthropic/claude-sonnet-4-5",
-    "apiKeyEnv": "ANTHROPIC_API_KEY"
-  }
-}
+npm run mcp -- demo
 ```
 
-A provider with several deployments looks like this:
-
-```json
-{
-  "console": {
-    "defaultProfile": "provider",
-    "limits": {
-      "toolRounds": 8,
-      "toolResultCharacters": 24000
-    },
-    "profiles": {
-      "azure-foundry": {
-        "label": "Provider",
-        "defaultModel": "terra",
-        "defaultReasoningEffort": "medium",
-        "models": {
-          "terra": { "label": "GPT-5.6 Terra", "model": "provider/gpt-5.6-terra" },
-          "luna": { "label": "GPT-5.6 Luna", "model": "provider/gpt-5.6-luna" },
-          "sol": { "label": "GPT-5.6 Sol", "model": "provider/gpt-5.6-sol" }
-        },
-        "apiKeyEnv": "API_KEY",
-        "apiBaseEnv": "API_BASE",
-        "apiVersionEnv": "API_VERSION"
-      }
-    }
-  }
-}
-```
-
-An OpenAI-compatible provider such as OpenCode uses a model such as `openai/your-model` plus `apiBaseEnv` and, if needed, `apiKeyEnv`. LiteLLM handles provider normalization.
-
-The Console shows all configured deployments in its Model selector and sends the selected Thinking effort to LiteLLM as `reasoning_effort`. Choose only efforts supported by the selected deployment. Existing profiles with a single `model` remain supported.
-
-### Launching
+## MCP clients and HTTP
 
-Set the referenced variables in the terminal that will run the Console, then launch everything on loopback with one command:
+For a packaged installation, point a client at `catence`:
 
 ```sh
-uvx catence-console@0.1.0 serve --data-dir /absolute/path/to/catence-data
+codex mcp add catence -- catence
+claude mcp add --transport stdio catence -- catence
 ```
 
-On its first normal launch this starts the matching Catence runtime at `http://127.0.0.1:8787`, permits only the local Console origins, and serves the prebuilt chat and dashboard at `http://127.0.0.1:8000`.
-
-To preflight a profile and an already-running Catence HTTP server, use:
+For a source checkout:
 
 ```sh
-uvx catence-console@0.1.0 doctor \
-  --data-dir /absolute/path/to/catence-data \
-  --mcp-url http://127.0.0.1:8787/mcp
+codex mcp add catence -- npm --prefix /absolute/path/to/catence run mcp
 ```
 
-`doctor` reports profile IDs, models, missing environment-variable names, and Catence health.
+Optional local Streamable HTTP MCP and dashboard APIs:
 
-### Local chat history
+```sh
+catence serve --host 127.0.0.1 --port 8787
+```
 
-Console chats, messages, tool steps, and thread metadata are persisted at `<data-dir>/console/chat-history.sqlite3`. A later turn receives a compact list of prior calls (not their results); it can lazily load one saved result when it is material, or repeat the authoritative call for fresh data.
+`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.
 
-## Add Catence to an MCP client
+## Catence Console
 
-First complete the setup and at least one sync. For a packaged install, point a client to the installed `catence` binary (or use the safe demo command):
+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
-catence --data-dir /absolute/path/to/catence-data
-npx --yes catence@0.1.0 demo
-```
-
-For a source checkout, each client should start the same local command, pointing at the same absolute data directory:
+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='…'
 
-```sh
-npm --prefix /absolute/path/to/catence run mcp -- --data-dir /absolute/path/to/catence-data
+uvx catence-console@0.2.0 serve
 ```
 
-The MCP server's ordinary reads are local and read-only. Its explicit Strava hydration tools are the exception; they use the already stored local connection and a shared write lock. `catence serve` retains the same tools at `/mcp` and also exposes loopback dashboard data at `/api/v1/dashboard`; browser origins must be allowed explicitly with `--allow-origin`.
-
-### Codex
+On the first authenticated visit, the Console wizard asks for an Azure, OpenAI, or Anthropic model and writes only the non-secret model configuration to `~/.catence/config.json`. 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.
 
-For a first look, add the generated demo server from the terminal:
+To preflight the Console and a running runtime:
 
 ```sh
-codex mcp add catence-demo -- npx --yes catence@0.1.0 demo
+uvx catence-console@0.2.0 doctor --home "$HOME/.catence" --mcp-url http://127.0.0.1:8787/mcp
 ```
 
-For a live npm install, use:
+Console chats and saved tool context are local at `~/.catence/console/chat-history.sqlite3`.
 
-```sh
-codex mcp add catence -- catence --data-dir /absolute/path/to/catence-data
-```
+### Docker and Cloudflare Tunnel
 
-For a source checkout, use:
+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
-codex mcp add catence -- npm --prefix /absolute/path/to/catence run mcp -- --data-dir /absolute/path/to/catence-data
-```
-
-Alternatively, add this to `~/.codex/config.toml` for a personal installation, or `.codex/config.toml` in a trusted repository:
-
-```toml
-[mcp_servers.catence]
-command = "npm"
-args = ["--prefix", "/absolute/path/to/catence", "run", "mcp", "--", "--data-dir", "/absolute/path/to/catence-data"]
-startup_timeout_sec = 30
-```
-
-### OpenCode
-
-Add this local MCP definition to `opencode.json` or `opencode.jsonc`:
-
-```jsonc
-{
-  "$schema": "https://opencode.ai/config.json",
-  "mcp": {
-    "catence": {
-      "type": "local",
-      "command": [
-        "npm",
-        "--prefix",
-        "/absolute/path/to/catence",
-        "run",
-        "mcp",
-        "--",
-        "--data-dir",
-        "/absolute/path/to/catence-data"
-      ],
-      "enabled": true
-    }
-  }
-}
+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
 ```
 
-### Claude Code
-
-Add the local stdio server from a terminal:
+Initialize the mounted volume before its first production sync, for example:
 
 ```sh
-claude mcp add --transport stdio catence -- npm --prefix /absolute/path/to/catence run mcp -- --data-dir /absolute/path/to/catence-data
+docker run --rm -it -v catence-data:/data --entrypoint catence-data catence-console \
+  setup --athlete alex --label "Alex"
 ```
 
-Use Claude Code's MCP listing command to confirm it was added:
+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.
 
-```sh
-claude mcp list
-```
+## Configuration
 
-### APM and MCPB
+[`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`.
 
-The repository's [`apm.yml`](apm.yml) registers both `catence` and the safe `catence-demo` server with supported agent clients. After a tag is published:
+For source development:
 
 ```sh
-apm install rifusaki/catence#v0.1.0
+npm ci
+npm run check
+npm test
+UV_CACHE_DIR=$PWD/.cache/uv uv run --project console --group dev python -m pytest console/tests -q
 ```
 
-Each release also attaches platform-specific `catence-demo-*.mcpb` files. Open the matching file in an MCPB-capable desktop client (including Claude Desktop) to install the one-click generated demo. Live-source setup remains an explicit CLI step, so the bundle never requests or stores provider credentials.
+## Beta releases
 
-## Wellness shortcuts
+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.
 
-Catence keeps its flexible catalog and analytical tools, and now exposes four small opinionated wellness tools for common recovery questions:
+## Data and caveats
 
-- `wellness_correlate` compares curated recovery/training metrics and can scan lags from −7 to +7 days.
-- `wellness_baselines` returns a trailing mean, standard-deviation band, latest value, and latest z-score.
-- `wellness_anomalies` finds statistical outliers and dates with multiple unusual signals; it does not diagnose or prescribe.
-- `wellness_coverage` shows absent dates and unresolved extraction errors without assuming that missing data means rest or a health outcome.
+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.
 
-They use the same source-aware `daily_health` and `canonical_activity_training` projections as the general query tools. See [distribution and release notes](docs/distribution.md) for the current tooling.
+See [distribution notes](docs/distribution.md) for release artifacts, including APM and MCPB demo bundles.

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.1.0";
+export declare const CATENCE_RUNTIME_VERSION = "0.2.0-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.1.0';
+export const CATENCE_RUNTIME_VERSION = '0.2.0-beta.1';
 export const CATENCE_PROTOCOL_VERSION = 1;
 export function catenceRuntimeHealth() {
     return {

package/dist/core/runtime/catalog.d.ts

@@ -0,0 +1,41 @@
+import { z } from 'zod';
+import type { CatencePaths } from '../../contracts/runtime.js';
+declare const catalogSchema: z.ZodObject<{
+    formatVersion: z.ZodLiteral<1>;
+    defaultAthleteId: z.ZodString;
+    athletes: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        label: z.ZodString;
+        createdAt: z.ZodString;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type Athlete = z.infer<typeof catalogSchema>['athletes'][number];
+export type CatenceCatalog = z.infer<typeof catalogSchema>;
+export type CatalogPaths = {
+    root: string;
+    catalog: string;
+    athletes: string;
+    console: string;
+};
+export declare function defaultCatalogHome(): string;
+export declare function resolveCatalogPaths(root?: string): CatalogPaths;
+export declare function athleteStorePaths(catalogPaths: CatalogPaths, athleteId: string): CatencePaths;
+export declare function loadCatalog(paths?: CatalogPaths): Promise<CatenceCatalog>;
+export declare function initializeCatalog(paths: CatalogPaths | undefined, athlete: {
+    id: string;
+    label: string;
+}): Promise<CatenceCatalog>;
+export declare function addAthlete(paths: CatalogPaths, athlete: {
+    id: string;
+    label: string;
+    setDefault?: boolean;
+}): Promise<CatenceCatalog>;
+export declare function resolveAthlete(paths: CatalogPaths, athleteId: string): Promise<{
+    athlete: Athlete;
+    paths: CatencePaths;
+}>;
+export declare function defaultAthlete(paths?: CatalogPaths): Promise<{
+    athlete: Athlete;
+    paths: CatencePaths;
+}>;
+export {};