graph_weaver 0.4.6 → 0.5.0

data/PLAN.md

@@ -1,144 +1,115 @@
 # Project Plan — GraphWeaver, typed GraphQL client for Ruby/Sorbet
 
-_Resume-from-here notes. README documents the product, NOTES.md is the
-research notebook this grew out of; this is the plan. Update on change._
+_Resume-from-here notes: where the project stands and what's next. The README
+documents the product, CHANGELOG records what changed, DECISIONS.md records the
+roads not taken, NOTES.md is the research notebook this grew out of. Update on
+change._
 
 ## Vision
 
 A "graphql-codegen for Ruby": `.graphql` queries + a schema (live class,
-introspection JSON, or SDL) → checked-in `# typed: strict` Ruby — nested
-T::Structs, generated casting, typed execute — so `srb tc` sees the exact
-shape of every query result. Dynamic (eval) mode for development, build
-step for CI/static checking. Runtime deps: graphql + sorbet-runtime only
-(graphql-client is NOT a dependency; the exploration outgrew it).
-
-## State: v0.0.1 on rubygems; v0.0.2 accumulating on main
-
-`make check` = bin/generate (spec fixture regeneration; parity specs
-enforce freshness) + rspec + srb tc.
-
-Language coverage: queries, mutations, typed variables (kwargs on
-execute, optional-when-defaulted), fragments (inline, named, interface
-conditions), union- AND interface-typed fields (__typename dispatch,
-required at generation time), enums (T::Enum), custom scalars via the
-ScalarType registry (register_scalar: codec inference off .parse/.load,
-requires:, opt-in input coercion incl. built-ins).
-Sources: live schema / introspection JSON / SDL — byte-identical output
-(enum values + abstract-type members sorted for determinism).
-Transport: executor precedence per call → per module → baked const →
-GraphWeaver.executor; Transport::HTTP (zero-dep) + opt-in Transport::Faraday
-(url / block middleware / ready connection), e2e specs against WEBrick.
-Errors: typed Response envelope (partial data + extensions survive) and
-a GraphWeaver::Error hierarchy (Transport/Server/Query/Validation/Type)
-with extensible transport-error classification, schema_stale? staleness
-detection, errors_at/each_error/report field-level surfacing (entity
-ids resolved from partial data), and #to_h machine output throughout.
-Dynamic mode: GraphWeaver.parse (paths or raw strings, derived names,
-container-scoped constants) and GraphWeaver.execute one-shots.
-Schema fetching: SchemaLoader.introspect(executor, cache:, ttl:) off
-live endpoints; load takes paths, content, or Hashes.
-Testing (graph_weaver/testing + graph_weaver/rspec): FakeExecutor
-(schema-correct castable fakes, faker semantics, GraphQL-name
-overrides, corrupt:, fail_at: with null propagation), Failure canned
-executors + SequenceExecutor, cassettes with shape-preserving
-anonymization, rspec seed + auto_fake integration. Selection module is
-the single shared query-walk (codegen/fake/anonymizer).
-Federation supergraph SDL loads transparently (needs
-directive_defaults_patch until upstream fix ships).
-Live validation: make integration (GitHub + Countries APIs).
-
-## Next steps (in rough order)
-
-~~Extraction~~ DONE 2026-07-07: this repo IS the gem now — GraphWeaver,
-github.com/dpep/graph_weaver, rspec-uuid conventions throughout. The
-graphql-client spikes live in git history (tag: `exploration`) and
-NOTES.md. Prior-art check partially answered: graphql-client PR #7
-(tapioca compiler over schema-wide dynamic classes) stalled since
-Jan 2024 with users asking; schema-wide typing can't catch
-unfetched-field bugs or type unions/interfaces — the niche looks open.
-
-~~Input objects~~ DONE 2026-07-11: module-level T::Structs, serialize/
-to_h, hash coercion at the execute boundary.
-~~Release~~ 0.1.0 cut 2026-07-11 (breaking: execute returns the
-Response envelope; execute! for raise-or-result).
-
-1. Stable class naming design — names come from GraphQL type names per
-   selection site; must not shift when unrelated selections are added
-   (generated code is app-code API). Current: one-level field-name
-   disambiguation, then raise. Shipped in 0.1.0 as-is — a naming change
-   is fair game pre-1.0 but should land early.
-2. CLI entrypoint (graph_weaver generate --schema X --queries dir) —
-   bin/generate is spec-fixture tooling, not shipped.
-3. Subscriptions (unsupported; raise). Recursive input types (raise).
-6. Parse/execute memoization: repeated GraphWeaver.parse/execute of the
-   same [schema, query] re-generates and re-evals every call (~3x the
-   cost of a cached module; benchmarked 2026-07-09) — memo keyed on
-   schema/query/name/executor, minding shared executor= mutation.
-   (Schema-side caching landed: SchemaLoader.introspect cache:/ttl: +
-   introspection_result primitive for Rails.cache et al. Possible
-   follow-up: re-introspect + retry once on validation-shaped
-   QueryErrors, since GraphQL has no standard schema-version signal.)
-7. Nice-to-haves: __typename auto-injection (currently required manually
-   on abstract selections), fragment reuse across queries, directives on
-   selections (@skip/@include make non-null fields nullable).
-8. Tapioca DSL compiler over dynamic mode (idea from graphql-client
-   PR #7): RBI the GraphWeaver.parse-eval'd modules so development mode
-   gets static types without the bin/generate build step — tapioca is
-   already in every Sorbet shop's workflow. Upstream's
-   Tapioca::Dsl::Helpers::GraphqlTypeHelper is prior art for type mapping.
-
-## External dependencies
-
-- rmosolgo/graphql-ruby#5659 (directive-argument defaults fix; our branch
-  `directive-argument-defaults` in ~/code/lib/ruby/graphql, pushed to the
-  dpep fork, PR in draft). When it ships in a release: bump graphql,
-  delete lib/graph_weaver/directive_defaults_patch.rb + its requires (TODO in file).
+introspection JSON, SDL, or an Apollo supergraph) → checked-in `# typed: strict`
+Ruby — nested `T::Struct`s, generated casting, a typed `execute` — so `srb tc`
+sees the exact shape of every query result. Dynamic mode for consoles, a build
+step for CI. Runtime deps: `graphql` + `sorbet-runtime`, nothing else.
+
+## State
+
+`0.4.6` on RubyGems. `main` carries a large unreleased body of work headed for
+**0.5.0** — see `## Unreleased` in the CHANGELOG, which is long and has a real
+upgrade story to tell.
+
+Green gate is in `CLAUDE.md`; `make check` runs the core of it.
+
+**What's built**, in brief — the CHANGELOG has the detail:
+
+- **Codegen.** Queries and mutations, typed variable kwargs, fragments (inline,
+  named, shared across queries), unions and interfaces (a struct per named
+  condition plus a forward-compatible `Other`), enums as `T::Enum`, custom
+  scalars, `@skip`/`@include` nullability. Generated class names derive from the
+  response key, so they're stable under unrelated edits. Shared types live once
+  per schema in `GraphQLTypes`.
+- **Sources.** Live schema class, introspection JSON, SDL, Apollo supergraph
+  (composition machinery stripped, `@inaccessible` subtracted to the API schema —
+  verified identical to Apollo's own `toAPISchema`), and raw subgraph SDL.
+- **Transports.** `Transport::HTTP` (zero-dep, pooled, keep-alive) by default;
+  Faraday on explicit opt-in. `InProcess` wraps a live schema class with
+  `context:`, logging and branded errors. Composable `Retry` honouring
+  `Retry-After`. One instrumentation seam covering both paths.
+- **Errors.** A typed `Response` envelope, an error hierarchy split by failure
+  site, field-level reporting with entity ids, `schema_stale?`, `#to_h`
+  throughout.
+- **Testing.** Schema-correct fakes, failure simulation, anonymizing cassettes,
+  and an in-process federation router that runs real subgraph resolvers —
+  verified against a real `@apollo/gateway` (42 identical, 1 refused, 0 wrong),
+  refusing at plan time anything it can't answer faithfully. One rspec tag picks
+  the mode: `graphql: :fake | :in_process | :router`.
+- **Lifecycle.** `generate` / `verify` / `schema:refresh` / `schema:diff` /
+  `queries:check` / `federation:diff`, plus `rails g graph_weaver:install`.
+
+## Next
+
+1. **Cut 0.5.0.** Needs an upgrade guide rather than a changelog dump — the
+   breaking list is long, but most of it is caught mechanically, so the guide is
+   largely *"regenerate, then follow `srb tc` and `verify_generated!`"*.
+   `gem push` needs an OTP.
+2. **`extend_type`'s mixin forms can't be statically checked.** A mixin's method
+   bodies are checked in the module's scope, not the struct's, so the docs have
+   to recommend `# typed: false` or `T.unsafe(self)`. In a library whose pitch is
+   static checking, that's a seam worth a design pass. Note `alias:` — which
+   emits into the struct body — *is* checked, which suggests the mixin forms are
+   the ones carrying the cost.
+3. **Nice-to-haves, unclaimed.** `write_timeout` on `Transport::HTTP` (and
+   possibly a `net_http:` passthrough rather than more kwargs); a Tapioca DSL
+   compiler so dynamic `parse` modules get static types without the build step.
+
+## Federation router: what it still refuses
+
+Each refuses at plan time with the type, field, subgraphs and next action. The
+cost of moving each boundary, if a real query mix ever demands it:
+
+- **`@requires` needing a chain** — the prefetch's own key must come from the
+  subgraph in hand; needs a real dependency DAG.
+- **An abstract type the supergraph doesn't break down** — a union or interface
+  at a boundary now plans, one branch per concrete type, bucketed on
+  `__typename` at execution. What is left is the supergraph that doesn't say
+  which concrete types a subgraph answers it with — no
+  `@join__unionMember`/`@join__implements`, and the type in more than one
+  subgraph. Closing it means reading a join version that predates those
+  directives; a modern composition always carries them.
+- **A nested field set no one fetch can build** — a nested field set now
+  crosses as the object it is, to any depth. What is left is the one whose
+  fields are split across subgraphs (`origin` in one and `origin.lat` in
+  another, or a `@key`'s object a `@requires` would half-fill from
+  elsewhere): a representation comes from one fetch, so the object would
+  arrive in pieces. Closing it means merging the pieces, which
+  `DECISIONS.md` argues against — the shapes that produce a split are the
+  ones where a real gateway stops being an oracle.
+- **Mutation root fields spanning subgraphs** — root mutation fields run in
+  series, so grouping them would run them in plan order.
+- **An alias shadowing an injected `@key`** — Apollo resolves the collision in
+  favour of its own key and a spec-conformant server doesn't, so there is no one
+  answer to agree with. Unfixable by design.
+
+`rake graph_weaver:federation:coverage` reports the refusal rate against a real
+supergraph and query set. That number decides whether any of the above is worth
+building — on the demo corpus it is 17/17.
+
+## Stated non-goals
+
+Recorded so they read as decisions rather than omissions, with the reasoning in
+`REVIEW.md` §7: subscriptions, `@defer`/`@stream`, file uploads, normalized
+caching, fragment masking, request batching, and a watch mode.
 
 ## Gotchas worth remembering
 
-- graphql-ruby to_definition/from_introspection reorder enum values and
-  possible_types — codegen sorts both; keep any new emission deterministic
-- schemas built from introspection/SDL have no scalar coercion or
-  resolvers — codegen must stay name-keyed, never call schema runtime hooks
-- graphql-client (the gem) casts scalars via coerce_isolated_input and
-  only with a live schema class — documented in the early specs
-
-## From the field-test experiments (2026-07-12)
-
-Generated-module size (2026-07-12, post-0.2.0): input structs are now
-table-driven (InputStruct runtime + FIELDS) — the PokeAPI filtered-query
-module dropped 29,233 -> 11,562 lines. The floor is ~2 lines/field
-(typed const + FIELDS entry). Remaining lever if it matters again:
-shared input structs emitted once per schema instead of per module.
-
-
-A junior + senior agent pair exercised the repo cold (clone, examples,
-extensions, a Pokedex app against Hasura's 4,441-type PokeAPI schema).
-Fixed same-day: snake_case type names generated invalid constants
-(camelize), GraphQL::ParseError/NotImplementedError escaping the Error
-umbrella, HttpExecutor timeouts, GitHub's top-level "type" error codes,
-typo'd client registrations silently no-oping. Still open:
-
-~~Recursive input types~~ DONE 2026-07-12: register-before-walk breaks
-the recursion; emission dependency-orders the structs and, for cycles,
-forward-declares the classes in an eval (srb rejects reopening a
-T::Struct statically, but adding props at runtime works — the full
-bodies below the eval are all srb sees). Verified live against Hasura
-bool_exp.
-
-~~Connection reuse in Transport::HTTP~~ DONE 2026-07-12: persistent
-keep-alive connection behind a mutex, dropped on any failure; net/http's
-keep_alive_timeout handles idle expiry. Faraday remains the pooling
-answer.
-
-- Subscriptions; @defer/@stream (routers send multipart responses — the
-  transport classifies them as ServerError today, no incremental support).
-- Shared input-type structs across generated modules: one Hasura
-  bool_exp variable pulls its whole recursive closure into EVERY module
-  (~28k lines each) — correct but heavy in PRs; needs cross-module
-  sharing or selection-based pruning (field-test round 2).
-- Structured logging: log_tag pairs lines and names operations now, but
-  events are prose — an optional {event:, url:, ms:} payload contract, a
-  scrub_variables hook, and cache-age on hit lines (field-test round 2).
-- Cut 0.1.1 — RubyGems 0.1.0 is materially behind main (snake_case fix,
-  recursive inputs, keep-alive, logging, error umbrella).
+- graphql-ruby's `to_definition`/`from_introspection` reorder enum values and
+  possible types — codegen sorts both; keep any new emission deterministic.
+- Schemas built from introspection or SDL have no scalar coercion or resolvers,
+  so codegen stays name-keyed and never calls schema runtime hooks.
+- A `SchemaDefinition` node reprints without its body when the root type names
+  are the GraphQL defaults, so directives on `schema` must be stripped before
+  reprinting a supergraph.
+- Code the build doesn't exercise rots silently — integration specs excluded from
+  the default run, examples the generator skips, doc samples nobody executes.
+  Six fabricated doc samples were found in one session by running them.

data/README.md

@@ -3,14 +3,19 @@ GraphWeaver
 ![Gem](https://img.shields.io/gem/dt/graph_weaver?style=plastic)
 [![codecov](https://codecov.io/gh/dpep/graph_weaver/branch/main/graph/badge.svg)](https://codecov.io/gh/dpep/graph_weaver)
 
-A typed GraphQL client for Ruby, built for federation, extensibility, Sorbet, and testing.
+**Your `.graphql` files, compiled into Sorbet types — and the fakes to test them.**
 
-GraphWeaver generates `# typed: strict` Ruby from your queries: nested `T::Struct`s, casting code, and a typed `execute` — so `srb tc` sees the exact shape of every query result, and a typo'd field is a static error, not a runtime surprise.
+GraphWeaver is graphql-codegen for Ruby. Write a query as a `.graphql` file and it
+generates checked-in `# typed: strict` Ruby — nested `T::Struct`s, casting, a typed
+`execute` — so `srb tc` knows the exact shape of every result. The schema can be a
+live graphql-ruby class, an introspection dump, SDL, or an Apollo supergraph;
+at runtime the only dependencies are `graphql` and `sorbet-runtime`.
 
 ```graphql
-# queries/person.graphql
+# app/graphql/queries/person.graphql
 query($id: ID!) {
   person(id: $id) {
+    id
     name
     birthday
     pets { name }
@@ -18,132 +23,146 @@ query($id: ID!) {
 }
 ```
 
+`rake graph_weaver:generate` turns that file into a `PersonQuery` module, and what
+comes back is a struct rather than a Hash you have to trust:
+
 ```ruby
-result = PersonQuery.execute!(id: "1")   # typed result, or raises on errors (execute returns an envelope)
+result = PersonQuery.execute!(id: "1")   # or #execute, for the Response envelope
 
-result.person&.name       # => "Daniel" (typed String)
-result.person&.birthday   # => Date (custom scalars deserialize)
-result.person&.nmae       # => srb tc: Method `nmae` does not exist
-```
+result.person&.name                # => "Daniel"
+result.person&.birthday            # => #<Date: 1990-06-15>   custom scalars deserialize
+result.person&.pets&.map(&:name)   # => ["Shelby", "Brownie"]
 
-New here? The **[getting started](docs/getting_started.md)** guide walks the
-production setup end to end — initializer, codegen, fakes, CI. Or run the
-**[examples](examples/)**, smallest first: `examples/countries.rb` (public
-API, no auth, all dynamic), `examples/rick_and_morty.rb` (filtering,
-pagination, a block-built type helper), and `examples/github/run.rb`
-(auth + checked-in generated modules; it stars this repo ⭐ and introduces
-you to your fellow stargazers).
+result.person&.nmae
+# srb tc: Method `nmae` does not exist on `PersonQuery::Result::Person`
+#         Did you mean `name`?
+```
 
-#### Features
+`person` is `T.nilable` because the schema says the field is nullable — the `&.`
+isn't defensive, it's the schema talking. A field you misspelled, or never
+selected, is a typecheck error rather than a `NoMethodError` in production.
 
-- **Queries and mutations** with typed variable kwargs — enums as `T::Enum`s, input objects as `T::Struct`s, required vs optional falling out of nullability and defaults
-- **Fragments** (inline, named, type conditions), **unions and interfaces** (member structs, `__typename` dispatch), **custom scalars** (pluggable registry), `@skip`/`@include` nullability
-- **Any schema source**: live schema class, introspection JSON, or SDL — including Apollo Federation supergraph SDL; introspect live endpoints with caching
-- **Any transport**: in-process schema execution, the zero-dependency HTTP executor, or Faraday with your own middleware — plus a composable `Retry` (exponential/linear/custom backoff, jitter, retry-by-error-class or GraphQL code) — swap per call with `executor:`
-- **Structured errors**: a typed response envelope (partial data + extensions survive), an error hierarchy split by failure site, field-level reports with entity ids, and `schema_stale?` detection — every error dual-surfaced as a human message plus JSON-ready `#to_h`
-- **Testing built in**: schema-correct fakes, failure simulation, record/replay cassettes with anonymization, rspec integration
-- **Dynamic mode** for development: `GraphWeaver.parse(...)` generates and evals on the fly, no build step
+Typed structs are the part every generator gets right. What decides whether you're
+still happy six months in is everything around them.
 
-#### Usage
+## Precise types are expensive to fake, so it fakes them for you
 
-Three ways to run a query — pick by context:
+Generation makes result types exact, which makes them tedious to build by hand —
+and most generators stop there and leave you the fixtures. GraphWeaver ships the
+fabricator. One line in the spec helper:
 
-| Context | Use |
-|---------|-----|
-| Production | checked-in codegen (`rake graph_weaver:generate`) — reviewed, `srb tc`-checked |
-| Development, consoles | `client.parse` / `client.load_queries!` — no build step |
-| Scripts, one-offs | `client.execute!` — no module at all |
+```ruby
+require "graph_weaver/rspec"
+```
 
-The production path assembled is the [getting started](docs/getting_started.md);
-the pieces:
+then one tag says what an example runs against:
 
 ```ruby
-require "graph_weaver"
-
-# a client for one server: transport (Faraday when loaded), auth, and a
-# lazily introspected schema. The first argument is a url or any schema
-# source — a live schema class, or a .json/.graphql dump
-api = GraphWeaver.new("https://api.example.com/graphql", auth: ENV["API_TOKEN"], cache: true)
-
-# make it the app default — generated modules execute through it
-GraphWeaver.client = api
-
-# generate checked-in typed modules (rake graph_weaver:generate, or directly)
-source = GraphWeaver::Codegen.generate(
-  schema: api.schema,
-  query: File.read("queries/person.graphql"),
-  module_name: "PersonQuery",
-)
-File.write("app/queries/person_query.rb", source)
-
-# at runtime
-PersonQuery.execute(id: "1")                        # via GraphWeaver.client
-PersonQuery.execute(other_client, id: "1")          # or per call
+it "shows the profile", graphql: :fake do
+  person = PersonQuery.execute!(id: "1").person
+
+  person.name       # => "Shakita Stark"      fabricated from your schema
+  person.birthday   # => #<Date: 2024-12-16>  custom scalars included
+  person.pets.size  # => 2
+end
 ```
 
-Module names derive from the operation name (`query GetPerson` →
-`GetPerson`) or, for `parse` on a `.graphql` file, from the file name;
-pass `module_name:`/`name:` to override. Pass `client:` (a constant) to
-bake a default client into the generated module. Prefer Faraday? It's
-opt-in (`gem "faraday"`), and the client picks it up when loaded —
-middleware blocks and ready connections in [transports](docs/transports.md).
+No fixture, no stub, no HTTP — and the values are seeded from rspec's own seed, so
+`--seed 4242` hands back that same person and a failure reproduces. The tag also
+picks a *real* client when you want one: `:in_process` runs your resolvers,
+`:router` runs them across a federated graph. Field-level failure simulation and
+record/replay cassettes with anonymization are in [testing](docs/testing.md).
 
-In development, skip the build step entirely — modules from `client.parse`
-carry the client's transport, no global wiring needed:
+## Federation without a gateway
 
-```ruby
-# parse a query into a typed module on the fly — a .graphql path or a raw string
-PersonQuery = api.parse("queries/person.graphql")
-PersonQuery.execute(id: "1")
+When your app is both a GraphQL client and a subgraph, the local router plans a
+query across the composed supergraph and runs your **real resolvers** over the
+boundary — no gateway process, no node, no sockets. That's
+[`examples/federation.rb`](examples/federation.rb), the example that needs no network:
+
+```
+$ bundle exec examples/federation.rb
+#<GraphWeaver::Testing::Router subgraphs=["accounts", "products", "reviews"]>
 
-# or every query file at once (queries_path convention), named like generation would
-api.load_queries!
+dpep reviewed 2 products:
+  Table ($899) — Love it
+  Couch ($1299) — Too expensive
 
-# or one-shot, no module at all — variables are plain kwargs
-api.execute!("query($id: ID!) { person(id: $id) { name } }", id: "1")
+fetches:
+  → accounts  root fields
+  → reviews   _entities × 1 User
+  → products  _entities × 2 Product
 ```
 
+The trace is the query plan: every node at a level in one `_entities` call, so two
+products cost one fetch. Anything it can't answer *faithfully* it refuses at plan
+time rather than guessing — and it's diffed against a real `@apollo/gateway` over
+the same supergraph, currently 42 queries identical, 1 refused, 0 wrong
+([`spec/integration/router_parity_spec.rb`](spec/integration/router_parity_spec.rb)).
+See [federation](docs/federation.md).
 
-#### Dig deeper
+## The schema keeps itself honest
 
-- **[Getting started](docs/getting_started.md)** — the production path in Rails,
-  step by step: initializer, rake tasks, fakes, CI, Sorbet or not
-- **[Generated modules](docs/generated_modules.md)** — module anatomy, typed
-  variables (enums, input objects), fragments/unions/interfaces,
-  `@skip`/`@include`, naming, clients, dynamic mode
-- **[Against a real API](docs/real_world.md)** — the exploratory tour:
-  introspect a live endpoint (GitHub end to end), dynamic mode, schema caching
-- **[Federation](docs/federation.md)** — Apollo Federation: supergraph vs API
-  schema, feeding weaver a composed graph, the `@inaccessible` caveat
-- **[Transports](docs/transports.md)** — clients, the execute contract,
-  Faraday, retries and backoff
-- **[Custom scalars](docs/scalars.md)** — the registry: codec inference,
-  requires, input coercion
-- **[Errors](docs/errors.md)** — the Response envelope, the error hierarchy,
-  field-level reports with entity ids, stale-schema detection
-- **[Logging](docs/logging.md)** — point `GraphWeaver.logger` at any Logger:
-  wire traffic at debug, introspection/cache/codegen at info, errors at warn
-- **[Testing](docs/testing.md)** — schema-correct fakes, failure simulation,
-  rspec integration
-- **[Cassettes](docs/cassettes.md)** — capture and replay real API
-  responses; anonymized recording (`GRAPHWEAVER_RECORD=1`, rake tasks)
+The lifecycle is rake tasks, not a CI pipeline you assemble yourself:
+`schema:refresh` re-introspects the committed dump, `schema:diff` fails when the
+server has drifted, `queries:check` names the queries that drift broke and where,
+and `verify` fails when the checked-in Ruby is stale. Generation is deterministic
+— same schema and queries, byte-identical files — so regenerating never shows a
+diff you didn't earn. See [getting started](docs/getting_started.md#5-verify-in-ci).
 
-----
-## Installation
+## Start here
 
 ```ruby
 # Gemfile
 gem "graph_weaver"
 ```
 
-or
+In Rails, setup is then one command:
 
 ```sh
-gem install graph_weaver
+rails g graph_weaver:install https://api.example.com/graphql
 ```
 
+which writes the initializer, the `app/graphql` layout, the editor config and the
+schema dump. **[Getting started](docs/getting_started.md)** walks the production
+setup end to end. Or skip the build step entirely and poke at an API from a
+console — anything holding a schema parses, and the module runs on what parsed it:
+
+```ruby
+api = GraphWeaver.new("https://countries.trevorblades.com/")
+CountryQuery = api.parse("queries/country.graphql")   # a path or a raw string
+CountryQuery.execute!(code: "JP").country&.capital    # => "Tokyo"
+
+api.run!("query { continents { name } }").continents  # or no module at all
+```
+
+The **[examples](examples/)** run that path for real, smallest first: a public API
+in 30 lines, a paginated search, the production path against GitHub, and the
+federated graph above.
+
+#### Also in the box
+
+- **Queries and mutations** with typed variable kwargs — enums as `T::Enum`s, input objects as `T::Struct`s, required vs optional falling out of nullability and defaults
+- **Fragments** (inline, named, type conditions), **unions and interfaces** (member structs, `__typename` dispatch), `@skip`/`@include` nullability
+- **Any transport**: in-process execution, a zero-dependency HTTP client, or Faraday with your own middleware — plus a composable `Retry` with backoff and jitter
+- **Structured errors**: a typed envelope that keeps partial data and extensions, an error hierarchy split by failure site, field-level reports with entity ids, and stale-schema detection
+
+#### Dig deeper
+
+- **[Getting started](docs/getting_started.md)** — the production path in Rails, step by step
+- **[Generated modules](docs/generated_modules.md)** — module anatomy, typed variables, fragments/unions/interfaces, naming, clients, dynamic mode
+- **[Testing](docs/testing.md)** — fakes, failure simulation, the rspec tags
+- **[Federation](docs/federation.md)** — supergraph vs API schema, the local router, what it refuses
+- **[Transports](docs/transports.md)** — the execute contract, Faraday, retries and backoff
+- **[Errors](docs/errors.md)** — the Response envelope, the error hierarchy, field-level reports
+- **[Custom scalars](docs/scalars.md)** — the registry: codec inference, requires, input coercion
+- **[Cassettes](docs/cassettes.md)** — capture and replay real responses, anonymized
+- **[Editor support](docs/editors.md)** — five lines of YAML for schema autocomplete in `.graphql` files, no JS project
+- **[Against a real API](docs/real_world.md)** — introspecting a live endpoint, GitHub end to end
+- **[Logging](docs/logging.md)** — point `GraphWeaver.logger` at any Logger
+
 ----
 ## Development
 
 - `make check` — regenerate spec fixtures, run specs, typecheck
-- `make integration` — one-off checks against the live GitHub and Countries APIs
+- `make integration` — one-off checks against live APIs (GitHub needs a token) and a federation gateway (needs node)