diff --git a/packages/powersync_attachments_helper/README.md b/packages/powersync_attachments_helper/README.md
index fdd46803..c9b5f532 100644
--- a/packages/powersync_attachments_helper/README.md
+++ b/packages/powersync_attachments_helper/README.md
@@ -10,7 +10,7 @@
 >
 > The `powersync_core/attachments` library is in alpha and brings improved APIs and functionality that is more in line with our other SDKs, such as the ability to write your own local storage implementation.
 >
-> Check out the [docs here](/packages/powersync_core/doc/attachments.md) to get started.
+> Check out the [docs here](https://pub.dev/documentation/powersync_core/latest/topics/attachments-topic.html) to get started.
 >
 > While the `powersync_attachments_helper` package will still get bug fixes if you need them,
 > new features will only be developed on `powersync_core/attachments`.
diff --git a/packages/powersync_core/doc/attachments.md b/packages/powersync_core/doc/attachments.md
index 67383942..555cda7b 100644
--- a/packages/powersync_core/doc/attachments.md
+++ b/packages/powersync_core/doc/attachments.md
@@ -5,16 +5,26 @@ PowerSync.
 Embedding this data directly in your source databases is [inefficient and not recommended](https://docs.powersync.com/usage/use-case-examples/attachments).
 
 Instead, the PowerSync SDK for Dart and Flutter provides utilities you can use to _reference_ this binary data
-in your local database, and then download it from a secondary data store such as Supabase Storage or S3.
+in your regular database schema, and then download it from a secondary data store such as Supabase Storage or S3.
 Because binary data is not directly stored in the source database in this model, we call these files _attachments_.
 
+
+> [!NOTE]  
+> These attachment utilities are recommended over our legacy [PowerSync Attachments Helper](https://pub.dev/packages/powersync_attachments_helper) package. The new utilities provide cleaner APIs that are more aligned with similar helpers in our other SDKs, and include improved features such as:
+> - Support for writing your own local storage implementation
+> - Support for dynamic nested directories and custom per-attachment file extensions out of the box
+> - Ability to add optional `metaData` to attachments
+> - No longer depends on `dart:io` 
+> 
+> If you are new to handling attachments, we recommend starting with these utilities. If you currently use the legacy `powersync_attachments_helper` package, a fairly simple migration would be to adopt the new utilities with a different table name and drop the legacy package. This means existing attachments are lost, but they should be downloaded again.
+
 ## Alpha release
 
-The attachment helpers described in this document are currently in an alpha state, intended for testing.
+The attachment utilities described in this document are currently in an alpha state, intended for testing.
 Expect breaking changes and instability as development continues.
 The attachments API is marked as `@experimental` for this reason.
 
-Do not rely on these libraries for production use.
+Do not rely on these utilities for production use.
 
 ## Usage