emdash 0.38.0 → 0.39.0

package/src/astro/routes/api/plugins/[pluginId]/[...path].ts

@@ -9,105 +9,37 @@
  * Private routes (the default) require authentication and appropriate permissions.
  */
 
-import { Permissions, type Permission } from "@emdash-cms/auth";
 import type { APIRoute } from "astro";
 
-import { requirePerm } from "#api/authorize.js";
-import { apiError, apiSuccess } from "#api/error.js";
-import { requireScope } from "#auth/scopes.js";
+import { apiError } from "#api/error.js";
+import { dispatchPluginApiRequest } from "#plugins/http-route-dispatch.js";
 
 export const prerender = false;
 
 /**
  * Handle all methods by matching against plugin-defined routes
  */
-const handleRequest: APIRoute = async ({ params, request, locals }) => {
+const handleRequest: APIRoute = async ({ params, request, locals, cache }) => {
 	const { emdash, user } = locals;
 	const pluginId = params.pluginId!;
 	const path = params.path || "";
-	const method = request.method.toUpperCase();
-
 	if (!emdash?.handlePluginApiRoute) {
 		return apiError("NOT_CONFIGURED", "EmDash not configured", 500);
 	}
-
-	// Resolve route metadata to decide auth before dispatch
-	const routeMeta = emdash.getPluginRouteMeta(pluginId, `/${path}`);
-
-	if (!routeMeta) {
-		return apiError("NOT_FOUND", "Plugin route not found", 404);
-	}
-
-	// Public routes skip auth, CSRF, and scope checks entirely
-	if (!routeMeta.public) {
-		// Plugin routes are dispatched by name only — the HTTP method never
-		// selects a different handler, so a route reached via GET or HEAD runs
-		// exactly the same code (and side effects) as one reached via POST.
-		// Method-based tiering is therefore unsafe: gating GET/HEAD/OPTIONS on
-		// `plugins:read` with no CSRF let an editor (or a cross-origin page,
-		// since HEAD is CORS-safe) invoke a mutating admin route by choosing the
-		// method (#1853). Astro also dispatches HEAD to the GET export, so no
-		// explicit HEAD handler is needed to reach a "GET" route. Gate every
-		// private invocation on the route's declared permission (defaulting to
-		// `plugins:manage`) + CSRF regardless of method.
-		const permission = routeMeta.permission ?? "plugins:manage";
-		if (!(permission in Permissions)) {
-			return apiError("INVALID_PLUGIN_ROUTE", "Plugin route declares an invalid permission", 500);
-		}
-		const denied = requirePerm(user, permission as Permission);
-		if (denied) return denied;
-
-		// Token scope enforcement — plugin routes require "admin" scope.
-		// Session auth is implicitly full-access (requireScope returns null).
-		const scopeError = requireScope(locals, "admin");
-		if (scopeError) return scopeError;
-
-		// CSRF protection on private routes. Plugin routes use soft auth in the
-		// middleware (user resolved but not required), so the middleware's CSRF
-		// check doesn't run — enforce it here. Applied to every method because
-		// any method can trigger a state change (see above). Token-authed
-		// requests (which set tokenScopes) are exempt — tokens aren't ambient
-		// credentials like cookies.
-		if (!locals.tokenScopes && request.headers.get("X-EmDash-Request") !== "1") {
-			return apiError("CSRF_REJECTED", "Missing required header", 403);
-		}
-	}
-
-	// Forward the caller only for private routes: it was validated by the
-	// requirePerm/requireScope checks above, so plugins can trust ctx.user.
-	// Public routes skip auth, so no caller is bound even when an ambient
-	// session happens to exist.
-	const caller = routeMeta.public ? undefined : user;
-
-	const result = await emdash.handlePluginApiRoute(pluginId, method, `/${path}`, request, caller);
-
-	if (!result.success) {
-		const code = result.error?.code ?? "PLUGIN_ERROR";
-		// Pass through messages from known plugin errors (PluginRouteError),
-		// but mask internal errors (unhandled exceptions) to avoid leaking
-		// database errors, file paths, etc. from sandboxed plugins.
-		const message =
-			code === "INTERNAL_ERROR"
-				? "Plugin route error"
-				: (result.error?.message ?? "Plugin route error");
-		// PluginRouteError status is returned at the top level of the result
-		const status = (result as { status?: number }).status ?? (code === "NOT_FOUND" ? 404 : 400);
-		return apiError(code, message, status);
-	}
-
-	const response = apiSuccess(result.data);
-	// Public routes may opt in to CDN/browser caching for GET responses.
-	// getRouteMeta only ever exposes cacheControl on public routes, and errors
-	// above keep the default private, no-store. Astro serves HEAD via this GET
-	// export, which is fine: same headers, no body.
-	if (routeMeta.cacheControl && (method === "GET" || method === "HEAD")) {
-		response.headers.set("Cache-Control", routeMeta.cacheControl);
-	}
-	return response;
+	return dispatchPluginApiRequest({
+		runtime: emdash,
+		pluginId,
+		path: `/${path}`,
+		request,
+		user,
+		tokenScopes: locals.tokenScopes,
+		invalidateContentCache: cache?.enabled ? (tags) => cache.invalidate({ tags }) : undefined,
+	});
 };
 
 // Export handlers for all HTTP methods
 export const GET = handleRequest;
+export const HEAD = handleRequest;
 export const POST = handleRequest;
 export const PUT = handleRequest;
 export const PATCH = handleRequest;

package/src/astro/routes/api/redirects/[id].ts

@@ -17,7 +17,6 @@ import {
 } from "#api/handlers/redirects.js";
 import { isParseError, parseBody } from "#api/parse.js";
 import { updateRedirectBody } from "#api/schemas.js";
-import { invalidateRedirectCache } from "#redirects/cache.js";
 
 export const prerender = false;
 
@@ -62,7 +61,6 @@ export const PUT: APIRoute = async ({ params, request, locals }) => {
 		if (isParseError(body)) return body;
 
 		const result = await handleRedirectUpdate(db, id, body);
-		invalidateRedirectCache();
 		return unwrapResult(result);
 	} catch (error) {
 		return handleError(error, "Failed to update redirect", "REDIRECT_UPDATE_ERROR");
@@ -85,7 +83,6 @@ export const DELETE: APIRoute = async ({ params, locals }) => {
 
 	try {
 		const result = await handleRedirectDelete(db, id);
-		invalidateRedirectCache();
 		return unwrapResult(result);
 	} catch (error) {
 		return handleError(error, "Failed to delete redirect", "REDIRECT_DELETE_ERROR");

package/src/astro/routes/api/redirects/index.ts

@@ -12,7 +12,6 @@ import { handleError, requireDb, unwrapResult } from "#api/error.js";
 import { handleRedirectCreate, handleRedirectList } from "#api/handlers/redirects.js";
 import { isParseError, parseBody, parseQuery } from "#api/parse.js";
 import { createRedirectBody, redirectsListQuery } from "#api/schemas.js";
-import { invalidateRedirectCache } from "#redirects/cache.js";
 
 export const prerender = false;
 
@@ -50,7 +49,6 @@ export const POST: APIRoute = async ({ request, locals }) => {
 		if (isParseError(body)) return body;
 
 		const result = await handleRedirectCreate(db, body);
-		invalidateRedirectCache();
 		return unwrapResult(result, 201);
 	} catch (error) {
 		return handleError(error, "Failed to create redirect", "REDIRECT_CREATE_ERROR");

package/src/astro/routes/api/search/index.ts

@@ -56,6 +56,7 @@ export const GET: APIRoute = async ({ url, locals }) => {
 			locale: query.locale,
 			limit: query.limit,
 			cursor: query.cursor,
+			scope: query.scope,
 		});
 
 		return apiSuccess(result);

package/src/astro/routes/api/visual-editing/action-token.ts

@@ -0,0 +1,36 @@
+import type { APIRoute } from "astro";
+
+import { apiError, apiSuccess } from "#api/error.js";
+import { resolveSecretsCached } from "#config/secrets.js";
+
+import {
+	generateVisualEditingActionToken,
+	VISUAL_ACTION_TOKEN_INVALID,
+	verifyVisualEditingActionToken,
+} from "../../../../visual-editing/action-token.js";
+
+export const prerender = false;
+
+export const POST: APIRoute = async ({ locals, request }) => {
+	const { emdash, user } = locals;
+	if (!emdash?.db) return apiError("NOT_CONFIGURED", "EmDash is not initialized", 500);
+	if (!user) return apiError("UNAUTHORIZED", "Authentication required", 401);
+
+	const token = request.headers.get("x-emdash-visual-action");
+	if (!token) {
+		return apiError(VISUAL_ACTION_TOKEN_INVALID, "Visual editing action token is required", 403);
+	}
+
+	const { previewSecret } = await resolveSecretsCached(emdash.db);
+	if (!(await verifyVisualEditingActionToken(token, previewSecret, user.id))) {
+		return apiError(
+			VISUAL_ACTION_TOKEN_INVALID,
+			"Visual editing action token is invalid or expired",
+			403,
+		);
+	}
+
+	return apiSuccess({
+		token: await generateVisualEditingActionToken(previewSecret, user.id),
+	});
+};

package/src/astro/routes/api/visual-editing/content/[collection]/[id]/publish.ts

@@ -0,0 +1,32 @@
+import type { APIRoute } from "astro";
+
+import { apiError } from "#api/error.js";
+import { resolveSecretsCached } from "#config/secrets.js";
+
+import {
+	VISUAL_ACTION_TOKEN_INVALID,
+	verifyVisualEditingActionToken,
+} from "../../../../../../../visual-editing/action-token.js";
+import { publishContent } from "../../../../content/[collection]/[id]/publish.js";
+
+export const prerender = false;
+
+export const POST: APIRoute = async (context) => {
+	const { emdash, user } = context.locals;
+	if (!emdash?.db) return apiError("NOT_CONFIGURED", "EmDash is not initialized", 500);
+	if (!user) return apiError("UNAUTHORIZED", "Authentication required", 401);
+	const token = context.request.headers.get("x-emdash-visual-action");
+	if (!token) {
+		return apiError(VISUAL_ACTION_TOKEN_INVALID, "Visual editing action token is required", 403);
+	}
+
+	const { previewSecret } = await resolveSecretsCached(emdash.db);
+	if (!(await verifyVisualEditingActionToken(token, previewSecret, user.id))) {
+		return apiError(
+			VISUAL_ACTION_TOKEN_INVALID,
+			"Visual editing action token is invalid or expired",
+			403,
+		);
+	}
+	return publishContent(context, "visual-editor");
+};

package/src/astro/routes/api/visual-editing/toolbar-labels.ts

@@ -0,0 +1,16 @@
+export const prerender = false;
+
+import { loadVisualEditingToolbarLabels } from "@emdash-cms/admin/locales/server";
+import type { APIRoute } from "astro";
+
+import { apiSuccess } from "#api/error.js";
+
+export const GET: APIRoute = async ({ request }) => {
+	const labels = await loadVisualEditingToolbarLabels(request);
+	const response = apiSuccess({
+		editMode: labels.editMode,
+		hideToolbar: labels.hideToolbar,
+	});
+	response.headers.set("Cache-Control", "private, no-store");
+	return response;
+};

package/src/astro/routes/sitemap-[collection].xml.ts

@@ -16,13 +16,15 @@
  */
 
 import type { APIRoute } from "astro";
+// @ts-ignore - virtual module
+import virtualConfig from "virtual:emdash/config";
 
 import { handleSitemapData } from "#api/handlers/seo.js";
 import { getPublicOrigin } from "#api/public-url.js";
 import { getSiteSettingsWithDb } from "#settings/index.js";
 
 import { getI18nConfig, isI18nEnabled } from "../../i18n/config.js";
-import { interpolateUrlPattern, localizePath } from "../../i18n/resolve.js";
+import { resolveLocalizedContentRoutePath } from "../../i18n/resolve.js";
 import { buildSeoImageUrl } from "../../seo/media-url.js";
 
 export const prerender = false;
@@ -97,7 +99,7 @@ export const GET: APIRoute = async ({ params, locals, url }) => {
 		const urlByEntry = new Map<string, string | null>();
 		const resolveEntryUrl = async (entry: Entry): Promise<string | null> => {
 			if (urlByEntry.has(entry.id)) return urlByEntry.get(entry.id) ?? null;
-			const path = interpolateUrlPattern({
+			const absolutePath = await resolveLocalizedContentRoutePath({
 				pattern: col.urlPattern,
 				collection: col.collection,
 				slug: entry.slug || entry.id,
@@ -106,9 +108,10 @@ export const GET: APIRoute = async ({ params, locals, url }) => {
 				// no updatedAt fallback — tokens stay literal without a publish
 				// date, consistent with the resolver's documented behavior.
 				date: entry.publishedAt,
+				locale: entry.locale,
+				trailingSlash: virtualConfig?.trailingSlash,
 			});
-			const localized = await localizePath(path, entry.locale);
-			const absolute = localized === null ? null : `${siteUrl}${localized}`;
+			const absolute = absolutePath === null ? null : `${siteUrl}${absolutePath}`;
 			urlByEntry.set(entry.id, absolute);
 			return absolute;
 		};

package/src/astro/types.ts

@@ -9,8 +9,18 @@ import type { Element } from "@emdash-cms/blocks";
 import type { Kysely } from "kysely";
 
 import type { ContentFieldFilters } from "../content-list-query.js";
-import type { RouteCallerInput, RouteMeta } from "../plugins/routes.js";
+import type {
+	PluginEditorExtensionDispatch,
+	ResolvedPluginEditorExtension,
+} from "../emdash-runtime.js";
+import type {
+	PluginContentCacheInvalidator,
+	RouteCallerInput,
+	RouteMeta,
+} from "../plugins/routes.js";
+import type { ActorInfo, ContentActionOrigin } from "../plugins/types.js";
 import type { ManifestRegistryConfigurationError } from "../registry/config.js";
+import type { CollectionWithFields } from "../schema/types.js";
 
 // Re-export core types
 export type {
@@ -56,6 +66,7 @@ export interface ManifestCollection {
 			kind: string;
 			label?: string;
 			required?: boolean;
+			translatable?: boolean;
 			widget?: string;
 			/**
 			 * Field options. Two shapes:
@@ -98,6 +109,8 @@ export interface ManifestPlugin {
 		title?: string;
 		size?: string;
 	}>;
+	editorPanels?: import("../plugins/types.js").PluginEditorPanel[];
+	editorActions?: import("../plugins/types.js").PluginEditorAction[];
 	fieldWidgets?: Array<{
 		name: string;
 		label: string;
@@ -135,6 +148,8 @@ export interface EmDashManifest {
 	 * registry plugin's `env:astro` requirement against the running host.
 	 */
 	astroVersion?: string;
+	/** IANA timezone used by datetime-local controls in the admin. */
+	timezone?: string;
 	collections: Record<string, ManifestCollection>;
 	plugins: Record<string, ManifestPlugin>;
 	/**
@@ -177,11 +192,9 @@ export interface EmDashManifest {
 	}>;
 	/**
 	 * Whether the plugin marketplace is configured.
-	 * When true, the admin UI can show marketplace browse/install features.
-	 *
-	 * When `registry` is also present, the registry replaces the marketplace
-	 * for the admin UI's browse and install flows. Existing marketplace-installed
-	 * plugins continue to work; new installs and updates use the registry.
+	 * When true, the admin shows migration guidance and keeps legacy installed
+	 * plugins updateable and uninstallable. It does not expose marketplace
+	 * browse or install flows.
 	 */
 	marketplace?: boolean;
 	/**
@@ -254,6 +267,15 @@ export interface HandlerResponse<T = unknown> {
  * handleContentGet, handleRevisionGet) use narrower types.
  */
 export interface EmDashHandlers {
+	// Comment administration
+	handleCommentModerate?: (
+		id: string,
+		status: "pending" | "approved" | "spam" | "trash",
+		moderator: { id: string; name: string | null },
+		expectedStatus?: "pending" | "approved" | "spam" | "trash",
+		request?: Request,
+	) => Promise<unknown>;
+
 	// Content handlers
 	handleContentList: (
 		collection: string,
@@ -363,22 +385,35 @@ export interface EmDashHandlers {
 	handleContentPublish: (
 		collection: string,
 		id: string,
-		options?: { publishedAt?: string; requireScheduledDue?: boolean; _rev?: string },
+		options?: {
+			publishedAt?: string;
+			requireScheduledDue?: boolean;
+			expectedScheduledAt?: string;
+			_rev?: string;
+			currentTime?: Date;
+			actor?: ActorInfo;
+			origin?: ContentActionOrigin;
+		},
 	) => Promise<HandlerResponse>;
 
 	handleContentUnpublish: (
 		collection: string,
 		id: string,
-		options?: { _rev?: string },
+		options?: { _rev?: string; actor?: ActorInfo; origin?: ContentActionOrigin },
 	) => Promise<HandlerResponse>;
 
 	handleContentSchedule: (
 		collection: string,
 		id: string,
 		scheduledAt: string,
+		options?: { _rev?: string; actor?: ActorInfo; origin?: ContentActionOrigin },
 	) => Promise<HandlerResponse>;
 
-	handleContentUnschedule: (collection: string, id: string) => Promise<HandlerResponse>;
+	handleContentUnschedule: (
+		collection: string,
+		id: string,
+		options?: { _rev?: string },
+	) => Promise<HandlerResponse>;
 
 	handleContentCountScheduled: (collection: string) => Promise<HandlerResponse>;
 
@@ -403,6 +438,16 @@ export interface EmDashHandlers {
 
 	handleMediaGet: (id: string) => Promise<HandlerResponse>;
 
+	handleMediaUpload: (input: {
+		filename: string;
+		base64?: string;
+		url?: string;
+		contentType?: string;
+		alt?: string;
+		authorId?: string;
+		maxUploadSize?: number;
+	}) => Promise<HandlerResponse>;
+
 	handleMediaCreate: (input: {
 		filename: string;
 		mimeType: string;
@@ -467,7 +512,16 @@ export interface EmDashHandlers {
 		path: string,
 		request: Request,
 		user?: RouteCallerInput | null,
+		invalidateContentCache?: PluginContentCacheInvalidator,
+		editorDispatch?: PluginEditorExtensionDispatch,
 	) => Promise<HandlerResponse>;
+	getPluginEditorExtension: (
+		pluginId: string,
+		kind: "panel" | "action",
+		extensionId: string,
+		collection: string,
+	) => ResolvedPluginEditorExtension | null;
+	getPluginEditorDraftSchema: (collection: string) => Promise<CollectionWithFields | null>;
 
 	// Public-only plugin API route handler for SSR page components.
 	handlePublicPluginApiRoute: (
@@ -515,6 +569,7 @@ export interface EmDashHandlers {
 		actorId: string,
 		request: Request,
 		caller?: RouteCallerInput | null,
+		invalidateContentCache?: PluginContentCacheInvalidator,
 	) => Promise<HandlerResponse>;
 	handlePluginMcpDenied: (
 		pluginId: string,
@@ -577,6 +632,12 @@ export interface EmDashHandlers {
 
 	// Sync registry plugin states (after install/update/uninstall)
 	syncRegistryPlugins: () => Promise<void>;
+	// Run install and activation hooks after the runtime loads a new plugin.
+	runPluginInstallLifecycle: (pluginId: string) => Promise<void>;
+	runPluginActivateLifecycle: (pluginId: string) => Promise<void>;
+	runPluginUninstallLifecycle: (pluginId: string, deleteData: boolean) => Promise<void>;
+	// Read settings metadata for runtime-installed plugins.
+	getRuntimePluginSettingsSchema: (pluginId: string) => Record<string, unknown> | null;
 
 	// Update plugin enabled/disabled status and rebuild hook pipeline
 	setPluginStatus: (pluginId: string, status: "active" | "inactive") => Promise<void>;

package/src/cli/commands/bundle-utils.ts

@@ -11,11 +11,12 @@ import { resolve, join } from "node:path";
 import { pipeline } from "node:stream/promises";
 import { pathToFileURL } from "node:url";
 
+import { extractManifestRoute, isJsonPostRouteContract } from "@emdash-cms/plugin-types";
 import { imageSize } from "image-size";
 import { packTar } from "modern-tar/fs";
 import { z } from "zod";
 
-import { capabilitiesToDeclaredAccess } from "../../plugins/types.js";
+import { capabilitiesToDeclaredAccess, declaredAccessToCapabilities } from "../../plugins/types.js";
 import type {
 	PluginManifest,
 	ResolvedPlugin,
@@ -140,6 +141,14 @@ export function readImageDimensions(buf: Uint8Array): [number, number] | null {
  * Strips functions (hooks, route handlers) and keeps only serializable metadata.
  */
 export function extractManifest(plugin: ResolvedPlugin): PluginManifest {
+	if ((plugin.admin.pages?.length ?? 0) > 0 || (plugin.admin.widgets?.length ?? 0) > 0) {
+		const adminRoute = plugin.routes.admin;
+		if (adminRoute && (adminRoute.public === true || !isJsonPostRouteContract(adminRoute))) {
+			throw new Error("Block Kit admin route must accept POST JSON requests and return JSON");
+		}
+	}
+	const declaredAccess = capabilitiesToDeclaredAccess(plugin.capabilities, plugin.allowedHosts);
+	const enforcedAccess = declaredAccessToCapabilities(declaredAccess);
 	// Build hook entries preserving exclusive/priority/timeout metadata.
 	// Plain HookName strings are emitted for hooks with default settings;
 	// structured ManifestHookEntry objects are emitted when metadata differs.
@@ -160,28 +169,17 @@ export function extractManifest(plugin: ResolvedPlugin): PluginManifest {
 	}
 
 	const routes: Array<ManifestRouteEntry | string> = Object.entries(plugin.routes).map(
-		([name, route]) => {
-			if (
-				route.public === undefined &&
-				route.permission === undefined &&
-				route.cacheControl === undefined
-			) {
-				return name;
-			}
-
-			const entry: ManifestRouteEntry = { name };
-			if (route.public !== undefined) entry.public = route.public;
-			if (route.permission !== undefined) entry.permission = route.permission;
-			if (route.cacheControl !== undefined) entry.cacheControl = route.cacheControl;
-			return entry;
-		},
+		([name, route]) => extractManifestRoute(name, route),
 	);
 	const tools: ManifestMcpTool[] = Object.entries(plugin.mcp?.tools ?? {}).map(([name, tool]) => {
 		if (!MCP_TOOL_NAME_PATTERN.test(name)) throw new Error(`Invalid MCP tool name "${name}"`);
 		const route = plugin.routes[tool.route];
-		if (!route?.permission || route.public) {
+		if (!route?.permission || route.public || route.response === "raw") {
 			throw new Error(`MCP tool "${name}" must reference a private route with a permission`);
 		}
+		if (!isJsonPostRouteContract(route)) {
+			throw new Error(`MCP tool "${name}" must reference a POST-compatible JSON route`);
+		}
 		return {
 			name,
 			description: tool.description,
@@ -200,8 +198,8 @@ export function extractManifest(plugin: ResolvedPlugin): PluginManifest {
 	return {
 		id: plugin.id,
 		version: plugin.version,
-		declaredAccess: capabilitiesToDeclaredAccess(plugin.capabilities, plugin.allowedHosts),
-		capabilities: plugin.capabilities,
+		declaredAccess,
+		capabilities: enforcedAccess.capabilities,
 		allowedHosts: plugin.allowedHosts,
 		storage: plugin.storage,
 		hooks,
@@ -212,6 +210,8 @@ export function extractManifest(plugin: ResolvedPlugin): PluginManifest {
 			settingsSchema: plugin.admin.settingsSchema,
 			pages: plugin.admin.pages,
 			widgets: plugin.admin.widgets,
+			editorPanels: plugin.admin.editorPanels,
+			editorActions: plugin.admin.editorActions,
 		},
 	};
 }

package/src/cli/commands/bundle.ts

@@ -17,6 +17,7 @@ import { createHash } from "node:crypto";
 import { readFile, stat, mkdir, writeFile, rm, copyFile, symlink, readdir } from "node:fs/promises";
 import { resolve, join, extname, basename } from "node:path";
 
+import { extractRouteOptions } from "@emdash-cms/plugin-types";
 import { defineCommand } from "citty";
 import consola from "consola";
 
@@ -302,11 +303,13 @@ export const bundleCommand = defineCommand({
 									}
 									if (routes) {
 										for (const [name, route] of Object.entries(routes)) {
-											const routeObj = route as Record<string, unknown>;
+											const routeObj =
+												typeof route === "object" && route !== null
+													? (route as Record<string, unknown>)
+													: {};
 											(resolvedPlugin.routes as Record<string, unknown>)[name] = {
-												handler: routeObj.handler,
-												public: routeObj.public,
-												cacheControl: routeObj.cacheControl,
+												handler: typeof route === "function" ? route : routeObj.handler,
+												...extractRouteOptions(route),
 											};
 										}
 									}
@@ -314,8 +317,8 @@ export const bundleCommand = defineCommand({
 							}
 							break;
 						}
-					} catch {
-						// Not a descriptor factory, skip
+					} catch (error) {
+						if (resolvedPlugin) throw error;
 					}
 				}
 			}

package/src/cli/commands/content.ts

@@ -389,7 +389,7 @@ const scheduleCommand = defineCommand({
 		},
 		at: {
 			type: "string",
-			description: "ISO 8601 datetime to publish at",
+			description: "ISO 8601 datetime with Z or an explicit UTC offset to publish at",
 			required: true,
 		},
 		"override-lock": {

package/src/cli/commands/doctor.ts

@@ -14,6 +14,10 @@ import { parse, printParseErrorCode, type ParseError } from "jsonc-parser";
 import { parse as parseToml } from "smol-toml";
 
 import { createDatabase } from "../../database/connection.js";
+import {
+	formatDatetimeStorageReport,
+	scanDatetimeStorage,
+} from "../../database/datetime-storage.js";
 import { listTablesLike } from "../../database/dialect-helpers.js";
 import { getMigrationStatus } from "../../database/migrations/runner.js";
 
@@ -302,6 +306,27 @@ async function checkDatabase(dbPath: string): Promise<CheckResult[]> {
 					message: `found ${orphaned.length}: ${orphaned.join(", ")}`,
 				});
 			}
+
+			try {
+				const report = await scanDatetimeStorage(db);
+				const clean =
+					report.noncanonicalCount === 0 &&
+					report.manualReviewCount === 0 &&
+					report.inspectionErrorCount === 0;
+				results.push({
+					name: "datetime storage",
+					status: clean ? "pass" : "fail",
+					message: clean
+						? `all stored content datetimes are canonical (${report.timezone})`
+						: formatDatetimeStorageReport(report),
+				});
+			} catch (error) {
+				results.push({
+					name: "datetime storage",
+					status: "fail",
+					message: `could not inspect stored datetimes: ${error instanceof Error ? error.message : String(error)}`,
+				});
+			}
 		} catch {
 			// Non-critical — tables may not exist on fresh DB
 		}