docs: clarify that all sync participants must share the same schema

Add an explicit "Schema Consistency Across Devices" section to
docs/SCHEMA.md and a matching note in README.md's "Sync from another
device" example. Both explain that every participant must initialize
the same tables with identical structure, surface the "schema hash is
unknown" error as the symptom of divergence, and point to RLS as the
correct pattern for per-tenant/per-workspace data isolation.

Author: andinux

README.md

@@ -150,6 +150,8 @@ SELECT cloudsync_terminate();
 
 Back on Device A, calling `cloudsync_network_sync()` will pull Device B's changes. The CRDT engine ensures all devices converge to the same data, automatically, with no conflicts.
 
+> **Note:** every device participating in the same sync must create **the same set of tables with the same structure** and initialize each one with `cloudsync_init()`. sqlite-sync derives a schema hash from the synced tables, and the server rejects payloads whose hash it does not recognize. For multi-tenant setups where each client should see only a subset of rows, use a shared schema with a tenant/scope column and enforce isolation with [Row-Level Security](./docs/row-level-security.md) — do not give each client a different table.
+
 ## Block-Level LWW
 
 Standard CRDT sync replaces an entire cell when two devices edit the same column. **Block-Level LWW** splits text into lines and merges them independently, designed for keeping **markdown files and agent memory** in sync.

docs/SCHEMA.md

@@ -2,6 +2,22 @@
 
 When designing your database schema for SQLite Sync, follow these guidelines to ensure correct CRDT behavior and conflict resolution.
 
+## Schema Consistency Across Devices
+
+All databases participating in the same sync (every client and the cloud database) **must have the same set of synced tables with identical structure**:
+
+- The same tables must be created on every participant.
+- Each table must be initialized with `cloudsync_init()` on every participant.
+- Column names, types, and constraints must match across participants.
+
+sqlite-sync computes a **schema hash** from the synced tables and includes it in every sync payload. The server rejects payloads whose schema hash it does not recognize, failing with an error like:
+
+```
+cloudsync operation failed: Cannot apply the received payload because the schema hash is unknown <hash>
+```
+
+If you need different clients to see different subsets of data (for example, per-tenant or per-workspace isolation), do **not** give each client a different table. Instead, use a single shared schema and scope the data with a column such as `tenant_id` or `workspace_id`, then enforce isolation server-side with [Row-Level Security](./row-level-security.md).
+
 ## Primary Key Requirements
 
 - **Use globally unique identifiers**: Always use TEXT primary keys with UUIDs or ULIDs.