catence 0.2.0-beta.1 → 0.2.0-beta.11

package/docs/deployment/local-console.md

@@ -0,0 +1,230 @@
+# Local Console deployment
+
+Catence Console is a password-protected local web chat that starts a matching
+Catence runtime on loopback. It uses Chainlit password login and fails closed
+unless all three authentication variables are supplied.
+
+This guide covers the **local** path: the npm package plus the Python Console
+on your machine. The Docker path (one container built from the public
+registries) is covered in [`docker.md`](docker.md). Both paths end with the
+same Console, data directory layout, model configuration, and credentials
+model.
+
+## Prerequisites
+
+- Node.js 22+ and Python 3.12+ with [uv](https://docs.astral.sh/uv/).
+- 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/` |
+| 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 | shell exports |
+| 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
+[`configuration.md`](../configuration.md) for the complete `config.json`
+schema.
+
+## 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 `~/.catence/config.json`. 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](../llm-providers.md#opencode).
+
+## 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)"
+```
+
+The Console fails closed unless `CATENCE_CONSOLE_USERNAME`,
+`CATENCE_CONSOLE_PASSWORD_HASH` (a bcrypt hash), and `CHAINLIT_AUTH_SECRET`
+are all set. There is one shared account; the username/password pair grants a
+single `console-owner` role.
+
+## 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
+```
+
+## Console serve options
+
+`catence-console serve` accepts:
+
+| Option | Default | Meaning |
+| --- | --- | --- |
+| `--home <dir>` | `$CATENCE_HOME` or `~/.catence` | Catalog home the runtime serves |
+| `--mcp-url <url>` | `$CATENCE_MCP_URL` or auto-start | If given, waits for an existing runtime instead of starting one |
+| `--ui-host <host>` | `$CATENCE_CONSOLE_HOST` or `127.0.0.1` | Web UI bind address |
+| `--mcp-host <host>` | `127.0.0.1` | Loopback host for the auto-started runtime |
+| `--mcp-port <port>` | `8787` | Loopback port for the auto-started runtime |
+| `--ui-port <port>` | `8000` | Web UI port |
+| `--no-build-ui` | — | Deprecated no-op |
+| `--external-mcp` | — | Deprecated alias for `--mcp-url` |
+
+When no `--mcp-url` is given, the Console spawns a matching runtime
+(`catence serve --home <home> --host <mcp-host> --port <mcp-port>
+--allow-origin http://127.0.0.1:<ui-port> --allow-origin http://localhost:<ui-port>`)
+and waits for `GET /health` to succeed within 20 seconds. The runtime and
+Console must agree on the protocol version; a mismatch is rejected before a
+chat starts.
+
+## How multi-athlete works in the Console
+
+The Console shares the same per-athlete stores as MCP, but scoping is
+**server-owned, not model-owned**:
+
+- The settings panel has an **Athlete** selector built from
+  `GET /api/v1/athletes` on the runtime. The default is the catalog's
+  `defaultAthleteId`.
+- On every personal-data tool call, the Console **forces** the selected
+  athleteId onto the arguments — the model cannot name or switch athletes, and
+  a chat's system message states: *"This Console chat is scoped to athleteId X.
+  Every Catence data tool call is forced to that athlete; do not try to select
+  or compare another athlete."*
+- The athlete choice is persisted per chat thread in the Console's
+  `console_preferences` table (`chat-history.sqlite3`), and the chat header
+  announces *"This chat is scoped to athlete **<id>**."*
+- `list_athletes` is exempt from forcing so the roster can be rendered.
+
+The dashboard is fetched through the authenticated Console origin: Chainlit
+middleware proxies `GET /api/v1/dashboard` and `GET /api/v1/athletes` to the
+runtime only when the Console's JWT cookie is valid (otherwise 401), so raw
+port 8787 does not need to be exposed.
+
+## 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
+```
+
+Then set the credentials and verify:
+
+```sh
+export OPENCODE_GO_API_KEY='…'                      # any non-empty value passes 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'
+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
+```
+
+## Troubleshooting
+
+- **"No Catence config exists"** — should not happen after a wizard run; ensure
+  `~/.catence/config.json` exists and contains a `console` section (copy it
+  from [`config.example.json`](../../config.example.json)).
+- **"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 the shell and restart the Console.
+- **Runtime not reachable** — `catence-console doctor --home "$HOME/.catence"
+  --mcp-url http://127.0.0.1:8787/mcp` checks the handshake; confirm the
+  runtime is running on that port and the protocol versions agree.

package/docs/deployment/local-mcp.md

@@ -0,0 +1,304 @@
+# Local MCP deployment
+
+This guide runs the Catence MCP server on your machine: install the runtime,
+create a catalog of athlete stores, sync provider data, and connect MCP clients
+over stdio or Streamable HTTP. It does **not** set up the web Console — see
+[`local-console.md`](local-console.md) for that.
+
+## Prerequisites
+
+- Node.js 22+
+- Python 3.12+ and [uv](https://docs.astral.sh/uv/) for the Garmin and Strava
+  provider workers
+- Provider credentials for the athletes you choose to sync
+
+The default catalog home is `~/.catence`. Set `CATENCE_HOME` or pass `--home`
+to use a different location.
+
+## 1. Install
+
+```sh
+npm install --global catence@beta      # or catence@latest for stable
+```
+
+This installs two binaries:
+
+- `catence` — the MCP server (`catence` starts stdio, `catence serve` starts
+  Streamable HTTP, `catence demo` creates a generated store before starting
+  stdio).
+- `catence-data` — catalog setup, athlete selection, per-athlete secrets,
+  `sync`, `backfill`, provider authentication, retrieval-index rebuilding, and
+  `demo` generation.
+
+## 2. Create the catalog and first athlete
+
+```sh
+catence-data setup --athlete alex --label "Alex"
+```
+
+This creates `~/.catence/` (or `$CATENCE_HOME`) with a catalog and the first
+athlete store. It also tolerates a directory that already holds only Console
+artifacts (`config.json`, `console/`).
+
+## 3. Store provider credentials (stdin only, never shell history)
+
+Provider values are written to the selected athlete's owner-only local secret
+file (`secrets/providers.json`, mode 0600). Read them through stdin so they do
+not enter shell history:
+
+```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
+```
+
+Supported fields per provider: Garmin `email` and `password`; Intervals.icu
+`apiKey` and `athleteId`; Strava `clientId` and `clientSecret`. Set only the
+providers you actually sync; `secret set` accepts each field independently.
+
+Secrets are injected into provider workers **only** from this per-athlete file;
+any `GARMIN_*`/`INTERVALS_*`/`STRAVA_*` values inherited by the shared process
+are deliberately stripped. An athlete that has not configured a provider
+cannot silently inherit its credentials.
+
+## 4. Sync data and build retrieval context
+
+```sh
+catence-data --athlete alex sync --provider all
+catence-data --athlete alex build-retrieval-index
+```
+
+## 5. Start the stdio MCP server
+
+```sh
+catence
+```
+
+An agent first calls `list_athletes`, then includes `athleteId` with every
+data tool. This is intentional: a shared agent may access the stores you
+configured, but no tool implicitly aggregates or crosses between athletes.
+
+## Multi-athlete catalog
+
+Catence is designed to serve **several isolated athlete stores** from one
+shared server. Each store has its own DuckDB, raw data, and tokens, so
+athletes never leak into each other.
+
+### MCP behavior
+
+- `list_athletes` returns `{ defaultAthleteId, athletes: [{ id, label }] }`.
+- Every personal-data tool in catalog mode requires an `athleteId` input (the
+  server auto-prepends it to every tool schema). Calls without it fail with
+  `athleteId is required. Call list_athletes to inspect the configured catalog.`
+- The `catence://athletes` resource returns the same catalog.
+- Rate limits are tracked **per athlete**: each athlete has its own sliding
+  window for server, tool, and resource limits.
+- MCP responses carry an `athlete` field identifying which store served them.
+
+### Adding another athlete
+
+```sh
+catence-data athlete add --id sam --label "Sam"
+printf %s 'sam@example.com' | catence-data --athlete sam secret set --provider garmin --field email --value-stdin
+printf %s 'sam-password' | catence-data --athlete sam secret set --provider garmin --field password --value-stdin
+catence-data --athlete sam sync --provider garmin
+catence-data athlete list
+```
+
+The catalog layout is deliberately simple:
+
+```text
+~/.catence/
+  catalog.json
+  config.json                     # shared Console configuration; no secrets
+  console/chat-history.sqlite3
+  athletes/
+    alex/                         # isolated DuckDB, raw data, and tokens
+      secrets/providers.json      # mode 0600
+    sam/
+      ...
+```
+
+Garmin, Intervals, and Strava client credentials are isolated per athlete.
+Strava OAuth tokens remain in that athlete's own store. The old 0.1
+single-store directory cannot be migrated safely: create a fresh home and
+re-sync each athlete.
+
+## Common operations
+
+```sh
+# Incremental or explicit data work for one athlete
+catence-data --athlete alex status
+catence-data --athlete alex sync --provider intervals
+catence-data --athlete alex sync --provider garmin --from 2025-07-29
+catence-data --athlete alex backfill --provider garmin --from 2020-01-01 --refresh
+catence-data --athlete alex retry --run <run-id>
+catence-data --athlete alex progress --watch    # follow an active sync run live
+
+# Strava OAuth uses clientId and clientSecret previously stored for this athlete
+catence-data --athlete alex auth strava --callback
+catence-data --athlete alex disconnect strava
+
+# Update the runtime and Console together on the tracked release channel
+catence-data update --check
+catence-data update
+
+# Choose a non-default catalog location
+catence-data --home /srv/catence setup --athlete alex --label "Alex"
+catence --home /srv/catence
+```
+
+`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.
+
+## Background sync and live progress
+
+Long Garmin backfills fetch hundreds of days of data and can take 20-30+
+minutes. Sync runs stream worker output to the console in real time, tolerate
+Ctrl+C and SSH/terminal deaths cleanly, and expose a live progress heartbeat
+you can follow from the CLI, the MCP server, or a Docker helper.
+
+### What happens during a run
+
+When a sync starts, Catence creates a row in `sync_runs` with status `running`
+and begins persisting heartbeats to the `sync_run_progress` table (schema
+migration 14). The Garmin staging worker emits one compact JSON progress record
+every few seconds on stdout; the runtime parses it, normalizes it, and upserts
+it. Even if the worker cannot emit — for example while stuck in login — the
+runtime persists a 30-second fallback heartbeat so a run is always observable
+and never falsely looks stale.
+
+Each progress record follows the same contract:
+
+- `runId`, `provider` — which run the record belongs to
+- `stage` — `starting`, `login`, `singletons`, `daily`, `range`,
+  `ftp_history`, `max_metrics`, `hrv_history`, `scores`, `activities`,
+  `collections` while extracting; `completed` on success; `failed`,
+  `interrupted`, or `timed_out` as terminal states written by the runtime
+- `currentStep` — the endpoint, date, or activity being fetched right now
+- `completedUnits` / `totalUnits` — for example days fetched out of the total
+  days in the window
+- `percentComplete` — 0 to 100
+- `elapsedSeconds` / `estimatedRemainingSeconds` — the ETA is computed once the
+  run has a known total and has completed at least one unit
+- `heartbeatAt` — UTC ISO timestamp of the record
+
+#### Live progress never needs the database lock
+
+DuckDB is a single-writer database: a running sync holds an exclusive lock on
+the store file, so no other process — not even a read-only one — can open it
+until the run finishes. To keep progress observable during a run, every
+heartbeat is also written to a sidecar file at
+`staging/garmin/<run-id>.progress.json` (atomic write, no database access).
+`progress`, `catence_sync_progress`, and the MCP server read the sidecar files
+for live runs and only touch the `sync_run_progress` table for recent-run
+history once the lock is free — so they keep working while a backfill holds the
+lock, and never crash with a lock error.
+
+Other read-only tools (`status`, `query_read_only_data`, and friends) still
+need the database and therefore return a clean `data_sync_in_progress` error
+while a sync run is active. That is expected behavior: the store is locked
+until the run completes, then they are served from the same snapshot.
+
+### Interruption and stale-run recovery
+
+- SIGINT, SIGTERM, and SIGHUP (Ctrl+C, terminal close, `kill`) are trapped on
+  both the Node runtime and the Python worker. The child stops between days and
+  the run is marked `interrupted` in `sync_runs` — never a zombie `running`
+  row — and the process exits with 130/143/129.
+- Before every sync or retry, runs still stuck in `running` for more than 15
+  minutes are marked `timed_out` (with `completed_at` set), so a dead SSH
+  session cannot block later syncs.
+- Resume a failed or interrupted run without re-reading history with
+  `retry --run <run-id>`.
+
+### Watching progress
+
+```sh
+catence-data --athlete alex progress          # one-shot JSON snapshot
+catence-data --athlete alex progress --watch  # live view; exits when no run is active
+```
+
+`--watch` renders a compact progress table on a TTY and exits when the last
+active run finishes; piped output stays JSON.
+
+The read-only MCP tool `catence_sync_progress` returns the same snapshot —
+active runs with their latest heartbeat plus the most recent runs — and takes
+`athleteId` like every other personal-data tool.
+
+## Safe demo and Glama
+
+Run a clearly marked generated dataset without provider accounts:
+
+```sh
+npx --yes catence@beta demo
+```
+
+It creates or reuses `~/.catence-demo` with one `demo` athlete. The generated
+data has explicit caveats in every tool response and never contains personal
+measurements. The Glama registry entry uses this command for **Try in
+Browser**, so the hosted sandbox has no access to local credentials or
+personal data.
+
+From a checkout:
+
+```sh
+npm run mcp -- demo
+```
+
+`catence-data demo` and `catence demo` both use `~/.catence-demo` by default
+and refuse to modify an existing directory unless it contains the Catence demo
+marker.
+
+## MCP clients and HTTP
+
+For a packaged installation, point a client at `catence`:
+
+```sh
+codex mcp add catence -- catence
+claude mcp add --transport stdio catence -- catence
+```
+
+For a source checkout:
+
+```sh
+codex mcp add catence -- npm --prefix /absolute/path/to/catence run mcp
+```
+
+### Streamable HTTP server
+
+Optional local Streamable HTTP MCP and dashboard APIs:
+
+```sh
+catence serve --host 127.0.0.1 --port 8787
+```
+
+By default it is loopback-only. `CATENCE_HTTP_HOST` and `CATENCE_HTTP_PORT`
+override the host and port when the flags are omitted.
+
+- `GET /api/v1/athletes` returns IDs and labels only.
+- `GET /api/v1/dashboard` requires `athleteId`, for example
+  `http://127.0.0.1:8787/api/v1/dashboard?athleteId=alex&days=28` (`endDate`
+  is an optional `YYYY-MM-DD`; `days` ranges 1-90 and defaults to 28).
+- Browser origins must be listed with `--allow-origin` (repeatable). The
+  packaged Console instead proxies the dashboard through its authenticated
+  same-origin route.
+
+Connect HTTP-based clients to `http://127.0.0.1:8787/mcp`. There is **no
+authentication on the MCP server itself** — it trusts the caller's `athleteId`
+parameter — so keep it on loopback or restrict it at the network layer. For
+remote access over SSH: `ssh -L 8787:127.0.0.1:8787 server`.

package/docs/distribution.md

@@ -0,0 +1,58 @@
+# Distribution and release readiness
+
+Catence now has a repeatable distribution path.
+
+## Artifacts
+
+| Surface | Source | Consumer path |
+| --- | --- | --- |
+| npm | `package.json` and compiled `dist/` | `npm install --global catence` or `npx --yes catence@<version> demo` |
+| PyPI Console | `console/pyproject.toml` | `uvx catence-console@<python-version> serve`; it starts the matching npm runtime unless `--mcp-url` is supplied |
+| PyPI UI runtime | `catence-ui` fork | `catence-chainlit==<python-version>` provides the prebuilt maintained Chainlit frontend used by Console |
+| APM | `apm.yml` | `apm install rifusaki/catence#v<version>` configures normal and generated-demo MCP entries |
+| MCPB | `mcpb/manifest.json` | Attach the platform-specific `catence-demo-<version>-<platform>-<arch>.mcpb` release asset in an MCPB-capable desktop client |
+
+The package exposes two binaries:
+
+- `catence` starts the stdio MCP server, `catence serve` starts the loopback Streamable HTTP server, and `catence demo` creates a generated store before starting stdio.
+- `catence-data` manages catalog `setup`, athlete selection, per-athlete secrets,
+  `sync`, `backfill`, provider authentication, retrieval-index rebuilding, and
+  `demo` generation.
+
+`catence-data demo` and `catence demo` use `~/.catence-demo` by default. Both
+commands refuse to modify an existing directory unless it contains the Catence
+demo marker. Generated data is marked in every MCP tool response.
+
+## Release gates
+
+`release/manifest.json` maps the npm version to its PEP 440 Console and
+Chainlit versions. The release check requires those fields and the protocol
+version to agree with the npm package, Console package, runtime health
+contract, APM manifest, and MCPB manifest. When invoked for a Git tag, it also
+requires the tag to be `v<package-version>`.
+
+The verification workflow runs TypeScript checking, a moderate-or-higher npm dependency audit, all tests, a npm-pack dry run, and MCPB-manifest validation. The tag workflow then:
+
+1. builds an MCPB on Linux, macOS, and Windows, with the bundle manifest restricted to its native platform because DuckDB includes a native binding;
+2. publishes npm with provenance;
+3. validates that the versioned APM manifest installs the two intended MCP entries in a clean consumer root; and
+4. builds and publishes the matching `catence-console` wheel after confirming that the manifest's exact `catence-chainlit` version is already available; and
+5. uploads the MCPB artifacts to the GitHub release. The tagged source tree is itself the APM package.
+
+The `release` GitHub environment is intentional: publishing waits for that environment's approval rules. Configure npm trusted publishing for `rifusaki/catence` before creating the first `v0.1.0` tag. Its publish job upgrades to npm 11.5.1 or newer and deliberately avoids `setup-node`'s registry authentication so npm uses the GitHub Actions OIDC identity. Before releasing the two Python artifacts, configure PyPI Trusted Publishing for the `pypi` environment in both the maintained `catence-ui` fork (`catence-chainlit`) and this repository (`catence-console`).
+
+For beta tags, the dedicated `Beta` workflow publishes npm with the `beta`
+dist-tag and creates a GitHub prerelease after the corresponding Chainlit beta
+is available. The server procedure and acceptance criteria are in
+[release/beta-checklist.md](../release/beta-checklist.md).
+
+## Current operational gaps
+
+- The npm package name is available at the time this document was written, but it is not claimed until the first successful npm publish.
+- The MCPB demo bundle includes Node dependencies for its target platform. It is intentionally a generated-data experience; live Garmin/Intervals/Strava setup remains explicit so a desktop extension never receives provider credentials by surprise.
+- Live Garmin and Strava extraction still require Python 3.12 and `uv`; a future fully bundled provider runtime would remove that prerequisite.
+- MCPB artifacts are unsigned until a production code-signing certificate is configured. MCPB-capable clients may show an unsigned-extension warning.
+- `catence-chainlit` must be released from the maintained UI fork before each matching Catence tag. Until the first public wheel exists, Console source development uses a locally built wheel.
+- CI produces native MCPB assets for the standard GitHub runner architectures. ARM Linux and Windows-on-ARM need additional runners before assets can be advertised for those targets.
+
+These gaps are product/release work, not silent runtime fallbacks: the npm and APM paths make their assumptions explicit, and the demo stays synthetic until the user runs the separate live sync workflow.