@@ -0,0 +1,9 @@
+---
+"@objectstack/driver-turso": patch
+---
+
+`README.md` — the remote branch of the architecture tree no longer lists `beginTransaction`, `commit` and `rollback` as `RemoteTransport` operations. `RemoteTransport` has no transaction methods, and remote mode refuses all three with `NOT_IMPLEMENTED` / 501. A new "What remote mode refuses" section lists every `NOT_IMPLEMENTED` / 501 the remote face raises: transactions (including `options.transaction` passed to the remote data and schema methods), a record number for an empty `autonumber` field on `create`, `bulkCreate` and an `upsert` with no `id`, `_id` or `conflictKeys`, `setDeferredDdl(true)`, `detectManagedDrift()`, `planMediaColumnMove()`, and two `aggregate()` shapes that `engine.aggregate()` computes in memory instead (a `groupBy` entry with a `dateGranularity`, an `aggregations` entry with a non-empty `filter`).
+
+Also corrected: the remote-mode bullet no longer says every operation is delegated to `RemoteTransport`, the remote example no longer says every CRUD call works as in local mode, and the local branch no longer lists array-style filters, which the driver refuses.
+
+- **No behaviour moves.** The driver's source and every published export are byte-identical; only the README text shipped in this package's `files[]` changes.
@@ -7,7 +7,7 @@ Turso/libSQL driver for ObjectStack — edge-first SQLite with embedded replicas
 `TursoDriver` implements a **dual-transport architecture**:
 
 - **Local/Replica modes:** Extends `SqlDriver` from `@objectstack/driver-sql`. All CRUD, schema, filtering, aggregation, window functions, introspection, and transactions are **inherited** via Knex + better-sqlite3.
-- **Remote mode:** Delegates all operations to `RemoteTransport` which uses `@libsql/client` SDK directly (HTTP/WebSocket). No local SQLite or Knex dependency needed.
+- **Remote mode:** Sends CRUD, bulk writes, `aggregate`, raw `execute`, schema sync and `dropTable` to `RemoteTransport`, which uses the `@libsql/client` SDK directly (HTTP/WebSocket). Transactions and the other calls listed under [What remote mode refuses](#what-remote-mode-refuses) are refused instead.
 
 ```
 TursoDriver extends SqlDriver (dual transport)
@@ -17,13 +17,14 @@ TursoDriver extends SqlDriver (dual transport)
 │   ├── Inherited: syncSchema, dropTable, introspectSchema
 │   ├── Inherited: aggregate, distinct, findWithWindowFunctions
 │   ├── Inherited: beginTransaction, commit, rollback
-│   └── Inherited: applyFilters (MongoDB-style + array-style)
+│   └── Inherited: applyFilters (MongoDB-style)
 ├── Transport: remote (via @libsql/client)
 │   ├── RemoteTransport: find, findOne, create, update, delete, count, upsert
 │   ├── RemoteTransport: bulkCreate, bulkUpdate, bulkDelete, updateMany, deleteMany
 │   ├── RemoteTransport: syncSchema, dropTable
-│   ├── RemoteTransport: beginTransaction, commit, rollback
-│   └── RemoteTransport: execute (raw SQL)
+│   ├── RemoteTransport: execute (raw SQL)
+│   └── Refused, NOT_IMPLEMENTED / 501: beginTransaction, commit, rollback,
+│       setDeferredDdl(true), detectManagedDrift, planMediaColumnMove
 ├── Override:  name, version, supports (Turso-specific capabilities)
 ├── Override:  connect / disconnect (transport-aware lifecycle)
 ├── Added:     transportMode ('local' | 'replica' | 'remote')
@@ -114,10 +115,41 @@ const driver = new TursoDriver({
 });
 await driver.connect();
 
-// All CRUD operations work the same as local mode
+// The CRUD methods are the same as in local mode; some calls are refused (below)
 const users = await driver.find('users', { where: { active: true } });
 ```
 
+#### What remote mode refuses
+
+Each call below is refused in remote mode with `code: 'NOT_IMPLEMENTED'` and
+`status: 501`: the call is valid, and the remote transport does not have the
+capability. The check runs before the call reads or writes anything.
+
+| Operation | Refused call | Use instead |
+|:---|:---|:---|
+| Transactions | `beginTransaction()`, `commit()`, `rollback()`, and `options.transaction` passed to any `RemoteTransport` method in the tree above, to `aggregate()` or to `syncSchemasBatch()` | The local or embedded-replica transport, which run Knex transactions and honour `options.transaction` |
+| Record numbers | `create()`, `bulkCreate()`, and an `upsert()` with no `id`, `_id` or `conflictKeys`, when a row leaves an `autonumber` field empty (`undefined`, `null` or `''`) | The local or embedded-replica transport, which generate record numbers, or a value you supply, which is written unchanged |
+| Deferring schema DDL | `setDeferredDdl(true)`, which `os migrate plan` calls. `setDeferredDdl(false)` is accepted | Run the command against a local SQLite copy of the database (a `file:` URL) |
+| Schema drift detection | `detectManagedDrift()` | `os migrate plan` against a local SQLite copy of the database (a `file:` URL) |
+| Planning the ADR-0104 media column move | `planMediaColumnMove()`, the column step of `os migrate files-to-references` | The local or embedded-replica transport, which plan it |
+
+- **Transactions.** Remote mode declares `supports.transactionsUnsupported: true`.
+  When the remote driver is the engine's default datasource, `engine.transaction()`
+  reads that and does not call `beginTransaction()`: it runs the callback with
+  no transaction and logs a warning once per datasource, or, called with
+  `require: true`, throws `TransactionUnsupportedError` before the callback runs.
+- **Record numbers.** Remote mode never generates one. The check uses the
+  `autonumber` fields this driver recorded when it synced the object's schema
+  (`syncSchema`, `syncSchemasBatch` or `initObjects`). An `upsert()` that
+  carries an `id`, `_id` or `conflictKeys` is not refused, because it may merge
+  into an existing row. If it inserts instead, the row is written with the field
+  empty and the driver logs a warning naming the row.
+- **Aggregation.** `aggregate()` called on the driver directly also refuses,
+  with the same code, a `groupBy` entry that has a `dateGranularity`, and an
+  `aggregations` entry with a non-empty `filter`. `engine.aggregate()` never
+  sends either one to this driver: it fetches the rows and computes both in
+  memory. The local transport also refuses a per-aggregation `filter`.
+
 ### Auto-Detection
 
 Transport mode is automatically detected from the URL: