@drakulavich/oura-cli 0.6.0 → 0.7.1

package/CHANGELOG.md

@@ -6,6 +6,34 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+## [0.7.1] - 2026-09-12
+
+### Fixed
+- Whether a day's activity totals are final is now read off the day itself. Oura's `class_5_min` carries one character per five-minute slot, so a day reporting a full 288 of them has been closed out; `sync` stores the length in a new `daily_activity.class_5_min_slots` column and `report` reads it. The converse does not hold, and the rule does not claim it: a count *below* 288 is not evidence a day is still open. A day's span is `timestamp(d+1) − timestamp(d)`, so travelling east shortens it — 2023-12-15 came back with 276 slots and 13,637 steps, 2024-01-13 with 270 and 15,736, both closed long ago — while 288 also comes back for 23-hour days and caps longer ones. So the slot count is read as positive evidence of closure only, and a day short of 288 falls back to the old next-day rule rather than being called open. The old rule inferred it instead — a day counted as complete once a *later* day had its own record — which described the ring's behaviour rather than the day, and came apart wherever the two did: a ring that stopped uploading froze its last day as "still accumulating" forever, keeping real steps out of every average; a report timezone west of the ring's discarded a day the cache had already closed; and `completeThrough` could name a day holding no activity record at all, promising an average over a day the table never printed. Rows written before the column exists keep NULL and take the same fallback, so an upgraded cache fills in as `sync` re-fetches each day — `sync --from` fills older days on demand. Because the slot count can only ever close a day and never reopen one, upgrading never makes a day with an activity record *less* complete than it already was: over a real 1,044-day cache the two rules together name exactly the days the old rule named. (#74)
+- `db trends`, `db stats` and `db week` now use that same judgement, so the screens stop disagreeing about one week (the all-time averages in `db stats` move by a few steps for the same reason: the day in progress no longer counts). `db trends` averaged the day in progress as though it were whole while `report` excluded it, and `db week` showed its part-day steps unmarked: the same seven days gave a 7,610 step average in one place and 6,639 in another. Activity, steps and active calories now stop at the last complete day in the window; sleep and readiness are final once they exist and still cover all of it. The week table marks the day with `*` and `DaySummary` carries `partial`, matching what `report` has always shown. (#75)
+- `sync` no longer aborts on a heart-rate sample without a `timestamp`. The `day` column is derived from it, so a null threw a `TypeError` at insert time, outside the CLI's error mapping, and every collection after `hr` in the run never synced. A row whose identity field is missing, null, empty, or not the type the column stores is now dropped before insert, counted in the JSON under `dropped` and named on the collection's line (`1 dropped (no timestamp/source)`); the row was unusable anyway, since those columns are what it would have been stored under. A row is judged by the columns its table keys on, not by the manifest's identity fields: a daily summary Oura sends without an `id` is still stored under its `day`. (#106)
+- An empty `200` from a snapshot endpoint no longer clears its table. `ring` is fetched whole every run and was replaced with whatever came back, so a partial read or an upstream hiccup deleted every ring and the JSON showed nothing in `removed`. The snapshot path now follows the rule the ranged collections already had: an empty answer describes nothing, so the rows are kept and reported under `refused` with the `--prune=ring` hint; a ring genuinely gone from the account is applied with that flag. Rings a non-empty response no longer lists are counted in `removed`, as they always should have been. (#105)
+- `db trends` and `db stats` say what is missing on an empty cache instead of printing a header over nothing, or seventeen lines of `0 rows`. Both now carry the same "run `oura-cli sync`, then this command again" line that `db today` and `db week` already print. (#85)
+- `report --period month` chunks its week buckets from the newest day back, so the remainder of a 30-day window is the oldest row and is labelled with its size (`2026-08-13 (2 days)`), not an unlabelled stub at the bottom that read as activity collapsing by 85 %. The `*` note names the bucket it marks (`the week of …`) instead of saying "today" above a table with no day rows. (#84)
+- The `describe` and `manifest` snapshots now cover the real command registry. The old snapshot was built from a hand-listed fixture that did not include `sync`, so #103 added `--prune` to a published contract and no test moved. The registry lives in `src/commands/registry.ts`, the contract test asserts it matches the argv normalizer's command set, and the fixture-based tests stay as they were, since a controlled input is what they need. (#104)
+
+## [0.7.0] - 2026-09-09
+
+### Added
+- `sync --prune=<collections>` applies removals the truncation guard refuses. The guard keeps rows when a response drops most of what one request described, which is right for a partial or short answer and wrong for a genuine large correction — and it cannot tell them apart, so a genuine one was refused on every run with no way through. Narrowing the window did not help: the scope is the returned rows' own bounds, so the ratio never moved, and `sync --from D --to D` refused identically. The flag is the user's answer to the question the guard cannot ask, per run and never stored.
+
+  It is scoped to the collections named because consent is per collection: the refusal message names the collection to pass (`re-run with --prune=hr`), so lifting the guard for one does not lift it for another that answers short in the same run — a loss that never comes back behind `--from`, since the next ordinary sync resumes from the watermark. `--prune=all` covers every collection; a valueless `--prune` is refused, because as a string flag it would otherwise swallow whatever came next on the line. Removals that went past the guard are counted separately from ordinary reconciliation, in the JSON as `pruned` and on the collection line as `(N past the truncation guard)`, so a bypass is never silent. `refused` and `pruned` carry the collection name alongside the count (`{rows, collection}`), because they are the only fields that imply a follow-up command and the command takes a name the table-keyed payload did not contain — `sync` is JSON-only off a TTY, and an agent that cannot map `heartrate` back to `hr` would reach for `--prune=all`. A run that passed the flag also records `pruneScope`, so a kept JSON log can say whether the guard was lifted and over what. A piece that returns nothing still removes nothing, flag or not. Where two pieces overlap, every piece covering a row is consulted before that row is decided, and one doubting piece is enough to keep it — a verdict taken while walking the pieces would have been settled by whichever came first, so the same responses in a different order could delete a row instead of keeping it. (#100)
+
+### Fixed
+- `sync` kept both rows when Oura reclassified a heart-rate sample (`awake` → `workout` shares the timestamp, and the unique index is `(timestamp, source)`), and no command could repair it. A re-fetched window is now reconciled against the response: rows the API no longer has are removed, inside the same transaction as the inserts. Verified on a copy of a real cache, where it removed exactly the five stale samples the exploratory session had found. (#91)
+- The same for the five tables whose `day` is not unique (`sleep_model`, `workouts`, `sessions`, `rest_mode_periods`, `enhanced_tags`): a record re-issued under a new id used to leave both rows, so `report` averaged one night twice. The scope of a removal always comes from the response and from one request at a time — a range wider than the endpoint allows is fetched in pieces, and a piece that answers with nothing describes nothing, so its days keep their rows. A piece whose answer would drop most of what is stored for it is treated as truncated: the removal is refused and reported. (#71)
+- `sync` reports `removed` and `refused` per table in its JSON, and the progress line says how many stale rows went and how many were kept because the response looked truncated.
+- `ensureSchema` read the schema version and applied migrations with nothing serialising the two, so concurrent commands recorded the same migration several times — harmless only while every migration is `CREATE ... IF NOT EXISTS`, and a hard failure for the loser as soon as one is an `ALTER TABLE`. Check and apply now run under `BEGIN IMMEDIATE`. Two processes creating the same cache also raced on `PRAGMA journal_mode = WAL`, which answers `SQLITE_BUSY` without waiting out `busy_timeout`; losing that race is no longer an error, since the winner set the mode this process wanted. (#77)
+- A misspelled global flag left its value in the command position, so the CLI reported the value as the command name — and for `--tok <token>` that put a Personal Access Token into an error message. A near miss of a known flag is now blamed on the flag (`Unknown flag "--tok". Did you mean --token?`), and a value that cannot be a command name is never quoted back. (#95)
+- An empty `--token` or `OURA_TOKEN` fell through to the token file, so a wrapper expanding an unset variable authenticated as whoever that file holds; an empty `OURA_TZ` fell through to the system zone and shifted every day boundary silently. Both are now `BAD_ARGS`, like the `--db` case fixed in 0.6.0, through one shared guard. (#92)
+- A database in a directory the user cannot write reported `attempt to write a readonly database` with a hint about the file's format. The file is fine; SQLite needs to create `-wal` and `-shm` beside it. Permission failures now get their own hint. (#78)
+- `doctor` runs SQLite's `quick_check` and reports it as a new `integrity` check, so a cache with a damaged page is named instead of passing every command until something touches the broken page. `doctor` also survives reading a corrupt cache rather than crashing part-way through its own checks, and `healthcheck`'s description now says it proves the file opens, not that its contents are intact. (#78)
+
 ## [0.6.0] - 2026-09-06
 
 ### Fixed

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). 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.
+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. A re-fetched window ends up holding exactly what the API returned for it: a sample Oura reclassified, or a record it re-issued under a new id, replaces the row it supersedes instead of joining it. When a response drops most of what one request covered — the shape of a partial or short answer — those rows are kept rather than deleted, and `sync` names the collection and how many. `oura-cli sync --prune=hr` then applies them for that collection once you have judged the correction genuine; `oura-cli sync --prune=all` does it for every collection in the run, which also lifts the guard on any collection that answers short in the same run. `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. 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`.
+Reports cover daily scores, averages, deltas vs the previous window, sleep details, and a short recommendation block. A day whose activity is still accumulating — normally just today — is shown with a `*` and kept out of the activity averages and recommendations; the JSON says so via `days[].partial` and `completeThrough`. `db today`, `db date` and `db week` carry the same `partial` flag, and `db week` marks the day with a `*` too, so the two screens cannot disagree. A day is treated as closed once Oura reports a full 24 hours of five-minute activity slots for it, so a ring that stops syncing no longer freezes its last day as unfinished.
 
 ### Trends and stats
 
@@ -183,7 +183,7 @@ 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, plus `error` when `ok` is false.
+- `oura-cli healthcheck` — `{ok, version, latencyMs}` JSON for liveness probes, plus `error` when `ok` is false. It proves the database opens and answers a query; it does not inspect the contents. `oura-cli doctor` runs SQLite's `quick_check` for that.
 - 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.

package/dist/index.js

@@ -1198,6 +1198,14 @@ import { resolve, dirname } from "path";
 import { homedir } from "os";
 import { chmodSync, existsSync, mkdirSync } from "fs";
 
+// src/lib/require-value.ts
+function requireValue(value, source, fallback) {
+  if (value.trim() === "") {
+    throw new CliError("BAD_ARGS", `${source} has no value`, `Pass a value, or remove ${source} to fall back to ${fallback}.`);
+  }
+  return value;
+}
+
 // src/db/migrations.ts
 var MIGRATIONS = [
   {
@@ -1399,33 +1407,42 @@ 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;
+    `
   }
 ];
 
 // src/db/open.ts
 var DB_HINT = "Check the path in --db / OURA_DB_PATH and that the file is a SQLite database oura-cli created.";
 var BUSY_HINT = "Another oura-cli process is using this database; wait for it to finish and retry.";
+var PERMISSION_HINT = "Check that you can write both the file and the directory holding it \u2014 SQLite creates -wal and -shm files alongside the database.";
 var BUSY_TIMEOUT_MS = 5000;
+var WAL_SWITCH_ATTEMPTS = 20;
+var WAL_SWITCH_WAIT_MS = 25;
+function hintFor(detail) {
+  if (/database is locked|SQLITE_BUSY/i.test(detail))
+    return BUSY_HINT;
+  if (/readonly database|read-only|EACCES|permission denied|unable to open database file/i.test(detail))
+    return PERMISSION_HINT;
+  return DB_HINT;
+}
 function dbError(what, err) {
   const detail = err instanceof Error ? err.message : String(err);
-  const hint = /database is locked|SQLITE_BUSY/i.test(detail) ? BUSY_HINT : DB_HINT;
-  return new CliError("DB_ERROR", `${what}: ${detail}`, hint);
+  return new CliError("DB_ERROR", `${what}: ${detail}`, hintFor(detail));
 }
 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 !== undefined)
-    return requirePath(explicit, "--db");
+    return requireValue(explicit, "--db", "the default database");
   const fromEnv = process.env.OURA_DB_PATH;
   if (fromEnv !== undefined)
-    return requirePath(fromEnv, "OURA_DB_PATH");
+    return requireValue(fromEnv, "OURA_DB_PATH", "the default database");
   return resolve(homedir(), ".oura-cli", "oura.db");
 }
 function openDatabase(explicit) {
@@ -1439,15 +1456,31 @@ function openDatabase(explicit) {
     if (isNew)
       chmodSync(dbPath, 384);
     db.exec(`PRAGMA busy_timeout = ${BUSY_TIMEOUT_MS}`);
-    const mode = db.query("PRAGMA journal_mode").get();
-    if (mode.journal_mode !== "wal")
-      db.exec("PRAGMA journal_mode = WAL");
+    if (journalMode(db) !== "wal")
+      enableWal(db);
     db.exec("PRAGMA foreign_keys = ON");
     return db;
   } catch (err) {
     throw dbError(`Cannot open database ${dbPath}`, err);
   }
 }
+function journalMode(db) {
+  return db.query("PRAGMA journal_mode").get().journal_mode;
+}
+function enableWal(db) {
+  for (let attempt = 0;; attempt++) {
+    try {
+      db.exec("PRAGMA journal_mode = WAL");
+      return;
+    } catch (err) {
+      if (journalMode(db) === "wal")
+        return;
+      if (attempt >= WAL_SWITCH_ATTEMPTS)
+        throw err;
+      Bun.sleepSync(WAL_SWITCH_WAIT_MS + Math.random() * WAL_SWITCH_WAIT_MS);
+    }
+  }
+}
 function schemaVersion(db) {
   db.exec("CREATE TABLE IF NOT EXISTS _schema_version (version INTEGER NOT NULL)");
   const row = db.query("SELECT MAX(version) AS v FROM _schema_version").get();
@@ -1455,12 +1488,23 @@ function schemaVersion(db) {
 }
 function ensureSchema(db, migrations = MIGRATIONS) {
   try {
-    const current = schemaVersion(db);
-    for (const m of migrations) {
-      if (m.version > current) {
-        db.exec(m.sql);
-        db.query("INSERT INTO _schema_version (version) VALUES (?)").run(m.version);
+    if (schemaVersion(db) >= Math.max(0, ...migrations.map((m) => m.version)))
+      return;
+    db.exec("BEGIN IMMEDIATE");
+    try {
+      const current = schemaVersion(db);
+      for (const m of migrations) {
+        if (m.version > current) {
+          db.exec(m.sql);
+          db.query("INSERT INTO _schema_version (version) VALUES (?)").run(m.version);
+        }
       }
+      db.exec("COMMIT");
+    } catch (err) {
+      try {
+        db.exec("ROLLBACK");
+      } catch {}
+      throw err;
     }
   } catch (err) {
     throw dbError("Schema migration failed", err);
@@ -1475,10 +1519,11 @@ function defaultTokenPath() {
   return process.env.OURA_TOKEN_PATH ?? resolve2(homedir2(), ".oura-token");
 }
 function resolveToken(explicit, tokenPath) {
-  if (explicit)
-    return { token: explicit.trim(), source: "--token" };
-  if (process.env.OURA_TOKEN)
-    return { token: process.env.OURA_TOKEN.trim(), source: "OURA_TOKEN" };
+  if (explicit !== undefined)
+    return { token: requireValue(explicit, "--token", "the token file").trim(), source: "--token" };
+  const fromEnv = process.env.OURA_TOKEN;
+  if (fromEnv !== undefined)
+    return { token: requireValue(fromEnv, "OURA_TOKEN", "the token file").trim(), source: "OURA_TOKEN" };
   const path = tokenPath ?? defaultTokenPath();
   try {
     return { token: readFileSync(path, "utf-8").trim(), source: path };
@@ -1685,8 +1730,9 @@ function localDateToUtcRange(localDate, timezone) {
   return [iso(localMidnightMs(localDate, timezone)), iso(localMidnightMs(shiftDay(localDate, 1), timezone))];
 }
 function resolveDefaultTimezone() {
-  if (process.env.OURA_TZ)
-    return process.env.OURA_TZ;
+  const fromEnv = process.env.OURA_TZ;
+  if (fromEnv !== undefined)
+    return requireValue(fromEnv, "OURA_TZ", "the system timezone");
   try {
     return Intl.DateTimeFormat().resolvedOptions().timeZone || "UTC";
   } catch {
@@ -1973,7 +2019,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 }
   ]
 });
 
@@ -2345,6 +2392,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]) });
@@ -2374,13 +2439,15 @@ function rangeQueries(c, start, end, tz) {
     return [];
   return c.rangeParams === "date" ? dateQueries(start, end, c.maxRangeDays, c.dayRangeOffset ?? [0, 0]) : datetimeQueries(start, end, tz, c.maxRangeDays);
 }
-async function fetchCollection(client, c, start, end, tz) {
-  const rows = [];
+async function fetchCollectionByPiece(client, c, start, end, tz) {
+  const pieces = [];
   for (const query of rangeQueries(c, start, end, tz)) {
-    for (const row of await client.fetch(c.endpoint, query))
-      rows.push(row);
+    pieces.push(await client.fetch(c.endpoint, query));
   }
-  return rows;
+  return pieces;
+}
+async function fetchCollection(client, c, start, end, tz) {
+  return (await fetchCollectionByPiece(client, c, start, end, tz)).flat();
 }
 
 // src/commands/describe.ts
@@ -2482,15 +2549,107 @@ function describeCommand(version, getCommands) {
   });
 }
 
+// src/db/reconcile.ts
+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 keyOf(values) {
+  return values.map((v) => String(v)).join(KEY_SEPARATOR);
+}
+function planWindow(db, c, pieces, options = {}) {
+  const identity = identityColumns(c);
+  if (identity.length === 0)
+    return emptyPlan();
+  const pickOf = (name) => c.columns.find((col) => col.name === name)?.pick;
+  const identityPicks = identity.map(pickOf);
+  const scopeName = c.rangeParams === "datetime" ? "timestamp" : "day";
+  const scopePick = pickOf(scopeName);
+  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 plan = emptyPlan();
+  const judged = pieces.map((piece) => {
+    if (piece.length === 0)
+      return null;
+    const scopeValues = piece.map((row) => scopePick(row)).filter((v) => v !== null && v !== undefined).map(String);
+    if (scopeValues.length === 0)
+      return null;
+    const days = [...new Set(scopeValues)];
+    const [where, params] = c.rangeParams === "datetime" ? [`${scopeName} BETWEEN ? AND ?`, [minOf(scopeValues), maxOf(scopeValues)]] : [`${scopeName} IN (${days.map(() => "?").join(", ")})`, days];
+    const stored = db.query(`SELECT ${identity.join(", ")} FROM ${c.table} WHERE ${where}`).all(...params);
+    const storedKeys = new Set;
+    const stale = [];
+    for (const row of stored) {
+      const values = identity.map((name) => row[name] ?? null);
+      const key = keyOf(values);
+      storedKeys.add(key);
+      if (!wanted.has(key))
+        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));
+    return { stale, looksTruncated, fresh };
+  });
+  const doubted = new Set;
+  for (const p of judged) {
+    if (p?.looksTruncated)
+      for (const values of p.stale)
+        doubted.add(keyOf(values));
+  }
+  const countedNew = new Set;
+  const countedStale = new Set;
+  for (const p of judged) {
+    if (p === null)
+      continue;
+    for (const key of p.fresh) {
+      if (countedNew.has(key))
+        continue;
+      countedNew.add(key);
+      plan.added += 1;
+    }
+    for (const values of p.stale) {
+      const key = keyOf(values);
+      if (countedStale.has(key))
+        continue;
+      countedStale.add(key);
+      if (doubted.has(key) && !options.prune) {
+        plan.refused += 1;
+      } else {
+        if (doubted.has(key))
+          plan.bypassed += 1;
+        plan.stale.push(values);
+      }
+    }
+  }
+  return plan;
+}
+function applyWindowPlan(db, c, plan) {
+  if (plan.stale.length === 0)
+    return 0;
+  const identity = identityColumns(c);
+  const del = db.query(`DELETE FROM ${c.table} WHERE ${identity.map((name) => `${name} IS ?`).join(" AND ")}`);
+  let removed = 0;
+  for (const values of plan.stale)
+    removed += del.run(...values).changes;
+  return removed;
+}
+function minOf(values) {
+  return values.reduce((a, b) => b < a ? b : a);
+}
+function maxOf(values) {
+  return values.reduce((a, b) => b > a ? b : a);
+}
+
 // src/db/sync.ts
 var BACKFILL_DAYS = 30;
 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;
-}
-async function importDaily(db, client, clock, log, window = {}) {
+async function importDaily(db, client, clock, log, window = {}, options = {}) {
   const { today, tz } = clock;
   const _log = log ?? (() => {});
   const end = window.to ?? today;
@@ -2505,10 +2664,25 @@ async function importDaily(db, client, clock, log, window = {}) {
   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}`);
+  if (options.prune !== undefined) {
+    const scope = options.prune === "all" ? "every collection" : options.prune.join(", ");
+    _log(`--prune: applying removals even where a response looks truncated (${scope})`);
+  }
   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 rows = await fetchCollection(client, c, start, end, tz);
+    const returned = await fetchCollectionByPiece(client, c, start, end, tz);
+    const pieces = returned.map((piece) => piece.filter((r) => hasIdentity(c, r)));
+    const rows = pieces.flat();
+    const missing = returned.flat().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;
@@ -2516,31 +2690,86 @@ async function importDaily(db, client, clock, log, window = {}) {
         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 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;
-    _log(`  + ${c.name} (${c.table}): ${rows.length} fetched, ${added[c.table]} new`);
+    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)
+          stmt.run(...rowValues(c, r));
+      return { windowPlan, gone: applyWindowPlan(db, c, windowPlan) };
+    }).immediate(pieces);
+    fetched[c.table] = rows.length + missing;
+    added[c.table] = windowPlan.added;
+    if (gone > 0)
+      removed[c.table] = gone;
+    if (windowPlan.refused > 0)
+      refused[c.table] = { rows: windowPlan.refused, collection: c.name };
+    if (windowPlan.bypassed > 0)
+      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}): ${fetched[c.table]} fetched, ${added[c.table]} new${droppedTail}${tail}${kept}`);
   }
   _log("Import complete.");
-  return { startDate, endDate: end, fetched, added, isFirstSync };
+  return {
+    startDate,
+    endDate: end,
+    fetched,
+    added,
+    removed,
+    dropped,
+    refused,
+    pruned,
+    isFirstSync,
+    ...options.prune === undefined ? {} : { pruneScope: options.prune }
+  };
+}
+
+// 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);
@@ -2549,6 +2778,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,
@@ -2567,15 +2797,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 });
     }
@@ -2726,12 +2958,13 @@ 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) => `${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 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)} ${padRight(d.stress ?? "\u2014", 10)}`);
+  const note = days.some((d) => d.partial) ? ["  * still accumulating; its activity totals are not final."] : [];
   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 = [
@@ -2739,13 +2972,15 @@ function formatTrends(trends, days, format) {
     source_default.bold(`  Trends: last ${days} days`),
     source_default.gray("\u2500".repeat(50))
   ];
+  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(`
 `);
 }
-function formatStats(stats, format) {
+function formatStats(stats, format, emptyHint) {
   if (format === "json")
     return JSON.stringify(stats, null, 2);
   const lines = [
@@ -2753,6 +2988,10 @@ function formatStats(stats, format) {
     source_default.bold("  Database Statistics"),
     source_default.gray("\u2550".repeat(50))
   ];
+  if (emptyHint && stats.tables.every((t) => t.rows === 0)) {
+    return [...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`);
   }
@@ -2788,26 +3027,49 @@ function resolveWindow(opts, today) {
   }
   return { from, to };
 }
-async function runSync(ctx, window = {}) {
+var PRUNE_ALL = "all";
+function resolvePruneScope(value) {
+  if (value === undefined || value === false)
+    return;
+  const raw = value === true ? "" : String(value);
+  const wanted = raw.split(",").map((s) => s.trim()).filter((s) => s !== "");
+  if (wanted.length === 0 || wanted.some((n) => n.startsWith("-"))) {
+    throw new CliError("BAD_ARGS", "--prune needs a value naming what to prune.", `Use --prune=<collection> (for example --prune=hr), a comma-separated list, or --prune=${PRUNE_ALL} for every collection.`);
+  }
+  if (wanted.includes(PRUNE_ALL)) {
+    if (wanted.length === 1)
+      return PRUNE_ALL;
+    throw new CliError("BAD_ARGS", `--prune=${PRUNE_ALL} cannot be combined with collection names.`, `Use --prune=${PRUNE_ALL} on its own, or list the collections you mean.`);
+  }
+  const unknown = wanted.filter((n) => byName(n) === undefined);
+  if (unknown.length > 0) {
+    throw new CliError("BAD_ARGS", `--prune: unknown collection${unknown.length > 1 ? "s" : ""}: ${unknown.join(", ")}.`, `Known collections: ${names().join(", ")}.`);
+  }
+  return [...new Set(wanted)];
+}
+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);
-  const today = getDaySummary(ctx.db, ctx.today);
+  const importResult = await importDaily(ctx.db, ctx.client, { today: ctx.today, tz: ctx.tz }, log, window, options);
+  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(`
 `)
   };
 }
-var syncCommand = dataCommand({
+var syncArgs = {
+  from: { type: "string", description: "Re-fetch every collection from this day (YYYY-MM-DD) instead of from its last stored day" },
+  to: { type: "string", description: "End of the explicit window (YYYY-MM-DD, default: today); requires --from" },
+  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" },
-  args: {
-    from: { type: "string", description: "Re-fetch every collection from this day (YYYY-MM-DD) instead of from its last stored day" },
-    to: { type: "string", description: "End of the explicit window (YYYY-MM-DD, default: today); requires --from" }
-  },
+  args: syncArgs,
   needs: { db: true, client: true },
-  run: (ctx, args) => runSync(ctx, resolveWindow({ from: args.from, to: args.to }, ctx.today))
-});
+  run: (ctx, args) => runSync(ctx, resolveWindow({ from: args.from, to: args.to }, ctx.today), { prune: resolvePruneScope(args.prune) })
+};
+var syncCommand = dataCommand(syncDef);
 
 // 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.";
@@ -2818,7 +3080,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) };
       }
     }),
@@ -2828,7 +3090,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") };
       }
     }),
@@ -2836,7 +3098,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.") };
       }
     }),
@@ -2847,7 +3110,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({
@@ -2855,7 +3118,7 @@ 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.") };
       }
     })
   }
@@ -2878,9 +3141,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) {
@@ -2894,7 +3156,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 = [
@@ -2995,8 +3257,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);
@@ -3004,6 +3266,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,
@@ -3011,13 +3274,17 @@ 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}.`;
 }
@@ -3032,7 +3299,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("");
@@ -3054,16 +3322,15 @@ function formatReport(data, format, period) {
     }
     lines.push("");
   } 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)));
+    lines.push(source_default.gray("  " + "\u2500".repeat(69)));
+    lines.push(`  ${"Week of".padEnd(21)} ${"Sleep".padStart(6)} ${"Ready".padStart(6)} ${"Active".padStart(7)} ${"Steps".padStart(10)}`);
+    lines.push(source_default.gray("  " + "\u2500".repeat(69)));
     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)}`);
+      lines.push(`  ${bucketLabel(b).padEnd(21)} ${scoreCell(avgSleepInt, 6)} ${scoreCell(avgReadyInt, 6)} ${scoreCell(avgActiveInt, 7)} ${stepsCell(b.totalSteps, 10)}`);
     }
     lines.push("");
   }
@@ -3132,7 +3399,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}, plus error when ok is false)." },
+    meta: { name: "healthcheck", description: "Fast liveness probe: opens the local database and runs one query (JSON: {ok, version, latencyMs}, plus error when ok is false). It proves the file opens, not that its contents are intact \u2014 `doctor` checks that." },
     args: { ...commonArgs },
     run({ args }) {
       assertKnownArgs(commonArgs, args);
@@ -3213,8 +3480,18 @@ async function runChecks(deps) {
     checks.push({ id: "database", status: "fail", detail: msg });
   }
   if (db) {
-    const last = latestDataDay(db);
-    if (!last) {
+    const damage = quickCheck(db);
+    checks.push(damage === null ? { id: "integrity", status: "ok", detail: "Database passes SQLite quick_check." } : { id: "integrity", status: "fail", detail: `Database is damaged: ${damage}`, fix: "Delete the cache file (--db / OURA_DB_PATH) and run `oura-cli sync` to rebuild it." });
+    let last = null;
+    let readFailed;
+    try {
+      last = latestDataDay(db);
+    } catch (err) {
+      readFailed = err instanceof Error ? err.message : String(err);
+    }
+    if (readFailed !== undefined) {
+      checks.push({ id: "data", status: "fail", detail: `Cannot read the cache: ${readFailed}`, fix: "Delete the cache file (--db / OURA_DB_PATH) and run `oura-cli sync` to rebuild it." });
+    } 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);
@@ -3225,6 +3502,7 @@ async function runChecks(deps) {
       }
     }
   } else {
+    checks.push({ id: "integrity", status: "fail", detail: "Cannot check integrity \u2014 database unavailable." });
     checks.push({ id: "data", status: "fail", detail: "Cannot check data \u2014 database unavailable." });
   }
   db?.close();
@@ -3233,6 +3511,15 @@ async function runChecks(deps) {
   const nextStep = checks.find((c) => !settled(c.status))?.fix ?? null;
   return { ok, checks, nextStep };
 }
+function quickCheck(db) {
+  try {
+    const rows = db.query("PRAGMA quick_check(1)").all();
+    const first = rows[0] === undefined ? "ok" : Object.values(rows[0])[0] ?? "ok";
+    return first === "ok" ? null : first;
+  } catch (err) {
+    return err instanceof Error ? err.message : String(err);
+  }
+}
 var DATA_TABLES = ["daily_sleep", "daily_readiness", "daily_activity"];
 function latestDataDay(db) {
   let latest = null;
@@ -3373,9 +3660,54 @@ var fetchCommand = dataCommand({
   }
 });
 
+// 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;
+}
+
 // src/lib/citty-error.ts
 var ANSI2 = /\u001b\[[0-9;]*m/g;
-function fromCittyError(err, removedCommandHints = {}) {
+var COMMAND_NAME = /^[a-z][a-z0-9-]{0,19}$/;
+function editDistanceAtMostOne(a, b) {
+  if (Math.abs(a.length - b.length) > 1)
+    return false;
+  let i = 0, j = 0, edits = 0;
+  while (i < a.length && j < b.length) {
+    if (a[i] === b[j]) {
+      i++;
+      j++;
+      continue;
+    }
+    if (++edits > 1)
+      return false;
+    if (a.length > b.length)
+      i++;
+    else if (a.length < b.length)
+      j++;
+    else {
+      i++;
+      j++;
+    }
+  }
+  return edits + (a.length - i) + (b.length - j) <= 1;
+}
+function nearestGlobalFlag(token) {
+  if (!token.startsWith("--") || token.length < 4)
+    return;
+  return [...GLOBAL_FLAGS_WITH_VALUE].find((flag) => flag !== token && (editDistanceAtMostOne(flag, token) || flag.startsWith(token)));
+}
+function fromCittyError(err, removedCommandHints = {}, rawArgs = []) {
   const code = err?.code;
   if (typeof code !== "string")
     return err;
@@ -3383,6 +3715,14 @@ function fromCittyError(err, removedCommandHints = {}) {
   switch (code) {
     case "E_UNKNOWN_COMMAND": {
       const name = message.replace(/^Unknown command\s*/, "").trim();
+      const before = rawArgs[rawArgs.lastIndexOf(name) - 1];
+      const meant = before === undefined ? undefined : nearestGlobalFlag(before);
+      if (meant) {
+        return new CliError("BAD_ARGS", `Unknown flag "${before}".`, `Did you mean ${meant}? Its value was read as a command name.`);
+      }
+      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.";
       return new CliError("BAD_ARGS", `Unknown command "${name}".`, hint);
     }
@@ -3397,17 +3737,7 @@ function fromCittyError(err, removedCommandHints = {}) {
 
 // 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 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.",
@@ -3437,7 +3767,7 @@ if (isVersionRequest(rawArgs)) {
   runMain(main, { rawArgs });
 } else {
   runCommand(main, { rawArgs }).catch((raw) => {
-    const err = fromCittyError(raw, REMOVED_COMMANDS);
+    const err = fromCittyError(raw, REMOVED_COMMANDS, rawArgs);
     emitError(err, formatFromArgv(rawArgs, process.stdout.isTTY === true));
     process.exit(exitCodeFor(err));
   });

package/docs/schemas/doctor.json

@@ -13,7 +13,7 @@
         "required": ["id", "status", "detail"],
         "additionalProperties": false,
         "properties": {
-          "id":     { "type": "string", "enum": ["token", "token-valid", "database", "data"] },
+          "id":     { "type": "string", "enum": ["token", "token-valid", "database", "integrity", "data"] },
           "status": { "type": "string", "enum": ["ok", "warn", "fail", "skip"] },
           "detail": { "type": "string" },
           "fix":    { "type": "string" }

package/package.json

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