emdash 0.33.0 → 0.35.0

package/src/astro/routes/api/admin/plugins/marketplace/[id]/install.ts

@@ -10,6 +10,7 @@ import { z } from "zod";
 import { requirePerm } from "#api/authorize.js";
 import { apiError, handleError, unwrapResult } from "#api/error.js";
 import { handleMarketplaceInstall } from "#api/index.js";
+import { checkMediaUsageActivationWriteFence } from "#api/media-usage-write-fence.js";
 import { isParseError, parseOptionalBody } from "#api/parse.js";
 
 export const prerender = false;
@@ -31,6 +32,9 @@ export const POST: APIRoute = async ({ params, request, locals }) => {
 		const denied = requirePerm(user, "plugins:manage");
 		if (denied) return denied;
 
+		const activationFence = await checkMediaUsageActivationWriteFence(emdash.db);
+		if (activationFence) return activationFence;
+
 		if (!id) {
 			return apiError("INVALID_REQUEST", "Plugin ID required", 400);
 		}

package/src/astro/routes/api/admin/plugins/registry/[id]/uninstall.ts

@@ -13,6 +13,7 @@ import { z } from "zod";
 import { requirePerm } from "#api/authorize.js";
 import { apiError, unwrapResult } from "#api/error.js";
 import { handleRegistryUninstall } from "#api/index.js";
+import { checkMediaUsageActivationWriteFence } from "#api/media-usage-write-fence.js";
 import { isParseError, parseOptionalBody } from "#api/parse.js";
 
 export const prerender = false;
@@ -32,6 +33,9 @@ export const POST: APIRoute = async ({ params, request, locals }) => {
 	const denied = requirePerm(user, "plugins:manage");
 	if (denied) return denied;
 
+	const activationFence = await checkMediaUsageActivationWriteFence(emdash.db);
+	if (activationFence) return activationFence;
+
 	if (!id) {
 		return apiError("INVALID_REQUEST", "Plugin ID required", 400);
 	}

package/src/astro/routes/api/admin/plugins/registry/[id]/update.ts

@@ -16,6 +16,7 @@ import { z } from "zod";
 import { requirePerm } from "#api/authorize.js";
 import { apiError, handleError, unwrapResult } from "#api/error.js";
 import { handleRegistryUpdate } from "#api/index.js";
+import { checkMediaUsageActivationWriteFence } from "#api/media-usage-write-fence.js";
 import { isParseError, parseOptionalBody } from "#api/parse.js";
 
 import { VERSION } from "../../../../../../../version.js";
@@ -51,6 +52,9 @@ export const POST: APIRoute = async ({ params, request, locals }) => {
 		const denied = requirePerm(user, "plugins:manage");
 		if (denied) return denied;
 
+		const activationFence = await checkMediaUsageActivationWriteFence(emdash.db);
+		if (activationFence) return activationFence;
+
 		if (!id) {
 			return apiError("INVALID_REQUEST", "Plugin ID required", 400);
 		}

package/src/astro/routes/api/admin/plugins/registry/install.ts

@@ -19,6 +19,7 @@ import { z } from "zod";
 import { requirePerm } from "#api/authorize.js";
 import { apiError, handleError, unwrapResult } from "#api/error.js";
 import { handleRegistryInstall } from "#api/index.js";
+import { checkMediaUsageActivationWriteFence } from "#api/media-usage-write-fence.js";
 import { isParseError, parseBody } from "#api/parse.js";
 
 import { VERSION } from "../../../../../../version.js";
@@ -71,6 +72,9 @@ export const POST: APIRoute = async ({ request, locals }) => {
 		const denied = requirePerm(user, "plugins:manage");
 		if (denied) return denied;
 
+		const activationFence = await checkMediaUsageActivationWriteFence(emdash.db);
+		if (activationFence) return activationFence;
+
 		const body = await parseBody(request, installBodySchema);
 		if (isParseError(body)) return body;
 

package/src/astro/routes/api/auth/dev-bypass.ts

@@ -24,7 +24,6 @@ import { ulid } from "ulidx";
 import { apiError, apiSuccess, handleError } from "#api/error.js";
 import { escapeHtml } from "#api/escape.js";
 import { isSafeRedirect } from "#api/redirect.js";
-import { runMigrations } from "#db/migrations/runner.js";
 
 const DEV_USER_EMAIL = "dev@emdash.local";
 const DEV_USER_NAME = "Dev Admin";
@@ -46,9 +45,6 @@ async function handleDevBypass(context: Parameters<APIRoute>[0]): Promise<Respon
 	}
 
 	try {
-		// Ensure migrations are run
-		await runMigrations(emdash.db);
-
 		// Find or create dev user (direct DB access to avoid @emdash-cms/auth import issues in dev)
 		const existingUser = await emdash.db
 			.selectFrom("users")

package/src/astro/routes/api/content/[collection]/[id]/terms/[taxonomy].ts

@@ -12,11 +12,48 @@ import { apiError, apiSuccess, handleError, requireDb } from "#api/error.js";
 import { parseBody, isParseError } from "#api/parse.js";
 import { contentTermsBody } from "#api/schemas.js";
 import { ContentRepository } from "#db/repositories/content.js";
-import { TaxonomyRepository } from "#db/repositories/taxonomy.js";
+import {
+	TaxonomyRepository,
+	type TaxonomyAssignmentResolution,
+} from "#db/repositories/taxonomy.js";
 import { invalidateTermCache } from "#taxonomies/index.js";
 
+import { getI18nConfig } from "../../../../../../../i18n/config.js";
+
 export const prerender = false;
 
+function assignmentResponse(assignments: TaxonomyAssignmentResolution[], entryLocale: string) {
+	const config = getI18nConfig();
+	const defaultLocale = config?.defaultLocale ?? "en";
+	return {
+		terms: assignments.flatMap(({ term }) =>
+			term
+				? [
+						{
+							id: term.id,
+							name: term.name,
+							slug: term.slug,
+							label: term.label,
+							parentId: term.parentId,
+							locale: term.locale,
+							translationGroup: term.translationGroup,
+						},
+					]
+				: [],
+		),
+		unresolved: assignments
+			.filter(({ term }) => term === null)
+			.map(({ translationGroup, availableLocales, translations }) => ({
+				translationGroup,
+				availableLocales,
+				translations,
+			})),
+		entryLocale,
+		defaultLocale,
+		implicitDefaultLocale: config === null,
+	};
+}
+
 /**
  * Get terms assigned to an entry
  */
@@ -34,26 +71,24 @@ export const GET: APIRoute = async ({ params, locals }) => {
 	}
 
 	try {
-		// Terms are stored against the per-locale entry row but their
-		// translation_group spans every locale. Resolve the entry's own locale
-		// server-side (deterministic, not client-spoofable) so only the matching
-		// term variant is returned — see issue #1218.
+		// Assignments store content and term translation groups. Resolve the
+		// entry's locale server-side so the response includes only that locale's
+		// term variant.
 		const entry = await new ContentRepository(emdash.db).findByIdOrSlug(collection, id);
 		if (!entry) return apiError("NOT_FOUND", "Content not found", 404);
-		const locale = entry.locale ?? undefined;
+		const locale = entry.locale || getI18nConfig()?.defaultLocale || "en";
+		const defaultLocale = getI18nConfig()?.defaultLocale ?? "en";
 
 		const repo = new TaxonomyRepository(emdash.db);
-		const terms = await repo.getTermsForEntry(collection, entry.id, taxonomy, locale);
-
-		return apiSuccess({
-			terms: terms.map((t) => ({
-				id: t.id,
-				name: t.name,
-				slug: t.slug,
-				label: t.label,
-				parentId: t.parentId,
-			})),
-		});
+		const assignments = await repo.getTermAssignmentsForEntry(
+			collection,
+			entry.id,
+			taxonomy,
+			locale,
+			defaultLocale,
+		);
+
+		return apiSuccess(assignmentResponse(assignments, locale));
 	} catch (error) {
 		return handleError(error, "Failed to get entry terms", "TERMS_GET_ERROR");
 	}
@@ -108,9 +143,12 @@ export const POST: APIRoute = async ({ params, request, locals }) => {
 	// Resolve the canonical content ID from the handler result.
 	// The URL `id` param may be a slug; we must use the real ID for term storage.
 	const canonicalId = typeof existingItem?.id === "string" ? existingItem.id : id;
-	// The entry is per-locale; scope the term read to its locale so only the
-	// matching translation variant is returned in the response — see #1218.
-	const entryLocale = typeof existingItem?.locale === "string" ? existingItem.locale : undefined;
+	// The assignment spans the content translation group, while the response
+	// includes only the term variant matching this entry's locale.
+	const entryLocale =
+		typeof existingItem?.locale === "string"
+			? existingItem.locale
+			: (getI18nConfig()?.defaultLocale ?? "en");
 
 	try {
 		const body = await parseBody(request, contentTermsBody);
@@ -142,17 +180,15 @@ export const POST: APIRoute = async ({ params, request, locals }) => {
 		invalidateTermCache();
 
 		// Get the updated terms using the canonical ID, scoped to the entry locale
-		const terms = await repo.getTermsForEntry(collection, canonicalId, taxonomy, entryLocale);
-
-		return apiSuccess({
-			terms: terms.map((t) => ({
-				id: t.id,
-				name: t.name,
-				slug: t.slug,
-				label: t.label,
-				parentId: t.parentId,
-			})),
-		});
+		const assignments = await repo.getTermAssignmentsForEntry(
+			collection,
+			canonicalId,
+			taxonomy,
+			entryLocale,
+			getI18nConfig()?.defaultLocale ?? "en",
+		);
+
+		return apiSuccess(assignmentResponse(assignments, entryLocale));
 	} catch (error) {
 		return handleError(error, "Failed to set entry terms", "TERMS_SET_ERROR");
 	}

package/src/astro/routes/api/import/wordpress/execute.ts

@@ -395,16 +395,9 @@ export async function importContent(
 				// Anchors (no `translationOf`) get an additive attach -- the
 				// row is fresh, no inherited pivots to consider.
 				//
-				// Translations get per-taxonomy replace semantics. WPML's
-				// "Translate Independently" mode is per-taxonomy, not per-
-				// post: a translation that overrides `category` shouldn't
-				// lose its inherited `tag` or `genre`. The replace path
-				// only touches taxonomies the translation actually carries
-				// AND that resolve to at least one term that survives the
-				// def's `collections` filter; taxonomies with no resolved
-				// terms (missing-def, dropped by filter, or just absent
-				// from the WXR) fall through with the inherited set intact
-				// from `copyEntryTerms`.
+				// Translations replace only taxonomies they explicitly carry.
+				// Since assignments belong to the content translation_group,
+				// that replacement is reflected in every sibling locale.
 				if (createdItem) {
 					try {
 						const written = translationOf

package/src/astro/routes/api/mcp.ts

@@ -48,6 +48,7 @@ export const POST: APIRoute = async ({ request, locals }) => {
 				scopes: [],
 				extra: {
 					emdash,
+					user,
 					userId: user.id,
 					userRole: user.role,
 					tokenScopes: locals.tokenScopes,

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

@@ -73,7 +73,13 @@ const handleRequest: APIRoute = async ({ params, request, locals }) => {
 		}
 	}
 
-	const result = await emdash.handlePluginApiRoute(pluginId, method, `/${path}`, request);
+	// 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";

package/src/astro/routes/api/schema/collections/[slug]/index.ts

@@ -17,7 +17,6 @@ import {
 } from "#api/index.js";
 import { parseBody, parseQuery, isParseError } from "#api/parse.js";
 import { collectionGetQuery, updateCollectionBody } from "#api/schemas.js";
-import type { UpdateCollectionInput } from "#schema/types.js";
 
 export const prerender = false;
 
@@ -53,12 +52,7 @@ export const PUT: APIRoute = async ({ params, request, locals }) => {
 	const body = await parseBody(request, updateCollectionBody);
 	if (isParseError(body)) return body;
 
-	const result = await handleSchemaCollectionUpdate(
-		emdash.db,
-		slug,
-		// eslint-disable-next-line typescript/no-unsafe-type-assertion -- parseBody validates via Zod
-		body as UpdateCollectionInput,
-	);
+	const result = await handleSchemaCollectionUpdate(emdash.db, slug, body);
 	emdash.invalidateUrlPatternCache();
 	return unwrapResult(result);
 };

package/src/astro/routes/api/setup/dev-bypass.ts

@@ -3,7 +3,7 @@
  * GET  /_emdash/api/setup/dev-bypass
  *
  * Development-only endpoint to bypass the setup wizard.
- * Runs migrations, creates a dev admin user, and marks setup complete.
+ * Creates a dev admin user and marks setup complete after runtime initialization.
  *
  * ONLY available when import.meta.env.DEV is true.
  *
@@ -28,7 +28,6 @@ import { escapeHtml } from "#api/escape.js";
 import { deleteApiTokensByName, handleApiTokenCreate } from "#api/handlers/api-tokens.js";
 import { getPublicOrigin } from "#api/public-url.js";
 import { isSafeRedirect } from "#api/redirect.js";
-import { runMigrations } from "#db/migrations/runner.js";
 import { OptionsRepository } from "#db/repositories/options.js";
 import { applySeed } from "#seed/apply.js";
 import { loadSeed } from "#seed/load.js";
@@ -55,10 +54,6 @@ async function handleDevBypass(context: Parameters<APIRoute>[0]): Promise<Respon
 	}
 
 	try {
-		// Run migrations
-		const migrations = await runMigrations(emdash.db);
-		console.log("[setup-dev-bypass] Migrations applied:", migrations.applied);
-
 		// Apply seed (user seed or built-in default). `?content=0` (or `false`)
 		// applies schema/structure only — no sample content, bylines, or terms.
 		const contentParam = url.searchParams.get("content");
@@ -189,7 +184,7 @@ async function handleDevBypass(context: Parameters<APIRoute>[0]): Promise<Respon
 		return apiSuccess({
 			success: true,
 			message: "Dev setup complete",
-			migrations: migrations.applied,
+			migrations: [],
 			userCreated,
 			user: {
 				id: user.id,

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

@@ -13,7 +13,6 @@ import { isParseError, parseBody } from "#api/parse.js";
 import { getPublicOrigin } from "#api/public-url.js";
 import { setupBody } from "#api/schemas.js";
 import { getAuthMode } from "#auth/mode.js";
-import { runMigrations } from "#db/migrations/runner.js";
 import { OptionsRepository } from "#db/repositories/options.js";
 import { applySeed } from "#seed/apply.js";
 import { loadSeed } from "#seed/load.js";
@@ -45,24 +44,17 @@ export const POST: APIRoute = async ({ request, url, locals }) => {
 		const body = await parseBody(request, setupBody);
 		if (isParseError(body)) return body;
 
-		// 1. Run core migrations
-		try {
-			await runMigrations(emdash.db);
-		} catch (error) {
-			return handleError(error, "Failed to run database migrations", "MIGRATION_ERROR");
-		}
-
-		// 2. Load seed file (user seed or built-in default)
+		// Load seed file (user seed or built-in default)
 		const seed = await loadSeed();
 
-		// 3. Override seed settings with form values
+		// Override seed settings with form values
 		seed.settings = {
 			...seed.settings,
 			title: body.title,
 			tagline: body.tagline,
 		};
 
-		// 4. Apply seed
+		// Apply seed
 		const validation = validateSeed(seed);
 		if (!validation.valid) {
 			return apiError("INVALID_SEED", `Invalid seed file: ${validation.errors.join(", ")}`, 400);
@@ -79,7 +71,7 @@ export const POST: APIRoute = async ({ request, url, locals }) => {
 			return handleError(error, "Failed to apply seed", "SEED_ERROR");
 		}
 
-		// 5. Store setup state
+		// Store setup state
 		// In external auth mode, mark setup complete immediately (first user to login becomes admin)
 		// Otherwise, setup_complete is set after admin user is created (passkey or auth provider)
 		const authMode = getAuthMode(emdash.config);
@@ -117,7 +109,7 @@ export const POST: APIRoute = async ({ request, url, locals }) => {
 			// Non-fatal - continue anyway
 		}
 
-		// 6. Return success with result
+		// Return success with result
 		return apiSuccess({
 			success: true,
 			// In external auth mode, setup is complete - redirect to admin

package/src/astro/routes/api/taxonomies/[name]/terms/index.ts

@@ -36,6 +36,7 @@ export const GET: APIRoute = async ({ params, request, locals }) => {
 		const result = await handleTermList(emdash.db, name, {
 			locale: query.locale,
 			includeCounts: query.includeCounts,
+			resolveFallback: query.resolveFallback,
 		});
 		return unwrapResult(result);
 	} catch (error) {

package/src/astro/routes/api/taxonomies/[name]/translations.ts

@@ -0,0 +1,48 @@
+/**
+ * Taxonomy definition translation endpoints
+ *
+ * GET /_emdash/api/taxonomies/:name/translations[?locale=xx]
+ *
+ * Creating a translation goes through `POST /_emdash/api/taxonomies` with
+ * `translationOf`, so there is no POST here.
+ */
+
+import type { APIRoute } from "astro";
+
+import { requirePerm } from "#api/authorize.js";
+import { apiError, handleError, requireDb, unwrapResult } from "#api/error.js";
+import { handleTaxonomyDefTranslations, handleTaxonomyGet } from "#api/handlers/taxonomies.js";
+import { isParseError, parseQuery } from "#api/parse.js";
+import { localeFilterQuery } from "#api/schemas.js";
+
+export const prerender = false;
+
+export const GET: APIRoute = async ({ params, request, locals }) => {
+	const { emdash, user } = locals;
+	const { name } = params;
+	if (!name) return apiError("VALIDATION_ERROR", "Taxonomy name required", 400);
+
+	const dbErr = requireDb(emdash?.db);
+	if (dbErr) return dbErr;
+
+	const denied = requirePerm(user, "taxonomies:read");
+	if (denied) return denied;
+
+	const query = parseQuery(new URL(request.url), localeFilterQuery);
+	if (isParseError(query)) return query;
+
+	try {
+		// Any locale's row will do — they share the translation_group the list is
+		// built from.
+		const anchor = await handleTaxonomyGet(emdash.db, name, { locale: query.locale });
+		if (!anchor.success) return unwrapResult(anchor);
+		const result = await handleTaxonomyDefTranslations(emdash.db, anchor.data.taxonomy.id);
+		return unwrapResult(result);
+	} catch (error) {
+		return handleError(
+			error,
+			"Failed to list taxonomy translations",
+			"TAXONOMY_TRANSLATIONS_ERROR",
+		);
+	}
+};

package/src/astro/routes/api/taxonomies/[name].ts

@@ -0,0 +1,102 @@
+/**
+ * Single taxonomy definition endpoint
+ *
+ * GET    /_emdash/api/taxonomies/:name[?locale=xx]
+ * PUT    /_emdash/api/taxonomies/:name[?locale=xx]
+ * DELETE /_emdash/api/taxonomies/:name
+ *
+ * GET and PUT address one locale's definition. DELETE takes no locale — it
+ * removes the taxonomy outright, terms and assignments included.
+ */
+
+import type { APIRoute } from "astro";
+
+import { requirePerm } from "#api/authorize.js";
+import { apiError, handleError, requireDb, unwrapResult } from "#api/error.js";
+import {
+	handleTaxonomyDelete,
+	handleTaxonomyGet,
+	handleTaxonomyUpdate,
+} from "#api/handlers/taxonomies.js";
+import { isParseError, parseBody, parseQuery } from "#api/parse.js";
+import { localeFilterQuery, updateTaxonomyDefBody } from "#api/schemas.js";
+
+export const prerender = false;
+
+/**
+ * Get a single taxonomy definition
+ */
+export const GET: APIRoute = async ({ params, request, locals }) => {
+	const { emdash, user } = locals;
+	const { name } = params;
+	if (!name) return apiError("VALIDATION_ERROR", "Taxonomy name required", 400);
+
+	const dbErr = requireDb(emdash?.db);
+	if (dbErr) return dbErr;
+
+	const denied = requirePerm(user, "taxonomies:read");
+	if (denied) return denied;
+
+	const query = parseQuery(new URL(request.url), localeFilterQuery);
+	if (isParseError(query)) return query;
+
+	try {
+		const result = await handleTaxonomyGet(emdash.db, name, { locale: query.locale });
+		return unwrapResult(result);
+	} catch (error) {
+		return handleError(error, "Failed to get taxonomy", "TAXONOMY_GET_ERROR");
+	}
+};
+
+/**
+ * Update a taxonomy definition
+ */
+export const PUT: APIRoute = async ({ params, request, locals }) => {
+	const { emdash, user } = locals;
+	const { name } = params;
+	if (!name) return apiError("VALIDATION_ERROR", "Taxonomy name required", 400);
+
+	const dbErr = requireDb(emdash?.db);
+	if (dbErr) return dbErr;
+
+	const denied = requirePerm(user, "taxonomies:manage");
+	if (denied) return denied;
+
+	const query = parseQuery(new URL(request.url), localeFilterQuery);
+	if (isParseError(query)) return query;
+
+	try {
+		const body = await parseBody(request, updateTaxonomyDefBody);
+		if (isParseError(body)) return body;
+
+		const result = await handleTaxonomyUpdate(emdash.db, name, {
+			...body,
+			locale: query.locale,
+		});
+		return unwrapResult(result);
+	} catch (error) {
+		return handleError(error, "Failed to update taxonomy", "TAXONOMY_UPDATE_ERROR");
+	}
+};
+
+/**
+ * Delete a taxonomy, its terms, and their content assignments
+ */
+export const DELETE: APIRoute = async ({ params, locals }) => {
+	const { emdash, user } = locals;
+	const { name } = params;
+	if (!name) return apiError("VALIDATION_ERROR", "Taxonomy name required", 400);
+
+	const dbErr = requireDb(emdash?.db);
+	if (dbErr) return dbErr;
+
+	const denied = requirePerm(user, "taxonomies:manage");
+	if (denied) return denied;
+
+	try {
+		const result = await handleTaxonomyDelete(emdash.db, name);
+		return unwrapResult(result);
+	} catch (error) {
+		return handleError(error, "Failed to delete taxonomy", "TAXONOMY_DELETE_ERROR");
+	}
+};

package/src/astro/types.ts

@@ -8,7 +8,8 @@
 import type { Element } from "@emdash-cms/blocks";
 import type { Kysely } from "kysely";
 
-import type { RouteMeta } from "../plugins/routes.js";
+import type { ContentFieldFilters } from "../content-list-query.js";
+import type { RouteCallerInput, RouteMeta } from "../plugins/routes.js";
 
 // Re-export core types
 export type {
@@ -31,12 +32,18 @@ export interface ManifestCollection {
 	supports: string[];
 	hasSeo: boolean;
 	urlPattern?: string;
+	/** Whether published entries require a slug. Defaults to true. */
+	routable?: boolean;
+	titleField?: string;
+	dateField?: string;
 	/**
 	 * Omit the auto-generated sidebar entry in the admin. The collection is
 	 * still listed in the manifest so its routes, editor, and API keep working
 	 * — only the navigation link is dropped.
 	 */
 	hidden?: boolean;
+	/** Valid custom field slugs to render in the admin content list. */
+	listColumns?: string[];
 	fields: Record<
 		string,
 		{
@@ -145,15 +152,22 @@ export interface EmDashManifest {
 		locales: string[];
 		prefixDefaultLocale?: boolean;
 	};
+	contentLocale?: {
+		defaultLocale: string;
+		implicit: boolean;
+	};
 	/**
 	 * Taxonomy definitions for the admin sidebar.
 	 */
 	taxonomies: Array<{
+		id: string;
 		name: string;
 		label: string;
 		labelSingular?: string;
 		hierarchical: boolean;
 		collections: string[];
+		locale: string;
+		translationGroup: string;
 	}>;
 	/**
 	 * Whether the plugin marketplace is configured.
@@ -247,6 +261,10 @@ export interface EmDashHandlers {
 			dateField?: "createdAt" | "updatedAt" | "publishedAt";
 			dateFrom?: string;
 			dateTo?: string;
+			bylines?: string[];
+			bylinesNone?: boolean;
+			includeInferredBylines?: boolean;
+			fieldFilters?: ContentFieldFilters;
 		},
 	) => Promise<HandlerResponse>;
 
@@ -271,7 +289,7 @@ export interface EmDashHandlers {
 		collection: string,
 		body: {
 			data: Record<string, unknown>;
-			slug?: string;
+			slug?: string | null;
 			status?: string;
 			authorId?: string;
 			bylines?: Array<{ bylineId: string; roleLabel?: string | null }>;
@@ -288,7 +306,7 @@ export interface EmDashHandlers {
 		id: string,
 		body: {
 			data?: Record<string, unknown>;
-			slug?: string;
+			slug?: string | null;
 			status?: string;
 			authorId?: string | null;
 			bylines?: Array<{ bylineId: string; roleLabel?: string | null }>;
@@ -403,12 +421,14 @@ export interface EmDashHandlers {
 
 	handleRevisionRestore: (revisionId: string, callerUserId: string) => Promise<HandlerResponse>;
 
-	// Plugin API route handler
+	// Plugin API route handler. `user` is the authenticated caller for
+	// private routes, exposed to plugin handlers as `ctx.user`.
 	handlePluginApiRoute: (
 		pluginId: string,
 		method: string,
 		path: string,
 		request: Request,
+		user?: RouteCallerInput | null,
 	) => Promise<HandlerResponse>;
 
 	// Public-only plugin API route handler for SSR page components.
@@ -456,6 +476,7 @@ export interface EmDashHandlers {
 		input: unknown,
 		actorId: string,
 		request: Request,
+		caller?: RouteCallerInput | null,
 	) => Promise<HandlerResponse>;
 	handlePluginMcpDenied: (
 		pluginId: string,