docs: add V1 README, CHANGELOG, and package docs

Expand README with setup and API guidance, add CHANGELOG breaking
section, and refresh package documentation for the V1 API surface.

Co-authored-by: Cursor <cursoragent@cursor.com>

CHANGELOG.md

@@ -0,0 +1,24 @@
+# Changelog
+
+## Unreleased (v1.0.0)
+
+### Breaking changes
+
+- Removed `UUID`, `NewUUID`, and `ParseUUID`.
+- Added `StringKSUID` and `BinaryKSUID` with distinct SQL encodings and shared GraphQL transit (`ksuid_str` JSON field, replacing `uuid_str`).
+- Removed `DBConfig.AutoMigrate`, `SQLOFunc`, and `JSONB.ToMap()`.
+- Replaced `Column` / `ColumnList` intersection interfaces with dialect-neutral type aliases.
+- `Apply*` and `Expr*` helpers now accept `Column` / `ColumnList` / `Expression` aliases instead of `mysql.*` types.
+
+### Added
+
+- Context-aware variants for all query and mutation helpers.
+- `Delete`, `DeleteAffected`, `WithTx`, `ContainsCol`, and `CurrentDialect()`.
+- Package documentation (`doc.go`), expanded README, and subpackage docs for `dbxm` / `dbxp`.
+- Comprehensive tests for KSUID types, CRUD helpers, column utilities, and module lifecycle.
+
+### Changed
+
+- Debug logger setup returns an error instead of panicking when `DebugLog` is enabled without a dialect logger blank import.
+- `DestName` skips logging when the database module is not initialized.
+- Source reorganized into domain-focused files (`query.go`, `exec.go`, `apply.go`, etc.).

README.md

@@ -1,3 +1,70 @@
 # dbx
 
-dbx (**D**ata**b**ase **E**extensions) is a small toolkit of common and reusable database helpers built around the [Jet](https://github.com/go-jet/jet) SQL builder. Provides an [app.Module](https://gitea.auvem.com/go-toolkit/app).
+**D**ata**b**ase e**x**tensions — a small toolkit of reusable database helpers built on [Jet](https://github.com/go-jet/jet) and [go-toolkit/app](https://gitea.auvem.com/go-toolkit/app).
+
+## Install
+
+```bash
+go get gitea.auvem.com/go-toolkit/dbx
+```
+
+## Quick start
+
+```go
+import (
+    "gitea.auvem.com/go-toolkit/app"
+    "gitea.auvem.com/go-toolkit/dbx"
+    _ "gitea.auvem.com/go-toolkit/dbx/dbxm" // MySQL debug logging only
+)
+
+func main() {
+    cfg := &dbx.DBConfig{
+        User:     "user",
+        Password: "pass",
+        URI:      "localhost:3306",
+        Name:     "mydb",
+        MaxConn:  10,
+    }
+
+    modules := []*app.Module{
+        dbx.ModuleDB(dbx.DialectMySQL, cfg, false),
+    }
+
+    app.Run(modules...)
+    db := dbx.SQLO()
+    _ = db
+}
+```
+
+For Postgres, use `dbx.DialectPostgres` and blank-import `dbxp` instead of `dbxm` when `DebugLog` is enabled.
+
+## Helper catalog
+
+| Area | Functions |
+|------|-----------|
+| Query | `Fetch`, `MustFetch`, `FetchOne`, `MustFetchOne` (+ `*Context` variants) |
+| Mutations | `Insert`, `InsertReturning`, `Update`, `UpdateAffected`, `UpdateReturning`, `Delete`, `DeleteAffected` (+ `*Context` variants) |
+| Transactions | `WithTx` |
+| Columns | `NormalCols`, `ContainsCol`, `ExprValues`, `ExprStringers` |
+| Partial update | `ApplyPtr`, `ApplyComplexPtr`, `ApplyInterfacePtr`, `ApplyVal` |
+| Pointers | `Ptr`, `Val`, `NowPtr`, `TrimPtr`, `TrimPtrToNil`, `IsZero` |
+| Types | `StringKSUID`, `BinaryKSUID`, `JSONB` |
+
+## KSUID type selection
+
+| Type | SQL column | Storage |
+|------|------------|---------|
+| `StringKSUID` | `VARCHAR(27)`, `TEXT` | Base62 string |
+| `BinaryKSUID` | `BINARY(20)`, `BYTEA` | Raw 20 bytes |
+
+Both types use identical GraphQL JSON transit (`ksuid_str` field). Pick the type that matches your column encoding — Scan rejects ambiguous payloads.
+
+## Dialect notes
+
+- **MySQL inserts:** use `Insert` for `LastInsertId` workflows.
+- **Postgres inserts:** use `InsertReturning` with a Jet `RETURNING` clause.
+- **Debug logging:** requires blank-import of `dbxm` or `dbxp` matching your dialect. Without it, module setup returns an error when `DebugLog` is true.
+
+## Documentation
+
+Package docs are available on pkg.go.dev and via `go doc gitea.auvem.com/go-toolkit/dbx`.

dbxm/doc.go

@@ -0,0 +1,7 @@
+// Package dbxm registers the MySQL Jet query debug logger for dbx.
+//
+// Blank-import this package when using dbx with MySQL and [dbx.DBConfig.DebugLog]
+// is enabled:
+//
+//	import _ "gitea.auvem.com/go-toolkit/dbx/dbxm"
+package dbxm

dbxp/doc.go

@@ -0,0 +1,7 @@
+// Package dbxp registers the Postgres Jet query debug logger for dbx.
+//
+// Blank-import this package when using dbx with Postgres and [dbx.DBConfig.DebugLog]
+// is enabled:
+//
+//	import _ "gitea.auvem.com/go-toolkit/dbx/dbxp"
+package dbxp

doc.go

@@ -3,12 +3,14 @@
 // # Module lifecycle
 //
 // Call [ModuleDB] once to register the database [app.Module], then use [SQLO]
-// to access the connection pool. Only one database per process is supported.
+// to access the connection pool. [CurrentDialect] reports the configured dialect.
+// Only one database per process is supported.
 //
 // # Query and mutation helpers
 //
 // [Fetch], [FetchOne], [Insert], [Update], [Delete], and their Must* and Context
 // variants wrap Jet [Statement] execution with consistent error semantics.
+// [WithTx] runs a function inside a SQL transaction.
 //
 // # Jet column utilities
 //
@@ -21,7 +23,11 @@
 // # Identifier types
 //
 // [StringKSUID] and [BinaryKSUID] wrap segmentio/ksuid with storage-specific
-// SQL encoding. [JSONB] provides map-based JSON column scanning.
+// SQL encoding. Both share identical GraphQL string transit. Choose StringKSUID
+// for text columns (VARCHAR, TEXT); choose BinaryKSUID for binary columns
+// (BINARY(20), BYTEA).
+//
+// [JSONB] provides map-based JSON column scanning for Postgres JSONB and MySQL JSON.
 //
 // # Pointer and string utilities
 //
@@ -31,7 +37,8 @@
 // # Debug logging
 //
 // Enable [DBConfig.DebugLog] and blank-import dbxm (MySQL) or dbxp (Postgres)
-// to register Jet query debug output.
+// to register Jet query debug output. Setup returns an error if DebugLog is
+// enabled without the matching blank import.
 //
 // # Dialect notes
 //