things-api 0.8.0 → 0.10.0

package/dist/cli/commands/reads.js

@@ -1,162 +1,21 @@
-import { execFileSync } from "node:child_process";
-import { openThings } from "../../client.js";
-import { ThingsDbNotFoundError } from "../../db/locate.js";
-import { ThingsDbOpenError } from "../../db/connection.js";
-import { isTodayMember } from "../../read/views.js";
-import { localToday } from "../../model/dates.js";
-import { templateStatus } from "../../model/recurrence.js";
-import { blue, bold, dim, strike, underline } from "../style.js";
-import { areaMark, CHECKLIST_MARK, countChip, dateChip, deadlineToken, eveningMoon, loggedDate, NOTES_MARK, projectCircle, REMINDER_MARK, shortDate, todayStar, todoBox, } from "../glyphs.js";
-import { errorEnvelope, ExitCode, okEnvelope } from "../../contracts.js";
-export function withClient(opts, kind, fn, render) {
-    const started = Date.now();
-    let client = null;
-    try {
-        client = openThings(opts.db ? { dbPath: opts.db } : {});
-        const fp = client.fingerprint();
-        const data = fn(client);
-        const meta = {
-            dbVersion: fp.observation.databaseVersion,
-            fingerprint: fp.kind === "ok" ? "ok" : fp.kind === "drift" ? "drift" : "unknown",
-            elapsedMs: Date.now() - started,
-        };
-        if (fp.kind !== "ok") {
-            process.stderr.write(`warning: schema fingerprint ${meta.fingerprint} — reads best-effort, writes disabled (run \`things doctor\`)\n`);
-        }
-        if (opts.json) {
-            process.stdout.write(`${JSON.stringify(okEnvelope(kind, data, meta))}\n`);
-        }
-        else {
-            process.stdout.write(`${render(data).join("\n")}\n`);
-        }
-        process.exitCode = ExitCode.Ok;
-    }
-    catch (err) {
-        const meta = {
-            dbVersion: null,
-            fingerprint: "unknown",
-            elapsedMs: Date.now() - started,
-        };
-        const isEnv = err instanceof ThingsDbNotFoundError || err instanceof ThingsDbOpenError;
-        const message = err instanceof Error ? err.message : String(err);
-        if (opts.json) {
-            process.stdout.write(`${JSON.stringify(errorEnvelope({ code: isEnv ? "environment" : "unexpected", message }, meta))}\n`);
-        }
-        else {
-            process.stderr.write(`error: ${message}\n`);
-        }
-        process.exitCode = isEnv ? ExitCode.Environment : ExitCode.Unexpected;
-    }
-    finally {
-        client?.close();
-    }
-}
 /**
- * One item line:
- * `<uuid-prefix>  <box> [★|⏾] [logged-date] [‹chip›] <title> [‹n›] [⍾] [≡] [≔] (container) #tags [⚑ deadline]`.
- * Repeating templates seat ↻ INSIDE the box (`[↻]`/`(↻)`) rather than as a
- * separate mark; open project rows render their circle and title blue.
- * The box is the glyph-language state carrier (../glyphs.ts): `[ ]`-family
- * for to-dos, `( )`-family for projects — state survives with color
- * stripped. Completed titles dim; canceled titles dim+strike (the `[×]`
- * mark keeps the state when strike/ANSI is unavailable). Human output shows
- * a SHORTENED uuid prefix (every command accepts unique prefixes >= 6
- * chars); `uuidWidth` is the display length from uuidDisplayWidth — never
- * below 8 so a copied prefix stays unique across the whole database, not
- * just the rendered list. Tags follow the title (`#`-prefixed, green — GUI
- * color), after the count chip (projects), notes marker, and container.
- * Heading-nested to-dos label their parent PROJECT (via headingProject),
- * never the heading — GUI behavior. Colors engage on a TTY only
- * (../style.ts); `--json` always carries full uuids.
+ * Read-only list commands: option/description wiring per view, delegating to
+ * the read driver (../read-driver.ts) for envelope/output and to the pure
+ * renderers (../render.ts) for human lines. Each command renders a compact
+ * human table (UUIDs always shown — agents and humans both need stable
+ * references) or a --json envelope.
  */
-export function formatItem(item, uuidWidth = 0, opts = {}) {
-    const todayIso = localToday(opts.now);
-    const asTitle = opts.projectTitle === true && item.type === "project";
-    const box = item.type === "project" ? projectCircle(item) : todoBox(item);
-    const meta = [];
-    if (opts.mark != null)
-        meta.push(opts.mark);
-    // ↻ now lives INSIDE the box for templates (glyphs.ts) — no separate mark.
-    if (opts.statusWord !== undefined)
-        meta.push(dim(opts.statusWord));
-    if (item.status !== "open" && item.stopped !== null)
-        meta.push(loggedDate(item.stopped, todayIso));
-    if (opts.hideDateChip === true) {
-        // rows under a day header — the header carries the date
-    }
-    else if (item.status === "open" && item.startDate !== null && item.startDate > todayIso)
-        meta.push(dateChip(item.startDate, todayIso));
-    // Repeating templates chip their app-materialized next occurrence.
-    else if (item.repeating.isTemplate && item.repeating.nextOccurrence != null)
-        meta.push(dateChip(item.repeating.nextOccurrence, todayIso));
-    // List rows mute their tags (the GUI's gray pills); tags go green only on
-    // the opened resource (todo show / the project|area header row).
-    const tags = item.tags.length > 0 ? ` ${dim(`#${item.tags.map((t) => t.title).join(" #")}`)}` : "";
-    // Closed rows drop the deadline flag — a months-old red "n days ago" on a
-    // logged item is noise (the GUI doesn't flag logbook rows either). Raw
-    // template rows drop it via the sentinel guard: their deadline column
-    // carries app-internal 4001-01-01 sentinels (upcoming's synthesized
-    // occurrences carry REAL rule-derived deadlines and must keep the flag).
-    const rule = item.repeating.rule;
-    const deadline = item.status === "open" && item.deadline !== null && item.deadline < "4000"
-        ? ` ${deadlineToken(item.deadline, todayIso)}`
-        : // The GUI's bare flag on no-date repeating templates: the rule WILL
-            // assign each occurrence a deadline (fixed rules always do; after-
-            // completion only with a start offset), date unknown until spawned.
-            item.repeating.isTemplate &&
-                rule !== undefined &&
-                (rule.type === "fixed" || rule.startOffsetDays < 0)
-                ? ` ${bold(dim("⚑"))}`
-                : "";
-    const container = item.type === "to-do" ? (item.project ?? item.headingProject ?? null) : null;
-    const context = container !== null
-        ? container.uuid === opts.suppressProject
-            ? ""
-            : ` (${container.title})`
-        : item.area
-            ? item.area.uuid === opts.suppressArea
-                ? ""
-                : ` (${item.area.title})`
-            : "";
-    const shownUuid = uuidWidth > 0 && item.uuid.length > uuidWidth
-        ? item.uuid.slice(0, uuidWidth)
-        : item.uuid.padEnd(uuidWidth);
-    let title = item.title;
-    if (asTitle)
-        title = bold(underline(title));
-    else if (item.status === "canceled")
-        title = dim(strike(title));
-    else if (item.status === "completed")
-        title = dim(title);
-    // Open project rows render their title blue — GUI parity (list accent) and
-    // a color cue reinforcing the round bracket. To-dos stay default-colored.
-    else if (item.type === "project")
-        title = blue(title);
-    // GUI indicator order after the title: bell, document, checklist.
-    const tail = [
-        ...(item.type === "project" ? [countChip(item)] : []),
-        ...(item.reminder !== null ? [dim(REMINDER_MARK)] : []),
-        ...(item.notes !== "" ? [dim(NOTES_MARK)] : []),
-        ...(item.type === "to-do" && item.checklistItemsCount > 0 ? [dim(CHECKLIST_MARK)] : []),
-    ];
-    return [
-        `${dim(shownUuid)} `,
-        box,
-        ...meta,
-        `${title}${tail.length > 0 ? ` ${tail.join(" ")}` : ""}${tags}${context === "" ? "" : dim(context)}${deadline}`,
-    ].join(" ");
-}
-/**
- * Row prefix in today-aware views: yellow ★ for Today members, cyan ⏾ for
- * effective This-Evening members (raw evening assignment counts only while
- * startDate is exactly today — the UI's daily expiry), null otherwise.
- */
-export function todayMark(item, now) {
-    if (!isTodayMember(item, now))
-        return null;
-    const evening = item.todaySection === "evening" && item.startDate === localToday(now);
-    return evening ? eveningMoon() : todayStar();
-}
+import { Option } from "commander";
+import { execFileSync } from "node:child_process";
+import { runAreaShow } from "./area.js";
+import { runProjectShow } from "./project.js";
+import { dim } from "../style.js";
+import { areaMark, LEGEND, shortDate } from "../glyphs.js";
+import { formatItem, disclosureHint, renderAnytimePreview, renderLegend, renderList, renderLogbook, renderProjectsSidebar, renderSearch, renderSections, renderSomedayPreview, renderToday, renderUpcoming, stripAnsi, uuidCol, uuidDisplayWidth, } from "../render.js";
+import { invocation, parseCap, parseLimit, runRead, shellQuote, truncationHint, usageError, withClient, } from "../read-driver.js";
+import { addTagFilterOptions, collectRef, CONTAINER_TAG_HINT, EXACT_TAG_DESC, hasTagPresence, TAG_DESC, UNTAGGED_DESC, tagFilterFields, tagFlagConflict, tagInvocationParts, } from "../tag-filters.js";
+import { doublePeriod, parsePeriodEnd, parsePeriodStart } from "../period.js";
+import { ALL_DESC, AREA_LIMIT_DESC, AREA_PREVIEW_LIMIT, ExitCode, FILTER_CONTRACT, GROUPED_ALL_DESC, LIMIT_DESC, localToday, okEnvelope, PERIOD_SINCE, PERIOD_UNTIL, PROJECT_LIMIT_DESC, PROJECT_PREVIEW_LIMIT, validateViewArgs, } from "../../index.js";
 /**
  * Foreground the Things app on a resource via its share URI. A GUI action
  * on this Mac — NOT headless; the shared implementation behind every
@@ -167,389 +26,291 @@ export function openInThings(uuid) {
     execFileSync("/usr/bin/open", [uri]);
     return uri;
 }
-/** Minimum displayed-prefix length: shorter prefixes collide across the DB. */
-const UUID_DISPLAY_MIN = 8;
-/**
- * Display width for a list's uuid column: the shortest prefix that is
- * unique WITHIN the list, floored at UUID_DISPLAY_MIN (list-local
- * uniqueness at 2–3 chars would still collide database-wide).
- */
-export function uuidDisplayWidth(items) {
-    if (items.length === 0)
-        return UUID_DISPLAY_MIN;
-    const sorted = items.map((i) => i.uuid).toSorted();
-    let needed = 1;
-    for (let i = 1; i < sorted.length; i++) {
-        const a = sorted[i - 1] ?? "";
-        const b = sorted[i] ?? "";
-        let common = 0;
-        while (common < a.length && common < b.length && a[common] === b[common])
-            common++;
-        needed = Math.max(needed, common + 1);
-    }
-    return Math.max(UUID_DISPLAY_MIN, needed);
-}
-function renderList(items) {
-    const w = uuidDisplayWidth(items);
-    return items.length === 0 ? ["(empty)"] : items.map((i) => formatItem(i, w));
-}
-/**
- * The sidebar mirror for `things projects`: loose projects first (the GUI
- * lists them above the areas), then a `── ⬡ Area ──` header per area with
- * its projects beneath (the redundant `(Area)` suffix suppressed). Items
- * arrive from projectsView already in sidebar order — this only inserts the
- * headers. Denser than renderSections on purpose: no title styling and no
- * blank line per project (every row here IS a project). With `hints`,
- * default-hidden later projects are never silent: each group trails a muted
- * `…n later projects` count (a later-only area still gets its header), and
- * the output ends with the flag that reveals them.
- */
-export function renderProjectsSidebar(items, hints) {
-    const total = hints?.groups.reduce((n, g) => n + g.hidden, 0) ?? 0;
-    if (items.length === 0 && total === 0 && (hints === undefined || hints.groups.length === 0))
-        return ["(empty)"];
-    const w = uuidDisplayWidth(items);
-    const byGroup = new Map();
-    for (const item of items) {
-        const key = item.area?.uuid ?? null;
-        byGroup.set(key, [...(byGroup.get(key) ?? []), item]);
-    }
-    // hints (when present) carry the full sidebar group order, including
-    // later-only groups the visible items can't reveal.
-    const groups = hints?.groups ??
-        [...byGroup.keys()].map((key) => ({
-            area: key === null ? null : (items.find((i) => i.area?.uuid === key)?.area ?? null),
-            hidden: 0,
-        }));
-    const lines = [];
-    for (const group of groups) {
-        const rows = byGroup.get(group.area?.uuid ?? null) ?? [];
-        // The loose block only exists when it has content; areas mirror the
-        // sidebar and render even when empty.
-        if (group.area === null && rows.length === 0 && group.hidden === 0)
-            continue;
-        if (group.area !== null) {
-            if (lines.length > 0)
-                lines.push("");
-            lines.push(`${bold("──")} ${areaMark()} ${bold(`${group.area.title} ──`)}`);
+/** Help copy for the `--overdue` content scope (open items past their deadline). */
+const OVERDUE_DESC = "only open items past their deadline (due today is not overdue)";
+export function registerReadCommands(program) {
+    program
+        .command("legend")
+        .description("The symbols and colors the list views use, grouped and explained: to-do boxes and " +
+        "project circles, markers and chips, colors and styles, section dividers and hints. " +
+        "Human-readable by default; --json emits {glyph, meaning, group} rows.")
+        .option("--json", "emit versioned JSON envelope on stdout")
+        .action((opts) => {
+        const started = Date.now();
+        if (opts.json) {
+            const entries = LEGEND.map((e) => ({
+                glyph: stripAnsi(e.glyph),
+                meaning: e.meaning,
+                group: e.group,
+            }));
+            const meta = {
+                dbVersion: null,
+                fingerprint: "unknown",
+                elapsedMs: Date.now() - started,
+            };
+            process.stdout.write(`${JSON.stringify(okEnvelope("legend", entries, meta))}\n`);
         }
-        lines.push(...rows.map((item) => formatItem(item, w, { suppressArea: group.area?.uuid ?? null })));
-        if (group.hidden > 0)
-            lines.push(dim(`…${group.hidden} later project${group.hidden === 1 ? "" : "s"}`));
-        else if (group.area !== null && rows.length === 0)
-            lines.push(dim("(no projects)"));
-    }
-    if (total > 0)
-        lines.push("", dim(`(${total} later project${total === 1 ? "" : "s"} — visible with \`things projects --show-later\`)`));
-    return lines;
-}
-const FULL_MONTHS = [
-    "January",
-    "February",
-    "March",
-    "April",
-    "May",
-    "June",
-    "July",
-    "August",
-    "September",
-    "October",
-    "November",
-    "December",
-];
-/**
- * Relative period: `3d`/`2w`/`1m`/`1y` (days/weeks/calendar months/years),
- * counted from `now` — FORWARD for an until-bound, BACKWARD for a since-
- * bound (each command's natural direction; the flag name carries it).
- */
-const RELATIVE_PERIOD = /^(\d+)([dwmy])$/i;
-function relativePeriodDate(m, now, sign) {
-    const n = sign * Number(m[1]);
-    const unit = (m[2] ?? "").toLowerCase();
-    const d = new Date(now);
-    if (unit === "d")
-        d.setDate(d.getDate() + n);
-    else if (unit === "w")
-        d.setDate(d.getDate() + 7 * n);
-    else if (unit === "m")
-        d.setMonth(d.getMonth() + n);
-    else
-        d.setFullYear(d.getFullYear() + n);
-    return d;
-}
-/**
- * `--until` accepting whole periods: `2024` means through Dec 31 2024,
- * `2024-03` through Mar 31, `2024-03-05` through end of that day; relative
- * periods (`2w`, `1m`, `1y`) count FORWARD from now through the end of the
- * landing day; anything else parses as an instant.
- */
-export function parsePeriodEnd(s, now = new Date()) {
-    const rel = RELATIVE_PERIOD.exec(s.trim());
-    if (rel !== null) {
-        const d = relativePeriodDate(rel, now, 1);
-        return new Date(d.getFullYear(), d.getMonth(), d.getDate(), 23, 59, 59, 999);
-    }
-    const m = /^(\d{4})(?:-(\d{2})(?:-(\d{2}))?)?$/.exec(s.trim());
-    if (m === null)
-        return new Date(s);
-    const year = Number(m[1]);
-    // Day 0 of month n+1 = the last day of month n.
-    if (m[2] === undefined)
-        return new Date(year, 11, 31, 23, 59, 59, 999);
-    const month = Number(m[2]) - 1;
-    if (m[3] === undefined)
-        return new Date(year, month + 1, 0, 23, 59, 59, 999);
-    return new Date(year, month, Number(m[3]), 23, 59, 59, 999);
-}
-/**
- * `--since` accepting the same vocabulary at the period's START: `2024` =
- * Jan 1 2024 00:00, `2024-03` = Mar 1, `2024-03-05` = that midnight;
- * relative periods (`2w`, `1m`) count BACKWARD from now to the landing
- * day's midnight; anything else parses as an instant.
- */
-export function parsePeriodStart(s, now = new Date()) {
-    const rel = RELATIVE_PERIOD.exec(s.trim());
-    if (rel !== null) {
-        const d = relativePeriodDate(rel, now, -1);
-        return new Date(d.getFullYear(), d.getMonth(), d.getDate());
-    }
-    const m = /^(\d{4})(?:-(\d{2})(?:-(\d{2}))?)?$/.exec(s.trim());
-    if (m === null)
-        return new Date(s);
-    const year = Number(m[1]);
-    if (m[2] === undefined)
-        return new Date(year, 0, 1);
-    const month = Number(m[2]) - 1;
-    if (m[3] === undefined)
-        return new Date(year, month, 1);
-    return new Date(year, month, Number(m[3]));
-}
-const WEEKDAYS = ["Sun", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat"];
-const SHORT_MONTHS = [
-    "Jan",
-    "Feb",
-    "Mar",
-    "Apr",
-    "May",
-    "Jun",
-    "Jul",
-    "Aug",
-    "Sep",
-    "Oct",
-    "Nov",
-    "Dec",
-];
-/**
- * GUI-style Upcoming bucket for a date, granularity decaying with distance:
- * individual days for the next week ("Wed Jul 15"), the remainder of the
- * current month ("Jul 19–31"), months through the end of NEXT year
- * ("August", "January 2027"), then bare years ("2028").
- */
-function upcomingBucket(iso, todayIso) {
-    const [y, m, d] = iso.split("-").map(Number);
-    const [y0, m0, d0] = todayIso.split("-").map(Number);
-    const diff = Math.round((Date.UTC(y ?? 0, (m ?? 1) - 1, d ?? 1) - Date.UTC(y0 ?? 0, (m0 ?? 1) - 1, d0 ?? 1)) /
-        86_400_000);
-    if (diff <= 7) {
-        const weekday = WEEKDAYS[new Date(Date.UTC(y ?? 0, (m ?? 1) - 1, d ?? 1)).getUTCDay()];
-        return { label: `${weekday} ${SHORT_MONTHS[(m ?? 1) - 1]} ${d}`, isDay: true };
-    }
-    if (y === y0 && m === m0) {
-        const lastDay = new Date(y ?? 0, m ?? 1, 0).getDate();
-        return { label: `${SHORT_MONTHS[(m ?? 1) - 1]} ${(d0 ?? 1) + 8}–${lastDay}`, isDay: false };
-    }
-    if ((y ?? 0) <= (y0 ?? 0) + 1) {
-        const month = FULL_MONTHS[(m ?? 1) - 1];
-        return { label: y === y0 ? `${month}` : `${month} ${y}`, isDay: false };
-    }
-    return { label: `${y}`, isDay: false };
-}
-/**
- * Upcoming rows under GUI-style date headers (empty periods are simply
- * absent), with the trailing Repeating To-Dos section: templates with no
- * set next occurrence, carrying their waiting/paused/ended status word and
- * the bare ⚑ when the rule will assign a deadline per occurrence.
- */
-export function renderUpcoming(items, now) {
-    if (items.length === 0)
-        return ["(empty)"];
-    const todayIso = localToday(now);
-    const w = uuidDisplayWidth(items);
-    const fmtOpts = now === undefined ? {} : { now };
-    const dated = items.filter((i) => i.startDate !== null);
-    const resting = items.filter((i) => i.startDate === null && i.repeating.isTemplate);
-    const lines = [];
-    let openHeader = null;
-    for (const item of dated) {
-        const bucket = upcomingBucket(item.startDate ?? "", todayIso);
-        if (bucket.label !== openHeader) {
-            if (lines.length > 0)
-                lines.push("");
-            lines.push(bold(`── ${bucket.label} ──`));
-            openHeader = bucket.label;
+        else {
+            process.stdout.write(`${renderLegend().join("\n")}\n`);
         }
-        lines.push(formatItem(item, w, { ...fmtOpts, hideDateChip: bucket.isDay }));
-    }
-    if (resting.length > 0) {
-        if (lines.length > 0)
-            lines.push("");
-        lines.push(bold("── Repeating To-Dos ──"));
-        for (const item of resting) {
-            lines.push(formatItem(item, w, { ...fmtOpts, statusWord: templateStatus(item.repeating, todayIso) }));
+        process.exitCode = ExitCode.Ok;
+    });
+    program
+        .command("today")
+        .description("The Today list, split into Today and This Evening (evening expires daily), with the sidebar badge split (red = deadline due/overdue)")
+        .option("--tag <ref>", TAG_DESC, collectRef, [])
+        .option("--exact-tag", EXACT_TAG_DESC)
+        .option("--untagged", UNTAGGED_DESC)
+        .option("--overdue", OVERDUE_DESC)
+        .option("--evening", "show only the This Evening section")
+        .option("--limit <n>", LIMIT_DESC)
+        .option("--all", ALL_DESC)
+        .option("--json", "emit versioned JSON envelope on stdout")
+        .option("--db <path>", "explicit database path")
+        .action((opts) => {
+        if (tagFlagConflict(opts))
+            return;
+        const lim = parseLimit(opts);
+        if (!lim.ok)
+            return;
+        const eveningOnly = opts.evening === true;
+        const base = invocation("today", [
+            ...tagInvocationParts(opts),
+            opts.overdue === true && "--overdue",
+            eveningOnly && "--evening",
+        ]);
+        const filter = {
+            ...tagFilterFields(opts),
+            ...(opts.overdue === true && { overdue: true }),
+            ...(eveningOnly && { eveningOnly: true }),
+        };
+        runRead(opts, "today", (c) => {
+            const { view, truncation } = c.read.today({ ...filter, limit: lim.limit });
+            // The renderer keeps This Evening honest under truncation from the
+            // metadata's per-section counts; the lines are precomputed here and
+            // the global footer (whole-view remainder) is appended by the driver.
+            return {
+                data: view,
+                truncation,
+                lines: renderToday(view, truncation.sections, base, { eveningOnly }),
+            };
+        }, 
+        // Type-correct fallback for the TodayView payload; never reached
+        // because `lines` is always precomputed above.
+        (data) => renderToday(data, undefined, base, { eveningOnly }), base, "today");
+    });
+    program
+        .command("inbox")
+        .description("Unprocessed captures (Inbox). Bound the CREATION date with --since/--until — an " +
+        "item's arrival into Things (a demoted item keeps its original creation date, so " +
+        "this is not strictly when it entered the Inbox).")
+        .option("--tag <ref>", TAG_DESC, collectRef, [])
+        .option("--exact-tag", EXACT_TAG_DESC)
+        .option("--untagged", UNTAGGED_DESC)
+        .option("--overdue", OVERDUE_DESC)
+        .option("--since <when>", `only captures created on/after this bound: ${PERIOD_SINCE}`)
+        .option("--until <when>", `only captures created on/before this bound: ${PERIOD_UNTIL}`)
+        .option("--limit <n>", LIMIT_DESC)
+        .option("--all", ALL_DESC)
+        .option("--json", "emit versioned JSON envelope on stdout")
+        .option("--db <path>", "explicit database path")
+        .action((opts) => {
+        if (tagFlagConflict(opts))
+            return;
+        const lim = parseLimit(opts);
+        if (!lim.ok)
+            return;
+        const since = opts.since !== undefined ? parsePeriodStart(opts.since) : undefined;
+        const until = opts.until !== undefined ? parsePeriodEnd(opts.until) : undefined;
+        for (const [flag, value] of [
+            ["--since", since],
+            ["--until", until],
+        ]) {
+            if (value !== undefined && Number.isNaN(value.getTime())) {
+                usageError(opts, `${flag} is not a parseable date`);
+                return;
+            }
         }
-    }
-    return lines;
-}
-/**
- * Logbook rows under GUI-style date headings, month granularity throughout
- * — `── July ──` within the current year, `── March 2025 ──` beyond (finer
- * than the GUI's bare per-year buckets, deliberately). When the row count
- * hits the limit, a trailing note says the range is NOT exhaustive.
- */
-export function renderLogbook(items, limit, now) {
-    if (items.length === 0)
-        return ["(empty)"];
-    const w = uuidDisplayWidth(items);
-    const currentYear = localToday(now).slice(0, 4);
-    const lines = [];
-    let openHeading = null;
-    for (const item of items) {
-        const s = item.stopped;
-        const heading = s === null
-            ? "no logged date"
-            : `${FULL_MONTHS[s.getMonth()]}${String(s.getFullYear()) === currentYear ? "" : ` ${s.getFullYear()}`}`;
-        if (heading !== openHeading) {
-            if (lines.length > 0)
-                lines.push("");
-            lines.push(bold(`── ${heading} ──`));
-            openHeading = heading;
+        // Bounds-&-defaults lift rule (identical to logbook): an explicit range
+        // bound (--since/--until) drops the default row cap unless --limit is
+        // also stated — the creation window the user named IS the bound, not an
+        // arbitrary 50-row cut.
+        const boundGiven = opts.since !== undefined || opts.until !== undefined;
+        const effectiveLimit = opts.limit === undefined && opts.all !== true && boundGiven ? null : lim.limit;
+        const base = invocation("inbox", [
+            ...tagInvocationParts(opts),
+            opts.overdue === true && "--overdue",
+            opts.since !== undefined && `--since ${shellQuote(opts.since)}`,
+            opts.until !== undefined && `--until ${shellQuote(opts.until)}`,
+        ]);
+        runRead(opts, "inbox", (c) => {
+            const { items: data, truncation } = c.read.inbox({
+                ...tagFilterFields(opts),
+                ...(opts.overdue === true && { overdue: true }),
+                ...(since !== undefined && { since }),
+                ...(until !== undefined && { until }),
+                limit: effectiveLimit,
+            });
+            const lines = renderList(data);
+            // Standard row-truncation hint (bigger --limit / --all), as every
+            // flat view — handled here (not via the driver's hintBase) so the
+            // creation-window note can sit last, mirroring upcoming's window
+            // footer mechanics.
+            const hint = truncationHint(base, truncation);
+            if (hint !== null)
+                lines.push("", hint);
+            // Presentation order is unchanged (manual ORDER BY index); the date
+            // bound is an invisible axis in the rows, so name the effective
+            // window in a dim footer note. Human output only — the precomputed
+            // lines never ride --json.
+            if (boundGiven) {
+                const today = localToday();
+                const sinceLabel = since !== undefined ? shortDate(localToday(since), today) : null;
+                const untilLabel = until !== undefined ? shortDate(localToday(until), today) : null;
+                const note = sinceLabel !== null && untilLabel !== null
+                    ? `(created ${sinceLabel} – ${untilLabel})`
+                    : sinceLabel !== null
+                        ? `(created since ${sinceLabel})`
+                        : `(created through ${untilLabel})`;
+                lines.push("", dim(note));
+            }
+            return { data, truncation, lines };
+        }, renderList, undefined, "inbox");
+    });
+    program
+        .command("anytime")
+        .description("All active items in canonical order (area-less first, then per " +
+        "area: direct to-dos, then each project with its members). Today members are " +
+        "starred (★). Children of someday/future-scheduled projects are excluded — the " +
+        "project row represents them. Every group and project row is always shown; " +
+        "--area-limit caps each area's direct list, --project-limit each project's list, " +
+        "--all shows everything")
+        .option("--tag <ref>", TAG_DESC, collectRef, [])
+        .option("--exact-tag", EXACT_TAG_DESC)
+        .option("--untagged", UNTAGGED_DESC)
+        .option("--overdue", OVERDUE_DESC)
+        .option("--area-limit <n>", AREA_LIMIT_DESC)
+        .option("--project-limit <n>", PROJECT_LIMIT_DESC)
+        .option("--all", GROUPED_ALL_DESC)
+        .addOption(new Option("--limit <n>").hideHelp())
+        .option("--json", "emit versioned JSON envelope on stdout")
+        .option("--db <path>", "explicit database path")
+        .action((opts) => {
+        if (tagFlagConflict(opts))
+            return;
+        if (opts.limit !== undefined) {
+            usageError(opts, "--limit is not available on anytime — cap blocks with --area-limit / --project-limit, or pass --all");
+            return;
         }
-        lines.push(formatItem(item, w, now === undefined ? {} : { now }));
-    }
-    if (items.length >= limit)
-        lines.push("", dim(`(${items.length} shown — --limit reached; raise --limit or narrow --since/--until)`));
-    return lines;
-}
-/**
- * Sidebar-grouped views (anytime/someday), rendered the way the GUI reads:
- * the area-less block headerless first, then one `── <area> ──` header per
- * area; inside a section, loose to-dos first, then each project GROUP — a
- * blank line, the project's bold+underlined title row, then its members.
- * Container names implied by the grouping are not repeated on member rows
- * (an area header covers its rows; a project title row covers the to-dos
- * beneath it — a clustered child whose project row is absent, e.g. under a
- * tag filter, keeps its `(project)` suffix). `star` prefixes each item line
- * with the Today-membership mark (★, or ⏾ for This-Evening members).
- */
-export function renderSections(sections, star = false) {
-    const all = sections.flatMap((s) => s.items);
-    if (all.length === 0)
-        return ["(empty)"];
-    const w = uuidDisplayWidth(all);
-    const lines = [];
-    const blank = () => {
-        if (lines.length > 0 && lines.at(-1) !== "")
-            lines.push("");
-    };
-    for (const section of sections) {
-        if (section.area !== null) {
-            blank();
-            lines.push(`${bold("──")} ${areaMark()} ${bold(`${section.area.title} ──`)}`);
+        const area = parseCap("--area-limit", opts.areaLimit, AREA_PREVIEW_LIMIT, opts.all === true, opts.json === true);
+        if (!area.ok)
+            return;
+        const project = parseCap("--project-limit", opts.projectLimit, PROJECT_PREVIEW_LIMIT, opts.all === true, opts.json === true);
+        if (!project.ok)
+            return;
+        const limits = { area: area.limit, project: project.limit };
+        const base = invocation("anytime", [
+            ...tagInvocationParts(opts),
+            opts.overdue === true && "--overdue",
+        ]);
+        // Content scopes compose (AND): --overdue narrows a tagged/untagged
+        // set, so the filter is built additively rather than one-or-the-other.
+        const filter = {
+            ...tagFilterFields(opts),
+            ...(opts.overdue === true && { overdue: true }),
+        };
+        runRead(opts, "anytime", (c) => {
+            const { view, grouped } = c.read.anytime({
+                ...filter,
+                areaLimit: area.limit,
+                projectLimit: project.limit,
+            });
+            return {
+                data: view,
+                grouped,
+                lines: renderAnytimePreview(view, grouped, limits, base),
+            };
+        }, 
+        // Grouped views hand back precomputed `lines`; renderSections is the
+        // type-correct fallback for the SidebarSection[] payload but is never
+        // reached here.
+        renderSections, undefined, "anytime");
+    });
+    program
+        .command("someday")
+        .description("Someday items (incubated, undated) in canonical order — inside each group the " +
+        "someday projects list first, then the to-dos; project children are represented " +
+        "by their project row. --show-active-project-items [n] appends a trailing section " +
+        "of someday to-dos inside active projects, grouped under their project (the UI's " +
+        "'Show items from active projects' toggle; n caps each project's list). " +
+        "--area-limit caps each group, --all shows everything")
+        .option("--tag <ref>", TAG_DESC, collectRef, [])
+        .option("--exact-tag", EXACT_TAG_DESC)
+        .option("--untagged", UNTAGGED_DESC)
+        .option("--overdue", OVERDUE_DESC)
+        .option("--area-limit <n>", AREA_LIMIT_DESC)
+        .option("--show-active-project-items [n]", "append someday to-dos inside active projects, grouped under their project; " +
+        "n caps each project's list (bare flag: every item)")
+        .option("--all", GROUPED_ALL_DESC)
+        .addOption(new Option("--limit <n>").hideHelp())
+        .option("--json", "emit versioned JSON envelope on stdout")
+        .option("--db <path>", "explicit database path")
+        .action((opts) => {
+        if (tagFlagConflict(opts))
+            return;
+        if (opts.limit !== undefined) {
+            process.stderr.write("error: --limit is not available on someday — cap groups with --area-limit, or pass --all\n");
+            process.exitCode = ExitCode.Usage;
+            return;
         }
-        // The uuid of the project whose title row is directly above (its member
-        // rows drop their redundant `(project)` suffix).
-        let openProject = null;
-        for (const item of section.items) {
-            const mark = star ? todayMark(item) : null;
-            if (item.type === "project") {
-                openProject = item.uuid;
-                blank();
-                lines.push(formatItem(item, w, {
-                    projectTitle: true,
-                    suppressArea: section.area?.uuid ?? null,
-                    mark,
-                }));
-            }
-            else {
-                lines.push(formatItem(item, w, {
-                    suppressProject: openProject,
-                    suppressArea: section.area?.uuid ?? null,
-                    mark,
-                }));
-            }
+        const showActive = opts.showActiveProjectItems !== undefined;
+        let projectCap = null;
+        if (typeof opts.showActiveProjectItems === "string") {
+            const capped = parseCap("--show-active-project-items", opts.showActiveProjectItems, 0, opts.all === true, opts.json === true);
+            if (!capped.ok)
+                return;
+            projectCap = capped.limit;
         }
-    }
-    return lines;
-}
-export function registerReadCommands(program) {
-    const listCommands = [
-        {
-            name: "today",
-            description: "The Today list, split into Today and This Evening (evening expires daily), with the sidebar badge split (red = deadline due/overdue)",
-            fetch: (c, tag, exactTag) => c.read.today(tag === undefined ? undefined : { tag, ...(exactTag === true && { exactTag }) }),
-            render: (data) => {
-                // GUI parity: every Today row carries the star, every This-Evening
-                // row the crescent, right after the box (one shared uuid column).
-                const w = uuidDisplayWidth([...data.today, ...data.evening]);
-                return [
-                    `── Today (badge: ${data.badge.dueOrOverdue} due/overdue · ${data.badge.other} other) ──`,
-                    ...(data.today.length === 0
-                        ? ["(empty)"]
-                        : data.today.map((i) => formatItem(i, w, { mark: todayStar() }))),
-                    "── This Evening ──",
-                    ...(data.evening.length === 0
-                        ? ["(empty)"]
-                        : data.evening.map((i) => formatItem(i, w, { mark: eveningMoon() }))),
-                ];
-            },
-        },
-        {
-            name: "inbox",
-            description: "Unprocessed captures (Inbox)",
-            fetch: (c, tag, exactTag) => c.read.inbox(tag === undefined ? undefined : { tag, ...(exactTag === true && { exactTag }) }),
-        },
-        {
-            name: "anytime",
-            description: "All active items in the UI's sidebar-mirroring order (area-less first, then per " +
-                "area: direct to-dos, then each project with its members). Today members are " +
-                "starred (★). Children of someday/future-scheduled projects are excluded — the " +
-                "project row represents them",
-            fetch: (c, tag, exactTag) => c.read.anytime(tag === undefined ? undefined : { tag, ...(exactTag === true && { exactTag }) }),
-            render: (sections) => renderSections(sections, true),
-        },
-        {
-            name: "someday",
-            description: "Someday items (incubated, undated) in sidebar order. Project children are " +
-                "represented by their project row; --active-project-items also lists someday " +
-                "to-dos inside active projects (the UI's 'Show items from active projects' toggle)",
-            fetch: (c, tag, exactTag, activeProjectItems) => c.read.someday({
-                ...(tag !== undefined && { tag }),
-                ...(exactTag === true && { exactTag }),
-                ...(activeProjectItems === true && { activeProjectItems }),
-            }),
-            render: (sections) => renderSections(sections),
-            extraOption: [
-                "--active-project-items",
-                "also list someday to-dos inside active projects",
-                "activeProjectItems",
-            ],
-        },
-    ];
-    for (const cmd of listCommands) {
-        const command = program
-            .command(cmd.name)
-            .description(cmd.description)
-            .option("--tag <ref>", "filter by tag (uuid or unique name): direct, inherited, or descendant-tagged")
-            .option("--exact-tag", "match the named tag only — exclude hierarchy descendants")
-            .option("--json", "emit versioned JSON envelope on stdout")
-            .option("--db <path>", "explicit database path");
-        if (cmd.extraOption)
-            command.option(cmd.extraOption[0], cmd.extraOption[1]);
-        command.action((opts) => {
-            const extra = cmd.extraOption ? opts[cmd.extraOption[2]] === true : undefined;
-            withClient(opts, cmd.name, (c) => cmd.fetch(c, opts.tag, opts.exactTag, extra), (cmd.render ?? renderList));
-        });
-    }
+        const area = parseCap("--area-limit", opts.areaLimit, AREA_PREVIEW_LIMIT, opts.all === true, opts.json === true);
+        if (!area.ok)
+            return;
+        const limits = { area: area.limit, project: projectCap };
+        const filter = {
+            ...tagFilterFields(opts),
+            ...(opts.overdue === true && { overdue: true }),
+        };
+        const base = invocation("someday", [
+            ...tagInvocationParts(opts),
+            opts.overdue === true && "--overdue",
+        ]);
+        runRead(opts, "someday", (c) => {
+            const { view, grouped } = c.read.someday({
+                ...filter,
+                ...(showActive && { activeProjectItems: true }),
+                areaLimit: area.limit,
+                projectLimit: projectCap,
+            });
+            // Hidden-items-never-silent: when the toggle is off, one extra
+            // query counts what it would reveal (someday to-dos inside active
+            // projects) — summing the active-project child blocks' totals from
+            // that query's grouped metadata (projectLimit defaults to every
+            // item there, so each block's total is the full group size).
+            const hiddenActiveItems = showActive
+                ? 0
+                : c.read
+                    .someday({ ...filter, activeProjectItems: true })
+                    .grouped.blocks.reduce((n, b) => n +
+                    (b.children?.reduce((m, child) => m + (child.kind === "project" ? child.total : 0), 0) ?? 0), 0);
+            return {
+                data: view,
+                grouped,
+                lines: renderSomedayPreview(view, grouped, limits, base, showActive, hiddenActiveItems),
+            };
+        }, 
+        // Precomputed lines above; renderSections is the type-correct
+        // SidebarSection[] fallback, never reached here.
+        renderSections, undefined, "someday");
+    });
     program
         .command("upcoming")
         .description("Future-scheduled items in date order, INCLUDING each repeating item's next " +
@@ -559,58 +320,99 @@ export function registerReadCommands(program) {
         "PROJECTS the following n-1 occurrences per repeating item from its decoded rule " +
         "(fixed rules only, max 10) — projections are host math the app has not " +
         "materialized yet.")
-        .option("--until <period>", "only items scheduled through this bound: `2w`/`3m`/`1y` from today, or `2026-09`, " +
-        "`2026-09-15`, `2026` (whole periods)", "1m")
-        .option("--all", "no date bound — every future-scheduled item (the app's full Upcoming)")
-        .option("--limit <n>", "maximum rows (applied after the date bound)")
-        .option("--tag <ref>", "filter by tag (uuid or unique name): direct, inherited, or descendant-tagged")
-        .option("--exact-tag", "match the named tag only — exclude hierarchy descendants")
+        .option("--until <period>", `only items scheduled through this bound: ${PERIOD_UNTIL} (whole periods)`, "1m")
+        .option("--since <period>", `skip items scheduled before this bound: ${PERIOD_SINCE}`)
+        .option("--all", "no date bound and no row limit — the app's full Upcoming")
+        .option("--limit <n>", LIMIT_DESC)
+        .option("--tag <ref>", TAG_DESC, collectRef, [])
+        .option("--exact-tag", EXACT_TAG_DESC)
+        .option("--untagged", UNTAGGED_DESC)
         .option("--horizon <n>", "occurrences per repeating item (default 1 = UI parity)")
         .option("--json", "emit versioned JSON envelope on stdout")
         .option("--db <path>", "explicit database path")
         .action((opts, command) => {
+        if (tagFlagConflict(opts))
+            return;
         const untilGiven = command.getOptionValueSource("until") !== "default";
-        if (opts.all === true && untilGiven) {
-            process.stderr.write("error: --all and --until are mutually exclusive\n");
-            process.exitCode = ExitCode.Usage;
+        const sinceGiven = opts.since !== undefined;
+        const limitGiven = opts.limit !== undefined;
+        if (opts.all === true && (untilGiven || sinceGiven)) {
+            usageError(opts, "--all does not combine with --until/--since");
             return;
         }
-        const untilDate = opts.all === true ? undefined : parsePeriodEnd(opts.until);
+        const lim = parseLimit(opts);
+        if (!lim.ok)
+            return;
+        // Bounds-&-defaults rule: an explicit volume cap (--limit) or range
+        // bound (--until/--since) disables the OTHER class's default. So an
+        // explicit --limit drops the default window (the next N scheduled
+        // items), and an explicit window drops the default row cap — each
+        // stated bound takes over output sizing.
+        const dropWindowDefault = !untilGiven && (limitGiven || sinceGiven);
+        const dropLimitDefault = !limitGiven && opts.all !== true && (untilGiven || sinceGiven);
+        const effectiveLimit = dropLimitDefault ? null : lim.limit;
+        const untilDate = opts.all === true || dropWindowDefault ? undefined : parsePeriodEnd(opts.until);
         if (untilDate !== undefined && Number.isNaN(untilDate.getTime())) {
-            process.stderr.write(`error: --until is not a parseable period: ${opts.until}\n`);
-            process.exitCode = ExitCode.Usage;
+            usageError(opts, `--until is not a parseable period: ${opts.until}`);
             return;
         }
-        const until = untilDate === undefined ? undefined : localToday(untilDate);
-        const limit = opts.limit === undefined ? undefined : Number(opts.limit);
-        if (limit !== undefined && (!Number.isInteger(limit) || limit < 1)) {
-            process.stderr.write(`error: --limit must be a positive integer\n`);
-            process.exitCode = ExitCode.Usage;
+        const sinceDate = sinceGiven ? parsePeriodStart(opts.since) : undefined;
+        if (sinceDate !== undefined && Number.isNaN(sinceDate.getTime())) {
+            usageError(opts, `--since is not a parseable period: ${opts.since}`);
             return;
         }
-        let clipped = false;
-        withClient(opts, "upcoming", (c) => {
-            const items = c.read.upcoming({
+        const until = untilDate === undefined ? undefined : localToday(untilDate);
+        const since = sinceDate === undefined ? undefined : localToday(sinceDate);
+        // The default window is in force only for a bare invocation (no
+        // explicit cap or bound); that is the one case whose footer names the
+        // window itself alongside the levers.
+        const defaultWindowActive = until !== undefined && !untilGiven;
+        const base = invocation("upcoming", [
+            untilGiven && `--until ${shellQuote(opts.until)}`,
+            sinceGiven && `--since ${shellQuote(opts.since)}`,
+            ...tagInvocationParts(opts),
+            opts.horizon !== undefined && `--horizon ${shellQuote(opts.horizon)}`,
+        ]);
+        runRead(opts, "upcoming", (c) => {
+            const { items: data, truncation } = c.read.upcoming({
                 ...(until !== undefined && { until }),
-                ...(opts.tag !== undefined && { tag: opts.tag }),
-                ...(opts.exactTag === true && { exactTag: true }),
+                ...(since !== undefined && { since }),
+                ...tagFilterFields(opts),
                 ...(opts.horizon !== undefined && { horizon: Number(opts.horizon) }),
+                limit: effectiveLimit,
             });
-            if (limit !== undefined && items.length > limit) {
-                clipped = true;
-                return items.slice(0, limit);
-            }
-            return items;
-        }, ((items) => {
-            const lines = renderUpcoming(items);
-            if (clipped && limit !== undefined) {
-                lines.push("", dim(`(${limit} shown — --limit reached; raise --limit or widen --until)`));
+            const lines = renderUpcoming(data);
+            if (defaultWindowActive && until !== undefined) {
+                const windowLabel = shortDate(until, localToday());
+                if (truncation.truncated && truncation.limit !== null) {
+                    // Bare invocation, row cap biting inside the default window: one
+                    // line names BOTH the window and the two levers, so neither the
+                    // limit nor the horizon is a hidden second bound.
+                    const more = truncation.total - truncation.shown;
+                    lines.push("", dim(`── ${more} more item${more === 1 ? "" : "s"} through ${windowLabel} — ` +
+                        `see more: \`${base} --limit ${truncation.limit * 2}\` · ` +
+                        `\`${base} --all\` ──`));
+                }
+                else {
+                    // Default window active, row cap NOT biting: the only useful
+                    // lever is a wider window (or everything).
+                    lines.push("", dim(`(through ${windowLabel} — wider: \`${base} --until ${doublePeriod(opts.until)}\`` +
+                        ` · \`${base} --all\`)`));
+                }
             }
-            if (until !== undefined) {
-                lines.push("", dim(`(through ${shortDate(until, localToday())} — --all for the full horizon)`));
+            else if (truncation.truncated && truncation.limit !== null) {
+                // The user stated a bound: no window line, only a row hint, and
+                // only when an explicit --limit truncated. A stated --until/--since
+                // makes --all a usage error (and would discard the very window
+                // they asked for), so a bounded run offers just a bigger cap.
+                const more = truncation.total - truncation.shown;
+                const bounded = untilGiven || sinceGiven;
+                const allLever = bounded ? "" : ` · \`${base} --all\``;
+                lines.push("", dim(`── ${more} more item${more === 1 ? "" : "s"} — ` +
+                    `see more: \`${base} --limit ${truncation.limit * 2}\`${allLever} ──`));
             }
-            return lines;
-        }));
+            return { data, truncation, lines };
+        }, (items) => renderUpcoming(items), undefined, "upcoming");
     });
     program
         .command("logbook")
@@ -618,17 +420,23 @@ export function registerReadCommands(program) {
         "(year appended beyond the current year). Scope with --area (direct items + its " +
         "projects' children, heading-nested included) / --project (all children, " +
         "heading-nested included) / --tag; bound the logged date with --since/--until.")
-        .option("--limit <n>", "maximum items to return", "100")
+        .option("--limit <n>", LIMIT_DESC)
+        .option("--all", ALL_DESC)
         .option("--area <ref>", "restrict to an area: direct items plus its projects' children")
         .option("--project <ref>", "restrict to one project's children (uuid or unique name)")
-        .option("--since <when>", "only entries logged on/after this bound: `2w`/`3m`/`1y` back from today, or " +
-        "`2024`, `2024-03`, `2024-03-05` (whole periods)")
-        .option("--until <when>", "only entries logged on/before this date (2024 or 2024-03 cover the whole period)")
-        .option("--tag <ref>", "filter by tag (uuid or unique name), direct OR inherited")
-        .option("--exact-tag", "match the named tag only — exclude hierarchy descendants")
+        .option("--since <when>", `only entries logged on/after this bound: ${PERIOD_SINCE}`)
+        .option("--until <when>", `only entries logged on/before this bound: ${PERIOD_UNTIL}`)
+        .option("--tag <ref>", TAG_DESC, collectRef, [])
+        .option("--exact-tag", EXACT_TAG_DESC)
+        .option("--untagged", UNTAGGED_DESC)
         .option("--json", "emit versioned JSON envelope on stdout")
         .option("--db <path>", "explicit database path")
         .action((opts) => {
+        if (tagFlagConflict(opts))
+            return;
+        const lim = parseLimit(opts);
+        if (!lim.ok)
+            return;
         const since = opts.since !== undefined ? parsePeriodStart(opts.since) : undefined;
         const until = opts.until !== undefined ? parsePeriodEnd(opts.until) : undefined;
         for (const [flag, value] of [
@@ -636,69 +444,107 @@ export function registerReadCommands(program) {
             ["--until", until],
         ]) {
             if (value !== undefined && Number.isNaN(value.getTime())) {
-                process.stderr.write(`error: ${flag} is not a parseable date\n`);
-                process.exitCode = ExitCode.Usage;
+                usageError(opts, `${flag} is not a parseable date`);
                 return;
             }
         }
-        const limit = Number(opts.limit);
-        withClient(opts, "logbook", (c) => c.read.logbook({
-            limit,
-            ...(opts.area !== undefined && { area: opts.area }),
-            ...(opts.project !== undefined && { project: opts.project }),
-            ...(since !== undefined && { since }),
-            ...(until !== undefined && { until }),
-            ...(opts.tag !== undefined && { tag: opts.tag }),
-            ...(opts.exactTag === true && { exactTag: true }),
-        }), ((items) => renderLogbook(items, limit)));
+        // Bounds-&-defaults rule: an explicit range bound (--since/--until)
+        // drops the default row cap unless --limit is also stated — the logged
+        // window the user named is the bound, not an arbitrary 50-row cut.
+        const boundGiven = opts.since !== undefined || opts.until !== undefined;
+        const effectiveLimit = opts.limit === undefined && opts.all !== true && boundGiven ? null : lim.limit;
+        const base = invocation("logbook", [
+            opts.area !== undefined && `--area ${shellQuote(opts.area)}`,
+            opts.project !== undefined && `--project ${shellQuote(opts.project)}`,
+            opts.since !== undefined && `--since ${shellQuote(opts.since)}`,
+            opts.until !== undefined && `--until ${shellQuote(opts.until)}`,
+            ...tagInvocationParts(opts),
+        ]);
+        runRead(opts, "logbook", (c) => {
+            const { items, truncation } = c.read.logbook({
+                ...(opts.area !== undefined && { area: opts.area }),
+                ...(opts.project !== undefined && { project: opts.project }),
+                ...(since !== undefined && { since }),
+                ...(until !== undefined && { until }),
+                ...tagFilterFields(opts),
+                limit: effectiveLimit,
+            });
+            return { data: items, truncation };
+        }, (items) => renderLogbook(items), base, "logbook");
     });
     program
         .command("trash")
         .description("Trashed items (trashed=1 flag, any status), most recently modified first")
-        .option("--limit <n>", "maximum items to return", "200")
+        .option("--limit <n>", LIMIT_DESC)
+        .option("--all", ALL_DESC)
         .option("--json", "emit versioned JSON envelope on stdout")
         .option("--db <path>", "explicit database path")
         .action((opts) => {
-        const limit = Number(opts.limit);
-        let clipped = false;
-        withClient(opts, "trash", (c) => {
-            // Fetch one past the limit so truncation is loud, never silent.
-            const items = c.read.trash({ limit: limit + 1 });
-            if (items.length > limit) {
-                clipped = true;
-                return items.slice(0, limit);
-            }
-            return items;
-        }, ((items) => {
-            const lines = renderList(items);
-            if (clipped)
-                lines.push("", dim(`(${limit} shown — --limit reached; raise --limit)`));
-            return lines;
-        }));
+        const lim = parseLimit(opts);
+        if (!lim.ok)
+            return;
+        runRead(opts, "trash", (c) => {
+            const { items, truncation } = c.read.trash({ limit: lim.limit });
+            return { data: items, truncation };
+        }, renderList, invocation("trash", []), "trash");
     });
-    program
-        .command("projects")
-        .description("Active projects in sidebar order: loose projects first, then grouped under " +
-        "their area (optionally scoped to --area <ref>). Someday and future-scheduled " +
-        "projects are hidden — --show-later appends them after each group's active " +
-        "block (state carried by the (~) mark and ‹date› chip)")
+    const projects = program
+        .command("projects [ref]")
+        .description("List active projects in canonical order, or — given a ref — show that one " +
+        "project (exactly like `things project show <ref>`). List: loose projects " +
+        "first, then grouped under their area (optionally scoped to --area <ref>). " +
+        "Someday and future-scheduled projects are hidden — --show-later appends them " +
+        "after each group's active block (state carried by the (~) mark and ‹date› " +
+        "chip). Filter the listed projects by their own tags with --tag / --untagged — " +
+        "inheritance-inclusive (a project inherits its area's tags), the same as the flat " +
+        "views. --show-logged applies only when showing one project.")
         .option("--area <ref>", "filter by area (uuid or unique name)")
         .option("--show-later", "include someday/future-scheduled projects after each active block")
+        .option("--show-logged [n]", "showing one project: include logged items (bare = all)")
+        .option("--overdue", "only projects past their deadline (due today is not overdue)")
+        .option("--all", "include someday/future-scheduled projects (same as --show-later)")
         .option("--json", "emit versioned JSON envelope on stdout")
-        .option("--db <path>", "explicit database path")
-        .action((opts) => {
+        .option("--db <path>", "explicit database path");
+    addTagFilterOptions(projects).action((id, opts) => {
+        // Given a ref, this IS `things project show <ref>` — delegate to the same
+        // code path so the output is identical (a true synonym). --overdue rides
+        // along (it filters the shown project's children there).
+        if (id !== undefined) {
+            runProjectShow(id, opts);
+            return;
+        }
+        if (tagFlagConflict(opts))
+            return;
+        // --all lifts the sole default restriction here — the hidden later block
+        // — so it is exactly --show-later (the charter: --all removes every
+        // default restriction on the view's own content).
+        const showLater = opts.showLater === true || opts.all === true;
+        // OWN-DEADLINE UNIFORM content scope: keep only projects whose own
+        // deadline is overdue. Composes as AND with --area/--show-later; a
+        // content scope, it never lifts a limit. Threaded into the hidden-later
+        // counting queries too so the counts reflect the same filter.
+        const overdue = opts.overdue === true;
+        // Tag scope (§9a): the projects LIST is a FLAT view — each project ROW is
+        // filtered by its own tags, INHERITANCE-INCLUSIVE (a project inherits its
+        // area's tags), the same as `anytime`. NOT a single-container view.
+        // Threaded into the hidden-later counts too so they reflect the same filter.
+        const tagFilter = tagFilterFields(opts);
         let hints;
         withClient(opts, "projects", (c) => {
             const scope = opts.area !== undefined ? { areaUuid: opts.area } : {};
             const visible = c.read.projects({
                 ...scope,
-                ...(opts.showLater === true && { later: true }),
+                ...(showLater && { later: true }),
+                ...(overdue && { overdue: true }),
+                ...tagFilter,
             });
             if (opts.area === undefined) {
                 // Sidebar scaffold: every VISIBLE area renders (project-less
                 // ones say so), in sidebar order; the loose block leads. One
                 // extra projects query buys the hidden-later counts.
-                const full = opts.showLater === true ? visible : c.read.projects({ later: true });
+                const full = showLater
+                    ? visible
+                    : c.read.projects({ later: true, ...(overdue && { overdue: true }), ...tagFilter });
                 const shown = new Set(visible.map((i) => i.uuid));
                 const groups = [
                     { area: null, hidden: 0 },
@@ -717,43 +563,114 @@ export function registerReadCommands(program) {
                 }
                 hints = { groups };
             }
-            else if (opts.showLater !== true) {
+            else if (!showLater) {
                 // --area scoped: only the bottom hint needs a count.
-                const full = c.read.projects({ ...scope, later: true });
+                const full = c.read.projects({
+                    ...scope,
+                    later: true,
+                    ...(overdue && { overdue: true }),
+                    ...tagFilter,
+                });
                 hints = { groups: [{ area: null, hidden: full.length - visible.length }] };
             }
             return visible;
         }, 
         // Scoped to one area the list is flat (the scope names the group);
         // unscoped it mirrors the sidebar with ⬡ area headers.
-        ((items) => {
+        (items) => {
             if (opts.area === undefined)
                 return renderProjectsSidebar(items, hints);
             const lines = renderList(items);
             const hidden = hints?.groups.reduce((n, g) => n + g.hidden, 0) ?? 0;
-            if (hidden > 0)
-                lines.push("", dim(`(${hidden} later project${hidden === 1 ? "" : "s"} — visible with \`--show-later\`)`));
+            if (hidden > 0) {
+                // Hidden-section placeholder: the reveal command echoes the user's
+                // own scope (--area) plus the flag that surfaces the later block.
+                const reveal = invocation("projects", [
+                    opts.area !== undefined && `--area ${shellQuote(opts.area)}`,
+                    overdue && "--overdue",
+                    ...tagInvocationParts(opts),
+                    "--show-later",
+                ]);
+                lines.push("", disclosureHint(hidden, "later project", [{ command: reveal }]));
+            }
             return lines;
-        }));
+        });
     });
-    program
-        .command("areas")
-        .description("All areas with their direct tags")
+    const areas = program
+        .command("areas [ref]")
+        .description("List all areas with their direct tags, or — given a ref — show that one area " +
+        "(exactly like `things area show <ref>`: its projects and direct to-dos). " +
+        "--show-later / --show-logged / --area-limit / --project-limit / the tag filters " +
+        "apply only when showing one area.")
+        .option("--all", "show every area (no default restriction applies)")
+        .option("--show-later", "showing one area: include its Upcoming and Someday sections")
+        .option("--show-logged [n]", "showing one area: include the n most recent logged items")
+        .option("--project-limit <n>", "showing one area: maximum project rows to show")
+        .option("--area-limit <n>", "showing one area: maximum direct to-dos to show")
+        .option("--overdue", "showing one area: only rows whose own deadline is past (due today is not overdue)")
         .option("--json", "emit versioned JSON envelope on stdout")
-        .option("--db <path>", "explicit database path")
-        .action((opts) => {
-        withClient(opts, "areas", (c) => c.read.areas(), ((data) => {
+        .option("--db <path>", "explicit database path");
+    addTagFilterOptions(areas).addHelpText("after", CONTAINER_TAG_HINT);
+    areas.action((id, opts) => {
+        // Given a ref, this IS `things area show <ref>` — delegate to the same code
+        // path so the output is identical (a true synonym); --overdue and the tag
+        // filters scope its rows there.
+        if (id !== undefined) {
+            runAreaShow(id, opts);
+            return;
+        }
+        // The areas LIST has no deadline to compare against — an area is not a
+        // dated entity — so --overdue is vacuous here and rejected fail-closed
+        // (the same exclusion style #159 used for upcoming/logbook/trash). The
+        // decision is the contract's (areas: overdue = false).
+        if (!FILTER_CONTRACT.areas.overdue && opts.overdue === true) {
+            usageError(opts, "--overdue does not apply to the areas list — areas have no deadline; use it on `things areas <ref>` (that area's rows) or `things projects --overdue`");
+            return;
+        }
+        // The tag filters scope an area's ROWS, not the area LIST — the bare list
+        // shows every area with its direct tags. Rejected fail-closed here (same
+        // style as --overdue; contract: areas tag = "rejected"). Use
+        // `things areas <ref>` or `things projects --tag`.
+        if (FILTER_CONTRACT.areas.tag === "rejected" &&
+            (hasTagPresence(opts) || opts.untagged === true)) {
+            usageError(opts, "the tag filters (--tag/--untagged) do not apply to the areas list — use them on `things areas <ref>` (that area's rows) or `things projects --tag`");
+            return;
+        }
+        withClient(opts, "areas", (c) => c.read.areas(), (data) => {
             const w = uuidDisplayWidth(data);
-            return data.map((a) => `${dim(a.uuid.length > w ? a.uuid.slice(0, w) : a.uuid.padEnd(w))}  ${areaMark()} ${a.title}${a.tags.length ? ` ${dim(`#${a.tags.map((t) => t.title).join(" #")}`)}` : ""}`);
-        }));
+            return data.map((a) => `${dim(uuidCol(a.uuid, w))}  ${areaMark()} ${a.title}${a.tags.length ? ` ${dim(`#${a.tags.map((t) => t.title).join(" #")}`)}` : ""}`);
+        });
     });
     program
         .command("tags")
-        .description("Tag taxonomy (parent → child hierarchy flattened with refs)")
+        .description("Tag taxonomy — the parent → child hierarchy as an indented tree")
+        .option("--all", "show every tag (no default restriction applies)")
         .option("--json", "emit versioned JSON envelope on stdout")
         .option("--db <path>", "explicit database path")
         .action((opts) => {
-        withClient(opts, "tags", (c) => c.read.tags(), ((data) => data.map((t) => `${t.uuid}  ${t.parent ? `${t.parent.title}/` : ""}${t.title}`)));
+        withClient(opts, "tags", (c) => c.read.tags(), 
+        // An INDENTED TREE, leaf names only — nesting is conveyed by indentation
+        // (2 spaces per depth level), mirroring the Things GUI. Tag names are
+        // globally unique (TAGW1-c), so each displayed leaf name is directly
+        // usable as a tag ref — no path prefix or uuid needed. Rows arrive in
+        // canonical DFS order (index, uuid) from tagsView, children following
+        // their parent; the tree IS structure, so leaf names render plainly (not
+        // dim). Depth is the length of the parent-name chain (names are unique).
+        (data) => {
+            const parentOf = new Map(data.map((t) => [t.title, t.parent]));
+            const depthOf = (title) => {
+                let depth = 0;
+                const seen = new Set();
+                let cur = parentOf.get(title) ?? null;
+                while (cur !== null && !seen.has(cur)) {
+                    seen.add(cur);
+                    depth++;
+                    cur = parentOf.get(cur) ?? null;
+                }
+                return depth;
+            };
+            return data.map((t) => `${"  ".repeat(depthOf(t.title))}${t.title}`);
+        });
     });
     program
         .command("changes")
@@ -761,55 +678,130 @@ export function registerReadCommands(program) {
         "trashed, logged, and repeating-template rows so agents can sync state; check " +
         "trashed/status/repeating on each item. Caveats: tag/area edits and checklist-item " +
         "edits don't bump tasks and are invisible here.")
-        .requiredOption("--since <when>", "ISO date/datetime (e.g. 2026-07-05T14:30:00)")
-        .option("--limit <n>", "maximum items", "200")
+        .requiredOption("--since <when>", `ISO date/datetime (e.g. 2026-07-05T14:30:00), or ${PERIOD_SINCE}`)
+        .option("--limit <n>", LIMIT_DESC)
+        .option("--all", ALL_DESC)
         .option("--json", "emit versioned JSON envelope on stdout")
         .option("--db <path>", "explicit database path")
         .action((opts) => {
-        const since = new Date(opts.since);
+        const lim = parseLimit(opts);
+        if (!lim.ok)
+            return;
+        const since = parsePeriodStart(opts.since);
         if (Number.isNaN(since.getTime())) {
-            process.stderr.write(`error: --since is not a parseable date: ${opts.since}\n`);
-            process.exitCode = ExitCode.Usage;
+            usageError(opts, `--since is not a parseable date: ${opts.since}`);
             return;
         }
-        withClient(opts, "changes", (c) => c.read.changes({ since, limit: Number(opts.limit) }), ((items) => items.length === 0
+        const base = invocation("changes", [`--since ${shellQuote(opts.since)}`]);
+        runRead(opts, "changes", (c) => {
+            const { items, truncation } = c.read.changes({ since, limit: lim.limit });
+            return { data: items, truncation };
+        }, (items) => items.length === 0
             ? ["(no changes)"]
-            : items.map((i) => `${i.changeKind === "created" ? "+" : "~"} ${formatItem(i)}${i.trashed ? " [trashed]" : ""}`)));
+            : items.map((i) => `${i.changeKind === "created" ? "+" : "~"} ${formatItem(i)}${i.trashed ? " [trashed]" : ""}`), base);
     });
     program
         .command("search <query>")
-        .description("Title/notes substring search, most recently modified first. Default scope: OPEN + " +
-        "untrashed items only — widen with --logged / --trashed / --all. Scope with " +
-        "--project / --area / --tag (tag matches include hierarchy descendants) / --type.")
+        .description("Title/notes substring search, ranked: title matches first, then notes, then a " +
+        "project surfaced by a matching heading title (shown as its parent project, " +
+        "`via heading`); projects rank above to-dos, active above someday, ties broken by " +
+        "most-recently-modified. Default scope: OPEN + untrashed items only — widen with " +
+        "--logged / --trashed / --all. Scope with --project / --area / --tag (tag matches " +
+        "include hierarchy descendants) / --type / --overdue (open items past their deadline).")
         .option("--project <ref>", "restrict to one project's children (uuid or unique name)")
         .option("--area <ref>", "restrict to one area's direct members (uuid or unique name)")
-        .option("--tag <ref>", "restrict by tag: direct, inherited, or descendant-tagged")
-        .option("--exact-tag", "match the named tag only — exclude hierarchy descendants")
+        .option("--tag <ref>", TAG_DESC, collectRef, [])
+        .option("--exact-tag", EXACT_TAG_DESC)
+        .option("--untagged", UNTAGGED_DESC)
+        .option("--overdue", OVERDUE_DESC)
         .option("--type <kind>", "todo | project")
         .option("--logged", "include completed/canceled items")
         .option("--trashed", "include trashed items")
-        .option("--all", "legacy behavior: everything (open + logged + trashed)")
-        .option("--limit <n>", "maximum results", "50")
+        .option("--all", "everything, unbounded: open + logged + trashed, with no row limit (excludes --limit)")
+        .option("--limit <n>", LIMIT_DESC)
         .option("--json", "emit versioned JSON envelope on stdout")
         .option("--db <path>", "explicit database path")
         .action((query, opts) => {
+        const json = opts["json"] === true;
         const type = opts["type"];
         if (type !== undefined && type !== "todo" && type !== "project") {
-            process.stderr.write("error: --type must be todo or project\n");
-            process.exitCode = 2;
+            usageError({ json }, "--type must be todo or project");
             return;
         }
-        withClient(opts, "search", (c) => c.read.search(query, {
-            limit: Number(opts["limit"] ?? 50),
-            ...(opts["project"] !== undefined && { project: opts["project"] }),
-            ...(opts["area"] !== undefined && { area: opts["area"] }),
-            ...(opts["tag"] !== undefined && { tag: opts["tag"] }),
-            ...(opts["exactTag"] === true && { exactTag: true }),
-            ...(type !== undefined && { type: type === "todo" ? "to-do" : "project" }),
-            ...(opts["logged"] === true && { logged: true }),
-            ...(opts["trashed"] === true && { trashed: true }),
-            ...(opts["all"] === true && { all: true }),
-        }), renderList);
+        const tagFlags = {
+            ...(Array.isArray(opts["tag"]) && { tag: opts["tag"] }),
+            exactTag: opts["exactTag"] === true,
+            untagged: opts["untagged"] === true,
+        };
+        const overdue = opts["overdue"] === true;
+        const all = opts["all"] === true;
+        // Tag-conflict AND the --overdue/status-widening incompatibility both
+        // derive from the shared contract (search: statusWidening = true) —
+        // --overdue lists OPEN, past-deadline items, so combining it with the
+        // completed/canceled/trashed-widening flags is contradictory.
+        const validated = validateViewArgs("search", {
+            ...tagFlags,
+            overdue,
+            logged: opts["logged"] === true,
+            trashed: opts["trashed"] === true,
+            all,
+        }, {
+            untaggedConflict: "--untagged does not combine with --tag/--exact-tag",
+            overdueRejected: "--overdue does not apply to search",
+            overdueStatusWiden: "--overdue does not combine with --logged/--trashed/--all",
+        });
+        if (!validated.ok) {
+            usageError({ json }, validated.message);
+            return;
+        }
+        const limitOpt = opts["limit"];
+        // --all widens the scope AND lifts the row limit — combining it with an
+        // explicit --limit is contradictory (like every other view).
+        const lim = parseLimit({ all, json, ...(limitOpt !== undefined && { limit: limitOpt }) });
+        if (!lim.ok)
+            return;
+        const base = invocation("search", [
+            shellQuote(query),
+            opts["project"] !== undefined && `--project ${shellQuote(opts["project"])}`,
+            opts["area"] !== undefined && `--area ${shellQuote(opts["area"])}`,
+            ...tagInvocationParts(tagFlags),
+            overdue && "--overdue",
+            type !== undefined && `--type ${type}`,
+            opts["logged"] === true && "--logged",
+            opts["trashed"] === true && "--trashed",
+        ]);
+        runRead(opts, "search", (c) => {
+            const { items, truncation } = c.read.search(query, {
+                limit: lim.limit,
+                ...(opts["project"] !== undefined && { project: opts["project"] }),
+                ...(opts["area"] !== undefined && { area: opts["area"] }),
+                ...validated.filter,
+                ...(type !== undefined && { type: type === "todo" ? "to-do" : "project" }),
+                ...(opts["logged"] === true && { logged: true }),
+                ...(opts["trashed"] === true && { trashed: true }),
+                ...(all && { all: true }),
+            });
+            return { data: items, truncation };
+        }, renderSearch, base);
     });
+    // Every row-rendering view points at `things legend` for its glyph language.
+    const GLYPH_VIEWS = new Set([
+        "today",
+        "inbox",
+        "anytime",
+        "someday",
+        "upcoming",
+        "logbook",
+        "trash",
+        "projects",
+        "areas",
+        "changes",
+        "search",
+    ]);
+    for (const c of program.commands) {
+        if (GLYPH_VIEWS.has(c.name())) {
+            c.addHelpText("after", "\nsymbols & colors: run `things legend`");
+        }
+    }
 }
 //# sourceMappingURL=reads.js.map