@agent-native/core 0.92.11 → 0.93.0

package/corpus/templates/content/AGENTS.md

@@ -91,59 +91,60 @@ 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; 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                                                                        |
-| `stage-builder-source-bulk-update`          | `--databaseId <id>` or `--documentId <id> --itemIds <json-array>` or `--documentIds <json-array> --field <json> [--sourceId <id>] [--dryRun true\|false]`      | Preview or stage one bounded field update across selected source-backed Builder rows; apply still goes through Builder review/execution                  |
-| `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                                                                                                 |
+| `stage-builder-source-bulk-update`          | `--databaseId <id>` or `--documentId <id> --itemIds <json-array>` or `--documentIds <json-array> --field <json> [--sourceId <id>] [--dryRun true\|false]`      | Preview or stage one bounded field update across selected source-backed Builder rows; apply still goes through Builder review/execution                                           |
+| `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                                                                                                                  |
+| `submit-content-database-form`              | `--databaseId <id> [--viewId <form-view-id>] [--title <text>] [--propertyValues <json>]`                                                                       | Submit one form response atomically; validates required questions, resolves option labels/IDs, writes Blocks correctly, verifies persistence, and returns the exact row page link |
+| `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.)
@@ -497,7 +498,7 @@ body. A Blocks field can only be deleted from the database view's column menu
 (not from the page body); deleting the last Blocks field warns that it removes
 the body for every object of the type. Formula properties store their expression in property options and support
 `{Property name}` substitution plus simple numeric math such as `{MSV} * 2`.
-Database views support multiple named table, list, gallery, board, calendar, and timeline views saved in
+Database views support multiple named table, list, gallery, board, calendar, timeline, and form views saved in
 `content_databases.view_config_json`. Each view has its own stacked sorts,
 type-aware filters with an all/any match mode, per-view hidden property IDs,
 column widths, and (for table, list, gallery, and board views) grouping property
@@ -569,8 +570,17 @@ If a calendar or timeline view has not saved a date property yet, the UI and
 Timeline views render the same date-backed row pages in a horizontally
 scrollable six-week range, using a per-view start date property and optional
 end date property so cards can span multiple days.
+Form views render database properties as ordered questions. Each form view owns
+its enabled-question order and required flags, so two forms on the same database
+can collect different information. Use `submit-content-database-form` for agent,
+Slack, MCP, and UI submissions instead of composing `add-database-item` plus
+several property writes. The action accepts property definition IDs or exact
+property names, accepts select/status option IDs or labels, rejects unknown
+options, writes primary and additional Blocks fields to their correct stores in
+one transaction, verifies the saved row, and returns `createdItemId`,
+`createdDocumentId`, `urlPath`, and `deepLink`.
 The active view menu can rename, duplicate, delete, or switch an existing
-view's layout between table, list, gallery, calendar, timeline, and board while
+view's layout between table, list, gallery, calendar, timeline, board, and form while
 preserving its sorts, filters, hidden properties, and layout-specific settings.
 Board views group
 pages by status, select, multi-select, or checkbox

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

@@ -56,12 +56,78 @@ type BuilderMcpToolResult = {
 };
 
 const BUILDER_CMS_DEFAULT_READ_LIMIT = 500;
-const BUILDER_CMS_MAX_READ_LIMIT = 1000;
+const BUILDER_CMS_MAX_READ_LIMIT = 10_000;
 const BUILDER_CMS_PAGE_SIZE = 100;
 const BUILDER_CMS_READ_RETRIES = 2;
-const BUILDER_CMS_METADATA_ENTRY_FIELDS =
-  "id,name,published,lastUpdated,createdDate,data.title,data.handle,data.url,data.slug,data.date,data.description,data.status,data.author,data.image";
-const BUILDER_CMS_BODY_ENTRY_FIELDS = `${BUILDER_CMS_METADATA_ENTRY_FIELDS},data.blocks,data.blocksString`;
+const BUILDER_CMS_METADATA_ENTRY_FIELD_PATHS = [
+  "id",
+  "name",
+  "published",
+  "lastUpdated",
+  "createdDate",
+  "data.title",
+  "data.handle",
+  "data.url",
+  "data.slug",
+  "data.date",
+  "data.description",
+  "data.status",
+  "data.author",
+  "data.image",
+] as const;
+const BUILDER_CMS_TOP_LEVEL_METADATA_FIELDS = new Set(
+  BUILDER_CMS_METADATA_ENTRY_FIELD_PATHS.filter(
+    (fieldPath) => !fieldPath.startsWith("data."),
+  ).map((fieldPath) => fieldPath.toLowerCase()),
+);
+const BUILDER_CMS_HEAVY_BODY_FIELD_PATHS = [
+  "data.blocks",
+  "data.blocksString",
+] as const;
+const BUILDER_CMS_FIELD_PATH_PATTERN =
+  /^[A-Za-z0-9_$-]+(?:\.[A-Za-z0-9_$-]+)*$/;
+
+function normalizeBuilderCmsListFieldPath(fieldPath: string) {
+  const trimmed = fieldPath.trim();
+  if (!trimmed || !BUILDER_CMS_FIELD_PATH_PATTERN.test(trimmed)) return null;
+  const normalized = trimmed.includes(".")
+    ? trimmed
+    : BUILDER_CMS_TOP_LEVEL_METADATA_FIELDS.has(trimmed.toLowerCase())
+      ? trimmed
+      : `data.${trimmed}`;
+  const lower = normalized.toLowerCase();
+  if (
+    BUILDER_CMS_HEAVY_BODY_FIELD_PATHS.some((heavyFieldPath) => {
+      const heavyLower = heavyFieldPath.toLowerCase();
+      return lower === heavyLower || lower.startsWith(`${heavyLower}.`);
+    })
+  ) {
+    return null;
+  }
+  if (
+    normalized.includes(".") &&
+    !normalized.toLowerCase().startsWith("data.")
+  ) {
+    return null;
+  }
+  return normalized;
+}
+
+export function builderCmsListEntryFields(fieldPaths: readonly string[] = []) {
+  const fields = new Map<string, string>();
+  for (const fieldPath of [
+    ...BUILDER_CMS_METADATA_ENTRY_FIELD_PATHS,
+    ...fieldPaths,
+  ]) {
+    const normalized = normalizeBuilderCmsListFieldPath(fieldPath);
+    if (!normalized) continue;
+    if (!fields.has(normalized)) fields.set(normalized, normalized);
+  }
+  return Array.from(fields.values()).join(",");
+}
+
+const BUILDER_CMS_METADATA_ENTRY_FIELDS = builderCmsListEntryFields();
+const BUILDER_CMS_BODY_ENTRY_FIELDS = `${BUILDER_CMS_METADATA_ENTRY_FIELDS},${BUILDER_CMS_HEAVY_BODY_FIELD_PATHS.join(",")}`;
 
 function builderContentApiHost() {
   return (
@@ -444,6 +510,7 @@ async function initializeBuilderMcp(args: {
 
 async function readBuilderCmsContentEntriesViaMcp(args: {
   model: string;
+  fieldPaths?: readonly string[];
   limit?: number;
   maxPages?: number;
   offset?: number;
@@ -464,17 +531,16 @@ async function readBuilderCmsContentEntriesViaMcp(args: {
       ? Math.max(0, Math.floor(args.offset))
       : 0;
   const contentEntries: BuilderCmsSourceEntry[] = [];
+  const fields = builderCmsListEntryFields(args.fieldPaths);
   const seenContentIds = new Set<string>();
   let pagesRead = 0;
   let hasMore = false;
   for (
     let offset = startOffset;
-    startOffset + contentEntries.length < limit;
+    contentEntries.length < limit;
     offset += BUILDER_CMS_PAGE_SIZE
   ) {
-    const pageLimit = readPageLimit(
-      limit - startOffset - contentEntries.length,
-    );
+    const pageLimit = readPageLimit(limit - contentEntries.length);
     const contentResult = await postBuilderMcp({
       endpoint,
       privateKey: args.privateKey,
@@ -490,7 +556,7 @@ async function readBuilderCmsContentEntriesViaMcp(args: {
             modelName: args.model,
             limit: pageLimit,
             offset,
-            fields: BUILDER_CMS_METADATA_ENTRY_FIELDS,
+            fields,
             enrich: true,
           },
         },
@@ -507,10 +573,7 @@ async function readBuilderCmsContentEntriesViaMcp(args: {
       pageEntries,
     );
     pagesRead += 1;
-    hasMore =
-      pageEntries.length >= pageLimit &&
-      appended > 0 &&
-      contentEntries.length < limit;
+    hasMore = pageEntries.length >= pageLimit && appended > 0;
     if (args.maxPages && pagesRead >= args.maxPages) break;
     if (!hasMore) break;
   }
@@ -527,7 +590,7 @@ async function readBuilderCmsContentEntriesViaMcp(args: {
         nextOffset: startOffset + contentEntries.length,
         fetchedEntryCount: startOffset + contentEntries.length,
         hasMore,
-        partial: hasMore && Boolean(args.maxPages),
+        partial: hasMore,
         readMode: "mcp",
       },
     };
@@ -549,7 +612,7 @@ async function readBuilderCmsContentEntriesViaMcp(args: {
         pageSize: BUILDER_CMS_PAGE_SIZE,
         startOffset,
         nextOffset: startOffset,
-        fetchedEntryCount: 0,
+        fetchedEntryCount: startOffset,
         hasMore: false,
         partial: false,
         readMode: "mcp",
@@ -600,7 +663,7 @@ async function readBuilderCmsContentEntriesViaMcp(args: {
             modelName: args.model,
             limit: 1,
             query: { id: entry.id },
-            fields: BUILDER_CMS_METADATA_ENTRY_FIELDS,
+            fields,
             enrich: true,
           },
         },
@@ -633,6 +696,7 @@ async function readBuilderCmsContentEntriesViaMcp(args: {
 
 async function readBuilderCmsContentEntriesViaContentApi(args: {
   model: string;
+  fieldPaths?: readonly string[];
   limit?: number;
   maxPages?: number;
   offset?: number;
@@ -650,7 +714,7 @@ async function readBuilderCmsContentEntriesViaContentApi(args: {
   // bare reference id.
   url.searchParams.set("enrich", "true");
   url.searchParams.set("noCache", "true");
-  url.searchParams.set("fields", BUILDER_CMS_METADATA_ENTRY_FIELDS);
+  url.searchParams.set("fields", builderCmsListEntryFields(args.fieldPaths));
 
   const limit = readLimit(args.limit);
   const startOffset =
@@ -663,11 +727,11 @@ async function readBuilderCmsContentEntriesViaContentApi(args: {
   let hasMore = false;
   for (
     let offset = startOffset;
-    startOffset + entries.length < limit;
+    entries.length < limit;
     offset += BUILDER_CMS_PAGE_SIZE
   ) {
     const pageUrl = new URL(url);
-    const pageLimit = readPageLimit(limit - startOffset - entries.length);
+    const pageLimit = readPageLimit(limit - entries.length);
     pageUrl.searchParams.set("limit", String(pageLimit));
     pageUrl.searchParams.set("offset", String(offset));
 
@@ -724,8 +788,7 @@ async function readBuilderCmsContentEntriesViaContentApi(args: {
       .filter((entry): entry is BuilderCmsSourceEntry => Boolean(entry));
     const appended = appendUniqueBuilderEntries(entries, seenIds, pageEntries);
     pagesRead += 1;
-    hasMore =
-      pageEntries.length >= pageLimit && appended > 0 && entries.length < limit;
+    hasMore = pageEntries.length >= pageLimit && appended > 0;
     if (args.maxPages && pagesRead >= args.maxPages) break;
     if (!hasMore) break;
   }
@@ -742,7 +805,7 @@ async function readBuilderCmsContentEntriesViaContentApi(args: {
       nextOffset: startOffset + entries.length,
       fetchedEntryCount: startOffset + entries.length,
       hasMore,
-      partial: hasMore && Boolean(args.maxPages),
+      partial: hasMore,
       readMode: "builder-api",
     },
   };
@@ -902,7 +965,10 @@ export async function readBuilderCmsModelFields(args: {
   fetchImpl?: FetchLike;
 }): Promise<BuilderCmsModelFieldSummary[]> {
   const models = await listBuilderCmsModels({ fetchImpl: args.fetchImpl });
-  if (models.state !== "live") return [];
+  if (models.state === "unconfigured") return [];
+  if (models.state === "error") {
+    throw new Error(models.message ?? "Builder CMS model discovery failed.");
+  }
   const modelName = args.model.trim().toLowerCase();
   return (
     models.models.find((model) => {
@@ -917,6 +983,7 @@ export async function readBuilderCmsModelFields(args: {
 
 export async function readBuilderCmsContentEntries(args: {
   model: string;
+  fieldPaths?: readonly string[];
   limit?: number;
   maxPages?: number;
   offset?: number;
@@ -929,6 +996,7 @@ export async function readBuilderCmsContentEntries(args: {
   if (publicKey) {
     const contentApiRead = await readBuilderCmsContentEntriesViaContentApi({
       model: args.model,
+      fieldPaths: args.fieldPaths,
       limit: args.limit,
       maxPages: args.maxPages,
       offset: args.offset,
@@ -945,6 +1013,7 @@ export async function readBuilderCmsContentEntries(args: {
     try {
       return await readBuilderCmsContentEntriesViaMcp({
         model: args.model,
+        fieldPaths: args.fieldPaths,
         limit: args.limit,
         maxPages: args.maxPages,
         offset: args.offset,