added AGENTS.md & DOCS

Author: dg

.gitattributes

@@ -1,9 +1,11 @@
 .gitattributes  export-ignore
 .github/        export-ignore
 .gitignore      export-ignore
+AGENTS.md       export-ignore
 ncs.*           export-ignore
 phpstan*.neon   export-ignore
 src/**/*.latte  export-ignore
+docs/           export-ignore
 tests/          export-ignore
 
 *.php*          diff=php

AGENTS.md

@@ -0,0 +1,82 @@
+# To My Agents!
+
+It is my fervent wish that this file guide every AI coding agent working with code in this repository.
+
+## Documentation
+
+Any distilled, agent-facing documentation for this package - how it works
+internally and the rationale behind key design decisions - lives in `docs/`.
+Consult it before non-trivial changes; it is the source of truth from which the
+public manual is distilled.
+
+Two independent worlds - the low-level core and the Explorer (ActiveRow) layer -
+each with sharp edges (lazy execution, accessed-column narrowing, N+1 batching,
+context-detected preprocessor modes). Read `docs/internals/` before touching them.
+
+## Project Overview
+
+**Nette Database** is a database abstraction layer offering two components:
+
+1. **Core** - a PDO wrapper with an advanced SQL preprocessor and parameter
+   substitution.
+2. **Explorer** - an ActiveRow layer (inspired by NotORM) with convention-based
+   relationships and automatic N+1 prevention.
+
+Supports MySQL, PostgreSQL, SQLite, MS SQL Server, and Oracle.
+
+- **PHP Version**: 8.1 - 8.5
+- **Package**: `nette/database`
+
+## Essential Commands
+
+```bash
+# Run all tests
+vendor/bin/tester tests -s -C
+
+# Run one test directory / file
+vendor/bin/tester tests/Database/Explorer -s -C
+vendor/bin/tester tests/Database/Explorer/Explorer.basic.phpt -s -C
+
+# Static analysis (PHPStan level 5 + phpstan-nette)
+composer phpstan
+```
+
+Most tests connect to real MySQL/PostgreSQL/MS SQL servers via
+`@dataProvider databases.ini`. Bring the servers up with the repo's
+`docker-compose.yml` (`docker compose up -d`, wait for `healthy`) before running
+them; a `Connection refused` / `could not find driver` failure means the servers
+aren't up yet, not a broken test.
+
+## Conventions
+
+- Every file starts with `declare(strict_types=1);`; everything typed; single
+  quotes unless the string contains an apostrophe; Nette Coding Standard.
+- Use generic annotations for IDE/PHPStan support: `@return Selection<ProductRow>`,
+  `@template T of ActiveRow`. Method phpDoc starts with a 3rd-person verb (Returns,
+  Formats, Checks); document a param/return only when it adds info beyond the type.
+- Tests are Nette Tester `.phpt` files; use `@dataProvider databases.ini` to run
+  against every engine, `test()` / `testException()` with descriptive names, and
+  **no comment before `test()`**. Fixtures: `tests/Database/files/{driver}-nette_test1.sql`.
+
+## Working in this repo
+
+- **The Explorer is lazy and self-narrowing.** `accessColumn` is the single seam
+  every read passes through; a first query fetches `SELECT *`, later ones narrow to
+  the accessed columns (cached), and relations are batched to avoid N+1. The cache
+  key even depends on the call-site (`debug_backtrace`) - a real refactor trap. See
+  `docs/internals/explorer.md`.
+- **The SQL preprocessor picks its array mode from surrounding SQL context**
+  (`?and`/`?set`/`?values`/`?order`/`?list`), so the same array expands differently
+  after `WHERE` vs `SET` vs `INSERT`. See `docs/internals/sql-preprocessor.md`.
+- **Nested transactions use a depth counter, not savepoints** - only the outermost
+  `transaction()` issues a real BEGIN/COMMIT/ROLLBACK; there is no partial rollback,
+  and no retry mechanism (no `$attempts`, no `RetryableException`, no `onRetry`).
+  There is no `TypeConverter` class either (DB->PHP conversion is
+  `Helpers::normalizeRow`). Don't document designed-but-absent features as present.
+- **Array expansion is a mass-assignment surface.** Passing raw user input as the
+  array to `insert`/`update`/`where` lets an attacker set arbitrary columns and
+  inject operators/SQL via keys - always whitelist columns first. Full guidance is
+  web-manual material.
+- User-facing how-to (Explorer/Selection API, `?`-placeholder reference, NEON
+  config, transactions, Reflection API) is manual material and lives in the public
+  web docs, not here.

docs/internals/connection-drivers.md

@@ -0,0 +1,55 @@
+# Connection & drivers
+
+## Execution path
+
+`Connection` connects **lazily** — the constructor opens the PDO only when the `lazy`
+option is falsy; otherwise the first `getPdo()`/`getDriver()`/`preprocess()` triggers
+`connect()` (which also instantiates the driver from `PDO::ATTR_DRIVER_NAME`, builds
+the `SqlPreprocessor`, and fires `onConnect`).
+
+`query()` = `preprocess()` (which runs the preprocessor only when there are
+parameters) → `new ResultSet(...)`. **The SQL actually executes in the `ResultSet`
+constructor, not in `query()`** — so timing, binding, and exception conversion all
+live there (see results-and-types.md). The `fetch*` shortcuts on `Connection` just
+delegate to `query(...)->fetch*()`.
+
+## The `Driver` dialect abstraction
+
+Each engine implements `Driver`: `delimite` (identifier quoting — MySQL backticks,
+PgSql double-quotes, both doubling), `formatDateTime`/`formatDateInterval`/`formatLike`,
+`applyLimit`, schema reflection (`getTables`/`getColumns`/`getIndexes`/`getForeignKeys`/
+`getColumnTypes`), `convertException`, and `isSupported` over the `Support*` feature
+constants.
+
+**`applyLimit` is the most dialect-divergent piece** — MySQL uses `LIMIT` (with the
+`LIMIT 18446744073709551615 OFFSET` trick for offset-only), PgSql separate `LIMIT`/
+`OFFSET`, SQL Server `OFFSET … ROWS FETCH NEXT … ROWS ONLY`, MS SQL/ODBC inject a
+`TOP n` (no offset), Oracle wraps in a `ROWNUM` subquery. Result-set type detection is
+per-driver `getColumnTypes`: PgSql and MsSql map the whole result set via
+`Helpers::detectTypes`, MySQL/SQLite/Sqlsrv go column-by-column via
+`Helpers::detectType`, and Odbc/Oci detect nothing. MySQL adds dialect rules
+(`NEWDECIMAL` precision 0 → integer, `TINY` len 1 + `convertBoolean` → bool, `TIME` →
+interval).
+
+## Exception mapping
+
+```
+\PDOException → DriverException
+                 ├── ConnectionException → ConnectionLostException
+                 ├── ConstraintViolationException
+                 │     ├── ForeignKey / NotNull / Unique / CheckConstraintViolation
+                 ├── DeadlockException
+                 └── LockTimeoutException
+```
+
+Note `Deadlock`/`LockTimeout` extend `DriverException` **directly**, not the
+constraint hierarchy. There is **no** `RetryableException` marker and `transaction()`
+performs no retries — retrying on deadlock/lock-timeout/connection-lost is the
+caller's job. The mapping is **per driver** in
+`convertException`: MySQL keys on the numeric error code, PgSql on the SQLSTATE; an
+unrecognized error falls back to a bare `DriverException::from()`. `DriverException::from`
+parses `errorInfo`, or the `SQLSTATE[..] [..] ..` pattern from the message when
+`errorInfo` is absent. Conversion is invoked in the `ResultSet` constructor (which also
+attaches the query string and params) and in `getInsertId`; `connect()`/`quote()` use
+`ConnectionException::from`/`DriverException::from` directly because the driver may not
+exist yet.