@drakulavich/oura-cli 0.7.0 → 0.8.0

package/dist/index.js

@@ -1407,6 +1407,12 @@ CREATE TABLE IF NOT EXISTS ring_battery_level (
 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);
     `
+  },
+  {
+    version: 4,
+    sql: `
+ALTER TABLE daily_activity ADD COLUMN class_5_min_slots INTEGER;
+    `
   }
 ];
 
@@ -1528,11 +1534,46 @@ function resolveToken(explicit, tokenPath) {
 
 // src/api/client.ts
 var BASE_URL = "https://api.ouraring.com/v2/usercollection";
+function kindOf(value) {
+  if (value === null)
+    return "null";
+  if (Array.isArray(value))
+    return "an array";
+  return typeof value === "object" ? "an object" : `a ${typeof value}`;
+}
 var MAX_PAGES = 1e4;
+var RETRY_LIMIT = 3;
+var MAX_RETRY_AFTER_MS = 60000;
+var MAX_TOTAL_WAIT_MS = 3 * 60000;
+var BACKOFF_MS = [1000, 2000, 4000];
+function retryDelayMs(retryAfter, attempt, now = Date.now()) {
+  let ms = Number.NaN;
+  if (retryAfter !== null) {
+    const whole = retryAfter.trim();
+    const firstPart = whole.split(",")[0].trim();
+    const firstDate = whole.match(/^[A-Za-z]{3}, [^,]*? GMT/)?.[0] ?? "";
+    const seconds = [whole, firstPart].filter((r) => r !== "").map(Number).find(Number.isFinite);
+    const date = [whole, firstDate, firstPart].map(Date.parse).find(Number.isFinite);
+    if (seconds !== undefined)
+      ms = seconds * 1000;
+    else if (date !== undefined)
+      ms = date - now;
+  }
+  if (!Number.isFinite(ms) || ms <= 0)
+    ms = BACKOFF_MS[Math.min(attempt, BACKOFF_MS.length - 1)];
+  return Math.min(ms, MAX_RETRY_AFTER_MS);
+}
 
 class OuraClient {
   token;
+  onPage;
+  onRetry;
+  sleep;
+  waitedMs = 0;
   constructor(options = {}) {
+    this.onPage = options.onPage;
+    this.onRetry = options.onRetry;
+    this.sleep = options.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
     const { token, source } = resolveToken(options.token, options.tokenPath);
     if (!token) {
       throw new CliError("TOKEN_MISSING", `No Oura access token at ${source}.`, "Run `oura-cli login` or set OURA_TOKEN.");
@@ -1553,7 +1594,8 @@ class OuraClient {
       const params = new URLSearchParams(query);
       if (nextToken)
         params.set("next_token", nextToken);
-      const page = await this.getPage(`${BASE_URL}/${endpoint}?${params}`);
+      const page = await this.getPage(endpoint, `${BASE_URL}/${endpoint}?${params}`);
+      this.onPage?.({ endpoint, rows: page.data.length });
       for (const row of page.data)
         rows.push(row);
       nextToken = page.next_token;
@@ -1565,17 +1607,38 @@ class OuraClient {
     } while (nextToken);
     return rows;
   }
-  async getPage(url) {
-    const response = await fetch(url, {
-      headers: { Authorization: `Bearer ${this.token}` }
-    });
+  async request(url) {
+    try {
+      return await fetch(url, { headers: { Authorization: `Bearer ${this.token}` } });
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      throw new CliError("API_ERROR", `Could not reach the Oura API: ${msg}`, "Check the network connection and try again.");
+    }
+  }
+  async getPage(endpoint, url) {
+    let response = await this.request(url);
+    let retries = 0;
+    for (;response.status === 429 && retries < RETRY_LIMIT; retries++) {
+      const waitMs = retryDelayMs(response.headers.get("retry-after"), retries);
+      if (this.waitedMs + waitMs > MAX_TOTAL_WAIT_MS)
+        break;
+      await response.body?.cancel();
+      this.waitedMs += waitMs;
+      this.onRetry?.({ endpoint, waitMs, attempt: retries });
+      await this.sleep(waitMs);
+      response = await this.request(url);
+    }
     if (!response.ok) {
       const rawBody = await response.text();
-      const redacted = redactSecrets(rawBody);
+      const redacted = redactSecrets(rawBody).split(this.token).join("[REDACTED]");
       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}`, "Run `oura-cli login` with a fresh Personal Access Token, or check OURA_TOKEN.");
       }
+      if (response.status === 429) {
+        const waited = Math.round(this.waitedMs / 1000);
+        throw new CliError("API_ERROR", `Oura API 429: ${body}`, `Rate limited; this page was retried ${retries} time${retries === 1 ? "" : "s"} and the command has waited ${waited} s on 429 answers (the most it will is ${MAX_TOTAL_WAIT_MS / 1000} s). Wait a few minutes and run it again, or ask for a shorter range.`);
+      }
       throw new CliError("API_ERROR", `Oura API ${response.status}: ${body}`);
     }
     let json;
@@ -1585,6 +1648,15 @@ class OuraClient {
       throw new CliError("API_ERROR", "Empty response body from Oura API.");
     }
     const body = json;
+    if (body === null || typeof body !== "object" || Array.isArray(body)) {
+      throw new CliError("API_ERROR", `Oura API returned a malformed body for ${endpoint}: expected an object, got ${kindOf(body)}.`);
+    }
+    if (body.data != null && !Array.isArray(body.data)) {
+      throw new CliError("API_ERROR", `Oura API returned a malformed body for ${endpoint}: expected an array under "data", got ${kindOf(body.data)}.`);
+    }
+    if (body.next_token != null && typeof body.next_token !== "string") {
+      throw new CliError("API_ERROR", `Oura API returned a malformed body for ${endpoint}: expected a string or null under "next_token", got ${kindOf(body.next_token)}.`);
+    }
     return { data: body.data ?? [], next_token: body.next_token ?? null };
   }
 }
@@ -1679,6 +1751,45 @@ function formatFromArgv(argv, isTty) {
   }
 }
 
+// src/lib/progress.ts
+function pageProgress(sink, verb) {
+  let endpoint;
+  let pages = 0;
+  let rows = 0;
+  let widest = 0;
+  let written = false;
+  const show = (text) => {
+    widest = Math.max(widest, text.length);
+    written = true;
+    sink.write(`\r${text}`);
+  };
+  const status = () => pages === 0 ? `  ${verb} ${endpoint}` : `  ${verb} ${endpoint}: page ${pages}, ${rows} rows so far`;
+  return {
+    onPage(page) {
+      if (page.endpoint !== endpoint) {
+        endpoint = page.endpoint;
+        pages = 0;
+        rows = 0;
+      }
+      pages++;
+      rows += page.rows;
+      show(`${status()}\u2026`);
+    },
+    onRetry(retry) {
+      if (retry.endpoint !== endpoint) {
+        endpoint = retry.endpoint;
+        pages = 0;
+        rows = 0;
+      }
+      show(`${status()}; rate limited, retrying in ${Math.ceil(retry.waitMs / 1000)} s\u2026`);
+    },
+    done() {
+      if (written)
+        sink.write(`\r${" ".repeat(widest)}\r`);
+    }
+  };
+}
+
 // src/lib/time.ts
 function nowUtc() {
   return new Date().toISOString().replace(/\.\d{3}Z$/, "Z");
@@ -1788,7 +1899,8 @@ var processIo = {
 `);
   },
   exit: (code) => process.exit(code),
-  isTty: process.stdout.isTTY === true
+  isTty: process.stdout.isTTY === true,
+  progress: process.stderr.isTTY ? process.stderr : undefined
 };
 var camel = (s) => s.replace(/-([a-z])/g, (_, c) => c.toUpperCase());
 function assertKnownArgs(declared, args) {
@@ -1809,7 +1921,7 @@ function assertKnownArgs(declared, args) {
   const unknown = Object.keys(args).filter((k) => !known.has(k));
   if (unknown.length > 0) {
     const flags = unknown.map((f) => f.length === 1 ? `-${f}` : `--${f}`).join(", ");
-    const hint = unknown.every((f) => f.length === 1) ? 'oura-cli has no single-letter flags; a value that starts with "-" must come after "--".' : "Run the command with --help to see its flags.";
+    const hint = unknown.every((f) => f.length === 1) ? 'oura-cli has no single-letter flags other than -v and -h; a value that starts with "-" must come after "--".' : "Run the command with --help to see its flags.";
     throw new CliError("BAD_ARGS", `Unknown flag${unknown.length > 1 ? "s" : ""}: ${flags}.`, hint);
   }
   const extra = (args._ ?? []).slice(positionals);
@@ -1828,16 +1940,25 @@ async function execute(def, args, io = processIo) {
     assertKnownArgs({ ...commonArgs, ...def.args ?? {} }, args);
     const outputFormat = def.jsonOnly ? "json" : format;
     const tz = assertTimezone(args.tz ?? resolveDefaultTimezone());
-    const ctx = { format: outputFormat, tz, today: today(tz) };
+    const ctx = { format: outputFormat, tz, today: today(tz), ...io.progress ? { progress: io.progress } : {} };
     if (def.needs?.db) {
       db = openDatabase(args.db);
       ensureSchema(db);
       ctx.db = db;
     }
+    const progress = def.needs?.client && io.progress ? pageProgress(io.progress, "syncing") : undefined;
     if (def.needs?.client) {
-      ctx.client = new OuraClient(args.token ? { token: args.token } : {});
+      ctx.client = new OuraClient({
+        ...args.token ? { token: args.token } : {},
+        ...progress ? { onPage: progress.onPage, onRetry: progress.onRetry } : {}
+      });
+    }
+    let out;
+    try {
+      out = await def.run(ctx, args);
+    } finally {
+      progress?.done();
     }
-    const out = await def.run(ctx, args);
     io.stdout(outputFormat === "json" ? JSON.stringify(out.json, null, 2) : out.text());
     exitCode = out.exitCode ?? 0;
   } catch (raw) {
@@ -2013,7 +2134,8 @@ var activity = defineCollection({
     { name: "total_calories", type: "INTEGER", pick: (r) => r.total_calories },
     { name: "target_calories", type: "INTEGER", pick: (r) => r.target_calories },
     { name: "contributors", type: "TEXT", pick: (r) => JSON.stringify(r.contributors) },
-    { name: "timestamp", type: "TEXT", pick: (r) => r.timestamp }
+    { name: "timestamp", type: "TEXT", pick: (r) => r.timestamp },
+    { name: "class_5_min_slots", type: "INTEGER", pick: (r) => r.class_5_min?.length ?? null }
   ]
 });
 
@@ -2385,6 +2507,24 @@ function insertSql(c) {
 function rowValues(c, row) {
   return c.columns.map((col) => col.pick(row));
 }
+function identityColumns(c) {
+  const unique = c.columns.filter((col) => col.unique).map((col) => col.name);
+  if (unique.length > 0)
+    return unique;
+  const pk = c.columns.filter((col) => col.pk).map((col) => col.name);
+  if (pk.length > 0)
+    return pk;
+  return (c.indexes ?? []).find((i) => i.unique)?.columns ?? [];
+}
+function hasIdentity(c, row) {
+  if (row == null || typeof row !== "object")
+    return false;
+  return identityColumns(c).every((name) => {
+    const col = c.columns.find((k) => k.name === name);
+    const v = col?.pick(row);
+    return col?.type === "TEXT" ? typeof v === "string" && v !== "" : typeof v === "number" && Number.isFinite(v);
+  });
+}
 var MS_PER_DAY = 86400000;
 function dateQueries(start, end, maxDays, offset) {
   const query = (s, e) => ({ start_date: shiftDay(s, offset[0]), end_date: shiftDay(e, offset[1]) });
@@ -2417,18 +2557,19 @@ function rangeQueries(c, start, end, tz) {
 async function fetchCollectionByPiece(client, c, start, end, tz) {
   const pieces = [];
   for (const query of rangeQueries(c, start, end, tz)) {
-    pieces.push(await client.fetch(c.endpoint, query));
+    pieces.push({ query, rows: await client.fetch(c.endpoint, query) });
   }
   return pieces;
 }
 async function fetchCollection(client, c, start, end, tz) {
-  return (await fetchCollectionByPiece(client, c, start, end, tz)).flat();
+  return (await fetchCollectionByPiece(client, c, start, end, tz)).flatMap((p) => p.rows);
 }
 
 // src/commands/describe.ts
 var OUTPUT_SCHEMAS = { doctor: "docs/schemas/doctor.json", describe: "docs/schemas/describe.json" };
 var ENUM_ARGS = {
   fetch: { collection: names() },
+  rows: { collection: names() },
   report: { period: ["week", "month"] }
 };
 function resolved(def) {
@@ -2525,21 +2666,25 @@ function describeCommand(version, getCommands) {
 }
 
 // src/db/reconcile.ts
-function identityColumns(c) {
-  const unique = c.columns.filter((col) => col.unique).map((col) => col.name);
-  if (unique.length > 0)
-    return unique;
-  const pk = c.columns.filter((col) => col.pk).map((col) => col.name);
-  if (pk.length > 0)
-    return pk;
-  return (c.indexes ?? []).find((i) => i.unique)?.columns ?? [];
-}
 var MAX_REMOVED_SHARE = 0.5;
 var ALWAYS_SAFE_TO_REMOVE = 5;
 var KEY_SEPARATOR = "\x00";
 function emptyPlan() {
   return { added: 0, stale: [], refused: 0, bypassed: 0 };
 }
+function requestedRange(c, query) {
+  if (c.rangeParams === "datetime") {
+    const from = Date.parse(query.start_datetime ?? "");
+    const to = Date.parse(query.end_datetime ?? "");
+    return (value) => {
+      const t = Date.parse(value);
+      return t >= from && t <= to;
+    };
+  }
+  const from = query.start_date;
+  const to = query.end_date;
+  return (value) => from !== undefined && to !== undefined && value >= from && value <= to;
+}
 function keyOf(values) {
   return values.map((v) => String(v)).join(KEY_SEPARATOR);
 }
@@ -2554,12 +2699,13 @@ function planWindow(db, c, pieces, options = {}) {
   if (scopePick === undefined || identityPicks.some((p) => p === undefined))
     return emptyPlan();
   const keyFor = (row) => keyOf(identityPicks.map((pick) => pick(row)));
-  const wanted = new Set(pieces.flat().map(keyFor));
+  const wanted = new Set(pieces.flatMap((p) => p.rows).map(keyFor));
   const plan = emptyPlan();
   const judged = pieces.map((piece) => {
-    if (piece.length === 0)
+    if (piece.rows.length === 0)
       return null;
-    const scopeValues = piece.map((row) => scopePick(row)).filter((v) => v !== null && v !== undefined).map(String);
+    const inRequested = requestedRange(c, piece.query);
+    const scopeValues = piece.rows.map((row) => scopePick(row)).filter((v) => v !== null && v !== undefined).map(String).filter(inRequested);
     if (scopeValues.length === 0)
       return null;
     const days = [...new Set(scopeValues)];
@@ -2575,7 +2721,7 @@ function planWindow(db, c, pieces, options = {}) {
         stale.push(values);
     }
     const looksTruncated = stale.length > ALWAYS_SAFE_TO_REMOVE && stale.length > stored.length * MAX_REMOVED_SHARE;
-    const fresh = [...new Set(piece.map(keyFor))].filter((key) => !storedKeys.has(key));
+    const fresh = [...new Set(piece.rows.map(keyFor))].filter((key) => !storedKeys.has(key));
     return { stale, looksTruncated, fresh };
   });
   const doubted = new Set;
@@ -2655,12 +2801,18 @@ async function importDaily(db, client, clock, log, window = {}, options = {}) {
   const fetched = {};
   const added = {};
   const removed = {};
+  const dropped = {};
   const refused = {};
   const pruned = {};
   const mayPrune = (name) => options.prune === "all" || (options.prune?.includes(name) ?? false);
   for (const { c, start } of plan) {
-    const pieces = await fetchCollectionByPiece(client, c, start, end, tz);
-    const rows = pieces.flat();
+    const returned = await fetchCollectionByPiece(client, c, start, end, tz);
+    const pieces = returned.map((piece) => ({ ...piece, rows: piece.rows.filter((r) => hasIdentity(c, r)) }));
+    const rows = pieces.flatMap((p) => p.rows);
+    const missing = returned.flatMap((p) => p.rows).length - rows.length;
+    if (missing > 0)
+      dropped[c.table] = missing;
+    const droppedTail = missing > 0 ? `, ${missing} dropped (no ${identityColumns(c).join("/")})` : "";
     const stmt = db.query(insertSql(c));
     if (c.rangeParams === "none") {
       const pk = c.columns.find((col) => col.pk)?.name;
@@ -2668,24 +2820,38 @@ async function importDaily(db, client, clock, log, window = {}, options = {}) {
         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" : ""}`);
+      const unstorable = rows.length === 0 && missing > 0;
+      const refuse = rows.length === 0 && known.size > 0 && (unstorable || !mayPrune(c.name));
+      if (!refuse) {
+        db.transaction((rs) => {
+          db.exec(`DELETE FROM ${c.table}`);
+          for (const r of rs)
+            stmt.run(...rowValues(c, r));
+        })(rows);
+      }
+      const now = ids();
+      const gone = [...known].filter((id) => !now.has(id)).length;
+      fetched[c.table] = rows.length + missing;
+      added[c.table] = [...now].filter((id) => !known.has(id)).length;
+      if (gone > 0)
+        removed[c.table] = gone;
+      if (refuse && !unstorable)
+        refused[c.table] = { rows: known.size, collection: c.name };
+      else if (rows.length === 0 && gone > 0)
+        pruned[c.table] = { rows: gone, collection: c.name };
+      const tail = gone > 0 ? `, ${gone} stale removed${pruned[c.table] ? " (past the truncation guard)" : ""}` : "";
+      const kept = !refuse ? "" : unstorable ? `, ${known.size} rows kept: the response held no storable rows` : `, ${known.size} rows kept that the API did not return \u2014 an empty answer describes nothing; re-run with --prune=${c.name} to apply it`;
+      _log(`  + ${c.name} (${c.table}): ${fetched[c.table]} fetched, ${added[c.table]} new${droppedTail}${tail}${kept}`);
       continue;
     }
     const { windowPlan, gone } = db.transaction((ps) => {
       const windowPlan = planWindow(db, c, ps, { prune: mayPrune(c.name) });
       for (const piece of ps)
-        for (const r of piece)
+        for (const r of piece.rows)
           stmt.run(...rowValues(c, r));
       return { windowPlan, gone: applyWindowPlan(db, c, windowPlan) };
     }).immediate(pieces);
-    fetched[c.table] = rows.length;
+    fetched[c.table] = rows.length + missing;
     added[c.table] = windowPlan.added;
     if (gone > 0)
       removed[c.table] = gone;
@@ -2695,7 +2861,7 @@ async function importDaily(db, client, clock, log, window = {}, options = {}) {
       pruned[c.table] = { rows: windowPlan.bypassed, collection: c.name };
     const tail = gone > 0 ? `, ${gone} stale removed${windowPlan.bypassed > 0 ? ` (${windowPlan.bypassed} past the truncation guard)` : ""}` : "";
     const kept = windowPlan.refused > 0 ? `, ${windowPlan.refused} rows kept that the API did not return \u2014 too many to drop on one response; re-run with --prune=${c.name} to apply them` : "";
-    _log(`  + ${c.name} (${c.table}): ${rows.length} fetched, ${added[c.table]} new${tail}${kept}`);
+    _log(`  + ${c.name} (${c.table}): ${fetched[c.table]} fetched, ${added[c.table]} new${droppedTail}${tail}${kept}`);
   }
   _log("Import complete.");
   return {
@@ -2704,6 +2870,7 @@ async function importDaily(db, client, clock, log, window = {}, options = {}) {
     fetched,
     added,
     removed,
+    dropped,
     refused,
     pruned,
     isFirstSync,
@@ -2711,8 +2878,28 @@ async function importDaily(db, client, clock, log, window = {}, options = {}) {
   };
 }
 
+// src/db/day-complete.ts
+var SLOTS_PER_DAY = 288;
+function dayCompleteness(db, today) {
+  const rows = db.query("SELECT day, class_5_min_slots AS slots FROM daily_activity").all();
+  const slotsByDay = new Map(rows.map((r) => [r.day, r.slots]));
+  const daysDesc = rows.map((r) => r.day).sort().reverse();
+  const newestDay = daysDesc[0] ?? null;
+  const isComplete = (day) => {
+    if (!slotsByDay.has(day))
+      return false;
+    if ((slotsByDay.get(day) ?? 0) >= SLOTS_PER_DAY)
+      return true;
+    return day < today && newestDay !== null && newestDay > day;
+  };
+  return {
+    isComplete,
+    completeThrough: (start, end) => daysDesc.find((d) => d >= start && d <= end && isComplete(d)) ?? null
+  };
+}
+
 // src/db/queries.ts
-function getDaySummary(db, day) {
+function getDaySummary(db, day, complete) {
   const sl = db.query("SELECT score FROM daily_sleep WHERE day=?").get(day);
   const rd = db.query("SELECT score, temperature_deviation FROM daily_readiness WHERE day=?").get(day);
   const ac = db.query("SELECT score, steps FROM daily_activity WHERE day=?").get(day);
@@ -2721,6 +2908,7 @@ function getDaySummary(db, day) {
   const sm = db.query(`SELECT total_sleep_duration, deep_sleep_duration, rem_sleep_duration, average_hrv, lowest_heart_rate, efficiency FROM sleep_model WHERE day=? AND type='long_sleep'`).get(day);
   return {
     day,
+    partial: ac != null && !complete.isComplete(day),
     sleep_score: sl?.score ?? null,
     readiness_score: rd?.score ?? null,
     activity_score: ac?.score ?? null,
@@ -2739,15 +2927,17 @@ function getDaySummary(db, day) {
 function getTrends(db, days, today) {
   const start = shiftDay(today, -(days - 1));
   const results = [];
+  const activityEnd = dayCompleteness(db, today).completeThrough(start, today) ?? shiftDay(start, -1);
   const metrics = [
-    ["Sleep Score", "daily_sleep", "score"],
-    ["Readiness", "daily_readiness", "score"],
-    ["Activity", "daily_activity", "score"],
-    ["Steps", "daily_activity", "steps"],
-    ["Active Cal", "daily_activity", "active_calories"]
+    ["Sleep Score", "daily_sleep", "score", false],
+    ["Readiness", "daily_readiness", "score", false],
+    ["Activity", "daily_activity", "score", true],
+    ["Steps", "daily_activity", "steps", true],
+    ["Active Cal", "daily_activity", "active_calories", true]
   ];
-  for (const [label, table, col] of metrics) {
-    const row = db.query(`SELECT AVG(${col}) as avg, MIN(${col}) as min, MAX(${col}) as max, COUNT(${col}) as count FROM ${table} WHERE day BETWEEN ? AND ?`).get(start, today);
+  for (const [label, table, col, accumulates] of metrics) {
+    const end = accumulates ? activityEnd : today;
+    const row = db.query(`SELECT AVG(${col}) as avg, MIN(${col}) as min, MAX(${col}) as max, COUNT(${col}) as count FROM ${table} WHERE day BETWEEN ? AND ?`).get(start, end);
     if (row.count > 0 && row.avg !== null) {
       results.push({ label, avg: +row.avg.toFixed(0), min: row.min, max: row.max, count: row.count });
     }
@@ -2761,7 +2951,7 @@ function getTrends(db, days, today) {
 function getStats(db, today) {
   const tables = COLLECTIONS.map((c) => {
     const row = db.query(`SELECT COUNT(*) as cnt FROM ${c.table}`).get();
-    return { table: c.table, rows: row.cnt };
+    return { collection: c.name, table: c.table, rows: row.cnt };
   });
   const range = db.query("SELECT MIN(day) as first, MAX(day) as last FROM daily_sleep").get();
   const trends = getTrends(db, 99999, today);
@@ -2797,7 +2987,28 @@ function padRight(text, width) {
 
 // src/lib/terminal.ts
 function terminalWidth() {
-  return process.stdout.isTTY && process.stdout.columns ? process.stdout.columns : 80;
+  return screenWidth() ?? 80;
+}
+function screenWidth() {
+  return process.stdout.isTTY && process.stdout.columns ? process.stdout.columns : undefined;
+}
+
+// src/render/rule.ts
+init_source();
+var INDENT = "  ";
+function rule(width, glyph = "\u2500", max = screenWidth()) {
+  const drawn = max === undefined ? width : Math.max(0, Math.min(width, max - INDENT.length));
+  return drawn === 0 ? "" : source_default.gray(INDENT + glyph.repeat(drawn));
+}
+var PLACEHOLDER = "<rule ";
+var RULE = `${PLACEHOLDER}\u2500>`;
+var DOUBLE_RULE = `${PLACEHOLDER}\u2550>`;
+function finish(lines, max = screenWidth()) {
+  let widest = 0;
+  for (const l of lines)
+    if (!l.startsWith(PLACEHOLDER))
+      widest = Math.max(widest, visibleWidth(l) - INDENT.length);
+  return lines.map((l) => l.startsWith(PLACEHOLDER) ? rule(widest, l.slice(PLACEHOLDER.length, -1), max) : l);
 }
 
 // src/render/format.ts
@@ -2822,19 +3033,19 @@ function formatDaySummary(summary, format, emptyHint) {
   if (format === "json")
     return JSON.stringify(summary, null, 2);
   if (emptyHint && isEmptyDay(summary)) {
-    return [
+    return finish([
       "",
       source_default.bold(`  ${summary.day}`),
-      source_default.gray("\u2500".repeat(50)),
+      RULE,
       `  No Oura data for ${summary.day} yet.`,
       `  ${emptyHint}`
-    ].join(`
+    ]).join(`
 `);
   }
   const lines = [
     "",
-    source_default.bold(`  ${summary.day}`),
-    source_default.gray("\u2500".repeat(50)),
+    source_default.bold(`  ${summary.partial ? `${summary.day}*` : summary.day}`),
+    RULE,
     `  Sleep:     ${scoreColor(summary.sleep_score)}    Readiness: ${scoreColor(summary.readiness_score)}    Activity: ${scoreColor(summary.activity_score)}`,
     `  Steps:     ${summary.steps ?? source_default.gray("\u2014")}`
   ];
@@ -2851,9 +3062,13 @@ function formatDaySummary(summary, format, emptyHint) {
     lines.push(`  Sleep:     ${fmtHours(summary.sleep_hours)} total | ${fmtHours(summary.deep_hours)} deep | ${fmtHours(summary.rem_hours)} REM`);
     lines.push(`  HRV:       ${summary.avg_hrv ?? "\u2014"}    Lowest HR: ${summary.lowest_hr ?? "\u2014"}    Efficiency: ${summary.efficiency ?? "\u2014"}%`);
   }
-  return lines.join(`
+  if (summary.partial)
+    lines.push("", PARTIAL_NOTE);
+  return finish(lines).join(`
 `);
 }
+var PARTIAL_NOTE = "  * activity totals are not final.";
+var PUBLISH_DELAY_NOTE = "Oura publishes a day's summary after that night's sleep syncs from the ring.";
 var SUMMARY_INDENT = 4;
 var SUMMARY_GAP = 2;
 var SUMMARY_MAX_COLUMNS = 4;
@@ -2896,38 +3111,48 @@ function formatWeekTable(days, format, emptyHint) {
     ].join(`
 `);
   }
-  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) => `${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)}`);
+  const header = `${"Day".padEnd(12)} ${"Sleep".padStart(6)} ${"Ready".padStart(6)} ${"Activity".padStart(9)} ${"Steps".padStart(7)} Stress`;
+  const rows = days.map((d) => `${padRight(d.partial ? `${d.day}*` : 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)} ${d.stress ?? "\u2014"}`);
+  const sep = rule(Math.max(visibleWidth(header), ...rows.map(visibleWidth)));
+  const note = days.some((d) => d.partial) ? [PARTIAL_NOTE] : [];
   return [`
-  Last 7 Days`, sep, `  ${header}`, sep, ...rows.map((r) => `  ${r}`)].join(`
+  Last 7 Days`, sep, `  ${header}`, sep, ...rows.map((r) => `  ${r}`), ...note].join(`
 `);
 }
-function formatTrends(trends, days, format) {
+function formatTrends(trends, days, format, emptyHint) {
   if (format === "json")
     return JSON.stringify(trends, null, 2);
   const lines = [
     "",
     source_default.bold(`  Trends: last ${days} days`),
-    source_default.gray("\u2500".repeat(50))
+    RULE
   ];
+  if (emptyHint && trends.length === 0)
+    lines.push(`  No Oura data for the last ${days} days yet.`, `  ${emptyHint}`);
   for (const t of trends) {
     lines.push(`  ${t.label.padEnd(15)} avg: ${String(t.avg).padStart(5)}  min: ${String(t.min).padStart(5)}  max: ${String(t.max).padStart(5)}  (${t.count} days)`);
   }
-  return lines.join(`
+  return finish(lines).join(`
 `);
 }
-function formatStats(stats, format) {
+function formatStats(stats, format, emptyHint) {
   if (format === "json")
     return JSON.stringify(stats, null, 2);
   const lines = [
     "",
     source_default.bold("  Database Statistics"),
-    source_default.gray("\u2550".repeat(50))
+    DOUBLE_RULE
   ];
+  if (emptyHint && stats.tables.every((t) => t.rows === 0)) {
+    return finish([...lines, "  No Oura data in the database yet.", `  ${emptyHint}`]).join(`
+`);
+  }
   for (const t of stats.tables) {
-    lines.push(`  ${t.table.padEnd(22)} ${String(t.rows).padStart(8)} rows`);
+    lines.push(`  ${`${t.collection} (${t.table})`.padEnd(38)} ${String(t.rows).padStart(8)} row${t.rows === 1 ? "" : "s"}`);
   }
+  const noDailyData = stats.dateRange.first === null && stats.trends.length === 0 && stats.records.mostSteps === null && stats.records.bestSleep === null;
+  if (emptyHint && noDailyData)
+    lines.push("", "  No daily summaries in the database yet.", `  ${emptyHint}`);
   if (stats.dateRange.first) {
     lines.push(`
   Date range: ${stats.dateRange.first} \u2192 ${stats.dateRange.last}`);
@@ -2942,7 +3167,7 @@ function formatStats(stats, format) {
   if (stats.records.bestSleep) {
     lines.push(`  Best sleep:  ${stats.records.bestSleep.score} on ${stats.records.bestSleep.day}`);
   }
-  return lines.join(`
+  return finish(lines).join(`
 `);
 }
 
@@ -2980,14 +3205,15 @@ function resolvePruneScope(value) {
   }
   return [...new Set(wanted)];
 }
+var TODAY_HINT_AFTER_SYNC = `${PUBLISH_DELAY_NOTE} Run \`oura-cli sync\` again later.`;
 async function runSync(ctx, window = {}, options = {}) {
   const lines = [];
   const log = ctx.format === "table" ? (m) => lines.push(m) : undefined;
   const importResult = await importDaily(ctx.db, ctx.client, { today: ctx.today, tz: ctx.tz }, log, window, options);
-  const today = getDaySummary(ctx.db, ctx.today);
+  const today = getDaySummary(ctx.db, ctx.today, dayCompleteness(ctx.db, ctx.today));
   return {
     json: { import: importResult, today },
-    text: () => [...lines, formatImportSummary(importResult), formatDaySummary(today, "table")].join(`
+    text: () => [...lines, formatImportSummary(importResult), formatDaySummary(today, "table", TODAY_HINT_AFTER_SYNC)].join(`
 `)
   };
 }
@@ -2997,15 +3223,171 @@ var syncArgs = {
   prune: { type: "string", description: "Apply removals sync kept back: --prune=hr, a list, or --prune=all" }
 };
 var syncDef = {
-  meta: { name: "sync", description: "Import latest data from Oura API and return today's summary" },
+  meta: { name: "sync", description: "Download new Oura data into the local cache and report what each collection fetched" },
   args: syncArgs,
   needs: { db: true, client: true },
   run: (ctx, args) => runSync(ctx, resolveWindow({ from: args.from, to: args.to }, ctx.today), { prune: resolvePruneScope(args.prune) })
 };
 var syncCommand = dataCommand(syncDef);
 
+// src/db/rows.ts
+function getRows(db, c, range, tz) {
+  const cols = c.columns.map((k) => k.name);
+  if (range !== null && !cols.includes("day"))
+    throw new Error(`getRows: ${c.name} has no day column to bound a range on.`);
+  const order = [...new Set([...cols.includes("day") ? ["day"] : [], ...identityColumns(c)])].join(", ");
+  const select = `SELECT ${cols.join(", ")} FROM ${c.table}`;
+  if (range === null)
+    return db.query(`${select} ORDER BY ${order}`).all();
+  const between = db.query(`${select} WHERE day BETWEEN ? AND ? ORDER BY ${order}`);
+  if (c.rangeParams !== "datetime")
+    return between.all(range.start, range.end);
+  const fromMs = Date.parse(localDateToUtcRange(range.start, tz)[0]);
+  const toMs = Date.parse(localDateToUtcRange(range.end, tz)[1]);
+  const instant = (r) => Date.parse(String(r.timestamp));
+  return between.all(shiftDay(range.start, -1), shiftDay(range.end, 1)).filter((r) => {
+    const t = instant(r);
+    return t >= fromMs && t < toMs;
+  }).sort((a, b) => instant(a) - instant(b));
+}
+
+// src/render/format-rows.ts
+init_source();
+var MAX_CELL = 40;
+var MIN_CELL = 8;
+var GAP = 2;
+function printable(value) {
+  if (value === null)
+    return "\u2014";
+  return String(value).replace(/\r\n|\r|\n/g, "\u23CE").replace(/[\u0000-\u001f\u007f]/g, " ");
+}
+function clip(text, width) {
+  return text.length > width ? `${text.slice(0, Math.max(0, width - 1))}\u2026` : text;
+}
+function widest(values, floor = 0) {
+  let out = floor;
+  for (const v of values)
+    if (v > out)
+      out = v;
+  return out;
+}
+function fit(natural, floors, available) {
+  const out = [...natural];
+  while (out.reduce((sum, w) => sum + w, 0) > available) {
+    let target = -1;
+    for (let i = 0;i < out.length; i++) {
+      if (out[i] > floors[i] && (target === -1 || out[i] > out[target]))
+        target = i;
+    }
+    if (target === -1)
+      return null;
+    out[target]--;
+  }
+  return out;
+}
+function records(names, texts, max) {
+  const nameW = widest(names.map(visibleWidth));
+  const valueW = max === undefined ? Number.POSITIVE_INFINITY : Math.max(MIN_CELL, max - INDENT.length - nameW - GAP);
+  const lines = [];
+  texts.forEach((row, r) => {
+    if (r > 0)
+      lines.push("");
+    names.forEach((name, i) => lines.push(`${INDENT}${padRight(name, nameW)}${" ".repeat(GAP)}${clip(row[i], valueW)}`.trimEnd()));
+  });
+  return lines;
+}
+function formatRows(c, rows, scope, format, emptyHint, max = screenWidth(), total = rows.length) {
+  if (format === "json")
+    return JSON.stringify(rows, null, 2);
+  const all = Math.max(total, rows.length);
+  const count = rows.length === all ? `${all} row${all === 1 ? "" : "s"}` : `${rows.length} of ${all} rows`;
+  const title = source_default.bold(`  ${c.name} (${c.table}): ${count}${scope}`);
+  if (rows.length === 0) {
+    return finish(["", title, RULE, `  No cached ${c.name} rows${scope}.`, `  ${emptyHint}`], max).join(`
+`);
+  }
+  const names = c.columns.map((k) => k.name);
+  const numeric = new Set(c.columns.filter((k) => k.type !== "TEXT").map((k) => k.name));
+  const texts = rows.map((r) => names.map((name) => clip(printable(r[name] ?? null), MAX_CELL)));
+  const headers = names.map(visibleWidth);
+  const natural = names.map((_, i) => widest(texts.map((row) => visibleWidth(row[i])), headers[i]));
+  const gaps = GAP * (names.length - 1);
+  const widths = max === undefined ? natural : fit(natural, headers.map((h) => Math.max(h, MIN_CELL)), max - INDENT.length - gaps);
+  if (widths === null)
+    return finish(["", title, RULE, ...records(names, texts, max)], max).join(`
+`);
+  const line = (parts) => `${INDENT}${parts.map((p, i) => numeric.has(names[i]) ? padLeft(clip(p, widths[i]), widths[i]) : padRight(clip(p, widths[i]), widths[i])).join(" ".repeat(GAP))}`.trimEnd();
+  return finish(["", title, RULE, line(names), RULE, ...texts.map(line)], max).join(`
+`);
+}
+
+// src/commands/fetch.ts
+function resolveRange(opts) {
+  const modes = [opts.day !== undefined, opts.from !== undefined || opts.to !== undefined, opts.days !== undefined].filter(Boolean).length;
+  if (modes > 1)
+    throw new CliError("BAD_ARGS", "Use only one of --day, --from/--to, or --days.");
+  if (opts.day !== undefined) {
+    const d = assertCalendarDate(opts.day, "--day");
+    return { start: d, end: d };
+  }
+  if (opts.from !== undefined || opts.to !== undefined) {
+    if (opts.from === undefined || opts.to === undefined)
+      throw new CliError("BAD_ARGS", "--from and --to must be given together.");
+    const start = assertCalendarDate(opts.from, "--from");
+    const end = assertCalendarDate(opts.to, "--to");
+    if (start > end)
+      throw new CliError("BAD_ARGS", `--from (${start}) must not be after --to (${end}).`);
+    return { start, end };
+  }
+  if (opts.days !== undefined) {
+    const n = assertPositiveInt(opts.days, "--days");
+    return { start: shiftDay(opts.today, -(n - 1)), end: opts.today };
+  }
+  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(" | ")} (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" },
+    days: { type: "string", description: "Last N days ending today" }
+  },
+  jsonOnly: true,
+  async run(ctx, args) {
+    const c = byName(args.collection);
+    if (!c)
+      throw new CliError("BAD_ARGS", `Unknown collection "${args.collection}".`, `Valid collections: ${names().join(", ")}`);
+    const opts = {
+      day: args.day,
+      from: args.from,
+      to: args.to,
+      days: args.days
+    };
+    assertRangeAllowed(c, opts);
+    const { start, end } = resolveRange({ ...opts, today: ctx.today });
+    const progress = ctx.progress ? pageProgress(ctx.progress, "fetching") : undefined;
+    const client = new OuraClient({
+      ...args.token ? { token: args.token } : {},
+      ...progress ? { onPage: progress.onPage, onRetry: progress.onRetry } : {}
+    });
+    try {
+      const data = await fetchCollection(client, c, start, end, ctx.tz);
+      return { json: data, text: () => JSON.stringify(data, null, 2) };
+    } finally {
+      progress?.done();
+    }
+  }
+});
+
 // src/commands/db.ts
-var SYNC_HINT = "Run `oura-cli sync` to download your data. Oura publishes a day's summary after that night's sleep syncs from the ring.";
+var SYNC_HINT = `Run \`oura-cli sync\` to download your data. ${PUBLISH_DELAY_NOTE}`;
 var dbCommand = defineCommand({
   meta: { name: "db", description: "Query and manage the local SQLite database" },
   subCommands: {
@@ -3013,7 +3395,7 @@ var dbCommand = defineCommand({
       meta: { name: "today", description: "Today's summary from local database" },
       needs: { db: true },
       run(ctx) {
-        const summary = getDaySummary(ctx.db, ctx.today);
+        const summary = getDaySummary(ctx.db, ctx.today, dayCompleteness(ctx.db, ctx.today));
         return { json: summary, text: () => formatDaySummary(summary, "table", SYNC_HINT) };
       }
     }),
@@ -3023,7 +3405,7 @@ var dbCommand = defineCommand({
       needs: { db: true },
       run(ctx, args) {
         const day = assertCalendarDate(String(args.day), "<day>");
-        const summary = getDaySummary(ctx.db, day);
+        const summary = getDaySummary(ctx.db, day, dayCompleteness(ctx.db, ctx.today));
         return { json: summary, text: () => formatDaySummary(summary, "table") };
       }
     }),
@@ -3031,7 +3413,8 @@ var dbCommand = defineCommand({
       meta: { name: "week", description: "Last 7 days from local database" },
       needs: { db: true },
       run(ctx) {
-        const days = daysBack(ctx.today, 7).map((d) => getDaySummary(ctx.db, d));
+        const complete = dayCompleteness(ctx.db, ctx.today);
+        const days = daysBack(ctx.today, 7).map((d) => getDaySummary(ctx.db, d, complete));
         return { json: days, text: () => formatWeekTable(days, "table", "Run `oura-cli sync`, then `oura-cli db week` again.") };
       }
     }),
@@ -3042,7 +3425,7 @@ var dbCommand = defineCommand({
       run(ctx, args) {
         const n = args.days === undefined ? 30 : assertPositiveInt(String(args.days), "<days>");
         const trends = getTrends(ctx.db, n, ctx.today);
-        return { json: trends, text: () => formatTrends(trends, n, "table") };
+        return { json: trends, text: () => formatTrends(trends, n, "table", "Run `oura-cli sync`, then `oura-cli db trends` again.") };
       }
     }),
     stats: dataCommand({
@@ -3050,7 +3433,38 @@ var dbCommand = defineCommand({
       needs: { db: true },
       run(ctx) {
         const stats = getStats(ctx.db, ctx.today);
-        return { json: stats, text: () => formatStats(stats, "table") };
+        return { json: stats, text: () => formatStats(stats, "table", "Run `oura-cli sync`, then `oura-cli db stats` again.") };
+      }
+    }),
+    rows: dataCommand({
+      meta: { name: "rows", description: "Cached rows of one collection, as stored: the local twin of `fetch`" },
+      args: {
+        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" },
+        days: { type: "string", description: "Last N days ending today" },
+        limit: { type: "string", description: "Print at most N rows, the earliest first (a day of heart rate is hundreds)" }
+      },
+      needs: { db: true },
+      run(ctx, args) {
+        const c = byName(String(args.collection));
+        if (!c)
+          throw new CliError("BAD_ARGS", `Unknown collection "${args.collection}".`, `Valid collections: ${names().join(", ")}`);
+        const opts = {
+          day: args.day,
+          from: args.from,
+          to: args.to,
+          days: args.days
+        };
+        assertRangeAllowed(c, opts);
+        const range = c.rangeParams === "none" ? null : resolveRange({ ...opts, today: ctx.today });
+        const limit = args.limit === undefined ? undefined : assertPositiveInt(String(args.limit), "--limit");
+        const all = getRows(ctx.db, c, range, ctx.tz);
+        const rows = limit === undefined ? all : all.slice(0, limit);
+        const scope = range === null ? "" : range.start === range.end ? ` for ${range.start}` : ` for ${range.start} \u2192 ${range.end}`;
+        const hint = range === null ? `Run \`oura-cli sync\` to fill the cache, or \`oura-cli fetch ${c.name}\` to read the API.` : `Run \`oura-cli sync\` (\`sync --from <day>\` for older days), or \`oura-cli fetch ${c.name}\` to read the API.`;
+        return { json: rows, text: () => formatRows(c, rows, scope, "table", hint, undefined, all.length) };
       }
     })
   }
@@ -3073,9 +3487,8 @@ function getReport(db, days, today) {
   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 complete = dayCompleteness(db, today);
+  const completeThrough = complete.completeThrough(weekStart, today);
   const activityEnd = completeThrough ?? shiftDay(weekStart, -1);
   const dailyRows = [];
   for (const d of windowDays) {
@@ -3089,7 +3502,7 @@ function getReport(db, days, today) {
       readiness: rd?.score ?? null,
       activity: ac?.score ?? null,
       steps: ac?.steps ?? null,
-      partial: ac != null && !isComplete(d)
+      partial: ac != null && !complete.isComplete(d)
     });
   }
   const metrics = [
@@ -3190,8 +3603,8 @@ var RECOMMENDATIONS = {
 };
 function bucketDaysIntoWeeks(days) {
   const buckets = [];
-  for (let i = 0;i < days.length; i += 7) {
-    const chunk = days.slice(i, i + 7);
+  for (let end = days.length;end > 0; end -= 7) {
+    const chunk = days.slice(Math.max(0, end - 7), end);
     const weekOf = chunk[0].day;
     const sleepVals = chunk.map((d) => d.sleep).filter((v) => v !== null);
     const readinessVals = chunk.map((d) => d.readiness).filter((v) => v !== null);
@@ -3199,6 +3612,7 @@ function bucketDaysIntoWeeks(days) {
     const stepsVals = chunk.map((d) => d.steps).filter((v) => v !== null);
     buckets.push({
       weekOf,
+      days: chunk.length,
       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,
@@ -3206,15 +3620,19 @@ function bucketDaysIntoWeeks(days) {
       partial: chunk.some((d) => d.partial)
     });
   }
-  return buckets;
+  return buckets.reverse();
+}
+function bucketLabel(b) {
+  const stub = b.days < 7 ? ` (${b.days} day${b.days === 1 ? "" : "s"})` : "";
+  return `${b.weekOf}${stub}${b.partial ? "*" : ""}`;
 }
-function partialDayNote(data) {
+function partialDayNote(data, bucket) {
   const partial = data.days.find((d) => d.partial);
   if (!partial)
     return null;
-  const which = partial.day === data.weekEnd ? "today" : partial.dayLabel;
+  const which = bucket ? `the week of ${bucket.weekOf}` : 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}.`;
+  return `  * ${which}: activity totals are not final; averages cover ${covers}.`;
 }
 function formatReport(data, format, period) {
   if (format === "json")
@@ -3227,7 +3645,8 @@ 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);
+  const buckets = period === "month" ? bucketDaysIntoWeeks(data.days) : [];
+  const note = partialDayNote(data, buckets.find((b) => b.partial));
   if (note)
     lines.push(source_default.yellow(note));
   lines.push("");
@@ -3241,26 +3660,21 @@ function formatReport(data, format, period) {
   }
   if (period === "week") {
     lines.push(source_default.bold("  Last 7 Days:"));
-    lines.push(source_default.gray("  " + "\u2500".repeat(52)));
-    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)));
+    const table = [RULE, `  ${"Day".padEnd(10)} ${"Sleep".padStart(6)} ${"Ready".padStart(6)} ${"Active".padStart(7)} ${"Steps".padStart(8)}`, RULE];
     for (const d of data.days) {
-      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)}`);
+      table.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("");
+    lines.push(...finish(table), "");
   } else {
-    const buckets = bucketDaysIntoWeeks(data.days);
     lines.push(source_default.bold("  Last 30 Days:"));
-    lines.push(source_default.gray("  " + "\u2500".repeat(60)));
-    lines.push(`  ${"Week of".padEnd(12)} ${"Sleep".padStart(6)} ${"Ready".padStart(6)} ${"Active".padStart(7)} ${"Steps".padStart(10)}`);
-    lines.push(source_default.gray("  " + "\u2500".repeat(60)));
+    const table = [RULE, `  ${"Week of".padEnd(21)} ${"Sleep".padStart(6)} ${"Ready".padStart(6)} ${"Active".padStart(7)} ${"Steps".padStart(10)}`, RULE];
     for (const b of buckets) {
       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.partial ? b.weekOf + "*" : b.weekOf).padEnd(12)} ${scoreCell(avgSleepInt, 6)} ${scoreCell(avgReadyInt, 6)} ${scoreCell(avgActiveInt, 7)} ${stepsCell(b.totalSteps, 10)}`);
+      table.push(`  ${bucketLabel(b).padEnd(21)} ${scoreCell(avgSleepInt, 6)} ${scoreCell(avgReadyInt, 6)} ${scoreCell(avgActiveInt, 7)} ${stepsCell(b.totalSteps, 10)}`);
     }
-    lines.push("");
+    lines.push(...finish(table), "");
   }
   lines.push(source_default.bold("  Averages (this period vs previous):"));
   for (const a of data.averages) {
@@ -3360,14 +3774,14 @@ function statusSymbol(status) {
   return source_default.red("\u2717");
 }
 function formatDoctorTable(result) {
-  const lines = ["", source_default.bold("  Doctor"), source_default.gray("\u2500".repeat(50))];
+  const lines = ["", source_default.bold("  Doctor"), RULE];
   for (const c of result.checks) {
     lines.push(`  ${statusSymbol(c.status)} ${c.id.padEnd(12)} ${c.detail}`);
   }
   lines.push("");
   const next = result.nextStep ?? (result.ok ? "nothing \u2014 everything looks healthy." : "see the failing checks above.");
   lines.push(`  Next: ${next}`);
-  return lines.join(`
+  return finish(lines).join(`
 `);
 }
 
@@ -3394,7 +3808,7 @@ async function runChecks(deps) {
         checks.push({ id: "token-valid", status: "fail", detail: err.message, fix: "oura-cli login" });
       } else {
         const msg = err instanceof Error ? err.message : String(err);
-        checks.push({ id: "token-valid", status: "warn", detail: `Could not reach the Oura API: ${msg}` });
+        checks.push({ id: "token-valid", status: "warn", detail: `Could not reach the Oura API: ${msg}`, fix: "Check the network connection and run `oura-cli doctor` again in a few minutes." });
       }
     }
   }
@@ -3422,9 +3836,14 @@ async function runChecks(deps) {
     } else if (!last) {
       checks.push({ id: "data", status: "warn", detail: "No data in the local cache yet.", fix: "oura-cli sync" });
     } else {
-      const ageDays = Math.round((new Date(`${deps.today}T00:00:00Z`).getTime() - new Date(`${last}T00:00:00Z`).getTime()) / 86400000);
-      if (ageDays > 2) {
-        checks.push({ id: "data", status: "warn", detail: `Most recent data is from ${last} (${ageDays} days ago).`, fix: "oura-cli sync" });
+      const hours = hoursSinceDayEnded(last, deps.now, deps.tz);
+      if (hours > STALE_AFTER_HOURS) {
+        checks.push({
+          id: "data",
+          status: "warn",
+          detail: `Most recent data is from ${last}; that day ended over ${Math.floor(hours)} hours ago (the limit is ${STALE_AFTER_HOURS}).`,
+          fix: "oura-cli sync"
+        });
       } else {
         checks.push({ id: "data", status: "ok", detail: `Data current through ${last}.` });
       }
@@ -3449,6 +3868,14 @@ function quickCheck(db) {
   }
 }
 var DATA_TABLES = ["daily_sleep", "daily_readiness", "daily_activity"];
+var STALE_AFTER_HOURS = 36;
+function hoursSinceDayEnded(day, now, tz) {
+  const ended = Date.parse(localDateToUtcRange(day, tz)[1]);
+  const hours = (Date.parse(now) - ended) / 3600000;
+  if (!Number.isFinite(hours))
+    throw new Error(`hoursSinceDayEnded: cannot place ${JSON.stringify(now)} against day ${day}.`);
+  return hours;
+}
 function latestDataDay(db) {
   let latest = null;
   for (const tbl of DATA_TABLES) {
@@ -3477,7 +3904,9 @@ async function runDoctor(ctx, args) {
     },
     createClient: (token) => new OuraClient({ token }),
     offline: args.offline === true,
-    today: ctx.today
+    today: ctx.today,
+    now: nowUtc(),
+    tz: ctx.tz
   };
   const result = await runChecks(deps);
   return {
@@ -3531,62 +3960,21 @@ function manifestCommand(version, getCommands) {
   });
 }
 
-// src/commands/fetch.ts
-function resolveRange(opts) {
-  const modes = [opts.day !== undefined, opts.from !== undefined || opts.to !== undefined, opts.days !== undefined].filter(Boolean).length;
-  if (modes > 1)
-    throw new CliError("BAD_ARGS", "Use only one of --day, --from/--to, or --days.");
-  if (opts.day !== undefined) {
-    const d = assertCalendarDate(opts.day, "--day");
-    return { start: d, end: d };
-  }
-  if (opts.from !== undefined || opts.to !== undefined) {
-    if (opts.from === undefined || opts.to === undefined)
-      throw new CliError("BAD_ARGS", "--from and --to must be given together.");
-    const start = assertCalendarDate(opts.from, "--from");
-    const end = assertCalendarDate(opts.to, "--to");
-    if (start > end)
-      throw new CliError("BAD_ARGS", `--from (${start}) must not be after --to (${end}).`);
-    return { start, end };
-  }
-  if (opts.days !== undefined) {
-    const n = assertPositiveInt(opts.days, "--days");
-    return { start: shiftDay(opts.today, -(n - 1)), end: opts.today };
-  }
-  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.`);
-  }
+// src/commands/registry.ts
+function buildRegistry(version) {
+  const subCommands = Object.assign(Object.create(null), {
+    login: loginCommand,
+    describe: describeCommand(version, () => subCommands),
+    healthcheck: healthcheckCommand(version),
+    doctor: doctorCommand,
+    manifest: manifestCommand(version, () => subCommands),
+    fetch: fetchCommand,
+    sync: syncCommand,
+    db: dbCommand,
+    report: reportCommand
+  });
+  return subCommands;
 }
-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(" | ")} (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" },
-    days: { type: "string", description: "Last N days ending today" }
-  },
-  jsonOnly: true,
-  async run(ctx, args) {
-    const c = byName(args.collection);
-    if (!c)
-      throw new CliError("BAD_ARGS", `Unknown collection "${args.collection}".`, `Valid collections: ${names().join(", ")}`);
-    const opts = {
-      day: args.day,
-      from: args.from,
-      to: args.to,
-      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) };
-  }
-});
 
 // src/lib/citty-error.ts
 var ANSI2 = /\u001b\[[0-9;]*m/g;
@@ -3619,11 +4007,28 @@ function nearestGlobalFlag(token) {
     return;
   return [...GLOBAL_FLAGS_WITH_VALUE].find((flag) => flag !== token && (editDistanceAtMostOne(flag, token) || flag.startsWith(token)));
 }
-function fromCittyError(err, removedCommandHints = {}, rawArgs = []) {
+function commandTokens(rawArgs) {
+  const tokens = [];
+  for (let i = 0;i < rawArgs.length; i++) {
+    const tok = rawArgs[i];
+    if (GLOBAL_FLAGS_WITH_VALUE.has(tok)) {
+      i++;
+      continue;
+    }
+    if (tok.startsWith("-"))
+      continue;
+    tokens.push(tok);
+  }
+  return tokens;
+}
+function fromCittyError(err, removedCommandHints = {}, rawArgs = [], parents = {}) {
   const code = err?.code;
   if (typeof code !== "string")
     return err;
   const message = (err instanceof Error ? err.message : String(err)).replace(ANSI2, "");
+  const first = commandTokens(rawArgs)[0];
+  const parent = first !== undefined && Object.hasOwn(parents, first) ? first : undefined;
+  const parentHelp = parent === undefined ? undefined : `\`oura-cli ${parent}\` takes one of: ${parents[parent].join(", ")}. Run \`oura-cli ${parent} --help\` for details.`;
   switch (code) {
     case "E_UNKNOWN_COMMAND": {
       const name = message.replace(/^Unknown command\s*/, "").trim();
@@ -3632,16 +4037,19 @@ function fromCittyError(err, removedCommandHints = {}, rawArgs = []) {
       if (meant) {
         return new CliError("BAD_ARGS", `Unknown flag "${before}".`, `Did you mean ${meant}? Its value was read as a command name.`);
       }
+      if (parentHelp !== undefined && before !== undefined && GLOBAL_FLAGS_WITH_VALUE.has(before)) {
+        return new CliError("BAD_ARGS", `"${parent}" needs a subcommand.`, parentHelp);
+      }
       if (!COMMAND_NAME.test(name)) {
         return new CliError("BAD_ARGS", "Unknown command.", "A value was read as a command name. Check the flags before it, and run `oura-cli --help` for the list of commands.");
       }
-      const hint = Object.hasOwn(removedCommandHints, name) ? removedCommandHints[name] : "Run `oura-cli --help` for the list of commands.";
+      const hint = Object.hasOwn(removedCommandHints, name) ? removedCommandHints[name] : parentHelp ?? "Run `oura-cli --help` for the list of commands.";
       return new CliError("BAD_ARGS", `Unknown command "${name}".`, hint);
     }
     case "EARG":
       return new CliError("BAD_ARGS", message.endsWith(".") ? message : `${message}.`, "Run the command with --help to see its arguments.");
     case "E_NO_COMMAND":
-      return new CliError("BAD_ARGS", "No command specified.", "Run `oura-cli --help` for the list of commands.");
+      return parentHelp === undefined ? new CliError("BAD_ARGS", "No command specified.", "Run `oura-cli --help` for the list of commands.") : new CliError("BAD_ARGS", `"${parent}" needs a subcommand.`, parentHelp);
     default:
       return err;
   }
@@ -3649,17 +4057,11 @@ function fromCittyError(err, removedCommandHints = {}, rawArgs = []) {
 
 // src/index.ts
 var VERSION = JSON.parse(readFileSync2(new URL("../package.json", import.meta.url), "utf-8")).version;
-var subCommands = Object.assign(Object.create(null), {
-  login: loginCommand,
-  describe: describeCommand(VERSION, () => subCommands),
-  healthcheck: healthcheckCommand(VERSION),
-  doctor: doctorCommand,
-  manifest: manifestCommand(VERSION, () => subCommands),
-  fetch: fetchCommand,
-  sync: syncCommand,
-  db: dbCommand,
-  report: reportCommand
-});
+var subCommands = buildRegistry(VERSION);
+var PARENT_COMMANDS = Object.fromEntries(Object.entries(subCommands).flatMap(([name, def]) => {
+  const subs = def.subCommands;
+  return subs !== null && typeof subs === "object" ? [[name, Object.keys(subs)]] : [];
+}));
 var FETCH_HINT = "The per-collection commands were replaced in 0.5.0 by `oura-cli fetch <collection>`, e.g. `oura-cli fetch sleep --day 2026-09-01`. Run `oura-cli fetch --help`.";
 var REMOVED_COMMANDS = {
   reset: "`db reset` was removed in 0.5.0; delete the database file (`--db` / OURA_DB_PATH) and run `oura-cli sync` to rebuild it.",
@@ -3682,14 +4084,16 @@ var main = defineCommand({
   subCommands
 });
 var rawArgs = normalizeArgv(process.argv).slice(2);
-var wantsHelp = rawArgs.some((a) => a === "--help" || a === "-h") || rawArgs.length === 0 && process.stdout.isTTY === true;
+var commands = commandTokens(rawArgs);
+var bareParent = commands.length === 1 && Object.hasOwn(PARENT_COMMANDS, commands[0]);
+var wantsHelp = rawArgs.some((a) => a === "--help" || a === "-h") || (commands.length === 0 || bareParent) && process.stdout.isTTY === true;
 if (isVersionRequest(rawArgs)) {
   console.log(VERSION);
 } else if (wantsHelp) {
-  runMain(main, { rawArgs });
+  runMain(main, { rawArgs: bareParent ? [...rawArgs, "--help"] : rawArgs });
 } else {
   runCommand(main, { rawArgs }).catch((raw) => {
-    const err = fromCittyError(raw, REMOVED_COMMANDS, rawArgs);
+    const err = fromCittyError(raw, REMOVED_COMMANDS, rawArgs, PARENT_COMMANDS);
     emitError(err, formatFromArgv(rawArgs, process.stdout.isTTY === true));
     process.exit(exitCodeFor(err));
   });