@bli-cockpit/cli 0.2.67 → 0.2.68

package/dist/commands/cal.js

@@ -0,0 +1,364 @@
+/**
+ * `cockpit cal` — the calendars a person attached, from a terminal
+ * (BLI-3709).
+ *
+ * Ten verbs over `/api/cal/**`, the same doors the browser will use when the
+ * UI lands. Every one of those routes already accepts the collector device
+ * token (`resolveCaller({ allowDeviceToken: true })`), so this command is a
+ * terminal in front of an existing door and adds no authority of its own.
+ *
+ * The CLI is the FIRST surface for this wave, deliberately (AGENTS.md, "CLI is
+ * king"): "when is standup" is a question with a one-line answer, and every
+ * bug fixed here is fixed for the browser and MCP halves that share the doors.
+ *
+ * TWO RULES WORTH KNOWING BEFORE READING THE CODE:
+ *
+ * - **The secret address never touches argv.** `add-ical` reads it from STDIN
+ *   and there is no flag that would take it (`local-args-tower-cal.ts` says
+ *   why in full). It is the one credential this surface handles.
+ * - **The zone is always sent.** Every read passes `--tz`, or this machine's
+ *   own zone from `Intl`, because a window computed server-side would be
+ *   computed in UTC and "today" would end at 5pm in Vancouver.
+ */
+import { askAgentDoor, emitAgentDoor, failAgentDoor, openAgentDoor, } from "./agent-door.js";
+import { isInteractiveStdin, readPipedText, writeLine } from "./cli-io.js";
+const TAG = "[cal cli]";
+const READ_DEADLINE_MS = 30_000;
+const WRITE_DEADLINE_MS = 60_000;
+/** A first read of a crowded calendar can take a while. */
+const SYNC_DEADLINE_MS = 120_000;
+const URL_MAX_CHARS = 2_000;
+export async function runCal(command, io) {
+    const door = await openAgentDoor("cal", command, io);
+    switch (command.action) {
+        case "today":
+        case "week":
+        case "next":
+            return window(command, door);
+        case "find":
+            return find(command, door);
+        case "calendars":
+            return listCalendars(door);
+        case "add-ical":
+            return addIcal(command, door);
+        case "create":
+            return create(command, door);
+        case "share":
+            return share(command, door);
+        case "detach":
+            return detach(command, door);
+        case "sync":
+            return sync(command, door);
+    }
+}
+/**
+ * This machine's own zone, which is what a person means by "today" unless they
+ * say otherwise. `Intl` knows it; there is nothing to configure and nothing to
+ * get out of step with the operating system.
+ */
+export function localTimeZone() {
+    try {
+        return Intl.DateTimeFormat().resolvedOptions().timeZone || "UTC";
+    }
+    catch {
+        return "UTC";
+    }
+}
+function windowQuery(command) {
+    const query = new URLSearchParams({ tz: command.timeZone ?? localTimeZone() });
+    if (command.calendarId)
+        query.set("calendar_id", command.calendarId);
+    if (command.limit !== undefined)
+        query.set("limit", String(command.limit));
+    if (command.includeDeselected)
+        query.set("all", "1");
+    if (command.offset !== undefined)
+        query.set("offset", String(command.offset));
+    if (command.hours !== undefined)
+        query.set("hours", String(command.hours));
+    if (command.from)
+        query.set("from", command.from);
+    if (command.to)
+        query.set("to", command.to);
+    return query;
+}
+async function window(command, door) {
+    // `--from`/`--to` beat a named window, on any of the three verbs: somebody
+    // who named two dates meant them.
+    const path = command.from && command.to ? "events" : command.action;
+    const answer = await askAgentDoor(door, {
+        path: `/api/cal/${path}?${windowQuery(command).toString()}`,
+        method: "GET",
+        label: `cal ${command.action}`,
+        timeoutMs: READ_DEADLINE_MS,
+    });
+    if (!answer.ok)
+        return failAgentDoor(door, TAG, answer.reason, answer.detail);
+    const body = answer.body;
+    if (door.json)
+        return emitAgentDoor(door, { ok: true, ...body });
+    const zone = body.window?.time_zone ?? localTimeZone();
+    const events = body.events ?? [];
+    if (events.length === 0) {
+        writeLine(door.io.stdout, (body.calendars ?? []).length === 0
+            ? "No calendars attached yet. `cockpit cal add-ical` for a personal one, or connect Google in the browser."
+            : `Nothing on ${describeWindow(body, zone)}.`);
+        return 0;
+    }
+    writeLine(door.io.stdout, describeWindow(body, zone));
+    writeLine(door.io.stdout, "");
+    let day = "";
+    for (const event of events) {
+        const eventDay = dayLabel(event.starts_at, zone);
+        if (eventDay !== day) {
+            if (day !== "")
+                writeLine(door.io.stdout, "");
+            writeLine(door.io.stdout, eventDay);
+            day = eventDay;
+        }
+        writeLine(door.io.stdout, eventLine(event, zone));
+    }
+    writeLine(door.io.stdout, "");
+    writeLine(door.io.stdout, `${events.length} event(s) across ${(body.calendars ?? []).length} calendar(s)${body.truncated ? " — more than fitted in one page" : ""}.`);
+    // Never silent about a series this Tower could not expand.
+    for (const note of body.notes ?? []) {
+        writeLine(door.io.stdout, `Note: "${note.title}" repeats on a rule Tower does not expand (${note.detail.join(", ")}), so only its first occurrence is shown.`);
+    }
+    return 0;
+}
+function describeWindow(body, zone) {
+    if (!body.window)
+        return "That window";
+    const from = dayLabel(body.window.from, zone);
+    const to = dayLabel(new Date(new Date(body.window.to).getTime() - 1).toISOString(), zone);
+    if (body.window.label === "next")
+        return `Next, from now (${zone})`;
+    return from === to ? `${from} (${zone})` : `${from} to ${to} (${zone})`;
+}
+function eventLine(event, zone) {
+    const when = event.all_day ? "all day" : `${clock(event.starts_at, zone)}–${clock(event.ends_at, zone)}`;
+    const marks = `${event.recurring ? "↻" : " "}${event.status === "tentative" ? "?" : " "}`;
+    const where = event.location ? `  @ ${event.location.slice(0, 40)}` : "";
+    const who = event.attendee_count > 0 ? `  (${event.attendee_count})` : "";
+    return `${marks} ${when.padEnd(13)}  ${event.title.slice(0, 52).padEnd(52)}${where}${who}`;
+}
+/** `Mon 7 Sep`, in the reader's zone. */
+function dayLabel(instant, zone) {
+    try {
+        return new Intl.DateTimeFormat("en-GB", {
+            timeZone: zone,
+            weekday: "short",
+            day: "numeric",
+            month: "short",
+        }).format(new Date(instant));
+    }
+    catch {
+        return instant.slice(0, 10);
+    }
+}
+function clock(instant, zone) {
+    try {
+        return new Intl.DateTimeFormat("en-GB", {
+            timeZone: zone,
+            hour: "2-digit",
+            minute: "2-digit",
+            hour12: false,
+        }).format(new Date(instant));
+    }
+    catch {
+        return instant.slice(11, 16);
+    }
+}
+async function find(command, door) {
+    const query = new URLSearchParams({ q: command.query ?? "" });
+    if (command.calendarId)
+        query.set("calendar_id", command.calendarId);
+    if (command.limit !== undefined)
+        query.set("limit", String(command.limit));
+    const answer = await askAgentDoor(door, {
+        path: `/api/cal/find?${query.toString()}`,
+        method: "GET",
+        label: "cal find",
+        timeoutMs: READ_DEADLINE_MS,
+    });
+    if (!answer.ok)
+        return failAgentDoor(door, TAG, answer.reason, answer.detail);
+    const matches = answer.body.matches ?? [];
+    if (door.json)
+        return emitAgentDoor(door, { ok: true, query: command.query, matches });
+    if (matches.length === 0) {
+        writeLine(door.io.stdout, `Nothing in your calendars matched "${command.query}".`);
+        return 0;
+    }
+    const zone = command.timeZone ?? localTimeZone();
+    for (const match of matches) {
+        const when = match.next_occurrence
+            ? `${dayLabel(match.next_occurrence, zone)} ${clock(match.next_occurrence, zone)}`
+            : `last on ${dayLabel(match.starts_at, zone)}`;
+        writeLine(door.io.stdout, `${match.recurring ? "↻" : " "} ${when.padEnd(20)}  ${match.title.slice(0, 50).padEnd(50)}  ${match.calendar_name}`);
+    }
+    writeLine(door.io.stdout, "");
+    writeLine(door.io.stdout, `${matches.length} match(es). Times are ${zone}.`);
+    return 0;
+}
+async function listCalendars(door) {
+    const answer = await askAgentDoor(door, {
+        path: "/api/cal/calendars",
+        method: "GET",
+        label: "cal calendars",
+        timeoutMs: READ_DEADLINE_MS,
+    });
+    if (!answer.ok)
+        return failAgentDoor(door, TAG, answer.reason, answer.detail);
+    const calendars = answer.body.calendars ?? [];
+    if (door.json)
+        return emitAgentDoor(door, { ok: true, calendars });
+    if (calendars.length === 0) {
+        writeLine(door.io.stdout, "No calendars attached yet.");
+        writeLine(door.io.stdout, "");
+        writeLine(door.io.stdout, "A personal calendar:  printf \"%s\" \"<secret iCal address>\" | cockpit cal add-ical");
+        writeLine(door.io.stdout, "A work calendar:      connect Google in the browser, then `cockpit cal calendars` again.");
+        return 0;
+    }
+    for (const calendar of calendars) {
+        const health = calendar.status === "active"
+            ? (calendar.last_sync_at ? `synced ${calendar.last_sync_at.slice(0, 16).replace("T", " ")}` : "never synced")
+            : `${calendar.status}: ${calendar.status_reason ?? "no reason recorded"}`;
+        const flags = `${calendar.org_visible ? "shared" : "private"}${calendar.selected ? "" : ", hidden"}`;
+        writeLine(door.io.stdout, `${calendar.name.slice(0, 32).padEnd(32)}  ${calendar.provider.padEnd(12)}  ${flags.padEnd(16)}  ${health}`);
+    }
+    writeLine(door.io.stdout, "");
+    writeLine(door.io.stdout, `${calendars.length} calendar(s). ids: ${calendars.map((calendar) => calendar.id).join(", ")}`);
+    return 0;
+}
+async function addIcal(command, door) {
+    // The address comes from stdin and nowhere else. An interactive terminal
+    // with nothing piped in is told how, rather than left waiting on a prompt
+    // that would echo a permanent credential into the scrollback.
+    if (isInteractiveStdin(door.io)) {
+        return failAgentDoor(door, TAG, "address_required_on_stdin", 'The calendar\'s secret address is read from stdin, never from a flag. Try: printf "%s" "https://calendar.google.com/calendar/ical/…/basic.ics" | cockpit cal add-ical --name "Personal"');
+    }
+    let icalUrl;
+    try {
+        icalUrl = (await readPipedText(door.io.stdin, {
+            maxChars: URL_MAX_CHARS,
+            overflowMessage: "That is longer than any calendar address; nothing was attached.",
+        })).trim();
+    }
+    catch (error) {
+        return failAgentDoor(door, TAG, "address_unreadable", error instanceof Error ? error.message : String(error));
+    }
+    if (icalUrl === "") {
+        return failAgentDoor(door, TAG, "address_required_on_stdin", "Nothing arrived on stdin, so nothing was attached.");
+    }
+    const answer = await askAgentDoor(door, {
+        path: "/api/cal/calendars",
+        method: "POST",
+        label: "cal add-ical",
+        timeoutMs: WRITE_DEADLINE_MS,
+        body: {
+            ical_url: icalUrl,
+            name: command.name ?? null,
+            ...(command.orgVisible ? { org_visible: true } : {}),
+        },
+    });
+    if (!answer.ok)
+        return failAgentDoor(door, TAG, answer.reason, answer.detail);
+    const calendar = answer.body.calendar;
+    if (door.json)
+        return emitAgentDoor(door, { ok: true, calendar });
+    writeLine(door.io.stdout, `Attached (${calendar?.id ?? "no id returned"}).`);
+    writeLine(door.io.stdout, `Nothing is read until a sync runs: \`cockpit cal sync ${calendar?.id ?? "<id>"}\`, or wait for the cron.`);
+    return 0;
+}
+async function create(command, door) {
+    const answer = await askAgentDoor(door, {
+        path: "/api/cal/events",
+        method: "POST",
+        label: "cal create",
+        timeoutMs: WRITE_DEADLINE_MS,
+        body: {
+            calendar_id: command.calendarId,
+            title: command.title,
+            starts_at: command.startsAt,
+            ends_at: command.endsAt,
+            ...(command.location ? { location: command.location } : {}),
+            ...(command.allDay ? { all_day: true } : {}),
+            ...(command.attendees.length > 0 ? { attendees: command.attendees } : {}),
+            time_zone: command.timeZone ?? localTimeZone(),
+        },
+    });
+    if (!answer.ok)
+        return failAgentDoor(door, TAG, answer.reason, answer.detail);
+    const event = answer.body.event;
+    if (door.json)
+        return emitAgentDoor(door, { ok: true, event });
+    const zone = command.timeZone ?? localTimeZone();
+    writeLine(door.io.stdout, `Created "${event?.title ?? command.title}" on ${event ? `${dayLabel(event.starts_at, zone)} ${clock(event.starts_at, zone)}` : "that calendar"}.`);
+    if (event?.html_link)
+        writeLine(door.io.stdout, event.html_link);
+    if (command.attendees.length > 0) {
+        writeLine(door.io.stdout, `Invitations went to ${command.attendees.join(", ")} from Google.`);
+    }
+    return 0;
+}
+async function share(command, door) {
+    const orgVisible = command.orgVisible && !command.makePrivate;
+    const answer = await askAgentDoor(door, {
+        path: `/api/cal/calendars?calendar_id=${encodeURIComponent(command.subjectId ?? "")}`,
+        method: "PATCH",
+        label: "cal share",
+        timeoutMs: WRITE_DEADLINE_MS,
+        body: { org_visible: orgVisible },
+    });
+    if (!answer.ok)
+        return failAgentDoor(door, TAG, answer.reason, answer.detail);
+    const calendar = answer.body.calendar;
+    if (door.json)
+        return emitAgentDoor(door, { ok: true, calendar });
+    writeLine(door.io.stdout, orgVisible
+        ? `"${calendar?.name ?? command.subjectId}" is now readable by everyone at BLI. Nobody but you can change it.`
+        : `"${calendar?.name ?? command.subjectId}" is private again — only you can read it.`);
+    return 0;
+}
+async function detach(command, door) {
+    const answer = await askAgentDoor(door, {
+        path: `/api/cal/calendars?calendar_id=${encodeURIComponent(command.subjectId ?? "")}`,
+        method: "DELETE",
+        label: "cal detach",
+        timeoutMs: WRITE_DEADLINE_MS,
+    });
+    if (!answer.ok)
+        return failAgentDoor(door, TAG, answer.reason, answer.detail);
+    if (door.json)
+        return emitAgentDoor(door, { ok: true, detached: command.subjectId });
+    writeLine(door.io.stdout, `Detached ${command.subjectId}. Its stored events went with it; the calendar itself is untouched at Google.`);
+    return 0;
+}
+async function sync(command, door) {
+    const answer = await askAgentDoor(door, {
+        path: `/api/cal/calendars/${encodeURIComponent(command.subjectId ?? "")}/sync${command.full ? "?full=1" : ""}`,
+        method: "POST",
+        label: "cal sync",
+        timeoutMs: SYNC_DEADLINE_MS,
+    });
+    if (!answer.ok)
+        return failAgentDoor(door, TAG, answer.reason, answer.detail);
+    const run = answer.body.run;
+    if (door.json)
+        return emitAgentDoor(door, { ok: true, run });
+    if (!run) {
+        writeLine(door.io.stdout, "Tower answered without a run. Nothing to report.");
+        return 0;
+    }
+    if (run.reason === "ok") {
+        writeLine(door.io.stdout, run.detail === "feed_unchanged"
+            ? "Nothing has changed on that calendar since the last read."
+            : `Synced: ${run.eventsAdded} new, ${run.eventsUpdated} updated, ${run.eventsDeleted} gone.`);
+        return 0;
+    }
+    // A failure names itself; the exit code says it failed.
+    writeLine(door.io.stderr, `${TAG} sync ${JSON.stringify({ reason: run.reason, detail: run.detail })}`);
+    writeLine(door.io.stdout, `That calendar did not sync: ${run.reason}${run.detail ? ` (${run.detail})` : ""}.`);
+    return 1;
+}

package/dist/commands/local-args-tower-cal.js

@@ -0,0 +1,165 @@
+/**
+ * `cockpit cal` argument parsing (BLI-3709) — the calendar surface's half of
+ * `local-args-tower.ts`, a sibling of `local-args-tower-mail.ts` for the same
+ * reason that file is one: a calendar has its own vocabulary (a window, a
+ * zone, a series, a secret address) and folding it into another family's
+ * parser would stretch that family's doc comment past the truth.
+ *
+ * ONE SECRET NEVER TRAVELS ON ARGV, and it is refused here rather than at the
+ * door: **the secret iCal address**. `cockpit cal add-ical` reads it from
+ * STDIN, always, and there is no `--url` flag to forget about. That address is
+ * a permanent, unauthenticated, read-anything-on-that-calendar credential;
+ * argv is world-readable on a shared machine (`ps`), lands in shell history,
+ * and is captured by this very product's own session harvester. Same rule as
+ * `mail add-imap`, same reasoning, and the same reason neither has an MCP
+ * twin.
+ *
+ * THE ZONE IS ALWAYS SENT. Every read verb passes `--tz` (or the machine's own
+ * zone, read from `Intl`) to the door, because a window computed on the server
+ * would be computed in UTC — "today" would end at 5pm in Vancouver.
+ */
+import { optionalNonEmpty, optionalPositiveInteger, optionalUrl, parseNamedArgs, } from "./local-arg-values.js";
+const CAL_ACTIONS = new Set([
+    "today",
+    "week",
+    "next",
+    "find",
+    "calendars",
+    "add-ical",
+    "create",
+    "share",
+    "detach",
+    "sync",
+]);
+/** Every verb that names ONE calendar first. */
+const CAL_ACTIONS_NEEDING_A_SUBJECT = new Set(["sync", "detach", "share"]);
+export function parseCalArgs(args) {
+    const values = parseNamedArgs(args, {
+        allowedFlags: [
+            "--home",
+            "--dashboard-url",
+            "--calendar",
+            "--tz",
+            "--offset",
+            "--hours",
+            "--from",
+            "--to",
+            "--limit",
+            "--all",
+            "--name",
+            "--title",
+            "--at",
+            "--until",
+            "--location",
+            "--attendee",
+            "--all-day",
+            "--org-visible",
+            "--private",
+            "--full",
+            "--json",
+        ],
+        valueFlags: [
+            "--home",
+            "--dashboard-url",
+            "--calendar",
+            "--tz",
+            "--offset",
+            "--hours",
+            "--from",
+            "--to",
+            "--limit",
+            "--name",
+            "--title",
+            "--at",
+            "--until",
+            "--location",
+            "--attendee",
+        ],
+    });
+    const first = values.positionals[0];
+    const action = (first === undefined ? "today" : first);
+    if (!CAL_ACTIONS.has(action)) {
+        throw new Error(`Unknown cal command: ${first}. Try today, week, next, find, calendars, add-ical, create, share, detach, or sync.`);
+    }
+    const rest = values.positionals.slice(first === undefined ? 0 : 1);
+    let subject;
+    let query;
+    if (CAL_ACTIONS_NEEDING_A_SUBJECT.has(action)) {
+        subject = optionalNonEmpty(rest[0]);
+        if (!subject)
+            throw new Error(`cal ${action} needs a calendar id — take one from \`cockpit cal calendars\`.`);
+        if (rest.length > 1)
+            throw new Error(`cal ${action} takes one id, not ${rest.length}.`);
+    }
+    else if (action === "find") {
+        query = optionalNonEmpty(rest.join(" "));
+        if (!query)
+            throw new Error('cal find needs words: cockpit cal find "standup".');
+    }
+    else if (rest.length > 0) {
+        throw new Error(`cal ${action} does not take "${rest[0]}".`);
+    }
+    const title = optionalNonEmpty(values.flags.get("--title"));
+    const startsAt = optionalNonEmpty(values.flags.get("--at"));
+    const endsAt = optionalNonEmpty(values.flags.get("--until"));
+    if (action === "create") {
+        if (!optionalNonEmpty(values.flags.get("--calendar"))) {
+            throw new Error("cal create needs --calendar <id>: with several calendars attached, which one this goes on is yours to say. `cockpit cal calendars` lists them.");
+        }
+        if (!title)
+            throw new Error('cal create needs --title "<what it is>".');
+        if (!startsAt)
+            throw new Error("cal create needs --at <when it starts> (an ISO instant, or a date with --all-day).");
+        if (!endsAt)
+            throw new Error("cal create needs --until <when it ends>.");
+    }
+    if (action === "share" && !values.booleans.has("--org-visible") && !values.booleans.has("--private")) {
+        throw new Error("cal share needs --org-visible (every member may read it) or --private (only you). Sharing is a decision, not a default.");
+    }
+    const limit = optionalPositiveInteger(values.flags.get("--limit"), "--limit");
+    const offsetRaw = optionalNonEmpty(values.flags.get("--offset"));
+    const offset = offsetRaw === undefined ? undefined : Number.parseInt(offsetRaw, 10);
+    if (offset !== undefined && !Number.isFinite(offset)) {
+        throw new Error("--offset takes a whole number of days (today/next) or weeks (week).");
+    }
+    return {
+        kind: "cal",
+        action,
+        homeDir: optionalNonEmpty(values.flags.get("--home")),
+        dashboardUrl: optionalUrl(values.flags.get("--dashboard-url")),
+        ...(subject ? { subjectId: subject } : {}),
+        ...(query ? { query } : {}),
+        calendarId: optionalNonEmpty(values.flags.get("--calendar")),
+        // An absent `--tz` means "this machine's zone", resolved at run time in
+        // `commands/cal.ts` rather than here, so the parser stays pure.
+        timeZone: optionalNonEmpty(values.flags.get("--tz")),
+        ...(offset === undefined ? {} : { offset }),
+        ...(optionalPositiveInteger(values.flags.get("--hours"), "--hours") === undefined
+            ? {}
+            : { hours: optionalPositiveInteger(values.flags.get("--hours"), "--hours") }),
+        from: optionalNonEmpty(values.flags.get("--from")),
+        to: optionalNonEmpty(values.flags.get("--to")),
+        ...(limit === undefined ? {} : { limit }),
+        includeDeselected: values.booleans.has("--all"),
+        name: optionalNonEmpty(values.flags.get("--name")),
+        title,
+        startsAt,
+        endsAt,
+        location: optionalNonEmpty(values.flags.get("--location")),
+        attendees: splitAddresses(values.flags.get("--attendee")),
+        allDay: values.booleans.has("--all-day"),
+        orgVisible: values.booleans.has("--org-visible"),
+        makePrivate: values.booleans.has("--private"),
+        full: values.booleans.has("--full"),
+        json: values.booleans.has("--json"),
+    };
+}
+/** `a@x.com,b@y.com` → two attendees. Exact, never fuzzy; empties dropped. */
+function splitAddresses(raw) {
+    if (!raw)
+        return [];
+    return raw
+        .split(",")
+        .map((value) => value.trim())
+        .filter((value) => value !== "");
+}

package/dist/commands/local-args-tower.js

@@ -21,6 +21,7 @@
  *   local-args-tower-work.ts    issue, project     — the issue tracker
  *                                                      (BLI-3716)
  *   local-args-tower-mail.ts    mail               — the mailboxes (BLI-3708)
+ *   local-args-tower-cal.ts     cal                — the calendars (BLI-3709)
  *   local-args-tower-search.ts   search            — one bar over all five
  *                                                      corpora (BLI-3728)
  *
@@ -32,4 +33,5 @@ export { SCOUT_MIN_PREFIX_LENGTH, parseScoutArgs, parseOpsArgs, SLACK_WORKSPACE_
 export { parseDocsArgs, parseMsgArgs, } from "./local-args-tower-docs-msg.js";
 export { ISSUE_STATES, parseIssueArgs, parseProjectArgs, } from "./local-args-tower-work.js";
 export { SEARCH_KINDS, parseSearchArgs } from "./local-args-tower-search.js";
-export { parseMailArgs } from "./local-args-tower-mail.js";
+export { parseMailArgs } from "./local-args-tower-mail.js";
+export { parseCalArgs } from "./local-args-tower-cal.js";

package/dist/commands/local-args.js

@@ -16,7 +16,7 @@
  * verbatim, no logic change.
  */
 import { parseAgentRulesArgs, parseAnalyzeArgs, parseAutostartArgs, parseBackfillArgs, parseCleanArgs, parseDoctorArgs, parseInstallArgs, parseLoginArgs, parseMemoryArgs, parseLogoutArgs, parseOnboardArgs, parseReleaseArgs, parseServeArgs, parseSessionsArgs, parseStartArgs, parseStatusArgs, parseSyncArgs, parseUpdateArgs, } from "./local-args-collector.js";
-import { parseBriefArgs, parseCorrectArgs, parseDocsArgs, parseIssueArgs, parseJarvisArgs, parseMailArgs, parseModelArgs, parseMsgArgs, parseNotesArgs, parseOpsArgs, parseProjectArgs, parseScoutArgs, parseSearchArgs, parseSettingsArgs, parseSlackArgs, parseTeamArgs, parseWorkbookArgs, } from "./local-args-tower.js";
+import { parseBriefArgs, parseCorrectArgs, parseDocsArgs, parseIssueArgs, parseJarvisArgs, parseMailArgs, parseCalArgs, parseModelArgs, parseMsgArgs, parseNotesArgs, parseOpsArgs, parseProjectArgs, parseScoutArgs, parseSearchArgs, parseSettingsArgs, parseSlackArgs, parseTeamArgs, parseWorkbookArgs, } from "./local-args-tower.js";
 // `normalizeUrl` has always been part of this module's surface — `local.ts` and
 // `local-auth.ts` import it from here — so it stays exported from this address
 // even though it now lives next door. The same goes for the four names the
@@ -105,6 +105,8 @@ export function parseLocalArgs(argv) {
             return parseIssueArgs(argv.slice(1));
         case "mail":
             return parseMailArgs(argv.slice(1));
+        case "cal":
+            return parseCalArgs(argv.slice(1));
         case "project":
             return parseProjectArgs(argv.slice(1));
         case "search":

package/dist/commands/local-help-commands-tower.js

@@ -0,0 +1,163 @@
+/**
+ * The long-form `cockpit <command> --help` text for the TOWER surfaces —
+ * documents, messages, issues, projects, mail, calendar and search (BLI-3709).
+ *
+ * Split out of `local-help-commands.ts` when that file crossed the 700-line
+ * readability ceiling, and split along the same seam the ARGUMENT parsers
+ * already use (`local-args-tower*.ts`): the collector's own commands — onboard,
+ * sync, backfill, autostart, clean — change for one set of reasons, and the
+ * Tower nouns a person reads and writes through change for another.
+ *
+ * Every string moved verbatim. Help output is what an intern pastes back when
+ * something breaks, so it is a user-visible contract like any other.
+ */
+/** One entry per Tower noun, in the order `cockpit --help` lists them. */
+export const TOWER_COMMAND_HELP = [
+    [
+        "docs",
+        [
+            "Usage: cockpit docs [list|tree|read <id|slug>|create|update <id>] [flags]",
+            "",
+            "The Tower document library, typed. Bare `cockpit docs` lists every document you may read.",
+            "list [--parent <id>|root] [--query <text>] [--limit <n>] — every document you may see: id, visibility, body size, slug, title. Metadata only — a list never carries a body, so it stays cheap enough for an agent to call (--json was 604 KB for 155 documents before BLI-3737, and is now a few tens of KB).",
+            "  --parent <id> lists the documents filed directly under that document; --parent root lists the top of the tree.",
+            "  --query <text> keeps the documents whose title OR body contains that text, matched case-insensitively in the database — never fuzzy, and the body still never comes back.",
+            "  --limit <n> caps the rows (1-1000). Narrow with these before reading: `cockpit docs list --query onboarding --json` then `cockpit docs read <slug>`.",
+            "tree — the same documents nested under their parent, for a sidebar-shaped view.",
+            "read <id|slug> — one document's title, slug, visibility, and its body. This is the ONLY verb that returns a body.",
+            "create --title \"<title>\" [--parent <id>] [--visibility org|private] [--file <path>|--body-stdin] — the body comes from --file, or stdin (`cat body.md | cockpit docs create --title \"...\"`); neither means an empty body, matching the browser's own default.",
+            "update <id|slug> [--title \"<t>\"] [--visibility org|private] [--parent <id>|--clear-parent] [--file <path>|--body-stdin] [--allow-empty] — only the fields you pass change; a `--parent` change IS a move, there is no separate move verb.",
+            "  --allow-empty clears the page on purpose. A body that would empty a document that holds text is refused (refused_empty_body) unless you say so, because far more often it is a surface that lost the content than a person who meant it.",
+            "A document body is never accepted on the command line — --file (safest on Windows) or a pipe only, same discipline as `cockpit notes paste`.",
+            "--json writes one machine-readable object to stdout; every reason and receipt line stays on stderr.",
+            "A refusal keeps Tower's own reason label — needs_rls_client, document_not_found_or_unreadable, document_not_writable, slug_taken, circular_parent, and so on.",
+            "The command uses the existing paired device identity. Run `cockpit login` first if this machine is not paired.",
+        ],
+    ],
+    [
+        "msg",
+        [
+            "Usage: cockpit msg [channels|create <name>|dm <email>|read <channel>|send <channel>|thread <id> --channel <channel>] [flags]",
+            "",
+            "Channels and messages, typed. <channel> is a channel id, or its name with or without a leading #.",
+            "channels — every channel you are a member of (or, as a super_admin, every channel).",
+            "create <name> [--private] [--members a@x.test,b@y.test] [--description \"<text>\"] — makes a channel and prints its id. A leading # is fine; --private means membership decides who may read it, and --members names who joins at birth BY EMAIL. An address Tower does not carry refuses the whole create — no half-built channel.",
+            "dm <email> — opens (or re-opens) the direct message with one person. Idempotent: the same address always resolves to the same channel, and you never have to name yourself.",
+            "read <channel> [--limit <n>] [--thread <id>] — the channel's most recent top-level messages, oldest first; --thread <id> reads one thread's replies instead.",
+            "send <channel> [--thread <id>] — posts a message. The content is never accepted on the command line: pipe it in, e.g. `echo \"hello\" | cockpit msg send general`.",
+            "thread <id> --channel <channel> — one thread's replies by the parent message's id.",
+            "--json writes one machine-readable object to stdout; every reason and receipt line stays on stderr.",
+            "A refusal keeps Tower's own reason label — needs_rls_client, channel_not_found_or_unreadable, content_too_long, and so on.",
+            "The command uses the existing paired device identity. Run `cockpit login` first if this machine is not paired.",
+        ],
+    ],
+    [
+        "issue",
+        [
+            "Usage: cockpit issue [list|show <id>|create|update <id>|move <id> <state>|comment <id>|history <id>] [flags]",
+            "",
+            "Tower's issue tracker. <id> is a BLI-#### identifier (BLI-3654) or an issue's uuid — both work everywhere an issue is named.",
+            "list [--state <s>] [--assignee me|unassigned|<uuid>] [--project <name|id>] [--limit <n>] — the issues you may see, most recently updated first.",
+            "show <id> — one issue: title, state, priority, assignee, description, and every comment on it.",
+            "create --title \"<title>\" [--project <name|id>] [--priority 0-4] [--assignee me|<uuid>] [--parent <id>] [--file <path>] — the DESCRIPTION comes from --file or stdin (`cat plan.md | cockpit issue create --title \"...\"`); neither means no description.",
+            "update <id> [--title \"<t>\"] [--priority 0-4] [--assignee me|<uuid>] [--project <name|id>] [--parent <id>] [--file <path>|--body-stdin] — only the fields you pass change. State does NOT move here; use move.",
+            "move <id> <state> — moves an issue and records the move. States: backlog, todo, in_progress, in_review, done, canceled.",
+            "comment <id> — posts a comment. The body is never taken on the command line: `echo \"shipped\" | cockpit issue comment BLI-3654`.",
+            "history <id> [--limit <n>] — every recorded state move and reassignment, oldest first.",
+            "A project may be named instead of id'd; the name is matched exactly (case-insensitively) against `cockpit project list`.",
+            "--json writes one machine-readable object to stdout; every reason and receipt line stays on stderr.",
+            "A refusal keeps Tower's own reason label — needs_rls_client, issue_not_found_or_unreadable, issue_not_writable, invalid_state, comment_too_long, and so on.",
+            "The command uses the existing paired device identity. Run `cockpit login` first if this machine is not paired.",
+        ],
+    ],
+    [
+        "mail",
+        [
+            "Usage: cockpit mail [accounts|add-imap|inbox|read <thread>|search \"<words>\"|send|attachment <id>|sync <account>|detach <account>] [flags]",
+            "",
+            "Every mailbox you attached, in one place. One person, several addresses — nothing here has a \"current\" mailbox.",
+            "accounts — every mailbox, its provider (gmail_oauth or imap), its health and when it last synced. The ids other verbs take are on the last line.",
+            "add-imap --address <you@gmail.com> [--name \"<display name>\"] — attaches a personal Google account over IMAP + SMTP. The APP PASSWORD is read from stdin and there is no flag for it:",
+            "      macOS:      printf \"%s\" \"abcd efgh ijkl mnop\" | cockpit mail add-imap --address you@gmail.com",
+            "      PowerShell: \"abcd efgh ijkl mnop\" | cockpit mail add-imap --address you@gmail.com",
+            "      Make one at myaccount.google.com/apppasswords (2-Step Verification has to be on). A work @buildlaunchiterate.ca address connects in the browser instead.",
+            "inbox [--account <id>] [--unread] [--label <l>] [--limit <n>] [--before <iso>] — everything across every mailbox, newest first. * is unread, @ has an attachment.",
+            "read <thread> — one conversation with its bodies. Thread ids come from `cockpit mail inbox --json`.",
+            "search \"<words>\" [--account <id>] [--limit <n>] — full text over subject and body. Quotes and OR work the way they do in a search box.",
+            "send --account <id> --to <a[,b]> [--cc <c>] --subject \"<s>\" [--reply-to <message id>] [--file <path>] — the BODY comes from --file or stdin. --account is required: which address this goes out from is yours to say.",
+            "attachment <id> --out <path> — downloads one attachment to a file. Attachments are pointers until you ask; nothing is stored in Tower.",
+            "sync <account> — reads that mailbox now instead of waiting for the cron. Prints what landed, or the reason it did not.",
+            "detach <account> — removes the mailbox, its stored mail and its credential.",
+            "--json writes one machine-readable object to stdout; every reason and receipt line stays on stderr.",
+            "A refusal keeps Tower's own reason label — needs_rls_client, account_not_found_or_unreadable, account_not_active, google_oauth_not_configured, credential_unavailable, and so on.",
+            "The command uses the existing paired device identity. Run `cockpit login` first if this machine is not paired.",
+        ],
+    ],
+    [
+        "cal",
+        [
+            'Usage: cockpit cal [today|week|next|find "<words>"|calendars|add-ical|create|share <id>|sync <id>|detach <id>] [flags]',
+            "",
+            "Every calendar you attached, in one place — plus any calendar a colleague marked shared.",
+            "today [--offset 1] [--tz <zone>] — what is on today, in YOUR zone (this machine's, unless --tz says otherwise). --offset 1 is tomorrow, -1 yesterday.",
+            "week [--offset 1] — Monday to Sunday. The week starts on Monday here.",
+            "next [--hours 12] — what is coming, from RIGHT NOW rather than from midnight. Defaults to the next 72 hours, so a Friday evening still answers.",
+            'find "<words>" — full text over titles, locations and descriptions. A repeating event is answered with the NEXT time it happens, not its first one in 2024.',
+            "calendars — every calendar, its provider (google_oauth or ical_url), whether it is shared, and when it last synced. The ids other verbs take are on the last line.",
+            "add-ical [--name \"<what to call it>\"] — attaches a personal calendar by its SECRET iCal ADDRESS, read from stdin. There is no flag for it:",
+            '      macOS:      printf "%s" "https://calendar.google.com/calendar/ical/…/basic.ics" | cockpit cal add-ical --name "Personal"',
+            '      PowerShell: "https://calendar.google.com/calendar/ical/…/basic.ics" | cockpit cal add-ical --name "Personal"',
+            "      Find it at calendar.google.com -> the calendar's Settings -> \"Secret address in iCal format\". Anybody who has that link can read the calendar, which is why it never goes on a command line.",
+            "      A work @buildlaunchiterate.ca calendar does not need this: connect Google in the browser and `cockpit cal calendars` will list them.",
+            'create --calendar <id> --title "<what>" --at <iso> --until <iso> [--location "<where>"] [--attendee a@x,b@y] [--all-day] — creates the event AT GOOGLE, then here. Attendees are invited by Google.',
+            "      Only a Google calendar can be written to: an iCal secret address is a read address, and `write_not_supported_for_provider` says so by name.",
+            "share <id> --org-visible|--private — makes one of YOUR calendars readable by everyone at BLI, or private again. Sharing never lets anybody else change it.",
+            "sync <id> [--full] — reads that calendar now instead of waiting for the cron. --full ignores the sync token / ETag and re-reads everything.",
+            "detach <id> — removes the calendar and its stored events from Tower. The calendar itself is untouched at Google.",
+            "--json writes one machine-readable object to stdout; every reason and receipt line stays on stderr.",
+            "A refusal keeps Tower's own reason label — needs_rls_client, calendar_not_found_or_unreadable, calendar_not_yours, ical_url_invalid, google_oauth_not_configured, write_not_supported_for_provider, and so on.",
+            "The command uses the existing paired device identity. Run `cockpit login` first if this machine is not paired.",
+        ],
+    ],
+    [
+        "project",
+        [
+            "Usage: cockpit project [list] [--archived] [--json]",
+            "",
+            "The projects issues are filed under. Bare `cockpit project` lists them.",
+            "list [--archived] — id, active/archived, name. --archived includes archived projects.",
+            "There is no create/update/delete verb: `GET /api/work/projects` is the whole of Tower's project door today.",
+            "--json writes one machine-readable object to stdout; every reason and receipt line stays on stderr.",
+        ],
+    ],
+    [
+        "search",
+        [
+            'Usage: cockpit search "<words>" [--kind doc,msg,issue,note,memory] [--limit <n>] [--json]',
+            "",
+            "One bar over five corpora: documents, messages, issues, meeting notes and memory.",
+            "It presses the SAME door the browser's search bar presses (GET /api/search), so what you",
+            "read here is the same row, the same ranking and the same snippet a person sees in Tower.",
+            "",
+            "The words are positional and do not need quoting unless they contain shell metacharacters:",
+            '`cockpit search storage ceiling` and `cockpit search "storage ceiling"` are the same search.',
+            "Quoted phrases and -word work inside the query itself — the query goes to Postgres's",
+            "websearch parser, which shrugs at anything a person can type instead of raising.",
+            "",
+            "--kind narrows to one or more corpora, comma separated. Omit it and all five are searched.",
+            "--limit caps the number of results (default 20, maximum 50).",
+            "--json writes the door's whole answer to stdout, hits, per-kind counts, failures and all.",
+            "",
+            "Every result is scoped by what YOU may read: four of the five corpora are searched on your",
+            "own database session, so a document or a channel you cannot open is not in the list.",
+            "",
+            "A corpus that could not ANSWER gets its own line, separately from \"nothing matched\" —",
+            "those are different facts and folding them together would let a broken search read as silence.",
+            "A memory result has no page to open; the text printed under it is the whole record.",
+            "",
+            "A refusal keeps Tower's own reason label — needs_rls_client, query_too_short, query_too_long,",
+            "unknown_kind, read_failed.",
+            "The command uses the existing paired device identity. Run `cockpit login` first if this machine is not paired.",
+        ],
+    ],
+];

package/dist/commands/local-help-commands.js

@@ -1,6 +1,11 @@
 /**
  * The long-form `cockpit <command> --help` text — one entry per command.
  *
+ * The collector's OWN commands live here; the Tower nouns (docs, msg, issue,
+ * project, mail, cal, search) live in `local-help-commands-tower.ts`, split off
+ * by BLI-3709 when this file crossed the same ceiling — along the seam
+ * `local-args-tower*.ts` already draws.
+ *
  * Split out of `local-help.ts` (BLI-3728) when that file crossed the 700-line
  * readability ceiling. The split is by RESPONSIBILITY, not by size: this file
  * is the per-command manual, `local-help.ts` is the command NAME registry plus
@@ -13,8 +18,12 @@
  */
 import { DEFAULT_DASHBOARD_URL } from "../local-state.js";
 import { localCommandHelp } from "./local-help.js";
+import { TOWER_COMMAND_HELP } from "./local-help-commands-tower.js";
 export function localSubcommandHelp(command) {
     const helpByCommand = new Map([
+        // BLI-3709: the Tower nouns live next door, split along the same seam the
+        // argument parsers already use — see `local-help-commands-tower.ts`.
+        ...TOWER_COMMAND_HELP,
         [
             "onboard",
             [
@@ -544,127 +553,6 @@ export function localSubcommandHelp(command) {
                 "right now.",
             ],
         ],
-        [
-            "docs",
-            [
-                "Usage: cockpit docs [list|tree|read <id|slug>|create|update <id>] [flags]",
-                "",
-                "The Tower document library, typed. Bare `cockpit docs` lists every document you may read.",
-                "list [--parent <id>|root] [--query <text>] [--limit <n>] — every document you may see: id, visibility, body size, slug, title. Metadata only — a list never carries a body, so it stays cheap enough for an agent to call (--json was 604 KB for 155 documents before BLI-3737, and is now a few tens of KB).",
-                "  --parent <id> lists the documents filed directly under that document; --parent root lists the top of the tree.",
-                "  --query <text> keeps the documents whose title OR body contains that text, matched case-insensitively in the database — never fuzzy, and the body still never comes back.",
-                "  --limit <n> caps the rows (1-1000). Narrow with these before reading: `cockpit docs list --query onboarding --json` then `cockpit docs read <slug>`.",
-                "tree — the same documents nested under their parent, for a sidebar-shaped view.",
-                "read <id|slug> — one document's title, slug, visibility, and its body. This is the ONLY verb that returns a body.",
-                "create --title \"<title>\" [--parent <id>] [--visibility org|private] [--file <path>|--body-stdin] — the body comes from --file, or stdin (`cat body.md | cockpit docs create --title \"...\"`); neither means an empty body, matching the browser's own default.",
-                "update <id|slug> [--title \"<t>\"] [--visibility org|private] [--parent <id>|--clear-parent] [--file <path>|--body-stdin] [--allow-empty] — only the fields you pass change; a `--parent` change IS a move, there is no separate move verb.",
-                "  --allow-empty clears the page on purpose. A body that would empty a document that holds text is refused (refused_empty_body) unless you say so, because far more often it is a surface that lost the content than a person who meant it.",
-                "A document body is never accepted on the command line — --file (safest on Windows) or a pipe only, same discipline as `cockpit notes paste`.",
-                "--json writes one machine-readable object to stdout; every reason and receipt line stays on stderr.",
-                "A refusal keeps Tower's own reason label — needs_rls_client, document_not_found_or_unreadable, document_not_writable, slug_taken, circular_parent, and so on.",
-                "The command uses the existing paired device identity. Run `cockpit login` first if this machine is not paired.",
-            ],
-        ],
-        [
-            "msg",
-            [
-                "Usage: cockpit msg [channels|create <name>|dm <email>|read <channel>|send <channel>|thread <id> --channel <channel>] [flags]",
-                "",
-                "Channels and messages, typed. <channel> is a channel id, or its name with or without a leading #.",
-                "channels — every channel you are a member of (or, as a super_admin, every channel).",
-                "create <name> [--private] [--members a@x.test,b@y.test] [--description \"<text>\"] — makes a channel and prints its id. A leading # is fine; --private means membership decides who may read it, and --members names who joins at birth BY EMAIL. An address Tower does not carry refuses the whole create — no half-built channel.",
-                "dm <email> — opens (or re-opens) the direct message with one person. Idempotent: the same address always resolves to the same channel, and you never have to name yourself.",
-                "read <channel> [--limit <n>] [--thread <id>] — the channel's most recent top-level messages, oldest first; --thread <id> reads one thread's replies instead.",
-                "send <channel> [--thread <id>] — posts a message. The content is never accepted on the command line: pipe it in, e.g. `echo \"hello\" | cockpit msg send general`.",
-                "thread <id> --channel <channel> — one thread's replies by the parent message's id.",
-                "--json writes one machine-readable object to stdout; every reason and receipt line stays on stderr.",
-                "A refusal keeps Tower's own reason label — needs_rls_client, channel_not_found_or_unreadable, content_too_long, and so on.",
-                "The command uses the existing paired device identity. Run `cockpit login` first if this machine is not paired.",
-            ],
-        ],
-        [
-            "issue",
-            [
-                "Usage: cockpit issue [list|show <id>|create|update <id>|move <id> <state>|comment <id>|history <id>] [flags]",
-                "",
-                "Tower's issue tracker. <id> is a BLI-#### identifier (BLI-3654) or an issue's uuid — both work everywhere an issue is named.",
-                "list [--state <s>] [--assignee me|unassigned|<uuid>] [--project <name|id>] [--limit <n>] — the issues you may see, most recently updated first.",
-                "show <id> — one issue: title, state, priority, assignee, description, and every comment on it.",
-                "create --title \"<title>\" [--project <name|id>] [--priority 0-4] [--assignee me|<uuid>] [--parent <id>] [--file <path>] — the DESCRIPTION comes from --file or stdin (`cat plan.md | cockpit issue create --title \"...\"`); neither means no description.",
-                "update <id> [--title \"<t>\"] [--priority 0-4] [--assignee me|<uuid>] [--project <name|id>] [--parent <id>] [--file <path>|--body-stdin] — only the fields you pass change. State does NOT move here; use move.",
-                "move <id> <state> — moves an issue and records the move. States: backlog, todo, in_progress, in_review, done, canceled.",
-                "comment <id> — posts a comment. The body is never taken on the command line: `echo \"shipped\" | cockpit issue comment BLI-3654`.",
-                "history <id> [--limit <n>] — every recorded state move and reassignment, oldest first.",
-                "A project may be named instead of id'd; the name is matched exactly (case-insensitively) against `cockpit project list`.",
-                "--json writes one machine-readable object to stdout; every reason and receipt line stays on stderr.",
-                "A refusal keeps Tower's own reason label — needs_rls_client, issue_not_found_or_unreadable, issue_not_writable, invalid_state, comment_too_long, and so on.",
-                "The command uses the existing paired device identity. Run `cockpit login` first if this machine is not paired.",
-            ],
-        ],
-        [
-            "mail",
-            [
-                "Usage: cockpit mail [accounts|add-imap|inbox|read <thread>|search \"<words>\"|send|attachment <id>|sync <account>|detach <account>] [flags]",
-                "",
-                "Every mailbox you attached, in one place. One person, several addresses — nothing here has a \"current\" mailbox.",
-                "accounts — every mailbox, its provider (gmail_oauth or imap), its health and when it last synced. The ids other verbs take are on the last line.",
-                "add-imap --address <you@gmail.com> [--name \"<display name>\"] — attaches a personal Google account over IMAP + SMTP. The APP PASSWORD is read from stdin and there is no flag for it:",
-                "      macOS:      printf \"%s\" \"abcd efgh ijkl mnop\" | cockpit mail add-imap --address you@gmail.com",
-                "      PowerShell: \"abcd efgh ijkl mnop\" | cockpit mail add-imap --address you@gmail.com",
-                "      Make one at myaccount.google.com/apppasswords (2-Step Verification has to be on). A work @buildlaunchiterate.ca address connects in the browser instead.",
-                "inbox [--account <id>] [--unread] [--label <l>] [--limit <n>] [--before <iso>] — everything across every mailbox, newest first. * is unread, @ has an attachment.",
-                "read <thread> — one conversation with its bodies. Thread ids come from `cockpit mail inbox --json`.",
-                "search \"<words>\" [--account <id>] [--limit <n>] — full text over subject and body. Quotes and OR work the way they do in a search box.",
-                "send --account <id> --to <a[,b]> [--cc <c>] --subject \"<s>\" [--reply-to <message id>] [--file <path>] — the BODY comes from --file or stdin. --account is required: which address this goes out from is yours to say.",
-                "attachment <id> --out <path> — downloads one attachment to a file. Attachments are pointers until you ask; nothing is stored in Tower.",
-                "sync <account> — reads that mailbox now instead of waiting for the cron. Prints what landed, or the reason it did not.",
-                "detach <account> — removes the mailbox, its stored mail and its credential.",
-                "--json writes one machine-readable object to stdout; every reason and receipt line stays on stderr.",
-                "A refusal keeps Tower's own reason label — needs_rls_client, account_not_found_or_unreadable, account_not_active, google_oauth_not_configured, credential_unavailable, and so on.",
-                "The command uses the existing paired device identity. Run `cockpit login` first if this machine is not paired.",
-            ],
-        ],
-        [
-            "project",
-            [
-                "Usage: cockpit project [list] [--archived] [--json]",
-                "",
-                "The projects issues are filed under. Bare `cockpit project` lists them.",
-                "list [--archived] — id, active/archived, name. --archived includes archived projects.",
-                "There is no create/update/delete verb: `GET /api/work/projects` is the whole of Tower's project door today.",
-                "--json writes one machine-readable object to stdout; every reason and receipt line stays on stderr.",
-            ],
-        ],
-        [
-            "search",
-            [
-                'Usage: cockpit search "<words>" [--kind doc,msg,issue,note,memory] [--limit <n>] [--json]',
-                "",
-                "One bar over five corpora: documents, messages, issues, meeting notes and memory.",
-                "It presses the SAME door the browser's search bar presses (GET /api/search), so what you",
-                "read here is the same row, the same ranking and the same snippet a person sees in Tower.",
-                "",
-                "The words are positional and do not need quoting unless they contain shell metacharacters:",
-                '`cockpit search storage ceiling` and `cockpit search "storage ceiling"` are the same search.',
-                "Quoted phrases and -word work inside the query itself — the query goes to Postgres's",
-                "websearch parser, which shrugs at anything a person can type instead of raising.",
-                "",
-                "--kind narrows to one or more corpora, comma separated. Omit it and all five are searched.",
-                "--limit caps the number of results (default 20, maximum 50).",
-                "--json writes the door's whole answer to stdout, hits, per-kind counts, failures and all.",
-                "",
-                "Every result is scoped by what YOU may read: four of the five corpora are searched on your",
-                "own database session, so a document or a channel you cannot open is not in the list.",
-                "",
-                "A corpus that could not ANSWER gets its own line, separately from \"nothing matched\" —",
-                "those are different facts and folding them together would let a broken search read as silence.",
-                "A memory result has no page to open; the text printed under it is the whole record.",
-                "",
-                "A refusal keeps Tower's own reason label — needs_rls_client, query_too_short, query_too_long,",
-                "unknown_kind, read_failed.",
-                "The command uses the existing paired device identity. Run `cockpit login` first if this machine is not paired.",
-            ],
-        ],
         [
             "release",
             [

package/dist/commands/local-help.js

@@ -46,6 +46,7 @@ export const rootCommandNames = new Set([
     "msg",
     "issue",
     "mail",
+    "cal",
     "project",
     "search",
     "release",
@@ -91,6 +92,7 @@ export function localCommandHelp(command) {
         "  cockpit msg [channels|create <name>|dm <email>|read <channel>|send <channel>|thread <id> --channel <channel>] [--private] [--members a@x,b@y] [--description <text>] [--thread <id>] [--limit <n>] [--dashboard-url <url>] [--json]",
         "  cockpit issue [list|show <BLI-id>|create --title <t>|update <BLI-id>|move <BLI-id> <state>|comment <BLI-id>|history <BLI-id>] [--state <s>] [--assignee me|unassigned|<uuid>] [--project <name|id>] [--limit <n>] [--priority 0-4] [--parent <BLI-id>] [--file <path>|--body-stdin] [--dashboard-url <url>] [--json]",
         "  cockpit mail [accounts|add-imap --address <a>|inbox|read <thread>|search \"<words>\"|send --account <id> --to <a> --subject <s>|attachment <id> --out <path>|sync <account>|detach <account>] [--account <id>] [--limit <n>] [--unread] [--label <l>] [--file <path>] [--dashboard-url <url>] [--json]",
+        "  cockpit cal [today|week|next|find \"<words>\"|calendars|add-ical|create --calendar <id> --title <t> --at <iso> --until <iso>|share <id> --org-visible|--private|sync <id> [--full]|detach <id>] [--tz <zone>] [--offset <n>] [--hours <n>] [--from <d> --to <d>] [--calendar <id>] [--limit <n>] [--all] [--dashboard-url <url>] [--json]",
         "  cockpit project [list] [--archived] [--dashboard-url <url>] [--json]",
         "  cockpit search \"<words>\" [--kind doc,msg,issue,note,memory] [--limit <n>] [--dashboard-url <url>] [--json]",
         "  cockpit release [--dry-run] [--skip-checks] [--no-floor] [--tag <tag>] [--access <public|restricted>] [--otp <code>]",

package/dist/commands/local.js

@@ -35,6 +35,7 @@ import { runClean } from "./clean.js";
 import { runDocs } from "./docs.js";
 import { runMsg } from "./msg.js";
 import { runIssue } from "./issue.js";
+import { runCal } from "./cal.js";
 import { runMail } from "./mail.js";
 import { runProject } from "./project.js";
 import { runSearch } from "./search.js";
@@ -143,6 +144,8 @@ export async function runLocalCockpitCli(argv, io = defaultIo()) {
                 return await runMsg(command, io);
             case "issue":
                 return await runIssue(command, io);
+            case "cal":
+                return runCal(command, io);
             case "mail":
                 return await runMail(command, io);
             case "project":

package/dist/commands/public-root.js

@@ -15,7 +15,7 @@ export async function runCockpitCli(argv, io) {
   }
 
   if (command === "--version" || command === "-V" || command === "version") {
-    writeLine(io?.stdout ?? process.stdout, "0.2.67");
+    writeLine(io?.stdout ?? process.stdout, "0.2.68");
     return 0;
   }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bli-cockpit/cli",
-  "version": "0.2.67",
+  "version": "0.2.68",
   "private": false,
   "type": "module",
   "bin": {
@@ -28,7 +28,7 @@
   },
   "dependencies": {
     "@bli-cockpit/memory-mcp": "0.1.9",
-    "@bli-cockpit/mcp": "0.1.9",
+    "@bli-cockpit/mcp": "0.1.10",
     "@bli-cockpit/telemetry-core": "0.1.30"
   }
 }