catence 0.2.0-beta.7 → 0.2.0-beta.9

package/README.md

@@ -213,6 +213,48 @@ docker compose -f catence-deploy/docker-compose.yml --env-file catence-deploy/.e
 
 [`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`.
 
+### Per-model reasoning effort
+
+Models that support reasoning effort can set a fixed level per model in `config.json`, or expose a per-chat **Thinking effort** dropdown with custom levels via `variants`.
+
+**Fixed level** (all requests for the model use it):
+
+```json
+{
+  "console": {
+    "profiles": {
+      "opencode-zen": {
+        "label": "OpenCode Zen",
+        "defaultModel": "deepseek-v4-flash-free",
+        "models": {
+          "deepseek-v4-flash-free": {
+            "label": "DeepSeek V4 Flash Free",
+            "model": "openai/deepseek-v4-flash-free",
+            "reasoningEffort": "high"
+          }
+        },
+        "apiKeyEnv": "OPENCODE_API_KEY",
+        "apiBaseEnv": "OPENCODE_ZEN_API_BASE"
+      }
+    }
+  }
+}
+```
+
+**Custom variants** (per-chat dropdown): `variants` maps each dropdown label to the value sent to the provider. This is how non-OpenAI models (for example DeepSeek V4 Flash, which uses its own Default/High/Max scheme rather than the OpenAI-standard list) expose their native levels:
+
+```json
+"deepseek-v4-flash-free": {
+  "label": "DeepSeek V4 Flash Free",
+  "model": "openai/deepseek-v4-flash-free",
+  "variants": { "High": "high", "Max": "max" }
+}
+```
+
+With `variants`, the chat **Thinking effort** dropdown shows `Provider default` plus each label; selecting one sends that exact value (e.g. `reasoning_effort: "high"`). Without `variants`, the dropdown falls back to the OpenAI-standard set (`minimal`, `low`, `medium`, `high`, `xhigh`).
+
+A fixed `reasoningEffort` overrides any profile-level `defaultReasoningEffort`; the per-chat dropdown selection (a variant value) overrides both. If nothing is set, the provider default is used.
+
 For source development:
 
 ```sh
@@ -238,3 +280,17 @@ data.
 Garmin is the primary source for activity and wellness data; Intervals.icu supplements training analysis; Strava is used for targeted segments, efforts, and gear. Missing fields mean a provider did not supply a value. The source credentials and source APIs determine the data available. Catence does not use the official Garmin API; Garmin sync relies on the selected athlete’s email/password credentials.
 
 See [distribution notes](docs/distribution.md) for release artifacts, including APM and MCPB demo bundles.
+
+##
+
+```bash
+cd catence-deploy
+docker compose -f docker-compose.yml --env-file .env exec console \
+  catence-data sync --athlete martina --provider all --home /data        # incremental sync, all providers
+docker compose -f docker-compose.yml --env-file .env exec console \
+  catence-data backfill --athlete martina --from 2026-01-01 --home /data # full backfill from a date
+docker compose -f docker-compose.yml --env-file .env exec console \
+  catence-data status --athlete martina --home /data                     # coverage/errors
+docker compose -f docker-compose.yml --env-file .env exec console \
+  catence-data athlete list --home /data                                 # list athlete IDs
+```

package/config.example.json

@@ -44,6 +44,31 @@
         "label": "Anthropic",
         "model": "anthropic/claude-sonnet-4-5",
         "apiKeyEnv": "ANTHROPIC_API_KEY"
+      },
+      "opencode-zen": {
+        "label": "OpenCode Zen",
+        "defaultModel": "deepseek-v4-flash-free",
+        "models": {
+          "deepseek-v4-flash-free": {
+            "label": "DeepSeek V4 Flash Free",
+            "model": "openai/deepseek-v4-flash-free",
+            "variants": { "High": "high", "Max": "max" }
+          },
+          "nemotron-3-ultra-free": { "label": "Nemotron 3 Ultra Free", "model": "openai/nemotron-3-ultra-free" },
+          "big-pickle": { "label": "Big Pickle", "model": "openai/big-pickle" }
+        },
+        "apiKeyEnv": "OPENCODE_API_KEY",
+        "apiBaseEnv": "OPENCODE_ZEN_API_BASE"
+      },
+      "opencode-zen-responses": {
+        "label": "OpenCode Zen (Responses)",
+        "defaultModel": "gpt-5.6-luna",
+        "models": {
+          "gpt-5.6-luna": { "label": "GPT 5.6 Luna", "model": "openai/responses/gpt-5.6-luna" },
+          "gpt-5.6-terra": { "label": "GPT 5.6 Terra", "model": "openai/responses/gpt-5.6-terra" }
+        },
+        "apiKeyEnv": "OPENCODE_API_KEY",
+        "apiBaseEnv": "OPENCODE_ZEN_RESPONSES_API_BASE"
       }
     }
   }

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

package/dist/core/logging.d.ts

@@ -0,0 +1,16 @@
+import type { CatencePaths } from '../contracts/runtime.js';
+export type SyncLogger = {
+    info: (message: string, context?: Record<string, unknown>) => void;
+    warn: (message: string, context?: Record<string, unknown>) => void;
+    error: (message: string, context?: Record<string, unknown>) => void;
+    debug: (message: string, context?: Record<string, unknown>) => void;
+};
+/**
+ * Resolve the sync log file path.
+ *
+ * `CATENCE_LOG` may be an absolute path or a path relative to the catalog home.
+ * When unset (the default), logs go to stderr only so the console stays clean
+ * and stdout remains machine-readable for callers like sync.sh.
+ */
+export declare function resolveLogFile(paths: CatencePaths, environment?: NodeJS.ProcessEnv): string | null;
+export declare function createSyncLogger(paths: CatencePaths, environment?: NodeJS.ProcessEnv): SyncLogger;

package/dist/core/logging.js

@@ -0,0 +1,68 @@
+import { appendFile, mkdir } from 'node:fs/promises';
+import path from 'node:path';
+const LEVEL_WEIGHT = { debug: 10, info: 20, warn: 30, error: 40 };
+function configuredLevel(environment = process.env) {
+    const raw = (environment.CATENCE_LOG_LEVEL ?? 'info').toLowerCase();
+    if (raw === 'debug')
+        return LEVEL_WEIGHT.debug;
+    if (raw === 'warn')
+        return LEVEL_WEIGHT.warn;
+    if (raw === 'error')
+        return LEVEL_WEIGHT.error;
+    return LEVEL_WEIGHT.info;
+}
+/**
+ * Resolve the sync log file path.
+ *
+ * `CATENCE_LOG` may be an absolute path or a path relative to the catalog home.
+ * When unset (the default), logs go to stderr only so the console stays clean
+ * and stdout remains machine-readable for callers like sync.sh.
+ */
+export function resolveLogFile(paths, environment = process.env) {
+    const configured = environment.CATENCE_LOG;
+    if (!configured)
+        return null;
+    return path.isAbsolute(configured) ? configured : path.join(paths.root, configured);
+}
+export function createSyncLogger(paths, environment = process.env) {
+    const threshold = configuredLevel(environment);
+    const logFile = resolveLogFile(paths, environment);
+    const write = (level, message, context) => {
+        if (LEVEL_WEIGHT[level] < threshold)
+            return;
+        const line = formatLogLine(level, message, context);
+        process.stderr.write(`${line}\n`);
+        if (logFile) {
+            // Fire-and-forget: never block a sync run on log persistence.
+            appendLogLine(logFile, `${line}\n`).catch(() => { });
+        }
+    };
+    return {
+        info: (message, context) => write('info', message, context),
+        warn: (message, context) => write('warn', message, context),
+        error: (message, context) => write('error', message, context),
+        debug: (message, context) => write('debug', message, context),
+    };
+}
+function formatLogLine(level, message, context) {
+    const timestamp = new Date().toISOString();
+    const tag = level.toUpperCase().padEnd(5);
+    let line = `[${timestamp}] [${tag}] ${message}`;
+    if (context && Object.keys(context).length > 0) {
+        line += ` ${serializeContext(context)}`;
+    }
+    return line;
+}
+function serializeContext(context) {
+    try {
+        return JSON.stringify(context);
+    }
+    catch {
+        return '';
+    }
+}
+let appendLogLine = async (file, line) => {
+    await mkdir(path.dirname(file), { recursive: true });
+    await appendFile(file, line, 'utf8');
+};
+//# sourceMappingURL=logging.js.map

package/dist/elt/application/management.js

@@ -8,6 +8,7 @@ import { promisify } from 'node:util';
 import { fileURLToPath } from 'node:url';
 import { buildRetrievalIndex } from '../../core/retrieval/index.js';
 import { defaultFromDate, ensurePaths, requireIntervalsConfig } from '../../core/runtime/configuration.js';
+import { createSyncLogger } from '../../core/logging.js';
 import { athleteProviderEnvironment } from '../../core/runtime/secrets.js';
 import { importJsonl } from '../ingestion/importer.js';
 import { IntervalsExtractor } from '../ingestion/providers/intervals.js';
@@ -19,7 +20,7 @@ const execFileAsync = promisify(execFile);
 function packageRoot() {
     return path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../../..');
 }
-async function syncProvider(database, paths, provider, options) {
+async function syncProvider(database, paths, provider, options, log) {
     const explicitWindow = options.explicitFrom ? { fromDate: options.explicitFrom, toDate: options.toDate, source: 'explicit' } : null;
     const uncoveredExplicitWindow = async (cursorName) => {
         if (!explicitWindow)
@@ -33,6 +34,7 @@ async function syncProvider(database, paths, provider, options) {
     const activityWindow = explicitWindow ? await uncoveredExplicitWindow('activities') : await database.resolveIncrementalWindow(provider, 'activities', options.toDate, defaultFromDate(), 14);
     const hasProviderWork = provider === 'intervals' ? activityWindow !== null : dailyWindow !== null || activityWindow !== null;
     if (!hasProviderWork) {
+        log.debug('No uncovered work; skipping provider', { provider, daily: dailyWindow ?? null, activities: activityWindow ?? null });
         return {
             runId: null, provider, fromDate: null,
             dailyFromDate: dailyWindow?.fromDate ?? null, dailyToDate: dailyWindow?.toDate ?? null,
@@ -43,13 +45,19 @@ async function syncProvider(database, paths, provider, options) {
     }
     const fromDate = [dailyWindow?.fromDate, activityWindow?.fromDate].filter((date) => Boolean(date)).sort()[0];
     const runId = await database.beginRun(provider, fromDate);
+    log.info('Starting sync run', {
+        runId, provider, fromDate, toDate: options.toDate,
+        dailyFrom: dailyWindow?.fromDate ?? null, dailyTo: dailyWindow?.toDate ?? null,
+        activityFrom: activityWindow?.fromDate ?? null, activityTo: activityWindow?.toDate ?? null,
+        backfill: options.backfill, refreshActivities: options.refreshActivities,
+    });
     let extractionStarted = false;
     try {
         if (provider === 'intervals') {
             const environment = await athleteProviderEnvironment(paths);
             const config = requireIntervalsConfig(environment);
             extractionStarted = true;
-            await new IntervalsExtractor(database, paths, config.apiKey, config.athleteId).sync(runId, activityWindow, !options.backfill || options.refreshActivities);
+            await new IntervalsExtractor(database, paths, config.apiKey, config.athleteId, log).sync(runId, activityWindow, !options.backfill || options.refreshActivities);
         }
         else {
             const output = path.join(paths.staging, 'garmin', `${runId}.jsonl`);
@@ -77,14 +85,18 @@ async function syncProvider(database, paths, provider, options) {
             });
             if (!existsSync(output))
                 throw new Error('Garmin staging worker completed without writing a JSONL manifest.');
-            await importJsonl(database, runId, output);
+            await importJsonl(database, runId, output, log);
         }
     }
     catch (error) {
-        await database.addError(runId, provider, 'sync', null, error instanceof Error ? error.message : String(error), true);
+        const message = error instanceof Error ? error.message : String(error);
+        log.error('Sync run failed', { runId, provider, error: message, stack: error instanceof Error ? error.stack : undefined });
+        await database.addError(runId, provider, 'sync', null, message, true);
     }
     finally {
         await database.finishRun(runId);
+        const [run] = await database.rows('SELECT status, error_count FROM sync_runs WHERE run_id = $runId', { runId });
+        log.info('Sync run finished', { runId, provider, status: run?.status ?? 'unknown', errorCount: run?.error_count ?? 0 });
     }
     if (options.advanceCursor && !options.explicitFrom && extractionStarted) {
         await database.advanceIncrementalCursor(provider, 'daily', runId, options.toDate, 3);
@@ -109,12 +121,13 @@ export async function syncData(paths, provider, explicitFrom, advanceCursor = tr
     if (provider === 'strava')
         return { provider, result: await syncStravaGear(paths) };
     const database = await CatenceDatabase.open(paths);
+    const log = createSyncLogger(paths);
     try {
         const providers = provider === 'all' ? ['intervals', 'garmin'] : [provider];
         const toDate = new Date().toISOString().slice(0, 10);
         const runs = [];
         for (const source of providers)
-            runs.push(await syncProvider(database, paths, source, { explicitFrom, toDate, advanceCursor, refreshActivities, backfill }));
+            runs.push(await syncProvider(database, paths, source, { explicitFrom, toDate, advanceCursor, refreshActivities, backfill }, log));
         return { runIds: runs.flatMap((run) => run.runId ? [run.runId] : []), runs };
     }
     finally {
@@ -130,7 +143,8 @@ export async function retryDataSync(paths, previousRunId) {
             throw new Error(`No sync run found for ${previousRunId}.`);
         if (previous.provider === 'strava')
             throw new Error('Retry Strava gear sync with `catence-data sync --provider strava`.');
-        const run = await syncProvider(database, paths, previous.provider, { explicitFrom: previous.from_date, toDate: new Date().toISOString().slice(0, 10), advanceCursor: false, refreshActivities: false, backfill: false });
+        const log = createSyncLogger(paths);
+        const run = await syncProvider(database, paths, previous.provider, { explicitFrom: previous.from_date, toDate: new Date().toISOString().slice(0, 10), advanceCursor: false, refreshActivities: false, backfill: false }, log);
         return { retriedRun: previousRunId, runId: run.runId, run };
     }
     finally {

package/dist/elt/ingestion/importer.d.ts

@@ -1,7 +1,8 @@
 import type { CatenceDatabase } from '../storage/database.js';
 import { type StagingRecord } from '../../contracts/staging.js';
-export declare function importRecord(database: CatenceDatabase, runId: string, record: StagingRecord): Promise<void>;
-export declare function importJsonl(database: CatenceDatabase, runId: string, filePath: string): Promise<number>;
+import type { SyncLogger } from '../../core/logging.js';
+export declare function importRecord(database: CatenceDatabase, runId: string, record: StagingRecord, log?: SyncLogger): Promise<void>;
+export declare function importJsonl(database: CatenceDatabase, runId: string, filePath: string, log?: SyncLogger): Promise<number>;
 export declare function importSingleStagingFile(database: CatenceDatabase, runId: string, filePath: string): Promise<number>;
 export declare function queueWorkItem(database: CatenceDatabase, runId: string, provider: 'intervals' | 'garmin' | 'strava', endpoint: string, remoteId: string | null, scope: unknown): Promise<string>;
 export declare function completeWorkItem(database: CatenceDatabase, itemId: string): Promise<void>;

package/dist/elt/ingestion/importer.js

@@ -7,7 +7,7 @@ import { importSourceEntity, refreshActivityQuality } from '../normalization/nor
 import { normalizeStravaEntity } from '../normalization/segments/strava-normalizer.js';
 import { reconcileActivityLink } from '../normalization/activities/linking.js';
 import { json } from '../storage/sql.js';
-export async function importRecord(database, runId, record) {
+export async function importRecord(database, runId, record, log) {
     if (record.kind === 'run_manifest') {
         if (record.runId !== runId)
             throw new Error(`Staging manifest run ${record.runId} does not match importer run ${runId}.`);
@@ -54,8 +54,9 @@ export async function importRecord(database, runId, record) {
         return;
     }
     await database.addError(runId, record.provider, record.endpoint, record.remoteId, record.message, record.retryable);
+    log?.warn('Staging record reported an extraction error', { runId, provider: record.provider, endpoint: record.endpoint, remoteId: record.remoteId, error: record.message });
 }
-export async function importJsonl(database, runId, filePath) {
+export async function importJsonl(database, runId, filePath, log) {
     let count = 0;
     const file = createReadStream(filePath, { encoding: 'utf8' });
     const lines = createInterface({ input: file, crlfDelay: Infinity });
@@ -63,7 +64,7 @@ export async function importJsonl(database, runId, filePath) {
         if (!line.trim())
             continue;
         const record = stagingRecordSchema.parse(JSON.parse(line));
-        await importRecord(database, runId, record);
+        await importRecord(database, runId, record, log);
         count += 1;
     }
     return count;

package/dist/elt/ingestion/providers/intervals.d.ts

@@ -1,12 +1,14 @@
 import type { CatenceDatabase } from '../../storage/database.js';
 import type { CatencePaths } from '../../../contracts/runtime.js';
+import type { SyncLogger } from '../../../core/logging.js';
 export declare class IntervalsExtractor {
     private readonly database;
     private readonly paths;
     private readonly apiKey;
     private readonly athleteId;
+    private readonly log;
     private readonly client;
-    constructor(database: CatenceDatabase, paths: CatencePaths, apiKey: string, athleteId: string);
+    constructor(database: CatenceDatabase, paths: CatencePaths, apiKey: string, athleteId: string, log: SyncLogger);
     sync(runId: string, activityWindow: {
         fromDate: string;
         toDate: string;

package/dist/elt/ingestion/providers/intervals.js

@@ -42,12 +42,14 @@ export class IntervalsExtractor {
     paths;
     apiKey;
     athleteId;
+    log;
     client;
-    constructor(database, paths, apiKey, athleteId) {
+    constructor(database, paths, apiKey, athleteId, log) {
         this.database = database;
         this.paths = paths;
         this.apiKey = apiKey;
         this.athleteId = athleteId;
+        this.log = log;
         // The typed client is used for provider-compatible authentication and the
         // primary identity request. Manifest-only calls below intentionally use
         // the same read-only credentials to cover endpoint families not wrapped by it.
@@ -189,6 +191,7 @@ export class IntervalsExtractor {
         catch (error) {
             const message = error instanceof Error ? error.message : String(error);
             await failWorkItem(this.database, workId, message);
+            this.log.warn('Endpoint capture failed', { runId, provider: 'intervals', endpoint, remoteId, error: message });
             await this.database.addError(runId, 'intervals', endpoint, remoteId, message, true);
             return undefined;
         }

package/dist/elt/ingestion/providers/strava/service.js

@@ -8,6 +8,7 @@ import { ensurePaths, loadCatenceConfig } from '../../../../core/runtime/configu
 import { athleteProviderEnvironment } from '../../../../core/runtime/secrets.js';
 import { CatenceDatabase, openReadOnlyRepository } from '../../../storage/database.js';
 import { importJsonl } from '../../importer.js';
+import { createSyncLogger } from '../../../../core/logging.js';
 import { withDataWriteLock } from '../../../storage/write-lock.js';
 const execFileAsync = promisify(execFile);
 export class StravaRateLimitError extends Error {
@@ -108,6 +109,7 @@ async function cachedState(database, resourceType, remoteId) {
 async function runReadOperation(paths, operation, extraArgs, resource, refresh = false) {
     return withDataWriteLock(paths, async () => {
         await ensurePaths(paths);
+        const log = createSyncLogger(paths);
         const database = await CatenceDatabase.open(paths);
         try {
             if (!refresh) {
@@ -117,6 +119,7 @@ async function runReadOperation(paths, operation, extraArgs, resource, refresh =
             }
             await checkBudget(database, paths);
             const runId = await database.beginRun('strava', new Date().toISOString().slice(0, 10));
+            log.info('Starting Strava read operation', { runId, operation, resource: resource.id });
             const directory = path.join(paths.staging, 'strava');
             const stagingPath = path.join(directory, `${runId}.jsonl`);
             const resultPath = path.join(directory, `${runId}.result.json`);
@@ -124,17 +127,20 @@ async function runReadOperation(paths, operation, extraArgs, resource, refresh =
             try {
                 result = await invokeWorker(paths, ['--mode', operation, '--run-id', runId, '--output', stagingPath, ...extraArgs], resultPath);
                 if (existsSync(stagingPath))
-                    await importJsonl(database, runId, stagingPath);
+                    await importJsonl(database, runId, stagingPath, log);
                 await storeRateState(database, result);
                 await writeState(database, resource.type, resource.id, result);
             }
             catch (error) {
                 const message = error instanceof Error ? error.message : String(error);
+                log.error('Strava read operation failed', { runId, operation, resource: resource.id, error: message, stack: error instanceof Error ? error.stack : undefined });
                 await database.addError(runId, 'strava', operation, resource.id, message, true);
                 throw error;
             }
             finally {
                 await database.finishRun(runId);
+                const [run] = await database.rows('SELECT status, error_count FROM sync_runs WHERE run_id = $runId', { runId });
+                log.info('Strava read operation finished', { runId, operation, status: run?.status ?? 'unknown', errorCount: run?.error_count ?? 0 });
             }
             if (result.status === 'error')
                 throw new StravaEnrichmentError(result.message ?? 'Strava did not complete the requested enrichment.');

package/dist/elt/storage/database.js

@@ -94,9 +94,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)) })),
         };
     }

package/docs/llm-providers.md

@@ -272,6 +272,83 @@ Notes:
   `OPENCODE_LLM_PROXY_TOKEN`; otherwise any non-empty value satisfies the
   profile's required-environment check.
 
+### Opencode Zen
+
+[OpenCode Zen](https://opencode.ai/zen) is a hosted model API with a curated
+selection of coding and reasoning models. It exposes an OpenAI-compatible
+endpoint at `https://opencode.ai/zen/v1` with a public `GET /v1/models`
+listing. Several models are available for free (no billing details required);
+paid models require an API key from [opencode.ai/auth](https://opencode.ai/auth).
+
+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-zen -- --write ~/.catence/config.json
+```
+
+Add `--free-only` to include only the free models.
+
+The script adds two profiles, because OpenCode Zen routes model families through
+different API shapes:
+
+- `opencode-zen` — chat/completions models (most models, including all free
+  models), base `https://opencode.ai/zen/v1` (LiteLLM `openai/<id>` names).
+- `opencode-zen-responses` — responses API models (GPT-5.x series), base
+  `https://opencode.ai/zen/v1` (LiteLLM `openai/responses/<id>` names).
+
+| Family | Profile prefix | Example |
+| --- | --- | --- |
+| Chat | `openai/<id>` | `openai/deepseek-v4-flash-free` |
+| Responses | `openai/responses/<id>` | `openai/responses/gpt-5.6-luna` |
+
+Free models carry a `-free` suffix (e.g., `deepseek-v4-flash-free`,
+`nemotron-3-ultra-free`, `big-pickle`). The discovery script recognises them
+automatically; `--free-only` filters the list to free models only.
+
+```sh
+export OPENCODE_API_KEY='…'                         # required for paid models; any non-empty value for free
+export OPENCODE_ZEN_API_BASE='https://opencode.ai/zen/v1'
+export OPENCODE_ZEN_RESPONSES_API_BASE='https://opencode.ai/zen/v1'
+```
+
+```jsonc
+{
+  "console": {
+    "defaultProfile": "opencode-zen",
+    "profiles": {
+      "opencode-zen": {
+        "label": "OpenCode Zen",
+        "defaultModel": "deepseek-v4-flash-free",
+        "models": {
+          "deepseek-v4-flash-free": { "label": "DeepSeek V4 Flash Free", "model": "openai/deepseek-v4-flash-free" },
+          "nemotron-3-ultra-free": { "label": "Nemotron 3 Ultra Free", "model": "openai/nemotron-3-ultra-free" },
+          "big-pickle": { "label": "Big Pickle", "model": "openai/big-pickle" }
+        },
+        "apiKeyEnv": "OPENCODE_API_KEY",
+        "apiBaseEnv": "OPENCODE_ZEN_API_BASE"
+      },
+      "opencode-zen-responses": {
+        "label": "OpenCode Zen (Responses)",
+        "defaultModel": "gpt-5.6-luna",
+        "models": {
+          "gpt-5.6-luna": { "label": "GPT 5.6 Luna", "model": "openai/responses/gpt-5.6-luna" },
+          "gpt-5.6-terra": { "label": "GPT 5.6 Terra", "model": "openai/responses/gpt-5.6-terra" }
+        },
+        "apiKeyEnv": "OPENCODE_API_KEY",
+        "apiBaseEnv": "OPENCODE_ZEN_RESPONSES_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.
+
+The same `OPENCODE_API_KEY` works for both Opencode Go and Opencode Zen.
+
 ## Multiple deployments per provider
 
 A profile can list several models under one set of credentials; the Console
@@ -296,6 +373,49 @@ settings then offer a per-deployment choice.
 }
 ```
 
+## Reasoning effort
+
+Models expose a per-chat **Thinking effort** dropdown in the Console settings.
+By default it offers the OpenAI-standard levels — `minimal`, `low`, `medium`,
+`high`, `xhigh` — which suit OpenAI and most OpenAI-compatible endpoints.
+
+Some models (for example DeepSeek V4 Flash) use their own reasoning-effort
+scheme rather than the OpenAI-standard list. For those, declare `variants` on
+the model: a mapping of dropdown label to the exact value sent to the provider.
+The chat dropdown then shows `Provider default` plus each label instead of the
+OpenAI-standard list.
+
+```jsonc
+{
+  "console": {
+    "profiles": {
+      "opencode-zen": {
+        "label": "OpenCode Zen",
+        "defaultModel": "deepseek-v4-flash-free",
+        "models": {
+          "deepseek-v4-flash-free": {
+            "label": "DeepSeek V4 Flash Free",
+            "model": "openai/deepseek-v4-flash-free",
+            "variants": { "High": "high", "Max": "max" }
+          }
+        },
+        "apiKeyEnv": "OPENCODE_API_KEY",
+        "apiBaseEnv": "OPENCODE_ZEN_API_BASE"
+      }
+    }
+  }
+}
+```
+
+Selecting a variant sends that value verbatim as `reasoning_effort` (with
+`allowed_openai_params` so LiteLLM forwards it for OpenAI-compatible models).
+The `Provider default` option sends no reasoning effort at all.
+
+You can also pin a fixed level with `reasoningEffort` on the model, or a
+profile-wide default with `defaultReasoningEffort` (OpenAI-standard values
+only). Precedence: per-chat dropdown selection > model `reasoningEffort` >
+profile `defaultReasoningEffort` > provider default.
+
 ## Verifying a profile
 
 `catence-console doctor` reports, for each profile, which environment variables

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "catence",
-  "version": "0.2.0-beta.7",
+  "version": "0.2.0-beta.9",
   "description": "Local MCP access to normalized Garmin, Intervals.icu, and targeted Strava fitness data.",
   "license": "AGPL-3.0-or-later",
   "repository": {
@@ -29,6 +29,7 @@
     "config.example.json",
     "docs",
     "scripts/discover-opencode-go.mjs",
+    "scripts/discover-opencode-zen.mjs",
     "pyproject.toml",
     "uv.lock",
     "python/__init__.py",
@@ -57,6 +58,7 @@
     "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",
+    "discover:opencode-zen": "node scripts/discover-opencode-zen.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-zen.mjs

@@ -0,0 +1,218 @@
+// Discover OpenCode Zen models and emit Catence Console profiles for them.
+//
+// OpenCode Zen serves its catalog through `GET /v1/models` at
+// `https://opencode.ai/zen/v1`. Models are split between the chat/completions
+// endpoint and the responses endpoint. Routing is determined by model ID prefix:
+// GPT-5.x models use the responses API; everything else uses chat/completions.
+//
+// Usage:
+//   node scripts/discover-opencode-zen.mjs [--base-url <url>] [--write <config.json>] [--set-default] [--free-only]
+//
+// Flags:
+//   --base-url <url>   Root of the OpenCode Zen API (default https://opencode.ai/zen/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-zen even when one already exists.
+//   --free-only        Only include free models (those with -free suffix or known free model IDs).
+
+import process from 'node:process';
+import { readFile, writeFile } from 'node:fs/promises';
+
+const DEFAULT_BASE_URL = 'https://opencode.ai/zen/v1';
+const API_KEY_ENV = 'OPENCODE_API_KEY';
+const API_BASE_ENV = 'OPENCODE_ZEN_API_BASE';
+const RESPONSES_BASE_ENV = 'OPENCODE_ZEN_RESPONSES_API_BASE';
+
+// Models that use the OpenAI Responses API (gpt-5.x series)
+const RESPONSES_PREFIXES = ['gpt-5', 'gpt-5.'];
+
+// Known free model IDs (in case the API doesn't mark them explicitly)
+const KNOWN_FREE_MODELS = new Set([
+  'deepseek-v4-flash-free',
+  'mimo-v2.5-free',
+  'nemotron-3-ultra-free',
+  'nemotron-3.5-lightning-free',
+  'hy3-free',
+  'laguna-s-2.1-free',
+  'big-pickle',
+  'north-mini-code-free',
+  'longcat-2.0-free',
+  'ling-3.0-flash-free',
+  'ling-3.0-tiny-free',
+]);
+
+const BRAND_NAMES = new Map([
+  ['deepseek', 'DeepSeek'],
+  ['gpt', 'GPT'],
+  ['mimo', 'MiMo'],
+  ['nemotron', 'Nemotron'],
+  ['hy3', 'Hy3'],
+  ['laguna', 'Laguna'],
+  ['big', 'Big'],
+  ['pickle', 'Pickle'],
+  ['north', 'North'],
+  ['mini', 'Mini'],
+  ['code', 'Code'],
+  ['longcat', 'LongCat'],
+  ['ling', 'Ling'],
+]);
+
+function isFreeModel(id) {
+  return id.endsWith('-free') || KNOWN_FREE_MODELS.has(id);
+}
+
+function classify(id) {
+  for (const prefix of RESPONSES_PREFIXES) {
+    if (id.startsWith(prefix)) return { route: 'responses', guessed: false };
+  }
+  return { route: 'chat', guessed: false };
+}
+
+function modelReference(id, route) {
+  if (route === 'responses') return `openai/responses/${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-zen.mjs [--base-url <url>] [--write <config.json>] [--set-default] [--free-only]\n',
+  );
+}
+
+async function main() {
+  const args = process.argv.slice(2);
+  let baseUrl = DEFAULT_BASE_URL;
+  let writePath = null;
+  let setDefault = false;
+  let freeOnly = 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 === '--free-only') {
+      freeOnly = 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`;
+
+  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 filteredIds = freeOnly ? ids.filter(isFreeModel) : ids;
+
+  const groups = { chat: [], responses: [] };
+  for (const id of filteredIds) {
+    const { route } = classify(id);
+    if (!(route in groups)) continue;
+    groups[route].push(id);
+  }
+  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') };
+  }
+  const responsesProfileModels = {};
+  for (const id of groups.responses) {
+    responsesProfileModels[id] = { label: labelFor(id), model: modelReference(id, 'responses') };
+  }
+
+  const chatDefault = groups.chat[0];
+  const responsesDefault = groups.responses[0];
+
+  const profiles = {};
+  if (groups.chat.length) {
+    profiles['opencode-zen'] = {
+      label: 'OpenCode Zen',
+      ...(chatDefault ? { defaultModel: chatDefault } : {}),
+      models: chatProfileModels,
+      apiKeyEnv: API_KEY_ENV,
+      apiBaseEnv: API_BASE_ENV,
+    };
+  }
+  if (groups.responses.length) {
+    profiles['opencode-zen-responses'] = {
+      label: 'OpenCode Zen (Responses)',
+      ...(responsesDefault ? { defaultModel: responsesDefault } : {}),
+      models: responsesProfileModels,
+      apiKeyEnv: API_KEY_ENV,
+      apiBaseEnv: RESPONSES_BASE_ENV,
+    };
+  }
+
+  const consoleSection = { defaultProfile: 'opencode-zen', profiles };
+
+  process.stderr.write(
+    `Discovered ${ids.length} models (${groups.chat.length} chat, ${groups.responses.length} responses).` +
+    (freeOnly ? ` Filtered to ${filteredIds.length} free models.` : '') + '\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-zen';
+    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 ${RESPONSES_BASE_ENV}='${baseUrl}'\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);
+});