diff --git a/README.md b/README.md
index 6942c51..8b1ad96 100644
--- a/README.md
+++ b/README.md
@@ -105,6 +105,22 @@ your_plugin/
 
 See the [Plugin System docs](https://github.com/your-org/tribes/blob/master/docs/PLUGINS.md) for the full specification.
 
+## Plugin Data
+
+If your plugin adds Ash resources that should replicate cluster-wide, use
+`extensions: [AshNostrSync]` on those resources and follow the host defaults:
+
+- persisted attributes sync by default unless explicitly excluded
+- synced resources should use one UUID primary key by default
+- `AshNostrSync` requires exactly one primary key; composite keys are not supported
+- synced resources get extension-managed `deleted_at` soft-delete support by default
+- destroy actions can use `soft_delete()` when they should tombstone rows
+- `soft_delete?(false)` is the opt-out if a synced resource should not use the default tombstone model
+
+Keep resource-specific side effects explicit in actions. `AshNostrSync` owns the
+default tombstone/filter/projection behavior, but your plugin still decides which
+actions are semantic deletes and what else they should do.
+
 ## Testing
 
 Three test levels: