@agent-native/core 0.90.1 → 0.90.3

package/corpus/templates/clips/server/routes/api/uploads/[recordingId]/abort.post.ts

@@ -6,10 +6,12 @@
  */
 
 import {
+  readAppState,
   writeAppState,
   deleteAppStateByPrefix,
 } from "@agent-native/core/application-state";
 import { runWithRequestContext } from "@agent-native/core/server";
+import { isStoredButUnservableFinalizeError } from "@shared/finalize-recovery.js";
 import { and, eq } from "drizzle-orm";
 import {
   defineEventHandler,
@@ -50,6 +52,7 @@ export default defineEventHandler(async (event: H3Event) => {
         id: schema.recordings.id,
         status: schema.recordings.status,
         videoUrl: schema.recordings.videoUrl,
+        failureReason: schema.recordings.failureReason,
       })
       .from(schema.recordings)
       .where(
@@ -68,18 +71,17 @@ export default defineEventHandler(async (event: H3Event) => {
       return { ok: true, recordingId, alreadyReady: true, chunksCleared: 0 };
     }
 
+    const preserveRecoveryState =
+      isStoredButUnservableFinalizeError(failureReason) ||
+      isStoredButUnservableFinalizeError(existing.failureReason);
+
     // Already a terminal failure (e.g. a duplicate/retried abort call, or
     // finalize's own failChunkAssembly already flipped it) — no-op instead of
     // re-clearing chunk state and overwriting the original failureReason.
-    if (existing.status === "failed") {
+    if (existing.status === "failed" && !preserveRecoveryState) {
       return { ok: true, recordingId, alreadyFailed: true, chunksCleared: 0 };
     }
 
-    const cleared = await deleteAppStateByPrefix(
-      `recording-chunks-${recordingId}-`,
-    );
-    await deleteResumableSession(recordingId).catch(() => {});
-
     const now = new Date().toISOString();
     await db
       .update(schema.recordings)
@@ -90,12 +92,27 @@ export default defineEventHandler(async (event: H3Event) => {
       })
       .where(eq(schema.recordings.id, recordingId));
 
+    const existingUploadStateRaw = await readAppState(
+      `recording-upload-${recordingId}`,
+    ).catch(() => null);
+    const existingUploadState =
+      existingUploadStateRaw && typeof existingUploadStateRaw === "object"
+        ? (existingUploadStateRaw as Record<string, unknown>)
+        : {};
     await writeAppState(`recording-upload-${recordingId}`, {
+      ...existingUploadState,
       recordingId,
       status: "failed",
       failureReason,
       updatedAt: now,
     });
+
+    const cleared = preserveRecoveryState
+      ? 0
+      : await deleteAppStateByPrefix(`recording-chunks-${recordingId}-`);
+    if (!preserveRecoveryState) {
+      await deleteResumableSession(recordingId).catch(() => {});
+    }
     await writeAppState("refresh-signal", { ts: Date.now() });
 
     return { ok: true, recordingId, chunksCleared: cleared };

package/corpus/templates/clips/server/routes/api/uploads/[recordingId]/chunk.post.ts

@@ -375,7 +375,11 @@ export default defineEventHandler(async (event: H3Event) => {
 
     // Only persist non-empty chunks. The final sentinel can legitimately be
     // empty — writing a zero-byte chunk would just clutter application_state.
+    // Check for abort/failure before writing so parallel in-flight requests
+    // don't recreate scratch chunk rows after /abort already cleared them.
     if (bytes.byteLength > 0) {
+      const failedBeforeWrite = await stopIfUploadFailed();
+      if (failedBeforeWrite) return failedBeforeWrite;
       // Pad index to 6 digits so string-sort order matches numeric order if the
       // finalize path ever sorts lexically. (finalize also parses back to a number.)
       const paddedIndex = String(index).padStart(6, "0");
@@ -409,15 +413,25 @@ export default defineEventHandler(async (event: H3Event) => {
 
     // Update upload progress (best-effort). If total is unknown we treat it as
     // indeterminate and keep progress at its last known value.
+    // Chunks may arrive out of order when uploaded in parallel, so take the
+    // max of the current persisted value and the incoming index to keep
+    // progress monotonically non-decreasing.
     if (total > 0) {
       const failedResponse = await stopIfUploadFailed();
       if (failedResponse) return failedResponse;
-      const progress = Math.min(100, Math.round(((index + 1) / total) * 100));
+      const chunksReceived = Math.max(
+        stateNumber(uploadState, "chunksReceived") ?? 0,
+        index + 1,
+      );
+      const progress = Math.max(
+        stateNumber(uploadState, "progress") ?? 0,
+        Math.min(100, Math.round((chunksReceived / total) * 100)),
+      );
       await writeAppState(`recording-upload-${recordingId}`, {
         recordingId,
         status: isFinal ? "processing" : "uploading",
         progress,
-        chunksReceived: index + 1,
+        chunksReceived,
         totalChunks: total,
         ...(expectedDataChunks !== undefined
           ? {
@@ -449,7 +463,10 @@ export default defineEventHandler(async (event: H3Event) => {
       await writeAppState(`recording-upload-${recordingId}`, {
         recordingId,
         status: isFinal ? "processing" : "uploading",
-        chunksReceived: index + 1,
+        chunksReceived: Math.max(
+          stateNumber(uploadState, "chunksReceived") ?? 0,
+          index + 1,
+        ),
         ...(expectedDataChunks !== undefined
           ? {
               expectedDataChunks,
@@ -579,7 +596,15 @@ export default defineEventHandler(async (event: H3Event) => {
             updatedAt: new Date().toISOString(),
           })
           .where(eq(schema.recordings.id, recordingId));
+        const failedUploadStateRaw = await readAppState(
+          `recording-upload-${recordingId}`,
+        ).catch(() => null);
+        const failedUploadState =
+          failedUploadStateRaw && typeof failedUploadStateRaw === "object"
+            ? (failedUploadStateRaw as Record<string, unknown>)
+            : {};
         await writeAppState(`recording-upload-${recordingId}`, {
+          ...failedUploadState,
           recordingId,
           status: "failed",
           failureReason: err instanceof Error ? err.message : "Finalize failed",

package/corpus/templates/clips/server/routes/api/video/[recordingId].get.ts

@@ -177,13 +177,13 @@ function rememberCompressedBuilderMediaMiss(compressedSourceUrl: string): void {
 function shouldFallbackToOriginalMedia(
   upstream: Response | { error: string; status: number },
 ): boolean {
-  return [403, 404, 416].includes(upstream.status);
+  return upstream.status >= 500 || [403, 404, 416].includes(upstream.status);
 }
 
 function shouldRememberCompressedBuilderMediaMiss(
   upstream: Response | { error: string; status: number },
 ): boolean {
-  return [403, 404].includes(upstream.status);
+  return upstream.status >= 500 || [403, 404].includes(upstream.status);
 }
 
 async function fetchProviderMedia(
@@ -497,10 +497,17 @@ export default defineEventHandler(async (event: H3Event) => {
             compressedSourceUrl &&
             !shouldSkipCompressedBuilderMediaProbe(compressedSourceUrl)
           ) {
-            upstream = await fetchProviderMedia(
-              compressedSourceUrl,
-              rangeHeader,
-            );
+            try {
+              upstream = await fetchProviderMedia(
+                compressedSourceUrl,
+                rangeHeader,
+              );
+            } catch (err) {
+              upstream = {
+                status: statusCodeForProviderFetchError(err),
+                error: messageForProviderFetchError(err),
+              };
+            }
             if (shouldRememberCompressedBuilderMediaMiss(upstream)) {
               rememberCompressedBuilderMediaMiss(compressedSourceUrl);
             }

package/corpus/templates/clips/shared/finalize-recovery.ts

@@ -26,8 +26,38 @@ const DEFAULT_READY_RECOVERY_TIMEOUT_MS = 90_000;
 const DEFAULT_READY_RECOVERY_INTERVAL_MS = 3_000;
 const DEFAULT_READY_RECOVERY_FETCH_TIMEOUT_MS = 2_000;
 
-function sleep(ms: number): Promise<void> {
-  return new Promise((resolve) => setTimeout(resolve, ms));
+function sleep(ms: number, signal?: AbortSignal): Promise<void> {
+  return new Promise((resolve, reject) => {
+    if (signal?.aborted) {
+      reject(
+        signal.reason instanceof Error ? signal.reason : new Error("Aborted"),
+      );
+      return;
+    }
+    const timer = setTimeout(resolve, ms);
+    signal?.addEventListener(
+      "abort",
+      () => {
+        clearTimeout(timer);
+        reject(
+          signal.reason instanceof Error ? signal.reason : new Error("Aborted"),
+        );
+      },
+      { once: true },
+    );
+  });
+}
+
+export function isStoredButUnservableFinalizeError(value: unknown): boolean {
+  const message =
+    typeof value === "string"
+      ? value
+      : value instanceof Error
+        ? value.message
+        : value && typeof value === "object" && "message" in value
+          ? String((value as { message?: unknown }).message ?? "")
+          : "";
+  return /\bstored-but-unservable\b/i.test(message);
 }
 
 function absoluteUploadUrl(uploadUrl: string): URL {
@@ -157,9 +187,10 @@ export async function waitForReadyRecordingAfterFinalizeError(args: {
   timeoutMs?: number;
   intervalMs?: number;
   fetchTimeoutMs?: number;
+  signal?: AbortSignal;
 }): Promise<RecoveredReadyRecording | null> {
   const fetchImpl = args.fetchImpl ?? fetch;
-  const sleepImpl = args.sleepImpl ?? sleep;
+  const sleepImpl = args.sleepImpl ?? ((ms) => sleep(ms, args.signal));
   const timeoutMs = Math.max(
     1,
     args.timeoutMs ?? DEFAULT_READY_RECOVERY_TIMEOUT_MS,
@@ -182,6 +213,7 @@ export async function waitForReadyRecordingAfterFinalizeError(args: {
   }
 
   for (let attempt = 0; attempt < attempts; attempt += 1) {
+    if (args.signal?.aborted) return null;
     const urls = authenticatedUrl
       ? [
           { url: authenticatedUrl, authenticated: true },

package/corpus/templates/content/AGENTS.md

@@ -87,58 +87,58 @@ cd templates/content && pnpm action <name> [args]
 
 ### Document Operations
 
-| Action                                      | Args                                                                                                                                                           | Purpose                                                                                                                                 |
-| ------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
-| `list-documents`                            | `[--format json]`                                                                                                                                              | List document metadata/tree; no full bodies                                                                                             |
-| `export-content-source`                     | `[--format json]`                                                                                                                                              | Export editable docs as `content/*.mdx` source files                                                                                    |
-| `import-content-source`                     | `--files <json> [--dryRun true\|false]`                                                                                                                        | Import `.md`/`.mdx` source files into editable docs                                                                                     |
-| `list-builder-docs`                         | `[--model docs-content\|blog-article] [--limit <n>]`                                                                                                           | List Builder docs/blog entries available for `.builder.mdx` pull                                                                        |
-| `pull-builder-doc`                          | `--model <model> --entryId <builder-entry-id> [--dryRun true\|false]`                                                                                          | Pull one Builder entry into Content and return `.builder.mdx` plus `content/builder/.raw` sidecar files                                 |
-| `check-builder-doc`                         | `--files <json> [--path <file.builder.mdx>]` or `--documentId <id>`                                                                                            | Validate Builder MDX round-trip, sidecar hashes, and remote conflict status before push                                                 |
-| `push-builder-doc`                          | `--files <json> [--path <file.builder.mdx>] [--dryRun true\|false]`                                                                                            | Guarded Builder autosave PATCH for the safe Builder test model; never publishes                                                         |
-| `navigate`                                  | `--path <path>` or `--documentId <id>` or `--databaseId <id>`                                                                                                  | Open a route, document page, or database page in the UI                                                                                 |
-| `search-documents`                          | `--query <text> [--format json]`                                                                                                                               | Search by title/content and return snippets                                                                                             |
-| `get-document`                              | `--id <id> [--format json]`                                                                                                                                    | Get a single document with content                                                                                                      |
-| `pull-document`                             | `--id <id> [--format markdown\|text]`                                                                                                                          | Collab-aware "ingest the final" read                                                                                                    |
-| `create-document`                           | `--title <text> [--content] [--parentId] [--icon]`                                                                                                             | Create a new document                                                                                                                   |
-| `edit-document`                             | `--id <id> --find <text> --replace <text>`                                                                                                                     | Surgical text edit (preferred for modifications)                                                                                        |
-| `edit-document`                             | `--id <id> --edits <json>`                                                                                                                                     | Batch surgical text edits                                                                                                               |
-| `update-document`                           | `--id <id> [--title] [--content] [--icon]`                                                                                                                     | Full rewrite of document fields                                                                                                         |
-| `share-local-file-document`                 | `--id <local-file-document-id>`                                                                                                                                | Create or refresh a DB-backed shareable copy of a local file document                                                                   |
-| `remove-local-file-source`                  | `[--sourceRootPath <path>]`                                                                                                                                    | Unlink local-file sources from Content without deleting local Markdown/MDX files                                                        |
-| `list-local-component-files`                |                                                                                                                                                                | List registered local MDX component source files                                                                                        |
-| `write-local-component-file`                | `--workspaceId <id> --path <relative-component-path> --content <source>`                                                                                       | Create or update a file in a registered local `components/` folder                                                                      |
-| `create-content-database`                   | `[--documentId <id>] [--parentId <id>] [--title <text>]`                                                                                                       | Create a database page or convert an existing page into a database                                                                      |
-| `create-inline-content-database`            | `--hostDocumentId <id> [--title <text>]`                                                                                                                       | Create a database owned by an inline database block in the host document                                                                |
-| `get-content-database`                      | `--databaseId <id>` or `--documentId <id>`                                                                                                                     | Get a database table with property schema and item pages                                                                                |
-| `list-trashed-content-databases`            |                                                                                                                                                                | List soft-deleted databases visible in the sidebar Trash surface                                                                        |
-| `restore-content-database`                  | `--databaseId <id>`                                                                                                                                            | Restore a soft-deleted database from the sidebar Trash surface                                                                          |
-| `get-content-database-source`               | `--databaseId <id>` or `--documentId <id>`                                                                                                                     | Inspect local/no-source or source-backed status, mappings, row identity, freshness, and change sets                                     |
-| `attach-content-database-source`            | `--databaseId <id>` or `--documentId <id> [--sourceType mock\|builder-cms] [--sourceName] [--sourceTable] [--relationshipMode items\|details] [--join <json>]` | Attach a source binding; use `items` to add more rows and `details` to match a source onto existing rows                                |
-| `change-content-database-source-role`       | `--databaseId <id>` or `--documentId <id> --sourceId <id> --relationshipMode items\|details [--join <json>]`                                                   | Change an attached source between adding rows and adding matched detail columns without removing the source                             |
-| `refresh-content-database-source`           | `--databaseId <id>` or `--documentId <id>`                                                                                                                     | Refresh the read-only source status envelope; Builder CMS reads live entries only when configured                                       |
-| `process-builder-body-hydration`            | `--sourceId <id> [--documentId <id>] [--limit <n>]`                                                                                                            | Hydrate queued Builder article bodies into readable Content markdown with preserved source-component markers                            |
-| `set-content-database-source-write-mode`    | `--databaseId <id>` or `--documentId <id> --liveWritesEnabled true\|false [--allowedWriteModes <json>]`                                                        | Enable/disable per-source Builder live writes; enabling is allowed only for `agent-native-blog-article-test` with explicit modes        |
-| `stage-builder-revision`                    | `--databaseId <id>` or `--documentId <id>`                                                                                                                     | Stage pending local Builder CMS changes as a local-only save-revision record; never calls Builder                                       |
-| `review-content-database-source-change-set` | `--databaseId <id>` or `--documentId <id> --changeSetId <id> --decision approve\|reject [--note]`                                                              | Approve or reject a local source change-set review record without provider writes                                                       |
-| `prepare-builder-source-execution`          | `--databaseId <id>` or `--documentId <id> --changeSetId <id> [--pushModeConfirmation autosave\|draft\|publish]`                                                | Prepare a dry-run Builder execution gate for approved field/body changes with request semantics/idempotency key; never calls Builder    |
-| `validate-builder-source-execution`         | `--databaseId <id>` or `--documentId <id> --changeSetId <id> [--idempotencyKey <key>]`                                                                         | Validate/replay a prepared Builder execution gate locally as a dry run; never calls Builder                                             |
-| `execute-builder-source-execution`          | `--databaseId <id>` or `--documentId <id> --changeSetId <id> [--idempotencyKey <key>] [--pushModeConfirmation autosave\|draft\|publish]`                       | Execute a guarded live Builder write only when approved, validated, enabled, idempotent, and targeting `agent-native-blog-article-test` |
-| `add-database-item`                         | `--databaseId <id> [--title <text>] [--propertyValues <json>]`                                                                                                 | Add a page row to a database, optionally seeding property values                                                                        |
-| `duplicate-database-item`                   | `--itemId <id>` or `--documentId <id> [--title <text>]`                                                                                                        | Duplicate exactly one database row page and its stored property values; for two or more rows, use `duplicate-database-items` once       |
-| `duplicate-database-items`                  | `--databaseId <id>` or `--documentId <databaseDocumentId> --itemIds <json-array>` or `--documentIds <json-array>`                                              | Preferred multi-row duplicate action; duplicate multiple database row pages atomically and return ordered duplicate item/document IDs   |
-| `delete-database-items`                     | `--databaseId <id>` or `--documentId <databaseDocumentId> --itemIds <json-array>` or `--documentIds <json-array>`                                              | Preferred multi-row delete action; delete multiple database row pages atomically while preserving `delete-document` admin semantics     |
-| `move-database-item`                        | `--itemId <id>` or `--documentId <id> --position <number>`                                                                                                     | Move a database row page to a new zero-based table position                                                                             |
-| `update-content-database-view`              | `--databaseId <id> --viewConfig <json>`                                                                                                                        | Persist database views, sorts, filters, hidden properties, and view settings                                                            |
-| `list-document-properties`                  | `--documentId <id> [--format json]`                                                                                                                            | List Notion-style property definitions and values for a document                                                                        |
-| `configure-document-property`               | `--documentId <id> [--id <propertyId>] --name <name> --type <type> [--visibility always_show\|hide_when_empty\|always_hide]`                                   | Create or update a property definition                                                                                                  |
-| `duplicate-document-property`               | `--documentId <id> --propertyId <propertyId>`                                                                                                                  | Duplicate a property definition and its stored values                                                                                   |
-| `delete-document-property`                  | `--documentId <id> --propertyId <propertyId>`                                                                                                                  | Delete a property definition and its stored values                                                                                      |
-| `set-document-property`                     | `--documentId <id> --propertyId <propertyId> --value <json>`                                                                                                   | Set a document property value (for a `blocks` field, the value is its markdown content)                                                 |
-| `reorder-document-property`                 | `--documentId <id> --propertyId <propertyId> --targetPropertyId <id> [--position before\|after]`                                                               | Reorder a property definition within its database (used to reorder Blocks fields on the page)                                           |
-| `set-document-discoverability`              | `--id <id> --hideFromSearch true\|false [--includeChildren true\|false]`                                                                                       | Hide/show an org-accessible document in Organization/search while keeping link access                                                   |
-| `move-document`                             | `--id <id> [--parentId] [--position]`                                                                                                                          | Move or reorder a document in the page tree                                                                                             |
-| `delete-document`                           | `--id <id>`                                                                                                                                                    | Delete with recursive children                                                                                                          |
+| Action                                      | Args                                                                                                                                                           | Purpose                                                                                                                                                  |
+| ------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `list-documents`                            | `[--format json]`                                                                                                                                              | List document metadata/tree; no full bodies                                                                                                              |
+| `export-content-source`                     | `[--format json]`                                                                                                                                              | Export editable docs as `content/*.mdx` source files                                                                                                     |
+| `import-content-source`                     | `--files <json> [--dryRun true\|false]`                                                                                                                        | Import `.md`/`.mdx` source files into editable docs                                                                                                      |
+| `list-builder-docs`                         | `[--model docs-content\|blog-article] [--limit <n>]`                                                                                                           | List Builder docs/blog entries available for `.builder.mdx` pull                                                                                         |
+| `pull-builder-doc`                          | `--model <model> --entryId <builder-entry-id> [--dryRun true\|false]`                                                                                          | Pull one Builder entry into Content and return `.builder.mdx` plus `content/builder/.raw` sidecar files                                                  |
+| `check-builder-doc`                         | `--files <json> [--path <file.builder.mdx>]` or `--documentId <id>`                                                                                            | Validate Builder MDX round-trip, sidecar hashes, and remote conflict status before push                                                                  |
+| `push-builder-doc`                          | `--files <json> [--path <file.builder.mdx>] [--dryRun true\|false]`                                                                                            | Guarded Builder autosave PATCH for the safe Builder test model; never publishes                                                                          |
+| `navigate`                                  | `--path <path>` or `--documentId <id>` or `--databaseId <id>`                                                                                                  | Open a route, document page, or database page in the UI                                                                                                  |
+| `search-documents`                          | `--query <text> [--format json]`                                                                                                                               | Search by title/content and return snippets                                                                                                              |
+| `get-document`                              | `--id <id> [--format json]`                                                                                                                                    | Get a single document with content                                                                                                                       |
+| `pull-document`                             | `--id <id> [--format markdown\|text]`                                                                                                                          | Collab-aware "ingest the final" read                                                                                                                     |
+| `create-document`                           | `--title <text> [--content] [--parentId] [--icon]`                                                                                                             | Create a new document                                                                                                                                    |
+| `edit-document`                             | `--id <id> --find <text> --replace <text>`                                                                                                                     | Surgical text edit (preferred for modifications)                                                                                                         |
+| `edit-document`                             | `--id <id> --edits <json>`                                                                                                                                     | Batch surgical text edits                                                                                                                                |
+| `update-document`                           | `--id <id> [--title] [--content] [--icon]`                                                                                                                     | Full rewrite of document fields                                                                                                                          |
+| `share-local-file-document`                 | `--id <local-file-document-id>`                                                                                                                                | Create or refresh a DB-backed shareable copy of a local file document                                                                                    |
+| `remove-local-file-source`                  | `[--sourceRootPath <path>]`                                                                                                                                    | Unlink local-file sources from Content without deleting local Markdown/MDX files                                                                         |
+| `list-local-component-files`                |                                                                                                                                                                | List registered local MDX component source files                                                                                                         |
+| `write-local-component-file`                | `--workspaceId <id> --path <relative-component-path> --content <source>`                                                                                       | Create or update a file in a registered local `components/` folder                                                                                       |
+| `create-content-database`                   | `[--documentId <id>] [--parentId <id>] [--title <text>]`                                                                                                       | Create a database page or convert an existing page into a database                                                                                       |
+| `create-inline-content-database`            | `--hostDocumentId <id> [--title <text>]`                                                                                                                       | Create a database owned by an inline database block in the host document                                                                                 |
+| `get-content-database`                      | `--databaseId <id>` or `--documentId <id>`                                                                                                                     | Get a database table with property schema and item pages                                                                                                 |
+| `list-trashed-content-databases`            |                                                                                                                                                                | List soft-deleted databases visible in the sidebar Trash surface                                                                                         |
+| `restore-content-database`                  | `--databaseId <id>`                                                                                                                                            | Restore a soft-deleted database from the sidebar Trash surface                                                                                           |
+| `get-content-database-source`               | `--databaseId <id>` or `--documentId <id>`                                                                                                                     | Inspect local/no-source or source-backed status, mappings, row identity, freshness, and change sets                                                      |
+| `attach-content-database-source`            | `--databaseId <id>` or `--documentId <id> [--sourceType mock\|builder-cms] [--sourceName] [--sourceTable] [--relationshipMode items\|details] [--join <json>]` | Attach a source binding; use `items` to add more rows and `details` to match a source onto existing rows                                                 |
+| `change-content-database-source-role`       | `--databaseId <id>` or `--documentId <id> --sourceId <id> --relationshipMode items\|details [--join <json>]`                                                   | Change an attached source between adding rows and adding matched detail columns without removing the source                                              |
+| `refresh-content-database-source`           | `--databaseId <id>` or `--documentId <id>`                                                                                                                     | Refresh the read-only source status envelope; large Builder CMS sources may return a partial fetch, and another refresh continues loading remaining rows |
+| `process-builder-body-hydration`            | `--sourceId <id> [--documentId <id>] [--limit <n>]`                                                                                                            | Hydrate queued Builder article bodies into readable Content markdown with preserved source-component markers                                             |
+| `set-content-database-source-write-mode`    | `--databaseId <id>` or `--documentId <id> --liveWritesEnabled true\|false [--allowedWriteModes <json>]`                                                        | Enable/disable per-source Builder live writes; enabling is allowed only for `agent-native-blog-article-test` with explicit modes                         |
+| `stage-builder-revision`                    | `--databaseId <id>` or `--documentId <id>`                                                                                                                     | Stage pending local Builder CMS changes as a local-only save-revision record; never calls Builder                                                        |
+| `review-content-database-source-change-set` | `--databaseId <id>` or `--documentId <id> --changeSetId <id> --decision approve\|reject [--note]`                                                              | Approve or reject a local source change-set review record without provider writes                                                                        |
+| `prepare-builder-source-execution`          | `--databaseId <id>` or `--documentId <id> --changeSetId <id> [--pushModeConfirmation autosave\|draft\|publish]`                                                | Prepare a dry-run Builder execution gate for approved field/body changes with request semantics/idempotency key; never calls Builder                     |
+| `validate-builder-source-execution`         | `--databaseId <id>` or `--documentId <id> --changeSetId <id> [--idempotencyKey <key>]`                                                                         | Validate/replay a prepared Builder execution gate locally as a dry run; never calls Builder                                                              |
+| `execute-builder-source-execution`          | `--databaseId <id>` or `--documentId <id> --changeSetId <id> [--idempotencyKey <key>] [--pushModeConfirmation autosave\|draft\|publish]`                       | Execute a guarded live Builder write only when approved, validated, enabled, idempotent, and targeting `agent-native-blog-article-test`                  |
+| `add-database-item`                         | `--databaseId <id> [--title <text>] [--propertyValues <json>]`                                                                                                 | Add a page row to a database, optionally seeding property values                                                                                         |
+| `duplicate-database-item`                   | `--itemId <id>` or `--documentId <id> [--title <text>]`                                                                                                        | Duplicate exactly one database row page and its stored property values; for two or more rows, use `duplicate-database-items` once                        |
+| `duplicate-database-items`                  | `--databaseId <id>` or `--documentId <databaseDocumentId> --itemIds <json-array>` or `--documentIds <json-array>`                                              | Preferred multi-row duplicate action; duplicate multiple database row pages atomically and return ordered duplicate item/document IDs                    |
+| `delete-database-items`                     | `--databaseId <id>` or `--documentId <databaseDocumentId> --itemIds <json-array>` or `--documentIds <json-array>`                                              | Preferred multi-row delete action; delete multiple database row pages atomically while preserving `delete-document` admin semantics                      |
+| `move-database-item`                        | `--itemId <id>` or `--documentId <id> --position <number>`                                                                                                     | Move a database row page to a new zero-based table position                                                                                              |
+| `update-content-database-view`              | `--databaseId <id> --viewConfig <json>`                                                                                                                        | Persist database views, sorts, filters, hidden properties, and view settings                                                                             |
+| `list-document-properties`                  | `--documentId <id> [--format json]`                                                                                                                            | List Notion-style property definitions and values for a document                                                                                         |
+| `configure-document-property`               | `--documentId <id> [--id <propertyId>] --name <name> --type <type> [--visibility always_show\|hide_when_empty\|always_hide]`                                   | Create or update a property definition                                                                                                                   |
+| `duplicate-document-property`               | `--documentId <id> --propertyId <propertyId>`                                                                                                                  | Duplicate a property definition and its stored values                                                                                                    |
+| `delete-document-property`                  | `--documentId <id> --propertyId <propertyId>`                                                                                                                  | Delete a property definition and its stored values                                                                                                       |
+| `set-document-property`                     | `--documentId <id> --propertyId <propertyId> --value <json>`                                                                                                   | Set a document property value (for a `blocks` field, the value is its markdown content)                                                                  |
+| `reorder-document-property`                 | `--documentId <id> --propertyId <propertyId> --targetPropertyId <id> [--position before\|after]`                                                               | Reorder a property definition within its database (used to reorder Blocks fields on the page)                                                            |
+| `set-document-discoverability`              | `--id <id> --hideFromSearch true\|false [--includeChildren true\|false]`                                                                                       | Hide/show an org-accessible document in Organization/search while keeping link access                                                                    |
+| `move-document`                             | `--id <id> [--parentId] [--position]`                                                                                                                          | Move or reorder a document in the page tree                                                                                                              |
+| `delete-document`                           | `--id <id>`                                                                                                                                                    | Delete with recursive children                                                                                                                           |
 
 Database views follow Notion-style tab labels. When creating or duplicating
 views in `viewConfig`, use unique default names (`Table 2`, `SEO copy 2`, etc.)