feat: complete media usage tracking setup

.changeset/fast-media-usage-backfill.md

@@ -0,0 +1,5 @@
+---
+"emdash": patch
+---
+
+Speeds up the initial scan when administrators turn on media usage tracking on Cloudflare Workers and Node.js.

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

@@ -0,0 +1,6 @@
+---
+"emdash": minor
+"@emdash-cms/admin": minor
+---
+
+Adds a media usage tracking setting. Tracking is enabled during initial setup. Existing sites enable it from Settings, keep the page open while EmDash scans existing content, and can return later to continue from saved progress.

.changeset/remove-media-usage-scheduled-recovery.md

@@ -0,0 +1,14 @@
+---
+"emdash": minor
+"@emdash-cms/cloudflare": minor
+---
+
+Removes scheduled media usage recovery. Media usage tracking now advances only while an administrator keeps its settings page visible. This breaks Cloudflare deployments that configure `mediaUsageCron` and Node.js integrations that provide a custom `CronScheduler`.
+
+#### What should I do?
+
+On Cloudflare, remove the dedicated media usage Cron Trigger and the `mediaUsageCron` option. Keep the general Cron Trigger unchanged; no replacement trigger is required.
+
+If you provide a custom Node.js scheduler, remove `setMediaUsageMaintenance()`. A custom `CronScheduler` now implements only `start()`, `stop()`, `reschedule()`, and `setSystemCleanup()`.
+
+Keep **Settings → Media usage tracking** open until it shows **Ready**. If the page closes, return to continue from saved progress.

demos/cloudflare/wrangler.jsonc

@@ -34,9 +34,9 @@
 			"bucket_name": "emdash-media",
 		},
 	],
-	// Cron trigger drives the AI Search reindex queue flush.
+	// Cron triggers drive general maintenance.
 	"triggers": {
-		"crons": ["* * * * *", "*/2 * * * *"],
+		"crons": ["* * * * *"],
 	},
 	// Observability
 	"observability": {

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

@@ -94,9 +94,11 @@ If the database is empty (no collections) and the setup wizard hasn't been compl
 
 To change the schema or content model of a site that is already deployed, see [Evolving a Deployed Site](/deployment/schema-evolution/).
 
-## Scheduled Publishing
+## Scheduled tasks
 
-On Cloudflare Workers, scheduled publishing, plugin cron, and maintenance tasks run from Worker Cron Triggers. New Cloudflare templates include both required schedules automatically. When updating an existing project, configure distinct general and Media Usage lanes:
+Cloudflare runs scheduled publishing, plugin tasks, and general maintenance from one Cron Trigger.
+
+Use the standard Worker entry point:
 
 ```ts title="src/worker.ts"
 import handler, {
@@ -112,28 +114,18 @@ export default {
 } satisfies ExportedHandler;
 ```
 
-By default, `*/2 * * * *` runs Media Usage maintenance and every other expression runs general maintenance. Then add both Cron Triggers to `wrangler.jsonc`:
+Configure one Cron Trigger for general maintenance in `wrangler.jsonc`:
 
 ```jsonc title="wrangler.jsonc"
 {
 	"triggers": {
-		"crons": ["* * * * *", "*/2 * * * *"],
+		"crons": ["* * * * *"],
 	},
 }
 ```
 
-To use different schedules, set the corresponding `generalCron` or `mediaUsageCron` option in `createScheduledHandler()` and use the same expression in `wrangler.jsonc`.
-
-<Aside type="caution">
-	Without the general trigger, scheduled publishing and plugin cron do not run. Without the dedicated Media Usage trigger, automatic historical reconciliation cannot progress. Local `astro dev` still uses the in-process scheduler.
-</Aside>
-
-### 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.
+To use a different general maintenance schedule, set `generalCron` in `createScheduledHandler()` and
+use the same expression in `wrangler.jsonc`.
 
 ## Deploy
 

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

@@ -53,20 +53,11 @@ export default defineConfig({
 
 The server runs on `http://localhost:4321` by default. Migrations are applied on the first request. If the database is empty and setup hasn't been completed, your seed file (or the built-in default if you don't have one) is also applied on that first request.
 
-## Scheduled Tasks
+## Scheduled tasks
 
-The built-in scheduler runs only while a Node process is running. It handles scheduled publishing,
-plugin tasks, and background media indexing.
+The built-in scheduler runs only while a Node.js process is running. It handles scheduled publishing, plugin tasks, and general maintenance.
 
-Keep at least one Node process running continuously in production. If all processes stop or sleep,
-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.js process running continuously in production. Scheduled tasks pause when every process stops or sleeps.
 
 ## Production Storage
 

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

@@ -15,6 +15,26 @@ and files that are not assigned to a folder. Open a folder to see its files.
 
 <img src={mediaLibraryImg.src} alt="EmDash media library showing image grid with upload button" />
 
+## Used in
+
+Open a file in EmDash's media library to see the content entries that reference it. While EmDash scans existing content, the list includes the references found so far and may be incomplete.
+
+### Turn on media usage tracking
+
+If media usage tracking is off, an administrator can turn it on:
+
+1. Finish any content edits. If another application writes directly to the content database, pause it and wait for any writes in progress to finish.
+2. Open **Settings → Media usage tracking**, select **Enable tracking**, then confirm.
+3. When the page shows **Indexing existing content**, editing and other database writes can resume.
+4. Keep the page open until it shows **Ready**. If you leave, return to continue from saved progress.
+
+Once media usage tracking is on, it cannot be turned off.
+
+<Aside type="caution">
+	The **Used in** list checks supported references in EmDash content. It does not inspect custom code
+	or external sites, so an empty list does not prove that a file is safe to delete.
+</Aside>
+
 ## Uploading Files
 
 ### From the Media Library

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

@@ -261,12 +261,12 @@ collections:
 | `stale`    | Indexed coverage is outdated                                           |
 | `unknown`  | Stored coverage contains a state this version does not recognize        |
 
-Only `complete` supports a scoped complete-zero statement within the EmDash-managed fields
+Only `complete` supports a scoped complete-zero statement within the supported fields
 described below. Counts with any other status are indexed projections and may over-report or
 under-report. Even complete results are advisory during concurrent writes; usage reads are not a
 transactional lock and must not be used as a deletion guarantee.
 
-### Get Media Usage Details
+### Get media usage details
 
 ```http
 GET /_emdash/api/media/:id/usage?limit=50&cursor=...
@@ -320,7 +320,7 @@ trashed entry. Sources are `columns` or `draft_overlay`; occurrences identify th
 and path without exposing internal index metadata.
 
 Media usage covers local media references in top-level image and file fields, repeater image
-fields, and Portable Text image blocks managed by EmDash content collections. It does not scan
+fields, and Portable Text image blocks stored in EmDash content collections. It does not scan
 custom code, rendered HTML, settings, menus, widgets, plugin-private data, external sites, or
 provider-only assets.
 
@@ -606,13 +606,14 @@ IDs or URLs, or change media usage records.
 DELETE /_emdash/api/media/:id
 ```
 
-### Enable automatic media usage indexing
+### Enable media usage tracking
 
-Automatic media usage indexing must be enabled once for each production site. Writes must be
-paused while EmDash prepares each collection so that no changes are missed.
+Sites with media usage tracking off must turn it on once. Pause direct database writes while EmDash prepares each collection. EmDash temporarily blocks its own content and schema writes during this step.
 
 Both endpoints require `schema:manage`. Bearer tokens also require the `admin` scope.
 
+For the admin procedure, see [Turn on media usage tracking](/guides/media-library/#turn-on-media-usage-tracking). The endpoints below provide the same procedure for API operators.
+
 #### Check the current state
 
 ```http
@@ -621,57 +622,97 @@ GET /_emdash/api/admin/media-usage/activation
 
 This request does not change anything. It returns one of these states:
 
-- `expanded`: automatic indexing is not enabled.
+- `expanded`: media usage tracking is off.
 - `activating`: EmDash is preparing the site's collections.
 - `active`: EmDash tracks changes to media references in content.
 
 Status responses do not include internal lock data or raw database errors.
 
-#### Prepare the next collection
+#### Start activation
 
 ```http
 POST /_emdash/api/admin/media-usage/activation
 Content-Type: application/json
 X-EmDash-Request: 1
 
 {
-	"writersDrained": true,
-	"maintenanceReady": true
+	"writersDrained": true
 }
 ```
 
-Each request prepares one collection. Send one request at a time until the state becomes `active`.
-
-Set both fields to `true`:
+The request prepares at most one collection. After it succeeds, advance setup and historical indexing through the progress endpoint below.
 
-- `writersDrained`: Application and direct database writes have stopped, and any writes already in
-  progress have finished.
-- `maintenanceReady`: Scheduled background tasks are running through `mediaUsageCron` on Cloudflare
-  or the built-in scheduler on Node.js.
+Set `writersDrained` to `true` after application and direct database writes have stopped and any writes already in progress have finished.
 
-#### Enable indexing in production
+#### Enable tracking with the API
 
-1. Confirm that scheduled background tasks are running: `mediaUsageCron` on Cloudflare, or the
-   built-in scheduler on Node.js.
-2. Stop all application and direct database writes. Wait for writes already in progress to finish.
-3. Call `GET` to check the current state.
-4. Call `POST` one request at a time until the state becomes `active`.
-5. Resume writes.
-6. Keep scheduled background tasks running while EmDash indexes existing content.
+1. Stop all direct database writers. Wait for writes already in progress to finish. EmDash fences its own writes during setup.
+2. Call the activation `GET` endpoint to check the current state.
+3. Call the activation `POST` endpoint once with `writersDrained: true`.
+4. Call the progress `POST` endpoint serially, following `nextRequestInMs`, until activation becomes `active`.
+5. Resume direct database writes after activation becomes `active`.
+6. Continue progress requests until historical indexing reports `ready` and `nextRequestInMs` is `null`.
 
-If `POST` times out or returns `409` or `500`, call `GET` before sending another request. If
-`lastErrorCode` is set, keep writes stopped, check the application logs, fix the problem, and try
-again. Do not edit EmDash's internal database tables.
+If `POST` times out or returns `409` or `500`, call `GET` before deciding what to do. If the state is
+still `activating` without `lastErrorCode`, another request may own the current batch. If `lastErrorCode` is set, keep writes stopped, check the application logs, fix the
+problem, and send one confirmed POST to retry. Do not edit EmDash's internal database tables.
 
 <Aside type="caution">
 	After this process starts, it cannot be cancelled or reset. Test it in a staging environment and
 	follow your normal database backup policy before using it in production.
 </Aside>
 
-When the state is `active`, EmDash tracks changes to media references in content. Existing content
-may still be indexing in the background.
+When the state is `active`, EmDash tracks changes to media references in content. Existing content may still need progress requests before historical indexing is ready.
+
+#### 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. The endpoint does not inspect content rows or return
+work-item details. It requires `schema:manage`; bearer tokens also require the `admin` scope.
+
+#### Advance setup and historical indexing
+
+```http
+POST /_emdash/api/admin/media-usage/progress
+X-EmDash-Request: 1
+```
+
+The request has no body. It runs one bounded maintenance step and returns the stored activation and progress state after that step.
+
+```json
+{
+	"success": true,
+	"data": {
+		"activation": {
+			"state": "active",
+			"collectionCursor": null,
+			"attemptCount": 2,
+			"drainConfirmedAt": "2026-08-24T12:00:00.000Z",
+			"lastAttemptedAt": "2026-08-24T12:00:01.000Z",
+			"lastErrorCode": null,
+			"leaseExpiresAt": null,
+			"activatedAt": "2026-08-24T12:00:01.000Z",
+			"updatedAt": "2026-08-24T12:00:02.000Z"
+		},
+		"progress": {
+			"status": "indexing",
+			"readyCollections": 1,
+			"totalCollections": 2
+		},
+		"nextRequestInMs": 0
+	}
+}
+```
+
+`progress` is `null` until activation is active. `nextRequestInMs` is `0` for an immediate successor, `30000` for a delayed retry, or `null` when the server knows of no successor. Send only one progress request at a time and wait for the returned delay.
+
+Closing the client does not discard completed work, but it stops future requests. To resume, read activation first, read progress when activation is active, then continue progress requests. After an ambiguous response, perform the same reads before retrying.
 
-### List Media Usage Work
+### List media usage work
 
 ```http
 GET /_emdash/api/admin/media-usage/work?collection=posts&state=failed&limit=50&cursor=...
@@ -710,7 +751,7 @@ page's `nextCursor`. The endpoint does not calculate an exact backlog count.
 Responses omit work versions, lease tokens, raw database errors, indexed content, media
 references, and exact counts.
 
-### Retry Media Usage Work
+### Retry media usage work
 
 ```http
 POST /_emdash/api/admin/media-usage/work/retry
@@ -735,9 +776,8 @@ replaces newer work or exposes its lease token.
 
 The list returns only known durable work. Retry can create work for the supplied identity in an
 active collection even when no work row exists, but it does not scan for historical gaps. Use
-collection-scoped Media Usage repair after imports or direct database writes.
-When scheduled maintenance is disabled, failed jobs remain visible and manually retryable, but no
-automatic freshness deadline is promised.
+collection-scoped media usage repair after imports or direct database writes.
+Failed jobs remain visible and manually retryable. A `needs_attention` progress state stops automatic requests from the media usage tracking settings page until the underlying failure is resolved.
 
 ### Recover Collection Deletion
 
@@ -763,7 +803,7 @@ returns `409 WORK_LEASE_ACTIVE`; a concurrent state change returns `409 WORK_CHA
 require `schema:manage`, and bearer tokens also require the `admin` scope. They recover internal
 index cleanup only and never delete media assets.
 
-### Repair Media Usage
+### Repair media usage
 
 ```http
 POST /_emdash/api/admin/media-usage/repair

e2e/tests/setup-wizard.spec.ts

@@ -58,6 +58,7 @@ test.describe("Setup Wizard", () => {
 	test("shows validation error when title is empty", async ({ admin }) => {
 		await admin.goToSetup();
 
+		await admin.page.getByLabel("Site Title").fill("");
 		await admin.page.getByRole("button", { name: "Continue" }).click();
 
 		await expect(admin.page.locator("text=Site title is required")).toBeVisible();