graph_weaver 0.6.1 → 0.7.1

data/docs/i18n.md

@@ -0,0 +1,171 @@
+# Translating input errors
+
+graph_weaver hands your app **a stable key and the facts**, and lets the app own
+the sentence. `kind` — a Symbol from a short closed vocabulary — and the key
+derived from it, `graph_weaver.input.<kind>`, are API: they change only with a
+MAJOR bump, and a new one arrives only as an addition. `#message` is the
+developer's line, in English, and it will be reworded. See
+[errors](errors.md) for `InputError` itself and for what a server has to send.
+
+## Translating it
+
+No locale file ships — the strings are app-voice, not library-voice, and owning
+a user-visible English string would make every reword a breaking change. Paste
+this into your own `config/locales/en.yml`:
+
+```yaml
+en:
+  graph_weaver:
+    input:
+      type_mismatch: "%{field} must be a %{type}."
+      unparseable: "%{field} isn't a valid %{type}."
+      not_a_member: "%{field} must be one of: %{members}."
+      missing: "%{field} is required."
+      unknown: "%{field} isn't a field we recognize."
+      out_of_range: "%{field} is out of range."
+      invalid_format: "%{field} isn't in the right format."
+      refused: "%{field} was rejected."
+```
+
+```ruby
+def render_input_error(error)
+  I18n.t(
+    "graph_weaver.input.#{error.kind}",
+    field: error.field,
+    value: error.value,
+    **error.details,
+    default: error.message,   # untranslated kinds fall back, never "translation missing"
+  )
+end
+```
+
+One call serves both halves — a refusal raised before the request left, and one
+the server sent back:
+
+```ruby
+# before the wire
+rescue GraphWeaver::InputError => e
+  form.errors.add(e.field&.underscore || :base, render_input_error(e))
+
+# and after it, the same call
+response.input_errors.each { |e| form.errors.add(e.field&.underscore || :base, render_input_error(e)) }
+```
+
+`#field` is the schema's spelling on both sides, so one `underscore` is the whole
+mapping to a Rails form field. **Plan for `nil`** — nothing named a slot, which
+is what a server that states no input path gives you, and the default until your
+server adopts [the convention](errors.md#what-your-server-can-send).
+
+`default:` is load-bearing: `:refused` is untranslatable by definition, so every
+app needs the fallback — and having it means you can translate the four kinds you
+care about and leave the rest.
+
+## The vocabulary
+
+Eight kinds; a ninth arrives only when a real input failure fits none of them.
+The last four columns are **who can say it**, which is the other half of the
+story — a `kind` is worth only as much as the producer that can state it, and the
+last of them is any server at all, through the
+[convention](#what-the-server-has-to-do).
+
+| `kind` | means | `details` carries | client | graphql-ruby | Hasura | convention |
+|---|---|---|---|---|---|---|
+| `:type_mismatch` | the value is not the type the schema declares, and no conversion applies | `type` | yes | yes | **no** | yes |
+| `:unparseable` | the right kind of thing, but the text doesn't parse as that scalar | `type` | yes | yes | **no** | yes |
+| `:not_a_member` | not one of the values an enum (or an inclusion rule) allows | `members` | yes | yes | yes | yes |
+| `:missing` | a required field or argument wasn't supplied, or was null | — | yes | yes | yes | yes |
+| `:unknown` | a key the input type doesn't define — a typo | `suggestion` | yes | yes | yes | yes |
+| `:out_of_range` | a number, length or date outside the bounds the schema states | `min`, `max` | **no** | **no** | **no** | yes |
+| `:invalid_format` | parses, right type, but fails a stated semantic rule — a regex, an email | `pattern` | **no** | **no** | **no** | yes |
+| `:refused` | rejected, with nothing more than a message — the fallback, never a guess | — | yes | yes | yes | yes |
+
+`field` and `value` ride on every kind. `value` is the offending value passed
+through [`filter_parameters`](logging.md#filtered-variables), so it reads
+`"[FILTERED]"` under a sensitive key and `nil` when the producer never said what
+the value was.
+
+Two rows carry the headline: **`:out_of_range` and `:invalid_format` — the
+everyday "right type, wrong value" — cannot be produced from either side without
+the [server convention](errors.md#what-your-server-can-send).** The client
+doesn't know the schema's bounds, and a graphql-ruby `validates:` failure reaches
+the wire as a bare sentence with no `extensions` at all.
+
+Those three are the servers graph_weaver reads by name. **Apollo** is `:refused`
+and the server's own sentence, nothing finer. **Anything else** says nothing
+graph_weaver will claim: `#input_errors` comes back `[]`, and the rejection stays
+an ordinary error to render as the server wrote it. Which shape each server is
+read off, and why Hasura's blanks are blank, is in
+[errors](errors.md#when-the-server-rejects-the-input).
+
+## Details
+
+One class carries both halves: `GraphWeaver::InputError` is *raised* before the
+request leaves, and it is also the **value** a server's rejection becomes — read
+back by `Response#input_errors`, `QueryError#input_errors` and
+`GraphQLError#input_errors`, all plural, since one variable-coercion error
+routinely carries problems about several fields. What it holds is the table in
+[errors](errors.md#what-an-inputerror-says-without-reading-english); the one
+thing a translator needs from it is that every named segment of `#path` — and so
+`#field` — is the **schema's** spelling, whichever side refused
+([why](errors.md#which-spelling-a-path-is-in)).
+
+**`field:` can't say which row.** A list index lives in `#path` and nowhere else,
+so every element of `lines: [LineInput!]!` translates to the same sentence. Where
+a form lists rows, label it from the path:
+
+```ruby
+# "input.lines.0.qty", where #field alone is "qty" for every line at once
+I18n.t("graph_weaver.input.#{error.kind}", field: error.path.join("."), **error.details)
+```
+
+Arrays stay arrays: `details[:members]` is `["CAT", "DOG"]`, so join it where you
+know the language — `members: e.details[:members].to_sentence`.
+
+`details[:type]` is the **GraphQL** name for the type — `Int`, `Money` — so a
+sentence built from it still says "Int" in the middle of the French. Translate
+the name yourself under a key of your own and pass it *after* the splat, which
+wins: `I18n.t(key, **e.details, type: I18n.t("types.#{e.details[:type]}"))`.
+
+`@oneOf` violations are `:refused`, except exactly one field explicitly null,
+which is `:missing` on that field — a form gets the one slot to highlight. The
+wrong *count* names no single field, so it stays a message.
+
+### What the server has to do
+
+For the two kinds nothing can produce on its own, and for every column the table
+leaves blank, the server states it — under one key, `extensions.input`, with the
+`kind` taken from the table above. The shape, the graphql-ruby recipes for it,
+and what a server that sends none of it gets instead are in
+[errors](errors.md#what-your-server-can-send).
+
+Two rules matter to a translator. **A `kind` outside the table becomes
+`:refused`** rather than being passed through, because a wrong key is worse than
+no key: the app will have translated it into a confident sentence. And **a key
+outside `type`/`members`/`min`/`max`/`pattern`/`suggestion` is dropped** before it
+reaches `details`, so `I18n.t(..., **details)` can never be handed an
+interpolation your locale file has no slot for — nor one I18n reserves, which is
+why it is `:pattern` and not `:format`.
+
+### Transport and server failures
+
+`kind` exists for input errors and nothing else. The failures beside them name no
+field and carry nothing to interpolate, so key those on the **exception class**,
+which is the only closed vocabulary on that side — a `code` is a per-server
+invention, so a translation keyed on one degrades to English against the next
+server:
+
+| what you rescued | what the user is told |
+|---|---|
+| `GraphWeaver::TransportError` | we couldn't reach the service — try again |
+| `GraphWeaver::ServerError` | the service is having trouble — try later (`#throttled?` earns its own sentence) |
+| `GraphWeaver::QueryError` whose `#input_errors` is empty | something went wrong with that request |
+
+One static translated sentence each, and log what the server said rather than
+showing it.
+
+### Where translation stops
+
+graph_weaver's own refusals are for developers and stay English, with no keys:
+`QueryValidationError`, the codegen errors, the schema-drift hint,
+`ConfigurationError`, `Testing::*`, and `InputError#message`. A message the
+*server* wrote arrives in whatever language the server chose, untouched.

data/docs/logging.md

@@ -1,42 +1,43 @@
 # Logging
 
 Silent by default. Point `GraphWeaver.logger` at anything
-stdlib-Logger-compatible and the whole flow narrates itself — in Rails
-the railtie wires `Rails.logger` automatically (set
-`GraphWeaver.logger = nil` in an initializer to opt out):
+stdlib-Logger-compatible and the whole flow narrates itself — in Rails the
+railtie wires `Rails.logger` automatically (set `GraphWeaver.logger = nil` in an
+initializer to opt out):
 
 ```ruby
 GraphWeaver.logger = Logger.new($stdout, level: Logger::INFO)
 ```
 
-What logs at which level — pick the level, get the story:
+Pick the level, get the story:
 
 | Level | What you see |
 |-------|--------------|
-| `debug` | the wire: query + variables per call (long queries truncated), response status/bytes, request timing, connection open/drop, dynamically parsed modules |
-| `info` | schema introspection (with timing) and cache hits/misses, the transport a client built, generated files written and any unregistered scalars, query modules loaded, a retry's wait and attempt number — and in development, what's being watched and what a save regenerated |
-| `warn` | every GraphWeaver error raised — `TransportError`, `ServerError`, `QueryError`, `ValidationError`, `TypeError` — registrations the schema being generated against can't match, a retry skipped because the operation was a mutation, and every fetch the test router answered with fabricated data |
+| `debug` | the wire: query + variables per call (long queries truncated), response status/bytes/content type, request timing, connection open/drop, dynamically parsed modules |
+| `info` | one line per operation in Rails (see [Instrumentation](#instrumentation)), schema introspection (with timing) and cache hits/misses, the transport a client built, generated files written and any unregistered scalars, query modules loaded, a retry's wait and attempt number — and in development, what's being watched and what a save regenerated |
+| `warn` | every GraphWeaver error raised — `TransportError`, `ServerError`, `QueryError`, `QueryValidationError`, `CastError` — registrations the schema being generated against can't match, a retry skipped because the operation was a mutation, and every fetch the test router answered with fabricated data |
 | `error` | development only: a `.graphql` edit that won't compile, with its file and position — the modules already loaded keep serving |
 
-Every line carries `graph_weaver` as the progname, so formatter-based
-filtering works out of the box. Wire lines are tagged
-`[req 3 FilteredPokemon]` — a per-process request id plus the operation
-name — so a request's lines stay paired when threads interleave.
+Every line carries `graph_weaver` as the progname, so formatter-based filtering
+works out of the box. Wire lines are tagged `[req 4123-3 FilteredPokemon]` — pid,
+that process's own request count, operation name — so a request's lines stay
+paired when threads interleave and distinct when a Puma cluster's workers share a
+log.
 
-**PII note**: queries, variables, and response sizes appear at debug
-only — variables can carry user data, so keep production loggers at
-info or above. Auth headers never log at any level.
+**PII note**: queries, variables and response sizes appear at debug only, so keep
+production loggers at info or above. Auth headers never log at any level.
 
 ## Filtered variables
 
 Debug gets switched on during an incident, which is exactly when a
-`login(password:)` mutation's variables must not land in the log. So the
-values of sensitive keys are replaced with `[FILTERED]` before the line is
-written — at any depth, including inside input objects.
+`login(password:)` mutation's variables must not land in the log. So the values of
+sensitive keys are replaced with `[FILTERED]` before the line is written, at any
+depth, including inside input objects.
 
 In Rails you configure nothing: the railtie adopts the app's own
 `config.filter_parameters`, so GraphWeaver scrubs whatever the request logs
-already scrub.
+already scrub — Rails' own default list has `:email` on it, so an ordinary field
+named `email` reads `[FILTERED]` the day you add the gem.
 
 Everywhere else, one list:
 
@@ -45,48 +46,194 @@ GraphWeaver.filter_parameters = [:password, /token/]
 ```
 
 Strings and Symbols match as case-insensitive substrings — `:token` covers
-`apiToken` — and Regexps match themselves. The default is `[:password,
-:token, :secret, :authorization]`, which covers the usual names before
-anyone configures anything; assigning replaces it rather than adding to it,
-and `[]` turns filtering off. Anything answering `#filter(hash)` is used
-as-is, which is how the railtie hands over an
-`ActiveSupport::ParameterFilter`.
-
-The same list scrubs error messages, which reach the log at `warn` rather
-than `debug`: a variable, input field, or entity key whose name is filtered
-is rejected with `[FILTERED]` in place of the value — everything else keeps
-quoting it, since `expected an Int, got "lots"` is the whole diagnosis.
+`apiToken` — and Regexps match themselves. The default is `[:password, :token,
+:secret, :authorization]`; assigning replaces it rather than adding to it, and
+`[]` turns filtering off for variables and messages. A credential in the *url* is
+scrubbed either way. Anything answering `#filter(hash)` is used as-is, which is
+how the railtie hands over an `ActiveSupport::ParameterFilter`.
+
+The same list scrubs error messages, which reach the log at `warn` rather than
+`debug`: a variable, input field or entity key whose name is filtered is rejected
+with `[FILTERED]` in place of the value, at every depth — a filtered key one level
+in reads `got {"token" => "[FILTERED]"}`. Everything else keeps quoting the
+value, since `expected an Int, got "lots"` is the whole diagnosis.
 
 ## Instrumentation
 
-A logger tells a human what happened; an APM needs to time it and count
-it. `GraphWeaver.instrumenter` is one callable wrapping every request —
-over the wire *and* in-process, one seam for both paths. It's a no-op
-until you set one, and `ActiveSupport::Notifications` is a two-line
-adapter:
+A logger tells a human what happened; an APM needs to time it and count it.
+`GraphWeaver.instrumenter` is one callable wrapping every request — over the wire
+*and* in-process. **In Rails you set nothing**: the railtie installs the adapter
+below and attaches `GraphWeaver::LogSubscriber` on top of it. Everywhere else:
 
 ```ruby
 GraphWeaver.instrumenter = lambda do |event, payload, &block|
   ActiveSupport::Notifications.instrument(event, payload, &block)
 end
+```
+
+An instrumenter you set yourself is never replaced — including
+`GraphWeaver.instrumenter = nil`, which opts out. Yours **must** call the block
+and return its value; a failure propagates through it, so the hook sees the
+exception and can record it.
 
+The one event is `GraphWeaver::EXECUTE_EVENT` (`"execute.graph_weaver"`) — one
+request, start to parsed response, whichever client slot served it:
+
+```ruby
 ActiveSupport::Notifications.subscribe(GraphWeaver::EXECUTE_EVENT) do |*, payload|
-  StatsD.timing("graphql.#{payload[:operation] || "anonymous"}", ...)
+  StatsD.timing("graphql.#{payload[:operation] || "anonymous"}", payload[:duration_ms],
+    tags: ["status:#{payload[:status]}", "kind:#{payload[:kind]}", "code:#{payload[:code]}"])
+end
+```
+
+**A subscriber that raises takes the request down with it** — the response was
+computed and is then thrown away. That is `ActiveSupport::Notifications`' own
+semantics, the same on `sql.active_record`, so rescue inside the block. A
+`GraphWeaver::LogSubscriber` subclass already does.
+
+### The payload
+
+| Key | When | |
+|-----|------|--|
+| `:operation` | always | the operation name sent with the request, nil for an anonymous document — what a trace keys on (a generated module always has one) |
+| `:client` | always | the class that ran it: `GraphWeaver::Transport::HTTP`, `GraphWeaver::InProcess`, your own |
+| `:kind` | always | `:query`, `:mutation` or `:subscription` — what the document runs, so a write failure rate is a payload question rather than a guess at the operation's name. The shorthand `{ ... }` document is a `:query`. The same reading decides whether [`Retry`](transports.md#retries) may repeat the request |
+| `:status` | always | `:ok`, `:errors` (a response carrying GraphQL errors), or `:failed` (it raised) |
+| `:duration_ms` | always | start to parsed response, for **this attempt** — under a [`Retry`](transports.md#retries) no event covers the backoff sleep, so a tracer recovers the caller's wall clock from the sibling spans instead: the first attempt's start to the last one's end |
+| `:url` | over the wire | the endpoint; nil in-process |
+| `:http_status` | over the wire | what the server answered with, success or not; nil in-process |
+| `:schema` | in-process | the schema class's name, as a String, so a payload logs as it stands |
+| `:code` | on `:errors` | the machine-readable reason, always a String or `nil` — the first `extensions.code` *any* of the errors carries, not the first error's, since a code that exists beats the absence of one at position 0. Present and `nil` when the errors carry none. Never an HTTP status: that is `:http_status` |
+| `:error` | on `:failed` | the exception's class name |
+| `:retries` | under a `Retry` | how many retries this attempt follows. Each attempt is its own event, so one retried call is three events reading 0, 1, 2 — present at 0 rather than absent, so its absence means nothing was retrying |
+| `:graph` | always | the [graph](getting_started.md#more-than-one-schema) the generated module was declared under, as a Symbol — `nil` for a module that names none, and for a client called directly. Never inferred from the client: a wrong graph on a request is worse than no graph |
+
+Every key is filled in before your callable's block returns, so a subscriber reads
+a complete payload; `ActiveSupport::Notifications` adds `:exception` and
+`:exception_object` of its own when the block raises.
+
+**`:graph` labels one request**, never what a *server* does while answering one:
+an in-process resolver that calls out produces an event of its own. The label is
+fiber-local, so a dispatch that crosses a `Fiber` — graphql-ruby's `Dataloader`
+does — arrives with `:graph` unset. No label rather than a wrong one.
+
+**Never the query text or the variables**: the payload fans out to subscribers
+that know none of the filtering rules, so the rule here isn't "scrub it", it's
+that it was never there. `:url` is the one thing on the payload that *is*
+scrubbed, because a url can itself be a credential — and the default names apply
+to its query parameters even when you have emptied or narrowed
+`filter_parameters`. Your list widens that; it can't narrow it.
+
+### One line per operation
+
+In Rails the railtie also attaches `GraphWeaver::LogSubscriber`, which turns each
+event into one line — the shape ActiveRecord uses for a query:
+
+```
+GraphWeaver PersonQuery (12.3ms) ok
+GraphWeaver PersonQuery (8.1ms) errors [THROTTLED]
+GraphWeaver PersonQuery (31.2ms) failed GraphWeaver::TransportError
+GraphWeaver PersonQuery (5.0ms) ok (retry 2)
+GraphWeaver billing/InvoicesQuery (12.3ms) ok
+```
+
+The operation is prefixed by its graph when the request carried one, so an app
+with several graphs sorts its own log and an app with one never sees the prefix.
+
+**The summary is info, the wire is debug.** This is the only GraphWeaver line at
+info, so a production log gets one per operation and nothing that can carry PII;
+debug adds the query, the variables and the response *beneath* it. It writes
+through `GraphWeaver.logger`.
+
+Outside Rails the same line is an instrumenter of your own, writing
+`payload[:operation]`, `[:duration_ms]` and `[:status]` from an `ensure` — the
+shape the two tracing examples below use.
+
+### OpenTelemetry
+
+```ruby
+tracer = OpenTelemetry.tracer_provider.tracer("graph_weaver")
+
+GraphWeaver.instrumenter = lambda do |_event, payload, &block|
+  tracer.in_span("graphql #{payload[:operation] || "query"}") do |span|
+    block.call
+  ensure
+    span.add_attributes(payload.compact.transform_keys { "graphql.#{_1}" }.transform_values(&:to_s))
+    span.status = OpenTelemetry::Trace::Status.error(payload[:code] || "graphql errors") if payload[:status] == :errors
+  end
+end
+```
+
+`ensure` rather than after the call: the payload is only complete once the block
+has returned, and a failed span needs the attributes most. `in_span` sets the
+span status itself for a *raise* only, which is the last line's reason to exist.
+
+**Span status is not the alerting signal; `payload[:status]` is.** A response
+carrying GraphQL errors is a 200 that returned normally, so nothing raises and a
+span left to itself is `UNSET` — an SLO built on span status alone misses every
+GraphQL-level failure there is. Alert on `:status` and group by `:code`.
+
+**Propagating the trace outward** is a header, and a
+[header value may be a callable](transports.md#headers) resolved per request —
+inside the span, which is what makes it work:
+`headers: { "traceparent" => -> { {}.tap { OpenTelemetry.propagation.inject(_1) }["traceparent"] } }`.
+
+### Datadog
+
+```ruby
+GraphWeaver.instrumenter = lambda do |event, payload, &block|
+  Datadog::Tracing.trace(event, resource: payload[:operation], service: "graphql") do |span|
+    block.call
+  ensure
+    payload.compact.each { |key, value| span.set_tag("graphql.#{key}", value.to_s) }
+    span.set_error([payload[:code], "graphql errors"]) if payload[:status] == :errors
+  end
 end
 ```
 
-The one event is `GraphWeaver::EXECUTE_EVENT`
-(`"graph_weaver.execute"`), a single request from start to parsed
-response. Its payload carries:
-
-| Key | |
-|-----|--|
-| `:url` | the endpoint — nil in-process |
-| `:schema` | the schema class's name, in-process only — a String, so a payload logs as it stands |
-| `:operation` | the operation name sent with the request (a generated module always has one) — what a trace keys on |
-| `:status` | the HTTP status, added once the response lands |
-
-Your callable **must** call the block and return its value. A failure
-propagates through it, so the hook sees the exception and can record it.
-The query text and the variables are deliberately absent: they carry
-PII, and belong at debug on the logger where the level gates them.
+Datadog's Net::HTTP and Faraday contribs already trace the transport layer, so
+with them on you have a span for the POST. This adds the span *above* it, named
+for the operation — the one that means anything, since every GraphQL call is a
+POST to the same url.
+
+## Details
+
+### What carries text we didn't author
+
+A log line, an exception and an APM tag all outlive the request, and each can
+carry text somebody else wrote. Every such channel has a policy, and there are no
+others:
+
+| Channel | Policy |
+|---------|--------|
+| the variables line | scrubbed through `filter_parameters` at every depth, and written at **debug** only |
+| the query text | debug only, truncated |
+| `InputError#message`, `#value`, `#to_h` | `[FILTERED]` under a filtered key, at every depth; capped at 1 KB |
+| `ServerError#message` | the status, what *we* judged wrong, the hint, the safe url — **never the body** |
+| `ServerError#body` | the bytes verbatim. This is the channel that carries them, which is why no other has to |
+| `ServerError#to_h` | status, `retry_after`, url — the body and the headers stay off it (read `#headers`) |
+| a redirect's `Location` | a url the server chose, folded the way we fold our own |
+| `TransportError#message` | the adapter's own sentence, capped, plus the safe url |
+| `GraphQLError#message` | the server's own words, **passed through untouched** — a server that quotes a rejected password has to be fixed at the server |
+| `extensions.code` → the info line, the APM `:code` | control characters stripped, capped — a tag can't forge a line |
+| the endpoint, everywhere it is said | userinfo and credential query parameters folded to `[FILTERED]` |
+| `#inspect` on any public object | its class and its safe url; never a header, a context or a body |
+
+The rule behind the `ServerError` rows: every raised error writes its message to
+the log at `warn`, and the commonest non-2xx body in the world is a framework
+error page echoing the request, `Authorization` header included.
+
+### What is process-global, and who owns it
+
+Three things outlive a single request and meet more than one writer in a shipped
+configuration. Each has one owner, so none needs a convention on your side:
+
+| Resource | Several writers arrive from | Who keeps them apart |
+|----------|-----------------------------|----------------------|
+| the `[req …]` counter | a Puma cluster: forked workers inherit it | the tag carries the pid, and the count restarts in a new process |
+| the schema cache file | two clients both saying `cache: true` | a dump records its source url; a client that didn't write it caches under a name of its own ([getting started](getting_started.md)) |
+| a cassette | `parallel_tests`, one cassette, several processes | a recorder re-reads and rewrites under a `flock` ([testing](testing.md)) |
+
+Two things are *not* process-global and shouldn't be made so: a client's GraphQL
+context (per client, guarded by the client — see `GraphWeaver::ContextSeam`), and
+a connection pool (per process, rebuilt after a fork).

data/docs/real_world.md

@@ -1,10 +1,9 @@
 # Against a real API
 
-The exploratory tour: point a client at a live endpoint and go, no build
-step — ideal for consoles, spikes, and getting a feel for an API. What
-ships is the checked-in codegen path in the [getting started](getting_started.md);
-this page is how you get there (the `parse` below becomes a `.graphql`
-file plus `rake graph_weaver:generate`, everything else stays).
+Point a client at a live endpoint and go, no build step — the exploratory tour,
+for consoles and spikes. What ships is the checked-in codegen path in
+[getting started](getting_started.md); the `parse` below becomes a `.graphql`
+file plus `rake graph_weaver:generate`, and everything else stays.
 
 Everything hangs off a client — transport and schema for one server. GitHub's
 API, end to end:
@@ -12,17 +11,16 @@ API, end to end:
 ```ruby
 require "graph_weaver"
 
-# transport + auth in one object (docs/transports.md for retries and
-# advanced setup). cache: true dumps the schema at GraphWeaver.schema_path
-# on first introspection — the same file rake graph_weaver:generate reads
-# (docs/getting_started.md for the formats), with the source url recorded
-# in a header, so a stale dump says where it came from.
+# transport + auth in one object (docs/transports.md for retries and TLS).
+# cache: true writes the schema to GraphWeaver.schema_path on first
+# introspection — the same dump rake graph_weaver:generate reads. It records
+# its source url, so a second client at a second origin caches under a name of
+# its own rather than overwriting this one.
 github = GraphWeaver.new("https://api.github.com/graphql", auth: `gh auth token`.strip, cache: true)
 
-# GitHub's DateTime needs no registration — it is one of the names the
-# registry knows (docs/scalars.md). A scalar of your own would go here;
-# registrations are global and codegen-time, so one line types your
-# console and your checked-in code identically.
+# GitHub's DateTime needs no registration (docs/scalars.md). A scalar of your
+# own goes here: registrations are global and codegen-time, so one line types
+# your console and your checked-in code identically.
 
 RepoQuery = github.parse(<<~GRAPHQL)
   query($owner: String!, $name: String!) {
@@ -36,24 +34,41 @@ GRAPHQL
 
 repo = RepoQuery.execute!(owner: "dpep", name: "graph_weaver").repository
 repo&.name_with_owner   # => "dpep/graph_weaver"
-repo&.created_at        # => 2026-07-07 ... (a real Time)
+repo&.created_at        # => a real Time
 repo&.stargazer_count   # => Integer
 ```
 
-Clients are independent — build one per server, each with its own transport
-and schema. When you're ready to check the generated code in, the same client
-is the schema `generate!` wants:
+Build one client per server; they're independent. That same client is what
+`GraphWeaver.generate!(schema: github)` takes when you check the generated code
+in, so no dump on disk is needed — and keeping a second server's modules beside
+your own is a [graph](getting_started.md#more-than-one-schema).
+
+## Browsing the schema
+
+`client.schema` is an ordinary graphql-ruby `Schema` class, so "what can I even
+ask for" is answered in the console with nothing else installed:
 
 ```ruby
-GraphWeaver.generate!(schema: github)   # no dump on disk needed
+schema = github.schema
+
+schema.query.fields.keys              # => ["repository", "search", ...]
+field = schema.query.fields["repository"]
+field.arguments.keys                  # => ["owner", "name", ...]
+field.type.to_type_signature          # => "Repository"
+
+repo = field.type.unwrap              # past the ! and [] wrappers
+repo.graphql_name                     # => "Repository"
+repo.fields.keys.sort                 # => ["createdAt", "description", ...]
 ```
 
-The introspection step (seconds on a big API) happens lazily on first
-`schema`/`parse` and caches per `cache:`/`ttl:`; for finer control the
-pieces are all public
-(`GraphWeaver::SchemaLoader.introspect(transport, cache:, ttl:)`, or cache
-`introspect(transport).to_json` in Rails.cache and `SchemaLoader.load` it).
+Reach for `graphql_name`, not `name`: a schema built from introspection or SDL
+has no Ruby class behind its types, so `.name` is `nil` there, and where the
+schema *is* a class you wrote `.name` gives the Ruby constant.
+
+Introspection (seconds on a big API) happens lazily on first `schema`/`parse`
+and caches per `cache:`/`ttl:`; for finer control the pieces are public —
+`GraphWeaver::SchemaLoader.introspect(transport, cache:, ttl:)`, or cache
+`introspect(transport).to_json` yourself and `SchemaLoader.load` it.
 
-The same flow runs as one-off integration specs against the live GitHub
-and Countries APIs — `make integration` (network; GitHub auth via
-`gh auth token` or `GITHUB_TOKEN`).
+`make integration` runs this flow against the live GitHub and Countries APIs
+(network; GitHub auth via `gh auth token` or `GITHUB_TOKEN`).