…code generation

New NpgsqlRest.DartClient plugin (1.0.0), a TsClient sibling that generates Dart
fetch modules for Flutter on package:http only, with full TsClient feature parity:

- Request/response model classes with fromJson/toJson; composite types as nested
  classes; int/double split (smallint/int/bigint vs real/dp/numeric/money);
  DateTime for date/timestamp(tz); reserved-word and core-type escaping
- Query-string/path/body handling; defaulted params omitted when null so the
  database default applies; path placeholders resolved to request field names
- ApiResult<T>/ApiError status wrappers; login/logout special-casing
- Multipart uploads with byte-counting progress callback and XSRF header
- SSE: streamed-response SseSubscription + create{Name}EventSource factories,
  onMessage/id/closeAfterMs/awaitConnectionMs lifecycle, execution-id header
- Proxy raw responses: proxy_out and void pass-through return http.Response
- Per-call parseUrl/parseRequest rewrite hooks
- Testability: top-level httpClient override for MockClient injection
- Annotations: dartclient, dartclient_module (tsclient_module fallback),
  dartclient_status_code, dartclient_events, dartclient_parse_url,
  dartclient_parse_request, dartclient_export_url, dartclient_url_only

Client app: new NpgsqlRest:DartClientCodeGen config section wired through
App.cs, appsettings.json, ConfigTemplate, ConfigSchemaGenerator, ConfigDefaults.

Tests: 24 golden-file test files / 63 facts in NpgsqlRestTests/DartClientTests
(1:1 mirror of TsClientTests plus Dart-specific edge cases); all generated
corpora verified with dart analyze.

Docker: Dockerfile.jit restore layer gains DartClient plus the previously
missing SqlFileSource and Mcp project files.

New OpenApiOptions.SpecVersion option selects the specification version of the
generated document: "3.0" emits openapi: 3.0.3 (default, backward compatible),
"3.1" emits openapi: 3.1.1. The emitter uses no keyword whose semantics differ
between OpenAPI 3.0 and 3.1, so the rest of the document is identical - the
setting matters for toolchains that require a 3.1 document (JSON Schema 2020-12
alignment).

- Emitted version strings exposed as OpenApiSpecVersions.V30/V31 constants
  instead of inline literals
- Values trimmed and compared case-insensitively; any other value fails fast
  at handler construction (startup) with an error listing the valid values
- SpecVersion wired through the client config stack (App.cs binding,
  appsettings.json, ConfigTemplate, ConfigSchemaGenerator, ConfigDefaults)
- Tests: existing version assertion refactored to the constant; new
  SpecVersionTests assert the 3.1 document is identical to the 3.0 document
  apart from the openapi field, invalid values throw, valid values are
  trimmed/case-insensitive
- Changelog: v3.20.0 section 2

New ClientCodeGen.ReactQuery options generate a TanStack Query v5 hooks module
alongside each generated client module: useQuery hooks for GET endpoints and
useMutation hooks for other methods, with exported query-key factories.

- Hooks import the client functions via a relative import computed from the two
  FilePath values and derive all types from them (Parameters<typeof fn>[0] /
  Awaited<ReturnType<typeof fn>>), independent of ExportTypes and
  CreateSeparateTypeFile; v5 object syntax only, compiles under tsc --strict
- Whole request object used as a query-key segment; QueryKeyPrefix becomes the
  literal first key element; ExposeQueryKeys=false inlines keys and exports no
  factories; ImportFrom replaces the @tanstack/react-query specifier for teams
  routing TanStack through an internal wrapper module
- tsclient_hooks=off annotation excludes a routine from the hooks file only;
  SSE, upload and url-only endpoints never produce hooks; empty modules write
  no file; SkipTypes logs a warning and skips hooks (TypeScript-only)
- Enabled without FilePath, or with an empty ImportFrom, fails fast at handler
  construction (startup)
- No automatic cache invalidation - consumers wire onSuccess through the
  options passthrough (future @invalidates annotation will build on the
  exported key factories)
- Config wired through App.cs, appsettings.json, ConfigTemplate,
  ConfigSchemaGenerator, ConfigDefaults
- Tests: ReactQueryHooksTests (8 facts) - goldens for query/mutation/
  parameterless/prefix+inline-keys+custom-import shapes, absence asserts for
  SSE/upload/url-only/opt-out, constructor fail-fast facts; hooks corpus
  compile-verified with tsc --strict against @tanstack/react-query@5
- Changelog: v3.20.0 section 3

…rom the MCP tool set

New McpOptions.ToolSchemas options project the MCP tool catalog (routines
annotated with mcp) into three capability documents - every output is a
projection of the tool objects BuildTool already produced, so parameter
exclusion (claim-sourced/IP/virtual/resolved), description precedence and
type mapping are inherited, not rebuilt:

- OpenAI Chat Completions tools array: {type:function, function:{name,
  description, parameters}} with parameters = the MCP inputSchema verbatim
- Anthropic Messages API tools array: {name, description, input_schema},
  same verbatim schema, no extra keys
- llms.txt markdown: H1 from ServerName/database name, blockquote from
  Instructions, per-endpoint sections (method/URL/description/parameters
  read from inputSchema), Machine-readable section linking OpenAPI, /mcp
  and the tools documents

Details:
- Independent of McpOptions.Enabled: generated and served from mcp
  annotations even when the /mcp endpoint is disabled (generation runs in
  Cleanup before the Enabled gate; the client app registers the handler
  when either flag is on)
- Tool names sanitized to ^[a-zA-Z0-9_-]{1,64}$ in the JSON documents with
  a logged warning; llms.txt keeps original names; sanitization collisions
  fail fast at startup listing both names
- FileName/UrlPath/FileOverwrite semantics mirror the OpenAPI plugin; a
  config value explicitly set to null skips that file/endpoint (section-
  exists binding); GET-only serving, application/json and text/markdown,
  anonymous, built once at startup, deterministic output (ordered by tool
  name, no timestamps)
- ToolSchemas.OpenApiUrlPath is a code-only property wired by the client
  app from OpenApiOptions.UrlPath (the MCP plugin has no reference to the
  OpenAPI plugin)
- Config wired through App.cs, appsettings.json, ConfigTemplate,
  ConfigSchemaGenerator, ConfigDefaults
- Tests: McpToolSchemaTests (7 facts) with two fixtures - OpenAI/Anthropic
  schema parity with MCP inputSchema, required-array behavior, claim-param
  exclusion inheritance, name sanitization + collision fail-fast, llms.txt
  golden, documents served with /mcp disabled
- Changelog: v3.20.0 section 4; JSON config examples across the changelog
  now show the full surrounding structure from the root

The recently standardized HTTP QUERY method (safe and idempotent like GET,
carrying the query in the request body) is now supported end to end:

- Core: QUERY added to the Method enum. The HTTP QUERY [path] annotation
  (and proxy QUERY / proxy_out QUERY) parse it, routing matches it, and
  parameters default to the JSON request body (RequestParamType.BodyJson);
  request_param_type still overrides per endpoint. QUERY is opt-in via the
  annotation - name-based and SQL-file method inference are unchanged
- TsClient: emits method "QUERY" with body: JSON.stringify(request)
- ReactQuery hooks: QUERY endpoints map to useQuery (safe + idempotent =
  cacheable), not useMutation
- DartClient: emits _send('QUERY', uri, body: jsonEncode(request.toJson()))
- MCP: QUERY tools get readOnlyHint: true, same as GET
- OpenAPI: QUERY endpoints are skipped with a logged warning - OpenAPI
  3.0/3.1 path items have no query operation key (representable from
  OpenAPI 3.2, not yet an emission target)
- HTTP files / llms.txt / ToolSchemas work with the method string as-is

Tests (7 facts): runtime QUERY requests binding parameters from the JSON
body (incl. omitted defaulted param), TsClient and DartClient goldens,
useQuery hook mapping, OpenAPI document absence, MCP readOnlyHint.

Changelog: v3.20.0 section 5

…AME})

The default configuration's connection string now uses the required
environment variable syntax:

  Host={!PGHOST};Port=5432;Database={!PGDATABASE};Username={!PGUSER};Password={!PGPASSWORD}

Running with the default configuration and a missing variable fails
immediately at startup with an error naming exactly what to set, instead
of a cryptic downstream Npgsql host-resolution failure.

Supporting fixes:
- Connection strings (main and additional/test connections) are now
  resolved through ResolveEnv instead of the plain formatter, so the
  {!NAME} required and {NAME} optional syntaxes both work in any
  ConnectionStrings entry - previously {!NAME} was not substituted at all
  in connection strings even when the variable was set
- The serialization/inspection paths (--config output, config validation)
  use a non-throwing ResolveEnv mode that keeps the literal {!NAME}
  placeholder in rendered output, so the configuration can always be
  printed and validated before the environment is set up; real value
  access still fails fast
- Verified end-to-end: missing PGHOST names the variable at startup, all
  vars set connects normally, --config renders with placeholders intact

Changelog: v3.20.0 section 6

Also for the 3.20.0 release:
- docs: update README.md (Dart client, React Query hooks, MCP tool
  schemas/llms.txt, HTTP QUERY, OpenAPI 3.0/3.1, test count 2,484)
- docs: update .claude/skills/npgsqlrest (SKILL.md, annotations-reference.md,
  regenerated configuration-reference.jsonc)
- docs: add QUERY to the http/proxy/proxy_out --annotations syntax strings
- test: fix WireMock port collision (SqlFileHttpClientTypeFixture 50954 -> 50956)
  that intermittently failed the parallel Proxy fixtures