donebear 0.3.9 → 0.4.1

package/dist/cli.mjs

@@ -14,6 +14,7 @@ import { accessSync, constants, existsSync, readdirSync, statSync } from "node:f
 import { config } from "dotenv";
 import { Command, InvalidArgumentError } from "commander";
 import { createHash, randomBytes, randomUUID } from "node:crypto";
+import { DEFAULT_RANK_GAP } from "@donebear/rank-logic";
 import { createServer } from "node:http";
 import { fileURLToPath } from "node:url";
 import Database from "better-sqlite3";
@@ -308,17 +309,17 @@ const refreshAccessToken = (config, refreshToken) => {
 };
 //#endregion
 //#region src/storage.ts
-const isRecord = (value) => typeof value === "object" && value !== null;
+const isRecord$1 = (value) => typeof value === "object" && value !== null;
 const isOAuthProvider = (value) => value === "google" || value === "github" || value === "oauth2";
 const parseStoredAuthSession = (value) => {
-	if (!isRecord(value)) return null;
+	if (!isRecord$1(value)) return null;
 	if (typeof value.accessToken !== "string") return null;
 	if (value.refreshToken !== null && typeof value.refreshToken !== "string") return null;
 	if (value.tokenType !== null && typeof value.tokenType !== "string") return null;
 	if (value.expiresAt !== null && typeof value.expiresAt !== "string") return null;
 	if (!isOAuthProvider(value.provider)) return null;
 	const { user } = value;
-	if (user !== null && (!isRecord(user) || typeof user.id !== "string" || user.email !== null && typeof user.email !== "string")) return null;
+	if (user !== null && (!isRecord$1(user) || typeof user.id !== "string" || user.email !== null && typeof user.email !== "string")) return null;
 	if (typeof value.createdAt !== "string") return null;
 	const parsedUser = user === null ? null : {
 		email: user.email ?? null,
@@ -336,7 +337,7 @@ const parseStoredAuthSession = (value) => {
 };
 const parseAuthFile = (payload) => {
 	const parsed = JSON.parse(payload);
-	if (!isRecord(parsed) || parsed.version !== 1) throw new CliError(`Invalid auth cache format in ${AUTH_FILE_PATH}`, EXIT_CODES.ERROR);
+	if (!isRecord$1(parsed) || parsed.version !== 1) throw new CliError(`Invalid auth cache format in ${AUTH_FILE_PATH}`, EXIT_CODES.ERROR);
 	const session = parseStoredAuthSession(parsed.session);
 	if (!session) throw new CliError(`Invalid auth session in ${AUTH_FILE_PATH}`, EXIT_CODES.ERROR);
 	return {
@@ -348,7 +349,7 @@ const readStoredAuthSession = async () => {
 	try {
 		return parseAuthFile(await readFile(AUTH_FILE_PATH, "utf-8")).session;
 	} catch (error) {
-		if (isRecord(error) && error.code === "ENOENT") return null;
+		if (isRecord$1(error) && error.code === "ENOENT") return null;
 		if (error instanceof CliError) throw error;
 		throw new CliError(`Failed to read credentials from ${AUTH_FILE_PATH}`, EXIT_CODES.ERROR);
 	}
@@ -486,6 +487,568 @@ const resolveTokenStatus = (token) => {
 		expiresInSeconds
 	};
 };
+/**
+* Curated GraphQL selection for agent-facing task reads.
+*
+* This intentionally remains smaller than the Task sync bootstrap surface.
+*/
+const TASK_FIELDS = {
+	bootstrapFields: [
+		"id",
+		"key",
+		"title",
+		"description",
+		"sortOrder",
+		"todaySortOrder",
+		"todayIndexReferenceDate",
+		"createdAt",
+		"updatedAt",
+		"completedAt",
+		"archivedAt",
+		"start",
+		"startDate",
+		"startBucket",
+		"deadlineAt",
+		"deadlineSuppressionAt",
+		"reminderAt",
+		"lastReminderInteractionAt",
+		"creatorId",
+		"workspaceId",
+		"assigneeId",
+		"projectId",
+		"headingId",
+		"teamId",
+		"projectSortOrder",
+		"repeatRule",
+		"repeatType",
+		"repeatStatus",
+		"repeatTemplateId",
+		"repeatInstanceDate",
+		"repeatNextAt"
+	],
+	insertFields: [
+		"archivedAt",
+		"assigneeId",
+		"completedAt",
+		"createdAt",
+		"creatorId",
+		"deadlineAt",
+		"deadlineSuppressionAt",
+		"description",
+		"headingId",
+		"key",
+		"lastReminderInteractionAt",
+		"projectId",
+		"projectSortOrder",
+		"reminderAt",
+		"repeatInstanceDate",
+		"repeatNextAt",
+		"repeatRule",
+		"repeatStatus",
+		"repeatTemplateId",
+		"repeatType",
+		"sortOrder",
+		"start",
+		"startBucket",
+		"startDate",
+		"teamId",
+		"title",
+		"todayIndexReferenceDate",
+		"todaySortOrder",
+		"updatedAt",
+		"workspaceId"
+	],
+	iosKeys: [
+		"id",
+		"key",
+		"title",
+		"description",
+		"sortOrder",
+		"todaySortOrder",
+		"todayIndexReferenceDate",
+		"createdAt",
+		"updatedAt",
+		"completedAt",
+		"archivedAt",
+		"start",
+		"startDate",
+		"startBucket",
+		"deadlineAt",
+		"deadlineSuppressionAt",
+		"reminderAt",
+		"lastReminderInteractionAt",
+		"creatorId",
+		"workspaceId",
+		"assigneeId",
+		"projectId",
+		"headingId",
+		"teamId",
+		"projectSortOrder",
+		"repeatRule",
+		"repeatType",
+		"repeatStatus",
+		"repeatTemplateId",
+		"repeatInstanceDate",
+		"repeatNextAt"
+	],
+	model: "Task",
+	readProjection: [
+		"id",
+		"title",
+		"description",
+		"createdAt",
+		"updatedAt",
+		"completedAt",
+		"archivedAt",
+		"start",
+		"startDate",
+		"startBucket",
+		"todayIndexReferenceDate",
+		"deadlineAt",
+		"creatorId",
+		"workspaceId",
+		"projectId",
+		"teamId",
+		"assigneeId",
+		"headingId",
+		"repeatRule",
+		"repeatTemplateId"
+	],
+	updateFields: [
+		"title",
+		"description",
+		"sortOrder",
+		"todaySortOrder",
+		"todayIndexReferenceDate",
+		"createdAt",
+		"updatedAt",
+		"completedAt",
+		"archivedAt",
+		"start",
+		"startDate",
+		"startBucket",
+		"deadlineAt",
+		"deadlineSuppressionAt",
+		"reminderAt",
+		"lastReminderInteractionAt",
+		"creatorId",
+		"assigneeId",
+		"projectId",
+		"headingId",
+		"teamId",
+		"projectSortOrder",
+		"repeatRule",
+		"repeatType",
+		"repeatStatus",
+		"repeatTemplateId",
+		"repeatInstanceDate",
+		"repeatNextAt"
+	]
+}.readProjection.join("\n");
+//#endregion
+//#region ../../packages/task-logic/src/date-only.ts
+const DATE_ONLY_DAY_MS = 1440 * 60 * 1e3;
+const DATE_ONLY_INPUT_PATTERN = /^(\d{4})-(\d{2})-(\d{2})$/u;
+const isFiniteEpoch$1 = (value) => typeof value === "number" && Number.isFinite(value);
+const isCanonicalDateOnlyEpoch = (value) => value % DATE_ONLY_DAY_MS === 0;
+const getUtcDateOnlyParts = (date) => ({
+	day: date.getUTCDate(),
+	month: date.getUTCMonth() + 1,
+	year: date.getUTCFullYear()
+});
+const isValidDateOnlyParts = (parts) => {
+	if (!(Number.isInteger(parts.year) && Number.isInteger(parts.month) && Number.isInteger(parts.day))) return false;
+	if (parts.year < 1 || parts.month < 1 || parts.month > 12 || parts.day < 1 || parts.day > 31) return false;
+	const candidate = new Date(Date.UTC(parts.year, parts.month - 1, parts.day));
+	return candidate.getUTCFullYear() === parts.year && candidate.getUTCMonth() + 1 === parts.month && candidate.getUTCDate() === parts.day;
+};
+const parseDateOnlyInput = (value) => {
+	if (typeof value !== "string") return null;
+	const match = DATE_ONLY_INPUT_PATTERN.exec(value.trim());
+	if (!match) return null;
+	const parts = {
+		day: Number(match[3]),
+		month: Number(match[2]),
+		year: Number(match[1])
+	};
+	return isValidDateOnlyParts(parts) ? parts : null;
+};
+const dateOnlyPartsToEpoch = (parts) => isValidDateOnlyParts(parts) ? Date.UTC(parts.year, parts.month - 1, parts.day) : null;
+const epochToDateOnlyParts = (epoch) => {
+	if (!isFiniteEpoch$1(epoch)) return null;
+	const date = new Date(epoch);
+	return Number.isNaN(date.getTime()) ? null : getUtcDateOnlyParts(date);
+};
+const formatDateOnlyParts = (parts) => isValidDateOnlyParts(parts) ? `${String(parts.year).padStart(4, "0")}-${String(parts.month).padStart(2, "0")}-${String(parts.day).padStart(2, "0")}` : null;
+const formatDateOnlyEpoch = (epoch) => {
+	const parts = epochToDateOnlyParts(epoch);
+	return parts ? formatDateOnlyParts(parts) : null;
+};
+const normalizeDateOnlyEpoch = (value) => {
+	if (!(isFiniteEpoch$1(value) && isCanonicalDateOnlyEpoch(value))) return null;
+	return value;
+};
+const parseDateOnlyInputToEpoch = (value) => {
+	const parts = parseDateOnlyInput(value);
+	return parts ? dateOnlyPartsToEpoch(parts) : null;
+};
+const localDateToDateOnlyEpoch = (date) => Date.UTC(date.getFullYear(), date.getMonth(), date.getDate());
+const getTodayDateOnlyEpoch = (now = /* @__PURE__ */ new Date()) => localDateToDateOnlyEpoch(now);
+//#endregion
+//#region ../../packages/task-logic/src/task-status.ts
+const normalizeStart = (value) => {
+	if (typeof value !== "string") return null;
+	const trimmed = value.trim().toLowerCase();
+	if (trimmed === "not_started") return "not_started";
+	if (trimmed === "started") return "started";
+	if (trimmed === "someday") return "someday";
+	return null;
+};
+const isNullish = (value) => value === null || value === void 0;
+const isRepeatTemplate = (task) => !isNullish(task.repeatRule) && isNullish(task.repeatTemplateId);
+const getTaskState$1 = (task) => {
+	if (!isNullish(task.archivedAt)) return "archived";
+	if (!isNullish(task.completedAt)) return "done";
+	return "open";
+};
+/**
+* Derive the GTD bucket a task belongs to. `todayEpoch` is a canonical
+* UTC-midnight date-only epoch (compute it via getTodayDateOnlyEpoch).
+*
+* Note: this deliberately does NOT hide repeat templates. Template hiding is a
+* list/retention concern that callers apply via isRepeatTemplate.
+*/
+const getTaskView = (task, todayEpoch) => {
+	if (!isNullish(task.archivedAt)) return "trash";
+	if (!isNullish(task.completedAt)) return "logbook";
+	const start = normalizeStart(task.start);
+	const startDate = normalizeDateOnlyEpoch(task.startDate);
+	const deadline = normalizeDateOnlyEpoch(task.deadlineAt);
+	const isDeadlineDue = deadline !== null && deadline <= todayEpoch;
+	const tomorrow = todayEpoch + DATE_ONLY_DAY_MS;
+	if (start === null) return null;
+	if (start === "not_started") return isDeadlineDue ? "today" : "inbox";
+	if (start === "someday") return isDeadlineDue ? "today" : "someday";
+	if (startDate === null) return isDeadlineDue ? "today" : "anytime";
+	if (startDate < tomorrow || isDeadlineDue) return "today";
+	return "upcoming";
+};
+/**
+* Canonical 3-field start shape for a target view. (cli/raycast additionally
+* emit a 4th `todayIndexReferenceDate`; that is a client concern and is
+* intentionally NOT produced here.)
+*/
+const buildTaskStartFields$1 = (view, options = {}) => {
+	const today = options.todayEpoch ?? getTodayDateOnlyEpoch(options.now);
+	const tomorrow = today + DATE_ONLY_DAY_MS;
+	const startDate = normalizeDateOnlyEpoch(options.startDate);
+	switch (view) {
+		case "inbox": return {
+			start: "not_started",
+			startBucket: "today",
+			startDate: null
+		};
+		case "anytime": return {
+			start: "started",
+			startBucket: "today",
+			startDate: null
+		};
+		case "someday": return {
+			start: "someday",
+			startBucket: "today",
+			startDate: null
+		};
+		case "today": return {
+			start: "started",
+			startBucket: "today",
+			startDate: startDate ?? today
+		};
+		case "upcoming": return {
+			start: "started",
+			startBucket: "upcoming",
+			startDate: startDate ?? tomorrow
+		};
+		default: return {
+			start: "not_started",
+			startBucket: "today",
+			startDate: null
+		};
+	}
+};
+//#endregion
+//#region ../../packages/manage-client/src/mutations.ts
+const startFieldsForView = (view, todayEpoch, startDate) => ({
+	...buildTaskStartFields$1(view, {
+		startDate,
+		todayEpoch
+	}),
+	todayIndexReferenceDate: view === "today" ? todayEpoch : null
+});
+const buildTaskInsertFields = (input) => ({
+	archivedAt: null,
+	completedAt: null,
+	createdAt: input.now,
+	creatorId: input.ids.creatorId,
+	deadlineAt: input.deadlineAt ?? null,
+	description: input.description ?? null,
+	key: input.ids.taskId.replaceAll("-", "").slice(0, 8),
+	projectId: input.projectId ?? null,
+	sortOrder: input.sortOrder ?? DEFAULT_RANK_GAP,
+	teamId: input.teamId ?? null,
+	title: input.title,
+	todaySortOrder: input.todaySortOrder ?? DEFAULT_RANK_GAP,
+	updatedAt: input.now,
+	workspaceId: input.ids.workspaceId,
+	...startFieldsForView(input.view, input.todayEpoch, input.startDate)
+});
+const buildMutateEnvelope = ({ batchId, clientId, clientTxIds, transactions }) => {
+	if (transactions.length !== clientTxIds.length) throw new Error("A client transaction ID is required for every transaction");
+	return {
+		batchId,
+		transactions: transactions.map((transaction, index) => {
+			const clientTxId = clientTxIds[index];
+			if (!clientTxId) throw new Error("Client transaction IDs cannot be empty");
+			return {
+				...transaction,
+				clientId,
+				clientTxId
+			};
+		})
+	};
+};
+//#endregion
+//#region ../../packages/manage-client/src/sync-mutate.ts
+const normalizeBaseUrl$1 = (value) => value.endsWith("/") ? value.slice(0, -1) : value;
+const isRecord = (value) => typeof value === "object" && value !== null;
+const parseResult = (value) => {
+	if (!isRecord(value)) return null;
+	if (typeof value.clientTxId !== "string" || typeof value.success !== "boolean") return null;
+	if (value.error !== void 0 && typeof value.error !== "string") return null;
+	if (value.syncId !== void 0 && typeof value.syncId !== "string") return null;
+	return {
+		clientTxId: value.clientTxId,
+		success: value.success,
+		...value.error === void 0 ? {} : { error: value.error },
+		...value.syncId === void 0 ? {} : { syncId: value.syncId }
+	};
+};
+const parseResponse = (value) => {
+	if (!isRecord(value) || typeof value.success !== "boolean" || typeof value.lastSyncId !== "string" || !Array.isArray(value.results)) return null;
+	const results = value.results.map(parseResult);
+	if (results.some((result) => result === null)) return null;
+	return {
+		lastSyncId: value.lastSyncId,
+		results,
+		success: value.success
+	};
+};
+const defaultErrorMapper$1 = (failure) => {
+	if (failure.type === "timeout") return new Error(`Sync mutation timed out after ${failure.timeoutMs}ms`, { cause: failure.cause });
+	if (failure.type === "http") return /* @__PURE__ */ new Error(`Sync mutation failed with HTTP ${failure.status}`);
+	if (failure.type === "mutation") {
+		const result = failure.response.results.find((item) => !item.success);
+		return new Error(result?.error ?? "Sync mutation failed");
+	}
+	if (failure.type === "invalid-response") return new Error("Sync mutation returned an invalid response", { cause: failure.cause });
+	return failure.cause instanceof Error ? failure.cause : new Error("Sync mutation request failed", { cause: failure.cause });
+};
+const isTimeoutError$1 = (error) => error instanceof Error && error.name === "TimeoutError";
+const createSyncMutateClient = ({ baseUrl, errorMapper = defaultErrorMapper$1, fetch: fetchImplementation = globalThis.fetch, getToken, timeoutMs }) => {
+	if (!fetchImplementation) throw new Error("A fetch implementation is required");
+	const mutate = async (request, options = {}) => {
+		const timeoutSignal = timeoutMs === void 0 ? void 0 : AbortSignal.timeout(timeoutMs);
+		const signal = options.signal && timeoutSignal ? AbortSignal.any([options.signal, timeoutSignal]) : options.signal ?? timeoutSignal;
+		let response;
+		try {
+			response = await fetchImplementation(`${normalizeBaseUrl$1(baseUrl)}/sync/mutate`, {
+				body: JSON.stringify(request),
+				headers: {
+					Accept: "application/json",
+					Authorization: `Bearer ${await getToken()}`,
+					"Content-Type": "application/json"
+				},
+				method: "POST",
+				signal
+			});
+		} catch (error) {
+			if (timeoutMs !== void 0 && (timeoutSignal?.aborted || isTimeoutError$1(error))) throw errorMapper({
+				cause: error,
+				timeoutMs,
+				type: "timeout"
+			});
+			throw errorMapper({
+				cause: error,
+				type: "network"
+			});
+		}
+		if (!response.ok) throw errorMapper({
+			body: await response.text(),
+			status: response.status,
+			type: "http"
+		});
+		let raw;
+		try {
+			raw = await response.json();
+		} catch (error) {
+			throw errorMapper({
+				cause: error,
+				type: "invalid-response"
+			});
+		}
+		const payload = parseResponse(raw);
+		if (!payload) throw errorMapper({
+			cause: /* @__PURE__ */ new TypeError("Malformed sync mutation response"),
+			type: "invalid-response"
+		});
+		if (!payload.success) throw errorMapper({
+			response: payload,
+			type: "mutation"
+		});
+		return payload;
+	};
+	return { mutate };
+};
+//#endregion
+//#region ../../packages/manage-client/src/index.ts
+const TASKS_QUERY = `
+  query DonebearTasks($first: Int!, $after: String, $workspaceId: ID!) {
+    tasks(first: $first, after: $after, filter: { workspaceId: { eq: $workspaceId } }) {
+      nodes { ${TASK_FIELDS} }
+      pageInfo { hasNextPage endCursor }
+    }
+  }
+`;
+const MY_WORKSPACES_QUERY = `
+  query MyWorkspaces {
+    myWorkspaces {
+      id name urlKey logoUrl role createdAt updatedAt
+    }
+  }
+`;
+const normalizeBaseUrl = (value) => value.endsWith("/") ? value.slice(0, -1) : value;
+const toInstantEpoch = (value) => {
+	if (typeof value !== "string") return null;
+	const epoch = Date.parse(value);
+	return Number.isFinite(epoch) ? epoch : null;
+};
+const toTaskRecord$1 = (node) => ({
+	archivedAt: toInstantEpoch(node.archivedAt),
+	assigneeId: node.assigneeId,
+	completedAt: toInstantEpoch(node.completedAt),
+	createdAt: toInstantEpoch(node.createdAt),
+	creatorId: node.creatorId,
+	deadlineAt: parseDateOnlyInputToEpoch(node.deadlineAt),
+	description: node.description,
+	headingId: node.headingId,
+	id: node.id,
+	projectId: node.projectId,
+	repeatRule: node.repeatRule,
+	repeatTemplateId: node.repeatTemplateId,
+	start: node.start,
+	startBucket: node.startBucket,
+	startDate: parseDateOnlyInputToEpoch(node.startDate),
+	teamId: node.teamId,
+	title: node.title,
+	todayIndexReferenceDate: parseDateOnlyInputToEpoch(node.todayIndexReferenceDate),
+	updatedAt: toInstantEpoch(node.updatedAt),
+	workspaceId: node.workspaceId
+});
+const defaultErrorMapper = (failure) => {
+	if (failure.type === "timeout") return new Error(`GraphQL request timed out after ${failure.timeoutMs}ms`, { cause: failure.cause });
+	if (failure.type === "http") return /* @__PURE__ */ new Error(`GraphQL request failed with HTTP ${failure.status}`);
+	if (failure.type === "graphql") return new Error(failure.errors[0]?.message ?? "GraphQL request failed");
+	if (failure.type === "missing-data") return /* @__PURE__ */ new Error("GraphQL request returned no data");
+	return failure.cause instanceof Error ? failure.cause : new Error("GraphQL request failed", { cause: failure.cause });
+};
+const isTimeoutError = (error) => error instanceof Error && error.name === "TimeoutError";
+const createGraphqlClient = ({ baseUrl, errorMapper = defaultErrorMapper, fetch: fetchImplementation = globalThis.fetch, getToken, timeoutMs }) => {
+	if (!fetchImplementation) throw new Error("A fetch implementation is required");
+	const graphqlRequest = async ({ query, signal: requestSignal, variables = {} }) => {
+		const timeoutSignal = timeoutMs === void 0 ? void 0 : AbortSignal.timeout(timeoutMs);
+		const signal = requestSignal && timeoutSignal ? AbortSignal.any([requestSignal, timeoutSignal]) : requestSignal ?? timeoutSignal;
+		let response;
+		try {
+			response = await fetchImplementation(`${normalizeBaseUrl(baseUrl)}/graphql`, {
+				body: JSON.stringify({
+					query,
+					variables
+				}),
+				headers: {
+					Authorization: `Bearer ${await getToken()}`,
+					"Content-Type": "application/json"
+				},
+				method: "POST",
+				signal
+			});
+		} catch (error) {
+			if (timeoutMs !== void 0 && (timeoutSignal?.aborted || isTimeoutError(error))) throw errorMapper({
+				cause: error,
+				timeoutMs,
+				type: "timeout"
+			});
+			throw errorMapper({
+				cause: error,
+				type: "network"
+			});
+		}
+		if (!response.ok) throw errorMapper({
+			body: await response.text(),
+			status: response.status,
+			type: "http"
+		});
+		let payload;
+		try {
+			payload = await response.json();
+		} catch (error) {
+			throw errorMapper({
+				cause: error,
+				type: "network"
+			});
+		}
+		if (payload.errors?.length) throw errorMapper({
+			errors: payload.errors,
+			type: "graphql"
+		});
+		if (payload.data === void 0) throw errorMapper({ type: "missing-data" });
+		return payload.data;
+	};
+	const paginate = async ({ nodeKey, pageSize = 100, query, signal, transform, variables = {} }) => {
+		const records = [];
+		let after = null;
+		for (let pageCount = 0; pageCount < 1e3; pageCount += 1) {
+			const connection = (await graphqlRequest({
+				query,
+				signal,
+				variables: {
+					...variables,
+					after,
+					first: pageSize
+				}
+			}))[nodeKey];
+			if (!connection) throw new Error(`GraphQL response is missing connection: ${nodeKey}`);
+			for (const node of connection.nodes) records.push(transform(node));
+			if (!connection.pageInfo.hasNextPage) return records;
+			if (!connection.pageInfo.endCursor) throw new Error("GraphQL page has no end cursor");
+			after = connection.pageInfo.endCursor;
+		}
+		throw new Error("GraphQL pagination exceeded safe page limit");
+	};
+	const listWorkspaces = async () => {
+		return (await graphqlRequest({ query: MY_WORKSPACES_QUERY })).myWorkspaces.map((workspace) => ({ ...workspace }));
+	};
+	const listTasks = (workspaceId) => paginate({
+		nodeKey: "tasks",
+		query: TASKS_QUERY,
+		transform: toTaskRecord$1,
+		variables: { workspaceId }
+	});
+	return {
+		graphqlRequest,
+		listTasks,
+		listWorkspaces,
+		paginate
+	};
+};
 //#endregion
 //#region src/api/http.ts
 const extractErrorMessage = (value) => {
@@ -536,62 +1099,15 @@ const requestNdjson = async (context, endpoint, options) => {
 };
 //#endregion
 //#region src/date-codecs.ts
-const ISO_DATE_ONLY_REGEX = /^(\d{4})-(\d{2})-(\d{2})$/u;
 const ISO_INSTANT_REGEX = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{1,9})?(?:Z|[+-]\d{2}:\d{2})$/u;
-const pad = (value, length = 2) => String(value).padStart(length, "0");
 const isFiniteEpoch = (value) => typeof value === "number" && Number.isFinite(value);
-const isValidDateOnlyParts = (parts) => {
-	if (!(Number.isInteger(parts.year) && Number.isInteger(parts.month) && Number.isInteger(parts.day))) return false;
-	if (parts.year < 1 || parts.month < 1 || parts.month > 12 || parts.day < 1 || parts.day > 31) return false;
-	const candidate = new Date(Date.UTC(parts.year, parts.month - 1, parts.day));
-	return candidate.getUTCFullYear() === parts.year && candidate.getUTCMonth() === parts.month - 1 && candidate.getUTCDate() === parts.day;
-};
-const dateOnlyPartsToEpoch = (parts) => {
-	if (!isValidDateOnlyParts(parts)) return null;
-	return Date.UTC(parts.year, parts.month - 1, parts.day);
-};
-const epochToDateOnlyParts = (epochMs) => {
-	if (!isFiniteEpoch(epochMs)) return null;
-	const date = new Date(epochMs);
-	if (Number.isNaN(date.getTime())) return null;
-	return {
-		day: date.getUTCDate(),
-		month: date.getUTCMonth() + 1,
-		year: date.getUTCFullYear()
-	};
-};
-const formatDateOnlyParts = (parts) => {
-	if (!isValidDateOnlyParts(parts)) return null;
-	return `${pad(parts.year, 4)}-${pad(parts.month)}-${pad(parts.day)}`;
-};
-const formatDateOnlyEpoch = (epochMs) => {
-	const parts = epochToDateOnlyParts(epochMs);
-	return parts ? formatDateOnlyParts(parts) : null;
-};
 const formatInstantEpoch = (epochMs) => {
 	if (!isFiniteEpoch(epochMs)) return null;
 	const date = new Date(epochMs);
 	if (Number.isNaN(date.getTime())) return null;
 	return date.toISOString();
 };
-const parseDateOnlyString = (value) => {
-	if (typeof value !== "string") return null;
-	const trimmed = value.trim();
-	const match = ISO_DATE_ONLY_REGEX.exec(trimmed);
-	if (!match) return null;
-	const year = Number.parseInt(match[1] ?? "", 10);
-	const month = Number.parseInt(match[2] ?? "", 10);
-	const parts = {
-		day: Number.parseInt(match[3] ?? "", 10),
-		month,
-		year
-	};
-	return isValidDateOnlyParts(parts) ? parts : null;
-};
-const parseApiDateOnlyToEpoch = (value) => {
-	const parts = parseDateOnlyString(value);
-	return parts ? dateOnlyPartsToEpoch(parts) : null;
-};
+const parseApiDateOnlyToEpoch = (value) => parseDateOnlyInputToEpoch(value);
 const parseApiInstantToEpoch = (value) => {
 	if (typeof value !== "string") return null;
 	const trimmed = value.trim();
@@ -601,47 +1117,19 @@ const parseApiInstantToEpoch = (value) => {
 };
 const parseCliDateOnlyToEpoch = (value, fieldLabel) => {
 	if (!value) return null;
-	const parts = parseDateOnlyString(value);
-	if (!parts) throw new Error(`Invalid ${fieldLabel}: ${value}. Expected YYYY-MM-DD.`);
-	return dateOnlyPartsToEpoch(parts);
+	const epoch = parseDateOnlyInputToEpoch(value);
+	if (epoch === null) throw new Error(`Invalid ${fieldLabel}: ${value}. Expected YYYY-MM-DD.`);
+	return epoch;
 };
-const dateOnlyEpochFromLocalDate = (now = /* @__PURE__ */ new Date()) => Date.UTC(now.getFullYear(), now.getMonth(), now.getDate());
+const dateOnlyEpochFromLocalDate = (now = /* @__PURE__ */ new Date()) => localDateToDateOnlyEpoch(now);
 //#endregion
 //#region src/manage-api.ts
-const TASK_FIELDS = `
-  id
-  title
-  description
-  createdAt
-  updatedAt
-  completedAt
-  archivedAt
-  start
-  startDate
-  startBucket
-  todayIndexReferenceDate
-  deadlineAt
-  creatorId
-  workspaceId
-  projectId
-  teamId
-  assigneeId
-  headingId
-  repeatRule
-  repeatTemplateId
-`;
-const TASKS_QUERY = `
-  query DonebearTasks($first: Int!, $after: String, $workspaceId: ID!) {
-    tasks(first: $first, after: $after, filter: { workspaceId: { eq: $workspaceId } }) {
-      nodes { ${TASK_FIELDS} }
-      pageInfo { hasNextPage endCursor }
-    }
-  }
-`;
 const TASKS_ALL_QUERY = `
   query DonebearTasksAll($first: Int!, $after: String, $workspaceIds: [ID!]!) {
     tasks(first: $first, after: $after, filter: { workspaceId: { in: $workspaceIds } }) {
-      nodes { ${TASK_FIELDS} }
+      nodes {
+        ${TASK_FIELDS}
+      }
       pageInfo { hasNextPage endCursor }
     }
   }
@@ -700,13 +1188,6 @@ const TEAMS_ALL_QUERY = `
     }
   }
 `;
-const MY_WORKSPACES_QUERY = `
-  query MyWorkspaces {
-    myWorkspaces {
-      id name urlKey logoUrl role createdAt updatedAt
-    }
-  }
-`;
 const WORKSPACE_CREATE_MUTATION = `
   mutation WorkspaceCreate($input: WorkspaceCreateInput!) {
     workspaceCreate(input: $input) {
@@ -778,8 +1259,9 @@ const API_KEY_REVOKE_MUTATION = `
   }
 `;
 const normalizeApiUrl = (url) => url.endsWith("/") ? url.slice(0, -1) : url;
-const requestGraphql = async (context, endpoint, options) => {
-	const response = await requestJson(context, endpoint, {
+const omitUndefined = (entries) => Object.fromEntries(Object.entries(entries).filter(([, value]) => value !== void 0));
+const requestGraphql = async (context, baseUrl, options) => {
+	const response = await requestJson(context, `${baseUrl}/graphql`, {
 		body: {
 			query: options.query,
 			variables: options.variables
@@ -795,14 +1277,13 @@ const requestGraphql = async (context, endpoint, options) => {
 	return response.data;
 };
 const paginateGraphql = async (context, options) => {
-	const endpoint = `${options.baseUrl}/graphql`;
 	const results = [];
 	let after = null;
 	let pageCount = 0;
 	while (true) {
 		pageCount += 1;
 		if (pageCount > 1e3) throw new CliError("GraphQL pagination exceeded safe page limit", EXIT_CODES.ERROR);
-		const connection = (await requestGraphql(context, endpoint, {
+		const connection = (await requestGraphql(context, options.baseUrl, {
 			query: options.query,
 			token: options.token,
 			variables: {
@@ -851,28 +1332,6 @@ const toNullableNumber = (input) => {
 	if (input === null || input === void 0) return null;
 	return typeof input === "number" ? input : null;
 };
-const toTaskRecordFromGraphqlNode = (node) => ({
-	archivedAt: parseApiInstantToEpoch(node.archivedAt),
-	assigneeId: node.assigneeId,
-	completedAt: parseApiInstantToEpoch(node.completedAt),
-	createdAt: parseApiInstantToEpoch(node.createdAt),
-	creatorId: node.creatorId,
-	deadlineAt: parseApiDateOnlyToEpoch(node.deadlineAt),
-	description: node.description,
-	headingId: node.headingId,
-	id: node.id,
-	projectId: node.projectId,
-	repeatRule: node.repeatRule,
-	repeatTemplateId: node.repeatTemplateId,
-	start: node.start,
-	startBucket: node.startBucket,
-	startDate: parseApiDateOnlyToEpoch(node.startDate),
-	teamId: node.teamId,
-	title: node.title,
-	todayIndexReferenceDate: parseApiDateOnlyToEpoch(node.todayIndexReferenceDate),
-	updatedAt: parseApiInstantToEpoch(node.updatedAt),
-	workspaceId: node.workspaceId
-});
 const toProjectRecordFromGraphqlNode = (node) => ({
 	archivedAt: parseApiInstantToEpoch(node.archivedAt),
 	completedAt: parseApiInstantToEpoch(node.completedAt),
@@ -905,15 +1364,6 @@ const toTeamRecordFromGraphqlNode = (node) => ({
 	updatedAt: parseApiInstantToEpoch(node.updatedAt),
 	workspaceId: node.workspaceId
 });
-const toWorkspaceSummaryFromGraphqlNode = (node) => ({
-	createdAt: node.createdAt,
-	id: node.id,
-	logoUrl: node.logoUrl,
-	name: node.name,
-	role: node.role,
-	updatedAt: node.updatedAt,
-	urlKey: node.urlKey
-});
 const toWorkspaceRecordFromGraphqlNode = (node) => ({
 	archivedAt: node.archivedAt,
 	createdAt: node.createdAt,
@@ -993,7 +1443,7 @@ const VIEWER_QUERY = `
   }
 `;
 const loadViewer = async (context, options) => {
-	const data = await requestGraphql(context, `${options.baseUrl}/graphql`, {
+	const data = await requestGraphql(context, options.baseUrl, {
 		query: VIEWER_QUERY,
 		token: options.token,
 		variables: {}
@@ -1004,22 +1454,19 @@ const loadViewer = async (context, options) => {
 		id: data.viewer.id
 	};
 };
-const listWorkspaces = async (context, options) => {
-	return (await requestGraphql(context, `${options.baseUrl}/graphql`, {
-		query: MY_WORKSPACES_QUERY,
-		token: options.token,
-		variables: {}
-	})).myWorkspaces.map(toWorkspaceSummaryFromGraphqlNode);
-};
+const listWorkspaces = async (_context, options) => await createGraphqlClient({
+	baseUrl: options.baseUrl,
+	getToken: () => options.token
+}).listWorkspaces();
 const createWorkspace = async (context, options) => {
-	return toWorkspaceRecordFromGraphqlNode((await requestGraphql(context, `${options.baseUrl}/graphql`, {
+	return toWorkspaceRecordFromGraphqlNode((await requestGraphql(context, options.baseUrl, {
 		query: WORKSPACE_CREATE_MUTATION,
 		token: options.token,
 		variables: { input: options.body }
 	})).workspaceCreate.workspace);
 };
 const joinWorkspace = async (context, options) => {
-	const data = await requestGraphql(context, `${options.baseUrl}/graphql`, {
+	const data = await requestGraphql(context, options.baseUrl, {
 		query: WORKSPACE_JOIN_MUTATION,
 		token: options.token,
 		variables: { code: options.code }
@@ -1029,20 +1476,16 @@ const joinWorkspace = async (context, options) => {
 		workspace: toWorkspaceRecordFromGraphqlNode(data.workspaceJoin.workspace)
 	};
 };
-const loadTasksByWorkspace = (context, options) => paginateGraphql(context, {
+const loadTasksByWorkspace = (_context, options) => createGraphqlClient({
 	baseUrl: options.baseUrl,
-	nodeKey: "tasks",
-	query: TASKS_QUERY,
-	token: options.token,
-	transform: toTaskRecordFromGraphqlNode,
-	variables: { workspaceId: options.workspaceId }
-});
+	getToken: () => options.token
+}).listTasks(options.workspaceId);
 const loadTasksByWorkspaceIds = (context, options) => paginateGraphql(context, {
 	baseUrl: options.baseUrl,
 	nodeKey: "tasks",
 	query: TASKS_ALL_QUERY,
 	token: options.token,
-	transform: toTaskRecordFromGraphqlNode,
+	transform: toTaskRecord$1,
 	variables: { workspaceIds: options.workspaceIds }
 });
 const loadTaskById = async (context, options) => {
@@ -1124,6 +1567,21 @@ const loadChecklistItemsByTask = async (context, options) => {
 	}
 	return results;
 };
+const mapSyncMutateFailure = (failure) => {
+	if (failure.type === "http") {
+		const { body: responseBody, status } = failure;
+		let body = responseBody;
+		try {
+			body = responseBody.length > 0 ? JSON.parse(responseBody) : null;
+		} catch {}
+		const exitCode = status === 401 || status === 403 ? EXIT_CODES.AUTH_REQUIRED : EXIT_CODES.ERROR;
+		return new CliError(extractErrorMessage(body), exitCode);
+	}
+	if (failure.type === "mutation") return new CliError(failure.response.results.find((item) => !item.success)?.error ?? "Sync mutation failed", EXIT_CODES.ERROR);
+	if (failure.type === "timeout") return new CliError(`Sync mutation timed out after ${failure.timeoutMs}ms`, EXIT_CODES.ERROR);
+	if (failure.cause instanceof Error) return failure.cause;
+	return new CliError("Sync mutation request failed", EXIT_CODES.ERROR);
+};
 const mutateModel = async (context, options) => {
 	if (context.dryRun) {
 		writeWarning(context, "dry run: mutation skipped");
@@ -1138,16 +1596,11 @@ const mutateModel = async (context, options) => {
 		});
 		return;
 	}
-	const response = await requestJson(context, `${options.baseUrl}/sync/mutate`, {
-		body: options.request,
-		method: "POST",
-		token: options.token
-	});
-	if (!response.success) {
-		const error = response.results.find((result) => !result.success);
-		if (error?.error) throw new CliError(error.error, EXIT_CODES.ERROR);
-		throw new CliError("Sync mutation failed", EXIT_CODES.ERROR);
-	}
+	await createSyncMutateClient({
+		baseUrl: options.baseUrl,
+		errorMapper: mapSyncMutateFailure,
+		getToken: () => options.token
+	}).mutate(options.request);
 };
 const listWorkspaceMembers = async (context, options) => await paginateGraphql(context, {
 	baseUrl: options.baseUrl,
@@ -1166,36 +1619,37 @@ const listWorkspaceInvitations = async (context, options) => await paginateGraph
 	variables: { workspaceId: options.workspaceId }
 });
 const createWorkspaceInvitation = async (context, options) => {
-	const endpoint = `${options.baseUrl}/graphql`;
-	const input = { workspaceId: options.workspaceId };
-	if (options.email !== void 0) input.email = options.email;
-	if (options.role !== void 0) input.role = options.role;
-	return toWorkspaceInvitationRecordFromGraphqlNode((await requestGraphql(context, endpoint, {
+	const input = omitUndefined({
+		email: options.email,
+		role: options.role,
+		workspaceId: options.workspaceId
+	});
+	return toWorkspaceInvitationRecordFromGraphqlNode((await requestGraphql(context, options.baseUrl, {
 		query: WORKSPACE_INVITATION_CREATE_MUTATION,
 		token: options.token,
 		variables: { input }
 	})).workspaceInvitationCreate.invitation);
 };
 const listWorkspaceHistory = async (context, options) => {
-	const endpoint = `${options.baseUrl}/graphql`;
-	const variables = {
+	const variables = omitUndefined({
 		limit: options.limit,
+		model: options.model || void 0,
 		workspaceId: options.workspaceId
-	};
-	if (options.model) variables.model = options.model;
-	return (await requestGraphql(context, endpoint, {
+	});
+	return (await requestGraphql(context, options.baseUrl, {
 		query: WORKSPACE_HISTORY_QUERY,
 		token: options.token,
 		variables
 	})).workspaceHistory.map(toWorkspaceHistoryEntryFromGraphqlNode);
 };
 const createApiKey = async (context, options) => {
-	const endpoint = `${options.baseUrl}/graphql`;
-	const variables = { label: options.label };
-	if (options.scopes !== void 0) variables.scopes = options.scopes;
-	if (options.workspaceIds !== void 0) variables.workspaceIds = options.workspaceIds;
-	if (options.expiresAt !== void 0) variables.expiresAt = options.expiresAt;
-	const data = await requestGraphql(context, endpoint, {
+	const variables = omitUndefined({
+		expiresAt: options.expiresAt,
+		label: options.label,
+		scopes: options.scopes,
+		workspaceIds: options.workspaceIds
+	});
+	const data = await requestGraphql(context, options.baseUrl, {
 		query: API_KEY_CREATE_MUTATION,
 		token: options.token,
 		variables
@@ -1206,14 +1660,14 @@ const createApiKey = async (context, options) => {
 	};
 };
 const listApiKeys = async (context, options) => {
-	return (await requestGraphql(context, `${options.baseUrl}/graphql`, {
+	return (await requestGraphql(context, options.baseUrl, {
 		query: API_KEYS_QUERY,
 		token: options.token,
 		variables: {}
 	})).apiKeys.map(toApiKeyRecordFromGraphqlNode);
 };
 const revokeApiKey = async (context, options) => {
-	await requestGraphql(context, `${options.baseUrl}/graphql`, {
+	await requestGraphql(context, options.baseUrl, {
 		query: API_KEY_REVOKE_MUTATION,
 		token: options.token,
 		variables: { id: options.keyId }
@@ -1420,7 +1874,7 @@ const runCreate = async (context, label, options) => {
 	if (key.workspaceIds && key.workspaceIds.length > 0) writeInfo(context, `  Restricted to workspaces: ${key.workspaceIds.join(", ")}`);
 	if (key.expiresAt) writeInfo(context, `  Expires: ${new Date(key.expiresAt).toLocaleDateString()}`);
 	writeInfo(context, "");
-	writeWarning(context, "Save this key now — it will not be shown again.");
+	writeWarning(context, "Save this key now; it will not be shown again.");
 };
 const runList = async (context) => {
 	const { token } = await requireAuthToken(context);
@@ -1765,72 +2219,24 @@ Non-interactive / CI use:
 };
 //#endregion
 //#region src/task-defaults.ts
-const DAY_MS = 1440 * 60 * 1e3;
 const buildTaskStartFields = (view, now = /* @__PURE__ */ new Date()) => {
-	const today = dateOnlyEpochFromLocalDate(now);
-	const tomorrow = today + DAY_MS;
-	switch (view) {
-		case "inbox": return {
-			start: "not_started",
-			startBucket: "today",
-			startDate: null,
-			todayIndexReferenceDate: null
-		};
-		case "anytime": return {
-			start: "started",
-			startBucket: "today",
-			startDate: null,
-			todayIndexReferenceDate: null
-		};
-		case "today": return {
-			start: "started",
-			startBucket: "today",
-			startDate: today,
-			todayIndexReferenceDate: today
-		};
-		case "upcoming": return {
-			start: "started",
-			startBucket: "upcoming",
-			startDate: tomorrow,
-			todayIndexReferenceDate: null
-		};
-		case "someday": return {
-			start: "someday",
-			startBucket: "today",
-			startDate: null,
-			todayIndexReferenceDate: null
-		};
-		default: return {
-			start: "not_started",
-			startBucket: "today",
-			startDate: null,
-			todayIndexReferenceDate: null
-		};
-	}
-};
-const getTaskState = (task) => {
-	if (task.archivedAt !== null) return "archived";
-	if (task.completedAt !== null) return "done";
-	return "open";
+	const today = getTodayDateOnlyEpoch(now);
+	return {
+		...buildTaskStartFields$1(view, { now }),
+		todayIndexReferenceDate: view === "today" ? today : null
+	};
 };
+const getTaskState = (task) => getTaskState$1(task);
 /**
 * Determine which view a task belongs to.
-* Matches the frontend logic in manage-frontend/lib/tasks/task-status.ts
+*
+* Repeat templates are hidden from the CLI's list-level views (they only exist
+* to generate instances); everything else delegates to the canonical
+* task-logic derivation shared across every client.
 */
 const resolveTaskView = (task) => {
-	if (task.repeatRule !== null && task.repeatTemplateId === null) return null;
-	if (task.archivedAt !== null) return "trash";
-	if (task.completedAt !== null) return "logbook";
-	const { start, startDate, deadlineAt } = task;
-	const today = dateOnlyEpochFromLocalDate();
-	const tomorrow = today + DAY_MS;
-	const hasDeadlineToday = deadlineAt !== null && deadlineAt >= today && deadlineAt < tomorrow;
-	if (start === "not_started") return hasDeadlineToday ? "today" : "inbox";
-	if (start === "someday") return hasDeadlineToday ? "today" : "someday";
-	if (start !== "started") return null;
-	if (startDate === null) return hasDeadlineToday ? "today" : "anytime";
-	if (startDate < tomorrow || hasDeadlineToday) return "today";
-	return "upcoming";
+	if (isRepeatTemplate(task)) return null;
+	return getTaskView(task, getTodayDateOnlyEpoch());
 };
 const formatEpochDate = (epochMs) => formatInstantEpoch(epochMs);
 //#endregion
@@ -2002,7 +2408,7 @@ const formatMarkdownOutput = (context, user, workspace, taskCounts, recentTasks,
 		lines.push("", "## Recent Open Tasks");
 		for (const t of recentTasks) {
 			const deadline = t.deadline ? `, due ${t.deadline}` : "";
-			lines.push(`- [${t.id.slice(0, 8)}] ${t.title} — ${t.view}${deadline}`);
+			lines.push(`- [${t.id.slice(0, 8)}] ${t.title} (${t.view})${deadline}`);
 		}
 	}
 	if (activeProjects.length > 0) {
@@ -2371,39 +2777,75 @@ const summarizeThingsImportResult = (result) => {
 //#region src/import/things-labels.ts
 const normalizeThingsLabelLookupKey = (value) => value.trim().toLocaleLowerCase();
 //#endregion
-//#region src/import/model-id.ts
-const IMPORT_ID_NAMESPACE = "b1f9f0ac-9f76-54ed-8eb0-7d6d3a0a0a31";
+//#region ../../packages/sync-ids/node_modules/uuid/dist-node/regex.js
+var regex_default = /^(?:[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$/i;
+//#endregion
+//#region ../../packages/sync-ids/node_modules/uuid/dist-node/validate.js
+function validate(uuid) {
+	return typeof uuid === "string" && regex_default.test(uuid);
+}
+//#endregion
+//#region ../../packages/sync-ids/node_modules/uuid/dist-node/parse.js
+function parse(uuid) {
+	if (!validate(uuid)) throw TypeError("Invalid UUID");
+	let v;
+	return Uint8Array.of((v = parseInt(uuid.slice(0, 8), 16)) >>> 24, v >>> 16 & 255, v >>> 8 & 255, v & 255, (v = parseInt(uuid.slice(9, 13), 16)) >>> 8, v & 255, (v = parseInt(uuid.slice(14, 18), 16)) >>> 8, v & 255, (v = parseInt(uuid.slice(19, 23), 16)) >>> 8, v & 255, (v = parseInt(uuid.slice(24, 36), 16)) / 1099511627776 & 255, v / 4294967296 & 255, v >>> 24 & 255, v >>> 16 & 255, v >>> 8 & 255, v & 255);
+}
+//#endregion
+//#region ../../packages/sync-ids/node_modules/uuid/dist-node/stringify.js
+const byteToHex = [];
+for (let i = 0; i < 256; ++i) byteToHex.push((i + 256).toString(16).slice(1));
+function unsafeStringify(arr, offset = 0) {
+	return (byteToHex[arr[offset + 0]] + byteToHex[arr[offset + 1]] + byteToHex[arr[offset + 2]] + byteToHex[arr[offset + 3]] + "-" + byteToHex[arr[offset + 4]] + byteToHex[arr[offset + 5]] + "-" + byteToHex[arr[offset + 6]] + byteToHex[arr[offset + 7]] + "-" + byteToHex[arr[offset + 8]] + byteToHex[arr[offset + 9]] + "-" + byteToHex[arr[offset + 10]] + byteToHex[arr[offset + 11]] + byteToHex[arr[offset + 12]] + byteToHex[arr[offset + 13]] + byteToHex[arr[offset + 14]] + byteToHex[arr[offset + 15]]).toLowerCase();
+}
+//#endregion
+//#region ../../packages/sync-ids/node_modules/uuid/dist-node/v35.js
+function stringToBytes(str) {
+	str = unescape(encodeURIComponent(str));
+	const bytes = new Uint8Array(str.length);
+	for (let i = 0; i < str.length; ++i) bytes[i] = str.charCodeAt(i);
+	return bytes;
+}
+const DNS = "6ba7b810-9dad-11d1-80b4-00c04fd430c8";
+const URL$1 = "6ba7b811-9dad-11d1-80b4-00c04fd430c8";
+function v35(version, hash, value, namespace, buf, offset) {
+	const valueBytes = typeof value === "string" ? stringToBytes(value) : value;
+	const namespaceBytes = typeof namespace === "string" ? parse(namespace) : namespace;
+	if (typeof namespace === "string") namespace = parse(namespace);
+	if (namespace?.length !== 16) throw TypeError("Namespace must be array-like (16 iterable integer values, 0-255)");
+	let bytes = new Uint8Array(16 + valueBytes.length);
+	bytes.set(namespaceBytes);
+	bytes.set(valueBytes, namespaceBytes.length);
+	bytes = hash(bytes);
+	bytes[6] = bytes[6] & 15 | version;
+	bytes[8] = bytes[8] & 63 | 128;
+	if (buf) {
+		offset ??= 0;
+		if (offset < 0 || offset + 16 > buf.length) throw new RangeError(`UUID byte range ${offset}:${offset + 15} is out of buffer bounds`);
+		for (let i = 0; i < 16; ++i) buf[offset + i] = bytes[i];
+		return buf;
+	}
+	return unsafeStringify(bytes);
+}
+//#endregion
+//#region ../../packages/sync-ids/node_modules/uuid/dist-node/sha1.js
+function sha1(bytes) {
+	if (Array.isArray(bytes)) bytes = Buffer.from(bytes);
+	else if (typeof bytes === "string") bytes = Buffer.from(bytes, "utf8");
+	return createHash("sha1").update(bytes).digest();
+}
+//#endregion
+//#region ../../packages/sync-ids/node_modules/uuid/dist-node/v5.js
+function v5(value, namespace, buf, offset) {
+	return v35(80, sha1, value, namespace, buf, offset);
+}
+v5.DNS = DNS;
+v5.URL = URL$1;
+//#endregion
+//#region ../../packages/sync-ids/src/index.ts
 const SYNC_COMPOSITE_ID_NAMESPACE = "92a73695-d772-4b43-9fb4-d79f5fbef300";
-const IDEMPOTENCY_ID_NAMESPACE = "4c8af5e2-1d36-5a0b-9c47-2f81b3d6e955";
-const uuidToBytes = (uuid) => {
-	const normalized = uuid.replaceAll("-", "");
-	if (normalized.length !== 32) throw new Error(`Invalid UUID namespace: ${uuid}`);
-	return Uint8Array.from(Buffer.from(normalized, "hex"));
-};
-const bytesToUuid = (bytes) => {
-	const hex = Buffer.from(bytes).toString("hex");
-	return [
-		hex.slice(0, 8),
-		hex.slice(8, 12),
-		hex.slice(12, 16),
-		hex.slice(16, 20),
-		hex.slice(20, 32)
-	].join("-");
-};
-const createUuidV5 = (name, namespace) => {
-	const namespaceBytes = uuidToBytes(namespace);
-	const hash = createHash("sha1").update(namespaceBytes).update(Buffer.from(name, "utf-8")).digest();
-	const bytes = Uint8Array.from(hash.subarray(0, 16));
-	const versionByte = bytes.at(6);
-	const variantByte = bytes.at(8);
-	if (typeof versionByte !== "number" || typeof variantByte !== "number") throw new TypeError("Failed to generate a deterministic UUID.");
-	bytes[6] = versionByte & 15 | 80;
-	bytes[8] = variantByte & 63 | 128;
-	return bytesToUuid(bytes);
-};
-const createCompositeSyncId = (model, parts) => createUuidV5(`${model}:${JSON.stringify(parts)}`, SYNC_COMPOSITE_ID_NAMESPACE);
-const createDeterministicImportId = (params) => createUuidV5(`things:${params.workspaceId}:${params.modelName}:${params.sourceId}`, IMPORT_ID_NAMESPACE);
-const createIdempotentMutationId = (params) => createUuidV5(`idem:${params.workspaceId}:${params.modelName}:${params.part}:${params.key}`, IDEMPOTENCY_ID_NAMESPACE);
+const createDeterministicId = (namespace, name) => v5(name, namespace);
+const createCompositeSyncId = (model, parts) => createDeterministicId(SYNC_COMPOSITE_ID_NAMESPACE, `${model}:${JSON.stringify(parts)}`);
 const createTaskLabelId = (params) => createCompositeSyncId("TaskLabel", [
 	params.workspaceId,
 	params.taskId,
@@ -2415,6 +2857,12 @@ const createTeamProjectId = (params) => createCompositeSyncId("TeamProject", [
 	params.projectId
 ]);
 //#endregion
+//#region src/import/model-id.ts
+const IMPORT_ID_NAMESPACE = "b1f9f0ac-9f76-54ed-8eb0-7d6d3a0a0a31";
+const IDEMPOTENCY_ID_NAMESPACE = "4c8af5e2-1d36-5a0b-9c47-2f81b3d6e955";
+const createDeterministicImportId = (params) => createDeterministicId(IMPORT_ID_NAMESPACE, `things:${params.workspaceId}:${params.modelName}:${params.sourceId}`);
+const createIdempotentMutationId = (params) => createDeterministicId(IDEMPOTENCY_ID_NAMESPACE, `idem:${params.workspaceId}:${params.modelName}:${params.part}:${params.key}`);
+//#endregion
 //#region src/import/things-values.ts
 var import_rrule = (/* @__PURE__ */ __commonJSMin(((exports, module) => {
 	(function webpackUniversalModuleDefinition(root, factory) {
@@ -5550,21 +5998,27 @@ const pickCompletedAt = (task) => {
 	return decodeThingsUnixSeconds(task.stopDate) ?? decodeThingsUnixSeconds(task.userModificationDate) ?? decodeThingsUnixSeconds(task.creationDate);
 };
 const sortValue = (primary, fallback) => typeof primary === "number" ? primary : fallback;
-const sanitizeBuffer = (buffer) => {
-	const asText = buffer.toString("utf-8");
+const textDecoder = new TextDecoder();
+const encodeBase64 = (value) => {
+	let binary = "";
+	for (const byte of value) binary += String.fromCodePoint(byte);
+	return btoa(binary);
+};
+const sanitizeBinary = (value) => {
+	const asText = textDecoder.decode(value);
 	if (!asText.includes("�") && READABLE_TEXT_PATTERN.test(asText)) {
 		const trimmed = asText.trim();
 		if (trimmed.length > 0) return trimmed;
 	}
 	return {
-		data: buffer.toString("base64"),
+		data: encodeBase64(value),
 		encoding: "base64"
 	};
 };
 const sanitizeValue = (value) => {
 	if (value === void 0 || value === null) return;
 	if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") return value;
-	if (Buffer.isBuffer(value)) return sanitizeBuffer(value);
+	if (value instanceof Uint8Array) return sanitizeBinary(value);
 	if (Array.isArray(value)) {
 		const items = value.map((entry) => sanitizeValue(entry)).filter((entry) => entry !== void 0);
 		return items.length > 0 ? items : void 0;
@@ -7395,8 +7849,8 @@ const filterTasks = (tasks, options) => {
 	if (query.length === 0) return viewFiltered;
 	return viewFiltered.filter((task) => {
 		const title = task.title.toLowerCase();
-		const notes = task.description?.toLowerCase() ?? "";
-		return title.includes(query) || notes.includes(query);
+		const description = task.description?.toLowerCase() ?? "";
+		return title.includes(query) || description.includes(query);
 	});
 };
 const loadTasksForScope = (context, scope, apiOptions) => {
@@ -7477,7 +7931,7 @@ const runTaskShow = async (context, taskRef, options, workspaceOverride) => {
 	if (task.projectId) writeInfo(context, `projectId: ${task.projectId}`);
 	if (task.teamId) writeInfo(context, `teamId: ${task.teamId}`);
 	if (task.assigneeId) writeInfo(context, `assigneeId: ${task.assigneeId}`);
-	if (task.description) writeInfo(context, `notes: ${task.description}`);
+	if (task.description) writeInfo(context, `description: ${task.description}`);
 };
 const resolveTitle = async (context, rawTitle) => {
 	if (rawTitle) {
@@ -7488,20 +7942,28 @@ const resolveTitle = async (context, rawTitle) => {
 	if (prompted) return prompted;
 	throw new CliError("Task title is required.", EXIT_CODES.VALIDATION, "Provide a title as an argument: donebear task add \"My task\"");
 };
-const resolveNotes = async (_context, flagNotes) => {
-	if (typeof flagNotes === "string") {
-		const trimmed = flagNotes.trim();
-		return trimmed.length > 0 ? trimmed : null;
+const resolveDescription = async (context, flagDescription) => {
+	if (typeof flagDescription !== "string") return null;
+	if (flagDescription === "-") {
+		const piped = await readStdin();
+		if (!piped) {
+			writeWarning(context, "No description received on stdin (--description -); task created without a description.");
+			return null;
+		}
+		return piped;
 	}
-	const stdinContent = await readStdin();
-	if (stdinContent) return stdinContent;
-	return null;
+	const trimmed = flagDescription.trim();
+	if (trimmed.length === 0) {
+		writeWarning(context, "Empty --description value; task created without a description.");
+		return null;
+	}
+	return trimmed;
 };
 const runTaskAdd = async (context, title, options, workspaceOverride) => {
 	const commandContext = await resolveCommandContext(context);
 	const userId = await requireUserId(context, commandContext);
 	const normalizedTitle = await resolveTitle(context, title);
-	const notes = await resolveNotes(context, options.notes);
+	const description = await resolveDescription(context, options.description);
 	const { workspace, autoSelected } = await resolveWorkspace(context, {
 		apiBaseUrl: commandContext.apiBaseUrl,
 		storedWorkspaceId: commandContext.localContext.workspaceId,
@@ -7526,37 +7988,35 @@ const runTaskAdd = async (context, title, options, workspaceOverride) => {
 	const taskId = idempotencyId("model") ?? randomUUID();
 	const now = Date.now();
 	const view = parseTaskView(options.when);
-	const startFields = buildTaskStartFields(view);
 	const deadlineEpoch = parseDeadline(options.deadline);
+	const clientId = options.idempotencyKey ? "cli-idem" : commandContext.localContext.clientId;
 	await mutateModel(context, {
 		baseUrl: commandContext.apiBaseUrl,
-		request: {
+		request: buildMutateEnvelope({
 			batchId: idempotencyId("batch") ?? randomUUID(),
+			clientId,
+			clientTxIds: [idempotencyId("tx") ?? randomUUID()],
 			transactions: [{
 				action: "INSERT",
-				clientId: options.idempotencyKey ? "cli-idem" : commandContext.localContext.clientId,
-				clientTxId: idempotencyId("tx") ?? randomUUID(),
 				modelId: taskId,
 				modelName: "Task",
-				payload: {
-					archivedAt: null,
-					completedAt: null,
-					createdAt: now,
-					creatorId: userId,
+				payload: buildTaskInsertFields({
 					deadlineAt: deadlineEpoch,
-					description: notes,
-					key: taskId.replaceAll("-", "").slice(0, 8),
+					description,
+					ids: {
+						creatorId: userId,
+						taskId,
+						workspaceId: workspace.id
+					},
+					now,
 					projectId,
-					sortOrder: 0,
 					teamId,
 					title: normalizedTitle,
-					todaySortOrder: 0,
-					updatedAt: now,
-					workspaceId: workspace.id,
-					...startFields
-				}
+					todayEpoch: getTodayDateOnlyEpoch(new Date(now)),
+					view
+				})
 			}]
-		},
+		}),
 		token: commandContext.token
 	});
 	if (context.json) {
@@ -7564,6 +8024,7 @@ const runTaskAdd = async (context, title, options, workspaceOverride) => {
 			autoSelected,
 			created: true,
 			deadlineAt: deadlineEpoch,
+			description,
 			id: taskId,
 			projectId,
 			teamId,
@@ -7577,6 +8038,7 @@ const runTaskAdd = async (context, title, options, workspaceOverride) => {
 	if (autoSelected) writeInfo(context, `Auto-selected workspace: ${workspace.name}`);
 	writeSuccess(context, `Added task: ${normalizedTitle}`);
 	writeInfo(context, `id: ${taskId}`);
+	if (description) writeInfo(context, `description: ${description}`);
 };
 const runTaskMutation = async (context, taskRef, payload) => {
 	const commandContext = await resolveCommandContext(context);
@@ -7644,7 +8106,7 @@ const resolveTeamId = async (context, commandContext, teamRef, workspaceRef) =>
 	}), teamRef, "Team");
 };
 const validateTaskEditOptions = (options) => {
-	if (options.clearNotes && typeof options.notes === "string") throw new Error("Use either --notes or --clear-notes, not both.");
+	if (options.clearDescription && typeof options.description === "string") throw new Error("Use either --description or --clear-description, not both.");
 	if (options.clearDeadline && typeof options.deadline === "string") throw new Error("Use either --deadline or --clear-deadline, not both.");
 	if (options.clearProject && typeof options.project === "string") throw new Error("Use either --project or --clear-project, not both.");
 	if (options.clearTeam && typeof options.team === "string") throw new Error("Use either --team or --clear-team, not both.");
@@ -7655,10 +8117,10 @@ const applyScalarEdits = (updates, options) => {
 		if (title.length === 0) throw new Error("Task title cannot be empty.");
 		updates.title = title;
 	}
-	if (options.clearNotes) updates.description = null;
-	else if (typeof options.notes === "string") {
-		const notes = options.notes.trim();
-		updates.description = notes.length > 0 ? notes : null;
+	if (options.clearDescription) updates.description = null;
+	else if (typeof options.description === "string") {
+		const description = options.description.trim();
+		updates.description = description.length > 0 ? description : null;
 	}
 	if (typeof options.when === "string") Object.assign(updates, buildTaskStartFields(parseTaskView(options.when)));
 	if (options.clearDeadline) updates.deadlineAt = null;
@@ -7674,7 +8136,7 @@ const runTaskEdit = async (context, taskRef, options, workspaceOverride) => {
 	else if (typeof options.project === "string") updates.projectId = await resolveProjectId(context, commandContext, options.project, wsRef);
 	if (options.clearTeam) updates.teamId = null;
 	else if (typeof options.team === "string") updates.teamId = await resolveTeamId(context, commandContext, options.team, wsRef);
-	if (Object.keys(updates).length === 0) throw new Error("No updates provided. Use --title, --notes, --clear-notes, --when, --deadline, --clear-deadline, --project, --clear-project, --team, or --clear-team.");
+	if (Object.keys(updates).length === 0) throw new Error("No updates provided. Use --title, --description, --clear-description, --when, --deadline, --clear-deadline, --project, --clear-project, --team, or --clear-team.");
 	updates.updatedAt = Date.now();
 	await runTaskMutation(context, taskRef, {
 		action: "UPDATE",
@@ -7781,7 +8243,7 @@ const runTaskRandom = async (context, options, workspaceOverride) => {
 	writeInfo(context, `start: ${task.start}`);
 	writeInfo(context, `startBucket: ${task.startBucket}`);
 	writeInfo(context, `deadline: ${formatDateOnlyEpoch(task.deadlineAt) ?? "(none)"}`);
-	if (task.description) writeInfo(context, `notes: ${task.description}`);
+	if (task.description) writeInfo(context, `description: ${task.description}`);
 };
 const resolveChecklistItemReference = async (context, commandContext, taskId, itemRef) => {
 	const trimmed = itemRef.trim();
@@ -7852,7 +8314,7 @@ Agent tip: run "donebear spec task add" for full option reference
 			}, workspaceOverride);
 		});
 	});
-	task.command("list").alias("ls").description("List tasks").option("-w, --workspace <workspace>", "Workspace id, slug, or exact name").option("-s, --state <state>", "open|done|archived|all", "open").option("-n, --limit <count>", "Maximum number of tasks", (value) => parsePositiveInteger(value, "Limit"), DEFAULT_TASK_LIST_LIMIT).option("-q, --search <query>", "Filter by title or notes").option("-v, --view <view>", "Filter by view (inbox|anytime|today|upcoming|someday|logbook|trash)").addHelpText("after", `
+	task.command("list").alias("ls").description("List tasks").option("-w, --workspace <workspace>", "Workspace id, slug, or exact name").option("-s, --state <state>", "open|done|archived|all", "open").option("-n, --limit <count>", "Maximum number of tasks", (value) => parsePositiveInteger(value, "Limit"), DEFAULT_TASK_LIST_LIMIT).option("-q, --search <query>", "Filter by title or description").option("-v, --view <view>", "Filter by view (inbox|anytime|today|upcoming|someday|logbook|trash)").addHelpText("after", `
 Examples:
   donebear task list --json
   donebear task list --state done --json
@@ -7873,7 +8335,7 @@ Views:  inbox | anytime | today | upcoming | someday | logbook | trash
 			await runTaskShow(context, taskId, options, workspaceOverride);
 		});
 	});
-	task.command("read").description("Print the description (notes) of a task").argument("<id>", "Task id or unique prefix").option("-w, --workspace <workspace>", "Workspace id, slug, or exact name").action(async (taskId, options, command) => {
+	task.command("read").description("Print the description of a task").argument("<id>", "Task id or unique prefix").option("-w, --workspace <workspace>", "Workspace id, slug, or exact name").action(async (taskId, options, command) => {
 		const context = contextFromCommand(command);
 		await runWithErrorHandling(context, async () => {
 			await runTaskRead(context, taskId, options, workspaceOverride);
@@ -7897,12 +8359,12 @@ Views:  inbox | anytime | today | upcoming | someday | logbook | trash
 			await runTaskRandom(context, options, workspaceOverride);
 		});
 	});
-	task.command("add").alias("create").description("Create a task").argument("[title]", "Task title (prompted interactively if omitted)").option("-w, --workspace <workspace>", "Workspace id, slug, or exact name").option("-n, --notes <text>", "Task notes (or pipe via stdin)").option("--when <view>", "inbox|anytime|today|upcoming|someday", "inbox").option("--deadline <date>", "Deadline (YYYY-MM-DD or ISO datetime)").option("--project <key-or-id>", "Project key or id").option("--team <key-or-id>", "Team key or id").option("--idempotency-key <key>", "Stable key making retries safe (repeated calls create only one task)").addHelpText("after", `
+	task.command("add").alias("create").description("Create a task").argument("[title]", "Task title (prompted interactively if omitted)").option("-w, --workspace <workspace>", "Workspace id, slug, or exact name").option("-d, --description <text>", "Task description (use --description - to read from piped stdin)").option("--when <view>", "inbox|anytime|today|upcoming|someday", "inbox").option("--deadline <date>", "Deadline (YYYY-MM-DD or ISO datetime)").option("--project <key-or-id>", "Project key or id").option("--team <key-or-id>", "Team key or id").option("--idempotency-key <key>", "Stable key making retries safe (repeated calls create only one task)").addHelpText("after", `
 Examples:
   donebear task add "Fix login bug" --when today --json
   donebear task add "Write tests" --deadline 2030-03-15 --project PROJ --json
-  donebear task add "Review PR" --when anytime --notes "Check for XSS" --json
-  echo "Multi-line notes" | donebear task add "My task"
+  donebear task add "Review PR" --when anytime --description "Check for XSS" --json
+  echo "Multi-line description" | donebear task add "My task" --description -
   donebear task add                       # prompts for title interactively
 
 Date format: YYYY-MM-DD (e.g. 2030-03-15)
@@ -7913,7 +8375,7 @@ View (--when): inbox | anytime | today | upcoming | someday
 			await runTaskAdd(context, title, options, workspaceOverride);
 		});
 	});
-	task.command("edit").description("Update task fields").argument("<id>", "Task id or unique prefix").option("-w, --workspace <workspace>", "Workspace id, slug, or exact name").option("--title <title>", "Replace task title").option("--notes <text>", "Replace task notes (empty string clears)").option("--clear-notes", "Clear task notes").option("--when <view>", "Set view bucket (inbox|anytime|today|upcoming|someday)").option("--deadline <date>", "Set deadline (YYYY-MM-DD or ISO datetime)").option("--clear-deadline", "Clear deadline").option("--project <key-or-id>", "Set project (key or id)").option("--clear-project", "Remove project assignment").option("--team <key-or-id>", "Set team (key or id)").option("--clear-team", "Remove team assignment").action(async (taskId, options, command) => {
+	task.command("edit").description("Update task fields").argument("<id>", "Task id or unique prefix").option("-w, --workspace <workspace>", "Workspace id, slug, or exact name").option("--title <title>", "Replace task title").option("--description <text>", "Replace task description (empty string clears)").option("--clear-description", "Clear task description").option("--when <view>", "Set view bucket (inbox|anytime|today|upcoming|someday)").option("--deadline <date>", "Set deadline (YYYY-MM-DD or ISO datetime)").option("--clear-deadline", "Clear deadline").option("--project <key-or-id>", "Set project (key or id)").option("--clear-project", "Remove project assignment").option("--team <key-or-id>", "Set team (key or id)").option("--clear-team", "Remove team assignment").action(async (taskId, options, command) => {
 		const context = contextFromCommand(command);
 		await runWithErrorHandling(context, async () => {
 			await runTaskEdit(context, taskId, options, workspaceOverride);
@@ -7988,6 +8450,13 @@ View (--when): inbox | anytime | today | upcoming | someday
 			});
 			const itemId = randomUUID();
 			const now = Date.now();
+			const checklistItems = await loadChecklistItemsByTask(context, {
+				baseUrl: commandContext.apiBaseUrl,
+				taskId: resolvedTask.id,
+				token: commandContext.token
+			});
+			const maxSortOrder = Math.max(...checklistItems.map((item) => item.sortOrder));
+			const sortOrder = checklistItems.length === 0 ? DEFAULT_RANK_GAP : maxSortOrder + DEFAULT_RANK_GAP;
 			await mutateModel(context, {
 				baseUrl: commandContext.apiBaseUrl,
 				request: {
@@ -8001,7 +8470,7 @@ View (--when): inbox | anytime | today | upcoming | someday
 						payload: {
 							completedAt: null,
 							createdAt: now,
-							sortOrder: now,
+							sortOrder,
 							taskId: resolvedTask.id,
 							title: title.trim(),
 							updatedAt: now,
@@ -8225,12 +8694,12 @@ const runSearch = async (context, query, options, workspaceOverride) => {
 		writeInfo(context, `No tasks found matching "${trimmedQuery}".`);
 		return;
 	}
-	writeInfo(context, `${scopeLabel(scope)} — "${trimmedQuery}" (${limited.length}/${filtered.length})`);
+	writeInfo(context, `${scopeLabel(scope)}: "${trimmedQuery}" (${limited.length}/${filtered.length})`);
 	for (const line of taskListLines(limited)) writeInfo(context, line);
 	if (context.copy) copyToClipboard(taskListLines(limited).join("\n"));
 };
 const registerSearchCommand = (program, workspaceOverride) => {
-	program.command("search").description("Search tasks by title or notes").argument("[query]", "Search query (prompted interactively if omitted)").option("-w, --workspace <workspace>", "Workspace id, slug, or exact name").option("-s, --state <state>", "open|done|archived|all", "all").option("-n, --limit <count>", "Maximum number of results", (value) => parsePositiveInteger(value, "Limit"), DEFAULT_SEARCH_LIMIT).addHelpText("after", `
+	program.command("search").description("Search tasks by title or description").argument("[query]", "Search query (prompted interactively if omitted)").option("-w, --workspace <workspace>", "Workspace id, slug, or exact name").option("-s, --state <state>", "open|done|archived|all", "all").option("-n, --limit <count>", "Maximum number of results", (value) => parsePositiveInteger(value, "Limit"), DEFAULT_SEARCH_LIMIT).addHelpText("after", `
 Examples:
   donebear search "meeting"
   donebear search "launch" --state open
@@ -8777,13 +9246,14 @@ const COMMAND_SPECS = {
 		examples: [
 			"donebear task add \"Fix login bug\" --when today --json",
 			"donebear task add \"Write tests\" --deadline 2026-03-15 --project PROJ --json",
-			"donebear task add \"Review PR\" --when anytime --notes \"Triage for bugs\" --json",
-			"echo \"Multi-line notes\" | donebear task add \"My task\"",
+			"donebear task add \"Review PR\" --when anytime --description \"Triage for bugs\" --json",
+			"echo \"Multi-line description\" | donebear task add \"My task\" --description -",
 			"donebear task add  # prompts for title interactively in TTY"
 		],
 		json_output: {
 			created: "boolean",
 			deadlineAt: "number | null",
+			description: "string | null",
 			id: "string (UUID)",
 			projectId: "string | null",
 			teamId: "string | null",
@@ -8792,19 +9262,19 @@ const COMMAND_SPECS = {
 			workspaceId: "string",
 			workspaceName: "string"
 		},
-		notes: "Title is prompted interactively when omitted in TTY. Notes can be piped via stdin. Task id accepts full UUID or prefix of >= 4 chars in all other task subcommands.",
+		notes: "Title is prompted interactively when omitted in TTY. The description is NOT read from stdin unless you pass --description - explicitly; without --description the task is created with no description (and the saved description is echoed back in the output). Task id accepts full UUID or prefix of >= 4 chars in all other task subcommands.",
 		options: {
 			"--deadline": {
 				description: "Due date",
 				format: "YYYY-MM-DD",
 				type: "string"
 			},
-			"--idempotency-key": {
-				description: "Stable key making retries safe (repeated calls create only one task)",
+			"--description": {
+				description: "Body / description text. Pass --description - to read from piped stdin.",
 				type: "string"
 			},
-			"--notes": {
-				description: "Body / description text (or pipe via stdin)",
+			"--idempotency-key": {
+				description: "Stable key making retries safe (repeated calls create only one task)",
 				type: "string"
 			},
 			"--project": {
@@ -8847,7 +9317,7 @@ const COMMAND_SPECS = {
 			}
 		},
 		command: "task append",
-		description: "Append text to task notes",
+		description: "Append text to a task's description",
 		examples: ["donebear task append abc1 \"Additional context\" --json"],
 		json_output: {
 			id: "string",
@@ -8908,8 +9378,8 @@ const COMMAND_SPECS = {
 				description: "Clear the due date",
 				type: "boolean"
 			},
-			"--clear-notes": {
-				description: "Clear notes/description",
+			"--clear-description": {
+				description: "Clear the description",
 				type: "boolean"
 			},
 			"--clear-project": {
@@ -8925,8 +9395,8 @@ const COMMAND_SPECS = {
 				format: "YYYY-MM-DD",
 				type: "string"
 			},
-			"--notes": {
-				description: "Replace notes/description",
+			"--description": {
+				description: "Replace the task description",
 				type: "string"
 			},
 			"--project": {
@@ -9024,7 +9494,7 @@ const COMMAND_SPECS = {
 			}
 		},
 		command: "task prepend",
-		description: "Prepend text to task notes",
+		description: "Prepend text to a task's description",
 		examples: ["donebear task prepend abc1 \"URGENT: \" --json"],
 		json_output: {
 			id: "string",
@@ -9040,7 +9510,7 @@ const COMMAND_SPECS = {
 			type: "string"
 		} },
 		command: "task read",
-		description: "Print task description/notes as plain text",
+		description: "Print task description as plain text",
 		examples: ["donebear task read abc1"],
 		options: { "--workspace": { type: "string" } },
 		usage: "donebear task read <id> [options]"
@@ -9166,7 +9636,7 @@ const TOP_LEVEL_SPECS = {
 			list: "List all API keys with scopes and expiration",
 			revoke: "Revoke an API key by id"
 		},
-		tip: "donebear spec api-key create  —  get full spec for api-key create"
+		tip: "donebear spec api-key create: get full spec for api-key create"
 	},
 	auth: {
 		command: "auth",
@@ -9177,13 +9647,13 @@ const TOP_LEVEL_SPECS = {
 			logout: "Sign out and remove stored session",
 			status: "Show auth status"
 		},
-		tip: "donebear spec auth login  —  get full spec for auth login"
+		tip: "donebear spec auth login: get full spec for auth login"
 	},
 	import: {
 		command: "import",
 		description: "Import external data into Done Bear",
 		subcommands: { things: "Import a Things 3 SQLite export into the selected workspace" },
-		tip: "donebear spec import things  —  get full spec for the Things importer"
+		tip: "donebear spec import things: get full spec for the Things importer"
 	},
 	label: {
 		command: "label",
@@ -9208,7 +9678,7 @@ const TOP_LEVEL_SPECS = {
 			show: "Get project details by id, key, or name",
 			unarchive: "Restore an archived project"
 		},
-		tip: "donebear spec project add  —  get full spec for project add"
+		tip: "donebear spec project add: get full spec for project add"
 	},
 	task: {
 		command: "task",
@@ -9216,20 +9686,20 @@ const TOP_LEVEL_SPECS = {
 		notes: "Task id accepts full UUID or a prefix of >= 4 chars.",
 		subcommands: {
 			add: "Create a new task",
-			append: "Append text to task notes",
+			append: "Append text to a task's description",
 			archive: "Archive a task",
 			checklist: "Manage task checklist items",
 			done: "Mark a task as complete",
 			edit: "Update task fields",
 			list: "List tasks (--state, --view, --search, --limit)",
-			prepend: "Prepend text to task notes",
+			prepend: "Prepend text to a task's description",
 			random: "Pick a random task (--state to filter)",
-			read: "Print task notes as plain text",
+			read: "Print task description as plain text",
 			reopen: "Reopen a completed task",
 			show: "Get task details by id",
 			unarchive: "Restore an archived task"
 		},
-		tip: "donebear spec task add  —  get full spec for task add"
+		tip: "donebear spec task add: get full spec for task add"
 	},
 	team: {
 		command: "team",
@@ -9253,7 +9723,7 @@ const TOP_LEVEL_SPECS = {
 			members: "List workspace members",
 			use: "Set the default workspace"
 		},
-		tip: "donebear spec workspace use  —  get full spec for workspace use"
+		tip: "donebear spec workspace use: get full spec for workspace use"
 	}
 };
 const runSpec = (_context, args) => {
@@ -9287,7 +9757,7 @@ const runSpec = (_context, args) => {
 	});
 };
 const registerSpecCommand = (program) => {
-	program.command("spec").description("Progressive CLI spec for agent discovery — no auth required").argument("[command]", "Command name (e.g. task, project)").argument("[subcommand]", "Subcommand name (e.g. add, list)").addHelpText("after", `
+	program.command("spec").description("Progressive CLI spec for agent discovery (no auth required)").argument("[command]", "Command name (e.g. task, project)").argument("[subcommand]", "Subcommand name (e.g. add, list)").addHelpText("after", `
 Examples:
   donebear spec                  Full CLI overview (~500 tokens)
   donebear spec task             All task subcommands
@@ -9444,7 +9914,7 @@ const runToday = async (context, options, workspaceOverride) => {
 		writeInfo(context, "No tasks for today.");
 		return;
 	}
-	writeInfo(context, `${scopeLabel(scope)} — Today (${limited.length}/${todayTasks.length})`);
+	writeInfo(context, `${scopeLabel(scope)}: Today (${limited.length}/${todayTasks.length})`);
 	for (const line of taskListLines(limited)) writeInfo(context, line);
 	if (context.copy) copyToClipboard(taskListLines(limited).join("\n"));
 };
@@ -9869,7 +10339,7 @@ With auth:
 
 Auth:
   donebear auth login            OAuth browser login
-  DONEBEAR_TOKEN=<token>         Non-interactive / CI — set this env var
+  DONEBEAR_TOKEN=<token>         Non-interactive / CI: set this env var
 
 Workspace targeting:
   donebear workspace=myorg task list