@drakulavich/oura-cli 0.5.1 → 0.6.0

package/CHANGELOG.md

@@ -6,6 +6,38 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+## [0.6.0] - 2026-09-06
+
+### Fixed
+- A global flag between a command and its subcommand made the CLI reject the flag's *value* as a command: `db --format json today` failed with `Unknown command "json"`, and `db --db <path> today` echoed the whole path back. Global flags are now lifted to the end of the command line wherever they appear, so the three spellings of `--format json db today` all work. Tokens after `--` are left alone. (#79)
+- `--no-color` left citty's help output coloured, because citty reads `NO_COLOR` when its module is evaluated and the variable was only set afterwards. The rule moved into `src/lib/color-mode.ts` and is applied by `src/lib/apply-color-mode.ts`, which the entry point imports first. Piped help is plain too unless `FORCE_COLOR` asks otherwise, `FORCE_COLOR=0` included, which chalk reads as off. (#80)
+- `describe`, `manifest`, `healthcheck` and `login` accepted an unknown `--format` (`xml`) and exited 0, while every other command exited 1 with `BAD_ARGS`. The value is validated in `assertKnownArgs`, which every command calls, instead of only in the resolver the JSON-only commands never reach. (#81)
+- `db week` lost its column alignment whenever colour was on: `padStart` counted the ANSI escapes chalk had already wrapped each score in, so it padded by nothing. Piped output was correct, which is why the tests never saw it. Padding now measures visible width (`src/lib/pad.ts`), and `report` uses the same helper. (#82)
+- An empty `--db` (or `OURA_DB_PATH`) was falsy, so it fell through to the default and every command silently opened — and migrated — the home cache at `~/.oura-cli/oura.db`. A wrapper expanding an unset variable into `--db "$VAR"` therefore wrote to the user's real database. The same went for `--db=` and a trailing `--db` with no value. All of them now fail with `BAD_ARGS`, like the blank-but-not-empty value already did, and an `OURA_DB_PATH` set to an empty string is an error rather than a request for the default. `doctor` reports it as an argument error too, instead of a `database: fail` health finding with a database exit code. (#76)
+- `sync` fetched nothing, and said nothing, for any collection whose last stored day was after the end of the window. A timezone west of the one the cache was built in (`--tz`, `OURA_TZ`, a laptop that travelled) did this to every daily collection for up to a day; a row dated in the future — a tag on next month, which Oura allows — did it to that collection on every run from then on. A collection now resumes from its newest stored day *at or before* the end of the window, so a future-dated row is ignored rather than freezing the collection, and the days behind it are still fetched. An explicit `--from` after the end of the window is rejected with `BAD_ARGS`. (#69)
+- `sync` never fetched the heart-rate samples Oura adds to days already behind the watermark: on a live account 8,004 `source='workout'` samples over nine days were missing from an incrementally synced cache and present in a fresh one, with nothing in the output to say so. A collection can now declare `syncLookbackDays`, and `hr` re-walks the last 14 days on every sync. The window `sync` reports still describes what the cache needed, so a lookback does not make every run announce a fortnight. Samples Oura later reclassifies (`awake` → `workout`) are still kept, since `heartrate` never deletes. (#68)
+- `report` decided whether a day's activity was complete from the newest heart-rate sample, but Oura publishes heart-rate days after the daily summaries: right after a ring sync the report called three fully synced days "still accumulating". A day now counts as complete once a later day has its own activity record; heart-rate plays no part. `lastUpload` stays in the JSON as information and the note no longer quotes it. (#57)
+
+### Added
+- Eight collections from the Oura OpenAPI spec (1.37), each available through `fetch <name>`, stored by `sync`, listed in `describe`/`manifest`, counted by `db stats`, with a JSON Schema under `docs/schemas/`: `resilience` (daily_resilience), `vo2max` (vO2_max — its table has existed since 0.1 and is finally populated), `sleep-time` (sleep_time), `session` (session), `rest-mode` (rest_mode_period), `tags` (enhanced_tag; the legacy `tag` endpoint is not offered), `ring` (ring_configuration) and `battery` (ring_battery_level, a timestamp-keyed timeseries fetched in pieces of at most 30 days like `hr`). Schema migration 3 creates the seven new tables. (#44)
+- Collection registry: `rangeParams: 'none'` for snapshot endpoints that take no range. `fetch` rejects `--day`/`--from`/`--to`/`--days` for them with `BAD_ARGS` instead of ignoring the flags, and `sync` replaces the table with each response (a ring removed from the account disappears locally too) instead of keeping a watermark — also under `--from/--to`, since a snapshot has no history to backfill.
+
+### Changed
+- The `sync` text summary lists every registry collection by its `fetch` name (`sleep 28 (+2)  readiness 0 (+0)`), in a fixed-width grid whose column count follows the terminal width (up to four, and a single unpadded cell per line once two no longer fit — around 46 columns, sooner when a count is wide), instead of a hand-written list of nine tables. Cells no longer break across lines on a narrow terminal, and the counts line up. (#83)
+- `sync` prints a progress line for every collection, including those that returned nothing, and names both the collection and its table (`  + tags (enhanced_tags): 0 fetched, 0 new`) so the lines and the summary can be read together. A silent collection used to be indistinguishable from a failed one while the summary listed it anyway. (#83)
+
+## [0.5.2] - 2026-09-06
+
+### Fixed
+- `db trends N` covers N calendar days ending today; it used to include one day more than the heading claimed. (#52)
+- `report` no longer averages a day whose activity is still accumulating as if it were complete. A day counts as complete once it is over in the report timezone and the ring has uploaded past its end (the newest heart-rate sample in the cache is the proxy); activity and steps averages, the high-activity pattern and the steps recommendation stop at the last complete day, while sleep and readiness — final once they exist — still use the whole window. The partial day stays in the daily table, marked `*`, with one line explaining it. (#57)
+- A 401/403 from the Oura API carries a hint (`oura-cli login` with a fresh token), like a missing token already did. (#54)
+
+### Changed
+- `manifest`: `healthcheck.expects` lists the `error` field that `healthcheck` emits when `ok` is false. (#54)
+- `report` JSON: `days[].partial`, `completeThrough`, `lastUpload` and `averages[].count` are added; nothing is removed or renamed. (#57)
+- README's automation section no longer claims JSON Schemas for every output shape (they cover `fetch` and `doctor`), explains that `doctor` and `healthcheck` exit 0 with `ok: false` when the probe itself ran, and records two quirks kept for compatibility: `report --period month` returns `weekStart`/`weekEnd`, and `heartrate.day` is the date written in Oura's timestamp, UTC in practice. (#54)
+
 ## [0.5.1] - 2026-09-05
 
 Fixes from the 0.5.0 exploratory testing sessions: the seam between citty and the command runner, and the sync window.
@@ -329,6 +361,7 @@ Fixes from the 0.5.0 exploratory testing sessions: the seam between citty and th
 - Local SQLite cache at `~/.oura-cli/oura.db`.
 - Auth via `oura-cli login`, `OURA_TOKEN`, `OURA_TOKEN_PATH`, or `~/.oura-token`.
 
+[0.5.2]: https://github.com/drakulavich/oura-cli/releases/tag/v0.5.2
 [0.5.1]: https://github.com/drakulavich/oura-cli/releases/tag/v0.5.1
 [0.5.0]: https://github.com/drakulavich/oura-cli/releases/tag/v0.5.0
 [0.4.4]: https://github.com/drakulavich/oura-cli/releases/tag/v0.4.4

package/README.md

@@ -54,7 +54,7 @@ oura-cli sync     # first sync fetches the last 30 days; later syncs resume from
 oura-cli report   # weekly digest in the terminal
 ```
 
-Subsequent `oura-cli sync` re-fetches each collection from its own last stored day (Oura revises recent days, so the overlap is deliberate) and reports rows fetched (+new). `oura-cli sync --from 2026-08-01 [--to 2026-08-07]` re-fetches an explicit window for every collection instead — for example after an interrupted sync. `oura-cli db today` / `oura-cli db week` read the local cache instantly, no API call.
+Subsequent `oura-cli sync` re-fetches each collection from its own last stored day (Oura revises recent days, so the overlap is deliberate) and reports rows fetched (+new). Heart rate goes back two weeks each time, because Oura publishes workout samples days after the day they belong to. `oura-cli sync --from 2026-08-01 [--to 2026-08-07]` re-fetches an explicit window for every collection instead — for example after an interrupted sync. `oura-cli db today` / `oura-cli db week` read the local cache instantly, no API call.
 
 ### If something looks wrong
 
@@ -96,7 +96,7 @@ oura-cli report                   # weekly (default)
 oura-cli report --period month    # 30-day window with weekly buckets
 ```
 
-Reports cover daily scores, averages, deltas vs the previous window, sleep details, and a short recommendation block.
+Reports cover daily scores, averages, deltas vs the previous window, sleep details, and a short recommendation block. A day whose activity is still accumulating (today, or the last day before the ring stopped syncing) is shown with a `*` and kept out of the activity averages and recommendations; the JSON says so via `days[].partial` and `completeThrough`.
 
 ### Trends and stats
 
@@ -116,7 +116,9 @@ oura-cli fetch workout --from 2026-05-01 --to 2026-05-31
 oura-cli fetch sleep-periods --day 2026-06-01 | jq '.[] | {day, type, average_hrv}'
 ```
 
-Collections: `sleep readiness activity hr spo2 stress workout sleep-periods cv-age`.
+Collections: `sleep readiness activity hr spo2 stress workout sleep-periods cv-age resilience vo2max sleep-time session rest-mode tags ring battery`.
+
+`ring` is a snapshot of your ring's hardware, not a day range, so it takes no `--day`/`--from`/`--days`. `battery` is a timeseries like `hr`: keyed by timestamp, fetched in pieces of at most 30 days.
 
 ### Piping to other tools
 
@@ -136,6 +138,9 @@ oura-cli db trends 90 > trends.json
 | Database path    | `--db`      | `OURA_DB_PATH`     | `~/.oura-cli/oura.db`       |
 | Timezone         | `--tz`      | `OURA_TZ`          | system timezone, else `UTC` |
 | Output format    | `--format`  |                    | auto-detect (TTY → table)   |
+| Colour           | `--no-color`| `NO_COLOR`         | on for a terminal, off when piped |
+
+These are global: they may appear anywhere on the command line, before the command, between a command and its subcommand, or at the end. `oura-cli --format json db today`, `oura-cli db --format json today` and `oura-cli db today --format json` are the same command.
 
 ## Security
 
@@ -162,6 +167,14 @@ This tool reads your personal health data — handle the token with care.
 | Workouts   | Oura V2 `workout`                   | `workouts`            |
 | Sleep model      | Oura V2 `sleep`               | `sleep_model`         |
 | Cardiovascular age | Oura V2 `cardiovascular_age` | `cardiovascular_age`  |
+| Resilience | Oura V2 `daily_resilience`          | `daily_resilience`    |
+| VO₂ max    | Oura V2 `vO2_max`                   | `vo2max`              |
+| Sleep time | Oura V2 `sleep_time`                | `sleep_time`          |
+| Sessions   | Oura V2 `session`                   | `sessions`            |
+| Rest mode  | Oura V2 `rest_mode_period`          | `rest_mode_periods`   |
+| Tags       | Oura V2 `enhanced_tag`              | `enhanced_tags`       |
+| Ring       | Oura V2 `ring_configuration`        | `ring_configuration`  |
+| Battery    | Oura V2 `ring_battery_level`        | `ring_battery_level`  |
 
 Runtime: [Bun](https://bun.sh). Storage: built-in `bun:sqlite`. CLI parsing: [citty](https://github.com/unjs/citty). Output styling: [chalk](https://github.com/chalk/chalk). One ~110 kB `dist/index.js`, no native deps.
 
@@ -170,10 +183,12 @@ Runtime: [Bun](https://bun.sh). Storage: built-in `bun:sqlite`. CLI parsing: [ci
 If you're driving the CLI from a script or LLM harness:
 
 - `oura-cli describe` — JSON manifest of every command, argument, and output schema. Agents discover capabilities without scraping `--help`.
-- `oura-cli healthcheck` — `{ok, version, latencyMs}` JSON for liveness probes.
+- `oura-cli healthcheck` — `{ok, version, latencyMs}` JSON for liveness probes, plus `error` when `ok` is false.
+- Gate on `.ok`, not on the exit code: `doctor` exits 0 with `ok: false` for any warning-level check (no data yet, stale data, Oura API unreachable), and `healthcheck` exits 0 with `ok: false` for an unusable database (the probe itself ran). `doctor --offline` skips the token-validation call, and a skipped check still counts towards `ok`.
 - Errors emit a stable JSON envelope on stderr: `{"error":{"code":"…","message":"…","hint":"…"}}`.
 - Documented exit codes: `0` success, `1` user error, `2` auth, `3` API, `4` storage.
-- JSON Schemas under [`docs/schemas/`](docs/schemas/) describe every output shape, semver-stable. Per-collection schemas pin the identity fields (`id`, `day`, `timestamp`) and allow the rest of the Oura record through unchanged, so new upstream fields never break validation.
+- JSON Schemas under [`docs/schemas/`](docs/schemas/) cover `fetch <collection>`, `doctor` and the `describe` manifest itself, semver-stable; `describe` names the schema next to each command. Per-collection schemas pin the identity fields (`id`, `day`, `timestamp`) and allow the rest of the Oura record through unchanged, so new upstream fields never break validation. The local-data commands (`sync`, `db *`, `report`) have no schema files yet; their shapes are versioned through the CHANGELOG.
+- Two contract quirks, kept for compatibility: `report --period month` returns its window as `weekStart`/`weekEnd`, and `heartrate.day` (likewise `ring_battery_level.day`) in the cache is the date written in Oura's timestamp (UTC in practice) while every `--day`/`--tz` argument is local.
 
 Plays cleanly with [OpenClaw](https://github.com/openclaw/openclaw) — `oura-cli manifest` returns the tool-registry shape. A first-party `oura-mcp` companion is on the roadmap.
 

package/dist/index.js

@@ -557,8 +557,26 @@ var init_source = __esm(() => {
   source_default = chalk;
 });
 
-// src/index.ts
+// src/lib/apply-color-mode.ts
 init_source();
+
+// src/lib/color-mode.ts
+function forcesColor(value) {
+  return value !== undefined && value !== "" && value !== "0" && value !== "false";
+}
+function shouldDisableColor(argv, env, isTty) {
+  if (argv.includes("--no-color") || env.NO_COLOR)
+    return true;
+  return !isTty && !forcesColor(env.FORCE_COLOR);
+}
+
+// src/lib/apply-color-mode.ts
+if (shouldDisableColor(process.argv, process.env, process.stdout.isTTY === true)) {
+  process.env.NO_COLOR = "1";
+  source_default.level = 0;
+}
+
+// src/index.ts
 import { readFileSync as readFileSync2 } from "fs";
 
 // node_modules/citty/dist/_chunks/libs/scule.mjs
@@ -1309,6 +1327,78 @@ CREATE VIEW IF NOT EXISTS v_sleep_detail AS
         average_hrv, average_heart_rate as avg_hr, lowest_heart_rate as lowest_hr, efficiency
     FROM sleep_model ORDER BY day DESC;
     `
+  },
+  {
+    version: 3,
+    sql: `
+CREATE TABLE IF NOT EXISTS daily_resilience (
+    id TEXT PRIMARY KEY,
+    day TEXT UNIQUE,
+    level TEXT,
+    sleep_recovery REAL,
+    daytime_recovery REAL,
+    stress REAL
+);
+CREATE TABLE IF NOT EXISTS sleep_time (
+    id TEXT PRIMARY KEY,
+    day TEXT UNIQUE,
+    status TEXT,
+    recommendation TEXT,
+    bedtime_start_offset INTEGER,
+    bedtime_end_offset INTEGER,
+    day_tz INTEGER
+);
+CREATE TABLE IF NOT EXISTS sessions (
+    id TEXT PRIMARY KEY,
+    day TEXT,
+    type TEXT,
+    mood TEXT,
+    start_datetime TEXT,
+    end_datetime TEXT,
+    heart_rate TEXT,
+    heart_rate_variability TEXT,
+    motion_count TEXT
+);
+CREATE INDEX IF NOT EXISTS idx_sessions_day ON sessions(day);
+CREATE TABLE IF NOT EXISTS rest_mode_periods (
+    id TEXT PRIMARY KEY,
+    day TEXT,
+    end_day TEXT,
+    start_time TEXT,
+    end_time TEXT,
+    episodes TEXT
+);
+CREATE INDEX IF NOT EXISTS idx_rest_mode_periods_day ON rest_mode_periods(day);
+CREATE TABLE IF NOT EXISTS enhanced_tags (
+    id TEXT PRIMARY KEY,
+    day TEXT,
+    end_day TEXT,
+    start_time TEXT,
+    end_time TEXT,
+    tag_type_code TEXT,
+    comment TEXT,
+    custom_name TEXT
+);
+CREATE INDEX IF NOT EXISTS idx_enhanced_tags_day ON enhanced_tags(day);
+CREATE TABLE IF NOT EXISTS ring_configuration (
+    id TEXT PRIMARY KEY,
+    color TEXT,
+    design TEXT,
+    firmware_version TEXT,
+    hardware_type TEXT,
+    set_up_at TEXT,
+    size INTEGER
+);
+CREATE TABLE IF NOT EXISTS ring_battery_level (
+    timestamp TEXT,
+    level INTEGER,
+    charging INTEGER,
+    in_charger INTEGER,
+    day TEXT
+);
+CREATE UNIQUE INDEX IF NOT EXISTS idx_ring_battery_level_unique ON ring_battery_level(timestamp);
+CREATE INDEX IF NOT EXISTS idx_ring_battery_level_day ON ring_battery_level(day);
+    `
   }
 ];
 
@@ -1324,11 +1414,18 @@ function dbError(what, err) {
 function asDbError(err) {
   return err instanceof SQLiteError ? dbError("Database query failed", err) : undefined;
 }
+function requirePath(value, source) {
+  if (value.trim() === "") {
+    throw new CliError("BAD_ARGS", `${source} has no path`, `Pass a path to a SQLite file, or remove ${source} to fall back to the default database.`);
+  }
+  return value;
+}
 function getDbPath(explicit) {
-  if (explicit)
-    return explicit;
-  if (process.env.OURA_DB_PATH)
-    return process.env.OURA_DB_PATH;
+  if (explicit !== undefined)
+    return requirePath(explicit, "--db");
+  const fromEnv = process.env.OURA_DB_PATH;
+  if (fromEnv !== undefined)
+    return requirePath(fromEnv, "OURA_DB_PATH");
   return resolve(homedir(), ".oura-cli", "oura.db");
 }
 function openDatabase(explicit) {
@@ -1438,7 +1535,7 @@ class OuraClient {
       const redacted = redactSecrets(rawBody);
       const body = redacted.length > 200 ? redacted.slice(0, 200) + "\u2026 (truncated)" : redacted;
       if (response.status === 401 || response.status === 403) {
-        throw new CliError("TOKEN_INVALID", `Oura API ${response.status}: ${body}`);
+        throw new CliError("TOKEN_INVALID", `Oura API ${response.status}: ${body}`, "Run `oura-cli login` with a fresh Personal Access Token, or check OURA_TOKEN.");
       }
       throw new CliError("API_ERROR", `Oura API ${response.status}: ${body}`);
     }
@@ -1469,15 +1566,13 @@ var SUBCOMMANDS = new Set([
 ]);
 function normalizeArgv(argv) {
   const [bun, script, ...rest] = argv;
-  const subIdx = rest.findIndex((a) => SUBCOMMANDS.has(a));
-  if (subIdx < 0)
-    return argv;
-  const before = rest.slice(0, subIdx);
-  const subcommandOnwards = rest.slice(subIdx);
+  const dd = rest.indexOf("--");
+  const scanned = dd >= 0 ? rest.slice(0, dd) : rest;
+  const passthrough = dd >= 0 ? rest.slice(dd) : [];
+  const kept = [];
   const hoisted = [];
-  const leftover = [];
-  for (let i = 0;i < before.length; i++) {
-    const tok = before[i];
+  for (let i = 0;i < scanned.length; i++) {
+    const tok = scanned[i];
     if (tok.includes("=")) {
       const name = tok.slice(0, tok.indexOf("="));
       if (GLOBAL_FLAGS_WITH_VALUE.has(name) || GLOBAL_FLAGS_BOOLEAN.has(name)) {
@@ -1487,8 +1582,8 @@ function normalizeArgv(argv) {
     }
     if (GLOBAL_FLAGS_WITH_VALUE.has(tok)) {
       hoisted.push(tok);
-      if (i + 1 < before.length) {
-        hoisted.push(before[i + 1]);
+      if (i + 1 < scanned.length) {
+        hoisted.push(scanned[i + 1]);
         i++;
       }
       continue;
@@ -1497,13 +1592,9 @@ function normalizeArgv(argv) {
       hoisted.push(tok);
       continue;
     }
-    leftover.push(tok);
+    kept.push(tok);
   }
-  const dd = subcommandOnwards.indexOf("--");
-  if (dd >= 0) {
-    return [bun, script, ...leftover, ...subcommandOnwards.slice(0, dd), ...hoisted, ...subcommandOnwards.slice(dd)];
-  }
-  return [bun, script, ...leftover, ...subcommandOnwards, ...hoisted];
+  return [bun, script, ...kept, ...hoisted, ...passthrough];
 }
 function isVersionRequest(rawArgs) {
   for (let i = 0;i < rawArgs.length; i++) {
@@ -1521,13 +1612,15 @@ function isVersionRequest(rawArgs) {
 }
 
 // src/lib/format-resolve.ts
-function resolveFormat({ explicit, isTty }) {
-  if (explicit === undefined)
-    return isTty ? "table" : "json";
-  if (explicit === "table" || explicit === "json")
-    return explicit;
+function assertValidFormat(explicit) {
+  if (explicit === undefined || explicit === "table" || explicit === "json")
+    return;
   throw new CliError("BAD_ARGS", `Unknown --format value: "${explicit}". Use "table" or "json".`);
 }
+function resolveFormat({ explicit, isTty }) {
+  assertValidFormat(explicit);
+  return explicit ?? (isTty ? "table" : "json");
+}
 function formatFromArgv(argv, isTty) {
   let explicit;
   for (let i = 0;i < argv.length; i++) {
@@ -1659,6 +1752,8 @@ var processIo = {
 };
 var camel = (s) => s.replace(/-([a-z])/g, (_, c) => c.toUpperCase());
 function assertKnownArgs(declared, args) {
+  if ("format" in declared)
+    assertValidFormat(args.format);
   const known = new Set(["_"]);
   let positionals = 0;
   for (const [name, def] of Object.entries(declared)) {
@@ -1891,6 +1986,7 @@ var hr = defineCollection({
   conflict: "ignore",
   rangeParams: "datetime",
   maxRangeDays: 30,
+  syncLookbackDays: 14,
   identity: [{ field: "timestamp", format: "date-time", description: "ISO 8601 timestamp of the sample" }],
   columns: [
     { name: "timestamp", type: "TEXT", pick: (r) => r.timestamp },
@@ -2028,6 +2124,192 @@ var cvAge = defineCollection({
   ]
 });
 
+// src/collections/resilience.ts
+var resilience = defineCollection({
+  name: "resilience",
+  endpoint: "daily_resilience",
+  table: "daily_resilience",
+  description: "Daily resilience level with its sleep-recovery, daytime-recovery and stress contributors",
+  conflict: "replace",
+  rangeParams: "date",
+  identity: [
+    { field: "id", description: "Oura record id" },
+    { field: "day", format: "date", description: "Date the record applies to (YYYY-MM-DD)" }
+  ],
+  columns: [
+    { name: "id", type: "TEXT", pk: true, pick: (r) => r.id },
+    { name: "day", type: "TEXT", unique: true, pick: (r) => r.day },
+    { name: "level", type: "TEXT", pick: (r) => r.level ?? null },
+    { name: "sleep_recovery", type: "REAL", pick: (r) => r.contributors?.sleep_recovery ?? null },
+    { name: "daytime_recovery", type: "REAL", pick: (r) => r.contributors?.daytime_recovery ?? null },
+    { name: "stress", type: "REAL", pick: (r) => r.contributors?.stress ?? null }
+  ]
+});
+
+// src/collections/vo2max.ts
+var vo2max = defineCollection({
+  name: "vo2max",
+  endpoint: "vO2_max",
+  table: "vo2max",
+  description: "Daily VO2 max estimate",
+  conflict: "replace",
+  rangeParams: "date",
+  dayRangeOffset: [0, 1],
+  identity: [
+    { field: "id", description: "Oura record id" },
+    { field: "day", format: "date", description: "Date the record applies to (YYYY-MM-DD)" }
+  ],
+  columns: [
+    { name: "id", type: "TEXT", pk: true, pick: (r) => r.id },
+    { name: "day", type: "TEXT", unique: true, pick: (r) => r.day },
+    { name: "vo2_max", type: "REAL", pick: (r) => r.vo2_max ?? null },
+    { name: "timestamp", type: "TEXT", pick: (r) => r.timestamp }
+  ]
+});
+
+// src/collections/sleep-time.ts
+var sleepTime = defineCollection({
+  name: "sleep-time",
+  endpoint: "sleep_time",
+  table: "sleep_time",
+  description: "Suggested bedtime window (offsets in seconds from midnight) with status and recommendation",
+  conflict: "replace",
+  rangeParams: "date",
+  identity: [
+    { field: "id", description: "Oura record id" },
+    { field: "day", format: "date", description: "Date the record applies to (YYYY-MM-DD)" }
+  ],
+  columns: [
+    { name: "id", type: "TEXT", pk: true, pick: (r) => r.id },
+    { name: "day", type: "TEXT", unique: true, pick: (r) => r.day },
+    { name: "status", type: "TEXT", pick: (r) => r.status ?? null },
+    { name: "recommendation", type: "TEXT", pick: (r) => r.recommendation ?? null },
+    { name: "bedtime_start_offset", type: "INTEGER", pick: (r) => r.optimal_bedtime?.start_offset ?? null },
+    { name: "bedtime_end_offset", type: "INTEGER", pick: (r) => r.optimal_bedtime?.end_offset ?? null },
+    { name: "day_tz", type: "INTEGER", pick: (r) => r.optimal_bedtime?.day_tz ?? null }
+  ]
+});
+
+// src/collections/session.ts
+var session = defineCollection({
+  name: "session",
+  endpoint: "session",
+  table: "sessions",
+  description: "Guided sessions (meditation, breathing, naps, rest) with their sample series as JSON",
+  conflict: "replace",
+  rangeParams: "date",
+  dayRangeOffset: [0, 1],
+  identity: [
+    { field: "id", description: "Oura record id" },
+    { field: "day", format: "date", description: "Date the session belongs to (YYYY-MM-DD)" }
+  ],
+  columns: [
+    { name: "id", type: "TEXT", pk: true, pick: (r) => r.id },
+    { name: "day", type: "TEXT", pick: (r) => r.day },
+    { name: "type", type: "TEXT", pick: (r) => r.type ?? null },
+    { name: "mood", type: "TEXT", pick: (r) => r.mood ?? null },
+    { name: "start_datetime", type: "TEXT", pick: (r) => r.start_datetime },
+    { name: "end_datetime", type: "TEXT", pick: (r) => r.end_datetime },
+    { name: "heart_rate", type: "TEXT", pick: (r) => r.heart_rate == null ? null : JSON.stringify(r.heart_rate) },
+    { name: "heart_rate_variability", type: "TEXT", pick: (r) => r.heart_rate_variability == null ? null : JSON.stringify(r.heart_rate_variability) },
+    { name: "motion_count", type: "TEXT", pick: (r) => r.motion_count == null ? null : JSON.stringify(r.motion_count) }
+  ],
+  indexes: [{ name: "idx_sessions_day", columns: ["day"] }]
+});
+
+// src/collections/rest-mode.ts
+var restMode = defineCollection({
+  name: "rest-mode",
+  endpoint: "rest_mode_period",
+  table: "rest_mode_periods",
+  description: "Rest mode periods; `day` is the period start day, episodes are kept as JSON",
+  conflict: "replace",
+  rangeParams: "date",
+  dayRangeOffset: [0, 1],
+  identity: [
+    { field: "id", description: "Oura record id" },
+    { field: "start_day", format: "date", description: "First day of the period (YYYY-MM-DD)" }
+  ],
+  columns: [
+    { name: "id", type: "TEXT", pk: true, pick: (r) => r.id },
+    { name: "day", type: "TEXT", pick: (r) => r.start_day },
+    { name: "end_day", type: "TEXT", pick: (r) => r.end_day ?? null },
+    { name: "start_time", type: "TEXT", pick: (r) => r.start_time ?? null },
+    { name: "end_time", type: "TEXT", pick: (r) => r.end_time ?? null },
+    { name: "episodes", type: "TEXT", pick: (r) => r.episodes == null ? null : JSON.stringify(r.episodes) }
+  ],
+  indexes: [{ name: "idx_rest_mode_periods_day", columns: ["day"] }]
+});
+
+// src/collections/tags.ts
+var tags = defineCollection({
+  name: "tags",
+  endpoint: "enhanced_tag",
+  table: "enhanced_tags",
+  description: "Tags the user added in the app; `day` is the tag start day",
+  conflict: "replace",
+  rangeParams: "date",
+  dayRangeOffset: [0, 1],
+  identity: [
+    { field: "id", description: "Oura record id" },
+    { field: "start_day", format: "date", description: "Day the tag starts on (YYYY-MM-DD)" }
+  ],
+  columns: [
+    { name: "id", type: "TEXT", pk: true, pick: (r) => r.id },
+    { name: "day", type: "TEXT", pick: (r) => r.start_day },
+    { name: "end_day", type: "TEXT", pick: (r) => r.end_day ?? null },
+    { name: "start_time", type: "TEXT", pick: (r) => r.start_time ?? null },
+    { name: "end_time", type: "TEXT", pick: (r) => r.end_time ?? null },
+    { name: "tag_type_code", type: "TEXT", pick: (r) => r.tag_type_code ?? null },
+    { name: "comment", type: "TEXT", pick: (r) => r.comment ?? null },
+    { name: "custom_name", type: "TEXT", pick: (r) => r.custom_name ?? null }
+  ],
+  indexes: [{ name: "idx_enhanced_tags_day", columns: ["day"] }]
+});
+
+// src/collections/ring.ts
+var ring = defineCollection({
+  name: "ring",
+  endpoint: "ring_configuration",
+  table: "ring_configuration",
+  description: "Ring hardware, colour, size, firmware and set-up time; a snapshot list, not a day range",
+  conflict: "replace",
+  rangeParams: "none",
+  identity: [{ field: "id", description: "Oura ring id" }],
+  columns: [
+    { name: "id", type: "TEXT", pk: true, pick: (r) => r.id },
+    { name: "color", type: "TEXT", pick: (r) => r.color ?? null },
+    { name: "design", type: "TEXT", pick: (r) => r.design ?? null },
+    { name: "firmware_version", type: "TEXT", pick: (r) => r.firmware_version ?? null },
+    { name: "hardware_type", type: "TEXT", pick: (r) => r.hardware_type ?? null },
+    { name: "set_up_at", type: "TEXT", pick: (r) => r.set_up_at ?? null },
+    { name: "size", type: "INTEGER", pick: (r) => r.size ?? null }
+  ]
+});
+
+// src/collections/battery.ts
+var battery = defineCollection({
+  name: "battery",
+  endpoint: "ring_battery_level",
+  table: "ring_battery_level",
+  description: "Ring battery level events (percent) with charging state",
+  conflict: "ignore",
+  rangeParams: "datetime",
+  maxRangeDays: 30,
+  identity: [{ field: "timestamp", format: "date-time", description: "ISO 8601 timestamp of the event" }],
+  columns: [
+    { name: "timestamp", type: "TEXT", pick: (r) => r.timestamp },
+    { name: "level", type: "INTEGER", pick: (r) => r.level ?? null },
+    { name: "charging", type: "INTEGER", pick: (r) => r.charging == null ? null : r.charging ? 1 : 0 },
+    { name: "in_charger", type: "INTEGER", pick: (r) => r.in_charger == null ? null : r.in_charger ? 1 : 0 },
+    { name: "day", type: "TEXT", pick: (r) => r.timestamp.slice(0, 10) }
+  ],
+  indexes: [
+    { name: "idx_ring_battery_level_unique", columns: ["timestamp"], unique: true },
+    { name: "idx_ring_battery_level_day", columns: ["day"] }
+  ]
+});
+
 // src/collections/index.ts
 var COLLECTIONS = [
   sleep,
@@ -2038,7 +2320,15 @@ var COLLECTIONS = [
   stress,
   workout,
   sleepPeriods,
-  cvAge
+  cvAge,
+  resilience,
+  vo2max,
+  sleepTime,
+  session,
+  restMode,
+  tags,
+  ring,
+  battery
 ];
 function names() {
   return COLLECTIONS.map((c) => c.name);
@@ -2078,6 +2368,8 @@ function datetimeQueries(start, end, tz, maxDays) {
   return out;
 }
 function rangeQueries(c, start, end, tz) {
+  if (c.rangeParams === "none")
+    return [{}];
   if (start > end)
     return [];
   return c.rangeParams === "date" ? dateQueries(start, end, c.maxRangeDays, c.dayRangeOffset ?? [0, 0]) : datetimeQueries(start, end, tz, c.maxRangeDays);
@@ -2092,7 +2384,7 @@ async function fetchCollection(client, c, start, end, tz) {
 }
 
 // src/commands/describe.ts
-var OUTPUT_SCHEMAS = { doctor: "docs/schemas/doctor.json" };
+var OUTPUT_SCHEMAS = { doctor: "docs/schemas/doctor.json", describe: "docs/schemas/describe.json" };
 var ENUM_ARGS = {
   fetch: { collection: names() },
   report: { period: ["week", "month"] }
@@ -2192,8 +2484,8 @@ function describeCommand(version, getCommands) {
 
 // src/db/sync.ts
 var BACKFILL_DAYS = 30;
-function lastDay(db, table) {
-  return db.query(`SELECT MAX(day) AS d FROM ${table}`).get().d;
+function lastDay(db, table, end) {
+  return db.query(`SELECT MAX(day) AS d FROM ${table} WHERE day <= ?`).get(end).d;
 }
 function rowCount(db, table) {
   return db.query(`SELECT COUNT(*) AS n FROM ${table}`).get().n;
@@ -2204,26 +2496,44 @@ async function importDaily(db, client, clock, log, window = {}) {
   const end = window.to ?? today;
   const backfillStart = shiftDay(end, -(BACKFILL_DAYS - 1));
   const plan = COLLECTIONS.map((c) => {
-    const last = lastDay(db, c.table);
-    return { c, last, start: window.from ?? last ?? backfillStart };
+    const last = c.rangeParams === "none" ? null : lastDay(db, c.table, end);
+    const resume = window.from ?? last ?? backfillStart;
+    const start = window.from ?? shiftDay(resume, -(last === null ? 0 : c.syncLookbackDays ?? 0));
+    return { c, last, resume, start };
   });
-  const isFirstSync = plan.every((p) => p.last === null);
-  const startDate = plan.map((p) => p.start).sort()[0];
+  const ranged = plan.filter((p) => p.c.rangeParams !== "none");
+  const isFirstSync = ranged.every((p) => p.last === null);
+  const startDate = ranged.map((p) => p.resume).sort()[0];
   _log(isFirstSync && window.from === undefined ? `First sync \u2014 backfilling the last ${BACKFILL_DAYS} days: ${startDate} \u2192 ${end}` : `Syncing ${startDate} \u2192 ${end}`);
   const fetched = {};
   const added = {};
   for (const { c, start } of plan) {
     const rows = await fetchCollection(client, c, start, end, tz);
-    const before = rowCount(db, c.table);
     const stmt = db.query(insertSql(c));
+    if (c.rangeParams === "none") {
+      const pk = c.columns.find((col) => col.pk)?.name;
+      if (!pk)
+        throw new Error(`Snapshot collection ${c.name} must declare a primary-key column (enforced by the registry tests).`);
+      const ids = () => new Set(db.query(`SELECT ${pk} AS id FROM ${c.table}`).all().map((r) => r.id));
+      const known = ids();
+      db.transaction((rs) => {
+        db.exec(`DELETE FROM ${c.table}`);
+        for (const r of rs)
+          stmt.run(...rowValues(c, r));
+      })(rows);
+      fetched[c.table] = rows.length;
+      added[c.table] = [...ids()].filter((id) => !known.has(id)).length;
+      _log(`  + ${c.name} (${c.table}): ${rows.length} fetched, ${added[c.table]} new${rows.length === 0 ? ", table cleared" : ""}`);
+      continue;
+    }
+    const before = rowCount(db, c.table);
     db.transaction((rs) => {
       for (const r of rs)
         stmt.run(...rowValues(c, r));
     })(rows);
     fetched[c.table] = rows.length;
     added[c.table] = rowCount(db, c.table) - before;
-    if (rows.length > 0)
-      _log(`  + ${c.table}: ${rows.length} fetched, ${added[c.table]} new`);
+    _log(`  + ${c.name} (${c.table}): ${rows.length} fetched, ${added[c.table]} new`);
   }
   _log("Import complete.");
   return { startDate, endDate: end, fetched, added, isFirstSync };
@@ -2255,7 +2565,7 @@ function getDaySummary(db, day) {
   };
 }
 function getTrends(db, days, today) {
-  const start = shiftDay(today, -days);
+  const start = shiftDay(today, -(days - 1));
   const results = [];
   const metrics = [
     ["Sleep Score", "daily_sleep", "score"],
@@ -2298,6 +2608,27 @@ function getStats(db, today) {
 
 // src/render/format.ts
 init_source();
+
+// src/lib/pad.ts
+var ANSI = /\u001B\[[0-9;]*m/g;
+function visibleWidth(text) {
+  return text.replace(ANSI, "").length;
+}
+function padLeft(text, width) {
+  const gap = width - visibleWidth(text);
+  return gap > 0 ? " ".repeat(gap) + text : text;
+}
+function padRight(text, width) {
+  const gap = width - visibleWidth(text);
+  return gap > 0 ? text + " ".repeat(gap) : text;
+}
+
+// src/lib/terminal.ts
+function terminalWidth() {
+  return process.stdout.isTTY && process.stdout.columns ? process.stdout.columns : 80;
+}
+
+// src/render/format.ts
 function scoreColor(score) {
   if (score === null)
     return source_default.gray("\u2014");
@@ -2351,13 +2682,35 @@ function formatDaySummary(summary, format, emptyHint) {
   return lines.join(`
 `);
 }
-function formatImportSummary(result) {
-  const n = (table) => `${result.fetched[table] ?? 0} (+${result.added[table] ?? 0})`;
-  return [
-    `  Fetched ${result.startDate} \u2192 ${result.endDate}, rows fetched (+new):`,
-    `    sleep ${n("daily_sleep")}   readiness ${n("daily_readiness")}   activity ${n("daily_activity")}   sleep periods ${n("sleep_model")}`,
-    `    spo2 ${n("daily_spo2")}   stress ${n("daily_stress")}   workouts ${n("workouts")}   heart rate ${n("heartrate")}   cardiovascular age ${n("cardiovascular_age")}`
-  ].join(`
+var SUMMARY_INDENT = 4;
+var SUMMARY_GAP = 2;
+var SUMMARY_MAX_COLUMNS = 4;
+function columnsThatFit(cellWidth, width) {
+  const fits = Math.floor((width - SUMMARY_INDENT + SUMMARY_GAP) / (cellWidth + SUMMARY_GAP));
+  return Math.max(1, Math.min(SUMMARY_MAX_COLUMNS, fits));
+}
+function rowsOf(cells, columns) {
+  const rows = [];
+  for (let i = 0;i < cells.length; i += columns) {
+    rows.push(" ".repeat(SUMMARY_INDENT) + cells.slice(i, i + columns).join(" ".repeat(SUMMARY_GAP)).trimEnd());
+  }
+  return rows;
+}
+function formatImportSummary(result, width = terminalWidth()) {
+  const counts = COLLECTIONS.map((c) => ({
+    name: c.name,
+    fetched: String(result.fetched[c.table] ?? 0),
+    added: String(result.added[c.table] ?? 0)
+  }));
+  const nameW = Math.max(...counts.map((c) => visibleWidth(c.name)));
+  const fetchedW = Math.max(...counts.map((c) => visibleWidth(c.fetched)));
+  const aligned = counts.map((c) => `${padRight(c.name, nameW)} ${padLeft(c.fetched, fetchedW)} (+${c.added})`);
+  const bare = counts.map((c) => `${c.name} ${c.fetched} (+${c.added})`);
+  const cellW = Math.max(...aligned.map(visibleWidth));
+  const columns = columnsThatFit(cellW, width);
+  const cells = columns === 1 ? bare : aligned.map((c) => padRight(c, cellW));
+  const head = `  Fetched ${result.startDate} \u2192 ${result.endDate}, rows fetched (+new):`;
+  return [head, ...rowsOf(cells, columns)].join(`
 `);
 }
 function formatWeekTable(days, format, emptyHint) {
@@ -2373,7 +2726,7 @@ function formatWeekTable(days, format, emptyHint) {
   }
   const header = `${"Day".padEnd(12)} ${"Sleep".padStart(6)} ${"Ready".padStart(6)} ${"Activity".padStart(9)} ${"Steps".padStart(7)} ${"Stress".padEnd(10)}`;
   const sep = source_default.gray("\u2500".repeat(56));
-  const rows = days.map((d) => `${d.day.padEnd(12)} ${scoreColor(d.sleep_score).padStart(6)} ${scoreColor(d.readiness_score).padStart(6)} ` + `${scoreColor(d.activity_score).padStart(9)} ${String(d.steps ?? "\u2014").padStart(7)} ${(d.stress ?? "\u2014").padEnd(10)}`);
+  const rows = days.map((d) => `${padRight(d.day, 12)} ${padLeft(scoreColor(d.sleep_score), 6)} ${padLeft(scoreColor(d.readiness_score), 6)} ` + `${padLeft(scoreColor(d.activity_score), 9)} ${padLeft(String(d.steps ?? "\u2014"), 7)} ${padRight(d.stress ?? "\u2014", 10)}`);
   return [`
   Last 7 Days`, sep, `  ${header}`, sep, ...rows.map((r) => `  ${r}`)].join(`
 `);
@@ -2422,13 +2775,17 @@ function formatStats(stats, format) {
 }
 
 // src/commands/sync.ts
-function resolveWindow(opts) {
+function resolveWindow(opts, today) {
   if (opts.to !== undefined && opts.from === undefined)
     throw new CliError("BAD_ARGS", "--to requires --from.");
   const from = opts.from === undefined ? undefined : assertCalendarDate(opts.from, "--from");
   const to = opts.to === undefined ? undefined : assertCalendarDate(opts.to, "--to");
   if (from !== undefined && to !== undefined && from > to)
     throw new CliError("BAD_ARGS", `--from (${from}) must not be after --to (${to}).`);
+  const end = to ?? today;
+  if (from !== undefined && from > end) {
+    throw new CliError("BAD_ARGS", `--from (${from}) is after the end of the window (${end}).`, "Pass --to as well to sync a window that ends in the future.");
+  }
   return { from, to };
 }
 async function runSync(ctx, window = {}) {
@@ -2449,7 +2806,7 @@ var syncCommand = dataCommand({
     to: { type: "string", description: "End of the explicit window (YYYY-MM-DD, default: today); requires --from" }
   },
   needs: { db: true, client: true },
-  run: (ctx, args) => runSync(ctx, resolveWindow({ from: args.from, to: args.to }))
+  run: (ctx, args) => runSync(ctx, resolveWindow({ from: args.from, to: args.to }, ctx.today))
 });
 
 // src/commands/db.ts
@@ -2519,9 +2876,14 @@ function getReport(db, days, today) {
   const weekStart = shiftDay(today, -(days - 1));
   const prevWeekEnd = shiftDay(today, -days);
   const prevWeekStart = shiftDay(today, -(days * 2 - 1));
+  const windowDays = daysBack(today, days);
+  const lastUpload = db.query("SELECT MAX(timestamp) AS t FROM heartrate").get().t;
+  const newestActivityDay = db.query("SELECT MAX(day) AS d FROM daily_activity").get().d;
+  const isComplete = (d) => d < today && newestActivityDay !== null && newestActivityDay > d;
+  const completeThrough = [...windowDays].reverse().find(isComplete) ?? null;
+  const activityEnd = completeThrough ?? shiftDay(weekStart, -1);
   const dailyRows = [];
-  for (let i = days - 1;i >= 0; i--) {
-    const d = shiftDay(today, -i);
+  for (const d of windowDays) {
     const sl = db.query("SELECT score FROM daily_sleep WHERE day=?").get(d);
     const rd = db.query("SELECT score FROM daily_readiness WHERE day=?").get(d);
     const ac = db.query("SELECT score, steps FROM daily_activity WHERE day=?").get(d);
@@ -2531,7 +2893,8 @@ function getReport(db, days, today) {
       sleep: sl?.score ?? null,
       readiness: rd?.score ?? null,
       activity: ac?.score ?? null,
-      steps: ac?.steps ?? null
+      steps: ac?.steps ?? null,
+      partial: ac != null && !isComplete(d)
     });
   }
   const metrics = [
@@ -2542,7 +2905,8 @@ function getReport(db, days, today) {
   ];
   const averages = [];
   for (const [label, table, col, isSteps] of metrics) {
-    const curr = db.query(`SELECT AVG(${col}) as avg, MIN(${col}) as min, MAX(${col}) as max, COUNT(${col}) as cnt FROM ${table} WHERE day BETWEEN ? AND ?`).get(weekStart, weekEnd);
+    const end = table === "daily_activity" ? activityEnd : weekEnd;
+    const curr = db.query(`SELECT AVG(${col}) as avg, MIN(${col}) as min, MAX(${col}) as max, COUNT(${col}) as cnt FROM ${table} WHERE day BETWEEN ? AND ?`).get(weekStart, end);
     const prev = db.query(`SELECT AVG(${col}) as avg FROM ${table} WHERE day BETWEEN ? AND ?`).get(prevWeekStart, prevWeekEnd);
     if (curr.cnt > 0 && curr.avg !== null) {
       const diff = prev.avg !== null ? curr.avg - prev.avg : null;
@@ -2551,6 +2915,7 @@ function getReport(db, days, today) {
         avg: curr.avg,
         min: curr.min,
         max: curr.max,
+        count: curr.cnt,
         prevAvg: prev.avg,
         diff,
         isSteps
@@ -2561,7 +2926,7 @@ function getReport(db, days, today) {
   const spo2 = sp.cnt > 0 && sp.avg !== null ? { avg: +sp.avg.toFixed(1), min: +sp.min.toFixed(1), max: +sp.max.toFixed(1) } : null;
   const lowSleep = db.query("SELECT day, score FROM daily_sleep WHERE day BETWEEN ? AND ? AND score < 70 ORDER BY score").all(weekStart, weekEnd).map((r) => ({ ...r, dayLabel: dayLabel(r.day) }));
   const lowReadiness = db.query("SELECT day, score FROM daily_readiness WHERE day BETWEEN ? AND ? AND score < 70 ORDER BY score").all(weekStart, weekEnd).map((r) => ({ ...r, dayLabel: dayLabel(r.day) }));
-  const highActivity = db.query("SELECT day, score, steps FROM daily_activity WHERE day BETWEEN ? AND ? AND score >= 90 ORDER BY score DESC").all(weekStart, weekEnd).map((r) => ({ ...r, dayLabel: dayLabel(r.day) }));
+  const highActivity = db.query("SELECT day, score, steps FROM daily_activity WHERE day BETWEEN ? AND ? AND score >= 90 ORDER BY score DESC").all(weekStart, activityEnd).map((r) => ({ ...r, dayLabel: dayLabel(r.day) }));
   const sd = db.query(`SELECT AVG(total_sleep_duration) as totalSleep, AVG(deep_sleep_duration) as deepSleep,
             AVG(rem_sleep_duration) as remSleep, AVG(light_sleep_duration) as lightSleep,
             AVG(efficiency) as efficiency, AVG(average_hrv) as hrv, AVG(lowest_heart_rate) as lowestHr
@@ -2570,7 +2935,7 @@ function getReport(db, days, today) {
   const recommendations = [];
   const avgSleep = db.query("SELECT AVG(score) as avg FROM daily_sleep WHERE day BETWEEN ? AND ?").get(weekStart, weekEnd);
   const avgReady = db.query("SELECT AVG(score) as avg FROM daily_readiness WHERE day BETWEEN ? AND ?").get(weekStart, weekEnd);
-  const avgSteps = db.query("SELECT AVG(steps) as avg FROM daily_activity WHERE day BETWEEN ? AND ?").get(weekStart, weekEnd);
+  const avgSteps = db.query("SELECT AVG(steps) as avg FROM daily_activity WHERE day BETWEEN ? AND ?").get(weekStart, activityEnd);
   if (avgSleep.avg !== null && avgSleep.avg < 75) {
     recommendations.push("sleep_low");
   } else if (avgSleep.avg !== null && avgSleep.avg >= 85) {
@@ -2586,7 +2951,7 @@ function getReport(db, days, today) {
   } else if (avgSteps.avg !== null && avgSteps.avg >= 1e4) {
     recommendations.push("steps_great");
   }
-  return { period, weekStart, weekEnd, days: dailyRows, averages, spo2, patterns: { lowSleep, lowReadiness, highActivity }, sleepDetails, recommendations };
+  return { period, weekStart, weekEnd, days: dailyRows, completeThrough, lastUpload, averages, spo2, patterns: { lowSleep, lowReadiness, highActivity }, sleepDetails, recommendations };
 }
 
 // src/render/format-report.ts
@@ -2600,13 +2965,13 @@ function colorizeScore(n) {
 }
 function scoreCell(n, width) {
   if (n === null)
-    return source_default.gray("\u2014".padStart(width));
-  return colorizeScore(n)(String(n).padStart(width));
+    return padLeft(source_default.gray("\u2014"), width);
+  return padLeft(colorizeScore(n)(String(n)), width);
 }
 function stepsCell(n, width) {
   if (n === null)
-    return source_default.gray("\u2014".padStart(width));
-  return n.toLocaleString().padStart(width);
+    return padLeft(source_default.gray("\u2014"), width);
+  return padLeft(n.toLocaleString(), width);
 }
 function fmtSeconds(s) {
   if (s === null)
@@ -2642,11 +3007,20 @@ function bucketDaysIntoWeeks(days) {
       avgSleep: sleepVals.length > 0 ? sleepVals.reduce((a, b) => a + b, 0) / sleepVals.length : null,
       avgReadiness: readinessVals.length > 0 ? readinessVals.reduce((a, b) => a + b, 0) / readinessVals.length : null,
       avgActivity: activityVals.length > 0 ? activityVals.reduce((a, b) => a + b, 0) / activityVals.length : null,
-      totalSteps: stepsVals.length > 0 ? stepsVals.reduce((a, b) => a + b, 0) : null
+      totalSteps: stepsVals.length > 0 ? stepsVals.reduce((a, b) => a + b, 0) : null,
+      partial: chunk.some((d) => d.partial)
     });
   }
   return buckets;
 }
+function partialDayNote(data) {
+  const partial = data.days.find((d) => d.partial);
+  if (!partial)
+    return null;
+  const which = partial.day === data.weekEnd ? "today" : partial.dayLabel;
+  const covers = data.completeThrough ? `through ${data.completeThrough}` : "no complete day yet";
+  return `  * ${which} is still accumulating; activity averages cover ${covers}.`;
+}
 function formatReport(data, format, period) {
   if (format === "json")
     return JSON.stringify(data, null, 2);
@@ -2658,6 +3032,9 @@ function formatReport(data, format, period) {
     lines.push(source_default.bold("  Oura Monthly Report"));
   }
   lines.push(source_default.gray(`  ${data.weekStart} \u2014 ${data.weekEnd}`));
+  const note = partialDayNote(data);
+  if (note)
+    lines.push(source_default.yellow(note));
   lines.push("");
   const hasReportData = data.days.some((day) => day.sleep !== null || day.readiness !== null || day.activity !== null || day.steps !== null) || data.averages.length > 0 || data.spo2 !== null || data.sleepDetails !== null;
   if (!hasReportData) {
@@ -2673,7 +3050,7 @@ function formatReport(data, format, period) {
     lines.push(`  ${"Day".padEnd(10)} ${"Sleep".padStart(6)} ${"Ready".padStart(6)} ${"Active".padStart(7)} ${"Steps".padStart(8)}`);
     lines.push(source_default.gray("  " + "\u2500".repeat(52)));
     for (const d of data.days) {
-      lines.push(`  ${d.dayLabel.padEnd(10)} ${scoreCell(d.sleep, 6)} ${scoreCell(d.readiness, 6)} ${scoreCell(d.activity, 7)} ${stepsCell(d.steps, 8)}`);
+      lines.push(`  ${(d.partial ? d.dayLabel + "*" : d.dayLabel).padEnd(10)} ${scoreCell(d.sleep, 6)} ${scoreCell(d.readiness, 6)} ${scoreCell(d.activity, 7)} ${stepsCell(d.steps, 8)}`);
     }
     lines.push("");
   } else {
@@ -2686,7 +3063,7 @@ function formatReport(data, format, period) {
       const avgSleepInt = b.avgSleep !== null ? Math.round(b.avgSleep) : null;
       const avgReadyInt = b.avgReadiness !== null ? Math.round(b.avgReadiness) : null;
       const avgActiveInt = b.avgActivity !== null ? Math.round(b.avgActivity) : null;
-      lines.push(`  ${b.weekOf.padEnd(12)} ${scoreCell(avgSleepInt, 6)} ${scoreCell(avgReadyInt, 6)} ${scoreCell(avgActiveInt, 7)} ${stepsCell(b.totalSteps, 10)}`);
+      lines.push(`  ${(b.partial ? b.weekOf + "*" : b.weekOf).padEnd(12)} ${scoreCell(avgSleepInt, 6)} ${scoreCell(avgReadyInt, 6)} ${scoreCell(avgActiveInt, 7)} ${stepsCell(b.totalSteps, 10)}`);
     }
     lines.push("");
   }
@@ -2755,7 +3132,7 @@ var reportCommand = dataCommand({
 // src/commands/healthcheck.ts
 function healthcheckCommand(version) {
   return defineCommand({
-    meta: { name: "healthcheck", description: "Quick local DB health probe (JSON: {ok, version, latencyMs})." },
+    meta: { name: "healthcheck", description: "Quick local DB health probe (JSON: {ok, version, latencyMs}, plus error when ok is false)." },
     args: { ...commonArgs },
     run({ args }) {
       assertKnownArgs(commonArgs, args);
@@ -2874,28 +3251,34 @@ function exitCodeForChecks(checks) {
     return exitCodeFor(new CliError("TOKEN_MISSING", fail.detail));
   return exitCodeFor(new CliError("DB_ERROR", fail.detail));
 }
+async function runDoctor(ctx, args) {
+  const dbPath = getDbPath(args.db);
+  const deps = {
+    resolveToken: () => resolveToken(args.token),
+    openDb: () => {
+      const db = openDatabase(args.db);
+      ensureSchema(db);
+      return { db, path: dbPath };
+    },
+    createClient: (token) => new OuraClient({ token }),
+    offline: args.offline === true,
+    today: ctx.today
+  };
+  const result = await runChecks(deps);
+  return {
+    json: result,
+    text: () => formatDoctorTable(result),
+    exitCode: exitCodeForChecks(result.checks)
+  };
+}
 var doctorCommand = dataCommand({
   meta: { name: "doctor", description: "Diagnose token, database, and sync health, and suggest the next step." },
   args: { offline: { type: "boolean", default: false, description: "Skip the live Oura API token-validation call" } },
-  async run(ctx, args) {
-    const deps = {
-      resolveToken: () => resolveToken(args.token),
-      openDb: () => {
-        const db = openDatabase(args.db);
-        ensureSchema(db);
-        return { db, path: getDbPath(args.db) };
-      },
-      createClient: (token) => new OuraClient({ token }),
-      offline: args.offline === true,
-      today: ctx.today
-    };
-    const result = await runChecks(deps);
-    return {
-      json: result,
-      text: () => formatDoctorTable(result),
-      exitCode: exitCodeForChecks(result.checks)
-    };
-  }
+  run: (ctx, args) => runDoctor(ctx, {
+    db: args.db,
+    token: args.token,
+    offline: args.offline === true
+  })
 });
 
 // src/commands/manifest.ts
@@ -2919,7 +3302,7 @@ function buildOpenclawManifest(version, commands) {
       examples: EXAMPLES[c.name] ?? [`oura-cli ${c.name}`]
     })),
     envVars: ["OURA_TOKEN", "OURA_TOKEN_PATH", "OURA_DB_PATH", "OURA_TZ"],
-    healthcheck: { command: "healthcheck", expects: { ok: "boolean", version: "string", latencyMs: "number" } }
+    healthcheck: { command: "healthcheck", expects: { ok: "boolean", version: "string", latencyMs: "number", error: "string, present only when ok is false" } }
   };
 }
 function manifestCommand(version, getCommands) {
@@ -2957,10 +3340,15 @@ function resolveRange(opts) {
   }
   return { start: opts.today, end: opts.today };
 }
+function assertRangeAllowed(c, opts) {
+  if (c.rangeParams === "none" && [opts.day, opts.from, opts.to, opts.days].some((v) => v !== undefined)) {
+    throw new CliError("BAD_ARGS", `"${c.name}" is a snapshot, not a day range; it takes no --day, --from/--to or --days.`);
+  }
+}
 var fetchCommand = dataCommand({
   meta: { name: "fetch", description: "Fetch raw records for one Oura collection straight from the API (JSON)." },
   args: {
-    collection: { type: "positional", required: true, description: `Collection: ${names().join(" | ")}` },
+    collection: { type: "positional", required: true, description: `Collection: ${names().join(" | ")} (ring is a snapshot and takes no range flags)` },
     day: { type: "string", description: "Single day (YYYY-MM-DD). Default: today." },
     from: { type: "string", description: "Range start (YYYY-MM-DD); requires --to" },
     to: { type: "string", description: "Range end (YYYY-MM-DD); requires --from" },
@@ -2971,13 +3359,14 @@ var fetchCommand = dataCommand({
     const c = byName(args.collection);
     if (!c)
       throw new CliError("BAD_ARGS", `Unknown collection "${args.collection}".`, `Valid collections: ${names().join(", ")}`);
-    const { start, end } = resolveRange({
+    const opts = {
       day: args.day,
       from: args.from,
       to: args.to,
-      days: args.days,
-      today: ctx.today
-    });
+      days: args.days
+    };
+    assertRangeAllowed(c, opts);
+    const { start, end } = resolveRange({ ...opts, today: ctx.today });
     const client = new OuraClient(args.token ? { token: args.token } : {});
     const data = await fetchCollection(client, c, start, end, ctx.tz);
     return { json: data, text: () => JSON.stringify(data, null, 2) };
@@ -2985,12 +3374,12 @@ var fetchCommand = dataCommand({
 });
 
 // src/lib/citty-error.ts
-var ANSI = /\u001b\[[0-9;]*m/g;
+var ANSI2 = /\u001b\[[0-9;]*m/g;
 function fromCittyError(err, removedCommandHints = {}) {
   const code = err?.code;
   if (typeof code !== "string")
     return err;
-  const message = (err instanceof Error ? err.message : String(err)).replace(ANSI, "");
+  const message = (err instanceof Error ? err.message : String(err)).replace(ANSI2, "");
   switch (code) {
     case "E_UNKNOWN_COMMAND": {
       const name = message.replace(/^Unknown command\s*/, "").trim();
@@ -3008,9 +3397,6 @@ function fromCittyError(err, removedCommandHints = {}) {
 
 // src/index.ts
 var VERSION = JSON.parse(readFileSync2(new URL("../package.json", import.meta.url), "utf-8")).version;
-if (process.argv.includes("--no-color") || process.env.NO_COLOR) {
-  source_default.level = 0;
-}
 var subCommands = Object.assign(Object.create(null), {
   login: loginCommand,
   describe: describeCommand(VERSION, () => subCommands),

package/docs/schemas/battery.json

@@ -0,0 +1,21 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/drakulavich/oura-cli/blob/main/docs/schemas/battery.json",
+  "title": "oura-cli fetch battery output",
+  "description": "Ring battery level events (percent) with charging state",
+  "type": "array",
+  "items": {
+    "type": "object",
+    "additionalProperties": true,
+    "required": [
+      "timestamp"
+    ],
+    "properties": {
+      "timestamp": {
+        "type": "string",
+        "format": "date-time",
+        "description": "ISO 8601 timestamp of the event"
+      }
+    }
+  }
+}

package/docs/schemas/resilience.json

@@ -0,0 +1,26 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/drakulavich/oura-cli/blob/main/docs/schemas/resilience.json",
+  "title": "oura-cli fetch resilience output",
+  "description": "Daily resilience level with its sleep-recovery, daytime-recovery and stress contributors",
+  "type": "array",
+  "items": {
+    "type": "object",
+    "additionalProperties": true,
+    "required": [
+      "id",
+      "day"
+    ],
+    "properties": {
+      "id": {
+        "type": "string",
+        "description": "Oura record id"
+      },
+      "day": {
+        "type": "string",
+        "format": "date",
+        "description": "Date the record applies to (YYYY-MM-DD)"
+      }
+    }
+  }
+}

package/docs/schemas/rest-mode.json

@@ -0,0 +1,26 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/drakulavich/oura-cli/blob/main/docs/schemas/rest-mode.json",
+  "title": "oura-cli fetch rest-mode output",
+  "description": "Rest mode periods; `day` is the period start day, episodes are kept as JSON",
+  "type": "array",
+  "items": {
+    "type": "object",
+    "additionalProperties": true,
+    "required": [
+      "id",
+      "start_day"
+    ],
+    "properties": {
+      "id": {
+        "type": "string",
+        "description": "Oura record id"
+      },
+      "start_day": {
+        "type": "string",
+        "format": "date",
+        "description": "First day of the period (YYYY-MM-DD)"
+      }
+    }
+  }
+}

package/docs/schemas/ring.json

@@ -0,0 +1,20 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/drakulavich/oura-cli/blob/main/docs/schemas/ring.json",
+  "title": "oura-cli fetch ring output",
+  "description": "Ring hardware, colour, size, firmware and set-up time; a snapshot list, not a day range",
+  "type": "array",
+  "items": {
+    "type": "object",
+    "additionalProperties": true,
+    "required": [
+      "id"
+    ],
+    "properties": {
+      "id": {
+        "type": "string",
+        "description": "Oura ring id"
+      }
+    }
+  }
+}

package/docs/schemas/session.json

@@ -0,0 +1,26 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/drakulavich/oura-cli/blob/main/docs/schemas/session.json",
+  "title": "oura-cli fetch session output",
+  "description": "Guided sessions (meditation, breathing, naps, rest) with their sample series as JSON",
+  "type": "array",
+  "items": {
+    "type": "object",
+    "additionalProperties": true,
+    "required": [
+      "id",
+      "day"
+    ],
+    "properties": {
+      "id": {
+        "type": "string",
+        "description": "Oura record id"
+      },
+      "day": {
+        "type": "string",
+        "format": "date",
+        "description": "Date the session belongs to (YYYY-MM-DD)"
+      }
+    }
+  }
+}

package/docs/schemas/sleep-time.json

@@ -0,0 +1,26 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/drakulavich/oura-cli/blob/main/docs/schemas/sleep-time.json",
+  "title": "oura-cli fetch sleep-time output",
+  "description": "Suggested bedtime window (offsets in seconds from midnight) with status and recommendation",
+  "type": "array",
+  "items": {
+    "type": "object",
+    "additionalProperties": true,
+    "required": [
+      "id",
+      "day"
+    ],
+    "properties": {
+      "id": {
+        "type": "string",
+        "description": "Oura record id"
+      },
+      "day": {
+        "type": "string",
+        "format": "date",
+        "description": "Date the record applies to (YYYY-MM-DD)"
+      }
+    }
+  }
+}

package/docs/schemas/tags.json

@@ -0,0 +1,26 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/drakulavich/oura-cli/blob/main/docs/schemas/tags.json",
+  "title": "oura-cli fetch tags output",
+  "description": "Tags the user added in the app; `day` is the tag start day",
+  "type": "array",
+  "items": {
+    "type": "object",
+    "additionalProperties": true,
+    "required": [
+      "id",
+      "start_day"
+    ],
+    "properties": {
+      "id": {
+        "type": "string",
+        "description": "Oura record id"
+      },
+      "start_day": {
+        "type": "string",
+        "format": "date",
+        "description": "Day the tag starts on (YYYY-MM-DD)"
+      }
+    }
+  }
+}

package/docs/schemas/vo2max.json

@@ -0,0 +1,26 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/drakulavich/oura-cli/blob/main/docs/schemas/vo2max.json",
+  "title": "oura-cli fetch vo2max output",
+  "description": "Daily VO2 max estimate",
+  "type": "array",
+  "items": {
+    "type": "object",
+    "additionalProperties": true,
+    "required": [
+      "id",
+      "day"
+    ],
+    "properties": {
+      "id": {
+        "type": "string",
+        "description": "Oura record id"
+      },
+      "day": {
+        "type": "string",
+        "format": "date",
+        "description": "Date the record applies to (YYYY-MM-DD)"
+      }
+    }
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@drakulavich/oura-cli",
-  "version": "0.5.1",
+  "version": "0.6.0",
   "description": "Oura Ring CLI — query and analyze Oura Ring health data from the command line, designed for humans and AI agents.",
   "keywords": [
     "oura",