@agent-native/core 0.122.3 → 0.123.0

package/docs/content/template-content-developers.mdx

@@ -0,0 +1,364 @@
+---
+title: "Content: Developer Guide"
+description: "Data model, action inventory, routes, and extension points for forking or extending the Content template."
+---
+
+# Content: Developer Guide
+
+This page is for anyone forking the Content template or building on it: the full data model, every action grouped by area, the route surface, and the places to look when adding a feature. If you're looking for how to use the app day to day, see the [Content overview](/docs/template-content) and its linked pages instead.
+
+## Quick start
+
+```bash
+npx @agent-native/core@latest create my-content --standalone --template content
+```
+
+See [Getting started](/docs/getting-started) for the rest of the setup and the framework fundamentals (actions, application state, live sync).
+
+<FileTree
+  id="doc-block-content8"
+  title="Content template layout"
+  entries={[
+    {
+      path: "actions/",
+      note: "defineAction operations — the single source of truth",
+    },
+    {
+      path: "actions/_*.ts",
+      note: "private helpers shared between actions, not mounted as tools",
+    },
+    { path: "app/routes/", note: "React Router file routes" },
+    { path: "app/components/editor/", note: "the Tiptap/Yjs document editor" },
+    { path: "server/db/schema.ts", note: "Drizzle schema — 22 tables" },
+    { path: "shared/content-source.ts", note: "local-folder sync contract" },
+    { path: "shared/nfm.ts", note: "Notion-Flavored Markdown converter" },
+    {
+      path: "shared/properties.ts",
+      note: "property type definitions and (de)serialization",
+    },
+    {
+      path: ".agents/skills/",
+      note: "content, document-editing, notion-integration, creative-context",
+    },
+    { path: "AGENTS.md", note: "top-level agent guide" },
+  ]}
+/>
+
+## Data model
+
+Content's schema (`server/db/schema.ts`) currently defines 22 tables, not the nine a much earlier version of this doc described. Nine cover the document lifecycle, collaboration, and sync surfaces below; the other 13 belong to the inline-database and external-source subsystem, documented in full on [Databases, properties & forms](/docs/template-content-databases#data-model).
+
+| Table                                      | What it holds                                                                                            |
+| ------------------------------------------ | -------------------------------------------------------------------------------------------------------- |
+| `documents`                                | The page tree — title, markdown content, description, icon, parent/position, favorite, visibility, space |
+| `content_spaces`                           | A personal or org workspace; owns one canonical Files database                                           |
+| `content_space_catalog_items`              | Maps a space into the current user's visible workspace catalog                                           |
+| `document_versions`                        | Full title/content snapshots for version history and restore                                             |
+| `document_preview_drafts`                  | An unsaved editor draft, kept separate from the saved document                                           |
+| `document_comments`                        | Threaded, anchor-tracked comments with `@mentions` and resolve state                                     |
+| `document_sync_links`                      | One row per Notion-linked document — remote page id, sync state, content hash, conflict flag             |
+| `builder_doc_sidecars`                     | Raw sidecar files (e.g. `.raw` Builder blocks) alongside a Builder-synced document                       |
+| `document_shares`                          | Framework shares table — per-user/per-org grants (`createSharesTable`)                                   |
+| `document_property_definitions`            | Column definitions for inline databases _(see Databases page)_                                           |
+| `content_databases`                        | Inline database objects _(see Databases page)_                                                           |
+| `content_database_items`                   | Database rows _(see Databases page)_                                                                     |
+| `content_database_body_hydration_queue`    | Queues a body-content backfill pass for source-imported rows that need one                               |
+| `content_database_sources`                 | An attached external source _(see Databases page)_                                                       |
+| `content_database_source_fields`           | Field mappings _(see Databases page)_                                                                    |
+| `content_database_source_rows`             | Row identity/provenance _(see Databases page)_                                                           |
+| `content_database_source_change_sets`      | Proposed sync changes _(see Databases page)_                                                             |
+| `content_database_source_change_reviews`   | Review decisions _(see Databases page)_                                                                  |
+| `content_database_source_executions`       | Guarded write-back attempts _(see Databases page)_                                                       |
+| `content_database_source_execution_claims` | Idempotency keys so a retried write-back can't double-write                                              |
+| `document_property_values`                 | Per-row property values _(see Databases page)_                                                           |
+| `document_block_field_contents`            | Content for secondary Blocks fields _(see Databases page)_                                               |
+
+<DataModel
+  id="doc-block-content9"
+  title="Documents, collaboration, and sync"
+  summary={
+    "documents is the page tree; every other table here hangs off it for spaces, versions, comments, Notion sync, Builder sidecars, and sharing. The inline-database and external-source subsystem is a separate, larger block on the Databases page."
+  }
+  entities={[
+    {
+      id: "documents",
+      name: "documents",
+      note: "The page tree (ownable, markdown body)",
+      fields: [
+        { name: "id", type: "id", pk: true },
+        {
+          name: "space_id",
+          type: "id",
+          fk: "content_spaces.id",
+          nullable: true,
+        },
+        {
+          name: "parent_id",
+          type: "id",
+          fk: "documents.id",
+          nullable: true,
+          note: "infinite nesting",
+        },
+        { name: "title", type: "string" },
+        { name: "content", type: "markdown" },
+        {
+          name: "description",
+          type: "string",
+          note: "stable guidance, not a generated summary",
+        },
+        { name: "icon", type: "string", nullable: true },
+        { name: "position", type: "int", note: "sibling ordering" },
+        { name: "is_favorite", type: "bool" },
+        {
+          name: "hide_from_search",
+          type: "bool",
+          note: "org-discoverable but not listed",
+        },
+        { name: "visibility", type: "enum", note: "private | org | public" },
+        { name: "trashed_at", type: "datetime", nullable: true },
+        {
+          name: "trash_root_id",
+          type: "id",
+          nullable: true,
+          note: "marks the top of a trashed subtree",
+        },
+        { name: "owner_email", type: "string" },
+        { name: "org_id", type: "id", nullable: true },
+      ],
+    },
+    {
+      id: "content_spaces",
+      name: "content_spaces",
+      note: "A personal or org workspace; owns one canonical Files database",
+      fields: [
+        { name: "id", type: "id", pk: true },
+        { name: "name", type: "string" },
+        { name: "kind", type: "string" },
+        { name: "files_database_id", type: "id", fk: "content_databases.id" },
+        { name: "owner_email", type: "string" },
+        { name: "org_id", type: "id", nullable: true },
+        { name: "archived_at", type: "datetime", nullable: true },
+      ],
+    },
+    {
+      id: "document_versions",
+      name: "document_versions",
+      note: "Full title/content snapshots for version history",
+      fields: [
+        { name: "id", type: "id", pk: true },
+        { name: "document_id", type: "id", fk: "documents.id" },
+        { name: "title", type: "string" },
+        { name: "content", type: "markdown" },
+      ],
+    },
+    {
+      id: "document_comments",
+      name: "document_comments",
+      note: "Threaded comments with quoted-text anchors",
+      fields: [
+        { name: "id", type: "id", pk: true },
+        { name: "document_id", type: "id", fk: "documents.id" },
+        { name: "thread_id", type: "id" },
+        {
+          name: "parent_id",
+          type: "id",
+          fk: "document_comments.id",
+          nullable: true,
+        },
+        { name: "quoted_text", type: "string", nullable: true },
+        { name: "anchor_prefix", type: "string", nullable: true },
+        { name: "anchor_suffix", type: "string", nullable: true },
+        { name: "mentions_json", type: "json", nullable: true },
+        { name: "resolved", type: "bool" },
+        {
+          name: "notion_comment_id",
+          type: "string",
+          nullable: true,
+          note: "bidirectional Notion sync",
+        },
+        { name: "notion_discussion_id", type: "string", nullable: true },
+      ],
+    },
+    {
+      id: "document_sync_links",
+      name: "document_sync_links",
+      note: "One row per Notion-linked document",
+      fields: [
+        { name: "document_id", type: "id", pk: true, fk: "documents.id" },
+        { name: "remote_page_id", type: "string" },
+        {
+          name: "state",
+          type: "enum",
+          note: "linked | syncing | error | conflict",
+        },
+        {
+          name: "last_synced_content_hash",
+          type: "string",
+          nullable: true,
+          note: "content-hash change detection",
+        },
+        { name: "has_conflict", type: "bool" },
+        { name: "sync_comments", type: "bool" },
+        { name: "last_error", type: "string", nullable: true },
+      ],
+    },
+    {
+      id: "builder_doc_sidecars",
+      name: "builder_doc_sidecars",
+      note: "Raw sidecar files for a Builder-synced document",
+      fields: [
+        { name: "id", type: "id", pk: true },
+        { name: "document_id", type: "id", fk: "documents.id" },
+        { name: "path", type: "string" },
+        { name: "content", type: "string" },
+        { name: "content_hash", type: "string" },
+      ],
+    },
+    {
+      id: "document_shares",
+      name: "document_shares",
+      note: "Per-user and per-org grants (createSharesTable)",
+      fields: [
+        { name: "id", type: "id", pk: true },
+        { name: "resource_id", type: "id", fk: "documents.id" },
+        { name: "principal_type", type: "enum", note: "user | org" },
+        { name: "principal_id", type: "string" },
+        { name: "role", type: "enum", note: "viewer | editor | admin" },
+      ],
+    },
+  ]}
+  relations={[
+    {
+      from: "content_spaces",
+      to: "documents",
+      kind: "1-n",
+      label: "owns pages",
+    },
+    { from: "documents", to: "documents", kind: "1-n", label: "has children" },
+    {
+      from: "documents",
+      to: "document_versions",
+      kind: "1-n",
+      label: "has snapshots",
+    },
+    {
+      from: "documents",
+      to: "document_comments",
+      kind: "1-n",
+      label: "has comments",
+    },
+    {
+      from: "documents",
+      to: "document_sync_links",
+      kind: "1-1",
+      label: "links to Notion",
+    },
+    {
+      from: "documents",
+      to: "builder_doc_sidecars",
+      kind: "1-n",
+      label: "has Builder sidecars",
+    },
+    {
+      from: "documents",
+      to: "document_shares",
+      kind: "1-n",
+      label: "has share grants",
+    },
+  ]}
+/>
+
+Content is stored as markdown. The editor converts to and from the Tiptap JSON model in memory; the SQL row is always markdown so actions, search, and Notion sync operate on one canonical format. All ownable tables carry `owner_email` and `org_id` via `ownableColumns()`, so every row is scoped to the signed-in user (and their active organization) from creation.
+
+## Action inventory {#action-inventory}
+
+Every operation is a TypeScript file in `templates/content/actions/`, auto-mounted at `POST /_agent-native/actions/:name`. Files prefixed `_` are private helpers, not mounted as tools.
+
+**Documents & pages** — `create-document`, `get-document`, `list-documents`, `search-documents`, `pull-document` (collab-aware flush-then-read), `edit-document` (find/replace), `update-document` (full rewrite), `delete-document` (soft-delete to Trash), `restore-document`, `permanently-delete-document`, `list-trashed-documents`, `move-document`, `export-document` (PDF-ready HTML, Markdown, or HTML), `transcribe-media`, `set-document-discoverability`, `set-image-alt-text`, `share-local-file-document`, `list-document-versions`, `restore-document-version`.
+
+**Comments** — `list-comments`, `add-comment`, `update-comment`, `delete-comment`.
+
+**Databases, properties & views** — `create-content-database`, `create-inline-content-database`, `get-content-database`, `list-content-databases`, `delete-content-database`, `restore-content-database`, `list-trashed-content-databases`, `add-database-item`, `duplicate-database-item`, `duplicate-database-items`, `delete-database-items`, `move-database-item`, `update-content-database-view`, `get-content-database-personal-view`, `update-content-database-personal-view`, `list-document-properties`, `configure-document-property`, `set-document-property`, `duplicate-document-property`, `delete-document-property`, `reorder-document-property`, `submit-content-database-form`.
+
+**External database sources** — `attach-content-database-source`, `disconnect-content-database-source`, `get-content-database-source`, `refresh-content-database-source`, `review-content-database-source-change-set`, `bind-content-database-source-field`, `add-content-database-source-field-property`, `suggest-source-join-key`, `list-notion-database-sources`, `list-builder-cms-models`. Builder's write-back path adds `prepare-builder-source-review`, `preview-builder-source-review`, `prepare-builder-source-execution`, `validate-builder-source-execution`, `execute-builder-source-execution`, `execute-builder-source-batch`, `cancel-prepared-builder-source-update`, `stage-builder-revision`, `stage-builder-source-bulk-update`, `materialize-builder-required-fields`, and `process-builder-body-hydration`.
+
+**Notion document sync** — `connect-notion-status`, `link-notion-page`, `create-and-link-notion-page`, `unlink-notion-page`, `list-notion-links`, `pull-notion-page`, `push-notion-page`, `refresh-notion-sync-status`, `resolve-notion-sync-conflict`, `sync-notion-comments`, `search-notion-pages`, `disconnect-notion`.
+
+**Builder CMS document sync** — `list-builder-docs`, `check-builder-doc`, `pull-builder-doc`, `push-builder-doc` (distinct from the read-only database-source path above — these round-trip a whole document).
+
+**Local folder sync** — `connect-local-folder-source`, `sync-local-folder-source`, `resolve-local-folder-conflict`, `disconnect-local-folder-source`, `export-content-source`, `import-content-source`, `sync-manifest-local-folder-source`, `remove-local-file-source`, `reveal-local-source-file`, `list-local-component-files`, `write-local-component-file`, `register-local-component-workspace`.
+
+**Spaces** — `list-content-spaces`, `create-content-space`, `ensure-content-spaces`.
+
+**Provider API escalation & staged scans** — `provider-api-catalog`, `provider-api-docs`, `provider-api-request`, `list-staged-datasets`, `query-staged-dataset`, `delete-staged-dataset`. Use these when a canned action doesn't expose the exact Notion/Builder endpoint, filter, or pagination you need — see the `notion-integration` skill.
+
+**Navigation & screen** — `view-screen`, `navigate`, `refresh-list`.
+
+## Routes {#routes}
+
+| Route                                                                                                              | What it renders                                                                                                                                              |
+| ------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `_app.tsx`                                                                                                         | Pathless layout — sidebar and agent panel stay mounted across navigation                                                                                     |
+| `_app._index.tsx`                                                                                                  | Landing view — the document tree                                                                                                                             |
+| `_app.page.tsx` / `_app.page._index.tsx` / `_app.page.$id.tsx`                                                     | The editor route family — `/page/:id` opens one document                                                                                                     |
+| `_app.favorites.tsx`                                                                                               | Redirects into the current space's Favorites Files-database document                                                                                         |
+| `_app.local-files.tsx`                                                                                             | `/local-files` — connect, pull, check, and push local folders                                                                                                |
+| `_app.settings.tsx`                                                                                                | Settings                                                                                                                                                     |
+| `_app.team.tsx`                                                                                                    | `/team` redirects to `/settings#organization`                                                                                                                |
+| `_app.agent.tsx`                                                                                                   | `/agent` — the full agent chat tab page                                                                                                                      |
+| `_app.extensions.tsx` + `_app.extensions._index.tsx` + `_app.extensions.$id.tsx` + `_app.extensions.$id.$slug.tsx` | `/extensions` — sandboxed widget routes (the framework's Alpine.js extension system; unrelated to the Tiptap "editor extensions" used elsewhere in this doc) |
+| `p.$id.tsx`                                                                                                        | `/p/:id` — public, read-only document view with a read-only agent chat                                                                                       |
+| `$id.tsx`                                                                                                          | Legacy `/:id` redirect to `/page/:id`                                                                                                                        |
+
+## Customizing it
+
+<AnnotatedCode
+  id="doc-block-content10"
+  title="A soft-delete action reusing shared trash logic"
+  filename="actions/delete-content-database.ts"
+  language="ts"
+  code={
+    'import { defineAction } from "@agent-native/core";\nimport { writeAppState } from "@agent-native/core/application-state";\nimport { assertAccess } from "@agent-native/core/sharing";\nimport { z } from "zod";\n\nimport { getDb } from "../server/db/index.js";\nimport { assertContentDatabaseLifecycleAccess } from "./_content-database-lifecycle.js";\nimport { trashDocumentSubtree } from "./delete-document.js";\n\nexport default defineAction({\n  description:\n    "Soft-delete a content database without deleting its documents or rows.",\n  schema: z.object({\n    databaseId: z.string().describe("Content database ID"),\n  }),\n  run: async ({ databaseId }) => {\n    const { database } = await assertContentDatabaseLifecycleAccess(databaseId);\n    if (database.systemRole) {\n      throw new Error("System Content databases cannot be deleted");\n    }\n    await assertAccess("document", database.documentId, "admin");\n    const db = getDb();\n    const deletedAt = database.deletedAt ?? new Date().toISOString();\n    await db.transaction((tx) =>\n      trashDocumentSubtree(\n        tx as unknown as ReturnType<typeof getDb>,\n        database.documentId,\n        database.ownerEmail,\n        deletedAt,\n      ),\n    );\n\n    await writeAppState("refresh-signal", { ts: Date.now() });\n\n    return {\n      success: true,\n      databaseId,\n      documentId: database.documentId,\n      deletedAt,\n    };\n  },\n});\n'
+  }
+  annotations={[
+    {
+      lines: "18-20",
+      label: "System databases are protected",
+      note: "A database created by the framework itself (Files, Favorites, workspace catalog) carries a systemRole and refuses deletion here, so a stray delete call can't orphan a space's canonical storage.",
+    },
+    {
+      lines: "24-31",
+      label: "Reuse the document trash, don't reimplement it",
+      note: "trashDocumentSubtree is the same helper delete-document uses. A database's row documents get the identical soft-delete/restore semantics as any other page subtree instead of a second, database-specific trash implementation.",
+    },
+    {
+      lines: "33",
+      label: "Signal a UI refresh",
+      note: "Mutations outside the standard create/update/delete document actions must poke refresh-signal themselves so the open sidebar repaints.",
+    },
+  ]}
+/>
+
+The places to look when changing behavior:
+
+- **`actions/`** — every operation the agent or UI can perform. Add a new file like `actions/publish-to-wordpress.ts` using `defineAction` and both sides get it for free.
+- **`app/routes/`** — the page surface described above.
+- **`app/components/editor/`** — the Tiptap editor. Add a new node type under `extensions/` and register it in `DocumentEditor.tsx`. The bubble toolbar, slash menu, and hover previews are all component files you can edit.
+- **`.agents/skills/`** — guidance the agent reads before acting: `content`, `document-editing`, `notion-integration`, `creative-context`, plus the framework skills. Add a new skill folder when you add a capability big enough to need its own guidance.
+- **`AGENTS.md`** — the top-level agent guide with the action cheatsheet. Update it whenever you add a feature so the agent discovers it without exploring.
+- **`server/db/schema.ts`** — the data model. Content has no `db:push` script; it relies on strictly additive migrations that run on startup. Migrations must never drop, rename, or destructively alter existing tables or columns — see [Database](/docs/database#migrations).
+- **A new external-source adapter** — implement the `ContentDatabaseSourceAdapter` interface in `actions/_content-database-source-adapters.ts` (see the existing `builder-cms`, `local-table`, and `notion-database` adapters) and wire it into `attach-content-database-source`. Every adapter reads into the same change-set/review pipeline described on the [Databases page](/docs/template-content-databases#connecting-an-external-source) — a new adapter should not bypass it with a direct write.
+- **`shared/content-source.ts`** — the local-folder sync contract (filenames, frontmatter, parsing, serialization). Extend this if you change what an exported file looks like.
+- **`shared/nfm.ts`** — the Notion-Flavored Markdown converter. Extend this if you add block types that need to round-trip through Notion.
+
+The agent can make most of these changes itself — ask it to "add a tags column to documents and expose it in the sidebar" and it will update the schema, migrate, wire the UI, and write the action.
+
+## What's next
+
+- [Content overview](/docs/template-content) — what the app is and how to get started
+- [Writing & organizing documents](/docs/template-content-editing) — the non-developer view of the editor and sharing model
+- [Databases, properties & forms](/docs/template-content-databases) — the full inline-database and external-source data model
+- [Local files, Notion & Builder CMS sync](/docs/template-content-sync) — the non-developer view of every sync surface
+- [Database](/docs/database) — the framework's Drizzle conventions and migration rules
+- [Actions](/docs/actions) — the action system every operation above is built on
+- [Sharing](/docs/sharing) — the share-grant model `document_shares` builds on

package/docs/content/template-content-editing.mdx

@@ -0,0 +1,60 @@
+---
+title: "Content: Writing & Organizing Documents"
+description: "How to write, format, organize, comment on, and share documents in Content — for anyone using the app day to day."
+---
+
+# Writing & Organizing Documents
+
+This page covers the everyday parts of Content: writing and formatting a page, arranging your pages into a tree, commenting with teammates, rolling back to an earlier version, and controlling who can see a document. It's written for anyone using the app, not just developers.
+
+## Writing and formatting
+
+Type `/` on an empty line to open the slash menu and insert headings, bulleted or numbered lists, tables, code blocks, images, dividers, and callouts. Select any text to pop up a formatting toolbar for bold, italic, links, and inline code.
+
+- Images can be dropped in or pasted; Content uploads them to your configured file storage automatically.
+- Math renders as real equations — type inline math between `` $` `` marks or a block equation between `$$` lines, and the editor displays the formatted result while keeping the original notation in the document.
+- Ask the agent instead of formatting by hand: "add a callout warning about the deprecated endpoint," "turn this list into a table," or "make this heading a level 2."
+
+## Organizing your pages
+
+Every page lives in a sidebar tree. Drag a page to reorder it or nest it under another page as a sub-page — nesting has no depth limit. Star a page to pin it to **Favorites** at the top of the sidebar.
+
+Use the search box (or ask the agent to "find my meeting notes from last week") to search titles and content across every page you can see, with a preview snippet for each match.
+
+## Comments
+
+Select a passage and leave a comment the way you would in Notion or Google Docs — the commented text gets a highlight instead of any change to the document body, so the page reads exactly the same afterward. Comments support @mentions of teammates, threaded replies, and a resolve/reopen toggle; resolved threads collapse into a "Resolved" section in the sidebar so they don't clutter an active review.
+
+If a commented passage gets edited later, the highlight follows the surrounding text rather than snapping to a fixed position, and if the exact text is ever deleted the comment thread still stays reachable from the sidebar instead of disappearing.
+
+## Version history
+
+Content keeps a snapshot of a page every time it changes significantly. Open a page's version history to see prior snapshots and restore one — restoring replaces the current content with that version's content wholesale; there's no line-by-line diff or partial restore.
+
+<WireframeBlock id="doc-block-content3">
+  <Screen
+    surface="desktop"
+    html={
+      "<div style='display:grid;grid-template-columns:1fr 260px;gap:14px;padding:16px;min-height:480px;box-sizing:border-box'><main style='display:flex;flex-direction:column;gap:12px;min-width:0'><div style='display:flex;align-items:center;gap:10px'><h1 style='margin:0'>Launch checklist</h1><div style='flex:1'></div><span class='wf-pill'>3 comments</span></div><div class='wf-card' style='flex:1;display:flex;flex-direction:column;gap:10px;padding:20px'><p style='margin:0'>Confirm pricing page copy before <mark>Thursday's release window</mark>.</p><div class='wf-box'>Owner: Priya · Status: In review</div><p style='margin:0' class='wf-muted'>Rollback plan documented below.</p></div></main><aside class='wf-card' style='display:flex;flex-direction:column;gap:10px'><strong>Comments</strong><div class='wf-box'>Sam: \"Can we push this a day?\"</div><div class='wf-box wf-muted'>Resolved (2)</div><hr/><strong>Version history</strong><span class='wf-pill'>Today, 2:14pm</span><span class='wf-pill'>Yesterday, 5:02pm</span><span class='wf-pill'>Restore</span></aside></div>"
+    }
+  />
+</WireframeBlock>
+
+## Sharing and visibility
+
+Documents are **private by default** — only you can see a page you create. To share one, use the share dialog (or ask the agent, "share this doc with the team as an editor") to:
+
+- Change visibility to **org** (anyone in your organization can open it) or **public** (anyone with the link can open it, at a read-only public URL).
+- Grant specific people or your whole org a **viewer**, **editor**, or **admin** role.
+
+An org-visible page can also be made discoverable-off — still open to anyone with the link, but left out of org-wide search and the sidebar list, useful for pages that exist for reference but shouldn't show up in everyday browsing.
+
+Public pages ship a read-only chat for visitors: they can ask questions about the page's content, but they can't create, edit, comment on, or share anything through it.
+
+## What's next
+
+- [Content overview](/docs/template-content) — what the app is and how to get started
+- [Databases, properties & forms](/docs/template-content-databases) — turning a page into a structured table
+- [Local files, Notion & Builder CMS sync](/docs/template-content-sync) — editing the same pages from outside the app
+- [Sharing](/docs/sharing) — the framework-wide share-grant model this page's roles build on
+- [Real-Time Collaboration](/docs/real-time-collaboration) — how simultaneous edits from people and the agent merge live

package/docs/content/template-content-sync.mdx

@@ -0,0 +1,149 @@
+---
+title: "Content: Local Files, Notion & Builder CMS Sync"
+description: "Edit Content documents from outside the app: a local Markdown/MDX folder, a linked Notion page, or a Builder CMS entry, each with reviewable two-way sync."
+---
+
+# Local Files, Notion & Builder CMS Sync
+
+A Content document doesn't have to be edited only inside the app. This page covers the three ways to keep a document in sync with something outside Content: a folder of Markdown/MDX files on disk, a linked Notion page, or a Builder CMS entry. Each is optional, and a document can use more than one.
+
+<Diagram id="doc-block-content6" title="Three sync surfaces, one canonical document" summary={"SQL is always the source of truth for a document's live state. Local files, Notion, and Builder CMS are round-trip surfaces around it, never a second source of truth."}>
+
+```html
+<div class="diagram-flow">
+  <div class="diagram-col">
+    <div class="diagram-box">
+      Local .md / .mdx folder<br /><small class="diagram-muted"
+        >Pull · Check · Push</small
+      >
+    </div>
+  </div>
+  <div class="diagram-arrow diagram-muted" aria-hidden="true">&harr;</div>
+  <div class="diagram-panel center">
+    <span class="diagram-pill accent">documents (markdown)</span
+    ><small class="diagram-muted">canonical SQL store</small>
+  </div>
+  <div class="diagram-arrow diagram-muted" aria-hidden="true">&harr;</div>
+  <div class="diagram-col">
+    <div class="diagram-box">
+      Notion page<br /><small class="diagram-muted"
+        >pull · push · comments</small
+      >
+    </div>
+    <div class="diagram-box">
+      Builder CMS entry<br /><small class="diagram-muted"
+        >pull · guarded push</small
+      >
+    </div>
+  </div>
+</div>
+```
+
+```css
+.diagram-flow {
+  display: flex;
+  align-items: center;
+  gap: 12px;
+  flex-wrap: wrap;
+}
+.diagram-flow .diagram-col {
+  display: flex;
+  flex-direction: column;
+  gap: 10px;
+}
+.diagram-flow .diagram-arrow {
+  font-size: 22px;
+  line-height: 1;
+}
+.diagram-flow .center {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  gap: 4px;
+}
+```
+
+</Diagram>
+
+## Local Markdown/MDX folder sync
+
+Open `/local-files` and connect a folder from your browser or Agent Native Desktop. This is the "Obsidian for MDX" workflow: files stay inspectable and editable on disk with your own tools, while Content still gives you a rich editor, agent actions, sharing, and custom blocks on the same pages.
+
+Each row in `/local-files` gives you three actions:
+
+- **Pull** — import the folder's current files into Content as ordinary documents.
+- **Check** — run the same import as a dry run, so you can preview what would change before committing to it.
+- **Push** — export the current document tree back out to the folder as Markdown/MDX files.
+
+Every exported file carries frontmatter (`id`, `title`, `parentId`, `position`, favorite/search/visibility flags, `updatedAt`) plus the page body as Markdown, so editing the file directly and pulling it back in updates the same document instead of creating a duplicate. If the same page changed on both sides since the last sync, or a file that used to exist is now missing, Content surfaces it as a conflict to review instead of silently deleting or overwriting either side. Disconnecting a folder always leaves both the Content pages and the files on disk in place.
+
+To open Content for an existing repo directly against a folder:
+
+```bash
+npx @agent-native/core@latest content .
+```
+
+This starts normal database-backed Content and registers an opaque local-folder connection in `agent-native.json` — it does not switch the app into a separate local-only mode. See [Local folder sources](/docs/local-file-mode) for the manifest format, truth policies, and Desktop bridge details.
+
+### Local MDX components
+
+A local-file workspace can expose its own React components as custom MDX blocks. Export a PascalCase component from a `.tsx` file in the configured `components` folder, and it becomes usable as `<ImpactCounter />` both in raw MDX and from the editor's slash menu under **Local components**. Components can also export simple editable input metadata, so selecting the component in the editor shows a corner edit button that rewrites its MDX props without touching code. Live component previews need a local Content dev server or Agent Native Desktop, since the browser alone can't compile `.tsx` files.
+
+## Notion sync
+
+Connect your Notion workspace once, then link any document to a Notion page. From there:
+
+- **Pull** overwrites the local document with the Notion page's current content.
+- **Push** overwrites the Notion page with the local document's current content.
+- Comments sync in both directions too.
+
+Content stores documents as Notion-Flavored Markdown — the same format Notion's own API emits and accepts — so a synced page round-trips byte-identical instead of drifting after repeated pulls and pushes. If both sides changed since the last sync, the link enters a conflict state and you choose a direction (pull-wins or push-wins) rather than getting an automatic line-level merge.
+
+Ask the agent: "Is Notion connected?", "Link this doc to Notion," "Pull the latest from Notion," or "Show me every document linked to Notion."
+
+## Builder CMS sync
+
+If your workspace has Builder.io configured, Content can pull a Builder docs or blog entry in as an editable document, complete with its `.builder.mdx` source file and any raw sidecar files Builder needs to reconstruct the entry. Edit it like any other Content document, then push it back through a guarded autosave — pushes currently target Builder's designated safe test model rather than every model, so a push can't accidentally overwrite production content you didn't intend to touch.
+
+Builder CMS models can also be attached as read-only inline-database sources — see [Databases, properties & forms](/docs/template-content-databases#connecting-an-external-source) for that workflow, which is a separate path from pulling/pushing a single document.
+
+<Callout tone="warning">
+
+Builder pulls can preserve provider-native blocks Content doesn't have a Markdown mapping for yet, marked as read-only `<SourceComponent>` placeholders in the source file. Treat those as preservation anchors: edit the prose around them freely, but don't delete, duplicate, or rewrite the marker itself — a guarded push refuses to go out if a marker looks tampered with or moved.
+
+</Callout>
+
+## Spaces and the Files database underneath every sync surface
+
+Every document belongs to a **space** — your personal space, or one shared with your organization — and every space owns one canonical Files database. A local folder, once connected, is a source attached to that Files database rather than a separate storage system, which is why imported files show up as normal pages with the same properties, sharing, and search as anything you typed by hand.
+
+<FileTree
+  id="doc-block-content7"
+  title="Sync contracts"
+  entries={[
+    {
+      path: "shared/content-source.ts",
+      note: "Single contract for local-folder filenames, frontmatter, parsing, and serialization",
+    },
+    {
+      path: "shared/nfm.ts",
+      note: "Notion-Flavored Markdown converter — the canonical Notion sync format",
+    },
+    {
+      path: "actions/pull-builder-doc.ts",
+      note: "Pull a Builder docs/blog entry into Content",
+    },
+    {
+      path: "actions/push-builder-doc.ts",
+      note: "Guarded autosave push back to Builder",
+    },
+  ]}
+/>
+
+## What's next
+
+- [Content overview](/docs/template-content) — what the app is and how to get started
+- [Writing & organizing documents](/docs/template-content-editing) — the editor and sharing model these synced documents use
+- [Databases, properties & forms](/docs/template-content-databases) — syncing rows inside a database, rather than whole documents
+- [Local folder sources](/docs/local-file-mode) — full configuration, truth policies, and conflict handling reference
+- [Developer Guide](/docs/template-content-developers) — the full sync action inventory and data model