1 files changed, 142 insertions, 0 deletions
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..51436ad
--- /dev/null
+++ b/README.md
@@ -0,0 +1,142 @@
+# @eol/gq
+
+A batteries-included GraphQL toolkit for Deno, wrapping `graphql-js` and `@graphql-tools/schema` with the bits most APIs end up reaching for anyway: a Fetch-compatible HTTP handler, a cached `gql` tag, a `.graphql` file loader, and a cleaned-up GraphQL Playground.
+
+## Install
+
+Published on JSR as [`@eol/gq`](https://jsr.io/@eol/gq).
+
+```bash
+deno add jsr:@eol/gq
+```
+
+Or import directly:
+
+```ts
+import { executeSchema, gql, GraphQLHTTP } from "jsr:@eol/gq";
+```
+
+## Quick start
+
+```ts
+import { executeSchema, gql, GraphQLHTTP } from "@eol/gq";
+
+const schema = executeSchema({
+  resolvers: {
+    Query: {
+      hello: (_, { name }) => `hello, ${name ?? "world"}`
+    }
+  },
+  typeDefs: gql`
+    type Query {
+      hello(name: String): String
+    }
+  `
+});
+
+Deno.serve(
+  { port: 8000 },
+  GraphQLHTTP({ graphiql: true, schema })
+);
+```
+
+Visit `http://localhost:8000` in a browser for the Playground, or `POST` a query to the same URL.
+
+## Loading schemas from `.graphql` files
+
+Use `importQL` to read an entry file and resolve its imports into a single SDL string.
+
+### Explicit imports
+
+```graphql
+# schema/schema.graphql
+# import "./post.graphql"
+# import "./user.graphql"
+
+type Query {
+  me: User
+  posts: [Post!]!
+}
+```
+
+```ts
+import { executeSchema, gql, importQL } from "@eol/gq";
+
+const typeDefs = gql(await importQL("schema/schema.graphql"));
+const schema = executeSchema({ resolvers, typeDefs });
+```
+
+### Dynamic imports
+
+Drop `# DYNAMIC_IMPORTS` in your entry file and every `.graphql` file found one level below `<cwd>/schema/` gets inlined at that marker:
+
+```
+schema/
+  schema.graphql   # contains: # DYNAMIC_IMPORTS
+  post/
+    post.graphql
+  user/
+    user.graphql
+```
+
+## API
+
+All symbols are re-exported from the package root (`@eol/gq`).
+
+### `GraphQLHTTP(options)`
+
+Returns a `(request) => Promise<Response>` handler. Pluggable into `Deno.serve`, [oak](https://jsr.io/@oak/oak), [hono](https://jsr.io/@hono/hono), or anything else Fetch-shaped.
+
+Options:
+
+| Option              | Type                                  | Description                                          |
+| ------------------- | ------------------------------------- | ---------------------------------------------------- |
+| `schema`            | `GraphQLSchema`                       | Required. Executable schema.                         |
+| `context`           | `(req) => Ctx \| Promise<Ctx>`        | Builds the resolver context per request.             |
+| `graphiql`          | `boolean`                             | Serve the Playground on `GET` + `Accept: text/html`. |
+| `headers`           | `HeadersInit`                         | Extra headers merged into every response.            |
+| `playgroundOptions` | `Omit<RenderPageOptions, "endpoint">` | Passthrough options for the Playground renderer.     |
+
+### `executeSchema(config)`
+
+Re-export of `@graphql-tools/schema`’s `makeExecutableSchema`, renamed for brevity.
+
+### `gql` *(tagged template)*
+
+Parses a GraphQL string into a `DocumentNode`. Results are cached by normalized source, and embedded `DocumentNode` interpolations are inlined from their original source.
+
+Companion knobs:
+
+- `disableExperimentalFragmentVariables()`
+- `disableFragmentWarnings()`
+- `enableExperimentalFragmentVariables()`
+- `resetCaches()`
+
+### `importQL(path)`
+
+Reads a `.graphql` file and resolves its imports. See [Loading schemas from `.graphql` files](#loading-schemas-from-graphql-files).
+
+### `runHttpQuery(params, options, request)`
+
+Low-level executor that `GraphQLHTTP` delegates to. Use it if you’re rolling your own transport but still want the context wiring.
+
+### Types
+
+`GQLOptions`, `GQLRequest`, `GraphQLParams`, `GraphQLHandler`, plus the Playground types (`RenderPageOptions`, `MiddlewareOptions`, `ISettings`, `EditorColours`, `Tab`, `Theme`, `CursorShape`, `IntrospectionResult`).
+
+## Features
+
+- Import `*.graphql` files — explicit and dynamic — via `importQL`.
+- GraphiQL/Playground code cleaned up; SVGs redrawn so they actually make sense.
+- Ships typed; passes `deno check entry.ts` with no fuss.
+- Zero build step — it’s Deno, you just import it.
+
+## TODO
+
+- Add a runnable example.
+- Replace React Playground with Svelte/SvelteKit.
+- Take over the world (real world, metaverse, or [yggdrasil](https://yggdrasil-network.github.io), whichever comes first).
+
+## License
+
+MIT.