@agent-native/core 0.88.0 → 0.90.2

package/corpus/templates/content/.agents/skills/actions/SKILL.md

@@ -161,6 +161,18 @@ to find likely URLs, `web-request` or `provider-api-docs` with clean
 `webFetch()` when you need to grep, aggregate, or compare many pages before
 returning a small result.
 
+For LONG compute, `run-code` supports durable background executions: pass
+`background: true` and the code is enqueued to a `sandbox_executions` row and
+executed out-of-band with a generous budget (default 10 min), surviving the
+hosted agent run's ~40s soft timeout. The call returns
+`{ executionId, status: "queued" }` immediately with polling guidance; check
+progress with `run-code` `{ executionId }` (or the `get-code-execution` tool
+where registered) — results persist after completion. Use background for big
+cross-source joins, multi-page provider sweeps, and heavy analysis scripts;
+keep quick scripts in the default foreground mode. Agents should continue
+other work between polls, and on `failed`/`timed_out` split the computation or
+persist intermediate progress with `workspaceWrite` and re-run.
+
 ### The `http` Option
 
 Controls how the action is exposed as an HTTP endpoint:
@@ -205,6 +217,49 @@ run: async (args) => {
 }
 ```
 
+### Returning Images the Agent Can See (`_agentImages`)
+
+An action's return object may include the well-known optional field
+`_agentImages` to attach vision images (screenshots, chart previews, rendered
+designs) to the tool result. The agent literally sees them — enabling visual
+self-review loops — while the field itself is stripped from the JSON text the
+model reads.
+
+```ts
+run: async ({ dashboardId }) => {
+  const shot = await renderDashboardPng(dashboardId); // Buffer
+  return {
+    dashboardId,
+    panelCount: 6,
+    _agentImages: [
+      // Either a public https URL (preferred — the provider fetches it)…
+      { url: "https://cdn.example.com/previews/dash-1.png", label: "overview" },
+      // …or base64 without a data: prefix (mediaType required; a full
+      // data:image/png;base64,… URL in `data` is also accepted and parsed).
+      { data: shot.toString("base64"), mediaType: "image/png" },
+    ],
+  };
+},
+```
+
+Rules and limits:
+
+- Shape: `Array<{ url?: string; data?: string; mediaType?: string; label?: string }>`.
+  Each entry needs `url` (https only) **or** `data`. Supported media types:
+  `image/jpeg`, `image/png`, `image/gif`, `image/webp`.
+- Caps: max **4 images** per result; max **~2MB of base64** per image.
+  Over-cap or invalid entries never fail the call — they become text notes in
+  the result telling the model what was dropped and why.
+- Persistence: the run ledger stores only the string result plus compact
+  `[image: …]` notes (URLs verbatim; base64 as a byte-count placeholder) —
+  never the payload. Images are re-attached only for the live turn; replayed
+  history is text-only, so prefer stable `url` images the model can re-request.
+- Engine support: native Anthropic and vision-capable AI-SDK providers
+  (anthropic, openai, google, openrouter) receive real image blocks; other
+  paths (Builder gateway, non-vision providers) degrade to the text notes.
+- External MCP tools need no changes — standard MCP `image` content parts are
+  converted automatically under the same caps.
+
 ### Validating Return Values (`outputSchema`)
 
 `schema` validates inputs; `outputSchema` validates what the action **returns**. Pass any Standard Schema-compatible schema (Zod, Valibot, ArkType) and the framework validates the result _after_ `run()` resolves — input validated before `run`, output after.

package/corpus/templates/content/.agents/skills/notion-integration/SKILL.md

@@ -26,7 +26,29 @@ Returns whether a Notion integration is connected and which workspace it belongs
 Link a local document to a Notion page for syncing.
 
 ```bash
-pnpm action link-notion-page --documentId abc123 --notionPageId notion-page-id
+pnpm action link-notion-page --documentId abc123 --pageId <notion-page-id-or-url>
+```
+
+`--pageIdOrUrl` and `--url` are accepted aliases for `--pageId`. There is no
+`--notionPageId` flag — passing it is silently dropped by the action's schema
+and the action fails with "documentId and pageId are required".
+
+### create-and-link-notion-page
+
+Create a brand-new Notion page from a Content document's current content and
+link it in one step (instead of creating in Notion first and linking after).
+
+```bash
+pnpm action create-and-link-notion-page --documentId abc123 [--parentPageIdOrUrl <id-or-url>]
+```
+
+### unlink-notion-page
+
+Remove the sync link between a document and its Notion page without deleting
+either side's content.
+
+```bash
+pnpm action unlink-notion-page --documentId abc123
 ```
 
 ### list-notion-links
@@ -57,6 +79,49 @@ pnpm action push-notion-page --documentId abc123
 
 This overwrites the Notion page's content with the local document's markdown, converted to Notion blocks.
 
+### refresh-notion-sync-status
+
+Check (and optionally auto-sync) the current sync status of a linked document.
+This is what the editor UI polls every few seconds while a document is open.
+
+```bash
+pnpm action refresh-notion-sync-status --documentId abc123 [--autoSync true]
+```
+
+### resolve-notion-sync-conflict
+
+Resolve a document whose link is in the `conflict` state (both sides changed
+since the last sync) by picking a direction.
+
+```bash
+pnpm action resolve-notion-sync-conflict --documentId abc123 --direction pull|push
+```
+
+### sync-notion-comments
+
+Sync comments bidirectionally between a document and its linked Notion page.
+
+```bash
+pnpm action sync-notion-comments --documentId abc123
+```
+
+### search-notion-pages
+
+Search Notion pages visible to the current user's connected workspace (used to
+find a page to link to).
+
+```bash
+pnpm action search-notion-pages --query "meeting notes"
+```
+
+### disconnect-notion
+
+Disconnect the current user's Notion OAuth connection.
+
+```bash
+pnpm action disconnect-notion
+```
+
 ## How Sync Works (Architecture)
 
 Documents are stored as **Notion-Flavored Markdown (NFM)** — the exact format
@@ -116,7 +181,7 @@ the two copies from drifting.
 | User says                      | What to do                                             |
 | ------------------------------ | ------------------------------------------------------ |
 | "Is Notion connected?"         | `connect-notion-status`                                |
-| "Link this doc to Notion"      | `link-notion-page --documentId ... --notionPageId ...` |
+| "Link this doc to Notion"      | `link-notion-page --documentId ... --pageId ...`       |
 | "Pull from Notion"             | `pull-notion-page --documentId ...`                    |
 | "Push to Notion"               | `push-notion-page --documentId ...`                    |
 | "Show Notion-linked documents" | `list-notion-links`                                    |

package/corpus/templates/content/AGENTS.md

@@ -87,57 +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                                                                   |
-| `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.)
@@ -216,12 +217,19 @@ Content has two file workflows:
   retargeting workflow is added.
 - **Builder source components:** Builder CMS database body hydration renders
   unsupported provider-native body blocks as `<SourceComponent ... />` markers.
-  Treat these as read-only preservation anchors, not editable local blocks.
-  Agents may edit surrounding prose, but must not delete, duplicate, move, or
-  rewrite `rawRef`, `rawHash`, or marker ids unless a dedicated provider
-  conversion workflow exists. Guarded Builder write-back refuses missing,
-  tampered, or structurally moved markers so source-native components are not
-  lost.
+  These markers include `mappingStatus` and `sourceEditState`: `mapped` /
+  `safe-to-edit` content has an explicit Markdown/NFM mapper, `preserved` /
+  `needs-review` content keeps a known Builder/source component intact for
+  review, and `unknown` / `preserved-only` content is an unmapped provider block
+  that must round-trip as-is. Treat source-component markers as read-only
+  preservation anchors, not editable local blocks. Agents may edit surrounding
+  prose, but must not delete, duplicate, move, or rewrite `rawRef`, `rawHash`,
+  mapping metadata, or marker ids unless a dedicated provider conversion
+  workflow exists. Guarded Builder write-back refuses missing, tampered, or
+  structurally moved markers so source-native components are not lost.
+  Readable bodies hydrated before source-component mapping may need a fresh
+  Builder body hydration pass before guarded push, because newly preserved
+  markers are intentionally treated as structure changes.
 - **Picked folders and components:** browser-picked folders can be the
   source of truth for `.md`/`.mdx` files, but the browser does not expose an
   absolute path that Vite can compile. Component previews from a picked
@@ -280,14 +288,14 @@ explicit sync action.
 
 ### Notion Integration
 
-| Action                  | Args                                    | Purpose                                   |
-| ----------------------- | --------------------------------------- | ----------------------------------------- |
-| `connect-notion-status` |                                         | Check Notion connection                   |
-| `link-notion-page`      | `--documentId <id> --notionPageId <id>` | Link doc to Notion page                   |
-| `list-notion-links`     |                                         | List linked documents                     |
-| `pull-notion-page`      | `--documentId <id>`                     | Pull content from Notion                  |
-| `push-notion-page`      | `--documentId <id>`                     | Push content to Notion                    |
-| `sync-notion-comments`  | `--documentId <id>`                     | Sync comments with Notion (bidirectional) |
+| Action                  | Args                                     | Purpose                                   |
+| ----------------------- | ---------------------------------------- | ----------------------------------------- |
+| `connect-notion-status` |                                          | Check Notion connection                   |
+| `link-notion-page`      | `--documentId <id> --pageId <id-or-url>` | Link doc to Notion page                   |
+| `list-notion-links`     |                                          | List linked documents                     |
+| `pull-notion-page`      | `--documentId <id>`                      | Pull content from Notion                  |
+| `push-notion-page`      | `--documentId <id>`                      | Push content to Notion                    |
+| `sync-notion-comments`  | `--documentId <id>`                      | Sync comments with Notion (bidirectional) |
 
 Use `provider-api-catalog`, `provider-api-docs`, and `provider-api-request`
 for Notion endpoints, filters, pagination modes, payload shapes, or API