catence 0.0.0 → 0.1.0

package/docs/architecture.md

@@ -0,0 +1,100 @@
+# Catence architecture
+
+This document records the architecture and design rationale for Catence, a local MCP server to interact with health and fitness data.
+
+Even though a great deal of code is written by an agent, the base architecture remains human-driven. However, since I am quite a beginner this means it may actually be somewhat less efficient, but as IBM famously said (somewhere), machine can't make decisions.
+
+## Design
+
+The project consists of the following stages:
+
+1. Data fetching
+2. Normalization and storage
+3. Queries, tools and methods
+4. Serving
+
+## Source-layer boundaries
+
+The repository is one publishable package, organized by logical layers:
+
+```text
+src/contracts/   shared staging, runtime-path, and storage-port contracts
+        ↑
+src/core/        catalog, query guard, analytics, retrieval, and runtime policy
+        ↑
+src/elt/         provider clients, artifact/archive storage, DuckDB, Parquet,
+                 normalization, and management use cases
+        ↑
+src/runtime/     internal facade for shared core, ETL, storage, and providers
+        ↑
+src/interfaces/  CLI and MCP transport adapters and executable entry points
+```
+
+`core` imports contracts and standard-library capabilities only. `elt` implements storage and provider concerns and may invoke core use cases such as retrieval-index building. `runtime` is the only import surface for `interfaces`; a checked boundary prevents CLI, HTTP, and MCP adapters from reaching into `core` or `elt` implementation paths. `interfaces` parses transport-specific input, invokes these use cases, and serializes the response. The Python Garmin and Strava workers remain under `python/catence/` so their stable `uv` module path and npm distribution contract remain intact; they are an ELT component and never write DuckDB.
+
+### 1. Data fetching
+
+Garmin Connect provides the complete local record. Intervals.icu contributes only its separately named activity-analysis values (for example training load, RPE, feel, and weighted power). Strava is a deliberately sparse, targeted source for current gear and selected activity segment enrichment.
+
+For Garmin, we will use [python-garminconnect](https://github.com/cyberjunky/python-garminconnect) as it is the most mature and widely used library for this purpose. On the Intervals.icu side, the best option available right now is [node-intervals-icue](https://github.com/paladini/node-intervals-icu).
+
+### 2. Normalization and storage
+
+Catence is DuckDB-first. It is a local, read-only ingestion pipeline before it becomes an MCP server.
+
+```text
+Intervals.icu / Garmin Connect / targeted Strava
+        ↓
+immutable raw JSON and original activity files
+        ↓
+DuckDB catalogue and provenance records
+        ↓
+Parquet activity-stream lake, queried through DuckDB views
+```
+
+Runtime data lives in the ignored `.catence/` directory:
+
+- `catence.duckdb` contains normalized entities, ingestion state, source provenance, and future-query views.
+- `raw/` contains content-addressed JSON responses and original downloaded activity files.
+- `lake/activity_samples/` contains one Parquet stream file per provider activity, partitioned by provider/year/month.
+- `staging/` contains versioned Garmin JSONL batches before the Node importer commits them to DuckDB.
+
+Node/TypeScript owns the DuckDB connection and all database writes. It fetches Intervals.icu directly and imports Garmin staging batches. Python owns Garmin authentication, API extraction, FIT parsing, and Parquet generation; it never opens the DuckDB database for writing.
+
+Every provider call is on an explicit GET/download allowlist. Syncs archive responses before normalization, record work-item and error state, continue past an individual failed endpoint/activity, and can be safely rerun because source artifacts are content-addressed and normalized rows have stable keys.
+
+The first manual sync uses the previous 12 months only when there is no local normalized coverage. Afterwards, normal syncs are cursor-backed: daily facts reconcile the most recent three days and activity discovery reconciles the most recent fourteen. Activity child endpoints and files are fetched only for new or changed activity summaries. Historical imports remain explicit backfill commands; by default they stop before the newest local source date for each daily/activity data family, avoiding remote reads and upserts of recent data. `backfill --refresh` intentionally disables that boundary. There is no scheduler or provider mutation.
+
+Normalized tables preserve provenance rather than force an early merge:
+
+- Activities remain provider-specific through `activity_sources`. Provider external IDs are strong links; the general cross-provider auto-link requires one sport-compatible candidate within 90 seconds and tight moving-duration/distance tolerances, while ambiguity and virtual/indoor conflicts remain unlinked. Strava hydration is separate: it uses elapsed duration and does not reject an otherwise compatible candidate on Strava's indoor/virtual classification. Garmin is the canonical original activity detail source. Intervals training load, RPE, feel, and related calculations remain separately named analysis fields; Strava is never canonical.
+- Daily health observations retain provider/source values in `daily_metrics`, while the default `daily_health` projection selects Garmin for every date where Garmin has health facts (another provider is a whole-day fallback). Nutrition includes daily macro/hydration totals and individual food/meal items, in addition to the complete archived payload.
+- Plans, workouts, events, routes, gear, devices, goals, achievements, messages, and provider-specific data are represented as normalized source and domain entities with stable query views and `extension_json` for fields the common model does not yet name.
+- Per-sample GPS, power, heart rate, cadence, speed, altitude, temperature, and grade data are stored as nullable Parquet columns; uncommon sensors are kept in per-sample JSON and the original activity archive remains recoverable.
+
+### 3. Queries, tools and methods
+
+The MCP process is a separate stdio consumer. Ordinary tools and resources open DuckDB `READ_ONLY` snapshots. The only write capabilities are the explicit `hydrate_strava_activity`, serial `hydrate_recent_strava_activities`, and `hydrate_strava_segment_history` tools: each acquires the shared data-directory lock, calls only the Strava GET allowlist, archives responses before normalization, commits, and releases the lock. If another writer owns it, the result is retryable `data_sync_in_progress`.
+
+The query layer has four shared pieces:
+
+1. A catalog describes every allowed dataset, field, unit, provenance field, filter, and grouping. The catalog includes activities, activity sources and summaries/intervals, health/daily facts, nutrition days/items, all domain projections, source entities, and activity samples.
+2. The repository reads stream data only from `stream_manifest`. It resolves each recorded relative Parquet path under `lake/activity_samples`, verifies it exists under that directory, and otherwise produces an empty typed relation. No MCP argument can introduce a filesystem path.
+3. Analytics services power both general tools and any future dedicated fitness tool. They provide bounded series reads, declarative aggregation, descriptive statistics/correlations/trends, and OLS, Theil–Sen, quadratic, or cubic fitting.
+4. A SQL guard offers a limited lower-level fallback for questions that do not yet justify a dedicated tool. It accepts one parameterized `SELECT` or `WITH … SELECT` over cataloged views, inspects its resolved table names, rejects filesystem/extension/mutation statements, interrupts after four seconds, and returns deterministic `ORDER BY ALL` pages of at most 500 rows. Every page reports `returnedRows`, `totalRows`, `truncated`, and a query-bound `nextCursor`; a truncated response explicitly warns against exhaustive conclusions.
+
+`read_series` returns a maximum of 1,000 points per page, along with the same explicit row-count/truncation fields. Dense activity streams default to minute aggregation on the first `auto` page; raw data stays available through the same bounded interface with a deterministic query-bound cursor.
+
+### 4. Serving and retrieval
+
+The server exposes `catence_status`, `describe_data`, `describe_dataset`, `read_series`, `aggregate_data`, `analyze_series`, `fit_series_model`, `query_read_only_data`, `find_activities`, `get_ftp_history`, `get_vo2max_history`, `power_curve_trend`, `power_coverage_report`, `latest_cycling_activities`, `cycling_progress_report`, `review_daily_recovery_load`, `review_weekly_training`, `review_activity_deep_dive`, `search_context`, `hydrate_strava_activity`, `hydrate_recent_strava_activities`, and `hydrate_strava_segment_history`, plus resources for status, catalog, a single activity, and a date-range summary.
+
+`catence serve` is a loopback-only-by-default Streamable HTTP adapter. It creates a stateless MCP server and transport for each `/mcp` request, so the HTTP and stdio surfaces use the same tool implementation. `GET /health` is a versioned client handshake with runtime version, protocol version, and capabilities; distributed Console builds reject an incompatible protocol before starting a chat. The same listener serves a small read-only `/api/v1/dashboard` snapshot for the local Console: canonical daily-health rows, weekly canonical activity aggregates, recent canonical activities, status, coverage, and explicit missing-data caveats.
+
+`catence-data build-retrieval-index` explicitly generates `retrieval_documents` and `retrieval_index_state` in DuckDB. Documents draw from activity labels and key
+summary facts, interval labels, routes/messages, planned workouts/events, weekly training summaries, nutrition daily summaries, and food names. They do
+not include sample streams, GPS paths, source JSON, raw nutrition payloads, or activity files. Sync marks the index stale; rebuilding is idempotent and records the raw-data watermark. When the index is stale, `search_context` says so before its result can be used as activity evidence and directs callers to `find_activities` or `query_read_only_data` instead.
+
+When the DuckDB FTS extension is already available locally, the build uses it; otherwise—and without attempting installation—search falls back to normalized keyword matching. `catence_status` reports the active retrieval mode. Embeddings and vector search remain deliberately deferred until keyword/full-text results prove inadequate.
+
+Dedicated tools should be added gradually only when recurring questions have stable semantics and cannot be expressed clearly by these primitives. They must call the same repository/analytics services, preserving provenance and the read-only boundary.

package/docs/mcp-activity-retrieval.md

@@ -0,0 +1,377 @@
+# MCP activity retrieval contract
+
+This document is the implementation contract for answering questions. It records the current data behaviour and the dedicated MCP endpoints that should replace repeated ad-hoc SQL.
+
+The only mutation exception is targeted Strava activity, serial activity-batch, or segment-history hydration. It acquires the shared data-directory lock, calls only the Strava GET allowlist, archives responses before normalization, and returns a retryable busy result if another writer owns the lock.
+
+## Basics
+
+- The MCP server is a local, stdio-only consumer of DuckDB and
+  registered Parquet files. These endpoints must not call Garmin or
+  Intervals.icu, download files, rebuild the retrieval index, or write to the
+  database.
+- `activity_id` is a logical identity only when it is linked by a
+  provider-supplied external ID. `activity_source_id` identifies one
+  provider's record and is the correct identifier for source-specific details,
+  samples, intervals, and laps.
+- Never link two records using time, distance, title, sport, or similar
+  metrics. A Garmin and an Intervals activity that look like the same workout
+  remain separate unless `link_state` and a shared external ID prove the link.
+- Every response includes `data`, `provenance`, `query`, `caveats`, and, when
+  appropriate, `nextCursor`. Keep existing result/error conventions:
+  `data_sync_in_progress`, `data_unavailable`, and `invalid_request`.
+- Source values are retained alongside derived values. Derived fields must name
+  their formula and must never overwrite a provider field.
+- For a selected activity’s Strava segments, climbs, per-segment grades, or
+  KOM/PRs, call `get_activity_segments`. It hydrates the matching Strava
+  activity before reading its efforts. Do not report segments as absent unless
+  that hydration result is `not_found`, `ambiguous`, unauthorised, throttled,
+  or failed—and report that result rather than guessing.
+
+## What exists today
+
+The following are already available and are the authoritative building blocks.
+Dedicated activity endpoints must call the same repository/analytics services,
+rather than embedding their own DuckDB connection or SQL guard.
+
+| Need | Current interface | Authoritative relation / identifier |
+| --- | --- | --- |
+| Find a recent activity | `query_read_only_data` on `activities`, `activity_sources`, and `activity_summary_facts` | `activity_id`; then `activity_source_id` |
+| Read one logical activity with its sources, summaries, and intervals | `catence://activity/{activityId}` | `activity_id` |
+| Read provider summary metrics | `aggregate_data` or `query_read_only_data` on `activity_summaries` | `activity_source_id` |
+| Read structured interval chunks | `query_read_only_data` on `activity_interval_facts` | `activity_source_id` |
+| Inspect sample-level HR/distance/etc. | `read_series` with `dataset: "activity_samples"` | `activity_source_id` |
+| Read an activity’s Strava segments/climbs | `get_activity_segments` | canonical `activity_id` or `activity_source_id` |
+| Locate relevant activity text | `search_context` | returned entity/activity identifiers |
+
+`activity_summary_facts` is the provider-specific summary view. It includes
+the summary metrics plus `activity_id`, `activity_source_id`, `provider`,
+`remote_activity_id`, source artifact hash, activity timestamps, sport, and
+name. `canonical_activity_training` contains one selected interpretation per
+logical activity (Garmin is preferred when linked); it is useful for
+comparison but must not hide provider detail.
+
+`activity_interval_facts` contains structured chunks:
+
+```text
+activity_source_id, interval_key, label, start_s, end_s, distance_m,
+avg_power, avg_hr, avg_pace, intensity, metrics_json,
+activity_id, provider, started_at_utc, sport, name
+```
+
+It is not synonymous with device laps. Some providers supply labelled workout
+intervals, some supply swim/lap chunks, and some expose an empty split list.
+Null `distance_m`, `start_s`, or `end_s` is a genuine “not supplied” value,
+not zero. `metrics_json` remains the source-specific escape hatch.
+
+`activity_samples` is a Parquet-backed time series available only through
+`read_series`/`aggregate_data`. It has `timestamp_utc`, `elapsed_s`,
+`distance_m`, `heart_rate_bpm`, and other nullable sensor fields. It cannot
+be used to introduce an arbitrary Parquet path.
+
+## Swim facts and tools
+
+`swim_length_facts` contains only explicit provider-supplied length records.
+Catence does not infer a 25 m/50 m length boundary, rest, or pace from Garmin
+sample points when distance disappears after the opening sample. An empty
+length result therefore means *not supplied*, not no lengths swum.
+
+`swim_set_facts` retains source-specific grouped work:
+
+- `garmin_detected` comes from Garmin split summaries and may have a supplied
+  duration/HR but no usable distance;
+- `intervals_auto` parses Intervals.icu labels such as `12x 52m 154bpm` into
+  `reps`, `rep_distance_m`, total distance, and mean HR. It remains an
+  auto-detected block, not a manually pressed set, and pace/work/rest stay
+  null unless supplied.
+
+`activity_interval_facts` now includes `duration_s`, `moving_s`, and
+`source_type` for those source rows. `canonical_activity_facts` exposes the
+unmodified Garmin and Intervals values beside each selected field, the source
+that won precedence, their distance difference, and quality flags.
+
+Use `get_swim_laps({ activityId, provider? })` for one source or linked
+activity. A source ID is resolved exactly; a logical activity ID returns all
+linked swim sources. Use `swim_progress_report({ startDate, endDate,
+poolLengthM? })` for Garmin-native summary comparisons. The report never
+creates a pace trend from `moving_s / distance_m`, and it returns
+data-completeness notes for per-length pace.
+
+Ingestion flags implausible pool settings, zero speed/cadence long pool
+sessions, active-length/distance mismatches, linked-provider distance
+disagreements, and missing explicit length records. Flags are caveats; they
+never overwrite or discard a provider's source values.
+
+## Current investigation procedure
+
+Use this procedure until the endpoints below exist.
+
+1. Check `catence_status`. If the sync snapshot is unavailable, report the MCP
+   error; do not retry by opening the database for writing.
+2. List provider records from newest to oldest with `activities` joined to
+   `activity_sources` and, where needed, `activity_summary_facts`. Include
+   both the logical and source IDs in the result.
+3. For one selected source, query `activity_interval_facts` ordered by
+   `start_s`. Do not use a time/distance heuristic to select a different
+   source.
+4. If a provider’s interval rows are empty or all structural fields are null,
+   say that detailed splits were not supplied by that imported endpoint. A
+   summary field such as Garmin's lap count or fastest split is still useful,
+   but it does **not** reconstruct per-lap records.
+5. If numerical detail is required, use `read_series` for the selected
+   `activity_source_id`; include its resolution/downsampling caveat. The
+   original activity file may exist in the raw archive, but raw archives are
+   not exposed directly to MCP in this release.
+
+### Segment calculations
+
+For an interval with positive `distance_m` and both times present, an agent
+may add the following *derived* fields:
+
+```text
+duration_s = end_s - start_s
+pace_s_per_100m = 100 * duration_s / distance_m
+```
+
+Only emit `pace_s_per_100m` when `duration_s > 0` and `distance_m > 0`.
+Retain the original `avg_pace` separately and do not infer its unit when the
+provider does not document/populate it. A no-distance chunk may be described
+as `no_distance_segment`; calling it a recovery/rest requires a source label
+or a clearly labelled user interpretation. If the sum of chunk distances
+differs from the activity summary, report both values and the difference.
+
+## Proposed dedicated MCP endpoints
+
+These endpoints are drafts, not registered tools yet. Add them incrementally
+only after their shared service methods and fixture tests exist.
+
+## Implemented fitness and hydration endpoints
+
+- `describe_dataset(dataset)` returns one cataloged schema and its coverage. `training_metric_observations` also reports its observed sports, metric names, units, and source types.
+- `get_ftp_history`, `get_vo2max_history`, `power_curve_trend`, and `power_coverage_report` read normalized, source-aware fitness facts. Power tools require an explicit sport or sport family, use `power_bests`/`power_best_facts` for FIT-derived duration values, and do not treat sparse `avg_power` summaries as coverage. `get_vo2max_history` does not default to cycling: omission returns available source labels and requires an explicit choice. For Garmin running VO₂max, request `sport: "running"`; the tool reads the raw `generic` source series and preserves that label on returned observations.
+- `find_activities` is implemented for compact, canonical, paginated activity/race discovery by sport, distance, name, and date. Its race flags are transparent heuristics, not provider-confirmed race metadata.
+- `get_activity_segments` is the required segment/climb path. It performs the
+  targeted Strava hydration before returning the persisted effort and segment
+  facts; an empty result must be interpreted alongside its hydration status.
+- `latest_cycling_activities` returns Garmin source records to avoid silently double-counting linked Intervals summaries; optional multisport parents are explicitly flagged.
+- `cycling_progress_report` composes the preceding read-only outputs with monthly canonical volume/load. It is descriptive, not a physiological model.
+- `hydrate_recent_strava_activities` accepts an explicit list or a bounded date/sport window and awaits each write in sequence. Its unmatched output includes the exact Strava search window and safe-match rejection diagnostics.
+
+### Power investigation procedure
+
+For a question about running or cycling power, do not begin with
+`canonical_activities.avg_power`: it is an activity-summary field and can be
+null even when the FIT stream has power. Instead:
+
+1. Call `describe_dataset` for `power_bests` and use `power_coverage_report`
+   with an explicit `sport` or `sportFamily` to establish coverage and every
+   available duration.
+2. Use `power_curve_trend` with the same selector and
+   `sourceQuality: "garmin_fit_derived"` for comparable monthly curve bests.
+3. Inspect `activity_samples` only for a selected `activity_source_id` when a
+   specific extreme needs validation. Raw sample reads are paginated and are
+   not evidence that the global power dataset is absent.
+
+### `list_recent_activities`
+
+Purpose: answer “what is my latest activity?” without requiring the agent to
+invent joins, provider precedence, or identifier handling.
+
+Input:
+
+```ts
+{
+  before?: string,              // ISO timestamp; exclusive cursor anchor
+  after?: string,               // ISO timestamp; inclusive
+  provider?: "garmin" | "intervals",
+  sport?: string,
+  sourceMode?: "source" | "logical", // default: "source"
+  limit?: number,               // 1–100; default: 20
+  cursor?: string
+}
+```
+
+`sourceMode: "source"` is the default because it never conceals an unlinked
+provider record. It returns one provider source per item. `sourceMode:
+"logical"` returns an activity plus all its source records only when the
+database already has that logical relationship; unlinked records remain
+separate items. Both modes sort by `started_at_utc DESC`, then stable source
+identity. Cursor contents are opaque, signed/validated query state—not a raw
+SQL offset.
+
+Each item should include:
+
+```ts
+{
+  activityId: string,
+  activitySourceId: string,
+  provider: "garmin" | "intervals",
+  remoteActivityId: string,
+  externalId: string | null,
+  linkState: string,
+  startedAtUtc: string | null,
+  startedAtLocal: string | null,
+  timezone: string | null,
+  sport: string | null,
+  name: string | null,
+  summary: {
+    distanceM: number | null,
+    movingS: number | null,
+    elapsedS: number | null,
+    avgHr: number | null,
+    maxHr: number | null,
+    trainingLoad: number | null
+  } | null,
+  availability: { intervals: boolean, samples: boolean }
+}
+```
+
+The query is a read-only projection of `activities`, `activity_sources`,
+`activity_summary_facts`, and `stream_manifest`. It must not use
+`canonical_activity_training` to suppress a Garmin source. Provenance names
+the selected relations and source artifact hash where available.
+
+### `get_activity_detail`
+
+Purpose: return the compact, authoritative detail an agent needs after a
+selection from `list_recent_activities`.
+
+Input is exactly one of:
+
+```ts
+{ activitySourceId: string, include?: ["summary", "intervals", "availability"] }
+// or
+{ activityId: string, include?: ["summary", "intervals", "availability"] }
+```
+
+`activitySourceId` returns exactly that provider record. `activityId` returns
+the logical activity plus **all** linked sources; it never selects a “best”
+source silently. The default includes `summary` and `availability`, not every
+interval. Intervals are limited to 500 items and receive deterministic cursor
+pagination. A compact response should contain activity identity/timestamps,
+source identities and external IDs, all available provider summaries, and:
+
+```ts
+availability: {
+  intervalCount: number,
+  intervalDetailsAvailable: boolean,
+  stream: { available: boolean, rowCount?: string, columns?: string[] },
+  originalArchiveRecorded: boolean
+}
+```
+
+`originalArchiveRecorded` only states that a raw object/manifest exists. It
+does not expose a filesystem path or claim that FIT parsing supplied laps.
+`include: ["intervals"]` follows the segment contract below.
+
+### `list_activity_segments`
+
+Purpose: replace the manual interval query used for lap/interval questions.
+It should have a neutral name because source “intervals”, swim laps, and
+device splits have different meanings.
+
+Input:
+
+```ts
+{
+  activitySourceId: string,
+  kind?: "all" | "structured_interval" | "lap_or_split", // default: "all"
+  includeDerived?: boolean,  // default: true
+  limit?: number,            // 1–500; default: 100
+  cursor?: string
+}
+```
+
+`kind` filters only by explicit source classification. It must return an
+empty result with `lap_or_split_available: false` when the provider supplied
+no detailed split records; it must not manufacture laps from sample points.
+
+For each item return source fields (`intervalKey`, `label`, `startS`, `endS`,
+`distanceM`, `avgHr`, `avgPower`, `avgPace`, `intensity`, and optionally
+`metricsJson`) plus safe derived fields:
+
+```ts
+{
+  derived: {
+    durationS: number | null,
+    paceSPer100m: number | null,
+    distanceClass: "positive_distance" | "no_distance" | "unknown"
+  }
+}
+```
+
+The top-level result includes total supplied distance, total derived distance,
+summary distance, and their difference. It must explicitly disclose whether
+the response is made of structured intervals, provider laps/splits, or both.
+
+### `read_activity_stream`
+
+Purpose: make selected-source sample inspection straightforward while retaining
+the existing bounded stream rules.
+
+Input:
+
+```ts
+{
+  activitySourceId: string,
+  metrics: Array<"elapsed_s" | "distance_m" | "heart_rate_bpm" |
+                 "power_w" | "cadence_rpm" | "speed_mps" | "temperature_c">,
+  resolution?: "raw" | "1m" | "5m" | "15m" | "auto",
+  startElapsedS?: number,
+  endElapsedS?: number,
+  pageSize?: number,
+  cursor?: string
+}
+```
+
+This is a source-ID wrapper over `read_series({ dataset: "activity_samples" })`.
+It inherits the 1,000-point page limit, cursor format, automatic downsampling,
+manifest-only Parquet access, and null handling. It returns no data—not an
+error—when the source has no registered stream, with a caveat explaining that
+sample availability is provider/activity-specific.
+
+## Intended agent behaviour
+
+For “how did this go in the context of my recent swims?” an agent should:
+
+1. Use `list_recent_activities` filtered to swimming to identify the selected
+   source and comparable source records.
+2. Use `get_activity_detail` for the selected source. Prefer canonical
+   Intervals training values only when the logical activity is strongly linked;
+   otherwise state the provider used.
+3. Use `list_activity_segments` only for set/lap questions. Compute pace using
+   the documented formula, name it as derived, and do not call unlabelled
+   sections “recovery” as a fact.
+4. Use `read_activity_stream` when the summary/segments cannot answer a
+   question about HR evolution, temperature, or other sample-level behaviour.
+5. State missing data and provenance in the answer. Do not imply that an empty
+   Garmin split list means no laps occurred—only that detailed split records
+   were not returned by the imported endpoint.
+
+## Implementation order and acceptance criteria
+
+1. Add repository methods that return typed source-first activity records and
+   manifest availability. Keep SQL there; MCP handlers remain thin.
+2. Implement `list_recent_activities`, including stable ordering and tamper-
+   resistant cursor validation.
+3. Implement `get_activity_detail` and `list_activity_segments` against the
+   repository methods. Reuse the existing JSON-safe result/error envelope.
+4. Add `read_activity_stream` as a validated adapter to `AnalyticsService`;
+   do not duplicate downsampling or Parquet path checks.
+5. Add Zod schemas and one independent module/test file per tool. Update the
+   catalog/README once the tools are registered.
+
+Fixture tests must cover:
+
+- two unlinked Garmin/Intervals records with similar timestamps and distances;
+  list results remain distinct;
+- a truly strong-ID-linked activity; detail returns both sources without
+  concealing either;
+- labelled intervals, unlabelled positive-distance chunks, and no-distance
+  chunks; pace is derived only when valid;
+- a Garmin summary with lap count/fastest split but an empty split list;
+  `lap_or_split_available` is false and no laps are invented;
+- no stream manifest, missing Parquet file, and a valid registered stream;
+- pagination, malformed/tampered cursors, limits, and read-only snapshot
+  errors;
+- response provenance and caveats for every branch.

package/package.json

@@ -1,10 +1,85 @@
 {
   "name": "catence",
-  "version": "0.0.0",
-  "description": "OIDC trusted publishing setup package for catence",
+  "version": "0.1.0",
+  "description": "Local MCP access to normalized Garmin, Intervals.icu, and targeted Strava fitness data.",
+  "license": "AGPL-3.0-or-later",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/rifusaki/catence.git"
+  },
+  "homepage": "https://github.com/rifusaki/catence#readme",
+  "bugs": {
+    "url": "https://github.com/rifusaki/catence/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "engines": {
+    "node": ">=22"
+  },
+  "bin": {
+    "catence": "./dist/interfaces/mcp/main.js",
+    "catence-data": "./dist/interfaces/cli/main.js"
+  },
+  "files": [
+    "dist/**/*.js",
+    "dist/**/*.d.ts",
+    "README.md",
+    "config.example.json",
+    "docs",
+    "pyproject.toml",
+    "uv.lock",
+    "python/__init__.py",
+    "python/catence/providers/garmin/*.py",
+    "python/catence/providers/strava/*.py",
+    "python/catence/__init__.py",
+    "python/catence/providers/__init__.py"
+  ],
   "keywords": [
-    "oidc",
-    "trusted-publishing",
-    "setup"
-  ]
+    "mcp",
+    "model-context-protocol",
+    "fitness",
+    "garmin",
+    "intervals-icu",
+    "strava",
+    "triathlon",
+    "duckdb"
+  ],
+  "scripts": {
+    "build": "node --input-type=module -e \"import { rmSync } from 'node:fs'; rmSync('dist', { recursive: true, force: true });\" && tsc -p tsconfig.build.json",
+    "check": "node scripts/check-runtime-boundaries.mjs && tsc -p tsconfig.json --noEmit",
+    "test": "vitest run --config vitest.config.ts",
+    "test:watch": "vitest",
+    "catence-data": "tsx src/interfaces/cli/main.ts",
+    "mcp": "tsx src/interfaces/mcp/main.ts",
+    "console": "uv run --project console catence-console serve",
+    "console:doctor": "uv run --project console catence-console doctor",
+    "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",
+    "mcpb:prepare": "npm run build && node scripts/release-artifacts.mjs prepare-mcpb",
+    "mcpb:pack": "node scripts/pack-mcpb.mjs",
+    "prepack": "npm run release:check && npm run build",
+    "prepublishOnly": "npm run release:check && npm run check && npm test"
+  },
+  "dependencies": {
+    "@duckdb/node-api": "^1.4.4-r.1",
+    "@modelcontextprotocol/sdk": "^1.30.0",
+    "commander": "^14.0.0",
+    "dotenv": "^17.2.2",
+    "intervals-icu": "^2.2.0",
+    "zod": "^4.1.5"
+  },
+  "devDependencies": {
+    "@types/node": "^24.3.0",
+    "tsx": "^4.20.5",
+    "typescript": "^5.9.2",
+    "vitest": "^3.2.4"
+  },
+  "overrides": {
+    "fast-uri": "3.1.5",
+    "hono": "4.12.34",
+    "nanoid": "3.3.17"
+  }
 }

package/pyproject.toml

@@ -0,0 +1,28 @@
+[project]
+name = "catence-data"
+version = "0.1.0"
+description = "Local Catence provider workers for read-only fitness data extraction"
+requires-python = ">=3.12"
+dependencies = [
+  "duckdb>=1.4.0",
+  "fitdecode>=0.10.0",
+  "garminconnect>=0.2.37",
+  "polars>=1.0.0",
+  "pyarrow>=18.0.0",
+  "pydantic>=2.0.0",
+  "stravalib>=2.5.0",
+]
+
+[tool.uv.sources]
+# fork commit
+garminconnect = { git = "https://github.com/rifusaki/python-garminconnect.git", rev = "732bf14602bce2ca22cb569ba6583c3229bf904d" }
+
+[tool.uv]
+package = false
+
+[dependency-groups]
+dev = ["pytest>=8.0.0"]
+
+[tool.pytest.ini_options]
+pythonpath = ["."]
+testpaths = ["python/tests"]

package/python/__init__.py

@@ -0,0 +1 @@
+"""Python runtime package root for Catence."""

package/python/catence/providers/garmin/__init__.py

@@ -0,0 +1,3 @@
+"""Read-only Garmin extraction worker for Catence."""
+
+STAGING_SCHEMA_VERSION = 1