Update Reified Relation Documentation

apps/website/app/(docs)/docs/roam/navigation.ts

@@ -25,6 +25,14 @@ export const navigation: NavigationList = [
         title: "Creating relationships",
         href: `${ROOT}/creating-discourse-relationships`,
       },
+      {
+        title: "Stored relations",
+        href: `${ROOT}/reified-relations`,
+      },
+      {
+        title: "Migration to stored relations",
+        href: `${ROOT}/migration-to-stored-relations`,
+      },
       {
         title: "Exploring",
         href: `${ROOT}/exploring-discourse-graph`,

apps/website/app/(docs)/docs/roam/pages/creating-discourse-relationships.md

@@ -9,6 +9,10 @@ One of the main features of the Discourse Graph extension is the ability to **cr
 
 The extension has an in-built [grammar](./grammar) that enables it to recognize when certain patterns of writing and outlining are meant to express particular discourse relations (e.g., support, oppose, inform) between discourse nodes. When it recognizes these patterns, it "writes" them to a formal discourse graph data structure, that you can then use to explore or query your discourse graph.
 
+## Deprecation notice
+
+Pattern-based relations are being deprecated. Please plan to move to [**stored relations**](./reified-relations), which will be the recommended way to define and persist discourse relations. Migration guidance is available in [**Migration to stored relations**](./migration-to-stored-relations).
+
 ## Stock Patterns
 
 - Take a look at [Relations Patterns](./relations-patterns)

apps/website/app/(docs)/docs/roam/pages/migration-to-stored-relations.md

@@ -0,0 +1,92 @@
+---
+title: "Migration to stored relations"
+date: "2025-01-01"
+author: ""
+published: true
+---
+
+## Migrate relations to stored relations
+
+### Summary
+
+Stored relations make relations load faster and more reliably. To start using them, your graph needs a one-time migration that copies your existing relations into the new format.
+
+This guide covers the migration flow from **Personal Settings**. If you’re new to stored relations, start with the [stored relations overview](./reified-relations).
+
+## Turn on stored relations
+
+1. Open **Personal Settings**
+2. Go to the **Home** panel
+3. Find **Enable stored relations**
+4. Turn the toggle **On**
+
+When you turn this on, you’ll be shown a migration step for your graph.
+
+## Migrate your existing relations
+
+After enabling the toggle, click:
+
+**Migrate all relations**
+
+What to expect:
+
+- It may take a few minutes
+- Roam may feel frozen while it runs (this is expected)
+- You **can** work in **another Roam window** during the migration
+- When it finishes, you can continue working normally
+
+## When should I run migration again?
+
+You only need to run migration again if:
+
+- Relations were created while stored relations were turned off
+- Your team is transitioning gradually and some people are still using the older relation method
+
+## Multi-user graphs
+
+Migration runs **per graph**, but the stored relations toggle is **per user**. During rollout, it’s possible for teammates to be in different modes.
+
+If some users are still using the older relation method, running migration again later helps ensure you see the most up-to-date relations.
+
+### What each user sees
+
+#### If you do NOT opt in
+
+- You can keep using **patterns** to create relations
+- The overlay will search **only pattern-based** relations
+- You **will not** see data-based relations
+
+#### If you DO opt in
+
+- You will see **only data-based** relations
+- You **will not** see pattern-based relations
+
+### Re-running migration (multi-user / mixed mode)
+
+You can run migration **multiple times**.
+
+This matters if:
+
+- Some users are still creating **pattern-based** relations
+- Other users have opted into **data-based** relations
+
+In that case, opt-in users must re-run migration to “catch up,” otherwise:
+
+- They won’t see new pattern-based relations created since the last migration
+
+#### Important edge case
+
+If you:
+
+1. Delete a **data-based** relation that originally came from a pattern, and then
+2. Re-run migration
+
+… it will be **re-created** from the still-existing pattern.
+
+### For the technically inclined
+
+Data-based relations are stored in:
+
+- `roam/js/discourse-graph/relations`
+
+Each relation is a **block**, with relation data stored in the block’s **hidden properties**.

apps/website/app/(docs)/docs/roam/pages/reified-relations.md

@@ -0,0 +1,131 @@
+---
+title: "Stored relations"
+date: "2025-01-01"
+author: ""
+published: true
+---
+
+## Stored relations
+
+### Overview
+
+Stored relations change how relationships between discourse nodes are created and managed.
+
+Instead of being inferred from patterns in your Roam graph, **stored relations are created and deleted explicitly** and saved as data. This makes relations faster to query, more reliable, and easier to manage.
+
+Stored relations are the foundation for improved performance and a more usable Discourse context overlay.
+
+---
+
+### What is a stored relation?
+
+A **stored relation** is an explicit relationship between two discourse nodes (for example, a claim supporting or opposing another claim).
+
+- Created directly in the [**Discourse context overlay**](./discourse-context-overlay)
+- Persisted as data in your graph
+- Independent of page structure or pattern matching
+
+Once created, stored relations behave consistently across queries, canvases, and overlays.
+
+---
+
+### Why stored relations?
+
+Stored relations provide several benefits over pattern-based relations:
+
+- **Faster performance**
+  - Relations are read directly from stored data
+  - The global Discourse context overlay loads significantly faster
+- **More predictable behavior**
+  - Relations do not disappear due to formatting or structural changes
+  - Editing text or reorganizing blocks does not affect relations
+- **Clearer mental model**
+  - Relations exist because you created them
+  - Deleting a relation removes it explicitly
+
+---
+
+### Creating stored relations
+
+Stored relations are created from the [**Discourse context overlay**](./discourse-context-overlay).
+
+Typical flow:
+
+1. Open the Discourse context overlay for a node
+2. Click **Add relation**
+3. Select the relation type
+4. Select the source and destination nodes
+
+The relation is immediately stored and available to all users who have enabled stored relations.
+
+---
+
+### Viewing stored relations
+
+When stored relations are enabled:
+
+- The [Discourse Context Overlay](./discourse-context-overlay) shows **only stored relations**
+- Queries and canvases resolve relations from stored data
+- Pattern-based relations are ignored
+
+This ensures consistent and fast results.
+
+---
+
+### Editing and deleting stored relations
+
+- Stored relations can be **deleted explicitly** from the Discourse context overlay
+- In most cases, editing a relation is equivalent to:
+  - Deleting the old relation
+  - Creating a new one
+
+Relation labels are referenced by node identity, so renaming a relation label updates all associated relations automatically.
+
+---
+
+### Multi-user behavior
+
+Stored relations are shared across the graph:
+
+- All users with stored relations enabled see the same relations
+- Users without stored relations enabled will not see them
+- Mixed usage is supported temporarily during the transition period
+
+For details on migrating and mixed-mode behavior, see the [**stored relations migration**](./migration-to-stored-relations) documentation.
+
+---
+
+### Current limitations and notes
+
+- Stored relations are **not inferred** from patterns
+- Creating or deleting patterns does not affect stored relations
+- Stored relations are currently opt-in during the transition period
+
+These limitations will be removed once stored relations become the default.
+
+---
+
+### For the technically inclined
+
+Stored relations are implemented as:
+
+- One block per relation
+- Located at: `roam/js/discourse-graph/relations`
+- Relation data stored in the block’s hidden properties
+- Source and destination nodes referenced by UID
+
+This structure allows fast lookup, consistent rendering, and future extensions (metadata, provenance, annotations).
+
+---
+
+### Future direction
+
+Stored relations will eventually replace pattern-based relations entirely.
+
+Once the transition period ends:
+
+- Stored relations will be the default
+- Pattern-based relations will be phased out
+- Migration will be handled automatically
+
+Until then, stored relations are available as an opt-in feature for users who want improved performance and reliability.

apps/website/app/(docs)/docs/roam/pages/relations-patterns.md

@@ -5,6 +5,10 @@ author: ""
 published: true
 ---
 
+## Deprecation notice
+
+Pattern-based relations are being deprecated. Please plan to move to [**stored relations**](./reified-relations), which will be the recommended way to define and persist discourse relations. Migration guidance is available in [**Migration to stored relations**](./migration-to-stored-relations).
+
 ## Stock Patterns
 
 The extension ships with the ability to recognize three such writing/outlining patterns. Give them a try!