Merge pull request #334 from powersync-ja/attachments-polish

Improve discoverability, wording polish and fix inaccuracies

Author: benitav

packages/powersync_attachments_helper/README.md

@@ -1,11 +1,19 @@
 # PowerSync Attachments Helper for Dart/Flutter
 
-[PowerSync Attachments Helper](https://pub.dev/packages/powersync_attachments_helper) is a package that assist in keeping files in sync with local and remote storage.
+[PowerSync Attachments Helper](https://pub.dev/packages/powersync_attachments_helper) is a package that assists in keeping files in sync between local and remote storage.
 
 > [!WARNING]  
-> There is a new attachments helper library in the core PowerSync package, available under
-> `package:powersync_core/attachments/attachments.dart`. While this package will continue to receive
-> bugfixes, new feature development will only happen in the other package.
+> This package will eventually be replaced by a new attachments helper library in the core PowerSync package, available through:
+> ```dart
+> package:powersync_core/attachments/attachments.dart
+> ```
+>
+> 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.
+>
+> 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`.
 
 
 ## Features
@@ -89,5 +97,3 @@ initializeAttachmentQueue(PowerSyncDatabase db) async {
   await attachmentQueue.init();
 }
 ```
-
-See our [Supabase Flutter To-Do List example app](../../demos/supabase-todolist/README.md) for a concrete implementation of the above.

packages/powersync_core/doc/attachments.md

@@ -5,7 +5,7 @@ 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 primary data model, and then download it from a secondary data store such as S3.
+in your local database, 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_.
 
 ## Alpha release
@@ -31,8 +31,7 @@ The attachments' state is stored in a local-only attachments table.
 
 ### Example implementation
 
-See the [supabase todolist](https://github.com/powersync-ja/powersync.dart/tree/main/demos/supabase-todolist) demo for
-a basic example of attachment syncing.
+See the [supabase-todolist](https://github.com/powersync-ja/powersync.dart/tree/main/demos/supabase-todolist) demo for a basic example of attachment syncing.
 
 ### Setup
 
@@ -77,7 +76,6 @@ final attachmentQueue = AttachmentQueue(
 ```
 
 Here,
-
  - An instance of `LocalStorageAdapter`, such as the `IOLocalStorage` provided by the SDK, is responsible for storing
    attachment contents locally.
  - An instance of `RemoteStorageAdapter` is responsible for downloading and uploading attachment contents to the secondary