feat(admin): add Media Usage setup and indexing progress

.changeset/media-usage-activation-ui.md

@@ -0,0 +1,6 @@
+---
+"emdash": minor
+"@emdash-cms/admin": minor
+---
+
+Adds guided Media Usage setup and historical indexing progress for administrators.

docs/src/content/docs/deployment/cloudflare.mdx

@@ -110,10 +110,13 @@ To use different schedules, set the corresponding `generalCron` or `mediaUsageCr
 
 ### Enable automatic media usage indexing
 
-Keep `mediaUsageCron` running while you enable automatic media usage indexing. Pause all application
-and direct database writes, follow [Enable automatic media usage
-indexing](/reference/rest-api/#enable-automatic-media-usage-indexing), then resume writes when the
-endpoint returns `active`. Existing content is indexed in the background.
+Keep `mediaUsageCron` running, then pause all application and direct database writes. Open
+**Settings → Media Usage**, select **Enable Media Usage**, confirm the safety requirements, and use
+**Continue setup** until setup finishes. Resume writers only after activation is active. The page
+then shows how many content types have finished indexing existing content.
+
+The [REST procedure](/reference/rest-api/#enable-automatic-media-usage-indexing) remains available
+for API operators.
 
 ## Deploy
 

docs/src/content/docs/deployment/nodejs.mdx

@@ -63,10 +63,13 @@ scheduled tasks pause.
 
 ### Enable automatic media usage indexing
 
-Keep at least one Node process running while you enable automatic media usage indexing. Pause all
-application and direct database writes, follow [Enable automatic media usage
-indexing](/reference/rest-api/#enable-automatic-media-usage-indexing), then resume writes when the
-endpoint returns `active`. Existing content is indexed in the background.
+Keep at least one Node process running, then pause all application and direct database writes. Open
+**Settings → Media Usage**, select **Enable Media Usage**, confirm the safety requirements, and use
+**Continue setup** until setup finishes. Resume writers only after activation is active. The page
+then shows how many content types have finished indexing existing content.
+
+The [REST procedure](/reference/rest-api/#enable-automatic-media-usage-indexing) remains available
+for API operators.
 
 ## Production Storage
 

docs/src/content/docs/guides/media-library.mdx

@@ -14,6 +14,20 @@ Open the media library from the admin sidebar by clicking **Media**. The library
 
 <img src={mediaLibraryImg.src} alt="EmDash media library showing image grid with upload button" />
 
+## Used in
+
+Open a local media item's details to see known references from EmDash-managed content fields.
+Already-found references remain visible while historical content is still indexing.
+
+Administrators see a Media Library notice until automatic indexing is active. Open **Settings →
+Media Usage**, enable the feature, and continue its bounded setup steps. Once active, the Settings
+page shows how many content types have finished indexing existing content.
+
+<Aside type="caution">
+	Used in results are advisory. They do not prove that a media item is universally unused or safe to
+	delete.
+</Aside>
+
 ## Uploading Files
 
 ### From the Media Library

docs/src/content/docs/reference/rest-api.mdx

@@ -371,6 +371,9 @@ paused while EmDash prepares each collection so that no changes are missed.
 
 Both endpoints require `schema:manage`. Bearer tokens also require the `admin` scope.
 
+Administrators can run the same procedure from **Settings → Media Usage**. The page sends one POST
+per deliberate setup action; it cannot stop external writers or verify scheduled maintenance.
+
 #### Check the current state
 
 ```http
@@ -429,6 +432,16 @@ again. Do not edit EmDash's internal database tables.
 When the state is `active`, EmDash tracks changes to media references in content. Existing content
 may still be indexing in the background.
 
+#### Check historical indexing progress
+
+```http
+GET /_emdash/api/admin/media-usage/progress
+```
+
+After activation is active, this returns `indexing`, `ready`, or `needs_attention` together with the
+number of ready and total current content types. It does not inspect content rows or return work-item
+details. The endpoint requires `schema:manage`; bearer tokens also require the `admin` scope.
+
 ### List Media Usage Work
 
 ```http

packages/admin/src/components/ConfirmDialog.tsx

@@ -24,6 +24,7 @@ export interface ConfirmDialogProps {
 	/** Button variant — defaults to "destructive" */
 	variant?: "destructive" | "primary";
 	isPending: boolean;
+	disabled?: boolean;
 	/** Error from a mutation — pass mutation.error directly */
 	error: unknown;
 	onConfirm: () => void;
@@ -40,6 +41,7 @@ export function ConfirmDialog({
 	pendingLabel,
 	variant = "destructive",
 	isPending,
+	disabled = false,
 	error,
 	onConfirm,
 	children,
@@ -56,7 +58,7 @@ export function ConfirmDialog({
 					<Button variant="secondary" onClick={onClose}>
 						{t`Cancel`}
 					</Button>
-					<Button variant={variant} disabled={isPending} onClick={onConfirm}>
+					<Button variant={variant} disabled={disabled || isPending} onClick={onConfirm}>
 						{isPending ? pendingLabel : confirmLabel}
 					</Button>
 				</div>

packages/admin/src/components/MediaLibrary.tsx

@@ -1,4 +1,4 @@
-import { Button, Input, Loader, Select, Tabs } from "@cloudflare/kumo";
+import { Banner, Button, Input, Loader, Select, Tabs } from "@cloudflare/kumo";
 import { plural } from "@lingui/core/macro";
 import { useLingui } from "@lingui/react/macro";
 import {
@@ -22,6 +22,11 @@ import {
 	fetchProviderMedia,
 	uploadToProvider,
 } from "../lib/api";
+import { useCurrentUser } from "../lib/api/current-user.js";
+import {
+	MEDIA_USAGE_ACTIVATION_QUERY_KEY,
+	fetchMediaUsageActivationStatus,
+} from "../lib/api/media-usage-activation.js";
 import { useDebouncedValue } from "../lib/hooks.js";
 import {
 	providerItemToMediaItem,
@@ -33,6 +38,7 @@ import {
 } from "../lib/media-utils";
 import { cn } from "../lib/utils";
 import { MediaDetailPanel } from "./MediaDetailPanel";
+import { RouterLinkButton } from "./RouterLinkButton.js";
 
 /** Maps a coarse type-filter choice to the media list's `mimeType` filter. */
 function mimeForTypeFilter(value: string): string | string[] | undefined {
@@ -80,6 +86,17 @@ export function MediaLibrary({
 	onLocalMimeFilterChange,
 }: MediaLibraryProps) {
 	const { t } = useLingui();
+	const isAdmin = (useCurrentUser().data?.role ?? 0) >= 50;
+	const activationQuery = useQuery({
+		queryKey: MEDIA_USAGE_ACTIVATION_QUERY_KEY,
+		queryFn: fetchMediaUsageActivationStatus,
+		enabled: isAdmin,
+		retry: false,
+		staleTime: 60_000,
+		refetchOnWindowFocus: false,
+		refetchOnReconnect: false,
+	});
+	const setupStatus = isAdmin && !activationQuery.isError ? activationQuery.data : undefined;
 	const [viewMode, setViewMode] = React.useState<"grid" | "list">("grid");
 	const [detailItem, setDetailItem] = React.useState<MediaItem | null>(null);
 	const [isDetailOpen, setIsDetailOpen] = React.useState(false);
@@ -368,6 +385,20 @@ export function MediaLibrary({
 					)}
 				</div>
 			</div>
+			{activeProvider === "local" && setupStatus && setupStatus.state !== "active" ? (
+				<Banner
+					variant="alert"
+					title={
+						setupStatus.state === "activating" ? t`Finish Media Usage setup` : t`Set up Media Usage`
+					}
+					description={t`Index existing content and keep Used in results up to date.`}
+					action={
+						<RouterLinkButton to="/settings/media-usage" size="sm" variant="secondary">
+							{setupStatus.state === "activating" ? t`Continue setup` : t`Enable Media Usage`}
+						</RouterLinkButton>
+					}
+				/>
+			) : null}
 
 			{/* Provider tabs (only when an external provider is configured) */}
 			{providerTabs.length > 1 && (

packages/admin/src/components/Settings.tsx

@@ -11,11 +11,13 @@ import {
 	Envelope,
 	DownloadSimple,
 	CaretDown,
+	ChartLineUp,
 } from "@phosphor-icons/react";
 import { useQuery } from "@tanstack/react-query";
 import * as React from "react";
 
 import { fetchManifest } from "../lib/api";
+import { useCurrentUser } from "../lib/api/current-user.js";
 import { SUPPORTED_LOCALES } from "../locales/index.js";
 import { useLocale } from "../locales/useLocale.js";
 import { SettingsNavRow, SettingsSection } from "./settings/SettingsLayout.js";
@@ -24,6 +26,7 @@ import { SettingsNavRow, SettingsSection } from "./settings/SettingsLayout.js";
  * Settings hub page — links to all settings sub-pages.
  */
 export function Settings() {
+	const { data: currentUser } = useCurrentUser();
 	const { data: manifest } = useQuery({
 		queryKey: ["manifest"],
 		queryFn: fetchManifest,
@@ -32,6 +35,7 @@ export function Settings() {
 	const { t } = useLingui();
 	const { locale, setLocale } = useLocale();
 	const showSecuritySettings = manifest?.authMode === "passkey";
+	const showMediaUsageSettings = (currentUser?.role ?? 0) >= 50;
 	const selectedLocale = SUPPORTED_LOCALES.find((option) => option.code === locale) ?? null;
 
 	return (
@@ -62,6 +66,17 @@ export function Settings() {
 					/>
 				</SettingsSection>
 
+				{showMediaUsageSettings ? (
+					<SettingsSection title={t`Media`}>
+						<SettingsNavRow
+							to="/settings/media-usage"
+							icon={<ChartLineUp className="h-5 w-5" />}
+							title={t`Media Usage`}
+							description={t`Track where media is used across your content`}
+						/>
+					</SettingsSection>
+				) : null}
+
 				{showSecuritySettings && (
 					<SettingsSection title={t`Security Settings`}>
 						<SettingsNavRow