Notion IntegrationCAUTION

A framework for building agentic apps

The instruction file, verbatim from the audited commit — this is the text the model reads, and the surface the audit's instruction layer examines. Quoted here so you can judge it without cloning anything.

---
name: notion-integration
description: >-
  How Notion sync works. Covers connecting, linking pages, pulling from Notion,
  pushing to Notion, and checking sync status.
---

# Notion Integration

The content app can sync documents bidirectionally with Notion. Documents can be linked to Notion pages, pulled from Notion, or pushed to Notion.

Notion sync is not creative-context retrieval. When drafting new copy from a
synced page, read the `creative-context` skill first and retrieve voice,
terminology, audience guidance, and factual evidence as separate roles. Apply
its exact reuse ladder, respect opt-out/pinned packs, and use app-local Notion
content as the fallback when the shared corpus has no relevant evidence. Keep
the resulting immutable `contextPackId` and reuse labels with document
generation provenance; never infer them from a later Notion sync snapshot.

## Scripts

### connect-notion-status

Check the Notion connection status.

```bash
pnpm action connect-notion-status
```

Returns whether a Notion integration is connected and which workspace it belongs to.

### link-notion-page

Link a local document to a Notion page for syncing.

```bash
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

List all documents that are linked to Notion pages.

```bash
pnpm action list-notion-links
```

### pull-notion-page

Pull content from a linked Notion page into the local document.

```bash
pnpm action pull-notion-page --documentId abc123
```

This overwrites the local document's content with the Notion page's content, converted to markdown.

### push-notion-page

Push local document content to the linked Notion page.

```bash
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"
```

### list-notion-database-sources

List Notion data sources visible to the current user's OAuth connection before
attaching one to a Content collection:

```bash
pnpm action list-notion-database-sources --query "projects"
```

The database-source pilot is read-only and uses the same per-user OAuth
connection as page sync. Choose a returned data-source ID, run
`suggest-source-join-key`, then attach it with
`attach-content-database-source --sourceType notion-database
--relationshipMode details`. Use `refresh-content-database-source` to pull a
new bounded snapshot. Never use a pasted token or claim Notion write-back.

### disconnect-notion

Disconnect the current user's Notion OAuth connection.

```bash
pnpm action disconnect-notion
```

## Raw Notion Provider API

Treat the Notion workflow actions above as shortcuts, not capability limits.
When the exact Notion endpoint, filter, pagination mode, or API version matters,
use `provider-api-catalog`, `provider-api-docs`, and `provider-api-request`
against the real Notion API. The provider API resolves auth from the user's
Notion OAuth connection, never from `NOTION_API_KEY`. For large scans, stage
results with `stageAs` and analyze them with `query-staged-dataset`.

## How Sync Works (Architecture)

Documents are stored as **Notion-Flavored Markdown (NFM)** — the exact format
Notion's `/pages/{id}/markdown` API emits and accepts. The storage form is
Notion's _canonical_ form, so a synced document is byte-identical on both sides.

- `shared/nfm.ts` is the single deterministic converter: `nfmToDoc` (NFM →
  ProseMirror JSON) and `docToNfm` (ProseMirror JSON → NFM), plus
  `canonicalizeNfm = docToNfm ∘ nfmToDoc`. It is used by **both** the editor
  (`setContent(nfmToDoc(x))` / `docToNfm(editor.getJSON())`) and the server
  (pull canonicalization + content hashing).
- The converter is a proven **fixpoint**: `docToNfm(nfmToDoc(x)) === x` for all
  canonical NFM `x`, verified by `shared/nfm.spec.ts` (pure) and
  `app/components/editor/nfm-editor.roundtrip.test.ts` (real TipTap schema).
  Because our canonical form equals Notion's emission, pull→edit→push→pull
  never drifts.
- Pulls also materialize accessible Notion child pages referenced by `<page>`
  atoms. Each child becomes a local `documents` row with `parent_id` set to the
  pulled parent and a `document_sync_links` row pointing at the child Notion
  page, so the sidebar tree and page blocks can open the same local subpage.
  Inaccessible child pages remain preserved as NFM page refe

CAUTIONgrade B · trust 89/100 Install with care. The audit found things worth knowing before you trust its output.

What the source does

Filesystem

none-observed

Network

none-observed

Shell

none-observed

Dependencies

pinned

Secrets in source

none-found

Findings (5)

.agents/skills/an

.agents/skills/content-product-development

.agents/skills/design-exploration

.agents/skills/turn-into-app

.agents/skills/visual-edit

Gates applied: no_behavioural_pass.

[![ModelsAtlas audit: Notion Integration](https://modelsatlas.com/skills/builderio/notion-integration/badge.svg)](https://modelsatlas.com/skills/builderio/notion-integration/)

Not your listing, or something out of date? Claim or update your listing.