The use_alias_generator branch predates the docs-site refactor (#446), so it
added these two guides as flat docs/07 and docs/08 pages and linked them from a
monolithic README. Move them under docs/02-guides/ to match the current
structure and repoint the config-reference links.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

The use_alias_generator branch predates the docs-site refactor (#446), so it
added these two guides as flat docs/07 and docs/08 pages and linked them from a
monolithic README. Move them under docs/02-guides/ to match the current
structure and repoint the config-reference links.

* feat: add use_alias_generator setting

* fix: don't silently ship wrong aliases or unformatted code

* fix: keep fragment forward references resolvable in operation modules

A generated client whose operation spreads a fragment could not be imported
on Python 3.10, with or without `defer_model_build`:

    PydanticUndefinedAnnotation: name 'UserFieldsFriends' is not defined

A fragment names its nested selections by forward reference, and an operation
that spreads it subclasses the fragment class from another module:

    # fragments.py
    class UserFields(BaseModel):
        friends: list["UserFieldsFriends"]

    # list_users.py
    class ListUsersUsers(UserFields):
        pass

Pydantic resolves the annotations a subclass inherits against the subclass's
own module, and `UserFieldsFriends` lives in `fragments`. On 3.11+ the
inherited `ForwardRef` evaluation is reused and this happens to work; on 3.10
it is re-evaluated and fails. `requires-python` is `>= 3.10` and the default
hatch environment pins 3.10, so this failed on the version CI runs.

With `defer_model_build` the same shape failed on every supported version,
because dropping the eager `model_rebuild()` calls removes the only thing
that ever resolved those references.

Emit the names the mixin bases need into the module that has to resolve them:

    from .fragments import (
        UserFields,
        UserFieldsFriends,  # noqa: F401
    )

The `noqa` is required because the name appears only inside an inherited
annotation. Keeping the build deferred rather than restoring the eager
fragment rebuilds preserves the whole import-time win - `defer_model_build`
now measures 1.79x faster to import on a 1448-type schema, against 1.74x
before, because no fragment models are built at import.

Add `ForwardRefNamesVisitor` and `collect_class_forward_ref_names()` in
`codegen.py`; `_map_fragment_forward_refs()` and `_mixin_forward_ref_import()`
in `package.py`. `ast.unparse` drops comments, so the line is injected as raw
source through the new `prepend_code` argument of `_queue_module`. Clients
with no fragment mixin are byte-for-byte unchanged.

The suite never caught this because every `expected_client` fixture is inert:
the tests diff generated source and never import it. Add two tests that
import a generated package and validate a payload, one per path. Both fail
only on Python 3.10, which the default hatch environment provides.

* docs: record graphql-core dependency and the two import-performance settings

`enable_custom_operations` makes the generated `base_operation.py` and
`client.py` import graphql-core to build and print a query AST at runtime, so
the generated package needs it alongside pydantic and httpx. It was missing
from "Generated code dependencies" and costs roughly 25 ms of import.

`defer_model_build` and `use_alias_generator` were documented in the README
but absent from the optional-settings list in `docs/02-configuration.md`,
where every other setting lives.

Also describe the `# noqa: F401` fragment import that generated operation
modules now carry, so it does not read as a code-generation bug to anyone
running a linter over the output.

* test: cover alias_generator in the multipart_uploads=false base-model test

Now that use_alias_generator exists, extend the no-upload base-model config test
to also enable it and assert alias_generator=to_camel lands on the generated
BaseModel - exercising the base-model source-path detection for all three
config rewrites in the uploads-disabled path.

* build: require pydantic >=2.8 for use_alias_generator

`use_alias_generator` sets `alias_generator=to_camel` and omits the explicit
`Field(alias=...)` for fields whose GraphQL name `to_camel` can reconstruct.
`to_camel`'s case handling was fixed in pydantic 2.8 (pydantic/pydantic#9561);
on earlier versions it could mangle names, so the generated package would
rebuild the wrong aliases. Raise the floor to 2.8 to match.

* docs: tighten the to_camel / pydantic 2.8 floor comments

* docs: move import-performance and fragments docs out of README

* fix: don't let the BaseModel config rewrite go missing unnoticed

* docs: drop the defer_model_build aside from the fragments page

* test: consolidate the rewrite_base_model config tests

* docs: place the import-performance and fragments guides in the docs site

The use_alias_generator branch predates the docs-site refactor (#446), so it
added these two guides as flat docs/07 and docs/08 pages and linked them from a
monolithic README. Move them under docs/02-guides/ to match the current
structure and repoint the config-reference links.

* fix: satisfy ty 0.0.62 in extract_operations and shorter_results

ty 0.0.62 (stricter than the version CI ran previously) flags two spots in
existing contrib plugins: the `ast.Constant.value` union widens the list
passed to `sorted()` past `SupportsRichComparison`, and `ImportFrom.module`
is `str | None` so indexing the `dict[str, set]` of extended imports with it
is rejected. Narrow the constant to `str` and bind/guard the module name.
No behaviour change.