diff --git a/apps/website/app/(docs)/docs/_components/DocsPageTemplate.tsx b/apps/website/app/(docs)/docs/_components/DocsPageTemplate.tsx
index 6bd6a9355..c86be7cad 100644
--- a/apps/website/app/(docs)/docs/_components/DocsPageTemplate.tsx
+++ b/apps/website/app/(docs)/docs/_components/DocsPageTemplate.tsx
@@ -3,6 +3,7 @@ import { useMDXComponents } from "mdx-components";
 
 type DocsPageTemplateProps = Omit<EvaluateResult, "default"> & {
   children: React.ReactNode;
+  isUseCasePage?: boolean;
 };
 
 const hasPrimaryHeading = (sourceCode: string): boolean =>
@@ -10,6 +11,7 @@ const hasPrimaryHeading = (sourceCode: string): boolean =>
 
 const DocsPageTemplate = ({
   children,
+  isUseCasePage,
   metadata,
   sourceCode,
   ...wrapperProps
@@ -25,7 +27,11 @@ const DocsPageTemplate = ({
   return (
     <Wrapper metadata={metadata} sourceCode={sourceCode} {...wrapperProps}>
       {!hasPrimaryHeading(sourceCode) && <H1>{metadata.title}</H1>}
-      {children}
+      {isUseCasePage ? (
+        <div className="use-case-content">{children}</div>
+      ) : (
+        children
+      )}
     </Wrapper>
   );
 };
diff --git a/apps/website/app/(docs)/docs/obsidian/[[...mdxPath]]/page.tsx b/apps/website/app/(docs)/docs/obsidian/[[...mdxPath]]/page.tsx
index f4600feb1..c5a2cb654 100644
--- a/apps/website/app/(docs)/docs/obsidian/[[...mdxPath]]/page.tsx
+++ b/apps/website/app/(docs)/docs/obsidian/[[...mdxPath]]/page.tsx
@@ -39,7 +39,10 @@ const Page = async ({ params }: DocsPageProps): Promise<React.ReactElement> => {
     const { default: MDXContent, ...wrapperProps } = result;
 
     return (
-      <DocsPageTemplate {...wrapperProps}>
+      <DocsPageTemplate
+        {...wrapperProps}
+        isUseCasePage={mdxPath?.[0] === "use-cases"}
+      >
         <MDXContent params={{ mdxPath: mdxPath ?? [] }} />
       </DocsPageTemplate>
     );
diff --git a/apps/website/app/(docs)/docs/obsidian/navigation.ts b/apps/website/app/(docs)/docs/obsidian/navigation.ts
index dbb6008b3..750457f47 100644
--- a/apps/website/app/(docs)/docs/obsidian/navigation.ts
+++ b/apps/website/app/(docs)/docs/obsidian/navigation.ts
@@ -67,6 +67,10 @@ export const navigation: NavigationList = [
         title: "Querying your discourse graph",
         href: `${ROOT}/querying-discourse-graph`,
       },
+      {
+        title: "Experiment tracking",
+        href: `${ROOT}/experiment-tracking`,
+      },
     ],
   },
 
@@ -83,20 +87,20 @@ export const navigation: NavigationList = [
     title: "🚢 Use cases",
     links: [
       {
-        title: "Literature review",
-        href: `${ROOT}/literature-reviewing`,
+        title: "Build and Utilize a Personal Knowledge Base",
+        href: `${ROOT}/build-utilize-personal-knowledge-base`,
       },
       {
-        title: "Research notes",
-        href: `${ROOT}/research-roadmapping`,
+        title: "Synthesize Insights from the Literature",
+        href: `${ROOT}/synthesize-insights-from-literature`,
       },
       {
-        title: "Reading clubs & seminars",
-        href: `${ROOT}/reading-clubs`,
+        title: "Share your ideas & research",
+        href: `${ROOT}/share-your-ideas-and-research`,
       },
       {
-        title: "Lab notebooks",
-        href: `${ROOT}/lab-notebooks`,
+        title: "Track your Projects and Experiments",
+        href: `${ROOT}/track-your-projects-and-experiments`,
       },
     ],
   },
diff --git a/apps/website/app/(docs)/docs/roam/[[...mdxPath]]/page.tsx b/apps/website/app/(docs)/docs/roam/[[...mdxPath]]/page.tsx
index 42180f867..f8e24002f 100644
--- a/apps/website/app/(docs)/docs/roam/[[...mdxPath]]/page.tsx
+++ b/apps/website/app/(docs)/docs/roam/[[...mdxPath]]/page.tsx
@@ -39,7 +39,10 @@ const Page = async ({ params }: DocsPageProps): Promise<React.ReactElement> => {
     const { default: MDXContent, ...wrapperProps } = result;
 
     return (
-      <DocsPageTemplate {...wrapperProps}>
+      <DocsPageTemplate
+        {...wrapperProps}
+        isUseCasePage={mdxPath?.[0] === "use-cases"}
+      >
         <MDXContent params={{ mdxPath: mdxPath ?? [] }} />
       </DocsPageTemplate>
     );
diff --git a/apps/website/app/(docs)/docs/roam/navigation.ts b/apps/website/app/(docs)/docs/roam/navigation.ts
index c1f106398..2f69aa608 100644
--- a/apps/website/app/(docs)/docs/roam/navigation.ts
+++ b/apps/website/app/(docs)/docs/roam/navigation.ts
@@ -49,6 +49,10 @@ export const navigation: NavigationList = [
         title: "Sharing",
         href: `${ROOT}/sharing-discourse-graph`,
       },
+      {
+        title: "Experiment tracking",
+        href: `${ROOT}/experiment-tracking`,
+      },
     ],
   },
   {
@@ -68,24 +72,20 @@ export const navigation: NavigationList = [
     title: "🚢 Use cases",
     links: [
       {
-        title: "Literature reviewing",
-        href: `${ROOT}/literature-reviewing`,
-      },
-      {
-        title: "Zettelkasten",
-        href: `${ROOT}/enhanced-zettelkasten`,
+        title: "Build and Utilize a Personal Knowledge Base",
+        href: `${ROOT}/build-utilize-personal-knowledge-base`,
       },
       {
-        title: "Reading clubs / seminars",
-        href: `${ROOT}/reading-clubs`,
+        title: "Synthesize Insights from the Literature",
+        href: `${ROOT}/synthesize-insights-from-literature`,
       },
       {
-        title: "Lab notebooks",
-        href: `${ROOT}/lab-notebooks`,
+        title: "Share your ideas & research",
+        href: `${ROOT}/share-your-ideas-and-research`,
       },
       {
-        title: "Product / research roadmapping",
-        href: `${ROOT}/research-roadmapping`,
+        title: "Track your Projects and Experiments",
+        href: `${ROOT}/track-your-projects-and-experiments`,
       },
     ],
   },
diff --git a/apps/website/app/(docs)/docs/roam/pages/build-utilize-personal-knowledge-base.md b/apps/website/app/(docs)/docs/roam/pages/build-utilize-personal-knowledge-base.md
new file mode 100644
index 000000000..f6ded4019
--- /dev/null
+++ b/apps/website/app/(docs)/docs/roam/pages/build-utilize-personal-knowledge-base.md
@@ -0,0 +1,8 @@
+---
+title: "Build and Utilize a Personal Knowledge Base"
+date: "2026-06-29"
+author: ""
+published: true
+---
+
+Description coming soon!
diff --git a/apps/website/app/(docs)/docs/roam/pages/experiment-tracking.md b/apps/website/app/(docs)/docs/roam/pages/experiment-tracking.md
new file mode 100644
index 000000000..57e253c40
--- /dev/null
+++ b/apps/website/app/(docs)/docs/roam/pages/experiment-tracking.md
@@ -0,0 +1,8 @@
+---
+title: "Experiment Tracking"
+date: "2026-06-29"
+author: ""
+published: true
+---
+
+TODO: Add content for this guide.
diff --git a/apps/website/content/obsidian/use-cases/lab-notebooks.md b/apps/website/app/(docs)/docs/roam/pages/share-your-ideas-and-research.md
similarity index 52%
rename from apps/website/content/obsidian/use-cases/lab-notebooks.md
rename to apps/website/app/(docs)/docs/roam/pages/share-your-ideas-and-research.md
index 9bdfa548c..a66aa276a 100644
--- a/apps/website/content/obsidian/use-cases/lab-notebooks.md
+++ b/apps/website/app/(docs)/docs/roam/pages/share-your-ideas-and-research.md
@@ -1,6 +1,6 @@
 ---
-title: "Lab notebooks"
-date: "2025-01-01"
+title: "Share your ideas & research"
+date: "2026-06-29"
 author: ""
 published: true
 ---
diff --git a/apps/website/app/(docs)/docs/roam/pages/synthesize-insights-from-literature.md b/apps/website/app/(docs)/docs/roam/pages/synthesize-insights-from-literature.md
new file mode 100644
index 000000000..da844d5f4
--- /dev/null
+++ b/apps/website/app/(docs)/docs/roam/pages/synthesize-insights-from-literature.md
@@ -0,0 +1,8 @@
+---
+title: "Synthesize Insights from the Literature"
+date: "2026-06-29"
+author: ""
+published: true
+---
+
+Description coming soon!
diff --git a/apps/website/app/(docs)/docs/roam/pages/track-your-projects-and-experiments.md b/apps/website/app/(docs)/docs/roam/pages/track-your-projects-and-experiments.md
new file mode 100644
index 000000000..7de0006ba
--- /dev/null
+++ b/apps/website/app/(docs)/docs/roam/pages/track-your-projects-and-experiments.md
@@ -0,0 +1,8 @@
+---
+title: "Track your Projects and Experiments"
+date: "2026-06-29"
+author: ""
+published: true
+---
+
+Description coming soon!
diff --git a/apps/website/app/(nextra)/nextra-css.css b/apps/website/app/(nextra)/nextra-css.css
index f62776bda..228dd8dbe 100644
--- a/apps/website/app/(nextra)/nextra-css.css
+++ b/apps/website/app/(nextra)/nextra-css.css
@@ -4,6 +4,104 @@
   --nextra-content-width: 90rem;
 }
 
+.use-case-content img {
+  border: 1px solid #cbcbcb;
+}
+
+/* Node tags — soft pill: tinted background, colored border/text, matching
+   the candidate-tag styling from the Roam graph's roam/css (screenshots).
+   hyp/clm share green and evd/res share red since the docs treat those pairs
+   as equivalent (Results Graph vs. Discourse Graph dialect). */
+.node-tag {
+  display: inline-block;
+  padding: 1px 10px;
+  border-radius: 999px;
+  font-size: 0.85em;
+  font-weight: 500;
+  white-space: nowrap;
+  background-color: color-mix(in srgb, var(--node-tag-color, #adb5bd) 15%, transparent);
+  border: 1px solid color-mix(in srgb, var(--node-tag-color, #adb5bd) 45%, transparent);
+  color: color-mix(in srgb, var(--node-tag-color, #adb5bd) 75%, #000);
+}
+
+.node-tag[data-type="que"] {
+  --node-tag-color: #e8590c;
+}
+.node-tag[data-type="hyp"] {
+  --node-tag-color: #40c057;
+}
+.node-tag[data-type="evd"] {
+  --node-tag-color: #e03131;
+}
+.node-tag[data-type="res"] {
+  --node-tag-color: #e03131;
+}
+.node-tag[data-type="clm"] {
+  --node-tag-color: #40c057;
+}
+.node-tag[data-type="iss"] {
+  --node-tag-color: #ae3ec9;
+}
+.node-tag[data-type="src"] {
+  --node-tag-color: #495057;
+}
+
+/* Callouts */
+.callout {
+  border: 1px solid color-mix(in srgb, var(--callout-color) 30%, transparent);
+  border-left: 4px solid var(--callout-color);
+  border-radius: 6px;
+  margin: 1.25rem 0;
+  overflow: hidden;
+}
+
+.callout-title {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  padding: 8px 14px;
+  background: color-mix(in srgb, var(--callout-color) 12%, transparent);
+  font-weight: 600;
+  font-size: 0.9em;
+  color: color-mix(in srgb, var(--callout-color) 60%, #000);
+}
+
+.callout-title-text {
+  flex: 1;
+  min-width: 0;
+}
+
+.callout-fold {
+  margin-left: auto;
+  transition: transform 0.2s ease;
+  opacity: 0.7;
+}
+
+details.callout[open] .callout-fold {
+  transform: rotate(180deg);
+}
+
+details.callout > summary {
+  cursor: pointer;
+  list-style: none;
+}
+
+details.callout > summary::-webkit-details-marker {
+  display: none;
+}
+
+.callout-body {
+  padding: 10px 14px;
+  font-size: 0.9em;
+}
+
+.callout-body > *:first-child {
+  margin-top: 0;
+}
+.callout-body > *:last-child {
+  margin-bottom: 0;
+}
+
 html:not(.dark) .nextra-search-results a {
   color: #1f1f1f !important;
 }
diff --git a/apps/website/content/obsidian/use-cases/_meta.ts b/apps/website/content/obsidian/use-cases/_meta.ts
index c193a603e..a05edbcf1 100644
--- a/apps/website/content/obsidian/use-cases/_meta.ts
+++ b/apps/website/content/obsidian/use-cases/_meta.ts
@@ -1,10 +1,13 @@
 import type { MetaRecord } from "nextra";
 
 const meta: MetaRecord = {
-  "literature-reviewing": "Literature review",
-  "research-roadmapping": "Research notes",
-  "reading-clubs": "Reading clubs and seminars",
-  "lab-notebooks": "Lab notebooks",
+  "build-utilize-personal-knowledge-base":
+    "Build and Utilize a Personal Knowledge Base",
+  "synthesize-insights-from-literature":
+    "Synthesize Insights from the Literature",
+  "share-your-ideas-and-research": "Share your ideas & research",
+  "track-your-projects-and-experiments": "Track your Projects and Experiments",
+  "experiment-tracking": "Experiment Tracking",
 };
 
 export default meta;
diff --git a/apps/website/content/obsidian/use-cases/build-utilize-personal-knowledge-base.md b/apps/website/content/obsidian/use-cases/build-utilize-personal-knowledge-base.md
new file mode 100644
index 000000000..4eb17a114
--- /dev/null
+++ b/apps/website/content/obsidian/use-cases/build-utilize-personal-knowledge-base.md
@@ -0,0 +1,177 @@
+---
+title: "Build and Utilize a Personal Knowledge Base"
+date: "2026-06-29"
+author: ""
+published: true
+---
+
+## Turn your tsundoku pile into a knowledge base with discourse graphs
+
+![tsundoku pile](/docs/guides/obsidian/tsundoku.png)
+_Candidate for saddest short poem_
+
+Many researchers have established pipeline for accumulating potentially useful evidence and insights, but fewer ways of managing and exploiting these resources.
+
+The [discourse graph protocol](/docs/obsidian/fundamentals/what-is-a-discourse-graph) can be used to drive more intentional note taking and to accentuate serendipitous discovery within existing knowledge bases.
+
+## Startup
+
+If you're already using Obsidian or Roam Research or another PKM platform, your first question might be _"Can I integrate discourse graphs into my existing knowledge base?"_
+
+For Obsidian (& Roam), the answer is **yes**. Your discourse nodes can coexist with your existing graph: the two major considerations for a smooth integration are _organizational preferences_ and _vault size_.
+
+### Vault organization
+
+If you are a **"folder-centric"** Obsidian user, we recommend keeping your discourse graph an folder within your vault.
+
+![left sidebar](/docs/guides/obsidian/left-sidebar.png)
+
+The Discourse Graph plugin lets you configure a default folder (or per-node-type folders) for discourse nodes in its settings, independent of Obsidian's own "Default location for new notes" setting.
+
+So Obsidian's **"Default location for new notes"** setting (in `Settings → Files & Links`) can control where non-discourse notes go while the plugin routes new nodes to its own folder.
+
+```
+vault/
+├── Discourse Graph/
+│   ├── Questions/
+│   ├── Claims/
+│   └── Evidence/
+└── Notes/          ← regular notes land here
+```
+
+As you convert more of your existing notes to discourse nodes via the plugin's **"Convert note to discourse node"** command, move these notes to the configured discourse folder.
+
+If you're a **"graph-centric"** vault user, following Obsidian wiki-linking and discourse graph [relation-creating](/docs/obsidian/core-features/creating-discourse-relationships) practices will allow you to navigate a vault of arbitrary size without getting lost in unrelated material.
+
+As you build out your graph, your discourse nodes will begin to form "paths of desire" around the central Questions in your vault.
+
+![graph view](/docs/guides/obsidian/graph-view02.png)
+
+> [!tip] Graph Gardening: Add a random note picker to your vault to get in the habit of reviewing older notes for potential conversion to discourse nodes.
+
+### Managing a large vault
+
+"Vanilla" Obsidian accommodates very large vaults with very few issues. Vault size usually only becomes a problem when you're running many script-heavy plugins at once.
+If you're an Obsidian power user you may already be using a plugin like [Dataview](https://blacksmithgu.github.io/obsidian-dataview/) to run queries over your vault. The discourse graph plugin uses [Datacore](https://github.com/blacksmithgu/datacore) to power its queries, which is even more performant in large vaults than Dataview. These two plugins can both be used in the same vault, but we recommend keeping an eye on your plugin count to optimize vault load time.
+
+## Transforming existing notes into discourse nodes
+
+You can transform a variety of file types into discourse nodes:
+
+- [readwise](https://readwise.io/) snippets
+- [memex](https://memex.garden/) imports
+- screenshots
+- captures from the [Obsidian web clipper](https://obsidian.md/clipper).
+- articles from [Zotero](/docs/obsidian/use-cases/synthesize-insights-from-literature), etc.
+
+As long as it can be referenced (`[filename]`) in a markdown file with the appropriate frontmatter, it can be part of your discourse graph.
+
+![Obsidian web clipper](/docs/guides/obsidian/clipping01.png)
+_This web clipping has been converted into a Source_
+
+![image to CLM](/docs/guides/obsidian/img-clm02.png)
+_This web screenshot has been converted into a Claim_
+
+### Best practices for node conversion
+
+The goal of transforming a **note** into a dg **node** is to preserve as much context and information as possible while orienting the content toward the questions animating your research -- or at least positioning it so that it suggests additional discourse nodes.
+
+First, paraphrase the key insight of the note and record the source of the insight. This paraphrase is your new discourse node/filename. The rest of the note will become a **Source** node where the remaining note text can be retained as additional context for the insight. You might extract several discourse nodes or [candidate nodes](/docs/obsidian/core-features/node-tags) from a single web-clipped article, but breaking it out into a single DG node + SRC is enough to get started.
+
+![claim](/docs/guides/obsidian/clm-clip02.png)
+_CLM node with SRC node attributing a blog_
+
+In the above image, you can see the a second related Claim and its Source has already been extracted from the same web clipping. If you decide to pursue this topic further, you've already identified another Source node to investigate (Klein _et al._)
+
+Adding `[[wiki-links]]` to key terms will keep your new node in conversation with the rest of your vault as you build your graph. This can help you to find appropriate [discourse relations](/docs/obsidian/core-features/creating-discourse-relationships) later.
+
+![source](/docs/guides/obsidian/src-node-clip.png)
+_This SRC node from a web clipping is linked to the rest of the vault_
+
+As you go through your vault, you might find that certain sources are accumulating multiple mentions in your graph. Identifying especially productive sources can help you to decide how to allocate your attention.
+
+Of course you may be the author of many of the original notes in your vault -- in that case, we suggest retaining the relevant contextual information on the QUE/CLM/EVD node itself -- but remember to create a Source node for yourself!
+
+![self-cite | 350](/docs/guides/obsidian/drmanhattan.png)
+
+### Progressive formalization
+
+The goal is to gradually convert most of your existing notes into a graph of interlinked CLM, QUE, or EVD nodes.
+
+You can jumpstart the process by identifying [candidate nodes](/docs/obsidian/core-features/node-tags) in your existing notes, and revisiting these notes to decide which nodes should be promoted to full-fledged discourse nodes. The trigger for such a promotion is identifying their relevance to one of your research questions, or finding a potential [discourse relation](/docs/obsidian/core-features/creating-discourse-relationships) elsewhere in your graph.
+
+![the graph](/docs/guides/obsidian/graph-view01.png)
+_So much room for activities!_
+
+## Creating new discourse nodes
+
+Build out your discourse graph by reading with an eye to capturing information relevant to your current questions or that inspires new questions.
+
+![web clipping](/docs/guides/obsidian/new-node01.png)
+_Here's a [web clipping](https://obsidian.md/clipper) captured with an eye to turning it into a CLM node - the Obsidian web clipper helpfully captures the source in the frontmatter_
+
+![claim node](/docs/guides/obsidian/new-node02.png)
+_... and here's the CLM node. Note that it's linked to 3 sources: one named after the article url where the full text is captured, one to the author, & one to the author's institution -- this reflects the organizational preferences of the vault owner; a single SRC node can contain all this information_
+
+This habit of intentional reading is a great way to nudge yourself toward [contributing to the public conversation](/docs/obsidian/use-cases/share-your-ideas-and-research).
+
+![you should start a blog](/docs/guides/obsidian/cat-meme.png)
+
+If you're using a highlighter like [memex](memex.garden) or the [Obsidian web clipper](https://obsidian.md/clipper), you can
+
+1. highlight the relevant text
+2. import it into your vault via the tool's import feature or copy-paste
+3. Select `Convert into` from the file window menu to turn it into a discourse node
+
+![convert menu](/docs/guides/obsidian/convert-menu.png)
+
+![memex highlight](/docs/guides/obsidian/memex-res.png)
+_Result node spotted in the wild_
+
+Similarly, plugins like [Zotsidian](https://github.com/Qiwei-Zhao/zotsidian) enable you to import items from your reference manager pre-formatted as Sources.
+
+![readymade Source](/docs/guides/obsidian/zot-import.png)
+
+After you've captured capture a few ideas, you can mark those that you might want to add to your graph later as [candidate nodes](/docs/obsidian/core-features/node-tags). The _progressive formalization_ ethos of the discourse graph protocol also applies to the process of deciding how to direct your attention: you can have a number of leads on potential projects active at once, and decide which ones to curate further later.
+
+![bullet journal](/docs/guides/obsidian/bullet-journal.png)
+_Bullet Journal with candidate nodes in a [Daily Notes](https://obsidian.md/help/plugins/daily-notes) page_
+
+## Searching & Querying your vault
+
+### Datacore
+
+The discourse graph plugin uses the [Datacore plugin](https://github.com/blacksmithgu/datacore) to power its search & query features. Datacore can read inline fields and text in addition to frontmatter and display them in interactive, live-updating components. The catch is that it requires React/JSX code blocks, a departure from the human-readable " just a text file" ethos that many Obsidian users prefer.
+
+Used judiciously, Datacore is very powerful for searching and creating logs and task lists, and for automatically routing items to your attention. It can also be used to create custom widgets that execute frequently-used scripts, like those in this vault for automatically creating a named Discourse Canvas or aliasing a node title.
+
+![alt text](/docs/guides/obsidian/bases+datacore.png)
+_The template depicted here includes one Base and two Datacore features: an aliasing widget and a log widget_
+
+### Bases
+
+Bases are Obsidian's native database layer. They can be used to filter your notes by frontmatter property. They do not require any code to maintain, but they cannot be used to peer into note content: this limitation makes the design of your notes' frontmatter content especially important.
+
+![alt text](/docs/guides/obsidian/source-base01.png)
+_Source Base_
+
+### Choices, choices
+
+So when should you use Bases vs Datacore? The following table can help you develop a sense for the appropriate tool:
+
+| Task                                                             | Tool     |
+| ---------------------------------------------------------------- | -------- |
+| Kanban active lab Projects by Status                             | Bases    |
+| Source/Evidence intake triage                                    | Bases    |
+| Count EVD per CLM                                                | Bases    |
+| simple self-serve dashboards                                     | Bases    |
+| Modeling Supports/Opposes as reified, queryable relations        | Datacore |
+| Reading Evidence bundles nested as sections in one file          | Datacore |
+| Anything using inline (`::`) fields from a synced/exported vault | Datacore |
+| Custom widgets                                                   | Datacore |
+
+## What else would you like to do?
+
+- [Synthesize Insights from the Literature](/docs/obsidian/use-cases/synthesize-insights-from-literature)
+- [Track your Projects and Experiments](/docs/obsidian/use-cases/track-your-projects-and-experiments)
+- [Share your ideas & research](/docs/obsidian/use-cases/share-your-ideas-and-research)
diff --git a/apps/website/content/obsidian/use-cases/experiment-tracking.md b/apps/website/content/obsidian/use-cases/experiment-tracking.md
new file mode 100644
index 000000000..7ae2a4d2b
--- /dev/null
+++ b/apps/website/content/obsidian/use-cases/experiment-tracking.md
@@ -0,0 +1,57 @@
+---
+title: "Experiment Tracking"
+date: "2026-06-29"
+author: ""
+published: true
+---
+
+# How to use Experiments
+
+The **Experiment** is a container for your day-to-day work exploring a **Hypothesis.** It consists of an **intervention** and a **metric** used to track the result of that intervention. The **Result** is a statement of your observations regarding that intervention in terms of the appropriate metric.
+
+Making an experiment page helps you track multiple days' work and reflect on your progress towards your experiment target.
+Ideally the target is a **Hypothesis** you are testing, and the experiment page is a space to document and reflect on **candidate results** for that hypothesis.
+
+### A quick word on candidate nodes
+
+**Candidate Results** are preliminary observations attached to a particular experiment. They might be first impressions formed from a certain data artefact. Use this tag to mark candidate results: <nodetag type="res" />
+
+**Candidate Issues** surface potential problems or future experiments. Use this tag to mark candidate issues: <nodetag type="iss" />
+
+When you're more confident in the observation, you can use the "Create Discourse Node" popup to convert the candidate result into a proper Result. This will affect where the Result appears in queries and its appearance on your Project Canvas. It will also give you a warm sense of accomplishment (this can be done to mature all candidate node types).
+
+## Creating experiments
+
+You can create a new experiment by
+
+1. Creating a new note and applying the Experiment Template from the Templater menu in the left sidebar
+
+![templater flow](/docs/guides/obsidian/create-exp01.png)
+
+2. Navigating to your "Experiments" base in the "Bases" folder and selecting "+ New"
+
+![bases flow](/docs/guides/obsidian/create-exp02.png)
+
+3. Using any of the methods to create nodes (Remember, an Experiment is a type of **Source**)
+
+## Experiment relations
+
+As a **Source** node, the **Experiment** has a special relationship to **Result** nodes: the **Experiment** _produces_ **Results**.
+
+Conversely, each Result in your graph should reference an Experiment.
+
+The Experiment also has a relationship with the **Issue** node, as Experiments _suggest/produce_ **Issues** that may later be developed into Experiments.
+
+![iss-exp relations](/docs/guides/obsidian/iss-exp.png)
+
+## Transforming an Issue into an Experiment
+
+If you decide an Issue captures something worth doing, you can easily change it into an Experiment: the **Issue** template is identical to the **Experiment** template, so you can either duplicate the node and change the name and metadata to use your preferred EXP syntax (e.g. "@measurement -") or simply edit the title of the Issue in place.
+
+![issue example](/docs/guides/obsidian/iss-ex.png)
+
+## What else would you like to do?
+
+- [Synthesize Insights from the Literature](/docs/obsidian/use-cases/synthesize-insights-from-literature)
+- [Build and Utilize a Personal Knowledge Base](/docs/obsidian/use-cases/build-utilize-personal-knowledge-base)
+- [Share your ideas & research](/docs/obsidian/use-cases/share-your-ideas-and-research)
diff --git a/apps/website/content/obsidian/use-cases/literature-reviewing.md b/apps/website/content/obsidian/use-cases/literature-reviewing.md
deleted file mode 100644
index 3aded41b9..000000000
--- a/apps/website/content/obsidian/use-cases/literature-reviewing.md
+++ /dev/null
@@ -1,14 +0,0 @@
----
-title: "Literature reviewing"
-date: "2025-01-01"
-author: ""
-published: true
----
-
-This is currently the most common use case.
-
-Lukas Kawerau (aka Cortex Futura) has a course that integrates the extension into a complete system for academic literature reviewing and writing: [https://learn.cortexfutura.com/p/cite-to-write-v2](https://learn.cortexfutura.com/p/cite-to-write-v2)
-
-Lukas gives a short overview of how in this tweet thread:
-
-[https://x.com/cortexfutura/status/1441795897680011276](https://x.com/cortexfutura/status/1441795897680011276)
diff --git a/apps/website/content/obsidian/use-cases/reading-clubs.md b/apps/website/content/obsidian/use-cases/reading-clubs.md
deleted file mode 100644
index 51c94d6e5..000000000
--- a/apps/website/content/obsidian/use-cases/reading-clubs.md
+++ /dev/null
@@ -1,10 +0,0 @@
----
-title: "Reading clubs"
-date: "2025-01-01"
-author: ""
-published: true
----
-
-Description coming soon!
-
-[Get in touch](mailto:joechan@umd.edu) if you're interested in joining a Reading Club!
diff --git a/apps/website/content/obsidian/use-cases/research-roadmapping.md b/apps/website/content/obsidian/use-cases/research-roadmapping.md
deleted file mode 100644
index 01d12fc3d..000000000
--- a/apps/website/content/obsidian/use-cases/research-roadmapping.md
+++ /dev/null
@@ -1,8 +0,0 @@
----
-title: "Research roadmapping"
-date: "2025-01-01"
-author: ""
-published: true
----
-
-Description coming soon!
diff --git a/apps/website/content/obsidian/use-cases/share-your-ideas-and-research.md b/apps/website/content/obsidian/use-cases/share-your-ideas-and-research.md
new file mode 100644
index 000000000..c9dfd2c15
--- /dev/null
+++ b/apps/website/content/obsidian/use-cases/share-your-ideas-and-research.md
@@ -0,0 +1,101 @@
+---
+title: "Share your ideas & research"
+date: "2026-06-29"
+author: ""
+published: true
+---
+
+You've built your graph, it's a work of beauty and insight -- now you're ready to share what you've learned.
+
+![sharing your graph](/docs/guides/obsidian/dgraph-share.png)
+_Getting eyes on the prize_
+
+- [Share individual nodes](#sharing-your-discourse-nodes)
+- [Share your canvas](#sharing-your-discourse-canvas)
+- [Use your graph as a springboard for drafting a manuscript](#drafting-a-manuscript-from-your-discourse-graph)
+
+## Sharing your discourse nodes
+
+We've just added a feature to allow you to share "live" nodes with your collaborators by publishing them to a shared group space: The **sync and import** feature, currently hidden behind an admin panel.
+
+![](/docs/guides/obsidian/backrooms.jpg)
+_Opening the admin panel_
+
+> [!info] For further information on the sync mode feature, visit [the website docs](/docs/obsidian/advanced-features/sync-and-import). To request access, please email discoursegraphs@gmail.com
+
+## Sharing your discourse canvas
+
+### Presenting your Canvas
+
+Your [canvas](/docs/obsidian/core-features/canvas) can be used to give a PowerPoint- or Figma-like visual overview of your work.
+
+You can start at your motivating Question and move through your hypothesis to your experiments and their results, opening each node in the sidebar to show your audience relevant details.
+
+![canvas walkthrough](/docs/guides/obsidian/canvas-walkthru01.gif)
+_Example Canvas walkthrough_
+
+You can create a "presentation view" for your discourse nodes by adding the material/images you wish to highlight at the top of the page -- the first image on the page is automatically selected as the image that displays on the discourse canvas.
+
+> [!tip] You can [modify your discourse templates](/docs/obsidian/configuration/node-types-templates) to customize your presentation view.
+
+### Exporting your Canvas
+
+You can export a static .png or .svg image of your discourse canvas from the menu.
+
+![export a png or svg](/docs/guides/obsidian/canvas-export%201.png)
+_Canvas export menu_
+
+> [!note] It is not possible at present to export a "live" discourse canvas to another graph.
+
+## Drafting a manuscript from your discourse graph
+
+### Using the canvas as a storyboard
+
+You can use the discourse canvas to organize your ideas for a paper. Your canvas allows you to follow your train of thought from hypothesis formation to hypothesis testing -- including the dead ends. You can see at a glance which sources (references) were crucial to the formulation of certain claims, and which informed the design of your experiments.
+
+If you are targeting a particular journal, you might find it helpful to spatially arrange your discourse nodes according to their ms submission format. This can give you a head start on the drafting stage.
+
+![](/docs/guides/obsidian/ms-canvas.png)
+_Using canvas layers to organize article sections_
+
+The Canvas layout can also be used to spot "gaps" in your argument at a glance, before Reviewer #2 rushes in to fill them with part of their œuvre.
+
+![](/docs/guides/obsidian/gap-spotting.png)
+_Spotting unsupported Claims before Reviewer # 2_
+
+The Canvas is also useful for designing figure panels -- particularly for deciding which figures should be composed into figure panels, and which visual evidence is crucial enough to highlight in the main body of the text vs. the supplementary information.
+
+![figure design](/docs/guides/obsidian/figdesign01.png)
+_Experimental setup in one panel for greatest impact ..._
+
+![figure design](/docs/guides/obsidian/figdesign02.png)
+_While the data speaks for itself_
+
+### Arguing with your graph
+
+Your discourse nodes should be formulated as concisely as possible (remember node = filename). But the rest of the page can be used to construct and elaborate your broader point. The example below links both **Evidence** and **Caveats** related to a **Claim**. In this discourse context, a _Caveat_ is an observation that weakens the claim without necessarily opposing it. Some caveats may be promoted to Evidence that _opposes_ a Claim after further investigation, others may become **Issues**: requests for additional analyses to clarify a point. Anticipating the most salient caveats to each of your claims is a useful preparation for the review stage of your ms submission.
+
+![](/docs/guides/obsidian/graph-argument.png)
+_An example of a claim with caveats_
+
+You can [modify your discourse graph templates](/docs/obsidian/configuration/node-types-templates) to structure key information in a way that facilitates article writing later.
+
+![](/docs/guides/obsidian/graph-argument-evd.png)
+_An example of an Evidence node with methods context_
+
+Discourse nodes are modular and composable and can be re-used in multiple projects. One strategy to maximize composability is to capture "evergreen" information in the node template and add additional project-specific context in the "log" section.
+
+![](/docs/guides/obsidian/node-log.png)
+_In the [Obsidian example vault](https://github.com/DiscourseGraphs/obsidian-lab-example) CLM, HYP, ISS, EXP, & QUE node templates have a "log" section_
+
+## Exporting your graph
+
+Your discourse nodes are markdown notes, and they can be copied, printed, & exported in different formats.
+
+While the **Discourse Node Sync** feature mentioned above is the only fully-supported way of sharing functional discourse nodes, you can get a quick-and-dirty approximation using copy/paste. Importing a "foreign" discourse node into your graph strips it of its relation data, but it can still be recognized as a discourse node if its NodeTypeId exists in your graph. Open the 3-dot menu in the file pane: if the option "Convert Into" exists, it is not recognized as a node, and you can select the type of node you'd like to turn it into.
+
+## What else would you like to do?
+
+- [Build and Utilize a Personal Knowledge Base](/docs/obsidian/use-cases/build-utilize-personal-knowledge-base)
+- [Synthesize Insights from the Literature](/docs/obsidian/use-cases/synthesize-insights-from-literature)
+- [Track your Projects and Experiments](/docs/obsidian/use-cases/track-your-projects-and-experiments)
diff --git a/apps/website/content/obsidian/use-cases/synthesize-insights-from-literature.md b/apps/website/content/obsidian/use-cases/synthesize-insights-from-literature.md
new file mode 100644
index 000000000..e5199d4e4
--- /dev/null
+++ b/apps/website/content/obsidian/use-cases/synthesize-insights-from-literature.md
@@ -0,0 +1,134 @@
+---
+title: "Synthesize Insights from the Literature"
+date: "2026-06-29"
+author: ""
+published: true
+---
+
+> [!tip] This guide makes reference to templates available in an example vault that you can find [here](https://github.com/DiscourseGraphs/obsidian-lab-example)
+
+## Literature Synthesis with discourse graphs
+
+Discourse graphs turn literature synthesis into a **question-directed activity**: instead of merely absorbing disconnected insights from different sources, the discourse graph workflow orients your reading around a central guiding question of your own devising.
+
+- <nodetag type="hyp" />
+  This purpose-driven reading increases engagement with the text and retention of salient data.
+- <nodetag type="hyp" />
+  It also incentivizes reading widely and strategically, as papers from many different authors/fields may have made small but significant contributions to your question.
+
+There's a bit of a chicken-and-egg problem here, as engaging in question-driven analysis of the literature first requires the development of a question, which usually involves at least some loosely-directed exploration. Discourse graphs accommodate both phases of the explore/exploit curve.
+
+![explore/exploit curve](/docs/guides/obsidian/exp-exp.png)
+
+## Building your library of sources
+
+Let's assume that your exploration phase is influenced by the items in your reference manager/personal library. Obsidian offers a variety of plugins for interacting with reference management software.
+
+![ref manager](/docs/guides/obsidian/biblio.png)
+
+The [example vault](https://github.com/DiscourseGraphs/obsidian-lab-example) uses [Zotsidian](https://github.com/Qiwei-Zhao/zotsidian), a Zotero integration plugin with built-in discourse graph support. 🥰
+
+> [!note]- If you like your reference manager, you can keep your reference manager -- they all play well with discourse graphs
+>
+> ![a note from a former president | 250](/docs/guides/obsidian/obama.png)
+
+### Managing literature sources with Zotsidian
+
+- Make sure you have Zotero Desktop ≥ 8 installed and running
+  - In Zotero, go to `Settings / Preferences -> Advanced` and make sure `Allow other applications on this computer to communicate with Zotero` is enabled.
+- Make sure you have citekeys for the Zotero items you want to work with
+  - Install the Better BibTeX (BBT) plugin from https://retorque.re/zotero-better-bibtex/ to automatically generate citekeys
+- [Install Zotsidian](https://github.com/Qiwei-Zhao/zotsidian#install-from-github-release) and enable the plugin
+- check your plugin settings:
+
+![settings | 350](/docs/guides/obsidian/zotsidian-settings.png)
+
+These settings control:
+
+- how to format citations (use `[[double brackets]]` if you want sources to be wiki- linked immediately )
+- where to store newly-created source nodes
+- which template to use
+- whether to show a hover-over infobox when a citation is imported
+
+![hover card](/docs/guides/obsidian/hover.png)
+
+> [!tip] The hovercard is useful when you're creating a lot of Source pages at once but can interfere with other mouse-over operations.
+
+In the example vault the hotkey `Ctrl-Shift-Y` opens a search panel that you can use to search for references in your Zotero library.
+
+![zotsidian search](/docs/guides/obsidian/zot-search.png)
+
+You can also search inline by typing "@..." which will autocomplete with your zotero references after 2 letters.
+
+![inline search](/docs/guides/obsidian/zot-search2.png)
+
+## Using Obsidian Bases to organize your reading
+
+You can also navigate and manage your Sources via Obsidian's built-in **Base** feature. This vault contains an example `Sources.base` where you can organize your Sources by citekey, tags, reading status, target Question, or any other frontmatter property.
+
+![Sources Base](/docs/guides/obsidian/source-base01.png)
+
+## Synthesis workflows
+
+![starting out](/docs/guides/obsidian/exp-exp01.png)
+
+At the outset of the _exploration_ phase, you probably have a topic in mind, or an assertion vaguely in the shape of a question/hypothesis that needs further refinement. You may be reading the literature to understand prior art on the topic. At this point, before a Question or Project has coalesced, some users like to take notes on their **Daily Notes Page**, in the **Media Log**:
+
+![a question](/docs/guides/obsidian/merton-que.png)
+
+> [!note]- As long as you use wikilink syntax
+> ([[mertonMatthewEffectScience1968]]) the notes you make here will be referenced at the bottom of the appropriate Source page so that you can find them later.
+>
+> ![alt text](/docs/guides/obsidian/merton-mentions.png)
+
+The **Media Log** provides a low-overhead way of taking quick notes that can later be converted to structured note-taking.
+
+Reflecting on your reading might inspire you to develop a few candidate questions of your own:
+
+![que-candidate](/docs/guides/obsidian/reader-que.png)
+
+After further reading, you're ready to formalize one of these candidates as the Question driving your literature review:
+
+![formalize q](/docs/guides/obsidian/reader-que02.png)
+
+Now you can read and revisit articles in light of your guiding question, and search for **Claims** _addressing_ the **Question** and **Evidence** _supporting_ those **Claims**.
+
+![new question](/docs/guides/obsidian/new-q.png)
+
+### EVD and CLM mining
+
+As you read the literature, capture claims and evidence relevant to your Question. You can track them on the Question page itself, on the relevant Source page, or anywhere else in your graph -- as long as you tag relevant items with `QUE - {your question}`, these mentions will be linked at the bottom of your Question page.
+
+![media log](/docs/guides/obsidian/med-log-ex.png)
+
+![linked mentions](/docs/guides/obsidian/linked-men.png)
+
+## Integrating findings from the literature with your research
+
+The [Discourse Canvas](/docs/obsidian/core-features/canvas) can be used to assemble your claims and evidence into an overview of the state of the field in relation to your target question.
+
+![lit review](/docs/guides/obsidian/lit-rev.png)
+
+As you collect and assimilate claims and evidence sourced directly from the literature, you will probably develop a few claims of your own that derive from your reading but aren't directly stated in any of the articles. This is your **Synthesis Claim**: an initial position on the question that you'd like to test further.
+
+![lit review](/docs/guides/obsidian/lit-rev02.png)
+
+This synthesis claim can be used as a springboard for more directed reading and the development of an experiment, simulation, or other test.
+
+Once you've metabolized the claim to find testable components, you can add those components to your graph as **Hypotheses** and begin developing **Experiments**.
+
+The multiple layers of the tldraw discourse canvas facilitate organizing your research campaign into _literature review_ and _project planning phases_.
+
+![lit synthesis](/docs/guides/obsidian/lit-synth-canvas.png)
+
+In the discourse graph workflow, these phases are largely simultaneous and mutually informative.
+
+![moving along the curve](/docs/guides/obsidian/exp-exp02.png)
+
+> [!tip] We're developing an LLM-assisted workflow for extracting claims & evidence from the literature. Join us on [Slack](https://join.slack.com/t/discoursegraphs/shared_invite/zt-37xklatti-cpEjgPQC0YyKYQWPNgAkEg) to learn more.
+
+## What else would you like to do?
+
+- [Build and Utilize a Personal Knowledge Base](/docs/obsidian/use-cases/build-utilize-personal-knowledge-base)
+- [Track your Projects and Experiments](/docs/obsidian/use-cases/track-your-projects-and-experiments)
+- [Share your ideas & research](/docs/obsidian/use-cases/share-your-ideas-and-research)
diff --git a/apps/website/content/obsidian/use-cases/track-your-projects-and-experiments.md b/apps/website/content/obsidian/use-cases/track-your-projects-and-experiments.md
new file mode 100644
index 000000000..e1d34eadd
--- /dev/null
+++ b/apps/website/content/obsidian/use-cases/track-your-projects-and-experiments.md
@@ -0,0 +1,74 @@
+---
+title: "Track your Projects and Experiments"
+date: "2026-06-29"
+author: ""
+published: true
+---
+
+> [!tip] This guide makes reference to templates available in an example vault that you can find [here](https://github.com/DiscourseGraphs/obsidian-lab-example)
+
+## How to use Projects
+
+The **Project** acts as a container for multiple activities exploring a particular research question. You can think of it as a conceptual framework to structure a set of Discourse nodes related to a certain research goal.
+
+Use Project pages to
+
+- Prioritize experiments
+- Stay oriented toward and reflect on your progress toward your project target/question
+- Keep relevant resources at hand (links, etc)
+
+The Project structure facilitates the creation of a traditional research narrative and aids in keeping track of all the moving parts that go into a scientific ms.
+
+### Examples
+
+The [discourse graph example vault](https://github.com/DiscourseGraphs/obsidian-lab-example) contains an example project page, `PRJ - Passarine Songbird Cargo Capacity`, that demonstrates a project structure appropriate to experimental research.
+
+![Project Page](/docs/guides/obsidian/prj-page.png)
+
+- The **Resources** section can be used to organize protocols, references, datasets, reagent lists, etc. It's also a convenient spot to pre-register your working **Hypothesis**
+
+- The **Create Discourse Graph Canvas** button will automatically spin up a discourse canvas named after the project for visual organization of your ideas.
+
+- The **Experiments, Issues, & Results** Bases can be used to keep track of multiple active experiments and filter by status, observations made from those experiments (Results), and ideas for future experiments (Issues).
+
+- The **ToDo** list collects tasks tagged `PRJ - Passarine Songbird Cargo Capacity`
+
+- The **Project Log** can be used to keep track of project updates and link project-relevant information from other parts of your graph. Like your **Daily Notes Page**, it has a button function for regular entries.
+
+- the **Project Meeting Notes** log will collect references to this project made in meeting notes throughout this graph.
+
+## How to Create a Project
+
+Create a new project by
+
+1. Creating a new note in the "Projects" Folder and applying the Project Template from the Templater menu in the left sidebar
+
+![templater flow](/docs/guides/obsidian/create-prj01.png)
+
+2. Navigating to your "Projects" base in the "Bases" folder and selecting "+ New"
+
+![bases flow](/docs/guides/obsidian/create-prj02.png)
+
+## The relationship between your Projects and your Discourse Graph
+
+In the example vault, the **Project** is not treated as a discourse node but rather an organizational background for other nodes. You can see how this works in the `Canvas - PRJ - Passarine Songbird Cargo Capacity`: the Project contains 3 **Questions:**
+
+- the original motivating question: `QUE - Can a 5 ounce bird carry a one-pound coconut?`
+- a question that arose during the course of the initial investigation: `QUE - what is the airspeed velocity of an unladen swallow?`
+- and a sub-question informing that second question: `QUE - African or European?`
+
+These three Questions are all part of the same work package, and while their respective edges may eventually meet, we're not going to force it.
+
+## The relationship between your Projects and your Experiments
+
+The Project is also the natural container for the **Experiment** node, which is a flavor of the **Source** node for laboratory work. Your Project will probably contain several experiments -- you can see from the `Experiments.base` that each Experiment is associated with a Project via its frontmatter for easier queryability.
+
+![Project-as-container](/docs/guides/obsidian/prj-container.png)
+
+Learn more about creating and tracking experiments [here](/docs/obsidian/core-features/experiment-tracking).
+
+## What else would you like to do?
+
+- [Build and Utilize a Personal Knowledge Base](/docs/obsidian/use-cases/build-utilize-personal-knowledge-base)
+- [Synthesize Insights from the Literature](/docs/obsidian/use-cases/synthesize-insights-from-literature)
+- [Share your ideas & research](/docs/obsidian/use-cases/share-your-ideas-and-research)
diff --git a/apps/website/content/obsidian/welcome/getting-started.md b/apps/website/content/obsidian/welcome/getting-started.md
index 92dcb437a..8b10b5663 100644
--- a/apps/website/content/obsidian/welcome/getting-started.md
+++ b/apps/website/content/obsidian/welcome/getting-started.md
@@ -20,7 +20,7 @@ For more information about Discourse Graphs, check out our website at [https://d
 ## What's Next?
 
 - Learn about [what makes a discourse graph](/docs/obsidian/fundamentals/what-is-a-discourse-graph)
-- Explore [use cases](/docs/obsidian/use-cases/literature-reviewing) for discourse graphs
+- Explore [use cases](/docs/obsidian/use-cases/synthesize-insights-from-literature) for discourse graphs
 - Join our community to share your experience and get help
 
 ## Guides: Jump right in
diff --git a/apps/website/content/roam/guides/_meta.ts b/apps/website/content/roam/guides/_meta.ts
index 071fab45c..05c102fae 100644
--- a/apps/website/content/roam/guides/_meta.ts
+++ b/apps/website/content/roam/guides/_meta.ts
@@ -9,6 +9,7 @@ const meta: MetaRecord = {
   "querying-discourse-graph": "Querying",
   "extending-personalizing-graph": "Extending",
   "sharing-discourse-graph": "Sharing",
+  "experiment-tracking": "Experiment tracking",
 };
 
 export default meta;
diff --git a/apps/website/content/roam/guides/experiment-tracking.md b/apps/website/content/roam/guides/experiment-tracking.md
new file mode 100644
index 000000000..57e253c40
--- /dev/null
+++ b/apps/website/content/roam/guides/experiment-tracking.md
@@ -0,0 +1,8 @@
+---
+title: "Experiment Tracking"
+date: "2026-06-29"
+author: ""
+published: true
+---
+
+TODO: Add content for this guide.
diff --git a/apps/website/content/roam/use-cases/_meta.ts b/apps/website/content/roam/use-cases/_meta.ts
index 18e66e72c..3d232508d 100644
--- a/apps/website/content/roam/use-cases/_meta.ts
+++ b/apps/website/content/roam/use-cases/_meta.ts
@@ -1,11 +1,12 @@
 import type { MetaRecord } from "nextra";
 
 const meta: MetaRecord = {
-  "literature-reviewing": "Literature reviewing",
-  "enhanced-zettelkasten": "Zettelkasten",
-  "reading-clubs": "Reading clubs and seminars",
-  "lab-notebooks": "Lab notebooks",
-  "research-roadmapping": "Product and research roadmapping",
+  "build-utilize-personal-knowledge-base":
+    "Build and Utilize a Personal Knowledge Base",
+  "synthesize-insights-from-literature":
+    "Synthesize Insights from the Literature",
+  "share-your-ideas-and-research": "Share your ideas & research",
+  "track-your-projects-and-experiments": "Track your Projects and Experiments",
 };
 
 export default meta;
diff --git a/apps/website/content/roam/use-cases/build-utilize-personal-knowledge-base.md b/apps/website/content/roam/use-cases/build-utilize-personal-knowledge-base.md
new file mode 100644
index 000000000..f6ded4019
--- /dev/null
+++ b/apps/website/content/roam/use-cases/build-utilize-personal-knowledge-base.md
@@ -0,0 +1,8 @@
+---
+title: "Build and Utilize a Personal Knowledge Base"
+date: "2026-06-29"
+author: ""
+published: true
+---
+
+Description coming soon!
diff --git a/apps/website/content/roam/use-cases/enhanced-zettelkasten.md b/apps/website/content/roam/use-cases/enhanced-zettelkasten.md
deleted file mode 100644
index 36ba3e2c9..000000000
--- a/apps/website/content/roam/use-cases/enhanced-zettelkasten.md
+++ /dev/null
@@ -1,12 +0,0 @@
----
-title: "Enhanced Zettelkasten"
-date: "2025-01-01"
-author: ""
-published: true
----
-
-Maarten Van Doorn has integrated the discourse graph into his take on applying the zettelkasten to his research.
-
-Here is a video overview:
-
-[https://www.youtube.com/watch?v=mNzUAICf4Rk](https://www.youtube.com/watch?v=mNzUAICf4Rk)
diff --git a/apps/website/content/roam/use-cases/literature-reviewing.md b/apps/website/content/roam/use-cases/literature-reviewing.md
deleted file mode 100644
index 3aded41b9..000000000
--- a/apps/website/content/roam/use-cases/literature-reviewing.md
+++ /dev/null
@@ -1,14 +0,0 @@
----
-title: "Literature reviewing"
-date: "2025-01-01"
-author: ""
-published: true
----
-
-This is currently the most common use case.
-
-Lukas Kawerau (aka Cortex Futura) has a course that integrates the extension into a complete system for academic literature reviewing and writing: [https://learn.cortexfutura.com/p/cite-to-write-v2](https://learn.cortexfutura.com/p/cite-to-write-v2)
-
-Lukas gives a short overview of how in this tweet thread:
-
-[https://x.com/cortexfutura/status/1441795897680011276](https://x.com/cortexfutura/status/1441795897680011276)
diff --git a/apps/website/content/roam/use-cases/reading-clubs.md b/apps/website/content/roam/use-cases/reading-clubs.md
deleted file mode 100644
index 51c94d6e5..000000000
--- a/apps/website/content/roam/use-cases/reading-clubs.md
+++ /dev/null
@@ -1,10 +0,0 @@
----
-title: "Reading clubs"
-date: "2025-01-01"
-author: ""
-published: true
----
-
-Description coming soon!
-
-[Get in touch](mailto:joechan@umd.edu) if you're interested in joining a Reading Club!
diff --git a/apps/website/content/roam/use-cases/research-roadmapping.md b/apps/website/content/roam/use-cases/research-roadmapping.md
deleted file mode 100644
index 01d12fc3d..000000000
--- a/apps/website/content/roam/use-cases/research-roadmapping.md
+++ /dev/null
@@ -1,8 +0,0 @@
----
-title: "Research roadmapping"
-date: "2025-01-01"
-author: ""
-published: true
----
-
-Description coming soon!
diff --git a/apps/website/content/roam/use-cases/lab-notebooks.md b/apps/website/content/roam/use-cases/share-your-ideas-and-research.md
similarity index 52%
rename from apps/website/content/roam/use-cases/lab-notebooks.md
rename to apps/website/content/roam/use-cases/share-your-ideas-and-research.md
index 9bdfa548c..a66aa276a 100644
--- a/apps/website/content/roam/use-cases/lab-notebooks.md
+++ b/apps/website/content/roam/use-cases/share-your-ideas-and-research.md
@@ -1,6 +1,6 @@
 ---
-title: "Lab notebooks"
-date: "2025-01-01"
+title: "Share your ideas & research"
+date: "2026-06-29"
 author: ""
 published: true
 ---
diff --git a/apps/website/content/roam/use-cases/synthesize-insights-from-literature.md b/apps/website/content/roam/use-cases/synthesize-insights-from-literature.md
new file mode 100644
index 000000000..da844d5f4
--- /dev/null
+++ b/apps/website/content/roam/use-cases/synthesize-insights-from-literature.md
@@ -0,0 +1,8 @@
+---
+title: "Synthesize Insights from the Literature"
+date: "2026-06-29"
+author: ""
+published: true
+---
+
+Description coming soon!
diff --git a/apps/website/content/roam/use-cases/track-your-projects-and-experiments.md b/apps/website/content/roam/use-cases/track-your-projects-and-experiments.md
new file mode 100644
index 000000000..82d339787
--- /dev/null
+++ b/apps/website/content/roam/use-cases/track-your-projects-and-experiments.md
@@ -0,0 +1,182 @@
+---
+title: "Track your Projects and Experiments"
+date: "2026-06-29"
+author: ""
+published: true
+---
+
+> [!tip] This guide references a [roam example graph](https://roamresearch.com/#/app/template-lab/page/wnEmTP0TK) that you can download and use as a starterpack for creating your own discourse graph
+
+## How to use Projects
+
+A **Project** acts as a container for multiple experiments exploring a particular research question. You can think of it as a conceptual framework to structure a set of Discourse nodes related to a certain research goal.
+
+Use Project pages to:
+
+- Prioritize experiments
+- Keep relevant resources at hand (links, etc.)
+- Stay oriented toward and reflect on your progress toward your project target/question
+
+The Project structure facilitates the creation of a traditional research narrative and aids in keeping track of all the moving parts that go into a scientific ms.
+
+### the project page
+
+You can see the layout of a Project Page in the **Project/Horizontal Dashboard** showcase in the [roam template lab graph](https://roamresearch.com/#/app/template-lab/page/wnEmTP0TK)
+
+> ![!tip]- to create a horizontal dashboard view of 2 or more blocks:
+> place your cursor in their parent (un-indented) block > press `Ctrl-P` to bring up the command palette > select "change block view" > press "h" for horizontal
+
+![](/docs/guides/roam/project-dash.png)
+_Example project page layout using the horizontal block view: click to embiggen_
+
+The _Resources_ section can be used to organize protocols, references, datasets, reagent lists, etc. It's also a convenient spot to pre-register your working **Hypothesis**.
+
+![](/docs/guides/roam/project-page-overview.png)
+_click to embiggen_
+
+The _Experiments, Issues, & Results_ section can be used to keep track of multiple active experiments and filter by status, observations made from those experiments (**Results**), and ideas for future experiments (**Issues**). You can create new experiments using the Smartblock in this section.
+
+_Project Meeting Notes_ can be used to keep track of project updates and link project-relevant information from other parts of your graph. Like your _Daily Notes Page_, it has a Smartblock function for regular entries.
+
+The _Project Canvas_ Smartblock first creates and then navigates to a [Canvas](https://roamresearch.com/#/app/template-lab/page/tAY-vitwh) for visualizing the components of your project.
+
+### creating a project
+
+Create a new Project by navigating to your home page and pressing the `New Project` Smartblock under "Projects & Experiments."
+
+You'll be prompted to enter a Project Name, the current status of the Project, and the research **Question** the Project is meant to address.
+
+![](/docs/guides/roam/new-project-modal.png)
+_the "Create Project" modal_
+
+> [!tip] You can create a new project from anywhere in your graph by typing `jj` followed by `createproject` (no spaces!)
+
+### reviewing recent work done in a project
+
+The **Experiments, Issues, & Results Dashboard** provides a quick overview of experiments-in-progress, potential new experiments, and experimental results.
+
+The **Project Meeting Notes** section can be used to record and review Project updates in chronological order. We recommend making liberal use of Roam's block linking and embedding features to cross-link relevant data and observations and surface them to all users of a shared graph.
+
+To find recently-created discourse nodes created during the course of a Project other than those on your Project Page dashboard, check out the **📈 Updates Dashboard** (for nodes created in the past 30 days) and the **🐣 Candidate nodes dashboard** (for nodes that might be ready for formalization).
+
+## How to use Experiments
+
+The **Experiment** is a container for your day-to-day work exploring a **Hypothesis**. It consists of an _intervention_ and a _metric_ used to track the result of that intervention. The **Result** is a statement of your observations regarding that intervention in terms of the appropriate metric.
+
+Making an experiment page helps you track multiple days' work and stay oriented towards and reflect on your progress towards your experiment target. Ideally the target is a **Hypothesis** you are testing, and the experiment page is a space to document and reflect on candidate results for that hypothesis.
+
+### A quick word on candidate nodes
+
+- **Candidate Results** are preliminary observations attached to a particular experiment. They might be first impressions formed from a certain data artefact. Use this tag to mark candidate results: <nodetag type="res" />
+- **Candidate Questions** are potential research questions to explore, of the scope to motivate an entire Project. <nodetag type="que" />
+- **Candidate Evidence** are equivalent to candidate results. This term might be preferred by those using the original Discourse Graph Dialect to perform literature synthesis (as opposed to the equivalent Results Graph dialect). The "Evidence" term can also be used to disambiguate observations from the literature from Results from your own work. <nodetag type="evd" />
+- **Candidate Hypotheses** are potential answers to the Question addressed by a particular project. They might live in the Resources field of a Project Page as you develop your expectations about the response to the intervention. <nodetag type="hyp" />
+- **Candidate Claims** are equivalent to candidate hypotheses. This term might be preferred by those using the original Discourse Graph Dialect to perform literature synthesis (as opposed to the equivalent Results Graph dialect). The "Claim" term can also be used to disambiguate proposed answers to a Question sourced from the literature from hypotheses that you've developed in the course of your work. <nodetag type="clm" />
+- **Candidate Issues** surface potential problems or future experiments. They may or may not be directly related to a particular Project. In a shared graph, a candidate issue can be a preliminary "Request for Experiments" that a lab group can refine together. <nodetag type="iss" />
+
+When you're more confident in an observation, you can use the "Create Discourse Node" popup to convert the candidate into a proper node. This will affect where it appears in queries and its appearance on your Project Canvas — and it will give you a warm sense of accomplishment. This works for all candidate node types.
+
+### experiment page layout
+
+You can see the layout and function of an experiment page here:
+
+![](/docs/guides/roam/experiment-page-dashboard.png)
+_example experiment page_
+
+The experiment page highlights the Hypothesis being investigated and gathers **ToDos**, **Issues**, and **Results** related to the experimental goal in several query blocks. As you add results & candidate results and issues & candidate issues, they will be added to the query blocks on your Experiment page.
+
+An _Experimental Log_, like a lab notebook/Daily Notes page, can be used to organize actions and observations by date.
+
+### creating an experiment
+
+You can create an experiment using the `New Experiment` Smartblocks on your Home Page or Project Page.
+
+![](/docs/guides/roam/project-page-new-experiment-button.png)
+_creating a new experiment from a project page_
+
+![](/docs/guides/roam/home-page-projects-experiments-dashboard.png)
+_creating a new experiment from our home page_
+
+You can also create a new experiment from anywhere in your graph by typing `jj add experiment page template`, or by typing `jj` and selecting "Create Experiment Page" from the dropdown menu in the modal.
+
+![](/docs/guides/roam/jj-create-experiment-smartblock.png)
+_creating a new experiment from the smartblock hotkey menu_
+
+You'll be prompted for several attributes relevant to the experiment: experiment type, title, model organism, question addressed, and project. Any fields irrelevant to your experiment can be left blank.
+
+![](/docs/guides/roam/create-experiment-modal.png)
+_the "create experiment" modal_
+
+> [!tip]- If you're using the template graph, the inputs for Model Organism and Experiment Type can be adjusted on your **🐭 🧪 Lab Housekeeping** page.
+> Editing the lists under "Model organisms/systems" and "Type of Experiment" will change the dropdowns in the "Create Experiment" window.
+
+![modal|250](/docs/guides/roam/lab-housekeeping-model-systems-experiment-types.png)
+_experiment options menu_
+
+### logging your observations
+
+The **Experimental log** can be used as a complement or replacement for your lab notebook.
+
+In your Experiment page, click "New Entry" to log today's notes. You can alternatively click the calendar icon to insert notes for another date. These notes should be scrapbook-style: messy notes to self, links, screenshots, etc.
+
+![](/docs/guides/roam/new-entry-button.png)
+_creating a log entry_
+
+> [!tip] The same entry will show up on your **Home page**; you can edit in either place
+
+You can add images by dragging them onto the page, copy/pasting, or typing `/image` to summon the image upload menu.
+
+![](/docs/guides/roam/add-image-menu.gif)
+_adding images by drag-&-drop and from the image upload menu_
+
+Mark a promising plot or observation as a candidate result by typing `\` to summon the candidate node menu and selecting `res-candidate`. You can use this same menu to note fledgling claims, hypotheses, and issues as well. You can revisit these nodes later for review.
+
+![](/docs/guides/roam/candidate-node-menu.gif)
+
+You can also mark important images or plots as candidate nodes by clicking the **Add Node Tag** icon in the bottom right corner and selecting the correct tag from the dropdown menu.
+
+![](/docs/guides/roam/add-node-tag-icon.png)
+
+![](/docs/guides/roam/candidate-tag-dropdown.png)
+
+![](/docs/guides/roam/candidate-tag-applied.png)
+
+You can use the candidate node menu the same way to mark issue candidates: possible future analyses or experiments.
+
+![](/docs/guides/roam/save-issue-candidate.gif)
+
+For short tasks that don't rise to the level of an experiment, you can create a TODO instead. Both TODOs and issue candidates will show up in the "todos" list for the experiment.
+
+![](/docs/guides/roam/experiment-todos-list.png)
+
+## How to create an Issue
+
+Often, while you're writing up your work, you have an idea for another experiment (or simulation, or analysis) to do. It's not clear if _now_ is the right time, or if _you_ are the right person. To save it for later, classify it as an **Issue**.
+
+Highlight the text you wish to convert into an Issue, hit `\`, and type `I` to create an **Issue**. Set the Status and Issue type.
+
+![](/docs/guides/roam/set-issue-status-type.gif)
+
+> [!tip] Pressing capital `I` creates an Issue, while lowercase `i` converts the selected text into an issue candidate instead
+
+Any text nested under the text you select will show up in the Issue Description, even after the Issue has been created.
+
+![](/docs/guides/roam/issue-description-nested-text.png)
+
+Alternatively, you can select the text with your mouse and use the node creation popup menu to create the Issue.
+
+## How to convert a candidate Issue into an Issue
+
+You may wish to use candidate nodes to keep track of potential issues to review at the end of your experimental workflow. These can then be discarded or converted into mature Issues.
+
+To create an issue candidate, place your cursor at the end of the block you'd like to convert and hit `\` to summon the candidate node creation menu.
+
+![](/docs/guides/roam/candidate-node-creation-menu.png)
+
+Once the candidate node has been created, hover over the node tag (<nodetag type="iss"></nodetag>) to summon the node creation popup menu and create your new Issue.
+
+![](/docs/guides/roam/convert-candidate-to-issue.gif)
+
+### Querying existing Issues
+
+You can use an Issue Query, like the one in [this example graph](https://roamresearch.com/#/app/template-lab/page/t0KMGepJ6), to review all of the Issues associated with a Project. This helps you find ideas for experiments, cross-reference your experimental ideas with existing issues, and claim the ones you'd like to work on later.
diff --git a/apps/website/mdx-components.tsx b/apps/website/mdx-components.tsx
index 333e60126..96f807765 100644
--- a/apps/website/mdx-components.tsx
+++ b/apps/website/mdx-components.tsx
@@ -1,12 +1,168 @@
+import React from "react";
 import { useMDXComponents as getThemeComponents } from "nextra-theme-docs";
 
 type MdxComponentMap = Record<string, unknown>;
+type ImgProps = React.ImgHTMLAttributes<HTMLImageElement>;
+
+// ── Image sizing ────────────────────────────────────────────────────────────
+
+const parseAltSize = (alt?: string): { alt: string; width?: number } => {
+  if (!alt) return { alt: "" };
+  const match = alt.match(/^(.*?)\s*\|\s*(\d+)\s*$/);
+  if (match)
+    return {
+      alt: match[1]?.trim() ?? "",
+      width: parseInt(match[2] ?? "0", 10),
+    };
+  return { alt };
+};
+
+// ── Node tag pills ──────────────────────────────────────────────────────────
+// Default per-type colors live in nextra-css.css (`.node-tag[data-type="..."]`),
+// which derives background/border/text from a single `--node-tag-color` via
+// color-mix — the same pattern used for callouts below. The `color` prop here
+// is only for one-off overrides that skip the CSS default.
+
+type NodeTagProps = {
+  type?: string;
+  color?: string;
+  children?: React.ReactNode;
+};
+
+const NodeTag = ({ type, color, children }: NodeTagProps) => {
+  const style = color
+    ? ({ "--node-tag-color": color } as React.CSSProperties)
+    : undefined;
+  return (
+    <span className="node-tag" data-type={type} style={style}>
+      {children ?? (type ? `#${type}-candidate` : "")}
+    </span>
+  );
+};
+
+// ── Callouts ────────────────────────────────────────────────────────────────
+
+const CALLOUT_REGEX = /^\[!([\w-]+)\]([+-]?)\s*(.*)/s;
+
+const CALLOUT_ICONS: Record<string, string> = {
+  info: "ℹ",
+  tip: "💡",
+  note: "✎",
+  warning: "⚠",
+  caution: "⚠",
+  check: "✓",
+  done: "✓",
+  success: "✓",
+  question: "?",
+  faq: "?",
+  help: "?",
+  fail: "✗",
+  missing: "✗",
+  error: "✗",
+  danger: "⚡",
+  abstract: "≡",
+  summary: "≡",
+};
+
+const CALLOUT_COLORS: Record<string, string> = {
+  info: "#4dabf7",
+  tip: "#69db7c",
+  note: "#74c0fc",
+  warning: "#ffa94d",
+  caution: "#ffa94d",
+  check: "#69db7c",
+  done: "#69db7c",
+  success: "#69db7c",
+  question: "#ffd43b",
+  faq: "#ffd43b",
+  help: "#ffd43b",
+  fail: "#ff8787",
+  missing: "#ff8787",
+  error: "#ff6b6b",
+  danger: "#ff6b6b",
+  abstract: "#74c0fc",
+  summary: "#74c0fc",
+};
+
+const Blockquote = ({ children }: React.HTMLAttributes<HTMLElement>) => {
+  const childArray = React.Children.toArray(children);
+  const firstElementIndex = childArray.findIndex(React.isValidElement);
+  const firstElement = childArray[firstElementIndex] as React.ReactElement<{
+    children: React.ReactNode;
+  }>;
+
+  if (!firstElement) return <blockquote>{children}</blockquote>;
+
+  const pChildren = React.Children.toArray(firstElement.props.children);
+  const firstText = pChildren[0];
+
+  if (typeof firstText !== "string") return <blockquote>{children}</blockquote>;
+
+  const match = firstText.match(CALLOUT_REGEX);
+  if (!match) return <blockquote>{children}</blockquote>;
+
+  const [, rawType, fold, titleText] = match;
+  if (!rawType) return <blockquote>{children}</blockquote>;
+  const type = rawType.toLowerCase();
+  const isFoldable = fold === "+" || fold === "-";
+  const isOpen = fold !== "-";
+  const icon = CALLOUT_ICONS[type] ?? "ℹ";
+  const color = CALLOUT_COLORS[type] ?? "#74c0fc";
+
+  const titleContent = (
+    <>
+      <span className="callout-icon">{icon}</span>
+      <span className="callout-title-text">
+        {titleText}
+        {pChildren.slice(1)}
+      </span>
+      {isFoldable && <span className="callout-fold">▾</span>}
+    </>
+  );
+
+  const body = childArray.slice(firstElementIndex + 1);
+  const TitleTag = isFoldable ? "summary" : "div";
+  const WrapperTag = isFoldable ? "details" : "div";
+
+  return (
+    <WrapperTag
+      className={`callout callout-${type}`}
+      style={{ "--callout-color": color } as React.CSSProperties}
+      {...(isFoldable && isOpen ? { open: true } : {})}
+    >
+      <TitleTag className="callout-title">{titleContent}</TitleTag>
+      <div className="callout-body">{body}</div>
+    </WrapperTag>
+  );
+};
+
+// ── Export ──────────────────────────────────────────────────────────────────
 
 export const useMDXComponents = (
   components: MdxComponentMap = {},
-): MdxComponentMap => ({
-  ...getThemeComponents(),
-  ...components,
-});
+): MdxComponentMap => {
+  const themeComponents = getThemeComponents();
+  const BaseImg = themeComponents.img as
+    | React.ComponentType<ImgProps>
+    | undefined;
+
+  const DocImage = ({ alt, width, ...props }: ImgProps) => {
+    const { alt: cleanAlt, width: parsedWidth } = parseAltSize(alt);
+    const resolvedWidth = parsedWidth ?? width;
+    if (BaseImg) {
+      return <BaseImg alt={cleanAlt} width={resolvedWidth} {...props} />;
+    }
+    // eslint-disable-next-line @next/next/no-img-element
+    return <img alt={cleanAlt} width={resolvedWidth} {...props} />;
+  };
+
+  return {
+    ...themeComponents,
+    img: DocImage,
+    blockquote: Blockquote,
+    nodetag: NodeTag,
+    ...components,
+  };
+};
 
 export default useMDXComponents;
diff --git a/apps/website/package.json b/apps/website/package.json
index 9c22c558b..c68d80561 100644
--- a/apps/website/package.json
+++ b/apps/website/package.json
@@ -18,9 +18,9 @@
   "dependencies": {
     "@repo/database": "workspace:*",
     "@repo/ui": "workspace:*",
+    "@supabase/auth-js": "catalog:",
     "@supabase/ssr": "catalog:",
     "@supabase/supabase-js": "catalog:",
-    "@supabase/auth-js": "catalog:",
     "clsx": "^2.1.1",
     "gray-matter": "^4.0.3",
     "lucide-react": "^0.540.0",
@@ -38,20 +38,22 @@
   },
   "devDependencies": {
     "@repo/eslint-config": "workspace:*",
-    "dotenv": "^16.0.0",
-    "vitest": "catalog:",
     "@repo/tailwind-config": "workspace:*",
     "@repo/types": "workspace:*",
     "@repo/typescript-config": "workspace:*",
     "@tailwindcss/typography": "^0.5.15",
+    "@types/hast": "^3.0.4",
     "@types/node": "catalog:",
     "@types/react": "catalog:",
     "@types/react-dom": "catalog:",
     "autoprefixer": "^10.4.20",
+    "dotenv": "^16.0.0",
     "eslint": "catalog:",
     "pagefind": "^1.4.0",
     "postcss": "^8.4.49",
     "tailwindcss": "^3.4.16",
-    "typescript": "^5"
+    "typescript": "^5",
+    "unist-util-visit": "^5.1.0",
+    "vitest": "catalog:"
   }
 }
diff --git a/apps/website/public/docs/guides/obsidian/backrooms.jpg b/apps/website/public/docs/guides/obsidian/backrooms.jpg
new file mode 100644
index 000000000..555c946e5
Binary files /dev/null and b/apps/website/public/docs/guides/obsidian/backrooms.jpg differ
diff --git a/apps/website/public/docs/guides/obsidian/bases+datacore.png b/apps/website/public/docs/guides/obsidian/bases+datacore.png
new file mode 100644
index 000000000..283268138
Binary files /dev/null and b/apps/website/public/docs/guides/obsidian/bases+datacore.png differ
diff --git a/apps/website/public/docs/guides/obsidian/biblio.png b/apps/website/public/docs/guides/obsidian/biblio.png
new file mode 100644
index 000000000..b5591e82e
Binary files /dev/null and b/apps/website/public/docs/guides/obsidian/biblio.png differ
diff --git a/apps/website/public/docs/guides/obsidian/bullet-journal.png b/apps/website/public/docs/guides/obsidian/bullet-journal.png
new file mode 100644
index 000000000..fa9c1db5b
Binary files /dev/null and b/apps/website/public/docs/guides/obsidian/bullet-journal.png differ
diff --git a/apps/website/public/docs/guides/obsidian/canvas-export 1.png b/apps/website/public/docs/guides/obsidian/canvas-export 1.png
new file mode 100644
index 000000000..4959abb4b
Binary files /dev/null and b/apps/website/public/docs/guides/obsidian/canvas-export 1.png differ
diff --git a/apps/website/public/docs/guides/obsidian/canvas-walkthru01.gif b/apps/website/public/docs/guides/obsidian/canvas-walkthru01.gif
new file mode 100644
index 000000000..d1270d349
Binary files /dev/null and b/apps/website/public/docs/guides/obsidian/canvas-walkthru01.gif differ
diff --git a/apps/website/public/docs/guides/obsidian/cat-meme.png b/apps/website/public/docs/guides/obsidian/cat-meme.png
new file mode 100644
index 000000000..f6a3a8fd3
Binary files /dev/null and b/apps/website/public/docs/guides/obsidian/cat-meme.png differ
diff --git a/apps/website/public/docs/guides/obsidian/clipping01.png b/apps/website/public/docs/guides/obsidian/clipping01.png
new file mode 100644
index 000000000..e35e4ec00
Binary files /dev/null and b/apps/website/public/docs/guides/obsidian/clipping01.png differ
diff --git a/apps/website/public/docs/guides/obsidian/clm-clip02.png b/apps/website/public/docs/guides/obsidian/clm-clip02.png
new file mode 100644
index 000000000..36ce80c57
Binary files /dev/null and b/apps/website/public/docs/guides/obsidian/clm-clip02.png differ
diff --git a/apps/website/public/docs/guides/obsidian/convert-menu.png b/apps/website/public/docs/guides/obsidian/convert-menu.png
new file mode 100644
index 000000000..5755ba308
Binary files /dev/null and b/apps/website/public/docs/guides/obsidian/convert-menu.png differ
diff --git a/apps/website/public/docs/guides/obsidian/convert-menub.png b/apps/website/public/docs/guides/obsidian/convert-menub.png
new file mode 100644
index 000000000..10ce1d9b1
Binary files /dev/null and b/apps/website/public/docs/guides/obsidian/convert-menub.png differ
diff --git a/apps/website/public/docs/guides/obsidian/create-exp01.png b/apps/website/public/docs/guides/obsidian/create-exp01.png
new file mode 100644
index 000000000..dd96a9755
Binary files /dev/null and b/apps/website/public/docs/guides/obsidian/create-exp01.png differ
diff --git a/apps/website/public/docs/guides/obsidian/create-exp02.png b/apps/website/public/docs/guides/obsidian/create-exp02.png
new file mode 100644
index 000000000..427c83cad
Binary files /dev/null and b/apps/website/public/docs/guides/obsidian/create-exp02.png differ
diff --git a/apps/website/public/docs/guides/obsidian/create-prj01.png b/apps/website/public/docs/guides/obsidian/create-prj01.png
new file mode 100644
index 000000000..917a0c794
Binary files /dev/null and b/apps/website/public/docs/guides/obsidian/create-prj01.png differ
diff --git a/apps/website/public/docs/guides/obsidian/create-prj02.png b/apps/website/public/docs/guides/obsidian/create-prj02.png
new file mode 100644
index 000000000..aeee0edc6
Binary files /dev/null and b/apps/website/public/docs/guides/obsidian/create-prj02.png differ
diff --git a/apps/website/public/docs/guides/obsidian/dgraph-share.png b/apps/website/public/docs/guides/obsidian/dgraph-share.png
new file mode 100644
index 000000000..c8a972daf
Binary files /dev/null and b/apps/website/public/docs/guides/obsidian/dgraph-share.png differ
diff --git a/apps/website/public/docs/guides/obsidian/drmanhattan.png b/apps/website/public/docs/guides/obsidian/drmanhattan.png
new file mode 100644
index 000000000..bac2b0813
Binary files /dev/null and b/apps/website/public/docs/guides/obsidian/drmanhattan.png differ
diff --git a/apps/website/public/docs/guides/obsidian/exp-exp.png b/apps/website/public/docs/guides/obsidian/exp-exp.png
new file mode 100644
index 000000000..a3be6be81
Binary files /dev/null and b/apps/website/public/docs/guides/obsidian/exp-exp.png differ
diff --git a/apps/website/public/docs/guides/obsidian/exp-exp01.png b/apps/website/public/docs/guides/obsidian/exp-exp01.png
new file mode 100644
index 000000000..484050e79
Binary files /dev/null and b/apps/website/public/docs/guides/obsidian/exp-exp01.png differ
diff --git a/apps/website/public/docs/guides/obsidian/exp-exp02.png b/apps/website/public/docs/guides/obsidian/exp-exp02.png
new file mode 100644
index 000000000..a67fc7409
Binary files /dev/null and b/apps/website/public/docs/guides/obsidian/exp-exp02.png differ
diff --git a/apps/website/public/docs/guides/obsidian/figdesign01.png b/apps/website/public/docs/guides/obsidian/figdesign01.png
new file mode 100644
index 000000000..901ad96b0
Binary files /dev/null and b/apps/website/public/docs/guides/obsidian/figdesign01.png differ
diff --git a/apps/website/public/docs/guides/obsidian/figdesign02.png b/apps/website/public/docs/guides/obsidian/figdesign02.png
new file mode 100644
index 000000000..b2cf8cca1
Binary files /dev/null and b/apps/website/public/docs/guides/obsidian/figdesign02.png differ
diff --git a/apps/website/public/docs/guides/obsidian/gap-spotting.png b/apps/website/public/docs/guides/obsidian/gap-spotting.png
new file mode 100644
index 000000000..9a84394ac
Binary files /dev/null and b/apps/website/public/docs/guides/obsidian/gap-spotting.png differ
diff --git a/apps/website/public/docs/guides/obsidian/graph-argument-evd.png b/apps/website/public/docs/guides/obsidian/graph-argument-evd.png
new file mode 100644
index 000000000..79c026d46
Binary files /dev/null and b/apps/website/public/docs/guides/obsidian/graph-argument-evd.png differ
diff --git a/apps/website/public/docs/guides/obsidian/graph-argument.png b/apps/website/public/docs/guides/obsidian/graph-argument.png
new file mode 100644
index 000000000..5e5937db6
Binary files /dev/null and b/apps/website/public/docs/guides/obsidian/graph-argument.png differ
diff --git a/apps/website/public/docs/guides/obsidian/graph-view01.png b/apps/website/public/docs/guides/obsidian/graph-view01.png
new file mode 100644
index 000000000..b0c4d1865
Binary files /dev/null and b/apps/website/public/docs/guides/obsidian/graph-view01.png differ
diff --git a/apps/website/public/docs/guides/obsidian/graph-view02.png b/apps/website/public/docs/guides/obsidian/graph-view02.png
new file mode 100644
index 000000000..a5a4245ff
Binary files /dev/null and b/apps/website/public/docs/guides/obsidian/graph-view02.png differ
diff --git a/apps/website/public/docs/guides/obsidian/hover.png b/apps/website/public/docs/guides/obsidian/hover.png
new file mode 100644
index 000000000..14fdc6e3f
Binary files /dev/null and b/apps/website/public/docs/guides/obsidian/hover.png differ
diff --git a/apps/website/public/docs/guides/obsidian/img-clm02.png b/apps/website/public/docs/guides/obsidian/img-clm02.png
new file mode 100644
index 000000000..fe1d5db04
Binary files /dev/null and b/apps/website/public/docs/guides/obsidian/img-clm02.png differ
diff --git a/apps/website/public/docs/guides/obsidian/iss-ex.png b/apps/website/public/docs/guides/obsidian/iss-ex.png
new file mode 100644
index 000000000..8a6806597
Binary files /dev/null and b/apps/website/public/docs/guides/obsidian/iss-ex.png differ
diff --git a/apps/website/public/docs/guides/obsidian/iss-exp.png b/apps/website/public/docs/guides/obsidian/iss-exp.png
new file mode 100644
index 000000000..13bb633d9
Binary files /dev/null and b/apps/website/public/docs/guides/obsidian/iss-exp.png differ
diff --git a/apps/website/public/docs/guides/obsidian/left-sidebar.png b/apps/website/public/docs/guides/obsidian/left-sidebar.png
new file mode 100644
index 000000000..b3da2a6d7
Binary files /dev/null and b/apps/website/public/docs/guides/obsidian/left-sidebar.png differ
diff --git a/apps/website/public/docs/guides/obsidian/linked-men.png b/apps/website/public/docs/guides/obsidian/linked-men.png
new file mode 100644
index 000000000..faf09ce27
Binary files /dev/null and b/apps/website/public/docs/guides/obsidian/linked-men.png differ
diff --git a/apps/website/public/docs/guides/obsidian/lit-rev.png b/apps/website/public/docs/guides/obsidian/lit-rev.png
new file mode 100644
index 000000000..37fe06b76
Binary files /dev/null and b/apps/website/public/docs/guides/obsidian/lit-rev.png differ
diff --git a/apps/website/public/docs/guides/obsidian/lit-rev02.png b/apps/website/public/docs/guides/obsidian/lit-rev02.png
new file mode 100644
index 000000000..559475109
Binary files /dev/null and b/apps/website/public/docs/guides/obsidian/lit-rev02.png differ
diff --git a/apps/website/public/docs/guides/obsidian/lit-synth-canvas.png b/apps/website/public/docs/guides/obsidian/lit-synth-canvas.png
new file mode 100644
index 000000000..4a192dcd8
Binary files /dev/null and b/apps/website/public/docs/guides/obsidian/lit-synth-canvas.png differ
diff --git a/apps/website/public/docs/guides/obsidian/med-log-ex.png b/apps/website/public/docs/guides/obsidian/med-log-ex.png
new file mode 100644
index 000000000..71b098eec
Binary files /dev/null and b/apps/website/public/docs/guides/obsidian/med-log-ex.png differ
diff --git a/apps/website/public/docs/guides/obsidian/memex-res.png b/apps/website/public/docs/guides/obsidian/memex-res.png
new file mode 100644
index 000000000..1ebf38ec0
Binary files /dev/null and b/apps/website/public/docs/guides/obsidian/memex-res.png differ
diff --git a/apps/website/public/docs/guides/obsidian/merton-mentions.png b/apps/website/public/docs/guides/obsidian/merton-mentions.png
new file mode 100644
index 000000000..794adc7dc
Binary files /dev/null and b/apps/website/public/docs/guides/obsidian/merton-mentions.png differ
diff --git a/apps/website/public/docs/guides/obsidian/merton-que.png b/apps/website/public/docs/guides/obsidian/merton-que.png
new file mode 100644
index 000000000..cf21fca4a
Binary files /dev/null and b/apps/website/public/docs/guides/obsidian/merton-que.png differ
diff --git a/apps/website/public/docs/guides/obsidian/ms-canvas.png b/apps/website/public/docs/guides/obsidian/ms-canvas.png
new file mode 100644
index 000000000..f8c0b0207
Binary files /dev/null and b/apps/website/public/docs/guides/obsidian/ms-canvas.png differ
diff --git a/apps/website/public/docs/guides/obsidian/new-node01.png b/apps/website/public/docs/guides/obsidian/new-node01.png
new file mode 100644
index 000000000..5ff6a441a
Binary files /dev/null and b/apps/website/public/docs/guides/obsidian/new-node01.png differ
diff --git a/apps/website/public/docs/guides/obsidian/new-node02.png b/apps/website/public/docs/guides/obsidian/new-node02.png
new file mode 100644
index 000000000..41cf28eb7
Binary files /dev/null and b/apps/website/public/docs/guides/obsidian/new-node02.png differ
diff --git a/apps/website/public/docs/guides/obsidian/new-q.png b/apps/website/public/docs/guides/obsidian/new-q.png
new file mode 100644
index 000000000..2e35ceb3d
Binary files /dev/null and b/apps/website/public/docs/guides/obsidian/new-q.png differ
diff --git a/apps/website/public/docs/guides/obsidian/node-log.png b/apps/website/public/docs/guides/obsidian/node-log.png
new file mode 100644
index 000000000..513e1a422
Binary files /dev/null and b/apps/website/public/docs/guides/obsidian/node-log.png differ
diff --git a/apps/website/public/docs/guides/obsidian/obama.png b/apps/website/public/docs/guides/obsidian/obama.png
new file mode 100644
index 000000000..69ae46038
Binary files /dev/null and b/apps/website/public/docs/guides/obsidian/obama.png differ
diff --git a/apps/website/public/docs/guides/obsidian/prj-container.png b/apps/website/public/docs/guides/obsidian/prj-container.png
new file mode 100644
index 000000000..acda60938
Binary files /dev/null and b/apps/website/public/docs/guides/obsidian/prj-container.png differ
diff --git a/apps/website/public/docs/guides/obsidian/prj-page.png b/apps/website/public/docs/guides/obsidian/prj-page.png
new file mode 100644
index 000000000..ba5189742
Binary files /dev/null and b/apps/website/public/docs/guides/obsidian/prj-page.png differ
diff --git a/apps/website/public/docs/guides/obsidian/reader-que.png b/apps/website/public/docs/guides/obsidian/reader-que.png
new file mode 100644
index 000000000..40d452754
Binary files /dev/null and b/apps/website/public/docs/guides/obsidian/reader-que.png differ
diff --git a/apps/website/public/docs/guides/obsidian/reader-que02.png b/apps/website/public/docs/guides/obsidian/reader-que02.png
new file mode 100644
index 000000000..6b8d76b40
Binary files /dev/null and b/apps/website/public/docs/guides/obsidian/reader-que02.png differ
diff --git a/apps/website/public/docs/guides/obsidian/source-base01.png b/apps/website/public/docs/guides/obsidian/source-base01.png
new file mode 100644
index 000000000..1eeb3d21b
Binary files /dev/null and b/apps/website/public/docs/guides/obsidian/source-base01.png differ
diff --git a/apps/website/public/docs/guides/obsidian/src-node-clip.png b/apps/website/public/docs/guides/obsidian/src-node-clip.png
new file mode 100644
index 000000000..aa29fae55
Binary files /dev/null and b/apps/website/public/docs/guides/obsidian/src-node-clip.png differ
diff --git a/apps/website/public/docs/guides/obsidian/tsundoku.png b/apps/website/public/docs/guides/obsidian/tsundoku.png
new file mode 100644
index 000000000..a19284dc6
Binary files /dev/null and b/apps/website/public/docs/guides/obsidian/tsundoku.png differ
diff --git a/apps/website/public/docs/guides/obsidian/zot-import.png b/apps/website/public/docs/guides/obsidian/zot-import.png
new file mode 100644
index 000000000..06c36ce7a
Binary files /dev/null and b/apps/website/public/docs/guides/obsidian/zot-import.png differ
diff --git a/apps/website/public/docs/guides/obsidian/zot-search.png b/apps/website/public/docs/guides/obsidian/zot-search.png
new file mode 100644
index 000000000..592d1cc3b
Binary files /dev/null and b/apps/website/public/docs/guides/obsidian/zot-search.png differ
diff --git a/apps/website/public/docs/guides/obsidian/zot-search2.png b/apps/website/public/docs/guides/obsidian/zot-search2.png
new file mode 100644
index 000000000..d3f0be385
Binary files /dev/null and b/apps/website/public/docs/guides/obsidian/zot-search2.png differ
diff --git a/apps/website/public/docs/guides/obsidian/zotsidian-settings.png b/apps/website/public/docs/guides/obsidian/zotsidian-settings.png
new file mode 100644
index 000000000..8275c938b
Binary files /dev/null and b/apps/website/public/docs/guides/obsidian/zotsidian-settings.png differ
diff --git a/apps/website/public/docs/guides/roam/add-image-menu.gif b/apps/website/public/docs/guides/roam/add-image-menu.gif
new file mode 100644
index 000000000..20ab8b911
Binary files /dev/null and b/apps/website/public/docs/guides/roam/add-image-menu.gif differ
diff --git a/apps/website/public/docs/guides/roam/add-node-tag-icon.png b/apps/website/public/docs/guides/roam/add-node-tag-icon.png
new file mode 100644
index 000000000..555173704
Binary files /dev/null and b/apps/website/public/docs/guides/roam/add-node-tag-icon.png differ
diff --git a/apps/website/public/docs/guides/roam/candidate-node-creation-menu.png b/apps/website/public/docs/guides/roam/candidate-node-creation-menu.png
new file mode 100644
index 000000000..f15c6edcb
Binary files /dev/null and b/apps/website/public/docs/guides/roam/candidate-node-creation-menu.png differ
diff --git a/apps/website/public/docs/guides/roam/candidate-node-menu.gif b/apps/website/public/docs/guides/roam/candidate-node-menu.gif
new file mode 100644
index 000000000..1dc36878f
Binary files /dev/null and b/apps/website/public/docs/guides/roam/candidate-node-menu.gif differ
diff --git a/apps/website/public/docs/guides/roam/candidate-tag-applied.png b/apps/website/public/docs/guides/roam/candidate-tag-applied.png
new file mode 100644
index 000000000..1dc38c610
Binary files /dev/null and b/apps/website/public/docs/guides/roam/candidate-tag-applied.png differ
diff --git a/apps/website/public/docs/guides/roam/candidate-tag-dropdown.png b/apps/website/public/docs/guides/roam/candidate-tag-dropdown.png
new file mode 100644
index 000000000..9efeee94b
Binary files /dev/null and b/apps/website/public/docs/guides/roam/candidate-tag-dropdown.png differ
diff --git a/apps/website/public/docs/guides/roam/convert-candidate-to-issue.gif b/apps/website/public/docs/guides/roam/convert-candidate-to-issue.gif
new file mode 100644
index 000000000..c6200ebd2
Binary files /dev/null and b/apps/website/public/docs/guides/roam/convert-candidate-to-issue.gif differ
diff --git a/apps/website/public/docs/guides/roam/create-experiment-modal.png b/apps/website/public/docs/guides/roam/create-experiment-modal.png
new file mode 100644
index 000000000..3b2046b97
Binary files /dev/null and b/apps/website/public/docs/guides/roam/create-experiment-modal.png differ
diff --git a/apps/website/public/docs/guides/roam/experiment-page-dashboard.png b/apps/website/public/docs/guides/roam/experiment-page-dashboard.png
new file mode 100644
index 000000000..36a4e6c19
Binary files /dev/null and b/apps/website/public/docs/guides/roam/experiment-page-dashboard.png differ
diff --git a/apps/website/public/docs/guides/roam/experiment-todos-list.png b/apps/website/public/docs/guides/roam/experiment-todos-list.png
new file mode 100644
index 000000000..8c68f42fc
Binary files /dev/null and b/apps/website/public/docs/guides/roam/experiment-todos-list.png differ
diff --git a/apps/website/public/docs/guides/roam/home-page-projects-experiments-dashboard.png b/apps/website/public/docs/guides/roam/home-page-projects-experiments-dashboard.png
new file mode 100644
index 000000000..1507ef06c
Binary files /dev/null and b/apps/website/public/docs/guides/roam/home-page-projects-experiments-dashboard.png differ
diff --git a/apps/website/public/docs/guides/roam/issue-description-nested-text.png b/apps/website/public/docs/guides/roam/issue-description-nested-text.png
new file mode 100644
index 000000000..2a938bf39
Binary files /dev/null and b/apps/website/public/docs/guides/roam/issue-description-nested-text.png differ
diff --git a/apps/website/public/docs/guides/roam/jj-create-experiment-smartblock.png b/apps/website/public/docs/guides/roam/jj-create-experiment-smartblock.png
new file mode 100644
index 000000000..9f6353bcf
Binary files /dev/null and b/apps/website/public/docs/guides/roam/jj-create-experiment-smartblock.png differ
diff --git a/apps/website/public/docs/guides/roam/lab-housekeeping-model-systems-experiment-types.png b/apps/website/public/docs/guides/roam/lab-housekeeping-model-systems-experiment-types.png
new file mode 100644
index 000000000..9fa14bf0f
Binary files /dev/null and b/apps/website/public/docs/guides/roam/lab-housekeeping-model-systems-experiment-types.png differ
diff --git a/apps/website/public/docs/guides/roam/new-entry-button.png b/apps/website/public/docs/guides/roam/new-entry-button.png
new file mode 100644
index 000000000..b9e6feeaf
Binary files /dev/null and b/apps/website/public/docs/guides/roam/new-entry-button.png differ
diff --git a/apps/website/public/docs/guides/roam/new-project-modal.png b/apps/website/public/docs/guides/roam/new-project-modal.png
new file mode 100644
index 000000000..8703894e8
Binary files /dev/null and b/apps/website/public/docs/guides/roam/new-project-modal.png differ
diff --git a/apps/website/public/docs/guides/roam/project-dash.png b/apps/website/public/docs/guides/roam/project-dash.png
new file mode 100644
index 000000000..b8ce87ae2
Binary files /dev/null and b/apps/website/public/docs/guides/roam/project-dash.png differ
diff --git a/apps/website/public/docs/guides/roam/project-page-new-experiment-button.png b/apps/website/public/docs/guides/roam/project-page-new-experiment-button.png
new file mode 100644
index 000000000..c9f8df3db
Binary files /dev/null and b/apps/website/public/docs/guides/roam/project-page-new-experiment-button.png differ
diff --git a/apps/website/public/docs/guides/roam/project-page-overview.png b/apps/website/public/docs/guides/roam/project-page-overview.png
new file mode 100644
index 000000000..7e1667faf
Binary files /dev/null and b/apps/website/public/docs/guides/roam/project-page-overview.png differ
diff --git a/apps/website/public/docs/guides/roam/save-issue-candidate.gif b/apps/website/public/docs/guides/roam/save-issue-candidate.gif
new file mode 100644
index 000000000..c26413c5a
Binary files /dev/null and b/apps/website/public/docs/guides/roam/save-issue-candidate.gif differ
diff --git a/apps/website/public/docs/guides/roam/set-issue-status-type.gif b/apps/website/public/docs/guides/roam/set-issue-status-type.gif
new file mode 100644
index 000000000..43adbfe5e
Binary files /dev/null and b/apps/website/public/docs/guides/roam/set-issue-status-type.gif differ
diff --git a/apps/website/public/docs/roam/project-canvas-candidate-example.png b/apps/website/public/docs/roam/project-canvas-candidate-example.png
new file mode 100644
index 000000000..d47528079
Binary files /dev/null and b/apps/website/public/docs/roam/project-canvas-candidate-example.png differ
diff --git a/apps/website/rehype-callouts.ts b/apps/website/rehype-callouts.ts
new file mode 100644
index 000000000..c6468746d
--- /dev/null
+++ b/apps/website/rehype-callouts.ts
@@ -0,0 +1,127 @@
+import { visit } from "unist-util-visit";
+import type { Root, Element, ElementContent, Text } from "hast";
+
+const CALLOUT_REGEX = /^\[!([\w-]+)\]([+-]?)\s*(.*)/s;
+
+const CALLOUT_ICONS: Record<string, string> = {
+  info: "ℹ",
+  tip: "💡",
+  note: "✎",
+  warning: "⚠",
+  caution: "⚠",
+  check: "✓",
+  done: "✓",
+  success: "✓",
+  question: "?",
+  faq: "?",
+  help: "?",
+  fail: "✗",
+  missing: "✗",
+  error: "✗",
+  danger: "⚡",
+  abstract: "≡",
+  summary: "≡",
+};
+
+const CALLOUT_COLORS: Record<string, string> = {
+  info: "#4dabf7",
+  tip: "#69db7c",
+  note: "#74c0fc",
+  warning: "#ffa94d",
+  caution: "#ffa94d",
+  check: "#69db7c",
+  done: "#69db7c",
+  success: "#69db7c",
+  question: "#ffd43b",
+  faq: "#ffd43b",
+  help: "#ffd43b",
+  fail: "#ff8787",
+  missing: "#ff8787",
+  error: "#ff6b6b",
+  danger: "#ff6b6b",
+  abstract: "#74c0fc",
+  summary: "#74c0fc",
+};
+
+export function rehypeCallouts() {
+  return (tree: Root) => {
+    visit(tree, "element", (node: Element, index, parent) => {
+      if (node.tagName !== "blockquote" || index == null || !parent) return;
+
+      const firstP = node.children.find(
+        (c): c is Element => c.type === "element" && c.tagName === "p",
+      );
+      if (!firstP) return;
+
+      const firstText = firstP.children[0];
+      if (!firstText || firstText.type !== "text") return;
+
+      const match = (firstText as Text).value.match(CALLOUT_REGEX);
+      if (!match) return;
+
+      const [, rawType, fold, titleText] = match;
+      if (!rawType) return;
+      const type = rawType.toLowerCase();
+      const isFoldable = fold === "+" || fold === "-";
+      const isOpen = fold !== "-";
+      const icon = CALLOUT_ICONS[type] ?? "ℹ";
+      const color = CALLOUT_COLORS[type] ?? "#74c0fc";
+
+      // Title: extracted text + any remaining inline children from firstP
+      const titleChildren: ElementContent[] = [
+        {
+          type: "element",
+          tagName: "span",
+          properties: { className: ["callout-icon"] },
+          children: [{ type: "text", value: icon }],
+        },
+        { type: "text", value: titleText || type },
+        ...(firstP.children.slice(1) as ElementContent[]),
+      ];
+
+      if (isFoldable) {
+        titleChildren.push({
+          type: "element",
+          tagName: "span",
+          properties: { className: ["callout-fold"] },
+          children: [{ type: "text", value: "▾" }],
+        });
+      }
+
+      // Body: blockquote children after firstP, filtering whitespace-only text nodes
+      const firstPIndex = node.children.indexOf(firstP);
+      const bodyChildren = node.children
+        .slice(firstPIndex + 1)
+        .filter(
+          (c): c is ElementContent =>
+            c.type !== "text" || (c as Text).value.trim() !== "",
+        );
+
+      const wrapper: Element = {
+        type: "element",
+        tagName: isFoldable ? "details" : "div",
+        properties: {
+          className: ["callout", `callout-${type}`],
+          style: `--callout-color: ${color}`,
+          ...(isFoldable && isOpen ? { open: true } : {}),
+        },
+        children: [
+          {
+            type: "element",
+            tagName: isFoldable ? "summary" : "div",
+            properties: { className: ["callout-title"] },
+            children: titleChildren,
+          },
+          {
+            type: "element",
+            tagName: "div",
+            properties: { className: ["callout-body"] },
+            children: bodyChildren,
+          },
+        ],
+      };
+
+      parent.children.splice(index, 1, wrapper);
+    });
+  };
+}
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 8af1f0ebf..852966013 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -521,6 +521,9 @@ importers:
       '@tailwindcss/typography':
         specifier: ^0.5.15
         version: 0.5.16(tailwindcss@3.4.17(ts-node@10.9.2(@types/node@22.20.0)(typescript@5.5.4)))
+      '@types/hast':
+        specifier: ^3.0.4
+        version: 3.0.4
       '@types/node':
         specifier: 'catalog:'
         version: 22.20.0
@@ -551,6 +554,9 @@ importers:
       typescript:
         specifier: ^5
         version: 5.5.4
+      unist-util-visit:
+        specifier: ^5.1.0
+        version: 5.1.0
       vitest:
         specifier: 'catalog:'
         version: 4.1.6(@edge-runtime/vm@3.2.0)(@opentelemetry/api@1.9.0)(@types/node@22.20.0)(jsdom@20.0.3)(msw@2.11.1(@types/node@22.20.0)(typescript@5.5.4))(vite@7.3.3(@types/node@22.20.0)(jiti@1.21.7)(tsx@4.21.0)(yaml@2.8.2))
@@ -5083,9 +5089,6 @@ packages:
   '@types/node@20.11.0':
     resolution: {integrity: sha512-o9bjXmDNcF7GbM4CNQpmi+TutCgap/K3w1JyKgxAjqx41zp9qlIAVFi0IhCNsJcXolEqLWhbFbEeL0PvYm4pcQ==}
 
-  '@types/node@20.19.13':
-    resolution: {integrity: sha512-yCAeZl7a0DxgNVteXFHt9+uyFbqXGy/ShC4BlcHkoE0AfGXYv/BUiplV72DjMYXHDBXFjhvr6DD1NiRVfB4j8g==}
-
   '@types/node@22.20.0':
     resolution: {integrity: sha512-QWlFW2wf3nTjC13/DqRnBpR4ZO36VJH/JVBkA/vcnmbTBNQIlnObqyqZE1tUR7+Ni23Lda8R1BxMfbXRpCUx5g==}
 
@@ -5865,7 +5868,7 @@ packages:
   basic-ftp@5.0.5:
     resolution: {integrity: sha512-4Bcg1P8xhUuqcii/S0Z9wiHIrQVPMermM1any+MX5GeGD7faD3/msQUDGLol9wOcz4/jbg/WJnGqoJF6LiBdtg==}
     engines: {node: '>=10.0.0'}
-    deprecated: Security vulnerability fixed in 5.2.0, please upgrade
+    deprecated: Security vulnerability fixed in 5.2.1, please upgrade
 
   before-after-hook@3.0.2:
     resolution: {integrity: sha512-Nik3Sc0ncrMK4UUdXQmAnRtzmNQTAAXmXIopizwZ1W1t8QmfJj+zL4OA2I7XPTPW5z5TDqv4hRo/JzouDJnX3A==}
@@ -10600,6 +10603,7 @@ packages:
 
   stream-to-promise@2.2.0:
     resolution: {integrity: sha512-HAGUASw8NT0k8JvIVutB2Y/9iBk7gpgEyAudXwNJmZERdMITGdajOa4VJfD/kNiA3TppQpTP4J+CtcHwdzKBAw==}
+    deprecated: Deprecated. Use node:stream/promises and node:stream/consumers instead.
 
   streamx@2.25.0:
     resolution: {integrity: sha512-0nQuG6jf1w+wddNEEXCF4nTg3LtufWINB5eFEN+5TNZW7KWJp6x87+JFL43vaAUPyCfH1wID+mNVyW6OHtFamg==}
@@ -11260,8 +11264,8 @@ packages:
   unist-util-visit-parents@6.0.1:
     resolution: {integrity: sha512-L/PqWzfTP9lzzEa6CKs0k2nARxTdZduw3zyh8d2NVBnsyvHjSX4TWse388YrrQKbvI8w20fGjGlhgT96WwKykw==}
 
-  unist-util-visit@5.0.0:
-    resolution: {integrity: sha512-MR04uvD+07cwl/yhVuVWAtw+3GOR/knlL55Nd/wAdblk27GCVt3lqpTivy/tkJcZoNPzTwS1Y+KMojlLDhoTzg==}
+  unist-util-visit@5.1.0:
+    resolution: {integrity: sha512-m+vIdyeCOpdr/QeQCu2EzxX/ohgS8KbnPDgFni4dQsfSCtpz8UqDyY5GjRru8PDKuYn7Fq19j1CQ+nJSsGKOzg==}
 
   universal-github-app-jwt@2.2.2:
     resolution: {integrity: sha512-dcmbeSrOdTnsjGjUfAlqNDJrhxXizjAz94ija9Qw8YkZ1uu0d+GoZzyH+Jb9tIIqvGsadUfwg+22k5aDqqwzbw==}
@@ -13585,7 +13589,7 @@ snapshots:
       unified: 11.0.5
       unist-util-position-from-estree: 2.0.0
       unist-util-stringify-position: 4.0.0
-      unist-util-visit: 5.0.0
+      unist-util-visit: 5.1.0
       vfile: 6.0.3
     transitivePeerDependencies:
       - supports-color
@@ -14034,7 +14038,7 @@ snapshots:
 
   '@playwright/test@1.29.0':
     dependencies:
-      '@types/node': 20.19.13
+      '@types/node': 22.20.0
       playwright-core: 1.29.0
 
   '@popperjs/core@2.11.8': {}
@@ -16368,12 +16372,12 @@ snapshots:
     dependencies:
       mermaid: 11.13.0
       react: 19.1.1
-      unist-util-visit: 5.0.0
+      unist-util-visit: 5.1.0
 
   '@theguild/remark-npm2yarn@0.3.3':
     dependencies:
       npm-to-yarn: 3.0.1
-      unist-util-visit: 5.0.0
+      unist-util-visit: 5.1.0
 
   '@tiptap/core@2.26.2(@tiptap/pm@2.26.2)':
     dependencies:
@@ -16981,7 +16985,7 @@ snapshots:
 
   '@types/jsdom@20.0.1':
     dependencies:
-      '@types/node': 20.19.13
+      '@types/node': 22.20.0
       '@types/tough-cookie': 4.0.5
       parse5: 7.3.0
 
@@ -17043,10 +17047,6 @@ snapshots:
     dependencies:
       undici-types: 5.26.5
 
-  '@types/node@20.19.13':
-    dependencies:
-      undici-types: 6.21.0
-
   '@types/node@22.20.0':
     dependencies:
       undici-types: 6.21.0
@@ -20312,7 +20312,7 @@ snapshots:
       mdast-util-to-hast: 13.2.0
       parse5: 7.3.0
       unist-util-position: 5.0.0
-      unist-util-visit: 5.0.0
+      unist-util-visit: 5.1.0
       vfile: 6.0.3
       web-namespaces: 2.0.1
       zwitch: 2.0.4
@@ -21451,7 +21451,7 @@ snapshots:
       micromark-util-sanitize-uri: 2.0.1
       trim-lines: 3.0.1
       unist-util-position: 5.0.0
-      unist-util-visit: 5.0.0
+      unist-util-visit: 5.1.0
       vfile: 6.0.3
 
   mdast-util-to-markdown@2.1.2:
@@ -21463,7 +21463,7 @@ snapshots:
       mdast-util-to-string: 4.0.0
       micromark-util-classify-character: 2.0.1
       micromark-util-decode-string: 2.0.1
-      unist-util-visit: 5.0.0
+      unist-util-visit: 5.1.0
       zwitch: 2.0.4
 
   mdast-util-to-string@4.0.0:
@@ -22039,7 +22039,7 @@ snapshots:
       title: 4.0.1
       ts-morph: 27.0.2
       unist-util-remove: 4.0.0
-      unist-util-visit: 5.0.0
+      unist-util-visit: 5.1.0
       unist-util-visit-children: 3.0.0
       yaml: 2.8.2
       zod: 4.3.6
@@ -23350,7 +23350,7 @@ snapshots:
       rehype-parse: 9.0.1
       shiki: 3.23.0
       unified: 11.0.5
-      unist-util-visit: 5.0.0
+      unist-util-visit: 5.1.0
 
   rehype-raw@7.0.0:
     dependencies:
@@ -23416,7 +23416,7 @@ snapshots:
       estree-util-is-identifier-name: 3.0.0
       estree-util-value-to-estree: 3.5.0
       reading-time: 1.5.0
-      unist-util-visit: 5.0.0
+      unist-util-visit: 5.1.0
 
   remark-rehype@11.1.2:
     dependencies:
@@ -23431,7 +23431,7 @@ snapshots:
       retext: 9.0.0
       retext-smartypants: 6.2.0
       unified: 11.0.5
-      unist-util-visit: 5.0.0
+      unist-util-visit: 5.1.0
 
   remark-stringify@11.0.0:
     dependencies:
@@ -23506,7 +23506,7 @@ snapshots:
     dependencies:
       '@types/nlcst': 2.0.3
       nlcst-to-string: 4.0.0
-      unist-util-visit: 5.0.0
+      unist-util-visit: 5.1.0
 
   retext-stringify@4.0.0:
     dependencies:
@@ -24863,7 +24863,7 @@ snapshots:
   unist-util-remove-position@5.0.0:
     dependencies:
       '@types/unist': 3.0.3
-      unist-util-visit: 5.0.0
+      unist-util-visit: 5.1.0
 
   unist-util-remove@4.0.0:
     dependencies:
@@ -24884,7 +24884,7 @@ snapshots:
       '@types/unist': 3.0.3
       unist-util-is: 6.0.0
 
-  unist-util-visit@5.0.0:
+  unist-util-visit@5.1.0:
     dependencies:
       '@types/unist': 3.0.3
       unist-util-is: 6.0.0