docs: add canonical Supported SQL reference (docs/supported-sql.md) (#23)

The README's "Supported SQL" section had grown into an implicit
mini-reference that was missing key facts — most glaringly,
transactions (`BEGIN` / `COMMIT` / `ROLLBACK`) which Phase 4f
shipped months ago. Other gaps: multi-row INSERT, auto-index
naming, read-only mode behavior, three-valued NULL logic, case
sensitivity of identifiers.

Rather than keep patching the README, split the canonical
reference out into its own document:

  - **`docs/supported-sql.md`** — strict reference: every
    statement with its full grammar, supported types, column
    constraints, error conditions, operator table, NULL
    semantics, transaction lifecycle, read-only behavior, and
    the complete "not yet supported" list organized by
    category (joins, aggregation, predicates, DDL,
    transactions, query shape, session / schema).

  - **`README.md`** — trimmed "Supported SQL" to a
    quick-reference summary table that now includes the
    `BEGIN` / `COMMIT` / `ROLLBACK` row. Defers to
    supported-sql.md for full semantics. The "not yet
    implemented" bullet is broader + links to the detailed
    list.

  - **`docs/usage.md`** — "Supported SQL" section shrunk to a
    handful of at-the-REPL tips (one-statement-per-call,
    transactions-are-real, case-sensitive identifiers,
    NULL-as-false-in-WHERE). Deleted the duplicated
    statement-by-statement breakdown, deleted the full
    Transactions and Not-Yet-Supported sections — all now
    live in supported-sql.md. usage.md stays focused on
    "how to use the tool" (REPL, meta-commands, history,
    embedding) instead of "what SQL does it speak".

  - **`docs/_index.md`** — Supported SQL surfaced in the
    "Start here" list as its own entry, between Using SQLRite
    and Desktop.

One factual correction landed along the way: the reference
initially claimed identifiers were case-insensitive "normalized
to lowercase at definition time". A quick check of
`Database::contains_table` showed it's a direct `HashMap`
lookup with zero normalization — so `CREATE TABLE Users` +
`SELECT * FROM users` actually errors. Fixed the doc to match
reality and flagged it as something Phase 5's cursor refactor
could revisit.

No engine changes. Pure docs.

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: joaoh82

README.md

@@ -124,24 +124,27 @@ sqlrite> DELETE FROM users WHERE age < 30;
 
 #### Supported SQL
 
+**See [docs/supported-sql.md](docs/supported-sql.md) for the full reference** — semantics, error behavior, NULL rules, type coercion, case-sensitivity, read-only mode, and the complete list of what's *not* supported yet. The table below is a quick-reference summary.
+
 | Statement | Features |
 |---|---|
-| `CREATE TABLE` | `PRIMARY KEY`, `UNIQUE`, `NOT NULL`; duplicate-column detection; types `INTEGER`/`INT`/`BIGINT`/`SMALLINT`, `TEXT`/`VARCHAR`, `REAL`/`FLOAT`/`DOUBLE`/`DECIMAL`, `BOOLEAN` |
-| `CREATE [UNIQUE] INDEX` | single-column, named indexes; `IF NOT EXISTS` supported; persists as a dedicated cell-based B-Tree |
-| `INSERT INTO` | auto-ROWID for INTEGER PRIMARY KEY; UNIQUE enforcement via indexes; clean type errors (no panics) |
-| `SELECT` | `*` or column list, `WHERE`, `ORDER BY col [ASC\|DESC]`, `LIMIT n`. `WHERE col = literal` probes an index when one exists |
-| `UPDATE` | multi-column `SET`, `WHERE`; UNIQUE + type enforcement; arithmetic in assignments (`SET age = age + 1`) |
+| `CREATE TABLE` | `PRIMARY KEY`, `UNIQUE`, `NOT NULL`; duplicate-column detection; types `INTEGER`/`INT`/`BIGINT`/`SMALLINT`, `TEXT`/`VARCHAR`, `REAL`/`FLOAT`/`DOUBLE`/`DECIMAL`, `BOOLEAN`. Auto-creates `sqlrite_autoindex_<table>_<col>` for every PK + UNIQUE column |
+| `CREATE [UNIQUE] INDEX` | Single-column, named indexes; `IF NOT EXISTS`; persists as a dedicated cell-based B-Tree. INTEGER + TEXT columns only |
+| `INSERT INTO` | Explicit column list required; auto-ROWID for `INTEGER PRIMARY KEY`; multi-row `VALUES (…), (…)`; UNIQUE enforcement; clean type errors (no panics); NULL padding for omitted columns |
+| `SELECT` | `*` or column list; `WHERE`; single-column `ORDER BY [ASC\|DESC]`; `LIMIT n`. `WHERE col = literal` probes an index when one exists |
+| `UPDATE` | Multi-column `SET`; `WHERE`; UNIQUE + type enforcement; arithmetic in assignments (`SET age = age + 1`) |
 | `DELETE` | `WHERE` predicate or full-table delete |
+| `BEGIN` / `COMMIT` / `ROLLBACK` | Real transactions, snapshot-based; WAL-backed commit; single-level (no savepoints); auto-rollback if `COMMIT`'s disk write fails |
 
-Expressions in `WHERE` and `SET`:
+Expressions in `WHERE` and `UPDATE`'s `SET` RHS:
 
 - Comparisons — `=`, `<>`, `<`, `<=`, `>`, `>=`
-- Logical — `AND`, `OR`, `NOT`
+- Logical — `AND`, `OR`, `NOT` (SQL three-valued logic; NULL-as-false in `WHERE`)
 - Arithmetic — `+`, `-`, `*`, `/`, `%` (integer ops stay integer; any `REAL` promotes to `f64`; divide/modulo by zero is a clean error)
 - String concat — `||`
-- Literals — numbers, single-quoted strings, booleans, `NULL`; parentheses
+- Literals — integer + real numbers, `'single-quoted strings'`, `TRUE` / `FALSE`, `NULL`; parentheses for grouping
 
-Not yet implemented: joins, subqueries, `GROUP BY` / aggregates, `DISTINCT`, `LIKE` / `IN` / `IS NULL`, expressions in the projection list, `OFFSET`. See the [Roadmap](#roadmap).
+**Not yet supported** (common ones): joins, subqueries, CTEs, `GROUP BY` / aggregates, `DISTINCT`, `LIKE` / `IN` / `IS NULL`, expressions in the projection list, column aliases, `OFFSET`, multi-column `ORDER BY`, savepoints, `ALTER TABLE`, `DROP TABLE`, `DROP INDEX`. The [full list with context](docs/supported-sql.md#not-yet-supported) lives in the reference.
 
 #### Meta commands
 

docs/_index.md

@@ -5,7 +5,8 @@ A small, hand-written guide to the SQLRite codebase — how it's structured, how
 ## Start here
 
 - [Getting started](getting-started.md) — install toolchain, build, run the REPL, your first `CREATE TABLE`
-- [Using SQLRite](usage.md) — complete REPL / SQL / meta-command reference
+- [Using SQLRite](usage.md) — REPL flow, meta-commands, history, launch modes
+- [Supported SQL](supported-sql.md) — canonical reference for every statement, operator, and edge case the engine executes today (plus what's not supported yet)
 - [Desktop app](desktop.md) — downloads, unsigned-installer bypass steps, and the Tauri architecture
 - [Smoke test](smoke-test.md) — step-by-step walkthrough to sanity-check REPL + desktop app after any non-trivial change
 - [Architecture](architecture.md) — high-level layer diagram and module map