catence 0.2.0-beta.10 → 0.2.0-beta.12

package/docs/mcp-activity-retrieval.md

@@ -142,35 +142,12 @@ differs from the activity summary, report both values and the difference.
 
 ## Proposed dedicated MCP endpoints
 
-These endpoints are drafts, not registered tools yet. Add them incrementally
-only after their shared service methods and fixture tests exist.
-
-## Implemented fitness and hydration endpoints
-
-- `describe_dataset(dataset)` returns one cataloged schema and its coverage. `training_metric_observations` also reports its observed sports, metric names, units, and source types.
-- `get_ftp_history`, `get_vo2max_history`, `power_curve_trend`, and `power_coverage_report` read normalized, source-aware fitness facts. Power tools require an explicit sport or sport family, use `power_bests`/`power_best_facts` for FIT-derived duration values, and do not treat sparse `avg_power` summaries as coverage. `get_vo2max_history` does not default to cycling: omission returns available source labels and requires an explicit choice. For Garmin running VO₂max, request `sport: "running"`; the tool reads the raw `generic` source series and preserves that label on returned observations.
-- `find_activities` is implemented for compact, canonical, paginated activity/race discovery by sport, distance, name, and date. Its race flags are transparent heuristics, not provider-confirmed race metadata.
-- `get_activity_segments` is the required segment/climb path. It performs the
-  targeted Strava hydration before returning the persisted effort and segment
-  facts; an empty result must be interpreted alongside its hydration status.
-- `latest_cycling_activities` returns Garmin source records to avoid silently double-counting linked Intervals summaries; optional multisport parents are explicitly flagged.
-- `cycling_progress_report` composes the preceding read-only outputs with monthly canonical volume/load. It is descriptive, not a physiological model.
-- `hydrate_recent_strava_activities` accepts an explicit list or a bounded date/sport window and awaits each write in sequence. Its unmatched output includes the exact Strava search window and safe-match rejection diagnostics.
-
-### Power investigation procedure
-
-For a question about running or cycling power, do not begin with
-`canonical_activities.avg_power`: it is an activity-summary field and can be
-null even when the FIT stream has power. Instead:
-
-1. Call `describe_dataset` for `power_bests` and use `power_coverage_report`
-   with an explicit `sport` or `sportFamily` to establish coverage and every
-   available duration.
-2. Use `power_curve_trend` with the same selector and
-   `sourceQuality: "garmin_fit_derived"` for comparable monthly curve bests.
-3. Inspect `activity_samples` only for a selected `activity_source_id` when a
-   specific extreme needs validation. Raw sample reads are paginated and are
-   not evidence that the global power dataset is absent.
+These endpoints are **drafts, not registered tools yet**. The current server
+(`src/interfaces/mcp/server.ts`) does not expose them, so an agent cannot call
+them today; they are specified here so semantics and acceptance criteria are
+agreed before implementation. Add them incrementally only after their shared
+service methods and fixture tests exist, then move them to the implemented
+list below.
 
 ### `list_recent_activities`
 
@@ -330,9 +307,39 @@ manifest-only Parquet access, and null handling. It returns no data—not an
 error—when the source has no registered stream, with a caveat explaining that
 sample availability is provider/activity-specific.
 
+## Implemented fitness and hydration endpoints
+
+- `describe_dataset(dataset)` returns one cataloged schema and its coverage. `training_metric_observations` also reports its observed sports, metric names, units, and source types.
+- `get_ftp_history`, `get_vo2max_history`, `power_curve_trend`, and `power_coverage_report` read normalized, source-aware fitness facts. Power tools require an explicit sport or sport family, use `power_bests`/`power_best_facts` for FIT-derived duration values, and do not treat sparse `avg_power` summaries as coverage. `get_vo2max_history` does not default to cycling: omission returns available source labels and requires an explicit choice. For Garmin running VO₂max, request `sport: "running"`; the tool reads the raw `generic` source series and preserves that label on returned observations.
+- `find_activities` is implemented for compact, canonical, paginated activity/race discovery by sport, distance, name, and date. Its race flags are transparent heuristics, not provider-confirmed race metadata.
+- `get_activity_segments` is the required segment/climb path. It performs the
+  targeted Strava hydration before returning the persisted effort and segment
+  facts; an empty result must be interpreted alongside its hydration status.
+- `latest_cycling_activities` returns Garmin source records to avoid silently double-counting linked Intervals summaries; optional multisport parents are explicitly flagged.
+- `cycling_progress_report` composes the preceding read-only outputs with monthly canonical volume/load. It is descriptive, not a physiological model.
+- `hydrate_recent_strava_activities` accepts an explicit list or a bounded date/sport window and awaits each write in sequence. Its unmatched output includes the exact Strava search window and safe-match rejection diagnostics.
+
+### Power investigation procedure
+
+For a question about running or cycling power, do not begin with
+`canonical_activities.avg_power`: it is an activity-summary field and can be
+null even when the FIT stream has power. Instead:
+
+1. Call `describe_dataset` for `power_bests` and use `power_coverage_report`
+   with an explicit `sport` or `sportFamily` to establish coverage and every
+   available duration.
+2. Use `power_curve_trend` with the same selector and
+   `sourceQuality: "garmin_fit_derived"` for comparable monthly curve bests.
+3. Inspect `activity_samples` only for a selected `activity_source_id` when a
+   specific extreme needs validation. Raw sample reads are paginated and are
+   not evidence that the global power dataset is absent.
+
 ## Intended agent behaviour
 
-For “how did this go in the context of my recent swims?” an agent should:
+This workflow is the target behaviour once the proposed endpoints above are
+implemented and registered; today the agent must approximate it with
+`find_activities`, `get_activity_segments`, and `read_series`. For “how did
+this go in the context of my recent swims?” an agent should:
 
 1. Use `list_recent_activities` filtered to swimming to identify the selected
    source and comparable source records.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "catence",
-  "version": "0.2.0-beta.10",
+  "version": "0.2.0-beta.12",
   "description": "Local MCP access to normalized Garmin, Intervals.icu, and targeted Strava fitness data.",
   "license": "AGPL-3.0-or-later",
   "repository": {

package/docs/deployment.md

@@ -1,338 +0,0 @@
-# Deploying Catence Console
-
-Catence Console is a password-protected local web chat that starts a matching
-Catence runtime on loopback. There are two supported ways to run it: **locally**
-(npm package + Python Console on your machine) or **in Docker** (one container
-built from the public registries). Both paths end with the same Console, data
-directory layout, model configuration, and credentials model.
-
-Everything below assumes a recent beta or stable release; channels are
-explained in the [beta release notes](../README.md#beta-releases).
-
-## Prerequisites
-
-- Node.js 22+ and Python 3.12+ with [uv](https://docs.astral.sh/uv/)
-  (local path), or Docker Engine with the `docker compose` plugin (Docker path).
-- Provider credentials for the athletes you choose to sync (Garmin,
-  Intervals.icu, Strava).
-- One model-provider key (OpenAI, Anthropic, OpenCode Go, Azure, or any
-  OpenAI-compatible endpoint).
-
-## What gets stored where
-
-| What | Where | Example |
-| --- | --- | --- |
-| Catalog + athlete stores | data home | `~/.catence/` or `/data` in Docker |
-| Model profiles (no secrets) | `config.json` in the data home | `console.profiles` |
-| Provider credentials | per-athlete secret file, mode 0600 | `catence-data secret set` |
-| API keys | process environment only | `.env` in Docker, shell exports locally |
-| Chat history + preferences | data home | `console/chat-history.sqlite3` |
-
-Credentials never land in `config.json`; profiles reference environment
-variable *names* (`apiKeyEnv`, `apiBaseEnv`, `apiVersionEnv`). See
-[`llm-providers.md`](llm-providers.md) for the profile reference and
-[`config.example.json`](../config.example.json) for a complete example.
-
----
-
-## Path A — Local deployment
-
-### 1. Install the runtime and the Console
-
-```sh
-npm install --global catence@beta          # or catence@latest for stable
-uv tool install catence-console            # persistent `catence-console` command
-# alternative to the last line: uvx catence-console@<version> serve (ephemeral)
-```
-
-`catence-console serve` launches a matching Catence runtime automatically: it
-uses a globally installed `catence` if present, otherwise `npx catence@<pinned>`.
-
-### 2. Create the catalog and first athlete
-
-```sh
-catence-data setup --athlete alex --label "Alex"
-```
-
-This creates `~/.catence/` (or `$CATENCE_HOME`). It also tolerates a directory
-that already holds only Console artifacts (`config.json`, `console/`).
-
-### 3. Store provider credentials (stdin only, never shell history)
-
-Garmin (`email`, `password`), Intervals.icu (`apiKey`, `athleteId`), and Strava
-(`clientId`, `clientSecret`):
-
-```sh
-# Garmin
-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
-# Intervals.icu
-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
-# Strava (create an API application at https://www.strava.com/settings/api)
-printf %s 'strava-client-id' | catence-data --athlete alex secret set --provider strava --field clientId --value-stdin
-printf %s 'strava-client-secret' | catence-data --athlete alex secret set --provider strava --field clientSecret --value-stdin
-```
-
-Set only the providers you actually sync; `secret set` accepts each field
-independently.
-
-### 4. Sync data and build retrieval context
-
-```sh
-catence-data --athlete alex sync --provider all
-catence-data --athlete alex build-retrieval-index
-```
-
-### 5. Configure the model
-
-On the first chat, the Console wizard asks for a provider and model and writes
-a starter profile. To start from the documented profiles instead, copy the
-`console` section from [`config.example.json`](../config.example.json) into
-`~/.catence/config.json`. To add OpenCode Go models, run the
-[model discovery script](#model-discovery-opencode-go) below.
-
-### 6. Set the model credentials and Console login
-
-```sh
-export OPENAI_API_KEY='…'                        # or ANTHROPIC_API_KEY / OPENCODE_GO_API_KEY …
-export CATENCE_CONSOLE_USERNAME='coach'
-export CATENCE_CONSOLE_PASSWORD_HASH="$(catence-console auth hash-password)"
-export CHAINLIT_AUTH_SECRET="$(openssl rand -hex 32)"
-```
-
-### 7. Start the Console
-
-```sh
-catence-console serve
-# open http://127.0.0.1:8000
-```
-
-The Model dropdown in the settings panel lists every profile's deployments.
-Preflight with:
-
-```sh
-catence-console doctor
-```
-
----
-
-## Path B — Docker deployment
-
-### 1. Deploy with the script
-
-```sh
-curl -fsSL https://raw.githubusercontent.com/rifusaki/catence/beta/scripts/deploy-console.sh | bash -s beta
-# or from a checkout: ./scripts/deploy-console.sh beta
-# use `stable` instead of `beta` for the stable channel
-```
-
-The script resolves the newest matching versions from npm and PyPI, writes a
-self-contained `catence-deploy/` project (Dockerfile, docker-compose.yml, and
-`.env` with placeholders), builds the image, **seeds a starter
-`/data/config.json`** into the data volume, and starts the stack — or, when
-secrets are missing, prints the remaining steps and exits.
-
-### 2. Fill in `catence-deploy/.env`
-
-```sh
-CATENCE_CONSOLE_USERNAME=coach
-CATENCE_CONSOLE_PASSWORD_HASH='…'      # generate: ./catence-deploy/hash-password.sh
-CHAINLIT_AUTH_SECRET='…'               # generate: openssl rand -hex 32
-OPENAI_API_KEY='…'                     # or ANTHROPIC_API_KEY / OPENCODE_GO_API_KEY …
-OPENAI_API_BASE=''                     # only for OpenAI-compatible endpoints
-OPENCODE_GO_API_KEY='…'                # the OpenCode Go base URLs are pre-filled below
-OPENCODE_GO_API_BASE='https://opencode.ai/zen/go/v1'
-OPENCODE_GO_MESSAGES_API_BASE='https://opencode.ai/zen/go'
-```
-
-Then start the stack (or re-run the script, which re-reads the saved `.env`):
-
-```sh
-docker compose -f catence-deploy/docker-compose.yml --env-file catence-deploy/.env up -d
-```
-
-### 3. Initialize an athlete store
-
-The data volume already contains a seeded `config.json`, so `setup` accepts
-it. Run through the container:
-
-```sh
-docker compose -f catence-deploy/docker-compose.yml --env-file catence-deploy/.env run --rm \
-  --entrypoint catence-data console setup --athlete alex --label "Alex"
-```
-
-### 4. Store provider credentials
-
-Garmin (`email`, `password`), Intervals.icu (`apiKey`, `athleteId`), and Strava
-(`clientId`, `clientSecret`), one `printf` per field:
-
-```sh
-# Garmin
-printf %s 'alex@example.com' | docker compose -f catence-deploy/docker-compose.yml --env-file catence-deploy/.env run --rm -T \
-  --entrypoint catence-data console --athlete alex secret set \
-  --provider garmin --field email --value-stdin
-printf %s 'your-garmin-password' | docker compose -f catence-deploy/docker-compose.yml --env-file catence-deploy/.env run --rm -T \
-  --entrypoint catence-data console --athlete alex secret set \
-  --provider garmin --field password --value-stdin
-# Intervals.icu
-printf %s 'intervals-api-key' | docker compose -f catence-deploy/docker-compose.yml --env-file catence-deploy/.env run --rm -T \
-  --entrypoint catence-data console --athlete alex secret set \
-  --provider intervals --field apiKey --value-stdin
-printf %s '12345' | docker compose -f catence-deploy/docker-compose.yml --env-file catence-deploy/.env run --rm -T \
-  --entrypoint catence-data console --athlete alex secret set \
-  --provider intervals --field athleteId --value-stdin
-# Strava (create an API application at https://www.strava.com/settings/api)
-printf %s 'strava-client-id' | docker compose -f catence-deploy/docker-compose.yml --env-file catence-deploy/.env run --rm -T \
-  --entrypoint catence-data console --athlete alex secret set \
-  --provider strava --field clientId --value-stdin
-printf %s 'strava-client-secret' | docker compose -f catence-deploy/docker-compose.yml --env-file catence-deploy/.env run --rm -T \
-  --entrypoint catence-data console --athlete alex secret set \
-  --provider strava --field clientSecret --value-stdin
-```
-
-Set only the providers you actually sync. Use the same `--entrypoint
-catence-data` pattern for `sync`, `backfill`, and `auth strava`.
-
-### 5. Configure the model
-
-The seeded `config.json` already offers OpenAI, OpenAI-compatible, and
-Anthropic starter profiles, so the settings panel works before the first chat.
-Edit `/data/config.json` inside the volume:
-
-```sh
-docker compose -f catence-deploy/docker-compose.yml --env-file catence-deploy/.env run --rm \
-  --entrypoint sh console -c 'cat > /data/config.json'   # paste JSON, then Ctrl-D
-```
-
-With `--home <dir>` (bind mount), edit `<dir>/config.json` on the host
-instead. To add OpenCode Go models, see [model discovery](#model-discovery-opencode-go).
-
-### 6. Verify with doctor
-
-`catence-console doctor` checks each profile's environment variables and the
-local Catence runtime. The deploy scaffold includes a helper for it:
-
-```sh
-./catence-deploy/doctor.sh
-```
-
-The helper runs the doctor *inside the running container* with `exec` — the
-container's own loopback holds the live MCP server at `127.0.0.1:8787`, and the
-provider keys from `.env` are already in its environment. (A `docker compose
-run` container has a separate loopback and would report the runtime as
-unreachable.) The equivalent long form is:
-
-```sh
-docker compose -f catence-deploy/docker-compose.yml --env-file catence-deploy/.env exec console \
-  /opt/catence-console/bin/catence-console doctor --home /data --mcp-url http://127.0.0.1:8787/mcp
-```
-
-Expect `"ready": true` once the model key is set; missing keys show up per
-profile without ever printing their values.
-
-### 7. Sync, backfill, and inspect athlete data
-
-The deploy scaffold includes a helper that runs `catence-data` *inside the
-running container* with `exec`, so the athlete's provider secrets from the
-data volume are already available:
-
-```sh
-./catence-deploy/sync.sh --athlete alex sync                  # incremental sync, all providers
-./catence-deploy/sync.sh --athlete alex backfill 2026-01-01   # full backfill from a date
-./catence-deploy/sync.sh --athlete alex status                # coverage and errors
-./catence-deploy/sync.sh athletes                             # list athlete IDs
-```
-
-`sync` defaults to `--provider all`; extra flags pass through, for example
-`./catence-deploy/sync.sh --athlete alex sync --refresh` or
-`./catence-deploy/sync.sh --athlete alex backfill 2026-01-01 --provider garmin`.
-Set a default athlete with `export CATENCE_ATHLETE=alex` to drop the
-`--athlete` argument. The equivalent long form is:
-
-```sh
-docker compose -f catence-deploy/docker-compose.yml --env-file catence-deploy/.env exec console \
-  catence-data sync --athlete alex --provider all --home /data
-```
-
-### 8. Expose the Console safely
-
-Keep the Console port bound to `127.0.0.1` (the default) and front it with a
-Cloudflare Tunnel or reverse proxy at HTTPS. Never expose Catence's MCP port
-8787 — it stays loopback-only inside the container. For remote MCP checks use
-SSH port forwarding (`ssh -L 8787:127.0.0.1:8787 server`).
-
----
-
-## Model discovery (OpenCode Go)
-
-OpenCode Go publishes an OpenAI-compatible API at
-`https://opencode.ai/zen/go/v1`; its model list is public. The discovery
-script fetches it and merges two ready-made profiles into `config.json`:
-`opencode-go` (chat + responses models, base `…/zen/go/v1`) and
-`opencode-go-messages` (messages models, base `…/zen/go`). Existing profiles,
-limits, and `defaultProfile` are preserved unless `--set-default` is passed.
-
-```sh
-# Local (from a checkout)
-npm run discover:opencode-go -- --write ~/.catence/config.json
-
-# Docker (the script ships inside the npm package in the image)
-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
-```
-
-Then set the credentials and verify. The generated `.env` already contains
-`OPENCODE_GO_API_BASE` and `OPENCODE_GO_MESSAGES_API_BASE`, so on Docker only
-the key is missing:
-
-```sh
-export OPENCODE_GO_API_KEY='…'                      # any non-empty value passes the key check
-catence-console doctor
-```
-
-The `openai/responses/…` models (for example `grok-4.5`) go through LiteLLM's
-responses bridge and are the least battle-tested path; smoke-test one chat turn
-before relying on them.
-
----
-
-## Updating
-
-From `catence-data update`-capable releases (0.2.0-beta.3 and later), the
-runtime updates both components on the tracked channel — beta installs follow
-the npm `beta` tag and matching PyPI prereleases:
-
-```sh
-catence-data update --check      # report only; exit 1 when updates are pending
-catence-data update              # npm runtime + uv tool catence-console upgrade
-catence-data update --channel stable   # move off a beta onto the stable channel
-```
-
-Older betas (for example a beta 2 install) predate the command; upgrade them
-manually once:
-
-```sh
-npm install --global catence@beta
-uv tool install --upgrade catence-console
-```
-
-Docker deployments: re-run `deploy-console.sh beta` (or `stable`); it
-re-resolves the newest versions from the registries and rebuilds. The data
-volume and your `config.json` are preserved.
-
-## Troubleshooting
-
-- **"No Catence config exists"** — should not happen after a seeded deploy or
-  wizard run; ensure `/data/config.json` (Docker) or `~/.catence/config.json`
-  exists and contains a `console` section.
-- **"Refusing to initialize"** — the data home contains unrelated files; the
-  error lists them. Console artifacts (`config.json`, `console/`, and Chainlit's
-  `.files/`, `.chainlit/`, `public/`) are allowed; anything else blocks `setup`.
-- **Settings panel has no Model dropdown** — the Console loads profiles from
-  `config.json`; write one via the wizard, a manual copy, or the discovery
-  script.
-- **Profile not ready** — `catence-console doctor` lists the missing
-  environment variables; set them in `.env` (Docker) or the shell (local) and
-  restart the Console.

package/docs/docker-deployment.md

@@ -1,232 +0,0 @@
-# Docker Deployment Quick Start and Common Commands
-
-This document mirrors the [local quick start](../README.md#quick-start) and [common operations](../README.md#common-operations) for Catence when deployed via Docker. It assumes you have completed the [deployment steps](deployment.md#path-b--docker-deployment) and have a running `catence-deploy` stack.
-
-## Quick Start (Docker)
-
-All commands run from the `catence-deploy` directory created by the deploy script.
-
-### 1. Initialize an athlete store
-
-```sh
-docker compose -f docker-compose.yml --env-file .env run --rm \
-  --entrypoint catence-data console setup --athlete alex --label "Alex"
-```
-
-### 2. Store provider credentials (stdin only, never shell history)
-
-```sh
-# Garmin
-printf %s 'alex@example.com' | docker compose -f docker-compose.yml --env-file .env run --rm -T \
-  --entrypoint catence-data console --athlete alex secret set \
-  --provider garmin --field email --value-stdin
-printf %s 'your-garmin-password' | docker compose -f docker-compose.yml --env-file .env run --rm -T \
-  --entrypoint catence-data console --athlete alex secret set \
-  --provider garmin --field password --value-stdin
-
-# Intervals.icu
-printf %s 'intervals-api-key' | docker compose -f docker-compose.yml --env-file .env run --rm -T \
-  --entrypoint catence-data console --athlete alex secret set \
-  --provider intervals --field apiKey --value-stdin
-printf %s '12345' | docker compose -f docker-compose.yml --env-file .env run --rm -T \
-  --entrypoint catence-data console --athlete alex secret set \
-  --provider intervals --field athleteId --value-stdin
-
-# Strava (create an API application at https://www.strava.com/settings/api)
-printf %s 'strava-client-id' | docker compose -f docker-compose.yml --env-file .env run --rm -T \
-  --entrypoint catence-data console --athlete alex secret set \
-  --provider strava --field clientId --value-stdin
-printf %s 'strava-client-secret' | docker compose -f docker-compose.yml --env-file .env run --rm -T \
-  --entrypoint catence-data console --athlete alex secret set \
-  --provider strava --field clientSecret --value-stdin
-```
-
-### 3. Sync data and build retrieval context
-
-```sh
-docker compose -f docker-compose.yml --env-file .env exec console \
-  catence-data sync --athlete alex --provider all --home /data
-docker compose -f docker-compose.yml --env-file .env exec console \
-  catence-data build-retrieval-index --athlete alex --home /data
-```
-
-### 4. Access the Console
-
-Open `http://127.0.0.1:8000` (or the `--bind:--port` you configured) and log in with `CATENCE_CONSOLE_USERNAME` and the password whose hash is in `CATENCE_CONSOLE_PASSWORD_HASH`.
-
----
-
-## Common Operations (Docker)
-
-The `sync.sh` helper in `catence-deploy/` wraps the most frequent `catence-data` calls inside the **running** container (so the provider secrets from the data volume are already available).
-
-```sh
-# Incremental sync for one athlete (all providers)
-./sync.sh --athlete alex sync
-
-# Sync a specific provider
-./sync.sh --athlete alex sync --provider intervals
-
-# Sync from a specific date (Garmin)
-./sync.sh --athlete alex sync --provider garmin --from 2025-07-29
-
-# Full backfill from a date
-./sync.sh --athlete alex backfill 2026-01-01
-
-# Backfill with refresh (re-fetch existing data)
-./sync.sh --athlete alex backfill 2026-01-01 --refresh
-
-# Retry a failed sync run
-./sync.sh --athlete alex retry --run <run-id>
-
-# Coverage and error status
-./sync.sh --athlete alex status
-
-# List athlete IDs in the catalog
-./sync.sh athletes
-
-# Strava OAuth (uses clientId/clientSecret stored for this athlete)
-docker compose -f docker-compose.yml --env-file .env exec console \
-  catence-data auth strava --athlete alex --callback --home /data
-docker compose -f docker-compose.yml --env-file .env exec console \
-  catence-data disconnect strava --athlete alex --home /data
-
-# Strava OAuth via SSH (remote Docker host accessed over SSH/Tailscale)
-## Option 1: SSH Port Forwarding (recommended)
-# On your LOCAL machine, forward the callback port to the remote Docker host:
-ssh -L 8765:127.0.0.1:8765 user@docker-host
-# Then run the standard callback flow on the REMOTE host (uses http://127.0.0.1:8765/strava/callback)
-docker compose -f docker-compose.yml --env-file .env exec console \
-  catence-data auth strava --athlete alex --callback --home /data
-
-## Option 2: Manual code exchange with http://localhost
-# On the REMOTE host, get the authorization URL:
-docker compose -f docker-compose.yml --env-file .env run --rm \
-  --entrypoint catence-data console auth strava \
-  --athlete alex --redirect-uri "http://localhost" --home /data
-# Open the printed URL in YOUR LOCAL BROWSER, approve Strava, then copy the 'code' from the redirect URL
-# Exchange the code on the REMOTE host:
-docker compose -f docker-compose.yml --env-file .env run --rm \
-  --entrypoint catence-data console auth strava \
-  --athlete alex --code "THE_CODE_FROM_URL" --redirect-uri "http://localhost" --home /data
-
-# Update the runtime and Console (re-run deploy script on the same channel)
-curl -fsSL https://raw.githubusercontent.com/rifusaki/catence/beta/scripts/deploy-console.sh | bash -s beta
-# or from checkout: ./scripts/deploy-console.sh beta
-
-# Choose a non-default catalog location (bind mount instead of named volume)
-# Stop the stack, edit docker-compose.yml to replace the volume with:
-#   volumes:
-#     - /srv/catence:/data
-# Then restart and run the same commands (--home /data is implied by CATENCE_HOME).
-```
-
----
-
-## Connecting to the Docker-based MCP from Outside
-
-### The MCP Server Inside the Container
-
-By default, the Catence MCP server runs on **loopback only** inside the container at `http://127.0.0.1:8787/mcp`. It is **never exposed** to the host network or the internet — this is intentional for security.
-
-The `CATENCE_MCP_BIND` variable controls **two things at once**:
-
-1. **Docker port mapping**: which host interface exposes port 8787 to the Docker host.
-2. **Server listen address**: which address the MCP server binds to inside the container.
-
-| Value | Docker maps | Server binds | Effect |
-|-------|-------------|--------------|--------|
-| `127.0.0.1` (default) | `127.0.0.1:8787 → container:8787` | `127.0.0.1` | MCP reachable only from the Docker host's loopback — requires SSH tunnel for remote access. |
-| `0.0.0.0` | `0.0.0.0:8787 → container:8787` | `0.0.0.0` | MCP reachable from any network interface — suitable for Tailscale or VPN exposure. |
-
-Set it at deploy time with `--mcp-bind`, or by editing `CATENCE_MCP_BIND` in `.env`:
-
-```sh
-# Default (loopback only — SSH tunnel required for remote access)
-./scripts/deploy-console.sh beta
-
-# Tailscale / network exposure
-./scripts/deploy-console.sh beta --mcp-bind 0.0.0.0
-```
-
-To change the binding after deployment, update `CATENCE_MCP_BIND` in `.env` and restart:
-
-```sh
-sed -i 's/CATENCE_MCP_BIND=.*/CATENCE_MCP_BIND=0.0.0.0/' catence-deploy/.env
-docker compose -f catence-deploy/docker-compose.yml --env-file catence-deploy/.env up -d
-```
-
-### SSH Port Forwarding (Recommended for Remote MCP Clients)
-
-From your **local machine**, forward the container's MCP port through the Docker host:
-
-```sh
-# Forward local port 8787 → Docker host port 8787 → container loopback 8787
-ssh -L 8787:127.0.0.1:8787 user@docker-host
-```
-
-Then point your MCP client at `http://127.0.0.1:8787/mcp` on your local machine.
-
-### Exposing MCP on Tailscale (Alternative)
-
-To expose the MCP server directly on a Tailscale interface (or any network interface) without SSH tunneling:
-
-```sh
-# Deploy with MCP bound to all interfaces (0.0.0.0) — restrict via Tailscale ACLs/firewall
-./scripts/deploy-console.sh beta --mcp-bind 0.0.0.0
-```
-
-Or set the environment variable before deploying:
-
-```sh
-CATENCE_MCP_BIND=0.0.0.0 ./scripts/deploy-console.sh beta
-```
-
-After deployment, the MCP server is available at `http://<tailscale-ip>:8787/mcp` from any device on your tailnet.
-
-**Security note**: The MCP server has **no authentication** — it trusts the caller's `athleteId` parameter. When exposing on `0.0.0.0`, you **must** restrict access at the network layer (Tailscale ACLs, firewall rules, etc.). The Console UI remains on loopback (`127.0.0.1:8000`) and should still be fronted by Cloudflare Tunnel or a reverse proxy.
-
-**Examples: Common MCP Clients**
-
-```sh
-# Via SSH tunnel (default loopback deployment)
-# Opencode
-opencode mcp add catence -- http://127.0.0.1:8787/mcp
-
-# Codex
-codex mcp add catence -- http://127.0.0.1:8787/mcp
-
-# Claude Desktop
-claude mcp add --transport http catence -- http://127.0.0.1:8787/mcp
-```
-
-```sh
-# Via Tailscale (when deployed with --mcp-bind 0.0.0.0)
-# Replace <tailscale-ip> with your server's Tailscale IP (from `tailscale ip`)
-# Opencode
-opencode mcp add catence -- http://<tailscale-ip>:8787/mcp
-
-# Codex
-codex mcp add catence -- http://<tailscale-ip>:8787/mcp
-
-# Claude Desktop
-claude mcp add --transport http catence -- http://<tailscale-ip>:8787/mcp
-```
-
-### Why Not Expose Port 8787 Directly?
-
-- The MCP server has **no authentication** — it trusts the caller's `athleteId` parameter.
-- Exposing it would allow any network caller to read all athlete data in the catalog.
-- The Console proxies dashboard requests through its **authenticated** same-origin route.
-- SSH port forwarding keeps the trust boundary at your SSH credentials.
-
----
-
-## Quick Reference: `docker compose run` vs `docker compose exec`
-
-| Command Type | Use For | Example |
-|--------------|---------|---------|
-| `run --rm --entrypoint catence-data console` | **One-off setup/secrets** — needs fresh stdin for `--value-stdin`, no running container required | `secret set`, `setup`, `auth strava --code` |
-| `exec console catence-data` | **Recurring ops** — uses the running container's environment (secrets already in volume) | `sync`, `backfill`, `status`, `build-retrieval-index` |
-
-The `sync.sh` helper uses `exec` for this reason.