pages

name	pages
description	Pages tools for Dataspheres AI

Pages

Tool reference for this resource group, mirrored by hand from the platform live /api/mcp/schema schema.

Tools

create_page — New Page

Creates a page (doc) in a datasphere. Guide the user through:

1. Which datasphere? (list_dataspheres if needed)
2. Title?
3. Content — offer to write it for them. Must be HTML (see schema below).
4. Folder placement — DO NOT SKIP THIS STEP. See FOLDER PLACEMENT PROTOCOL below.
5. Status? Default DRAFT — only PUBLISHED if user explicitly says "publish"

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ DATA-CARD PRE-FLIGHT (CRITICAL — run BEFORE drafting content)

If the user is on a dataset editor (URL matches /app/{uri}/datasets/{datasetId}/edit) OR the request mentions "this dataset", "the charts I built", "the cards", or any dataset by name: you MUST call list_data_cards with the CURRENT datasphereUri (and the current datasetId if you're narrowing to one dataset) BEFORE drafting the page content.

Why: manually-built cards are a huge signal about what the user wants the page to be about. If you draft a page without them, you'll produce a generic essay and the user will have to ask you to "add my charts" as a follow-up. Avoid that round trip — discover the cards first, weave them into the narrative, embed them via the dataCard node in the HTML content.

How to embed a card in the HTML content field:

[Data Card: {name}]

Skip the pre-flight only if: (a) the user explicitly says "no charts" / "text only", or (b) list_data_cards was already called earlier in this conversation for the same datasphereUri + datasetId and the results are fresh. ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ FOLDER PLACEMENT PROTOCOL (CRITICAL — run this BEFORE showing the preview card)

Every page belongs in a folder. Orphan pages buried at the datasphere root are hard to find later, and dumping everything into "General" defeats the whole point of having folders. ARI must actively find the RIGHT folder — or surface the choice to the user.

Step 1 — Discover what folders already exist. Before finalizing folderName, call list_folders for the target datasphere (skip if list_folders results are already in conversation history from this session). You need to see the existing folder tree before you can make a smart choice.

Step 2 — Find the best semantic match. Score each existing folder against the page's title + content topic. A good match means the folder name clearly belongs to the same domain as the page (e.g. page titled "Week 4: Compound Interest" → "Curriculum" or "Lessons" folder; page about "Q3 Funding Report" → "Reports" or "Finance" folder).

• Strong match (high confidence) → use that folder. Tell the user in one sentence: "Filing this under {folder} since that's where your other {topic} content lives." Then include folderName in the preview card with that value.
• Weak or ambiguous match (multiple candidates, none obviously right) → ASK the user: "I see folders like {a}, {b}, and {c} — where should this live? Or should I create a new one like {suggestion}?" Wait for the user's answer before emitting the preview card.
• No existing folders / no remotely relevant folder → propose a NEW folder name based on the content topic. Tell the user: "There's no folder for {topic} yet — I'll create one called {suggestion}. Sound good, or do you prefer a different name?" Wait for confirmation (or take silence/yes as a go), then pass the new folderName in the preview (the API auto-creates it).

Step 3 — Never silently guess. If you skip list_folders and make up a folderName, you WILL create duplicates ("Curriculum" vs "curriculum" vs "Course Content") and the user's tree becomes a mess. When in doubt, ASK. Asking one folder question is cheaper than cleaning up a messy tree later.

Step 4 — Edge cases.

• User explicitly names a folder ("put it in the Research folder") → use that name verbatim; if list_folders shows a close match (e.g. "Research & Reports"), use the existing one instead and tell the user. Otherwise pass their exact name and the API will auto-create it.
• User says "I don't care" / "wherever" → use your best-match pick from Step 2 and tell them which folder you chose in one sentence.
• Datasphere has ZERO folders → propose a name and wait for yes, don't silently create one.
• Updating an existing page (update_page): keep the current folder unless the user asks to move it. Only re-run the protocol if the topic clearly diverges from the folder it lives in.

Step 5 — Confirm in the preview card. The folderName field MUST appear in the tool_confirmation block so the user sees where the page will land before approving. Never hide the folder choice. ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

PUBLISHING — TWO LEVELS (educate the user):

• DRAFT (default for unclear intent): Only visible to the author. Work-in-progress.
• PUBLISHED: Visible to ALL datasphere members.
• isPubliclyVisible: true: Visible on the PUBLIC INTERNET without login. Crawled by Google, SEO-indexed. Use for marketing content, blog posts, public documentation, shareable articles, research reports the user wants to share.
• isPubliclyVisible: false: Only logged-in datasphere members can see it.

INTENT MAPPING (READ CAREFULLY):

• User says "draft a page" / "write something for me" → status: DRAFT, isPubliclyVisible: false
• User says "publish" / "publish this" → status: PUBLISHED, isPubliclyVisible: false (members-only)
• User says "publish publicly" / "make it public" / "SEO" / "shareable link" / "post it on the internet" → status: PUBLISHED, isPubliclyVisible: true
• User says "ship it" / "I want to share this" / "send this to someone" → status: PUBLISHED, isPubliclyVisible: true (they clearly want a shareable link)
• User asks for a research report or essay meant to be read by people they'll share it with → status: PUBLISHED, isPubliclyVisible: true (the whole point is shareability)

When in doubt about visibility, ASK THE USER instead of defaulting to private. Embedded data cards / datasets / images automatically inherit the page's public visibility, so making the page public also makes its embedded data public — tell the user this when confirming.

AFTER SUCCESSFUL CREATION — URLS TO SURFACE: Once the page is created, you'll be navigated to the advanced editor automatically. In your reply, ALWAYS include these URLs so the user knows where their content lives:

• Edit URL (always): /app/{datasphereUri}/docs/{pageId}/edit — the advanced editor for enrichment
• Member Preview URL (ALWAYS available after save): /docs/{datasphereUri}/{slug} — this is the public-facing view route. Datasphere members can use it right now to simulate how the published page looks. Even if the page isn't publicly visible yet, members can still see it via this URL. ALWAYS include this URL in your reply as the "Preview" link so the user can see the final reader experience before sharing it further.
• Public URL (same route, but becomes world-reachable when isPubliclyVisible=true): /docs/{datasphereUri}/{slug}

Example reply after a successful save:

Saved — "Week 12 Discussion Guide" is ready.

• 🔗 Preview (member view)
• ✏️ Edit in advanced editor

NOTE on embedded datasets/data cards: when a page has isPubliclyVisible=true and status=PUBLISHED, ALL embedded datasets and data cards in that page automatically become accessible on the public internet too (they inherit the page's visibility). Tell the user this explicitly if they've embedded live data.

PREVIEW CARD MUST INCLUDE ALL OF THESE FIELDS:

• title, datasphereUri, folderName, status, isPubliclyVisible, content (first 200 chars preview, collected value = FULL HTML)

FIELD RULES:

• Use EXACT lowercase field names: "title", "content", "datasphereUri", "folderName", "status", "isPubliclyVisible"
• Do NOT create extra fields — only the fields listed in the tool definition
• Do NOT duplicate fields with different cases
• "content" must be the FULL HTML, not truncated
• Be CONSISTENT with folderName across related pages
• Pages appear at /app/{uri}/docs/{slug} — NOT /pages/
• If the page slug already exists, the API upserts it

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ POST-SUCCESS PROTOCOL (what to do on your NEXT turn after this tool completes) ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ The user is auto-navigated by the server to the correct destination based on what was published. Your job is to confirm + surface the right URLs. READ THE appLink in the tool result to figure out which path you took:

1. If appLink starts with /docs/{uri}/{slug} — PUBLISHED PUBLIC. Anyone on the internet can read it; Google will crawl it.

   • In ONE sentence: "Page is live publicly."
   • Print BOTH URLs as clickable links: "Public: /docs/{uri}/{slug}" AND "Edit: /app/{uri}/docs/{pageId}/edit"
   • Mention embedded data cards/datasets inherit public visibility.
   • Offer to enrich further.

2. If appLink is /app/{uri}/docs/{slug} — PUBLISHED to datasphere members only.

   • In ONE sentence: "Page is live for datasphere members."
   • Print BOTH URLs: "Members view: /app/{uri}/docs/{slug}" AND "Edit: /app/{uri}/docs/{pageId}/edit"
   • Mention they can flip isPubliclyVisible later for a public shareable link.
   • Offer to enrich further.

3. If appLink is /app/{uri}/docs/{pageId}/edit — DRAFT only (visible to author).

   • In ONE sentence: "Draft is saved."
   • Print the edit URL.
   • Invite them to enrich in the editor — add media, rearrange sections, rewrite passages.
   • Offer to help with specific things ("let me know what you need next").

4. NEVER re-list the full page content — the user can see it in the editor. NEVER call more tools unless the user asks. NEVER re-emit the create_page confirmation after approval.

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

PAGE STRUCTURE — STORYTELLING WITH DATA

A great dataspheres page is a STORY backed by live data. When synthesizing search results, datasets, and data cards into a page, follow this structure:

1. Opening (1-2 paragraphs) — a strong

   Overview

   or

   What this page is about

   , followed by 1-2 punchy

   paragraphs that frame the question, stake, or insight. Lead with the most important takeaway — don't bury the lede.

2. Context section (optional) —

   Background

   or

   Why it matters

   . 2-3

   paragraphs of narrative, possibly with one

   citing a source.

3. Data sections — one or more

   {metric or finding}

   blocks.
   • Each section should have:
     • A

       introducing what the chart shows and why it matters

     • A dataCard or datasetEmbed block
     • A

       interpreting the result in plain English

   • Vary the chart types across sections (don't embed 4 bar charts in a row).

4. Narrative pull-quotes — use

   to embed quoted passages from linked URLs or search results. Always cite the source in an inside a

   .

5. Conclusion —

   Takeaways

   or

   What this means

   , 1-2 paragraphs that wrap up the narrative and connect the data back to the opening.

6. CTA / next steps —

   What to do next

   , either a short

   or a

   with 2-4 action items. Link to related dataspheres, pages, or external resources with .

RULES:

• Every page has a clear beginning, middle, and end.
• Every embedded data card or dataset has a short

  above it explaining the "why".

• Cite EVERY external source with a

  + attribution or a tiptap-link.

• Keep individual paragraphs under 80 words — readers skim.
• Use sparingly for emphasis, not decoration.

TIPTAP PAGE HTML — AVAILABLE NODES

The page editor is TipTap. Generate HTML that uses EXACTLY these node patterns. The editor parses the HTML and hydrates each custom block into a live React component.

heading

Section heading. Levels 1-3 only. Pattern:

|

|

{text}</h?> Example:

Key Findings

When to use: Start every major section with

. Use

for the page title only. Use

for sub-sections. Rules: Never nest headings; Never use

or deeper

paragraph

A body-text block. Pattern:

{text, possibly with inline formatting}

Example:

The data shows a significant upward trend since 2018.

When to use: The default block for prose. Use between headings, around embeds, and as transitions.

bulletList

Unordered list of items. Pattern:

• ...

...

Example:

• First point

• Second point

When to use: Non-sequential items: key takeaways, feature lists, bullet summaries. Rules: List items MUST wrap their text in

; Use the exact class "tiptap-bullet-list" on the

orderedList

Numbered list. Pattern:

1. ...

...
Example:

1. Step one

2. Step two

When to use: Sequential steps, ranked lists, numbered procedures. Rules: List items MUST wrap their text in

; Use the exact class "tiptap-ordered-list" on the

blockquote

Quoted passage, typically with a citation. Pattern:

{quote text}

— {source}

Example:

"Worldbuilding is the foundation of every great story."

— From a 2023 interview

When to use: Embedding a narrative excerpt from a search result or linked URL. Always attribute the source in an tag inside a

.

horizontalRule

Section divider. Pattern:

---

Example:

---

When to use: Between major logical sections when a heading feels too strong.

codeBlock

Preformatted code / data snippet. Pattern:

{code text}

Example:

SELECT * FROM events WHERE year = 2024;

When to use: Showing SQL, JSON, or code verbatim.

table

Classic HTML table. Resizable in the editor. Pattern:

......

...

Example:

Name	Count
Alpha	42

When to use: Showing tabular data that does NOT need to be a live query. For live aggregations use dataCard or datasetEmbed instead. Rules: Every cell MUST wrap text in

; Use the exact classes: tiptap-table, tiptap-table-row, tiptap-table-cell, tiptap-table-header

customImage

Figure-wrapped image with caption + optional link. Pattern:

{caption} Required attrs: src, alt Example: Monthly active users over five years When to use: Photos, screenshots, uploaded images, hero visuals.

customAudio

Audio player with title + description. Pattern:

...
Required attrs: data-src Example:
When to use: Embedding podcasts, voice notes, audio clips.

embed

External embed — YouTube, Twitter/X, Vimeo, CodePen, Spotify, etc. Renders as an iframe figure. Pattern:

Required attrs: data-url Example: When to use: Embedding an external video, tweet, or interactive widget via its canonical URL. The editor resolves the provider automatically.

imageRow

Row of 2-4 side-by-side images. Pattern:

{two or more customImage figures}
Example:

When to use: Before / after comparisons, gallery rows, side-by-side screenshots.

embedRow

Row of 2-4 side-by-side embeds (e.g. two YouTube videos). Pattern:

{two or more embed figures}
Example:
When to use: Side-by-side video comparisons, multi-platform tweet rows.

mermaid

Mermaid diagram block — renders a diagram from mermaid.js source. Pattern:

Required attrs: data-source Example:
When to use: Flowcharts, sequence diagrams, org charts, architecture diagrams. Mermaid syntax only — no images.

datasetEmbed

Live dataset preview — renders an interactive table of the dataset rows. Always fresh, always the latest data. Pattern:

[Dataset: {id}]
Required attrs: data-type="datasetEmbed", data-dataset-id, data-datasphere-id Example:
[Dataset: cmnosy7ev00pyp3loqqdk2h0m]
When to use: When the user wants the raw dataset rows visible in the page. Use this for reference tables, glossaries, or any time the READER needs to browse rows. Rules: data-dataset-id must be a real dataset id you have seen via list_datasets or a tool result; data-datasphere-id is required — the renderer needs it for auth; The inner text [Dataset: {id}] is a placeholder the editor discards on hydration

dataCard

Live data card — renders an interactive chart (bar, line, pie, scatter, etc.) that re-executes its formula on every view. New rows in the source dataset automatically propagate to the rendered chart. Pattern:

[Data Card: {id}]
Required attrs: data-type="dataCard", data-datacard-id, data-dataset-id, data-datasphere-id Example:
[Data Card: cmnpe7tj0000cp356eam375ec]
When to use: Showing a chart the user has already created (via the Data Cards builder) or that you just created via create_data_card. This is the PRIMARY way to embed quantitative narrative into a page. Rules: data-datacard-id must come from list_data_cards, search_data_cards, or a fresh create_data_card result; All three data-* ids are required — the renderer needs them to fetch the card and verify auth; Place a short

explanation ABOVE each data card so the reader knows what the chart shows; Don't include more than 4 data cards in one page — readers get chart fatigue

experienceBlock

Interactive scroll/slide experience block — advanced. Only use if explicitly requested. Pattern:

Example: (advanced — ask the user before using) When to use: Only when the user explicitly says "make this a presentation" or "slide experience".

citation ⭐ ANTI-HALLUCINATION

Inline source citation badge [N] — links a claim to a numbered reference in the appendix. Pattern: ^[{N}] Required attrs: data-type="citation", data-citation-n, data-citation-url Example:

The global AI market reached $207B in 2023^[1].

When to use: After ANY factual claim from a web_search result — statistics, quotes, findings. Place immediately after the claim. Number sequentially from 1. This PREVENTS hallucination by requiring every fact to trace to a real URL. Rules: data-citation-n must be sequential integers from 1; data-citation-title and data-citation-excerpt must be URL-encoded; Always pair with a citationAppendix block; Use real URLs from web_search results — never invent URLs

citationAppendix ⭐ ANTI-HALLUCINATION

Auto-generated reference list block — appears at the bottom, lists all citations. Pattern:

[Citation References]
Required attrs: data-type="citationAppendix" Example:
[Citation References]
When to use: Add exactly ONE at the very end of every page that contains citation badges. The editor populates it automatically — the inner text is just a placeholder. Rules: Only ONE citationAppendix per document; Place at the very end after all content; Required whenever you use citation badges

mention

@-mention of a datasphere (inline pill that links to the datasphere). Pattern: @{name} Example: @CLO When to use: Inline reference to a datasphere by name inside a

.

strong

Inline bold text. Pattern: {text} Example:

This is important.

When to use: Emphasizing a key term, metric, or finding inline.

em

Inline italic text. Pattern: {text} Example:

See the Communicating Design book.

When to use: Titles of works, foreign phrases, light emphasis.

link

Inline hyperlink. Pattern: {text} Example:

Source: Example Research

When to use: Citing a source, linking to an external reference. Always include class="tiptap-link".

CRITICAL REMINDERS

• Every custom block (dataCard, datasetEmbed, mermaid, embed, customImage, citationAppendix, etc.) is a
  or with data-type="...". Never omit the data-type.
• For dataCard and datasetEmbed: the ids (data-datacard-id, data-dataset-id, data-datasphere-id) MUST be real. Get them from list_data_cards / search_data_cards / create_data_card tool results. Never invent ids.
• The placeholder inner text (e.g. [Data Card: id]) is fine — the editor discards it on hydration. It just needs to be non-empty.
• CITATIONS: Use <span data-type="citation"> after EVERY factual claim from web_search results. Add ONE <div data-type="citationAppendix"> at the very end. This is the primary anti-hallucination mechanism. URL-encode data-citation-title and data-citation-excerpt.
• Output ONE HTML string. No markdown, no ```html fences, no explanation outside the HTML. ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Field	Type	Required	Description
datasphereUri	string	yes	Datasphere URI to create the page in
title	string	yes	Page title
content	string	no	Full page HTML. Write a comprehensive, research-grade article (aim for 800–2500+ words): use ALL research findings and data from the conversation, embed any data cards from create_data_card tool results using , cite every fact with inline badges + ONE at the end, use / / // . NEVER write a stub — always draft the complete, fully-developed document.
folderName	string	no	Top-level folder name to file under (auto-created if missing). Only resolves root folders — for a sub-folder use docFolderId.
docFolderId	string	no	Exact folder ID to file under (from list_folders/get_folder). Required to target a sub-folder; wins over folderName.
status	string	no	Page status — ALWAYS default to DRAFT unless user explicitly says publish
isPubliclyVisible	boolean	no	If true, page is accessible on the public internet without login (SEO-indexed). Default false.

get_page — Fetch Page

Fetches the full content of a single page by its slug. Use when the user asks to read, view, or discuss a specific page.

CRITICAL: datasphereUri is the short URI slug (e.g. "marcus-johnson"), NOT a full URL. slug is the page slug (e.g. "getting-started"), NOT a full path. If you can see the page in the current ARIA elements or page context, extract the slug from there instead of calling list_pages.

Field	Type	Required	Description
datasphereUri	string	yes	Datasphere URI
slug	string	yes	Page slug

list_pages — Pages

Lists pages (docs) in a datasphere.

CRITICAL: datasphereUri is the short URI slug (e.g. "marcus-johnson", "bitcoin"), NOT a full URL path. Never pass "/app/marcus-johnson/docs/..." — just pass "marcus-johnson". If you know which datasphere from conversation context, pass it directly. Don't call without datasphereUri.

• Positive flow: "Here are the pages in [Datasphere] — [brief note on count/folders]. Want to open one, create a new page, or search for something specific?"
• Negative flow: "No pages in [Datasphere] yet. Want me to create the first one?"

Field	Type	Required	Description
datasphereUri	string	yes	URI of the datasphere
folder	string	no	Filter by folder name

update_page — Update Page

Updates an existing page. Guide:

1. List pages first (list_pages) so the user can pick.
2. Ask what to change — title, content, status, folder, public visibility.
3. If updating content: read the existing page content first (get_page) so you don't blow away embedded data cards, datasets, or images. Splice in your changes while PRESERVING the custom blocks.
4. Show a preview of the diff before confirming.

URLS TO SURFACE AFTER SUCCESS: (same rules as create_page)

• Edit: /app/{datasphereUri}/docs/{pageId}/edit
• Public (if PUBLISHED + isPubliclyVisible): /docs/{datasphereUri}/{slug}
• Internal (if PUBLISHED only): /app/{datasphereUri}/docs/{slug}

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

PAGE STRUCTURE — STORYTELLING WITH DATA

A great dataspheres page is a STORY backed by live data. When synthesizing search results, datasets, and data cards into a page, follow this structure:

1. Opening (1-2 paragraphs) — a strong

   Overview

   or

   What this page is about

   , followed by 1-2 punchy

   paragraphs that frame the question, stake, or insight. Lead with the most important takeaway — don't bury the lede.

2. Context section (optional) —

   Background

   or

   Why it matters

   . 2-3

   paragraphs of narrative, possibly with one

   citing a source.

3. Data sections — one or more

   {metric or finding}

   blocks.
   • Each section should have:
     • A

       introducing what the chart shows and why it matters

     • A dataCard or datasetEmbed block
     • A

       interpreting the result in plain English

   • Vary the chart types across sections (don't embed 4 bar charts in a row).

4. Narrative pull-quotes — use

   to embed quoted passages from linked URLs or search results. Always cite the source in an inside a

   .

5. Conclusion —

   Takeaways

   or

   What this means

   , 1-2 paragraphs that wrap up the narrative and connect the data back to the opening.

6. CTA / next steps —

   What to do next

   , either a short

   or a

   with 2-4 action items. Link to related dataspheres, pages, or external resources with .

RULES:

• Every page has a clear beginning, middle, and end.
• Every embedded data card or dataset has a short

  above it explaining the "why".

• Cite EVERY external source with a

  + attribution or a tiptap-link.

• Keep individual paragraphs under 80 words — readers skim.
• Use sparingly for emphasis, not decoration.

TIPTAP PAGE HTML — AVAILABLE NODES

The page editor is TipTap. Generate HTML that uses EXACTLY these node patterns. The editor parses the HTML and hydrates each custom block into a live React component.

heading

Section heading. Levels 1-3 only. Pattern:

|

|

{text}</h?> Example:

Key Findings

When to use: Start every major section with

. Use

for the page title only. Use

for sub-sections. Rules: Never nest headings; Never use

or deeper

paragraph

A body-text block. Pattern:

{text, possibly with inline formatting}

Example:

The data shows a significant upward trend since 2018.

When to use: The default block for prose. Use between headings, around embeds, and as transitions.

bulletList

Unordered list of items. Pattern:

• ...

...
Example:

• First point

• Second point

When to use: Non-sequential items: key takeaways, feature lists, bullet summaries. Rules: List items MUST wrap their text in

; Use the exact class "tiptap-bullet-list" on the

orderedList

Numbered list. Pattern:

1. ...

...
Example:

1. Step one

2. Step two

When to use: Sequential steps, ranked lists, numbered procedures. Rules: List items MUST wrap their text in

; Use the exact class "tiptap-ordered-list" on the

blockquote

Quoted passage, typically with a citation. Pattern:

{quote text}

— {source}

Example:

"Worldbuilding is the foundation of every great story."

— From a 2023 interview

When to use: Embedding a narrative excerpt from a search result or linked URL. Always attribute the source in an tag inside a

.

horizontalRule

Section divider. Pattern:

---

Example:

---

When to use: Between major logical sections when a heading feels too strong.

codeBlock

Preformatted code / data snippet. Pattern:

{code text}

Example:

SELECT * FROM events WHERE year = 2024;

When to use: Showing SQL, JSON, or code verbatim.

table

Classic HTML table. Resizable in the editor. Pattern:

......

...

Example:

Name	Count
Alpha	42

When to use: Showing tabular data that does NOT need to be a live query. For live aggregations use dataCard or datasetEmbed instead. Rules: Every cell MUST wrap text in

; Use the exact classes: tiptap-table, tiptap-table-row, tiptap-table-cell, tiptap-table-header

customImage

Figure-wrapped image with caption + optional link. Pattern:

{caption} Required attrs: src, alt Example: Monthly active users over five years When to use: Photos, screenshots, uploaded images, hero visuals.

customAudio

Audio player with title + description. Pattern:

...
Required attrs: data-src Example:
When to use: Embedding podcasts, voice notes, audio clips.

embed

External embed — YouTube, Twitter/X, Vimeo, CodePen, Spotify, etc. Renders as an iframe figure. Pattern:

Required attrs: data-url Example: When to use: Embedding an external video, tweet, or interactive widget via its canonical URL. The editor resolves the provider automatically.

imageRow

Row of 2-4 side-by-side images. Pattern:

{two or more customImage figures}
Example:

When to use: Before / after comparisons, gallery rows, side-by-side screenshots.

embedRow

Row of 2-4 side-by-side embeds (e.g. two YouTube videos). Pattern:

{two or more embed figures}
Example:
When to use: Side-by-side video comparisons, multi-platform tweet rows.

mermaid

Mermaid diagram block — renders a diagram from mermaid.js source. Pattern:

Required attrs: data-source Example:
When to use: Flowcharts, sequence diagrams, org charts, architecture diagrams. Mermaid syntax only — no images.

datasetEmbed

Live dataset preview — renders an interactive table of the dataset rows. Always fresh, always the latest data. Pattern:

[Dataset: {id}]
Required attrs: data-type="datasetEmbed", data-dataset-id, data-datasphere-id Example:
[Dataset: cmnosy7ev00pyp3loqqdk2h0m]
When to use: When the user wants the raw dataset rows visible in the page. Use this for reference tables, glossaries, or any time the READER needs to browse rows. Rules: data-dataset-id must be a real dataset id you have seen via list_datasets or a tool result; data-datasphere-id is required — the renderer needs it for auth; The inner text [Dataset: {id}] is a placeholder the editor discards on hydration

dataCard

Live data card — renders an interactive chart (bar, line, pie, scatter, etc.) that re-executes its formula on every view. New rows in the source dataset automatically propagate to the rendered chart. Pattern:

[Data Card: {id}]
Required attrs: data-type="dataCard", data-datacard-id, data-dataset-id, data-datasphere-id Example:
[Data Card: cmnpe7tj0000cp356eam375ec]
When to use: Showing a chart the user has already created (via the Data Cards builder) or that you just created via create_data_card. This is the PRIMARY way to embed quantitative narrative into a page. Rules: data-datacard-id must come from list_data_cards, search_data_cards, or a fresh create_data_card result; All three data-* ids are required — the renderer needs them to fetch the card and verify auth; Place a short

explanation ABOVE each data card so the reader knows what the chart shows; Don't include more than 4 data cards in one page — readers get chart fatigue

experienceBlock

Interactive scroll/slide experience block — advanced. Only use if explicitly requested. Pattern:

Example: (advanced — ask the user before using) When to use: Only when the user explicitly says "make this a presentation" or "slide experience".

citation ⭐ ANTI-HALLUCINATION

Inline source citation badge [N] — links a claim to a numbered reference in the appendix. Pattern: ^[{N}] Required attrs: data-type="citation", data-citation-n, data-citation-url Example:

The global AI market reached $207B in 2023^[1].

When to use: After ANY factual claim from a web_search result. Place immediately after the claim. Number sequentially from 1. Rules: data-citation-n must be sequential integers from 1; data-citation-title and data-citation-excerpt must be URL-encoded; Always pair with a citationAppendix block; Use real URLs from web_search results — never invent URLs

citationAppendix ⭐ ANTI-HALLUCINATION

Auto-generated reference list block — appears at the bottom, lists all citations. Pattern:

[Citation References]
Required attrs: data-type="citationAppendix" Example:
[Citation References]
When to use: Add exactly ONE at the very end of every page that contains citation badges. Rules: Only ONE citationAppendix per document; Place at the very end; Required whenever you use citation badges

mention

@-mention of a datasphere (inline pill that links to the datasphere). Pattern: @{name} Example: @CLO When to use: Inline reference to a datasphere by name inside a

.

strong

Inline bold text. Pattern: {text} Example:

This is important.

When to use: Emphasizing a key term, metric, or finding inline.

em

Inline italic text. Pattern: {text} Example:

See the Communicating Design book.

When to use: Titles of works, foreign phrases, light emphasis.

link

Inline hyperlink. Pattern: {text} Example:

Source: Example Research

When to use: Citing a source, linking to an external reference. Always include class="tiptap-link".

CRITICAL REMINDERS

• Every custom block (dataCard, datasetEmbed, mermaid, embed, customImage, citationAppendix, etc.) is a
  or with data-type="...". Never omit the data-type.
• For dataCard and datasetEmbed: the ids (data-datacard-id, data-dataset-id, data-datasphere-id) MUST be real. Get them from list_data_cards / search_data_cards / create_data_card tool results. Never invent ids.
• The placeholder inner text (e.g. [Data Card: id]) is fine — the editor discards it on hydration. It just needs to be non-empty.
• CITATIONS: Use <span data-type="citation"> after EVERY factual claim from web_search results. Add ONE <div data-type="citationAppendix"> at the very end. This is the primary anti-hallucination mechanism. URL-encode data-citation-title and data-citation-excerpt.
• Output ONE HTML string. No markdown, no ```html fences, no explanation outside the HTML. ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Field	Type	Required	Description
datasphereUri	string	yes	Datasphere URI
slug	string	yes	Page slug to update
title	string	no	New title
content	string	no	Full updated HTML. Write comprehensive, research-grade content (800–2500+ words where appropriate). Preserve existing <div data-type="dataCard" ...> embeds; add new ones from create_data_card results in conversation if relevant. Use / / /.
status	string	no	Status
isPubliclyVisible	boolean	no	Public access?
folderName	string	no	Move to a top-level folder by name (empty string = root). For a sub-folder use docFolderId.
docFolderId	string	no	Move to this exact folder ID (from list_folders/get_folder). null = root; wins over folderName.