things-api 0.8.0 → 0.9.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 { localToday } from "../../model/dates.js";
+import { dim } from "../style.js";
+import { areaMark, LEGEND, shortDate } from "../glyphs.js";
+import { formatItem, renderAnytimePreview, renderLegend, renderList, renderLogbook, renderProjectsSidebar, renderSearch, renderSections, renderSomedayPreview, renderToday, renderUpcoming, stripAnsi, uuidCol, uuidDisplayWidth, } from "../render.js";
+import { invocation, parseCap, parseLimit, runRead, shellQuote, withClient, } from "../read-driver.js";
+import { parsePeriodEnd, parsePeriodStart } from "../period.js";
+import { ExitCode, okEnvelope } from "../../contracts.js";
+import { AREA_PREVIEW_LIMIT, PROJECT_PREVIEW_LIMIT, paginateList, paginateToday, partitionSomedaySection, previewSections, previewSomedaySections, } from "../../read/pagination.js";
+import { ALL_DESC, AREA_LIMIT_DESC, GROUPED_ALL_DESC, LIMIT_DESC, PERIOD_SINCE, PERIOD_UNTIL, PROJECT_LIMIT_DESC, } from "../../surface-copy.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,204 @@ 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} ──`)}`);
-        }
-        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 };
+function registerListView(program, spec) {
+    program
+        .command(spec.name)
+        .description(spec.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("--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 lim = parseLimit(opts);
+        if (!lim.ok)
+            return;
+        const base = invocation(spec.name, [
+            opts.tag !== undefined && `--tag ${shellQuote(opts.tag)}`,
+            opts.exactTag === true && "--exact-tag",
+        ]);
+        runRead(opts, spec.name, (c) => spec.paginate(spec.fetch(c, opts.tag, opts.exactTag), lim.limit), spec.render, base, spec.name);
+    });
 }
-/**
- * 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;
+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(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) }));
+        else {
+            process.stdout.write(`${renderLegend().join("\n")}\n`);
         }
-    }
-    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;
+        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>", "filter by tag (uuid or unique name): direct, inherited, or descendant-tagged")
+        .option("--exact-tag", "match the named tag only — exclude hierarchy descendants")
+        .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 lim = parseLimit(opts);
+        if (!lim.ok)
+            return;
+        const base = invocation("today", [
+            opts.tag !== undefined && `--tag ${shellQuote(opts.tag)}`,
+            opts.exactTag === true && "--exact-tag",
+        ]);
+        runRead(opts, "today", (c) => {
+            const full = c.read.today(opts.tag === undefined
+                ? undefined
+                : { tag: opts.tag, ...(opts.exactTag === true && { exactTag: true }) });
+            const { data, pagination } = paginateToday(full, lim.limit);
+            // The renderer needs the PRE-cap view to keep This Evening honest
+            // under truncation, so the lines are precomputed here; the global
+            // footer (whole-view remainder) is still appended by the driver.
+            return { data, pagination, lines: renderToday(full, data, base) };
+        }, 
+        // Type-correct fallback for the TodayView payload; never reached
+        // because `lines` is always precomputed above.
+        (data) => renderToday(data, data, base), base, "today");
+    });
+    registerListView(program, {
+        name: "inbox",
+        description: "Unprocessed captures (Inbox)",
+        fetch: (c, tag, exactTag) => c.read.inbox(tag === undefined ? undefined : { tag, ...(exactTag === true && { exactTag }) }),
+        render: renderList,
+        paginate: paginateList,
+    });
+    program
+        .command("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. 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>", "filter by tag (uuid or unique name): direct, inherited, or descendant-tagged")
+        .option("--exact-tag", "match the named tag only — exclude hierarchy descendants")
+        .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 (opts.limit !== undefined) {
+            process.stderr.write("error: --limit is not available on anytime — cap blocks with --area-limit / --project-limit, or pass --all\n");
+            process.exitCode = ExitCode.Usage;
+            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);
+        if (!area.ok)
+            return;
+        const project = parseCap("--project-limit", opts.projectLimit, PROJECT_PREVIEW_LIMIT, opts.all === true);
+        if (!project.ok)
+            return;
+        const limits = { area: area.limit, project: project.limit };
+        const base = invocation("anytime", [
+            opts.tag !== undefined && `--tag ${shellQuote(opts.tag)}`,
+            opts.exactTag === true && "--exact-tag",
+        ]);
+        runRead(opts, "anytime", (c) => {
+            const full = c.read.anytime(opts.tag === undefined
+                ? undefined
+                : { tag: opts.tag, ...(opts.exactTag === true && { exactTag: true }) });
+            const { data, grouped } = previewSections(full, limits);
+            return { data, grouped, lines: renderAnytimePreview(full, 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 sidebar 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>", "filter by tag (uuid or unique name): direct, inherited, or descendant-tagged")
+        .option("--exact-tag", "match the named tag only — exclude hierarchy descendants")
+        .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 (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);
+            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);
+        if (!area.ok)
+            return;
+        const limits = { area: area.limit, project: projectCap };
+        const filter = {
+            ...(opts.tag !== undefined && { tag: opts.tag }),
+            ...(opts.exactTag === true && { exactTag: true }),
+        };
+        const base = invocation("someday", [
+            opts.tag !== undefined && `--tag ${shellQuote(opts.tag)}`,
+            opts.exactTag === true && "--exact-tag",
+        ]);
+        runRead(opts, "someday", (c) => {
+            const full = c.read.someday({
+                ...filter,
+                ...(showActive && { activeProjectItems: true }),
+            });
+            // Hidden-items-never-silent: when the toggle is off, one extra
+            // query counts what it would reveal so the hint can say so.
+            const hiddenActiveItems = showActive
+                ? 0
+                : c.read
+                    .someday({ ...filter, activeProjectItems: true })
+                    .reduce((n, s) => n +
+                    partitionSomedaySection(s).children.reduce((m, g) => m + g.items.length, 0), 0);
+            const { data, grouped } = previewSomedaySections(full, limits);
+            return {
+                data,
+                grouped,
+                lines: renderSomedayPreview(full, 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,10 +233,10 @@ 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("--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>", "filter by tag (uuid or unique name): direct, inherited, or descendant-tagged")
         .option("--exact-tag", "match the named tag only — exclude hierarchy descendants")
         .option("--horizon <n>", "occurrences per repeating item (default 1 = UI parity)")
@@ -570,47 +244,49 @@ export function registerReadCommands(program) {
         .option("--db <path>", "explicit database path")
         .action((opts, command) => {
         const untilGiven = command.getOptionValueSource("until") !== "default";
-        if (opts.all === true && untilGiven) {
-            process.stderr.write("error: --all and --until are mutually exclusive\n");
+        const sinceGiven = opts.since !== undefined;
+        if (opts.all === true && (untilGiven || sinceGiven)) {
+            process.stderr.write("error: --all does not combine with --until/--since\n");
             process.exitCode = ExitCode.Usage;
             return;
         }
+        const lim = parseLimit(opts);
+        if (!lim.ok)
+            return;
         const untilDate = opts.all === true ? 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;
             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`);
+        const sinceDate = sinceGiven ? parsePeriodStart(opts.since) : undefined;
+        if (sinceDate !== undefined && Number.isNaN(sinceDate.getTime())) {
+            process.stderr.write(`error: --since is not a parseable period: ${opts.since}\n`);
             process.exitCode = ExitCode.Usage;
             return;
         }
-        let clipped = false;
-        withClient(opts, "upcoming", (c) => {
-            const items = c.read.upcoming({
-                ...(until !== undefined && { until }),
-                ...(opts.tag !== undefined && { tag: opts.tag }),
-                ...(opts.exactTag === true && { exactTag: true }),
-                ...(opts.horizon !== undefined && { horizon: Number(opts.horizon) }),
-            });
-            if (limit !== undefined && items.length > limit) {
-                clipped = true;
-                return items.slice(0, limit);
-            }
-            return items;
-        }, ((items) => {
+        const until = untilDate === undefined ? undefined : localToday(untilDate);
+        const since = sinceDate === undefined ? undefined : localToday(sinceDate);
+        const base = invocation("upcoming", [
+            untilGiven && `--until ${shellQuote(opts.until)}`,
+            sinceGiven && `--since ${shellQuote(opts.since)}`,
+            opts.tag !== undefined && `--tag ${shellQuote(opts.tag)}`,
+            opts.exactTag === true && "--exact-tag",
+            opts.horizon !== undefined && `--horizon ${shellQuote(opts.horizon)}`,
+        ]);
+        runRead(opts, "upcoming", (c) => paginateList(c.read.upcoming({
+            ...(until !== undefined && { until }),
+            ...(since !== undefined && { since }),
+            ...(opts.tag !== undefined && { tag: opts.tag }),
+            ...(opts.exactTag === true && { exactTag: true }),
+            ...(opts.horizon !== undefined && { horizon: Number(opts.horizon) }),
+        }), lim.limit), (items) => {
             const lines = renderUpcoming(items);
-            if (clipped && limit !== undefined) {
-                lines.push("", dim(`(${limit} shown — --limit reached; raise --limit or widen --until)`));
-            }
             if (until !== undefined) {
                 lines.push("", dim(`(through ${shortDate(until, localToday())} — --all for the full horizon)`));
             }
             return lines;
-        }));
+        }, base, "upcoming");
     });
     program
         .command("logbook")
@@ -618,17 +294,20 @@ 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("--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>", "filter by tag (uuid or unique name), direct OR inherited")
         .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")
         .action((opts) => {
+        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 [
@@ -641,40 +320,36 @@ export function registerReadCommands(program) {
                 return;
             }
         }
-        const limit = Number(opts.limit);
-        withClient(opts, "logbook", (c) => c.read.logbook({
-            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)}`,
+            opts.tag !== undefined && `--tag ${shellQuote(opts.tag)}`,
+            opts.exactTag === true && "--exact-tag",
+        ]);
+        runRead(opts, "logbook", (c) => paginateList(c.read.logbook({
+            limit: null,
             ...(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)));
+        }), lim.limit), (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) => paginateList(c.read.trash({ limit: null }), lim.limit), renderList, invocation("trash", []), "trash");
     });
     program
         .command("projects")
@@ -684,21 +359,26 @@ export function registerReadCommands(program) {
         "block (state carried by the (~) mark and ‹date› chip)")
         .option("--area <ref>", "filter by area (uuid or unique name)")
         .option("--show-later", "include someday/future-scheduled projects after each active block")
+        .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) => {
+        // --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;
         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 }),
             });
             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 });
                 const shown = new Set(visible.map((i) => i.uuid));
                 const groups = [
                     { area: null, hidden: 0 },
@@ -717,7 +397,7 @@ 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 });
                 hints = { groups: [{ area: null, hidden: full.length - visible.length }] };
@@ -726,7 +406,7 @@ export function registerReadCommands(program) {
         }, 
         // 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);
@@ -734,26 +414,28 @@ export function registerReadCommands(program) {
             if (hidden > 0)
                 lines.push("", dim(`(${hidden} later project${hidden === 1 ? "" : "s"} — visible with \`--show-later\`)`));
             return lines;
-        }));
+        });
     });
     program
         .command("areas")
         .description("All areas with their direct tags")
+        .option("--all", "show every area (no default restriction applies)")
         .option("--json", "emit versioned JSON envelope on stdout")
         .option("--db <path>", "explicit database path")
         .action((opts) => {
-        withClient(opts, "areas", (c) => c.read.areas(), ((data) => {
+        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)")
+        .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(), (data) => data.map((t) => `${t.uuid}  ${t.parent ? `${t.parent.title}/` : ""}${t.title}`));
     });
     program
         .command("changes")
@@ -761,26 +443,34 @@ 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;
             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) => paginateList(c.read.changes({ since, limit: null }), lim.limit), (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.")
         .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")
@@ -788,19 +478,36 @@ export function registerReadCommands(program) {
         .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 type = opts["type"];
         if (type !== undefined && type !== "todo" && type !== "project") {
             process.stderr.write("error: --type must be todo or project\n");
-            process.exitCode = 2;
+            process.exitCode = ExitCode.Usage;
             return;
         }
-        withClient(opts, "search", (c) => c.read.search(query, {
-            limit: Number(opts["limit"] ?? 50),
+        const all = opts["all"] === true;
+        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, ...(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"])}`,
+            opts["tag"] !== undefined && `--tag ${shellQuote(opts["tag"])}`,
+            opts["exactTag"] === true && "--exact-tag",
+            type !== undefined && `--type ${type}`,
+            opts["logged"] === true && "--logged",
+            opts["trashed"] === true && "--trashed",
+        ]);
+        runRead(opts, "search", (c) => paginateList(c.read.search(query, {
+            limit: null,
             ...(opts["project"] !== undefined && { project: opts["project"] }),
             ...(opts["area"] !== undefined && { area: opts["area"] }),
             ...(opts["tag"] !== undefined && { tag: opts["tag"] }),
@@ -808,8 +515,27 @@ export function registerReadCommands(program) {
             ...(type !== undefined && { type: type === "todo" ? "to-do" : "project" }),
             ...(opts["logged"] === true && { logged: true }),
             ...(opts["trashed"] === true && { trashed: true }),
-            ...(opts["all"] === true && { all: true }),
-        }), renderList);
+            ...(all && { all: true }),
+        }), lim.limit), 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