notion-integration

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.

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.

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

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.

pnpm action unlink-notion-page --documentId abc123

list-notion-links

List all documents that are linked to Notion pages.

pnpm action list-notion-links

pull-notion-page

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

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.

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.

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.

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.

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

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 database:

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.

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 references.
• Do not route Notion content through shared/notion-markdown.ts (the old tiptap-markdown bridge). It is retained only for clipboard copy/paste.

Supported losslessly: paragraphs, headings (incl. toggle headings via {toggle="true"}), bulleted/numbered/to-do lists with tab nesting, real quote blocks (multi-line via <br>), block colors ({color="…"}), inline bold/italic/strike/code/underline/color/background and links, inline + block equations, code blocks, dividers, <empty-block/>, callouts, toggles, columns, tables (header row/column, cell/row colors), images/audio/video/file/pdf, page and database references, synced blocks (children preserved), mentions, and backslash-escaped special characters. Visual indentation is a block indent attribute (Tab indents a block, matching Notion).

Sync State

The document_sync_links table tracks sync relationships:

Column	Description
document_id	Local document ID
provider	Always "notion"
remote_page_id	Notion page ID
state	"linked", "syncing", "error", "conflict"
last_synced_at	Timestamp of last successful sync
last_synced_content_hash	SHA-256 of the canonical content identical on both sides — the authoritative "did it change" signal (immune to timestamp jitter)
has_conflict	Whether both sides changed since last sync (0 or 1)
last_error	Error message if sync failed

Conflict detection is content-hash based: a side has "changed" only when its canonical content hash differs from last_synced_content_hash. A no-op sync (identical canonical content) is never mistaken for an edit — this is what keeps the two copies from drifting.

Common Tasks

User says	What to do
"Is Notion connected?"	connect-notion-status
"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

Important Notes

• Notion access is per-user OAuth only. Never read NOTION_API_KEY from the environment or process.env, never accept a user-pasted token or save a user-entered Notion token through /_agent-native/env-vars, and require editor access for routes that pull or push Notion content.
• Pull replaces local content with Notion's; push replaces Notion's with local. When both sides changed since the last sync the link enters conflict state and the user resolves it (pull-wins or push-wins) — there is no line-level merge.
• Because storage is canonical NFM, a no-op sync changes nothing: editing the same document in Notion and in the app will not create growing inconsistencies.
• Always check connect-notion-status before attempting sync operations.