[doron050]

Summary

The README had grown into a long reference with multi-line caveats. This turns it into a short overview and gives every topic one page in docs/.

For users

Page	Contents
README.md	what the plugin is, SQL → generated code → usage, install, what's supported, options, doc index
docs/Generated-Code.md	files, the query class, rows and models, naming rules, logging, RuboCop / Steep
docs/Queries.md	annotations, arguments, macros, batches, :copyfrom
docs/Types.md	the Ruby type of each SQL type per database, time zones, enums
docs/Connections.md	pools, shared connections, forked workers, fibers, lost connections, prepared statements
docs/Transactions.md	commit / rollback, isolation, tx, what happens on errors and interrupts
docs/Options.md	every option, shared options, overrides
docs/Troubleshooting.md	the old "Limitations", as symptom → cause → fix per database

For contributors: Contributing, Architecture (now includes the WASM packaging from Design.md, which is removed), Testing, Coverage, Releasing.

Corrections found while checking the docs against the code

• Types were shown with PostgreSQL's classes for every database. SQLite dates / timestamps are String and booleans Integer; MySQL booleans are Integer; PostgreSQL time is a String. The type tables are now per database, taken from each driver's mapping.
• The generated Gemfile already has gem 'timeout', '>= 0.4' for a rubyVersion below 3.3; the docs told users to add it.
• Architecture.md: the generated-code snippet nested row classes inside QuerySql; they are module-level, as in examples/pg.
• Coverage.md: a sentence in the middle split the table; one row had missing columns; three rows had the wrong "not applicable" database. Rows are now grouped by topic (their content is unchanged).
• MySQL enum modules are named after table and column (ExtendedBiosBioType), which was not documented.

Not docs-only

scripts/docs/generate_examples.rb changed (intro and link layout of docs/Examples.md), so CI runs. No generator, examples/ or test changes.

Verification

• test/coverage_map_test.rb passes; every relative link and anchor in the README and docs/ was checked with a script.
• Not run: the rest of the unit suite, RuboCop, Steep and the end-to-end suites (nothing they cover changed).

Review notes

• The Troubleshooting fix for SQLite NUMERIC (call to_f, or declare Numeric with overrides) is my suggestion, not a tested behavior.
• Releasing.md is unchanged.

Suggested label: documentation.

🤖 Generated with Claude Code

https://claude.ai/code/session_01FskpZEyJE4jgCmz45fQCXg