catence 0.2.0-beta.1 → 0.2.0-beta.10

package/dist/elt/storage/database.js

@@ -2,6 +2,7 @@ import { DuckDBInstance } from '@duckdb/node-api';
 import { randomUUID } from 'node:crypto';
 import { existsSync } from 'node:fs';
 import { ReadOnlyRepository } from '../../core/query/repository.js';
+import { SYNC_STAGES, STALE_RUN_TIMEOUT_MS } from '../../contracts/progress.js';
 import { migrations } from './migrations.js';
 import { json } from './sql.js';
 export class CatenceDatabase {
@@ -81,6 +82,66 @@ export class CatenceDatabase {
         await this.run(`UPDATE sync_runs SET status = CASE WHEN error_count > 0 THEN 'completed_with_errors' ELSE 'completed' END, completed_at = now() WHERE run_id = $runId`, { runId });
         await this.run("UPDATE retrieval_index_state SET status = 'stale' WHERE index_name = 'context'");
     }
+    async heartbeatRun(runId, progress) {
+        await this.run(`INSERT INTO sync_run_progress (run_id, provider, stage, current_step, completed_units, total_units, percent, elapsed_seconds, estimated_remaining_seconds, heartbeat_at, detail_json)
+       VALUES ($runId, $provider, $stage, $currentStep, $completedUnits, $totalUnits, $percent, $elapsedSeconds, $estimatedRemainingSeconds, now(), '{}')
+       ON CONFLICT (run_id) DO UPDATE SET
+         provider = EXCLUDED.provider,
+         stage = EXCLUDED.stage,
+         current_step = EXCLUDED.current_step,
+         completed_units = EXCLUDED.completed_units,
+         total_units = EXCLUDED.total_units,
+         percent = EXCLUDED.percent,
+         elapsed_seconds = EXCLUDED.elapsed_seconds,
+         estimated_remaining_seconds = EXCLUDED.estimated_remaining_seconds,
+         heartbeat_at = now(),
+         detail_json = '{}'`, {
+            runId,
+            provider: progress.provider,
+            stage: progress.stage,
+            currentStep: progress.currentStep,
+            completedUnits: progress.completedUnits,
+            totalUnits: progress.totalUnits,
+            percent: progress.percentComplete,
+            elapsedSeconds: progress.elapsedSeconds,
+            estimatedRemainingSeconds: progress.estimatedRemainingSeconds,
+        });
+    }
+    async markRunInterrupted(runId, stage = 'interrupted') {
+        await this.run("UPDATE sync_runs SET status = 'interrupted', completed_at = now() WHERE run_id = $runId AND status = 'running'", { runId });
+        await this.run('UPDATE sync_run_progress SET stage = $stage, heartbeat_at = now() WHERE run_id = $runId', { runId, stage });
+    }
+    async interruptStaleSyncRuns(timeoutMs = STALE_RUN_TIMEOUT_MS) {
+        const cutoff = new Date(Date.now() - timeoutMs).toISOString();
+        const stale = await this.rows(`SELECT run_id FROM sync_runs WHERE status = 'running' AND started_at < $cutoff`, { cutoff });
+        for (const row of stale) {
+            await this.run("UPDATE sync_runs SET status = 'timed_out', completed_at = now() WHERE run_id = $runId AND status = 'running'", { runId: row.run_id });
+            await this.run("UPDATE sync_run_progress SET stage = 'timed_out', heartbeat_at = now() WHERE run_id = $runId", { runId: row.run_id });
+        }
+        return { runIds: stale.map((row) => row.run_id) };
+    }
+    async syncProgress() {
+        const running = await this.rows(`SELECT runs.run_id, runs.provider,
+         coalesce(progress.stage, 'starting') AS stage,
+         progress.current_step AS current_step,
+         coalesce(progress.completed_units, 0) AS completed_units,
+         progress.total_units AS total_units,
+         coalesce(progress.percent, 0) AS percent,
+         coalesce(progress.elapsed_seconds, 0) AS elapsed_seconds,
+         progress.estimated_remaining_seconds AS estimated_remaining_seconds,
+         cast(coalesce(progress.heartbeat_at, runs.started_at) AS VARCHAR) AS heartbeat_at
+       FROM sync_runs AS runs
+       LEFT JOIN sync_run_progress AS progress USING (run_id)
+       WHERE runs.status = 'running'
+       ORDER BY runs.started_at DESC`);
+        const recent = await this.rows(`SELECT progress.run_id, progress.provider, progress.stage, progress.current_step,
+         progress.completed_units, progress.total_units, progress.percent, progress.elapsed_seconds,
+         progress.estimated_remaining_seconds, cast(progress.heartbeat_at AS VARCHAR) AS heartbeat_at
+       FROM sync_run_progress AS progress
+       ORDER BY progress.heartbeat_at DESC
+       LIMIT 10`);
+        return { running: running.map(toSyncProgressState), recent: recent.map(toSyncProgressState) };
+    }
     async addError(runId, provider, endpoint, remoteId, message, retryable) {
         await this.run(`INSERT INTO normalization_errors (error_id, run_id, provider, endpoint, remote_id, message, retryable)
        VALUES ($errorId, $runId, $provider, $endpoint, $remoteId, $message, $retryable)`, { errorId: randomUUID(), runId, provider, endpoint, remoteId, message, retryable });
@@ -94,9 +155,11 @@ export class CatenceDatabase {
         const rawObjects = await this.rows('SELECT count(*)::INTEGER AS count FROM raw_objects');
         const activities = await this.rows('SELECT count(*)::INTEGER AS count FROM activities');
         const streams = await this.rows('SELECT count(*)::INTEGER AS count FROM stream_manifest');
+        const errorDetails = await this.rows('SELECT run_id, provider, endpoint, remote_id, message, cast(created_at AS VARCHAR) AS created_at FROM normalization_errors WHERE resolved_at IS NULL ORDER BY created_at DESC LIMIT 100');
         const cursors = await this.rows('SELECT provider, cursor_name, cast(covered_through_date AS VARCHAR) AS covered_through_date, cast(latest_source_date AS VARCHAR) AS latest_source_date, lookback_days, last_successful_run_id, cast(last_completed_at AS VARCHAR) AS last_completed_at, status FROM sync_cursors ORDER BY provider, cursor_name');
         return {
             runs, unresolvedErrors: errors[0]?.count ?? 0, rawObjects: rawObjects[0]?.count ?? 0, activities: activities[0]?.count ?? 0, streams: streams[0]?.count ?? 0,
+            errors: errorDetails,
             cursors: cursors.map((cursor) => ({ ...cursor, next_from_date: subtractDays(cursor.covered_through_date, Number(cursor.lookback_days)) })),
         };
     }
@@ -281,10 +344,6 @@ export class ReadOnlyCatenceDatabase {
         }
     }
 }
-/** Compose core read services with the DuckDB-backed, read-only adapter. */
-export async function openReadOnlyRepository(paths) {
-    return new ReadOnlyRepository(await ReadOnlyCatenceDatabase.open(paths), paths);
-}
 export class ReadOnlyDatabaseError extends Error {
     code;
     constructor(code, message) {
@@ -293,4 +352,22 @@ export class ReadOnlyDatabaseError extends Error {
         this.name = 'ReadOnlyDatabaseError';
     }
 }
+/** Compose core read services with the DuckDB-backed, read-only adapter. */
+export async function openReadOnlyRepository(paths) {
+    return new ReadOnlyRepository(await ReadOnlyCatenceDatabase.open(paths), paths);
+}
+function toSyncProgressState(row) {
+    return {
+        runId: row.run_id,
+        provider: row.provider,
+        stage: SYNC_STAGES.includes(row.stage) ? row.stage : 'starting',
+        currentStep: row.current_step,
+        completedUnits: Math.max(0, Number(row.completed_units) || 0),
+        totalUnits: row.total_units === null || row.total_units === undefined ? null : Math.max(0, Number(row.total_units) || 0),
+        percentComplete: Math.min(100, Math.max(0, Number(row.percent) || 0)),
+        elapsedSeconds: Math.max(0, Number(row.elapsed_seconds) || 0),
+        estimatedRemainingSeconds: row.estimated_remaining_seconds === null || row.estimated_remaining_seconds === undefined ? null : Math.max(0, Number(row.estimated_remaining_seconds) || 0),
+        heartbeatAt: row.heartbeat_at,
+    };
+}
 //# sourceMappingURL=database.js.map

package/dist/elt/storage/migrations.js

@@ -828,5 +828,29 @@ const swimFactsAndQualityMigration = {
     UPDATE retrieval_index_state SET status = 'stale' WHERE index_name = 'context';
   `,
 };
-export const migrations = [...baseMigrations, stravaAndIdentityMigration, garminPrimaryAndTrainingMetricsMigration, garminActivitySportAndFtpBackfillMigration, garminPrimaryDailyHealthMigration, garminHistoricalMetricsAndStreamsMigration, garminUtcActivityTimestampMigration, garminLactateThresholdMetricsMigration, swimFactsAndQualityMigration];
+const syncRunProgressMigration = {
+    version: 14,
+    name: 'sync_run_progress_heartbeats',
+    sql: `
+    -- Live progress heartbeats for in-flight sync runs. Written by the Node
+    -- side from progress records streamed by provider workers; read-only
+    -- surfaces (status, progress CLI, MCP) join against sync_runs.
+    CREATE TABLE IF NOT EXISTS sync_run_progress (
+      run_id VARCHAR PRIMARY KEY,
+      provider VARCHAR NOT NULL,
+      stage VARCHAR NOT NULL,
+      current_step VARCHAR,
+      completed_units INTEGER NOT NULL DEFAULT 0,
+      total_units INTEGER,
+      percent DOUBLE NOT NULL DEFAULT 0,
+      elapsed_seconds DOUBLE NOT NULL DEFAULT 0,
+      estimated_remaining_seconds DOUBLE,
+      heartbeat_at TIMESTAMPTZ NOT NULL,
+      detail_json JSON NOT NULL DEFAULT '{}'
+    );
+
+    UPDATE retrieval_index_state SET status = 'stale' WHERE index_name = 'context';
+  `,
+};
+export const migrations = [...baseMigrations, stravaAndIdentityMigration, garminPrimaryAndTrainingMetricsMigration, garminActivitySportAndFtpBackfillMigration, garminPrimaryDailyHealthMigration, garminHistoricalMetricsAndStreamsMigration, garminUtcActivityTimestampMigration, garminLactateThresholdMetricsMigration, swimFactsAndQualityMigration, syncRunProgressMigration];
 //# sourceMappingURL=migrations.js.map

package/dist/interfaces/cli/commands.js

@@ -2,7 +2,7 @@
 import { createInterface } from 'node:readline/promises';
 import { stdin as input, stdout as output } from 'node:process';
 import { Command } from 'commander';
-import { addAthlete, athleteStorePaths, createDemoStore, dataStatus, defaultCatalogHome, disconnectStravaAccount, initializeCatalog, linkActivity, loadCatalog, rebuildRetrievalIndex, resolveAthlete, resolveCatalogPaths, retryDataSync, setAthleteSecret, syncData, connectStrava, connectStravaWithCallback, unlinkActivity, } from '../../runtime/index.js';
+import { addAthlete, athleteStorePaths, CATENCE_RUNTIME_VERSION, channelForVersion, createDemoStore, dataStatus, defaultCatalogHome, disconnectStravaAccount, fetchNpmDistTags, fetchPypiReleases, hasCommand, initializeCatalog, isGlobalNpmInstall, linkActivity, loadCatalog, npmGlobalPrefix, planSelfUpdate, readInstalledConsoleVersion, rebuildRetrievalIndex, resolveAthlete, resolveCatalogPaths, retryDataSync, runSelfUpdateCommand, setAthleteSecret, syncData, syncProgress, connectStrava, connectStravaWithCallback, unlinkActivity, } from '../../runtime/index.js';
 const program = new Command()
     .name('catence-data')
     .description('Athlete-scoped Catence data setup, extraction, and normalization.')
@@ -158,6 +158,96 @@ program.command('status').action(async () => {
     const { paths } = await currentAthlete();
     process.stdout.write(`${JSON.stringify(await dataStatus(paths), null, 2)}\n`);
 });
+function renderProgress(snapshot) {
+    const lines = snapshot.running.map((run) => {
+        const pct = run.percentComplete.toFixed(1).padStart(5);
+        const units = run.totalUnits !== null ? `${run.completedUnits}/${run.totalUnits}` : String(run.completedUnits);
+        const eta = run.estimatedRemainingSeconds !== null ? `${Math.round(run.estimatedRemainingSeconds)}s` : '?';
+        const step = run.currentStep ?? '';
+        return `${pct}%  ${run.stage.padEnd(12)} ${units.padEnd(11)} ${eta.padEnd(6)} ${step}`;
+    });
+    return lines.length === 0 ? 'no active sync runs' : lines.join('\n');
+}
+program.command('progress')
+    .description('Show live progress for active sync runs.')
+    .option('--watch', 'refresh every few seconds until no sync runs are active')
+    .action(async (options) => {
+    const { paths } = await currentAthlete();
+    if (!options.watch) {
+        process.stdout.write(`${JSON.stringify(await syncProgress(paths), null, 2)}\n`);
+        return;
+    }
+    while (true) {
+        const snapshot = await syncProgress(paths);
+        if (output.isTTY) {
+            output.write(`\x1b[2J\x1b[H${renderProgress(snapshot)}\n`);
+        }
+        else {
+            process.stdout.write(`${JSON.stringify(snapshot, null, 2)}\n`);
+        }
+        if (snapshot.running.length === 0)
+            break;
+        await new Promise((resolve) => setTimeout(resolve, 3000));
+    }
+});
+program.command('update')
+    .description('Check for and apply the newest Catence release on the tracked channel (runtime and Console).')
+    .option('--check', 'report available releases without changing anything')
+    .option('--channel <stable|beta>', 'release channel to track; defaults to the installed runtime channel')
+    .option('--runtime', 'only check or update the Catence runtime package')
+    .option('--console', 'only check or update the Catence Console package')
+    .action(async (options) => {
+    if (options.channel !== undefined && options.channel !== 'stable' && options.channel !== 'beta') {
+        throw new Error('--channel must be stable or beta.');
+    }
+    const channel = options.channel ?? channelForVersion(CATENCE_RUNTIME_VERSION);
+    const runtimeOnly = options.runtime ?? false;
+    const consoleOnly = options.console ?? false;
+    const updateRuntime = runtimeOnly || !consoleOnly;
+    const updateConsole = consoleOnly || !runtimeOnly;
+    const [npmDistTags, pypiReleases, consoleInstalled] = await Promise.all([
+        fetchNpmDistTags('catence'),
+        fetchPypiReleases('catence-console'),
+        readInstalledConsoleVersion(),
+    ]);
+    const plan = planSelfUpdate({ runtimeVersion: CATENCE_RUNTIME_VERSION, channel, npmDistTags, pypiReleases, consoleInstalled });
+    const report = { channel, runtime: plan.runtime, console: plan.console };
+    if (options.check) {
+        process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+        process.exit(plan.ok ? 0 : 1);
+    }
+    const applied = [];
+    if (plan.runtime.updateAvailable && updateRuntime) {
+        const runtimeTarget = plan.runtime.target;
+        if (runtimeTarget === undefined)
+            throw new Error('No runtime update target is available.');
+        const npmPrefix = await npmGlobalPrefix();
+        if (isGlobalNpmInstall(import.meta.url, npmPrefix)) {
+            const exitCode = await runSelfUpdateCommand('npm', ['install', '--global', `catence@${runtimeTarget}`]);
+            if (exitCode !== 0)
+                throw new Error(`npm failed to install catence@${runtimeTarget} (exit ${exitCode}).`);
+            applied.push(`runtime: catence@${runtimeTarget}`);
+        }
+        else {
+            process.stderr.write(`Runtime is not a global npm install; run: npm install --global catence@${runtimeTarget}\n`);
+        }
+    }
+    if (plan.console.updateAvailable && updateConsole) {
+        const consoleTarget = plan.console.target;
+        if (consoleTarget === undefined)
+            throw new Error('No Console update target is available.');
+        if (await hasCommand('uv')) {
+            const exitCode = await runSelfUpdateCommand('uv', ['tool', 'install', '--upgrade', `catence-console==${consoleTarget}`]);
+            if (exitCode !== 0)
+                throw new Error(`uv failed to install catence-console==${consoleTarget} (exit ${exitCode}).`);
+            applied.push(`console: catence-console==${consoleTarget}`);
+        }
+        else {
+            process.stderr.write(`uv is not installed; run: pip install --upgrade 'catence-console==${consoleTarget}'\n`);
+        }
+    }
+    process.stdout.write(`${JSON.stringify({ ...report, applied }, null, 2)}\n`);
+});
 program.command('build-retrieval-index').description('Build derived local retrieval context for one athlete.').action(async () => {
     const { paths } = await currentAthlete();
     process.stdout.write(`${JSON.stringify(await rebuildRetrievalIndex(paths), null, 2)}\n`);

package/dist/interfaces/mcp/server.js

@@ -231,6 +231,13 @@ export function createCatenceMcpServer(paths = resolveCatalogPaths(), dependenci
         data: { ...(await repository.status()), ...(await repository.coverage()) },
         provenance: { database: 'read-only DuckDB snapshot' }, query: {}, caveats: [],
     }))));
+    server.registerTool('catence_sync_progress', {
+        title: 'Catence sync progress',
+        description: 'Read live progress heartbeats for active sync runs, plus the most recent completed or interrupted runs. Read-only.',
+    }, tool('catence_sync_progress', async () => useRepository(activePaths(), async (repository) => ({
+        data: await repository.progress(),
+        provenance: { database: 'read-only DuckDB snapshot' }, query: {}, caveats: [],
+    }))));
     server.registerTool('review_daily_recovery_load', {
         title: 'Review daily recovery and training load',
         description: 'Return source-cited daily health, training, and nutrition facts for a recovery/load review. It does not prescribe a training plan.',

package/dist/runtime/index.d.ts

@@ -7,6 +7,8 @@
  * without changing the public product adapters.
  */
 export type { CatencePaths } from '../contracts/runtime.js';
+export { channelForVersion, compareReleaseVersions, fetchNpmDistTags, fetchPypiReleases, hasCommand, isGlobalNpmInstall, latestRelease, npmGlobalPrefix, parseReleaseVersion, planSelfUpdate, readInstalledConsoleVersion, runSelfUpdateCommand, } from '../core/runtime/self-update.js';
+export type { SelfUpdatePlan, UpdateChannel } from '../core/runtime/self-update.js';
 export { CATENCE_PROTOCOL_VERSION, CATENCE_RUNTIME_VERSION, catenceRuntimeHealth } from '../contracts/release.js';
 export { configuredMcpRateLimit, loadCatenceConfig, resolvePaths } from '../core/runtime/configuration.js';
 export { addAthlete, athleteStorePaths, defaultAthlete, defaultCatalogHome, initializeCatalog, loadCatalog, resolveAthlete, resolveCatalogPaths, } from '../core/runtime/catalog.js';
@@ -26,8 +28,9 @@ export { WELLNESS_METRICS, WellnessService } from '../core/query/wellness.js';
 export { jsonSafe, ReadOnlyRepository } from '../core/query/repository.js';
 export { queryReadOnlyData } from '../core/query/sql-guard.js';
 export { createDemoStore, demoStoreMetadata } from '../elt/application/demo.js';
-export { connectStrava, connectStravaWithCallback, dataStatus, disconnectStravaAccount, initializeDataStore, linkActivity, rebuildRetrievalIndex, retryDataSync, syncData, unlinkActivity, } from '../elt/application/management.js';
+export { connectStrava, connectStravaWithCallback, dataStatus, disconnectStravaAccount, initializeDataStore, linkActivity, rebuildRetrievalIndex, retryDataSync, syncData, syncProgress, unlinkActivity, } from '../elt/application/management.js';
 export type { ProviderChoice } from '../elt/application/management.js';
+export type { InterruptedRuns, SyncProgressSnapshot, SyncProgressState } from '../contracts/progress.js';
 export { openReadOnlyRepository, ReadOnlyDatabaseError } from '../elt/storage/database.js';
 export { DataWriteBusyError } from '../elt/storage/write-lock.js';
 export { hydrateStravaActivity, hydrateStravaSegmentHistory, StravaEnrichmentError, StravaRateLimitError, } from '../elt/ingestion/providers/strava/service.js';

package/dist/runtime/index.js

@@ -1,3 +1,4 @@
+export { channelForVersion, compareReleaseVersions, fetchNpmDistTags, fetchPypiReleases, hasCommand, isGlobalNpmInstall, latestRelease, npmGlobalPrefix, parseReleaseVersion, planSelfUpdate, readInstalledConsoleVersion, runSelfUpdateCommand, } from '../core/runtime/self-update.js';
 export { CATENCE_PROTOCOL_VERSION, CATENCE_RUNTIME_VERSION, catenceRuntimeHealth } from '../contracts/release.js';
 export { configuredMcpRateLimit, loadCatenceConfig, resolvePaths } from '../core/runtime/configuration.js';
 export { addAthlete, athleteStorePaths, defaultAthlete, defaultCatalogHome, initializeCatalog, loadCatalog, resolveAthlete, resolveCatalogPaths, } from '../core/runtime/catalog.js';
@@ -14,7 +15,7 @@ export { WELLNESS_METRICS, WellnessService } from '../core/query/wellness.js';
 export { jsonSafe, ReadOnlyRepository } from '../core/query/repository.js';
 export { queryReadOnlyData } from '../core/query/sql-guard.js';
 export { createDemoStore, demoStoreMetadata } from '../elt/application/demo.js';
-export { connectStrava, connectStravaWithCallback, dataStatus, disconnectStravaAccount, initializeDataStore, linkActivity, rebuildRetrievalIndex, retryDataSync, syncData, unlinkActivity, } from '../elt/application/management.js';
+export { connectStrava, connectStravaWithCallback, dataStatus, disconnectStravaAccount, initializeDataStore, linkActivity, rebuildRetrievalIndex, retryDataSync, syncData, syncProgress, unlinkActivity, } from '../elt/application/management.js';
 export { openReadOnlyRepository, ReadOnlyDatabaseError } from '../elt/storage/database.js';
 export { DataWriteBusyError } from '../elt/storage/write-lock.js';
 export { hydrateStravaActivity, hydrateStravaSegmentHistory, StravaEnrichmentError, StravaRateLimitError, } from '../elt/ingestion/providers/strava/service.js';

package/docs/deployment.md

@@ -0,0 +1,338 @@
+# 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.