diff --git a/gaps/GAP-10/DRAFT.md b/gaps/GAP-10/DRAFT.md
new file mode 100644
index 0000000..76ae88f
--- /dev/null
+++ b/gaps/GAP-10/DRAFT.md
@@ -0,0 +1,654 @@
+# @mock Directive Specification
+
+This document specifies the `@mock` directive, which allows GraphQL clients to
+return mocked data for individual fields, selection sets, or entire operations.
+
+Mock data may be defined for fields and types that do not yet exist in the
+schema. This enables backend and client developers to work in parallel — client
+developers can start building applications using expected new fields without
+waiting for the server to implement the new schema.
+
+```graphql example
+query GetBusinessInfo {
+  business(id: "123") {
+    name
+    # this field doesn't exist yet on the server!
+    website @mock(value: "https://www.example.com")
+  }
+}
+```
+
+`@mock` can also be used to mock subtrees and whole operations:
+
+```graphql example
+# mock just the 'hours' field
+query GetBusinessHours {
+  business(id: "123") {
+    name
+    hours @mock(variant: "morning-only") {
+      open
+      close
+    }
+  }
+}
+
+# mock the entire operation
+query GetBusinessRating @mock(variant: "five-star-bakery") {
+  business(id: "123") {
+    name
+    rating
+  }
+}
+```
+
+Mock data is stored in JSON files and read statically when requests are
+executed:
+
+```json example
+{
+  "morning-only": {
+    "data": {
+      "open": "8:00am",
+      "close": "12:00pm"
+    },
+    "__path__": "business.hours"
+  }
+}
+```
+
+The client transforms the document to remove mocked {Selection}s before
+executing or sending the request to the server. Upon receiving a response from
+the server, mock values are merged into the response object before yielding to
+the application.
+
+Use of Large Language Models (LLMs) is suggested as a means of creating and
+maintaining mock data.
+
+# Directive
+
+```graphql
+directive @mock(
+  variant: String
+  value: String
+) on QUERY | MUTATION | SUBSCRIPTION | FIELD
+```
+
+## Arguments
+
+`@mock` accepts two mutually exclusive arguments: {"variant"} and {"value"}.
+Exactly one of these arguments must be provided. Providing both {"variant"} and
+{"value"} in the same `@mock` directive is a validation error.
+
+### variant
+
+{"variant"} maps to a _mock variant id_. This uniquely identifies a _mock value_
+(stored in the _mock file_) to return for the field or operation where `@mock`
+is applied.
+
+A *mock variant id* must not start with two underscores (`__`). This is
+reserved and must not be used as a {"variant"} argument value.
+
+The mechanism for clients to read the *mock file* is implementation-defined.
+See: [Appendix: Reading Mock Files](#sec-Reading-Mock-Files).
+
+### value
+
+{"value"} provides an inline *mock value* as the value of the argument.
+
+When {"value"} is provided, the client uses the supplied string as the mock
+response for the annotated field without consulting a *mock file*.
+
+{"value"} may only be applied to fields that resolve to
+_[leaf types](https://spec.graphql.org/September2025/#sec-Leaf-Field-Selections)_
+(scalars and enums). It must not be applied to fields that return object types
+or to operation roots.
+
+Because {"value"} is always a string, the client must coerce the string to the
+appropriate JSON type:
+
+CoerceInlineValue(value) :
+  1. If {value} is {"null"}, return `null`.
+  1. If {value} is {"true"}, return the boolean `true`.
+  1. If {value} is {"false"}, return the boolean `false`.
+  1. If {value} can be parsed as a base-10 number, return {value} as number.
+  1. Return {value} as a string.
+
+Note: This specification requires JSON as the serialization format for GraphQL
+responses.
+
+## Transforming Operations
+
+Operations must be transformed to remove any selections which have `@mock`
+applied before sending the request to the server. The client must insert a _mock
+value_ in each corresponding position before yielding a response to the
+application.
+
+If every selection in a {SelectionSet} uses `@mock`, the parent that contains
+that {SelectionSet} must be removed:
+
+- If the parent is a field or inline fragment, remove it from the operation.
+- If the parent is a fragment definition, remove the definition and all of its
+  corresponding fragment spreads.
+
+After removing mocked selections, if an operation
+[variable](https://spec.graphql.org/September2025/#sec-Language.Variables) is no
+longer referenced by any remaining selection, the variable definition must also
+be removed from the operation. An unreferenced variable would produce an invalid
+document per the
+_[All Variables Used](https://spec.graphql.org/September2025/#sec-All-Variables-Used)_
+rule.
+
+When `@mock` is applied to a field, the _mock value_ must always be included in
+the response, regardless of other directives present on the same field. In
+particular, `@mock` takes precedence over `@skip` and `@include` — the mock data
+is always returned, irrespective of whether the field would otherwise be skipped
+or included based on those directives' conditions.
+
+If `@mock` is applied to an operation definition (e.g. {"query"}), the entire
+response must be resolved from a _mock file_. No request should be sent to the
+server.
+
+**Example**
+
+The resulting operation that may be sent to a server as a result of applying all
+transformation logic specified above can be seen in this example:
+
+```graphql example
+fragment FooFields on Foo {
+  foo @mock(value: "foo!")
+  bar
+}
+
+fragment MoreFooFields on Foo {
+  baz @mock(value: "baz!")
+}
+
+query GetFoo($id: ID!, $planet: String!) {
+  foo(id: $id) {
+    id
+    ...FooFields
+    ...MoreFooFields
+    ... on Foo { baz @mock(value: "baz!") }
+    sayHello(planet: $planet) @mock(value: "hello world")
+  }
+}
+```
+
+Will be transformed into the following:
+
+```graphql example
+fragment FooFields on Foo {
+  bar
+}
+
+query GetFoo($id: ID!) {
+  foo(id: $id) {
+    id
+    ...FooFields
+  }
+}
+```
+
+**Formal Specification**
+
+TransformOperation(document, selectionSet) :
+  1. If {selectionSet} has a `@mock` directive, return {null}.
+  1. For each {selection} in {selectionSet}:
+      * If {selection} has a `@mock` directive, remove {selection} from
+        {selectionSet}.
+      * Otherwise, if {selection} has a {SelectionSet}:
+        * Let {childSelectionSet} be the {SelectionSet} of {selection}.
+        * Let {document} be {TransformOperation(document, childSelectionSet)}.
+        * If {childSelectionSet} is now empty, remove {selection} from
+          {selectionSet}.
+  1. For each fragment definition in {document}:
+      * Let {fragmentSelectionSet} be the {SelectionSet} of the fragment.
+      * Let {document} be {TransformOperation(document, fragmentSelectionSet)}.
+      * If the fragment's {SelectionSet} is now empty, remove the definition
+        and all corresponding fragment spreads from {document}.
+  1. For each variable definition in {document}:
+      * If the variable is no longer referenced by any remaining selection,
+        remove it.
+  1. Return {document}.
+
+**Lists**
+
+When `@mock` is applied to a selection which is a child of a list type, the
+client inserts the same _mock value_ in each corresponding array element in
+the repsonse.
+
+For example, this query inserts the same {"blurHash"} value for each item in
+{"menuItems"}:
+
+```graphql example
+query GetMenuItemPhotos {
+  business(id: "123") {
+    menuItems {
+      name
+      blurHash @mock(value: "L15hfK~ot5NL$_?GRjIV?vW?M{RP")
+    }
+  }
+}
+```
+
+# Mock Files
+
+:: A *mock file* is a `.json` file that maps each *mock variant id* to a
+*mock variant*.
+
+Each operation or fragment that contains one or more `@mock` directives using
+the {"variant"} argument must have an associated *mock file*. Operations or
+fragments where all `@mock` directives use only the {"value"} argument do not
+require a *mock file*.
+
+Note: Mock files are intended to be long-lived and may be checked into version
+control. This is useful for client developers working on a project over an
+extended period of time, and where the client code depends on GraphQL schema
+that does not yet exist.
+
+## Mock File Location
+
+The *mock file* must be named `{Name}.json`, where `{Name}` is the name of the
+operation or fragment within which the mock values may be used.
+
+To avoid mock file naming collisions, this specification requires that all
+operation and fragment names within a project are unique.
+
+The mock file must be stored in a directory named {"__graphql_mocks__"} adjacent
+to the source file containing the operation or fragment.
+
+**Example**
+
+For an operation named `GetBusinessInfo` defined in `BusinessDetails.graphql`:
+
+```
+.
+├── __graphql_mocks__
+│   └── GetBusinessInfo.json
+└── BusinessDetails.graphql
+```
+
+## Mock File Structure
+
+The mock file contains a JSON object which maps *mock variant id* keys to a
+*mock variant*.
+
+:: A *mock variant id* is any key in the object that does not start with two
+underscores (`__`).
+
+:: A *mock variant* is the object associated with each *mock variant id*.
+
+### Mock Variant Object
+
+A *mock variant* object may contain **only** the following keys:
+
+- {"data"} (required)
+- {"errors"}
+- {"extensions"}
+- {"__path__"} (required)
+- {"__description__"}
+- {"__metadata__"}
+
+#### data
+
+:: {"data"} stores the *mock value*. It may be a scalar, object, array, or
+`null`, depending on what in the operation is being mocked.
+
+The client merges {"data"} directly into the {"data"} field of the operation's
+response — it must not be nested inside an additional {"data"} entry in the
+_mock variant_:
+
+```json counter-example
+{
+  "mock-id": {
+    "data": {
+      "data": {
+        "business": {
+          "name": "The Great British Bakery",
+          "rating": 5.0
+        }
+      }
+    },
+    "__path__": "Query"
+  }
+}
+```
+
+When applying `@mock` to a field that returns a list type, {"data"} contains the
+list value directly:
+
+```json example
+{
+  "menu-items": {
+    "data": [
+      { "name": "Pancakes", "price": "$8.00" },
+      { "name": "Waffles", "price": "$9.00" }
+    ],
+    "__path__": "business.menuItems"
+  }
+}
+```
+
+#### errors
+
+{"errors"} may contain an array of error objects conforming to the
+[GraphQL error format](https://spec.graphql.org/September2025/#sec-Errors).
+This is valid for both operation-level and field-level `@mock` directives.
+
+The client must merge {"errors"} into the GraphQL server's response if present.
+
+#### extensions
+
+{"extensions"} may be a key-value mapping of arbitrary data, conforming to the
+[Extensions](https://spec.graphql.org/September2025/#sec-Extensions) section of
+the GraphQL specification.
+
+The client must merge {"extensions"} into the GraphQL server's response if
+present.
+
+#### __description__
+
+{"__description__"} may contain a string which describes the *mock value* in
+natural language. This value should be used when regenerating the *mock value*.
+
+```json example
+{
+  "5-star-business": {
+    "data": {
+      "business": {
+        "name": "The Great British Bakery",
+        "rating": 5.0
+      }
+    },
+    "__path__": "Query",
+    "__description__": "A delicious bakery with a rating of 5.0"
+  }
+}
+```
+
+#### __path__
+
+{"__path__"} is the *field path* within the operation or fragment where `@mock`
+is or may be applied for a given *mock variant id*.
+
+:: A *field path* is a dot-separated string of field names (or aliases, where
+present) representing the location of the field relative to the root of the
+operation or fragment. 
+
+For `@mock` on an operation root, {"__path__"} is the root operation type name
+(e.g. {"Query"}, {"Mutation"}, or {"Subscription"}).
+
+**Example**
+
+For the following fragment:
+
+```graphql example
+fragment FooFields on Foo {
+  # field path is "bar"
+  bar @mock(variant: "basic-bar")
+
+  # field path is "aliasedBar"
+  aliasedBar: bar @mock(variant: "aliased-bar")
+
+  baz {
+    # field path is "baz.qux"
+    qux @mock(variant: "basic-qux")
+  }
+
+  # field path is "greeting"
+  greeting @mock(variant: "basic-greeting") {
+    salutation
+    planet
+  }
+}
+```
+
+This would be a (minimally) valid corresponding *mock file*:
+
+```json example
+{
+  "basic-bar": {
+    "data": "...",
+    "__path__": "bar"
+  },
+  "aliased-bar": {
+    "data": "...",
+    "__path__": "aliasedBar"
+  },
+  "basic-qux": {
+    "data": "...",
+    "__path__": "baz.qux"
+  },
+  "basic-greeting": {
+    "data": {
+      "salutation": "...",
+      "planet": "..."
+    },
+    "__path__": "greeting"
+  }
+}
+```
+
+#### __metadata__
+
+{"__metadata__"} may be a key-value mapping for additional user or application
+defined metadata.
+
+# Validation
+
+As development progresses, the shape of the operation or schema may change.
+Since mock files may be checked into version control and persist across schema
+changes, an existing *mock value* in a *mock file* or inline {"value"} argument
+may become invalid over time.
+
+Conforming clients must verify that mock data is valid for each operation.
+
+## Mock File Validation
+
+If a *mock variant id* referenced by a {"variant"} argument does not exist in
+the *mock file*, this is a validation error.
+
+Each _mock variant id_ within a _mock file_ must be unique; duplicate keys
+trigger a validation error.
+
+The {"__path__"} of each *mock variant* must correspond to a valid *field path*
+within the operation or fragment associated with the *mock file*.
+
+GraphQL clients must raise an error for an invalid *mock value* defined inside
+a *mock file*.
+
+A *mock value* is valid when its shape is compatible with the operation's
+selections at the *field path* where `@mock` is applied. For each selected
+field, the *mock value* must satisfy {CompleteValue()} for the field's
+schema type. Fields present in the operation but not defined in the
+schema are skipped during validation.
+
+Note: It is also possible to detect if a JSON payload is valid for a given
+operation by constructing an in-memory GraphQL server that has no resolvers and
+uses the JSON payload as its {rootValue} — then ensuring no errors are
+thrown for execution of the operation against the test server. The schema
+must be modified to include any new types and fields referenced in the
+*mock value*.
+
+## Inline Mock Value Validation
+
+The {"value"} argument may only be used on leaf fields (scalars and enums). When
+the field exists in the schema, the coerced value must match the field's return
+type.
+
+**Formal Specification**
+
+ValidateInlineValueArgument(field, schema) :
+  1. If the `@mock` directive on {field} uses the {"value"} argument:
+      * {field} must not have a {selectionSet}.
+      * The {"variant"} argument must not be present.
+      * Let {value} be the string provided to the {"value"} argument.
+      * If {field} exists in {schema}:
+        * Let {coerced} be the result of {CoerceInlineValue(value)}.
+        * {coerced} must be the return type of {field}.
+
+## No Nested @mock Validation
+
+`@mock` must not be used on a field that is a child of another field which also
+uses `@mock`:
+
+```graphql counter-example
+query Foo {
+  bar @mock(variant: "bar-fields") {
+    # ❌ Validation error: @mock on baz is nested inside @mock on bar
+    baz @mock(value: "hi from baz")
+  }
+}
+```
+
+This rule extends across fragment boundaries. {FragmentSpread} nodes must be
+recursively expanded:
+
+```graphql counter-example
+fragment FooFields on Foo {
+  # ❌ Validation error: @mock on bar would be nested inside MockedFoo
+  bar @mock(value: "baz")
+}
+
+query UnmockedFoo {
+  foo {
+    ...FooFields
+  }
+}
+
+query MockedFoo {
+  foo @mock(variant: "foo-fields") {
+    ...FooFields
+  }
+}
+```
+
+**Formal Specification**
+
+ValidateNoNestedMocks(selectionSet, isMockedByParent) :
+  1. For each {selection} in {selectionSet}, expanding any fragment spreads:
+    * Let {fieldUsesMock} be {true} if {selection} has a `@mock` directive,
+      otherwise {false}.
+    * If {isMockedByParent} is {true}, {fieldUsesMock} must be {false}.
+    * Let {isChildrenMocked} be {true} if both {isMockedByParent} and
+      {fieldUsesMock} is {true}, otherwise {false}.
+    * If {selection} has a {selectionSet}:
+      * Let {nextSelectionSet} be that {selectionSet}.
+      * Call {ValidateNoNestedMocks(nextSelectionSet, isChildrenMocked)}.
+
+## No Empty Operation Root Validation
+
+An operation's root {SelectionSet} must contain at least one selection
+that does not use `@mock`. If every selection in the operation's root
+{SelectionSet} is mocked, the transformed operation would contain an
+empty {SelectionSet}, which is not valid GraphQL.
+
+```graphql counter-example
+# ❌ Validation error: all top-level fields are mocked
+query GetBusiness {
+  business(id: "123") @mock(variant: "bakery") {
+    name
+    rating
+  }
+}
+```
+
+**Formal Specification**
+
+ValidateNonEmptyRootSelectionSet(operationDefinition) :
+  1. If {operationDefinition} does not have the `@mock` directive applied:
+      * Let {rootSelectionSet} be the root selection set in
+        {operationDefinition},
+        expanding any fragment spreads.
+      * At least one selection in {rootSelectionSet} must not have a `@mock`
+        directive.
+
+# Mock File Generation
+
+The mechanism for generating and maintaining mock files is
+implementation-defined.
+
+However, this specification is designed to work well with LLM-based coding
+agents. Developers using agents can request new mock variants conversationally.
+
+It is recommended that implementers provide a workflow for developers to
+generate contextually appropriate mock data based on field names, types,
+and surrounding context.
+
+For example, a developer may add a mock with the following prompt:
+
+```example
+"add a mock for GetBusinessInfo where the rating field returns an error"
+```
+
+**Non-Normative: Suggested Agent Skill**
+
+Implementers of this specification may provide an
+[Agent Skill](https://agentskills.io/home) conforming to the Agent Skills
+Specification. This allows coding agents to discover and use mock management
+capabilities.
+
+The following is a suggested `SKILL.md`. Implementers are welcome to replace or
+adapt this prompt to suit their implementation:
+
+[SKILL.md](./SKILL.md)
+
+# Appendix
+
+_This section is non-normative._
+
+## Dynamic Mock Variant IDs
+
+The {"variant"} argument could be passed in from operation
+_[variables](https://spec.graphql.org/September2025/#sec-Language.Variables)_.
+
+A use case would be to build an interface to let viewers control which
+*mock value* is used. For example, the following GET parameters:
+
+```example
+GET /my_page?gql_mock_variants=barMock=some-variant-id;bazMock=some-other-variant-id
+```
+
+This could be mapped to operation variables for the following operation:
+
+```graphql example
+query Foo($barMock: String, $bazMock: String) {
+  bar @mock(variant: $barMock)
+  baz @mock(variant: $bazMock)
+}
+```
+
+GraphQL servers resolve variable references in arguments during
+execution via {CoerceArgumentValues()}, but this does not happen on
+the client. Clients that support variable references in `@mock`
+arguments must implement their own coercion of directive argument
+variables.
+
+## Reading Mock Files
+
+GraphQL clients that implement this specification must have access to the data
+contained in mock files when requests are executed. Since web browsers and
+mobile applications cannot read remote file systems, a mechanism is required
+to make the data contained in mock files available to the client.
+
+This mechanism is implementation-defined.
+
+## Schema-Aware Clients
+
+Schema-aware clients face additional complexity: operations using the `@mock`
+directive may reference types and fields not yet present in the server schema.
+Such clients must patch their local schema to include these definitions, or
+disable validation for mocked operations. The mechanism for schema patching is
+outside the scope of this specification, however contributions addressing this
+are welcome for inclusion in a future version of this document.
+
+## Trusted Documents
+
+Clients that use
+[trusted documents](https://graphql.org/learn/security/#trusted-documents)
+register a hash of each operation at build time and send only that hash at
+runtime.
+
+The document that is hashed must be the result of {TransformOperation}. The same
+transformation must be applied at both build time (when computing the hash) and
+at runtime (when preparing the request).
diff --git a/gaps/GAP-10/README.md b/gaps/GAP-10/README.md
new file mode 100644
index 0000000..bfc0023
--- /dev/null
+++ b/gaps/GAP-10/README.md
@@ -0,0 +1,321 @@
+# GAP-10: @mock Directive Specification
+
+## Overview
+
+This proposal defines the `@mock` directive, enabling GraphQL clients to return
+mocked data for fields or entire operations. Mock data is stored statically in
+JSON files alongside the operations that use them.
+
+## Motivation
+
+Client and backend developers often work in parallel, but clients cannot build
+against schema that isn't yet implemented. The `@mock` directive lets client
+developers define and use mock responses for fields and types that may not yet
+be present in the server schema, unblocking frontend development.
+
+## FAQs
+
+### Conditional response based on list position
+
+This specification does not support conditional use of mock values in individual array
+positions. You may, however, hoist usage of `@mock` to the parent node that returns
+a list and return an array containing different values.
+
+**Example**
+
+Consider the following query:
+
+```graphql
+query PetStorePets {
+  dogsForSale {
+    name @mock(value: "fido")
+  }
+}
+```
+
+This might produce the following response:
+
+```json
+{
+  "data": {
+    "dogsForSale": [
+      { "name": "fido" },
+      { "name": "fido" },
+      { "name": "fido" }
+    ]
+  }
+}
+```
+
+For the purposes of a mock user interface, this might be ok! If you wanted to
+change the value for each item in the list, you would need to mock at a higher
+level:
+
+```graphql
+query PetStorePets {
+  dogsForSale @mock(variant: "3-dogs-for-sale") {
+    name
+  }
+}
+```
+
+#### Future Proposal
+
+We may in future extend this specification to allow for a random pick of
+multiple mock values:
+
+```graphql
+query PetStorePets {
+  dogsForSale {
+    name @mock(value: "john") @mock(value: "ringo") @mock(value: "paul")
+  }
+}
+```
+
+This may produce the following response:
+
+```json
+{
+  "data": {
+    "dogsForSale": [
+      { "name": "paul" },
+      { "name": "ringo" },
+      { "name": "paul" }
+    ]
+  }
+}
+```
+
+#### Why don't we allow specifying an array position?
+
+<details>
+
+Consider the following query:
+
+```graphql
+query GetUserFavorites {
+  businessesNearMe {
+    menuItems {
+      name
+      price
+    }
+  }
+}
+```
+
+Consider that we wish to mock a new field that does not yet exist on the server;
+`blurHash`:
+
+```graphql
+query GetUserFavorites {
+  businessesNearMe {
+    menuItems {
+      name
+      price
+      photo {
+        url
+        blurHash @mock(value: "LEHV6nWB2yk8pyo0adR*.7kCMdnj")
+      }
+    }
+  }
+}
+```
+
+Currently, all list items in the user interface will use the same string for
+`blurHash` - we have no way to use different values for different positions in
+the list.
+
+A tempting option might be to add a "list position argument" that the client
+can interpret to merge in the mock value in the right position:
+
+```graphql
+query GetUserFavorites {
+  businessesNearMe {
+    menuItems {
+      name
+      price
+      photo {
+        url
+        blurHash
+          @mock(value: "LEHV6nWB2yk8pyo0adR*.7kCMdnj", nth_child: 0)
+          @mock(value: "L6PZfSi_.AyE_3t7t7R**0o#DgR4", nth_child: 1)
+      }
+    }
+  }
+}
+```
+
+_(Fans of CSS will find
+[`nth_child`](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Selectors/:nth-child)
+familiar.)_
+
+However, there are issues with this API:
+
+##### 1. Parent Ambiguity
+
+Which list parent does `nth-child` apply to? There are two list parents of
+`Photo.blurHash`: (1) `Query.businessesNearMe` and (2) `Business.menuItems`.
+
+We would need an even more complicated API to resolve this ambiguity.
+
+##### 2. Order Instability
+
+Results from the server may not be stable over long periods of time.
+
+Consider this example that searches book stores for available books:
+
+```graphql
+query BooksInStock {
+  findBookInStock(name: "Fly Fishing", author: "JR Hartley") {
+    inStock
+    storeDetails { name address } @mock(..., nth_child: 0)
+  }
+}
+```
+
+The data the server returns may change over time, either due to:
+
+1. Organic results change
+2. The server changes behavior (e.g. a default `orderBy` parameter changes from
+   `ASC to `DESC` -- this should not happen by convention, but we cannot rely on
+   this.)
+
+This means that the result object that the mocked field is merged into may
+change over time - resulting in a different UI state than was intended,
+potentially leading to nonsensical or broken UI states.
+
+##### 3. Abstract types 
+
+```graphql
+query BooksInStock {
+  findBookInStock(name: "Fly Fishing", author: "JR Hartley") {
+    inStock
+    ... on PhysicalStore {
+      storeDetails { name address } @mock(..., nth_child: 3)
+    }
+    ... on Website {
+      websiteDetails { name url } @mock(..., nth_child: 3)
+    }
+  }
+}
+```
+
+It is ambiguous if the `nth_child` applies to the concrete or abstract type.
+i.e. does `nth_child: 3` means "the third occurrence of PhysicalStore
+specifically" or "the third element of `findBookInStock`"?
+
+This is particularly problematic where applied inside a fragment defined in a
+separate file, and it's not obvious that the fragment is even called inside of
+a list!
+
+And what if that fragment is reused in multiple queries, both as a list and not
+as a list? 🤯
+
+##### Summary
+
+Although complex, the issues above are solvable in theory. However given the
+complexity, the current version of this specification does not support this.
+
+If you have ideas for how to solve this, please send a pull request for a future
+spec version :)
+
+</details>
+
+### Mocking on inline fragments and fragment spreads
+
+`@mock` is not supported on inline fragments or fragment spreads:
+
+```graphql
+query Foo {
+  barOrBaz {
+    # not supported
+    ... on Bar @mock(variant: "mock-bar") {
+      hello
+    }
+    # not supported
+    ... on Baz @mock(variant: "mock-baz") {
+      world
+    }
+  }
+  qux {
+    # not supported
+    ...QuxFields @mock(variant: "mock-qux")
+  }
+}
+```
+
+Instead, apply `@mock` to individual fields within the fragment:
+
+```graphql
+query Foo {
+  barOrBaz {
+    ... on Bar {
+      hello @mock(value: "hi")
+    }
+    ... on Baz {
+      world @mock(value: "earth")
+    }
+  }
+}
+```
+
+<details>
+<summary>Why not?</summary>
+
+#### New types are unreachable
+
+The primary motivation for `@mock` is building against schema that doesn't yet
+exist. But when a type condition references a new type, the server will never
+return that type in its response — so the mock data has nowhere to be merged.
+
+```graphql
+query PetStore {
+  forSale {
+    ... on Dog {
+      breed
+    }
+    # Fish doesn't exist in the schema yet.
+    # The server will never return __typename: "Fish",
+    # so this mock data can never be inserted.
+    ... on Fish @mock(variant: "clownfish") {
+      species
+    }
+  }
+}
+```
+
+For the non-list case, the client could force-overlay the mock data, but this
+means overriding the server's type resolution — semantically different from what
+`@mock` does elsewhere, where it merges data into a known position in the
+response tree.
+
+For the list case, the client would need to *inject* new objects into the array,
+raising the same position-ambiguity problems described in
+[Why don't we allow specifying an array position?](#why-dont-we-allow-specifying-an-array-position).
+
+#### `__typename` dependency
+
+Merging mock data for a type condition requires knowing which type the server
+resolved. This means the client must rely on `__typename` being present in the
+response. While common (especially with normalized caches), this is not
+guaranteed — adding an implicit runtime dependency that field-level mocking
+does not have.
+
+#### Dead mock branches
+
+When multiple type conditions have `@mock`, only the branch matching the
+server's resolved type will trigger. The other mock variants exist in the mock
+file but are dead code for that response. This makes it harder to validate that
+mock data stays in sync with the operation over time, since stale mocks in
+non-matching branches won't surface as errors.
+
+#### Fragment spread precedence
+
+For `...QuxFields @mock(variant: "mock-qux")`, the fragment `QuxFields` may
+be defined in a separate file with its own mock file (`QuxFields.json`)
+containing field-level `@mock` directives. It is unclear which mocks take
+precedence — the spread-level mock or the individual field-level mocks inside
+the fragment — creating a composition problem that does not exist with
+field-level mocking.
+
+</details>
diff --git a/gaps/GAP-10/SKILL.md b/gaps/GAP-10/SKILL.md
new file mode 100644
index 0000000..f0db8cd
--- /dev/null
+++ b/gaps/GAP-10/SKILL.md
@@ -0,0 +1,122 @@
+---
+name: graphql-mock
+description: Create and edit mock values for GraphQL operations using the @mock directive
+---
+
+This skill manages mock values for GraphQL operations using the `@mock`
+directive.
+
+## Capabilities
+
+- **Add mock variant**: Create a new named mock value for an existing operation
+- **Modify mock**: Update an existing mock value
+- **List mocks**: Show available mock ids for an operation
+
+## Mock Files
+
+Mock files are located in `__graphql_mocks__/{Name}.json` adjacent to
+the source file containing the operation or fragment. {Name} is the name of
+that operation or fragment.
+
+Each mock file is a JSON object where keys are "mock variant ids" and values are
+"mock variants".
+
+A "mock variant" is an object containing the following attributes:
+
+- **`data`** (required): The mock value - the raw data to be returned - defined by https://spec.graphql.org/September2025/#sec-Data.
+- **`errors`**: May contain an errors array - defined by https://spec.graphql.org/September2025/#sec-Errors.
+- **`extensions`**: May contain arbitrary data - defined by https://spec.graphql.org/September2025/#sec-Extensions.
+- **`__path__`** (required): The field path within the operation or fragment where `@mock` is applied. A dot-separated string of field names (or aliases, where present) relative to the root. For `@mock` on an operation root, use the root operation type name (e.g. `"Query"`, `"Mutation"`, `"Subscription"`). When a field has an alias, use the alias in the path.
+- **`__description__`**: A natural language description of the data being returned.
+- **`__metadata__`**: May contain a key/value mapping of arbitrary data.
+
+**Example**
+
+```json
+{
+  "5-star-business": {
+    "data": {
+      "business": {
+        "name": "The Great British Bakery",
+        "rating": 5.0
+      }
+    },
+    "__path__": "Query",
+    "__description__": "A delicious bakery with a rating of 5.0"
+  },
+  "has-no-rating": {
+    "data": {
+      "business": {
+        "name": "El Greco Deli",
+        "rating": null
+      }
+    },
+    "__path__": "Query",
+    "__description__": "A new restaurant which has not yet been rated - the rating field returns null"
+  }
+}
+```
+
+## Generating mock variants
+
+When generating a new mock value, add the following to your context window:
+
+- the user's prompt (e.g. "add a @mock response for this field <highlighted position>")
+- the corresponding selection and nested selection set in the operation or fragment
+- the GraphQL schema. It is possible that some of the fields in the mock
+  response already exist in the schema, and may be looked up - you can use the
+  fields' descriptions, sibling fields' descriptions and the field's parent type
+  description as additional context.
+
+When regenerating an existing mock value, also include the existing mock value
+payload and preserve as much as possible (unless the user has specified
+otherwise).
+
+Ensure the generated mock value is valid against the selections in the operation
+or fragment.
+
+Use plausible and realistic values. e.g. for "Business.name", use a made-up
+business name such as "The Great British Bakery". Avoid using "foo", "bar",
+"myBusiness", "string" etc. as values.
+
+Generate a __description__ field which summarizes the output, and has enough
+context such that it could be used to regenerate a similarly shaped payload.
+
+The values generated for leaf nodes do not matter and do not need to be
+preserved or included in the description - unless otherwise specified by the
+user.
+
+### Errors
+
+When the mock should represent an error state, use the GraphQL errors format -
+unless you know that the schema uses a union to represent error state. You must
+check against the schema.
+
+**Example**
+
+```json
+{
+  "data": { "fieldName": null },
+  "errors": [{
+    "path": ["fieldName"],
+    "message": "field error"
+  }]
+}
+```
+
+## Instructions
+
+When asked to add or update a mock variant:
+
+1. Locate the operation or fragment's mock file
+2. Read the existing mock file to understand the mock value shape
+3. If creating a new mock, create a new entry with a descriptive mock variant id
+4. Ensure the mock value includes appropriate `data` and/or `errors` fields
+5. Add a summary of the user's prompt to the `__description__` field
+6. Write the updated mock file (do not modify other mocks in the file)
+
+## Schema
+
+Look for the GraphQL schema in the repository to understand what shape of data
+should be returned. (e.g. <repo_root>/schema.graphql). Ask the user if the
+schema file cannot be found, and remember where it is located for future.
diff --git a/gaps/GAP-10/metadata.yml b/gaps/GAP-10/metadata.yml
new file mode 100644
index 0000000..c657393
--- /dev/null
+++ b/gaps/GAP-10/metadata.yml
@@ -0,0 +1,16 @@
+id: 10
+title: "@mock Directive"
+summary: >
+  A client-side directive that allows GraphQL clients to return mocked data for
+  individual fields or entire operations, enabling frontend development against
+  schema that doesn't yet exist on the server.
+status: proposal
+authors:
+  - name: "Mark Larah"
+    email: "markl@yelp.com"
+    githubUsername: "@magicmark"
+  - name: "Michael Rebello"
+    email: "me@michaelrebello.com"
+    githubUsername: "@rebello95"
+sponsor: "@magicmark"
+discussion: "https://github.com/graphql/gaps/pull/10"