@webiny/mcp 6.1.0-beta.1 → 6.1.0-beta.3

package/skills/api/event-handler-pattern/SKILL.md

@@ -2,8 +2,10 @@
 name: webiny-event-handler-pattern
 context: webiny-api
 description: >
-  Generic EventHandler implementation pattern — handle method, event payloads, filtering, DI.
-  Use this skill to understand how to implement any Webiny EventHandler (before/after hooks).
+  EventHandler implementation pattern — handle method, event payloads, filtering, DI,
+  domain event definition, publishing events from UseCases, and reacting to external events.
+  Use this skill to implement any Webiny EventHandler (before/after hooks) or to define
+  and publish your own domain events.
 ---
 
 # EventHandler Pattern
@@ -19,8 +21,6 @@ An **EventHandler** reacts to domain events in the Webiny lifecycle (e.g., `Entr
 
 ## Interface Shape
 
-Every EventHandler follows this pattern:
-
 ```ts
 interface SomeEventHandler.Interface {
     handle(event: SomeEventHandler.Event): Promise<void>;
@@ -31,9 +31,9 @@ The `Event` is a `DomainEvent<Payload>` where the payload contains the entity an
 
 ## Architecture Rule: Always Wrap Logic in a Reusable Abstraction (MANDATORY)
 
-**Never put business logic directly inside an EventHandler.** EventHandlers are thin orchestrators — they receive an event and delegate to an injected service (abstraction). The real logic lives in a dedicated service defined with `createAbstraction` and `createFeature`.
+**Never put business logic directly inside an EventHandler.** EventHandlers are thin orchestrators — they receive an event and delegate to an injected service or use case. The real logic lives in a dedicated abstraction.
 
-**Why:** Inline handler logic cannot be reused by other handlers, GraphQL resolvers, or CLI commands. Wrapping it in an abstraction makes it injectable, testable, and replaceable.
+**Why:** Inline handler logic cannot be reused by other handlers, GraphQL resolvers, or CLI commands.
 
 **Always follow this structure:**
 
@@ -43,12 +43,12 @@ features/
 │   ├── abstractions.ts
 │   ├── feature.ts
 │   └── MyService.ts
-└── myHandler/             ← thin handler that injects the service
+└── syncOnCreate/          ← thin handler that injects the service
     ├── feature.ts
-    └── MyHandler.ts
+    └── EntryAfterCreateHandler.ts
 ```
 
-The EventHandler feature and the service feature are **registered separately** in `Extension.tsx`.
+The EventHandler feature and the service feature are **registered separately** in `Extension.ts`.
 
 ## How to Implement
 
@@ -61,10 +61,10 @@ class MyHandler implements SomeEventHandler.Interface {
   constructor(private myService: MyService.Interface) {}
 
   async handle(event: SomeEventHandler.Event) {
-    const { entity } = event.payload;
+    const { entity, model } = event.payload;
 
-    // For CMS handlers: always filter by model
-    // if (entity.modelId !== "myModel") return;
+    // For CMS handlers: ALWAYS filter by model
+    if (model.modelId !== "myModel") return;
 
     await this.myService.doWork(entity);
   }
@@ -80,7 +80,7 @@ See **webiny-api-architect** for how to define `MyService` as a proper abstracti
 
 ## Injecting Dependencies
 
-EventHandlers can depend on UseCases, platform services, or your own custom abstractions:
+EventHandlers can depend on UseCases, platform services, or custom abstractions:
 
 ```ts
 import { SomeEventHandler } from "webiny/api/<category>";
@@ -90,9 +90,7 @@ class MyHandler implements SomeEventHandler.Interface {
   constructor(private someUseCase: SomeUseCase.Interface) {}
 
   async handle(event: SomeEventHandler.Event) {
-    const result = await this.someUseCase.execute({
-      /* ... */
-    });
+    const result = await this.someUseCase.execute({ /* ... */ });
   }
 }
 
@@ -102,8 +100,175 @@ export default SomeEventHandler.createImplementation({
 });
 ```
 
+---
+
+## Defining Your Own Domain Events
+
+When your feature needs to notify other parts of the system about important domain actions, define your own events.
+
+### Event Payload Types (in `abstractions.ts`)
+
+Event payloads and handler abstractions live in `abstractions.ts`. The `events.ts` file only contains the event classes.
+
+```ts
+// features/disableEntity/abstractions.ts
+import { createAbstraction } from "@webiny/feature/api";
+import type { IEventHandler } from "@webiny/api-core/features/EventPublisher";
+import type { Entity } from "~/shared/Entity.js";
+// Forward declaration — actual classes are in events.ts
+import type { EntityBeforeDisableEvent, EntityAfterDisableEvent } from "./events.js";
+
+// Event Payload Types
+export interface EntityBeforeDisablePayload {
+    entity: Entity;
+}
+
+export interface EntityAfterDisablePayload {
+    entity: Entity;
+}
+
+// Handler Abstractions — one per event
+export const EntityBeforeDisableEventHandler = createAbstraction<
+    IEventHandler<EntityBeforeDisableEvent>
+>("MyPackage/EntityBeforeDisableEventHandler");
+
+export namespace EntityBeforeDisableEventHandler {
+    export type Interface = IEventHandler<EntityBeforeDisableEvent>;
+    export type Event = EntityBeforeDisableEvent;
+}
+
+export const EntityAfterDisableEventHandler = createAbstraction<
+    IEventHandler<EntityAfterDisableEvent>
+>("MyPackage/EntityAfterDisableEventHandler");
+
+export namespace EntityAfterDisableEventHandler {
+    export type Interface = IEventHandler<EntityAfterDisableEvent>;
+    export type Event = EntityAfterDisableEvent;
+}
+```
+
+### Event Class Definition (`events.ts`)
+
+Event classes import payload types and handler abstractions from `abstractions.ts`.
+
+```ts
+// features/disableEntity/events.ts
+import { DomainEvent } from "@webiny/api-core/features/EventPublisher";
+import {
+    EntityBeforeDisableEventHandler,
+    EntityAfterDisableEventHandler
+} from "./abstractions.js";
+import type {
+    EntityBeforeDisablePayload,
+    EntityAfterDisablePayload
+} from "./abstractions.js";
+
+export class EntityBeforeDisableEvent extends DomainEvent<EntityBeforeDisablePayload> {
+    eventType = "entity.beforeDisable" as const;
+
+    getHandlerAbstraction() {
+        return EntityBeforeDisableEventHandler;
+    }
+}
+
+export class EntityAfterDisableEvent extends DomainEvent<EntityAfterDisablePayload> {
+    eventType = "entity.afterDisable" as const;
+
+    getHandlerAbstraction() {
+        return EntityAfterDisableEventHandler;
+    }
+}
+```
+
+### Publishing Events from a UseCase
+
+```ts
+// features/disableEntity/DisableEntityUseCase.ts
+import { EventPublisher } from "@webiny/api-core/features/EventPublisher";
+import { EntityBeforeDisableEvent, EntityAfterDisableEvent } from "./events.js";
+
+class DisableEntityUseCase implements UseCaseAbstraction.Interface {
+    constructor(
+        private eventPublisher: EventPublisher.Interface,
+        private getEntityById: GetEntityByIdUseCase.Interface,
+        private updateEntity: UpdateEntityUseCase.Interface
+    ) {}
+
+    async execute(entityId: string): Promise<Result<void, UseCaseAbstraction.Error>> {
+        const getResult = await this.getEntityById.execute(entityId);
+        if (getResult.isFail()) return Result.fail(getResult.error);
+
+        const entity = getResult.value;
+
+        // Publish BEFORE event (can be intercepted to reject)
+        await this.eventPublisher.publish(new EntityBeforeDisableEvent({ entity }));
+
+        // Perform the operation
+        const updateResult = await this.updateEntity.execute(entityId, { status: "disabled" });
+        if (updateResult.isFail()) return Result.fail(updateResult.error);
+
+        // Publish AFTER event (for side effects)
+        await this.eventPublisher.publish(new EntityAfterDisableEvent({ entity: updateResult.value }));
+
+        return Result.ok();
+    }
+}
+
+export default UseCaseAbstraction.createImplementation({
+    implementation: DisableEntityUseCase,
+    dependencies: [EventPublisher, GetEntityByIdUseCase, UpdateEntityUseCase]
+});
+```
+
+---
+
+## Reacting to External Events
+
+To react to events from other packages (e.g., CMS entry deletion), implement the external event's handler abstraction:
+
+```ts
+// features/cleanupOnEntryDelete/CleanupOnEntryDeleteHandler.ts
+import { EntryAfterDeleteEventHandler } from "@webiny/api-headless-cms/features/contentEntry/DeleteEntry/events.js";
+import { CleanupService } from "../cleanupService/abstractions.js";
+import { MY_MODEL_ID } from "~/shared/constants.js";
+
+class CleanupOnEntryDeleteHandler implements EntryAfterDeleteEventHandler.Interface {
+    constructor(private cleanupService: CleanupService.Interface) {}
+
+    async handle(event: EntryAfterDeleteEventHandler.Event): Promise<void> {
+        const { entry, model } = event.payload;
+
+        // ALWAYS filter by model — handler fires for ALL models
+        if (model.modelId !== MY_MODEL_ID) return;
+
+        if (!event.payload.permanent) return;
+
+        await this.cleanupService.cleanup(entry.entryId);
+    }
+}
+
+export default EntryAfterDeleteEventHandler.createImplementation({
+    implementation: CleanupOnEntryDeleteHandler,
+    dependencies: [CleanupService]
+});
+```
+
+---
+
+## Event Naming Conventions
+
+| Artifact           | Pattern                                        | Example                            |
+| ------------------ | ---------------------------------------------- | ---------------------------------- |
+| `eventType`        | `"entity.beforeAction"` / `"entity.afterAction"` | `"tenant.beforeDisable"`          |
+| Handler abstraction | `{Entity}{Before\|After}{Action}EventHandler` | `TenantBeforeDisableEventHandler` |
+| Event class        | `{Entity}{Before\|After}{Action}Event`         | `TenantBeforeDisableEvent`        |
+
 ## Registration
 
+**YOU MUST include the full file path with the `.ts` extension in the `src` prop.** For example, use `src={"@/extensions/my-handler.ts"}`, NOT `src={"@/extensions/my-handler"}`. Omitting the file extension will cause a build failure.
+
+**YOU MUST use `export default` for the `createImplementation()` call** when the file is targeted directly by an Extension `src` prop. Using a named export (`export const Foo = SomeFactory.createImplementation(...)`) will cause a build failure. Named exports are only valid inside files registered via `createFeature`.
+
 ```tsx
 <Api.Extension src={"@/extensions/my-handler.ts"} />
 ```
@@ -114,18 +279,25 @@ Deploy with: `yarn webiny deploy api --env=dev`
 
 **Before writing any code that accesses event payload properties or domain types (CmsEntry, CmsModel, etc.), you MUST read the source file listed in the catalog's `Source` field to verify the exact property names and types. Do not assume or guess property names from memory.**
 
-To see the exact event payload types for a specific EventHandler:
-
-1. Read the `abstractions.ts` file from the catalog `Source` path — it contains the payload interface with all property names and types.
-2. Read the `events.ts` file (sibling to `abstractions.ts`) — it contains the `Interface` and `Event` type aliases.
-3. If the payload references domain types (e.g., `CmsEntry`, `CmsModel`), follow the import and read that type declaration too.
-
-Only use properties that are confirmed to exist in the source type declarations.
+1. Read the `abstractions.ts` file from the catalog `Source` path — it contains the payload interface
+2. Read the `events.ts` file (sibling to `abstractions.ts`) — it contains the `Interface` and `Event` types
+3. If the payload references domain types, follow the import and read that declaration
 
 ## Key Rules
 
 - **Before handlers**: payload may be mutable — write to it to set computed fields. Throw to reject the operation.
 - **After handlers**: payload reflects persisted state — do not mutate. Use for side effects.
 - **Filter by entity**: handlers fire for ALL entities of that type. Always check `modelId`, `entity type`, etc.
+- **Events extend** `DomainEvent<TPayload>` with `eventType` property (not `static type`)
+- **Every event must** implement `getHandlerAbstraction()` returning its handler abstraction
+- **Every handler abstraction** must have a namespace with `Interface` and `Event` types
+- **Payload types** live in `abstractions.ts`; event classes live in `events.ts`
+- **Publish order**: before event → operation → after event
 - DI constructor parameter order must match the `dependencies` array order exactly
 - Use `.js` extensions in import paths (ES modules)
+
+## Related Skills
+
+- **webiny-api-architect** — Architecture overview, Services vs UseCases, feature naming
+- **webiny-use-case-pattern** — UseCase implementation where events are published from
+- **webiny-dependency-injection** — Injectable services catalog

package/skills/api/graphql-api/SKILL.md

@@ -5,19 +5,24 @@ description: >
   Adding custom GraphQL queries and mutations using GraphQLSchemaFactory.
   Use this skill when the developer wants to add custom GraphQL endpoints, create custom
   queries or mutations, add business logic to the API layer, build custom resolvers,
-  or inject backend services (identity, tenancy, CMS use-cases) into their GraphQL schema.
-  Covers the full pattern from simple queries to complex resolvers with dependency injection.
+  inject backend services (identity, tenancy, CMS use-cases) into their GraphQL schema,
+  or build dynamic GraphQL inputs from CMS models. Covers the full pattern from simple
+  queries to complex resolvers with dependency injection and permission transformers.
 ---
 
 # Custom GraphQL API
 
 ## TL;DR
 
-Add custom GraphQL queries and mutations using the `GraphQLSchemaFactory` builder pattern. Implement `GraphQLSchemaFactory.Interface`, use the builder to add type definitions and resolvers (with per-resolver DI), and export with `GraphQLSchemaFactory.createImplementation()`. Register as `<Api.Extension>`.
+Add custom GraphQL queries and mutations using `GraphQLSchemaFactory`. Implement `GraphQLSchemaFactory.Interface`, use the schema builder to add type definitions and resolvers (with per-resolver DI), and export with `GraphQLSchemaFactory.createImplementation()`. Register as `<Api.Extension>`.
+
+**YOU MUST include the full file path with the `.ts` extension in every `src` prop.** For example, use `src={"/extensions/MySchema.ts"}`, NOT `src={"/extensions/MySchema"}`. Omitting the file extension will cause a build failure.
+
+**YOU MUST use `export default` for the `createImplementation()` call** when the file is targeted directly by an Extension `src` prop. Using a named export (`export const Foo = SomeFactory.createImplementation(...)`) will cause a build failure. Named exports are only valid inside files registered via `createFeature`.
 
 ## The GraphQLSchemaFactory Pattern
 
-The `execute` method receives a `builder` (`GraphQLSchemaBuilder.Interface`) and returns it after adding type defs and resolvers.
+The `execute` method receives a schema builder and returns it after adding type defs and resolvers.
 
 ```typescript
 // extensions/mySchema/MyGraphQLSchema.ts
@@ -62,7 +67,7 @@ export const MySchema = () => {
 };
 ```
 
-## Builder API Reference
+## Schema Builder API Reference
 
 | Method                                  | Description                                                                                   |
 | --------------------------------------- | --------------------------------------------------------------------------------------------- |
@@ -93,7 +98,7 @@ Key points:
 
 ## Per-Resolver Dependency Injection
 
-Dependencies in `addResolver` are resolved at request time from the request-scoped container. This is different from class-level constructor DI -- it gives each resolver access to request-scoped services like identity and tenant context.
+Dependencies in `addResolver` are resolved at request time from the request-scoped container. This is different from class-level constructor DI — it gives each resolver access to request-scoped services like identity and tenant context.
 
 ```typescript
 import { GraphQLSchemaFactory } from "webiny/api/graphql";
@@ -130,66 +135,259 @@ export default GraphQLSchemaFactory.createImplementation({
 });
 ```
 
-## Nested Mutation Pattern
+Note: `GraphQLSchemaFactory` implementations typically have `dependencies: []` because DI happens at the resolver level via `addResolver({ dependencies })`, not at the class constructor level.
+
+---
+
+## Query Schema with UseCase DI
 
-For namespaced mutations (e.g. `mutation { tenantManager { installTenant } }`), add a pass-through resolver for the namespace type:
+Full pattern using `Response` / `ErrorResponse` wrappers and UseCase injection:
 
 ```typescript
-import { GraphQLSchemaFactory } from "webiny/api/graphql";
-import { IdentityContext } from "webiny/api/security";
-import { MyService } from "@/extensions/myFeature/MyFeature.js";
+import { Response } from "@webiny/handler-graphql";
+import { ErrorResponse } from "@webiny/handler-graphql";
+import { GraphQLSchemaFactory } from "@webiny/handler-graphql/graphql/abstractions.js";
+import { GetCurrentEntityUseCase } from "../features/getCurrentEntity/abstractions.js";
 
-class OrderSchema implements GraphQLSchemaFactory.Interface {
+class GetCurrentEntitySchema implements GraphQLSchemaFactory.Interface {
   async execute(
     builder: GraphQLSchemaFactory.SchemaBuilder
   ): Promise<GraphQLSchemaFactory.SchemaBuilder> {
     builder.addTypeDefs(/* GraphQL */ `
-      type Order {
+      type EntityResponse {
+        data: Entity
+        error: Error
+      }
+
+      type Entity {
         id: ID!
-        total: Float!
+        values: JSON!
       }
 
-      type OrderMutation {
-        create(total: Float!): Order
+      type MyPackageQuery {
+        getCurrentEntity: EntityResponse
       }
 
-      extend type Mutation {
-        orders: OrderMutation
+      extend type Query {
+        myPackage: MyPackageQuery
       }
     `);
 
     // Pass-through resolver for the namespace
     builder.addResolver({
-      path: "Mutation.orders",
+      path: "Query.myPackage",
       resolver: () => {
         return () => ({});
       }
     });
 
-    // Actual mutation with DI
-    builder.addResolver<{ total: number }>({
-      path: "OrderMutation.create",
-      dependencies: [IdentityContext, MyService],
-      resolver: (identityContext: IdentityContext.Interface, myService: MyService.Interface) => {
+    builder.addResolver({
+      path: "MyPackageQuery.getCurrentEntity",
+      dependencies: [GetCurrentEntityUseCase],
+      resolver: (getEntity: GetCurrentEntityUseCase.Interface) => {
+        return async () => {
+          const result = await getEntity.execute();
+          if (result.isFail()) {
+            return new ErrorResponse(result.error);
+          }
+          return new Response(result.value);
+        };
+      }
+    });
+
+    return builder;
+  }
+}
+
+export default GraphQLSchemaFactory.createImplementation({
+  implementation: GetCurrentEntitySchema,
+  dependencies: []
+});
+```
+
+---
+
+## Namespaced Mutation Pattern
+
+For namespaced mutations (e.g. `mutation { myPackage { createEntity } }`):
+
+1. **One schema** defines the base namespace type + extends `Mutation`
+2. **Other schemas** extend the namespace type
+
+```typescript
+// Schema 1: defines the namespace
+builder.addTypeDefs(/* GraphQL */ `
+  type MyPackageMutation {
+    _empty: String
+  }
+
+  extend type Mutation {
+    myPackage: MyPackageMutation
+  }
+`);
+
+builder.addResolver({
+  path: "Mutation.myPackage",
+  resolver: () => {
+    return () => ({});
+  }
+});
+
+// Schema 2: extends the namespace
+builder.addTypeDefs(/* GraphQL */ `
+  extend type MyPackageMutation {
+    disableEntity(entityId: ID!): BooleanResponse
+  }
+`);
+
+builder.addResolver<{ entityId: string }>({
+  path: "MyPackageMutation.disableEntity",
+  dependencies: [DisableEntityUseCase],
+  resolver: (disableEntity: DisableEntityUseCase.Interface) => {
+    return async ({ args }) => {
+      const result = await disableEntity.execute(args.entityId);
+      if (result.isFail()) {
+        return new ErrorResponse(result.error);
+      }
+      return new Response(true);
+    };
+  }
+});
+```
+
+---
+
+## Dynamic Input Fields from CMS Model
+
+When GraphQL inputs must reflect CMS model fields (e.g., an extensible "extensions" object):
+
+```typescript
+import { GraphQLSchemaFactory } from "@webiny/handler-graphql/graphql/abstractions.js";
+import { Response, ErrorResponse } from "@webiny/handler-graphql";
+import { PluginsContainer } from "@webiny/api-headless-cms/legacy/abstractions.js";
+import { renderInputFields } from "@webiny/api-headless-cms/utils/renderInputFields.js";
+import { createFieldTypePluginRecords } from "@webiny/api-headless-cms/graphql/schema/createFieldTypePluginRecords.js";
+import { ListModelsUseCase } from "@webiny/api-headless-cms/exports/api/cms/model.js";
+import { CreateEntityUseCase } from "../features/createEntity/abstractions.js";
+import { ENTITY_MODEL_ID } from "~/shared/constants.js";
+
+class CreateEntitySchema implements GraphQLSchemaFactory.Interface {
+  constructor(
+    private pluginsContainer: PluginsContainer.Interface,
+    private listModelsUseCase: ListModelsUseCase.Interface
+  ) {}
+
+  async execute(
+    builder: GraphQLSchemaFactory.SchemaBuilder
+  ): Promise<GraphQLSchemaFactory.SchemaBuilder> {
+    const inputCreateFields = await this.getExtensionsInput();
+
+    builder.addTypeDefs(/* GraphQL */ `
+      ${inputCreateFields.map(f => f.typeDefs).join("\n")}
+
+      input CreateEntityInput {
+        id: ID
+        name: String!
+        description: String
+        ${inputCreateFields.map(f => f.fields).join("\n")}
+      }
+
+      extend type MyPackageMutation {
+        createEntity(input: CreateEntityInput!): BooleanResponse
+      }
+    `);
+
+    builder.addResolver<{ input: CreateEntityUseCase.Input }>({
+      path: "MyPackageMutation.createEntity",
+      dependencies: [CreateEntityUseCase],
+      resolver: (createEntity: CreateEntityUseCase.Interface) => {
         return async ({ args }) => {
-          if (!identityContext.getPermission("orders.create")) {
-            throw new Error("Not authorized");
+          const result = await createEntity.execute(args.input);
+          if (result.isFail()) {
+            return new ErrorResponse(result.error);
           }
-          return { id: "order-1", total: args.total };
+          return new Response(true);
         };
       }
     });
 
     return builder;
   }
+
+  private async getExtensionsInput() {
+    const fieldTypePlugins = createFieldTypePluginRecords(this.pluginsContainer);
+    const modelsResult = await this.listModelsUseCase.execute({
+      includePlugins: true,
+      includePrivate: false
+    });
+
+    if (modelsResult.isFail()) {
+      return [{ typeDefs: "", fields: "extensions: JSON" }];
+    }
+
+    const models = modelsResult.value;
+    const model = models.find(m => m.modelId === ENTITY_MODEL_ID)!;
+
+    return renderInputFields({
+      models,
+      model,
+      fields: model.fields.filter(f => f.fieldId === "extensions"),
+      fieldTypePlugins
+    });
+  }
 }
 
+// Note: constructor DI needed here because of PluginsContainer + ListModelsUseCase
 export default GraphQLSchemaFactory.createImplementation({
-  implementation: OrderSchema,
+  implementation: CreateEntitySchema,
+  dependencies: [PluginsContainer, ListModelsUseCase]
+});
+```
+
+---
+
+## Permission Transformer (Adding CMS Permissions)
+
+When your package needs CMS access, implement a `PermissionTransformer` to expand your custom permission into the required CMS permissions:
+
+```typescript
+// features/addCmsPermissions/AddCmsPermissions.ts
+import { PermissionTransformer } from "@webiny/api-core/features/security/authorization/AuthorizationContext/abstractions.js";
+
+class AddCmsPermissions implements PermissionTransformer.Interface {
+  execute(permission: PermissionTransformer.Permission) {
+    if (permission.name !== "mypackage.*") {
+      return permission;
+    }
+
+    return [
+      permission,
+      { name: "cms.endpoint.manage" },
+      { name: "cms.contentModel", own: false, rwd: "r", pw: "", models: ["myEntityModelId"] },
+      { name: "cms.contentModelGroup", own: false, rwd: "r", pw: "", groups: ["hidden"] },
+      { name: "cms.contentEntry", own: false, rwd: "rwd", pw: "" }
+    ];
+  }
+}
+
+export default PermissionTransformer.createImplementation({
+  implementation: AddCmsPermissions,
   dependencies: []
 });
 ```
 
+---
+
+## Key Rules
+
+- Implement `GraphQLSchemaFactory.Interface`
+- Use `builder.addTypeDefs()` for schema definitions and `builder.addResolver()` for resolvers
+- Resolver `dependencies` array lists DI abstractions; resolver function receives resolved instances in same order
+- Type the resolver args generic: `builder.addResolver<{ input: UseCaseAbstraction.Input }>`
+- The root Query/Mutation types define a namespace type (e.g., `MyPackageQuery`, `MyPackageMutation`) extended by individual schemas
+- Use `Response` for success, `ErrorResponse` for failure (from `@webiny/handler-graphql`)
+- Export as `default`
+
 ## Quick Reference
 
 ```
@@ -200,10 +398,12 @@ Return:       Promise<GraphQLSchemaFactory.SchemaBuilder>
 Export:       GraphQLSchemaFactory.createImplementation({ implementation, dependencies })
 Register:     <Api.Extension src={"@/extensions/mySchema/MyGraphQLSchema.ts"} />
 Deploy:       yarn webiny deploy api --env=dev
+Response:     import { Response, ErrorResponse } from "@webiny/handler-graphql"
 ```
 
 ## Related Skills
 
-- `webiny-api-architect` -- Define custom abstractions, features, and services consumed by resolvers
-- `webiny-dependency-injection` -- Full DI reference for all injectable services
-- `webiny-project-structure` -- How to register extensions in `webiny.config.tsx`
+- **webiny-api-architect** — Architecture overview, Services vs UseCases, feature naming, anti-patterns
+- **webiny-use-case-pattern** — UseCase implementation consumed by GraphQL resolvers
+- **webiny-dependency-injection** — Full DI reference for all injectable services
+- **webiny-project-structure** — How to register extensions in `webiny.config.tsx`