@agent-native/core 0.90.1 → 0.90.2

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.)

package/corpus/templates/content/actions/_builder-cms-read-client.ts

@@ -22,6 +22,18 @@ export interface BuilderCmsReadResult {
   entries: BuilderCmsSourceEntry[];
   fetchedAt: string;
   message: string | null;
+  progress: BuilderCmsReadProgress;
+}
+
+export interface BuilderCmsReadProgress {
+  requestedLimit: number;
+  pageSize: number;
+  startOffset: number;
+  nextOffset: number;
+  fetchedEntryCount: number;
+  hasMore: boolean;
+  partial: boolean;
+  readMode: "builder-api" | "mcp" | "none";
 }
 
 export interface BuilderCmsEntryLiveState {
@@ -385,6 +397,8 @@ async function initializeBuilderMcp(args: {
 async function readBuilderCmsContentEntriesViaMcp(args: {
   model: string;
   limit?: number;
+  maxPages?: number;
+  offset?: number;
   fetchImpl: FetchLike;
   privateKey: string;
 }): Promise<BuilderCmsReadResult> {
@@ -397,14 +411,22 @@ async function readBuilderCmsContentEntriesViaMcp(args: {
   });
 
   const limit = readLimit(args.limit);
+  const startOffset =
+    typeof args.offset === "number" && Number.isFinite(args.offset)
+      ? Math.max(0, Math.floor(args.offset))
+      : 0;
   const contentEntries: BuilderCmsSourceEntry[] = [];
   const seenContentIds = new Set<string>();
+  let pagesRead = 0;
+  let hasMore = false;
   for (
-    let offset = 0;
-    contentEntries.length < limit;
+    let offset = startOffset;
+    startOffset + contentEntries.length < limit;
     offset += BUILDER_CMS_PAGE_SIZE
   ) {
-    const pageLimit = readPageLimit(limit - contentEntries.length);
+    const pageLimit = readPageLimit(
+      limit - startOffset - contentEntries.length,
+    );
     const contentResult = await postBuilderMcp({
       endpoint,
       privateKey: args.privateKey,
@@ -436,7 +458,13 @@ async function readBuilderCmsContentEntriesViaMcp(args: {
       seenContentIds,
       pageEntries,
     );
-    if (pageEntries.length < pageLimit || appended === 0) break;
+    pagesRead += 1;
+    hasMore =
+      pageEntries.length >= pageLimit &&
+      appended > 0 &&
+      contentEntries.length < limit;
+    if (args.maxPages && pagesRead >= args.maxPages) break;
+    if (!hasMore) break;
   }
   if (contentEntries.length > 0) {
     return {
@@ -444,6 +472,16 @@ async function readBuilderCmsContentEntriesViaMcp(args: {
       entries: contentEntries,
       fetchedAt,
       message: null,
+      progress: {
+        requestedLimit: limit,
+        pageSize: BUILDER_CMS_PAGE_SIZE,
+        startOffset,
+        nextOffset: startOffset + contentEntries.length,
+        fetchedEntryCount: startOffset + contentEntries.length,
+        hasMore,
+        partial: hasMore && Boolean(args.maxPages),
+        readMode: "mcp",
+      },
     };
   }
 
@@ -458,6 +496,16 @@ async function readBuilderCmsContentEntriesViaMcp(args: {
       entries: [],
       fetchedAt,
       message: null,
+      progress: {
+        requestedLimit: limit,
+        pageSize: BUILDER_CMS_PAGE_SIZE,
+        startOffset,
+        nextOffset: startOffset,
+        fetchedEntryCount: 0,
+        hasMore: false,
+        partial: false,
+        readMode: "mcp",
+      },
     };
   }
 
@@ -522,12 +570,24 @@ async function readBuilderCmsContentEntriesViaMcp(args: {
     entries: hydratedEntries,
     fetchedAt,
     message: null,
+    progress: {
+      requestedLimit: limit,
+      pageSize: BUILDER_CMS_PAGE_SIZE,
+      startOffset,
+      nextOffset: startOffset + hydratedEntries.length,
+      fetchedEntryCount: startOffset + hydratedEntries.length,
+      hasMore: false,
+      partial: false,
+      readMode: "mcp",
+    },
   };
 }
 
 async function readBuilderCmsContentEntriesViaContentApi(args: {
   model: string;
   limit?: number;
+  maxPages?: number;
+  offset?: number;
   fetchImpl: FetchLike;
   publicKey: string;
 }): Promise<BuilderCmsReadResult> {
@@ -544,15 +604,21 @@ async function readBuilderCmsContentEntriesViaContentApi(args: {
   url.searchParams.set("noCache", "true");
 
   const limit = readLimit(args.limit);
+  const startOffset =
+    typeof args.offset === "number" && Number.isFinite(args.offset)
+      ? Math.max(0, Math.floor(args.offset))
+      : 0;
   const entries: BuilderCmsSourceEntry[] = [];
   const seenIds = new Set<string>();
+  let pagesRead = 0;
+  let hasMore = false;
   for (
-    let offset = 0;
-    entries.length < limit;
+    let offset = startOffset;
+    startOffset + entries.length < limit;
     offset += BUILDER_CMS_PAGE_SIZE
   ) {
     const pageUrl = new URL(url);
-    const pageLimit = readPageLimit(limit - entries.length);
+    const pageLimit = readPageLimit(limit - startOffset - entries.length);
     pageUrl.searchParams.set("limit", String(pageLimit));
     pageUrl.searchParams.set("offset", String(offset));
 
@@ -571,6 +637,16 @@ async function readBuilderCmsContentEntriesViaContentApi(args: {
           error instanceof Error
             ? `Builder CMS read failed: ${error.message}`
             : "Builder CMS read failed.",
+        progress: {
+          requestedLimit: limit,
+          pageSize: BUILDER_CMS_PAGE_SIZE,
+          startOffset,
+          nextOffset: startOffset + entries.length,
+          fetchedEntryCount: startOffset + entries.length,
+          hasMore,
+          partial: Boolean(args.maxPages) && hasMore,
+          readMode: "builder-api",
+        },
       };
     }
 
@@ -580,6 +656,16 @@ async function readBuilderCmsContentEntriesViaContentApi(args: {
         entries: [],
         fetchedAt,
         message: `Builder CMS read failed with HTTP ${response.status}.`,
+        progress: {
+          requestedLimit: limit,
+          pageSize: BUILDER_CMS_PAGE_SIZE,
+          startOffset,
+          nextOffset: startOffset + entries.length,
+          fetchedEntryCount: startOffset + entries.length,
+          hasMore,
+          partial: Boolean(args.maxPages) && hasMore,
+          readMode: "builder-api",
+        },
       };
     }
 
@@ -588,7 +674,11 @@ async function readBuilderCmsContentEntriesViaContentApi(args: {
       .map((entry) => normalizeBuilderCmsApiEntry(entry, args.model))
       .filter((entry): entry is BuilderCmsSourceEntry => Boolean(entry));
     const appended = appendUniqueBuilderEntries(entries, seenIds, pageEntries);
-    if (pageEntries.length < pageLimit || appended === 0) break;
+    pagesRead += 1;
+    hasMore =
+      pageEntries.length >= pageLimit && appended > 0 && entries.length < limit;
+    if (args.maxPages && pagesRead >= args.maxPages) break;
+    if (!hasMore) break;
   }
 
   return {
@@ -596,6 +686,16 @@ async function readBuilderCmsContentEntriesViaContentApi(args: {
     entries,
     fetchedAt,
     message: null,
+    progress: {
+      requestedLimit: limit,
+      pageSize: BUILDER_CMS_PAGE_SIZE,
+      startOffset,
+      nextOffset: startOffset + entries.length,
+      fetchedEntryCount: startOffset + entries.length,
+      hasMore,
+      partial: hasMore && Boolean(args.maxPages),
+      readMode: "builder-api",
+    },
   };
 }
 
@@ -644,6 +744,50 @@ export async function readBuilderCmsEntryLiveState(args: {
   return liveStateFromBuilderEntry(json);
 }
 
+export async function readBuilderCmsContentEntry(args: {
+  model: string;
+  entryId: string;
+  fetchImpl?: FetchLike;
+}): Promise<BuilderCmsSourceEntry | null> {
+  const publicKey = await resolveBuilderCredential("BUILDER_PUBLIC_KEY");
+  if (!publicKey) {
+    throw new Error(
+      "Builder CMS entry read skipped because BUILDER_PUBLIC_KEY is not configured.",
+    );
+  }
+
+  const url = new URL(
+    `/api/v3/content/${encodeURIComponent(args.model)}/${encodeURIComponent(
+      args.entryId,
+    )}`,
+    builderContentApiHost(),
+  );
+  url.searchParams.set("apiKey", publicKey);
+  url.searchParams.set("includeUnpublished", "true");
+  url.searchParams.set("enrich", "true");
+  url.searchParams.set("noCache", "true");
+  url.searchParams.set("cachebust", String(Date.now()));
+  url.searchParams.set("fields", BUILDER_CMS_ENTRY_FIELDS);
+
+  const response = await fetchBuilderContentPage({
+    fetchImpl: args.fetchImpl ?? fetch,
+    url,
+  });
+  if (response.status === 404) return null;
+  if (!response.ok) {
+    throw new Error(
+      `Builder CMS entry read failed with HTTP ${response.status}.`,
+    );
+  }
+
+  const json = (await response.json()) as unknown;
+  const rawEntry = Array.isArray(json)
+    ? json[0]
+    : (entryArrayFromResponse(json)[0] ?? json);
+  const entry = normalizeBuilderCmsApiEntry(rawEntry, args.model);
+  return entry?.id === args.entryId ? entry : null;
+}
+
 export async function listBuilderCmsModels(
   args: {
     fetchImpl?: FetchLike;
@@ -725,6 +869,8 @@ export async function readBuilderCmsModelFields(args: {
 export async function readBuilderCmsContentEntries(args: {
   model: string;
   limit?: number;
+  maxPages?: number;
+  offset?: number;
   fetchImpl?: FetchLike;
 }): Promise<BuilderCmsReadResult> {
   const fetchedAt = new Date().toISOString();
@@ -735,6 +881,8 @@ export async function readBuilderCmsContentEntries(args: {
     const contentApiRead = await readBuilderCmsContentEntriesViaContentApi({
       model: args.model,
       limit: args.limit,
+      maxPages: args.maxPages,
+      offset: args.offset,
       fetchImpl,
       publicKey,
     });
@@ -749,6 +897,8 @@ export async function readBuilderCmsContentEntries(args: {
       return await readBuilderCmsContentEntriesViaMcp({
         model: args.model,
         limit: args.limit,
+        maxPages: args.maxPages,
+        offset: args.offset,
         fetchImpl,
         privateKey,
       });
@@ -761,6 +911,16 @@ export async function readBuilderCmsContentEntries(args: {
           error instanceof Error
             ? error.message
             : "Builder CMS MCP read failed.",
+        progress: {
+          requestedLimit: readLimit(args.limit),
+          pageSize: BUILDER_CMS_PAGE_SIZE,
+          startOffset: 0,
+          nextOffset: 0,
+          fetchedEntryCount: 0,
+          hasMore: false,
+          partial: false,
+          readMode: "mcp",
+        },
       };
     }
   }
@@ -772,6 +932,16 @@ export async function readBuilderCmsContentEntries(args: {
       fetchedAt,
       message:
         "Builder CMS read skipped because BUILDER_PUBLIC_KEY is not configured.",
+      progress: {
+        requestedLimit: readLimit(args.limit),
+        pageSize: BUILDER_CMS_PAGE_SIZE,
+        startOffset: 0,
+        nextOffset: 0,
+        fetchedEntryCount: 0,
+        hasMore: false,
+        partial: false,
+        readMode: "none",
+      },
     };
   }
 
@@ -780,5 +950,15 @@ export async function readBuilderCmsContentEntries(args: {
     entries: [],
     fetchedAt,
     message: "Builder CMS read returned no entries.",
+    progress: {
+      requestedLimit: readLimit(args.limit),
+      pageSize: BUILDER_CMS_PAGE_SIZE,
+      startOffset: 0,
+      nextOffset: 0,
+      fetchedEntryCount: 0,
+      hasMore: false,
+      partial: false,
+      readMode: "none",
+    },
   };
 }

package/corpus/templates/content/actions/_builder-docs-client.ts

@@ -40,6 +40,23 @@ import { flushOpenDocumentEditorToSql } from "./_document-flush.js";
 
 type FetchLike = typeof fetch;
 
+function builderDocsReadProgress(args: {
+  limit: number;
+  count: number;
+  readMode: "builder-api" | "none";
+}): BuilderCmsReadResult["progress"] {
+  return {
+    requestedLimit: args.limit,
+    pageSize: args.limit,
+    startOffset: 0,
+    nextOffset: args.count,
+    fetchedEntryCount: args.count,
+    hasMore: false,
+    partial: false,
+    readMode: args.readMode,
+  };
+}
+
 export interface BuilderDocsFilesInput {
   path?: string | null;
   files?: Record<string, string> | null;
@@ -263,6 +280,11 @@ async function readBuilderDocsPublishedEntries(args: {
       fetchedAt,
       message:
         "Builder docs list skipped because BUILDER_PUBLIC_KEY is not configured.",
+      progress: builderDocsReadProgress({
+        limit: args.limit,
+        count: 0,
+        readMode: "none",
+      }),
     };
   }
 
@@ -289,6 +311,11 @@ async function readBuilderDocsPublishedEntries(args: {
         error instanceof Error
           ? `Builder docs list failed: ${error.message}`
           : "Builder docs list failed.",
+      progress: builderDocsReadProgress({
+        limit: args.limit,
+        count: 0,
+        readMode: "builder-api",
+      }),
     };
   }
 
@@ -298,17 +325,28 @@ async function readBuilderDocsPublishedEntries(args: {
       entries: [],
       fetchedAt,
       message: `Builder docs list failed with HTTP ${response.status}.`,
+      progress: builderDocsReadProgress({
+        limit: args.limit,
+        count: 0,
+        readMode: "builder-api",
+      }),
     };
   }
 
   const json = (await response.json()) as unknown;
+  const entries = entryArrayFromResponse(json)
+    .map((entry) => normalizeBuilderCmsApiEntry(entry, args.model))
+    .filter((entry): entry is BuilderCmsSourceEntry => Boolean(entry));
   return {
     state: "live",
-    entries: entryArrayFromResponse(json)
-      .map((entry) => normalizeBuilderCmsApiEntry(entry, args.model))
-      .filter((entry): entry is BuilderCmsSourceEntry => Boolean(entry)),
+    entries,
     fetchedAt,
     message: null,
+    progress: builderDocsReadProgress({
+      limit: args.limit,
+      count: entries.length,
+      readMode: "builder-api",
+    }),
   };
 }