docs: updates to README

Author: adwk67

README.md

@@ -30,10 +30,12 @@ from UTF-16, report errors in the exact format the standard demands, copy values
 into buffers the application supplied, and not crash when the application lies
 about how big those buffers are.
 
-`stackable-odbc-core` is that shared part, written once. You supply only what is
-actually about your database, which is how to connect, how to run a query and
-how to read a row back. One macro then generates the C entry points the standard
-requires.
+`stackable-odbc-core` is that shared part, written once. What you supply is the
+part that really is about your database: how to connect and authenticate, how to
+run a query and read rows back, how your database's types map onto ODBC's, and
+how to answer its catalog questions. For a networked database that is a complete
+client in its own right, so it is a substantial piece of work — but none of it
+is ODBC. One macro then generates the C entry points the standard requires.
 
 This is a library rather than a driver you can load on its own. A working driver
 is this crate plus a backend, and
@@ -136,6 +138,14 @@ backend supports.
 In practice you do not look the list up. Write the four associated types, run
 `cargo check`, and the compiler names what is still missing.
 
+Two traits and one macro bound the surface, not the effort. A backend for a
+real database is a real client: authentication, sessions, type mapping, catalog
+queries and error mapping are all yours, and in both existing drivers that adds
+up to a substantial crate. What core takes off your hands is the ODBC half —
+the handle table, the UTF-16, the diagnostics format, the buffer copying and
+the conversion tables — the half that is identical for every database, and the
+half where a mistake is memory corruption rather than a wrong answer.
+
 [AGENTS.md](https://github.com/stackabletech/stackable-odbc-core/blob/main/AGENTS.md)
 has the full walkthrough: how a call flows through the layers, what each
 capability method means, the catalog and descriptor rules, and the Windows
@@ -150,6 +160,13 @@ five descriptor functions work. Descriptors are the standard's own way of
 describing a bound column or parameter, and one can be shared between queries on
 a connection.
 
+This is a Unicode driver: every function that takes or returns a string is
+exported only in its wide (`W`-suffixed) form, such as `SQLConnectW`, and the
+Driver Manager translates for ANSI applications, so those keep working without
+the driver carrying a second set of entry points. Functions with no strings in
+their signature, such as `SQLFetch`, have one spelling and are exported
+unsuffixed.
+
 `CORE_EXPORTED_FUNCTIONS` in `src/function_id.rs` is the authoritative list of
 what is exported, and a guard test pins every entry to a symbol that exists. The
 deprecated ODBC 2.x functions are left out, because the Driver Manager already
@@ -172,9 +189,14 @@ ignored, so a tool can react instead of trusting a wrong answer.
 - **No bookmarks**, which are saved row positions an application can return to
   later, and no automatic population of parameter metadata, so
   `SQL_ATTR_AUTO_IPD` stays `SQL_FALSE`.
-- **No async.** `Backend` is synchronous. A driver built on an async client
-  library bridges to it internally, for example with a current-thread tokio
-  runtime and `block_on`.
+- **No async.** Every call runs to completion before returning:
+  `SQL_ASYNC_MODE` is reported as `SQL_AM_NONE`, and turning on
+  `SQL_ATTR_ASYNC_ENABLE` is refused rather than ignored. This is about the
+  calling thread, not the shape of the results — rows still arrive one
+  `SQLFetch` at a time, and the query timeout and `SQLCancel` still bound and
+  interrupt a slow query. `Backend` is likewise synchronous, so a driver built
+  on an async client library bridges to it internally, for example with a
+  current-thread tokio runtime and `block_on`.
 
 ## Drivers built on this crate