Dream Feature doc

docs/platform/features/dream.mdx

@@ -34,6 +34,19 @@ Over time a user's memories often *imply* something larger than any single entry
 - Each pattern memory keeps a link back to the specific memories it was distilled from, so an insight is always traceable to its evidence.
 - Synthesis is **additive and idempotent**: re-running it will not create duplicate patterns for the same underlying evidence.
 
+**Example.** These four memories accumulate for the same user over time:
+
+- *"User runs approximately 40 kilometers per week and is currently training for a marathon."*
+- *"User lifts weights at the gym three times a week, primarily focusing on legs and back."*
+- *"User tracks all workouts using a Garmin Forerunner watch."*
+- *"User's goal for 2026 is to run a sub-4-hour marathon."*
+
+Synthesis distills them into one pattern memory, kept alongside the originals:
+
+> *"User follows a structured fitness routine that includes weekly long runs (≈40 km), regular leg-and-back strength training, tracks workouts with a Garmin device, and pursues progressive marathon time goals."*
+
+Each source memory stays exactly where it was; the new pattern links back to all of them as its evidence.
+
 <Note>
   Synthesis only considers memories created **after** you enable it for a project. Turning it on sets a forward boundary, so historical memories aren't reprocessed in bulk on day one. Everything added from that point on is eligible.
 </Note>
@@ -42,12 +55,18 @@ Over time a user's memories often *imply* something larger than any single entry
 
 When a user tells you something that **contradicts** an earlier memory ("I moved to Berlin" after an earlier "I live in Lisbon"), Dream marks the older memory as **superseded** and links it to the newer fact that replaced it. Superseded memories are **not deleted, and not hidden by default** — a normal `search` or `get` still returns them alongside your active memories, badged as superseded, so you keep the full history. When you want only the current truth, ask for it explicitly with `latest_only=true` (see [How reads change](#how-reads-change-with-dream) below). Supersede runs automatically as part of adding memories, on every plan.
 
+**Example.** The user has an existing memory *"User drives a 2019 Subaru Outback."* Later they mention selling it, producing a new memory *"User sold their 2019 Subaru Outback and bought a Tesla Model 3."* Dream marks the Subaru memory as superseded and links it to the newer one. A default `search` returns **both** (the Tesla memory as active, the Subaru one labelled superseded); `latest_only=true` returns only *"User sold their 2019 Subaru Outback and bought a Tesla Model 3."*
+
 ### Merge
 
-When a new memory is effectively a **duplicate** of one you already have, Dream folds it into a single canonical memory instead of storing two near-identical copies. The **merged duplicate is hidden from your reads by default** (you get the one canonical memory), but it is retained, not deleted, and you can include it with `include_merged=true`. Like Supersede, Merge runs automatically as memories are added, on every plan, and keeps your memory set compact without you deduplicating by hand.
+When a new memory is effectively a **duplicate** of one you already have, Dream keeps a single canonical memory instead of two near-identical copies. When a duplicate is stored as its own memory, Dream marks it **merged** and links it to the canonical one; the merged record is hidden from reads by default (you get the one canonical memory), retained — not deleted — and surfaced with `include_merged=true`. Merge runs automatically as memories are added, on every plan, and keeps your memory set compact without you deduplicating by hand.
+
+In practice, most exact or near-duplicate restatements of a fact you already have are recognised and **deduplicated as the memory is added** — no second copy is created, so you simply keep the one memory. A distinct `merged` record appears when a fuller version of an existing fact arrives and folds the barer one in.
+
+**Example.** The user has an existing memory *"User has a dog named Rex."* Later they mention *"My dog Rex is a 3-year-old golden retriever."* The richer statement is stored and Dream marks the barer *"User has a dog named Rex"* as **merged** into it. A default read returns the single canonical memory *"User's dog Rex is a 3-year-old golden retriever"*; `include_merged=true` also returns the merged original.
 
 <Info>
-  **Nothing Dream does is destructive.** Superseded and merged memories are retained, never erased. Every change is recorded and reviewable, so you always know why a memory was retired or combined, and the change can be reverted from the dashboard.
+  **Nothing Dream does is destructive.** Superseded and merged memories are retained, never erased. Every change is recorded and reviewable, so you always know why a memory was retired or combined.
 </Info>
 
 ## How reads change with Dream
@@ -78,19 +97,14 @@ Synthesis is a **per-project** setting, so you can enable it for one project and
 
 From the Dream section you can also review what Dream has done: recent synthesis runs, the patterns produced and their source memories, and the memories that were superseded or merged.
 
-<Note>
-  On **Free** and **Starter** plans you can run a no-write **Preview** from the Dream section to see the kind of pattern memories Synthesis *would* produce for a project, before upgrading to enable it for real.
-</Note>
-
 ## Plan availability
 
 | Capability | Free | Starter | Pro | Enterprise |
 |---|:---:|:---:|:---:|:---:|
 | **Supersede** (outdated facts flagged) | ✓ | ✓ | ✓ | ✓ |
 | **Merge** (duplicates folded, hidden by default) | ✓ | ✓ | ✓ | ✓ |
-| **Synthesis Preview** (no-write) | ✓ | ✓ | ✓ | ✓ |
 | **Synthesis** (pattern memories written) | — | — | ✓ | ✓ |
-| **Dream dashboard** (runs, activity, revert) | — | — | ✓ | ✓ |
+| **Dream dashboard** (runs, activity) | — | — | ✓ | ✓ |
 
 Synthesis requires a **Pro plan or higher**. Enterprise plans additionally get a **faster, configurable schedule** (see below).
 
@@ -123,7 +137,7 @@ Because Synthesis is processed in batches in the background, **expect new patter
 ## FAQ
 
 **Does Dream delete any of my memories?**
-No. Nothing Dream does is destructive. Superseded memories stay visible in default reads (labelled as history), merged duplicates are hidden by default but retained, and synthesized patterns are added alongside your existing memories, never in place of them. Every change is reviewable and reversible from the dashboard.
+No. Nothing Dream does is destructive. Superseded memories stay visible in default reads (labelled as history), merged duplicates are hidden by default but retained, and synthesized patterns are added alongside your existing memories, never in place of them. Every change is reviewable from the dashboard.
 
 **How do I get only the current facts, without the superseded ones?**
 Pass `latest_only=true` on your read. Superseded and merged memories are both excluded, leaving only active memories. By default (no flag) superseded memories are included so you keep the full history.
@@ -140,8 +154,5 @@ Synthesis runs on a schedule (every 7 days on Pro, daily on Enterprise) and only
 **Are synthesized pattern memories traceable?**
 Yes. Every pattern memory links back to the specific source memories it was distilled from, so you can always see the evidence behind an insight from the Dream dashboard.
 
-**Can I try Synthesis before upgrading?**
-Yes. Free and Starter plans can run a no-write **Preview** from the Dream section to see the kind of patterns Synthesis would produce, without anything being written.
-
 **Can I turn Synthesis off?**
 Yes, at any time, per project. Turning it off is fully reversible and leaves all existing memories, including already-synthesized patterns, untouched.