catence 0.1.0 → 0.2.0-beta.10

package/README.md

@@ -1,389 +1,359 @@
 # 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:
+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).
 
-- **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
+```sh
+npm install --global catence@0.2.0
+catence-data setup --athlete alex --label "Alex"
+```
 
-After publication, start a no-account MCP server with generated data:
+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
-npx --yes catence@0.1.0 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
 ```
 
-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:
+Sync and create retrieval context:
 
 ```sh
-npm run catence-data -- demo
-npm run mcp -- demo --data-dir ./catence-demo
+catence-data --athlete alex sync --provider all
+catence-data --athlete alex build-retrieval-index
 ```
 
-### Install for live data
-
-After publication, install the package once, then create and synchronize a store that you own:
+Start the stdio MCP server:
 
 ```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
 ```
 
-### Prerequisites
+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.
 
-- Node.js 22 or later
-- Python 3.12 or later and [uv](https://docs.astral.sh/uv/) for Garmin and Strava provider syncs
+### Add another athlete
 
-Clone the repository, install the Node and Python dependencies, and create your local `.env` with the following credentials:
+```sh
+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
+```
 
-- 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)
+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/
+      ...
+```
 
-### Create and sync a local data store
+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.
 
-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.
+### Common operations
 
 ```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
+# 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-data --athlete alex progress --watch    # follow an active sync run live
+
+# Strava OAuth uses clientId and clientSecret previously stored for this athlete
+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
 ```
 
-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.
+`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.
 
-### Common commands
+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.
 
-Run these from the repository root. Omit `--data-dir` to use the checkout's `.catence/` directory.
+## Background sync and live progress
 
-```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
-```
+Long Garmin backfills fetch hundreds of days of data and can take 20-30+ minutes. Sync runs stream worker output to the console in real time, tolerate Ctrl+C and SSH/terminal deaths cleanly, and expose a live progress heartbeat you can follow from the CLI, the MCP server, or a Docker helper.
 
-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.
+### What happens during a run
 
-### Connect Strava
+When a sync starts, Catence creates a row in `sync_runs` with status `running` and begins persisting heartbeats to the `sync_run_progress` table (schema migration 14). The Garmin staging worker emits one compact JSON progress record every few seconds on stdout; the runtime parses it, normalizes it, and upserts it. Even if the worker cannot emit — for example while stuck in login — the runtime persists a 30-second fallback heartbeat so a run is always observable and never falsely looks stale.
 
-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
-```
+Each progress record follows the same contract:
 
-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`.
+- `runId`, `provider` — which run the record belongs to
+- `stage` — `starting`, `login`, `singletons`, `daily`, `range`, `ftp_history`, `max_metrics`, `hrv_history`, `scores`, `activities`, `collections` while extracting; `completed` on success; `failed`, `interrupted`, or `timed_out` as terminal states written by the runtime
+- `currentStep` — the endpoint, date, or activity being fetched right now
+- `completedUnits` / `totalUnits` — for example days fetched out of the total days in the window
+- `percentComplete` — 0 to 100
+- `elapsedSeconds` / `estimatedRemainingSeconds` — the ETA is computed once the run has a known total and has completed at least one unit
+- `heartbeatAt` — UTC ISO timestamp of the record
 
-The existing manual flow remains available for headless use:
+### Interruption and stale-run recovery
 
-```sh
-npm run catence-data -- auth strava
-npm run catence-data -- auth strava --code <authorization-code>
-```
+- SIGINT, SIGTERM, and SIGHUP (Ctrl+C, terminal close, `kill`) are trapped on both the Node runtime and the Python worker. The child stops between days and the run is marked `interrupted` in `sync_runs` — never a zombie `running` row — and the process exits with 130/143/129.
+- Before every sync or retry, runs still stuck in `running` for more than 15 minutes are marked `timed_out` (with `completed_at` set), so a dead SSH session cannot block later syncs.
+- Resume a failed or interrupted run without re-reading history with `retry --run <run-id>`.
 
-Catence requests `read`, `activity:read_all`, and `read_all`. To remove the stored Strava connection later, run:
+### Watching progress
 
 ```sh
-npm run catence-data -- disconnect strava
+catence-data --athlete alex progress          # one-shot JSON snapshot
+catence-data --athlete alex progress --watch  # live view; exits when no run is active
 ```
 
-## Run the local Console
+`--watch` renders a compact progress table on a TTY and exits when the last active run finishes; piped output stays JSON.
 
-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.
+The read-only MCP tool `catence_sync_progress` returns the same snapshot — active runs with their latest heartbeat plus the most recent runs — and takes `athleteId` like every other personal-data tool.
 
-### Install and launch
+### Docker deployments
 
-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:
+`scripts/deploy-console.sh` generates a `sync.sh` helper that gained a `progress` command and a `--detach` flag:
 
 ```sh
-uvx catence-console@0.1.0 serve --data-dir /absolute/path/to/catence-data
+cd catence-deploy
+./sync.sh --athlete alex sync --detach     # start the run in the background and return
+./sync.sh --athlete alex progress --watch  # follow it live
+./sync.sh --athlete alex progress          # one-shot snapshot
 ```
 
-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.
+`--detach` works with `backfill` too. A detached run keeps streaming into the container logs (`docker compose -f catence-deploy/docker-compose.yml logs -f console`) and keeps writing heartbeats, so it survives the shell that started it and is recoverable by the next sync.
 
-For source development, install the locally built `catence-chainlit` wheel and run `uv run --project console catence-console serve` from this repository.
+## Safe demo and Glama
 
-### First-run setup
-
-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:
+Run a clearly marked generated dataset without provider accounts:
 
 ```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
+npx --yes catence@0.2.0 demo
 ```
 
-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:
+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.
 
-```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"
-  }
-}
-```
+From a checkout:
 
-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"
-      }
-    }
-  }
-}
+```sh
+npm run mcp -- demo
 ```
 
-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
+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
 ```
 
-For a source checkout, each client should start the same local command, pointing at the same absolute data directory:
+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
-npm --prefix /absolute/path/to/catence run mcp -- --data-dir /absolute/path/to/catence-data
+uvx catence-console@0.2.0 doctor --home "$HOME/.catence" --mcp-url http://127.0.0.1:8787/mcp
 ```
 
-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`.
+Console chats and saved tool context are local at `~/.catence/console/chat-history.sqlite3`.
 
-### Codex
+### Docker and Cloudflare Tunnel
 
-For a first look, add the generated demo server from the terminal:
+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-demo -- npx --yes catence@0.1.0 demo
+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
 ```
 
-For a live npm install, use:
+Initialize the mounted volume before its first production sync, for example:
 
 ```sh
-codex mcp add catence -- catence --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"
 ```
 
-For a source checkout, use:
+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
-codex mcp add catence -- npm --prefix /absolute/path/to/catence run mcp -- --data-dir /absolute/path/to/catence-data
+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
 ```
 
-Alternatively, add this to `~/.codex/config.toml` for a personal installation, or `.codex/config.toml` in a trusted repository:
+## Configuration
 
-```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
-```
+[`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`.
 
-### OpenCode
+### Per-model reasoning effort
 
-Add this local MCP definition to `opencode.json` or `opencode.jsonc`:
+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`.
 
-```jsonc
+**Fixed level** (all requests for the model use it):
+
+```json
 {
-  "$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
+  "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"
+      }
     }
   }
 }
 ```
 
-### Claude Code
-
-Add the local stdio server from a terminal:
-
-```sh
-claude mcp add --transport stdio catence -- npm --prefix /absolute/path/to/catence run mcp -- --data-dir /absolute/path/to/catence-data
-```
-
-Use Claude Code's MCP listing command to confirm it was added:
+**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:
 
-```sh
-claude mcp list
+```json
+"deepseek-v4-flash-free": {
+  "label": "DeepSeek V4 Flash Free",
+  "model": "openai/deepseek-v4-flash-free",
+  "variants": { "High": "high", "Max": "max" }
+}
 ```
 
-### APM and MCPB
+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`).
 
-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:
+**Disabling reasoning effort**: an explicitly empty `variants` map (`"variants": {}`) disables the feature for that model — no `reasoning_effort` is ever sent and the **Thinking effort** dropdown is greyed out. This is how models that reject the parameter (for example MiMo, which expects its own `thinking` toggle) are configured:
 
-```sh
-apm install rifusaki/catence#v0.1.0
+```json
+"mimo-v2.5": {
+  "label": "MiMo V2.5",
+  "model": "openai/mimo-v2.5",
+  "variants": {}
+}
 ```
 
-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.
+A model cannot combine `variants: {}` with a fixed `reasoningEffort`.
 
-## Wellness shortcuts
+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. The dropdown options always follow the model currently selected in the **Model** dropdown.
 
-Catence keeps its flexible catalog and analytical tools, and now exposes four small opinionated wellness tools for common recovery questions:
+For source development:
 
-- `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.
+```sh
+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
+```
 
-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.
+## Beta releases
+
+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.
+
+## Data and caveats
+
+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.
+
+See [distribution notes](docs/distribution.md) for release artifacts, including APM and MCPB demo bundles.
+
+##
+
+```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 progress --athlete martina --home /data --watch           # live sync progress
+docker compose -f docker-compose.yml --env-file .env exec console \
+  catence-data athlete list --home /data                                 # list athlete IDs
+```