catence 0.2.0-beta.2 → 0.2.0-beta.4

package/README.md

@@ -22,7 +22,7 @@ Catence helps explore recovery, training load, trends, activity detail, swimming
 
 ## Quick start
 
-Install Catence and create the first athlete. The default catalog home is `~/.catence`; set `CATENCE_HOME` or pass `--home` to use a different location.
+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).
 
 ```sh
 npm install --global catence@0.2.0
@@ -93,11 +93,21 @@ catence-data --athlete alex retry --run <run-id>
 catence-data --athlete alex auth strava --callback
 catence-data --athlete alex disconnect strava
 
+# Update the runtime and Console together on the tracked release channel
+catence-data update --check
+catence-data update
+
 # Choose a non-default catalog location
 catence-data --home /srv/catence setup --athlete alex --label "Alex"
 catence --home /srv/catence
 ```
 
+`catence-data update` follows the channel of the installed runtime: a beta
+install tracks the npm `beta` tag and the matching PyPI prereleases, a stable
+install tracks `latest`. Pass `--channel stable` to move off a beta. The command
+replaces the global `catence` package and installs or upgrades
+`catence-console` with `uv tool` when `uv` is available; `--check` only reports.
+
 Register `http://127.0.0.1:8765/strava/callback` with the Strava application for the callback flow. The manual `auth strava --code <authorization-code>` flow remains available for headless environments.
 
 ## Safe demo and Glama
@@ -186,6 +196,19 @@ docker run --rm -it -v catence-data:/data --entrypoint catence-data catence-cons
 
 Use the same `--entrypoint catence-data` pattern for `secret set` and `sync`. Route a Cloudflare Tunnel to `http://127.0.0.1:8000`; do not run a tunnel client in this image. Use HTTPS at the tunnel and retain the Console login—the dashboard is fetched through the authenticated Console origin rather than directly from port 8787.
 
+[`scripts/deploy-console.sh`](scripts/deploy-console.sh) deploys this stack from
+the public registries and seeds a starter `config.json` (the Console model
+profiles from [`config.example.json`](config.example.json)) into the data
+volume, so the settings panel works before the first chat. Edit
+`/data/config.json` in the volume (or the bind-mounted `--home` directory) to
+change models and defaults, or discover OpenCode Go profiles from the image:
+
+```sh
+docker compose -f catence-deploy/docker-compose.yml --env-file catence-deploy/.env run --rm \
+  --entrypoint node console \
+  /usr/local/lib/node_modules/catence/scripts/discover-opencode-go.mjs --write /data/config.json
+```
+
 ## Configuration
 
 [`config.example.json`](config.example.json) documents rate limits, Strava budgets, and Console model profiles. It intentionally contains environment-variable names rather than credential values. Keep per-athlete provider values in `catence-data secret set`, not in `.env` or `config.json`.

package/dist/contracts/release.d.ts

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

package/dist/contracts/release.js

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

package/dist/core/runtime/catalog.js

@@ -40,9 +40,8 @@ export function athleteStorePaths(catalogPaths, athleteId) {
 function legacyStoreMessage(paths) {
     return `Catence 0.2 uses a catalog at ${paths.root}. The existing directory looks like a 0.1 data store and cannot be migrated automatically. Create a fresh catalog and re-sync each athlete.`;
 }
-async function hasEntries(directory) {
-    return (await readdir(directory).catch((error) => error.code === 'ENOENT' ? [] : Promise.reject(error))).length > 0;
-}
+/** Home-directory entries the Console creates on its own and must not block catalog initialization. */
+const CONSOLE_ARTIFACTS = new Set(['config.json', 'console']);
 export async function loadCatalog(paths = resolveCatalogPaths()) {
     const contents = await readFile(paths.catalog, 'utf8').catch((error) => {
         if (error.code !== 'ENOENT')
@@ -68,9 +67,19 @@ async function writeCatalog(paths, catalog) {
 export async function initializeCatalog(paths = resolveCatalogPaths(), athlete) {
     if (existsSync(paths.catalog))
         return loadCatalog(paths);
-    if (await hasEntries(paths.root)) {
-        if (existsSync(path.join(paths.root, 'catence.duckdb')))
-            throw new Error(legacyStoreMessage(paths));
+    let entries;
+    try {
+        entries = await readdir(paths.root);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            entries = [];
+        else
+            throw error;
+    }
+    if (entries.includes('catence.duckdb'))
+        throw new Error(legacyStoreMessage(paths));
+    if (entries.some((entry) => !CONSOLE_ARTIFACTS.has(entry))) {
         throw new Error(`Refusing to initialize ${paths.root}: choose an empty --home directory or remove its unrelated contents.`);
     }
     const id = athleteIdSchema.parse(athlete.id);

package/dist/core/runtime/self-update.d.ts

@@ -0,0 +1,44 @@
+export type UpdateChannel = 'stable' | 'beta';
+export type ParsedRelease = {
+    major: number;
+    minor: number;
+    patch: number;
+    /** Present only for prerelease builds; a stable release beats every beta of the same tuple. */
+    beta?: number;
+};
+export type SelfUpdatePlan = {
+    channel: UpdateChannel;
+    runtime: {
+        current: string;
+        target?: string;
+        updateAvailable: boolean;
+    };
+    console: {
+        installed?: string;
+        target?: string;
+        updateAvailable: boolean;
+    };
+    /** True when neither component has anything to apply. */
+    ok: boolean;
+};
+export declare function parseReleaseVersion(version: string): ParsedRelease | null;
+export declare function compareReleaseVersions(left: ParsedRelease, right: ParsedRelease): -1 | 0 | 1;
+export declare function channelForVersion(version: string): UpdateChannel;
+export declare function latestRelease(versions: string[], channel: UpdateChannel): string | undefined;
+export declare function planSelfUpdate(options: {
+    runtimeVersion: string;
+    channel: UpdateChannel;
+    npmDistTags: Record<string, string>;
+    pypiReleases: string[];
+    consoleInstalled?: string;
+}): SelfUpdatePlan;
+export declare function fetchNpmDistTags(packageName: string, fetchImpl?: typeof fetch): Promise<Record<string, string>>;
+export declare function fetchPypiReleases(packageName: string, fetchImpl?: typeof fetch): Promise<string[]>;
+/** Run an update command (npm or uv) with the user's terminal attached. */
+export declare function runSelfUpdateCommand(command: string, args: string[]): Promise<number>;
+export declare function hasCommand(command: string): Promise<boolean>;
+/** Read `catence-console --version` from PATH; undefined when the Console is not installed. */
+export declare function readInstalledConsoleVersion(): Promise<string | undefined>;
+/** Global npm package root, used to decide whether `catence` can update itself in place. */
+export declare function npmGlobalPrefix(): Promise<string | undefined>;
+export declare function isGlobalNpmInstall(moduleUrl: string, npmPrefix: string | undefined): boolean;

package/dist/core/runtime/self-update.js

@@ -0,0 +1,138 @@
+/**
+ * Self-update support for the Catence runtime and its Console.
+ *
+ * The runtime tracks npm dist-tags on the `catence` package; the Console
+ * tracks PEP 440 releases on PyPI (`catence-console`). A release is "newer"
+ * only when it strictly dominates the installed version inside the tracked
+ * channel: `stable` for non-prerelease installs, or the beta prerelease
+ * channel for beta installs. Channel names match npm dist-tags, so a beta
+ * runtime consults the `beta` tag and an explicit `--channel stable` moves a
+ * beta install onto the `latest` tag.
+ */
+import { spawn } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+const NPM_VERSION = /^(\d+)\.(\d+)\.(\d+)(?:-beta\.(\d+))?$/;
+const PEP440_BETA = /^(\d+)\.(\d+)\.(\d+)b(\d+)$/;
+export function parseReleaseVersion(version) {
+    const npm = NPM_VERSION.exec(version.trim());
+    if (npm) {
+        return {
+            major: Number(npm[1]),
+            minor: Number(npm[2]),
+            patch: Number(npm[3]),
+            beta: npm[4] === undefined ? undefined : Number(npm[4]),
+        };
+    }
+    const pep440 = PEP440_BETA.exec(version.trim());
+    if (pep440) {
+        return { major: Number(pep440[1]), minor: Number(pep440[2]), patch: Number(pep440[3]), beta: Number(pep440[4]) };
+    }
+    return null;
+}
+export function compareReleaseVersions(left, right) {
+    for (const field of ['major', 'minor', 'patch']) {
+        if (left[field] !== right[field])
+            return left[field] < right[field] ? -1 : 1;
+    }
+    const leftBeta = left.beta ?? Number.POSITIVE_INFINITY;
+    const rightBeta = right.beta ?? Number.POSITIVE_INFINITY;
+    if (leftBeta === rightBeta)
+        return 0;
+    return leftBeta < rightBeta ? -1 : 1;
+}
+export function channelForVersion(version) {
+    return parseReleaseVersion(version)?.beta !== undefined ? 'beta' : 'stable';
+}
+export function latestRelease(versions, channel) {
+    let best;
+    for (const version of versions) {
+        const parsed = parseReleaseVersion(version);
+        if (!parsed)
+            continue;
+        const isBeta = parsed.beta !== undefined;
+        if (channel === 'beta' ? !isBeta : isBeta)
+            continue;
+        if (!best || compareReleaseVersions(parsed, best.parsed) > 0)
+            best = { version, parsed };
+    }
+    return best?.version;
+}
+export function planSelfUpdate(options) {
+    const distTag = options.channel === 'beta' ? 'beta' : 'latest';
+    const runtimeTarget = options.npmDistTags[distTag];
+    const consoleTarget = latestRelease(options.pypiReleases, options.channel);
+    const runtimeUpdateAvailable = isNewer(runtimeTarget, parseReleaseVersion(options.runtimeVersion));
+    const consoleUpdateAvailable = options.consoleInstalled
+        ? isNewer(consoleTarget, parseReleaseVersion(options.consoleInstalled))
+        : consoleTarget !== undefined;
+    return {
+        channel: options.channel,
+        runtime: { current: options.runtimeVersion, target: runtimeTarget, updateAvailable: runtimeUpdateAvailable },
+        console: { installed: options.consoleInstalled, target: consoleTarget, updateAvailable: consoleUpdateAvailable },
+        ok: !runtimeUpdateAvailable && !consoleUpdateAvailable,
+    };
+}
+function isNewer(target, current) {
+    if (!target || !current)
+        return false;
+    const parsed = parseReleaseVersion(target);
+    return parsed !== null && compareReleaseVersions(parsed, current) > 0;
+}
+export async function fetchNpmDistTags(packageName, fetchImpl = fetch) {
+    const response = await fetchImpl(`https://registry.npmjs.org/${packageName}`);
+    if (!response.ok)
+        throw new Error(`npm registry returned HTTP ${response.status} for ${packageName}.`);
+    const payload = (await response.json());
+    return payload['dist-tags'] ?? {};
+}
+export async function fetchPypiReleases(packageName, fetchImpl = fetch) {
+    const response = await fetchImpl(`https://pypi.org/pypi/${packageName}/json`);
+    if (!response.ok)
+        throw new Error(`PyPI returned HTTP ${response.status} for ${packageName}.`);
+    const payload = (await response.json());
+    return Object.keys(payload.releases ?? {});
+}
+/** Run an update command (npm or uv) with the user's terminal attached. */
+export function runSelfUpdateCommand(command, args) {
+    return new Promise((resolve, reject) => {
+        const child = spawn(command, args, { stdio: 'inherit' });
+        child.once('error', reject);
+        child.once('close', (code) => resolve(code ?? 1));
+    });
+}
+export function hasCommand(command) {
+    return new Promise((resolve) => {
+        const child = spawn(command, ['--version'], { stdio: 'ignore' });
+        child.once('error', () => resolve(false));
+        child.once('close', (code) => resolve(code === 0));
+    });
+}
+/** Read `catence-console --version` from PATH; undefined when the Console is not installed. */
+export function readInstalledConsoleVersion() {
+    return new Promise((resolve) => {
+        const child = spawn('catence-console', ['--version'], { stdio: ['ignore', 'pipe', 'inherit'] });
+        let stdout = '';
+        child.stdout?.on('data', (chunk) => (stdout += chunk.toString('utf8')));
+        child.once('error', () => resolve(undefined));
+        child.once('close', (code) => {
+            const match = /^catence-console (\S+)/.exec(stdout.trim());
+            resolve(code === 0 && match ? match[1] : undefined);
+        });
+    });
+}
+/** Global npm package root, used to decide whether `catence` can update itself in place. */
+export function npmGlobalPrefix() {
+    return new Promise((resolve) => {
+        const child = spawn('npm', ['prefix', '-g'], { stdio: ['ignore', 'pipe', 'inherit'] });
+        let stdout = '';
+        child.stdout?.on('data', (chunk) => (stdout += chunk.toString('utf8')));
+        child.once('error', () => resolve(undefined));
+        child.once('close', (code) => resolve(code === 0 ? stdout.trim() : undefined));
+    });
+}
+export function isGlobalNpmInstall(moduleUrl, npmPrefix) {
+    if (!npmPrefix)
+        return false;
+    return fileURLToPath(moduleUrl).startsWith(`${npmPrefix}/lib/node_modules/`);
+}
+//# sourceMappingURL=self-update.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, 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,64 @@ program.command('status').action(async () => {
     const { paths } = await currentAthlete();
     process.stdout.write(`${JSON.stringify(await dataStatus(paths), null, 2)}\n`);
 });
+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/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';

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';

package/docs/deployment.md

@@ -0,0 +1,258 @@
+# 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)
+
+```sh
+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
+```
+
+### 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: docker compose ... run --rm --entrypoint /opt/catence-console/bin/catence-console console auth hash-password
+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
+
+```sh
+printf %s 'value' | 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
+```
+
+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. 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;
+  `config.json` and `console/` 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/llm-providers.md

@@ -2,9 +2,11 @@
 
 Catence Console talks to a model through [LiteLLM](https://docs.litellm.ai/).
 There are exactly three provider shapes: **OpenAI**, **Anthropic**, and a
-generic **OpenAI-compatible** profile. Azure and Opencode are not special cases
-in the code: both are reached through the OpenAI-compatible profile, and the
-steps for each are documented below.
+generic **OpenAI-compatible** profile. Azure is not a special case in the code:
+it is reached through the OpenAI-compatible profile. OpenCode Go can be reached
+the same way through a local gateway, or directly at its own OpenAI-compatible
+endpoint with native `openai/…` and `anthropic/…` model names; the steps for
+each are documented below.
 
 ## How configuration is split
 
@@ -166,9 +168,77 @@ Notes:
 
 ### Opencode
 
-Opencode itself does not expose an OpenAI-compatible server; its `serve` command
-publishes Opencode's own API. To reuse the providers you already configured in
-Opencode, run an OpenAI-compatible gateway such as the
+[OpenCode Go](https://opencode.ai) publishes an OpenAI-compatible API at
+`https://opencode.ai/zen/go/v1`; its `GET /v1/models` listing is public and does
+not require a key. The Console can use it directly, so most setups do not need a
+local gateway.
+
+The repository includes a discovery script that fetches the live model list and
+merges ready-made Console profiles into `config.json`. From a Catence checkout:
+
+```sh
+npm run discover:opencode-go -- --write ~/.catence/config.json
+```
+
+The script adds two profiles, because OpenCode Go routes model families through
+different API shapes:
+
+- `opencode-go` — chat and responses models, base
+  `https://opencode.ai/zen/go/v1` (LiteLLM `openai/…` names).
+- `opencode-go-messages` — messages models, base `https://opencode.ai/zen/go`
+  (LiteLLM `anthropic/…` names).
+
+| Family | Profile prefix | Example |
+| --- | --- | --- |
+| Chat | `openai/<id>` | `openai/deepseek-v4-flash` |
+| Responses | `openai/responses/<id>` | `openai/responses/grok-4.5` |
+| Messages | `anthropic/<id>` | `anthropic/minimax-m2.5` |
+
+The script warns on stderr and skips any model that does not fit one of these
+families. Rerun it to refresh the model lists; existing profiles, limits, and
+`defaultProfile` are preserved unless `--set-default` is passed.
+
+```sh
+export OPENCODE_GO_API_KEY='…'                      # any non-empty value satisfies the key check
+export OPENCODE_GO_API_BASE='https://opencode.ai/zen/go/v1'
+export OPENCODE_GO_MESSAGES_API_BASE='https://opencode.ai/zen/go'
+```
+
+```jsonc
+{
+  "console": {
+    "defaultProfile": "opencode-go",
+    "profiles": {
+      "opencode-go": {
+        "label": "OpenCode Go",
+        "defaultModel": "flash",
+        "models": {
+          "flash": { "label": "DeepSeek V4 flash", "model": "openai/deepseek-v4-flash" },
+          "grok": { "label": "Grok 4.5", "model": "openai/responses/grok-4.5" }
+        },
+        "apiKeyEnv": "OPENCODE_GO_API_KEY",
+        "apiBaseEnv": "OPENCODE_GO_API_BASE"
+      },
+      "opencode-go-messages": {
+        "label": "OpenCode Go messages",
+        "defaultModel": "minimax",
+        "models": {
+          "minimax": { "label": "MiniMax M2.5", "model": "anthropic/minimax-m2.5" }
+        },
+        "apiKeyEnv": "OPENCODE_GO_API_KEY",
+        "apiBaseEnv": "OPENCODE_GO_MESSAGES_API_BASE"
+      }
+    }
+  }
+}
+```
+
+Verify with `catence-console doctor`. The `responses` models
+(`openai/responses/…`) go through LiteLLM's responses bridge and are the least
+battle-tested path; smoke-test one chat turn before relying on them.
+
+If you instead want to reuse the providers already configured in your local
+Opencode CLI, run an OpenAI-compatible gateway such as the
 [`opencode-llm-proxy`](https://github.com/KochC/opencode-llm-proxy) plugin, which
 serves Chat Completions at `http://127.0.0.1:4010/v1` and lists every configured
 model as `provider/model`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "catence",
-  "version": "0.2.0-beta.2",
+  "version": "0.2.0-beta.4",
   "description": "Local MCP access to normalized Garmin, Intervals.icu, and targeted Strava fitness data.",
   "license": "AGPL-3.0-or-later",
   "repository": {
@@ -28,6 +28,7 @@
     "README.md",
     "config.example.json",
     "docs",
+    "scripts/discover-opencode-go.mjs",
     "pyproject.toml",
     "uv.lock",
     "python/__init__.py",
@@ -55,6 +56,7 @@
     "mcp": "tsx src/interfaces/mcp/main.ts",
     "console": "uv run --project console catence-console serve",
     "console:doctor": "uv run --project console catence-console doctor",
+    "discover:opencode-go": "node scripts/discover-opencode-go.mjs",
     "package:check": "npm pack --dry-run",
     "release:check": "node scripts/release-artifacts.mjs check",
     "mcpb:validate": "npm exec --yes --package @anthropic-ai/mcpb -- mcpb validate mcpb/manifest.json",

package/scripts/discover-opencode-go.mjs

@@ -0,0 +1,210 @@
+// Discover OpenCode Go models and emit Catence Console profiles for them.
+//
+// OpenCode Go serves its catalog through three APIs: most models speak the
+// OpenAI Chat Completions API, Grok and GPT-5.6 Luna speak the OpenAI
+// Responses API, and MiniMax and Qwen speak the Anthropic Messages API. The
+// public `GET /models` endpoint returns only model ids, not which API each
+// model needs, so routing comes from the trusted table below and is intersected
+// with the live list (the same "live discovery + trusted metadata" approach
+// OpenClaw uses).
+//
+// Usage:
+//   node scripts/discover-opencode-go.mjs [--base-url <url>] [--write <config.json>] [--set-default]
+//
+// Flags:
+//   --base-url <url>   Root of the OpenCode Go API (default https://opencode.ai/zen/go/v1).
+//   --write <path>     Merge the two profiles into an existing config.json instead of printing to stdout.
+//   --set-default      With --write, set console.defaultProfile to opencode-go even when one already exists.
+
+import process from 'node:process';
+import { readFile, writeFile } from 'node:fs/promises';
+
+const DEFAULT_BASE_URL = 'https://opencode.ai/zen/go/v1';
+const API_KEY_ENV = 'OPENCODE_GO_API_KEY';
+const API_BASE_ENV = 'OPENCODE_GO_API_BASE';
+const MESSAGES_BASE_ENV = 'OPENCODE_GO_MESSAGES_API_BASE';
+
+// LiteLLM appends a fixed suffix to the profile base URL per provider, so the
+// three APIs need different prefixes and two base URLs:
+//   openai/<id>             -> {base}/chat/completions
+//   openai/responses/<id>   -> {base}/responses
+//   anthropic/<id>          -> {base minus /v1}/v1/messages
+const RESPONSES_MODELS = new Set(['grok-4.5', 'gpt-5.6-luna']);
+const MESSAGES_MODELS = new Set([
+  'minimax-m2.5',
+  'minimax-m2.7',
+  'minimax-m3',
+  'qwen3.5-plus',
+  'qwen3.6-plus',
+  'qwen3.7-plus',
+  'qwen3.7-max',
+  'qwen3.8-max',
+]);
+
+const BRAND_NAMES = new Map([
+  ['deepseek', 'DeepSeek'],
+  ['glm', 'GLM'],
+  ['gpt', 'GPT'],
+  ['grok', 'Grok'],
+  ['hy3', 'Hy3'],
+  ['kimi', 'Kimi'],
+  ['mimo', 'MiMo'],
+  ['minimax', 'MiniMax'],
+  ['qwen', 'Qwen'],
+]);
+
+function classify(id) {
+  if (RESPONSES_MODELS.has(id)) return { route: 'responses', guessed: false };
+  if (MESSAGES_MODELS.has(id)) return { route: 'messages', guessed: false };
+  if (/^(grok-|gpt-)/.test(id)) return { route: 'responses', guessed: true };
+  if (/^(minimax-|qwen)/.test(id)) return { route: 'messages', guessed: true };
+  return { route: 'chat', guessed: false };
+}
+
+function modelReference(id, route) {
+  if (route === 'responses') return `openai/responses/${id}`;
+  if (route === 'messages') return `anthropic/${id}`;
+  return `openai/${id}`;
+}
+
+function labelFor(id) {
+  return id
+    .split('-')
+    .map((segment) => BRAND_NAMES.get(segment) ?? segment.charAt(0).toUpperCase() + segment.slice(1))
+    .join(' ');
+}
+
+function usage() {
+  process.stderr.write(
+    'Usage: node scripts/discover-opencode-go.mjs [--base-url <url>] [--write <config.json>] [--set-default]\n',
+  );
+}
+
+async function main() {
+  const args = process.argv.slice(2);
+  let baseUrl = DEFAULT_BASE_URL;
+  let writePath = null;
+  let setDefault = false;
+  for (let i = 0; i < args.length; i += 1) {
+    const arg = args[i];
+    if (arg === '--base-url') {
+      baseUrl = args[i + 1];
+      if (!baseUrl) throw new Error('--base-url requires a URL.');
+      i += 1;
+    } else if (arg === '--write') {
+      writePath = args[i + 1];
+      if (!writePath) throw new Error('--write requires a config.json path.');
+      i += 1;
+    } else if (arg === '--set-default') {
+      setDefault = true;
+    } else if (arg === '--help' || arg === '-h') {
+      usage();
+      return;
+    } else {
+      throw new Error(`Unknown argument: ${arg}`);
+    }
+  }
+
+  if (!baseUrl.endsWith('/v1')) {
+    process.stderr.write(`Warning: --base-url ${baseUrl} does not end in /v1; chat and responses URLs may be wrong.\n`);
+  }
+  const modelsUrl = `${baseUrl.replace(/\/$/, '')}/models`;
+  const messagesBase = baseUrl.replace(/\/v1\/?$/, '');
+
+  let response;
+  try {
+    response = await fetch(modelsUrl, { headers: { accept: 'application/json' } });
+  } catch (error) {
+    throw new Error(`Could not reach ${modelsUrl}: ${error.message}`);
+  }
+  if (!response.ok) {
+    throw new Error(`GET ${modelsUrl} returned HTTP ${response.status}.`);
+  }
+  const payload = await response.json();
+  const ids = (payload.data ?? []).map((entry) => entry.id).filter((id) => typeof id === 'string' && id);
+
+  const groups = { chat: [], responses: [], messages: [] };
+  const guessed = [];
+  for (const id of ids) {
+    const { route, guessed: wasGuessed } = classify(id);
+    if (!(route in groups)) continue;
+    groups[route].push(id);
+    if (wasGuessed) guessed.push(`${id} -> ${route}`);
+  }
+  for (const route of Object.keys(groups)) groups[route].sort();
+
+  const chatProfileModels = {};
+  for (const id of groups.chat) {
+    chatProfileModels[id] = { label: labelFor(id), model: modelReference(id, 'chat') };
+  }
+  for (const id of groups.responses) {
+    chatProfileModels[id] = { label: labelFor(id), model: modelReference(id, 'responses') };
+  }
+  const messagesProfileModels = {};
+  for (const id of groups.messages) {
+    messagesProfileModels[id] = { label: labelFor(id), model: modelReference(id, 'messages') };
+  }
+
+  const chatDefault = groups.chat[0] ?? groups.responses[0];
+  const profiles = {};
+  profiles['opencode-go'] = {
+    label: 'OpenCode Go',
+    ...(chatDefault ? { defaultModel: chatDefault } : {}),
+    models: chatProfileModels,
+    apiKeyEnv: API_KEY_ENV,
+    apiBaseEnv: API_BASE_ENV,
+  };
+  if (messagesProfileModels && groups.messages.length) {
+    profiles['opencode-go-messages'] = {
+      label: 'OpenCode Go (Anthropic)',
+      defaultModel: groups.messages[0],
+      models: messagesProfileModels,
+      apiKeyEnv: API_KEY_ENV,
+      apiBaseEnv: MESSAGES_BASE_ENV,
+    };
+  }
+
+  const consoleSection = { defaultProfile: 'opencode-go', profiles };
+
+  if (guessed.length) {
+    process.stderr.write('Routed by prefix heuristic (verify before use):\n');
+    for (const line of guessed) process.stderr.write(`  ${line}\n`);
+  }
+  process.stderr.write(
+    `Discovered ${ids.length} models (${groups.chat.length} chat, ${groups.responses.length} responses, ${groups.messages.length} messages).\n`,
+  );
+
+  if (writePath) {
+    let root = {};
+    try {
+      root = JSON.parse(await readFile(writePath, 'utf8'));
+    } catch (error) {
+      if (error.code !== 'ENOENT') throw new Error(`Could not read ${writePath}: ${error.message}`);
+    }
+    if (typeof root !== 'object' || root === null || Array.isArray(root)) {
+      throw new Error(`${writePath} must contain a JSON object.`);
+    }
+    const existingConsole = typeof root.console === 'object' && root.console !== null ? root.console : {};
+    const mergedProfiles = { ...(existingConsole.profiles ?? {}), ...profiles };
+    const defaultProfile =
+      existingConsole.defaultProfile && !setDefault ? existingConsole.defaultProfile : 'opencode-go';
+    root.console = { ...existingConsole, defaultProfile, profiles: mergedProfiles };
+    await writeFile(writePath, `${JSON.stringify(root, null, 2)}\n`);
+    process.stderr.write(`Merged profiles into ${writePath} (defaultProfile: ${defaultProfile}).\n`);
+    return;
+  }
+
+  process.stderr.write(
+    `Export the key and base URLs, then add the JSON below under "console" in config.json:\n` +
+      `  export ${API_KEY_ENV}='sk-…'\n` +
+      `  export ${API_BASE_ENV}='${baseUrl}'\n` +
+      `  export ${MESSAGES_BASE_ENV}='${messagesBase}'\n` +
+      `(or rerun with --write ~/.catence/config.json to merge into an existing config.)\n`,
+  );
+  process.stdout.write(`${JSON.stringify(consoleSection, null, 2)}\n`);
+}
+
+await main().catch((error) => {
+  process.stderr.write(`Error: ${error.message}\n`);
+  process.exit(1);
+});