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

package/skills/api/permissions/SKILL.md

@@ -0,0 +1,291 @@
+---
+name: webiny-api-permissions
+context: webiny-api
+description: >
+  Schema-based permission system for API features. Use this skill when implementing
+  authorization in use cases, defining permission schemas with createPermissions,
+  checking read/write/delete/publish permissions, handling own-record scoping,
+  or testing permission scenarios. Covers the full pattern from schema definition
+  to use case integration to test matrices.
+---
+
+# Schema-Based Permissions
+
+## Overview
+
+Webiny uses a **schema-based permission system** defined via `createPermissions`. Each package declares a permission schema and gets a typed `Permissions` abstraction injectable into use cases via DI. This replaces manual `identityContext.getPermission()` calls with high-level methods like `canRead`, `canEdit`, `canDelete`, `canPublish`, `onlyOwnRecords`, etc.
+
+## Permission Schema Definition
+
+```ts
+// domain/permissions.ts (or permissions/schema.ts)
+import { createPermissions } from "@webiny/api-core/features/security/permissions/index.js";
+import type { Permissions } from "@webiny/api-core/features/security/permissions/index.js";
+
+const schema = {
+  prefix: "wb", // Permission prefix
+  fullAccess: { name: "wb.*" }, // Wildcard = full access to all entities
+  entities: [
+    {
+      id: "page", // Entity identifier (used in method calls)
+      permission: "wb.page", // Permission name stored on the identity
+      scopes: ["full", "own"], // Access scopes: "full" = all records, "own" = only own
+      actions: [
+        { name: "rwd" }, // Read/Write/Delete (chars: "r", "w", "d")
+        { name: "pw" } // Publish/Unpublish (chars: "p", "u")
+      ]
+    },
+    {
+      id: "settings",
+      permission: "wb.settings",
+      scopes: ["full"] // No "own" — no ownership concept for settings
+    }
+  ]
+} as const; // MUST use `as const` for type narrowing
+
+type MySchema = typeof schema;
+
+export const MyPermissions = createPermissions(schema);
+
+export namespace MyPermissions {
+  export type Interface = Permissions<MySchema>;
+}
+```
+
+`createPermissions` returns `{ Abstraction, Implementation }`. Register the Implementation in your feature.
+
+### Schema Fields
+
+| Field                   | Description                                                           |
+| ----------------------- | --------------------------------------------------------------------- |
+| `prefix`                | Namespaces the DI abstraction: `${prefix}:Permissions`                |
+| `fullAccess.name`       | Wildcard permission (e.g. `"wb.*"`) — grants all entity access        |
+| `entities[].id`         | Entity identifier used in method calls: `canRead("page")`             |
+| `entities[].permission` | Permission name matched against identity permissions                  |
+| `entities[].scopes`     | `["full"]` or `["full", "own"]` — determines if own-scope supported   |
+| `entities[].actions`    | Action definitions — built-in: `"rwd"`, `"pw"`; custom: boolean flags |
+
+### Scopes
+
+- **`"full"`** — User can access all records (default when no `own` flag on permission object)
+- **`"own"`** — User can only access records where `createdBy.id === identity.id`
+
+---
+
+## Permission Methods
+
+All methods follow a 3-tier bypass:
+
+1. `identityContext.hasFullAccess()` → `name: "*"` permission (super admin)
+2. `hasFullSchemaAccess()` → wildcard permission (e.g. `"wb.*"`)
+3. Entity-level permission check
+
+### Method Reference
+
+| Method                      | Purpose               | Item-aware | Notes                                                                                         |
+| --------------------------- | --------------------- | ---------- | --------------------------------------------------------------------------------------------- |
+| `canAccess(entity, item?)`  | General access check  | Yes        | Without item: checks entity permission exists. With item + `own: true`: checks `createdBy.id` |
+| `onlyOwnRecords(entity)`    | List filter flag      | No         | Returns `true` when ALL permissions have `own: true`                                          |
+| `canRead(entity)`           | Read permission       | No         | Checks `rwd` includes `"r"` (or no `rwd` = unrestricted)                                      |
+| `canCreate(entity)`         | Create permission     | No         | Checks `rwd` includes `"w"`                                                                   |
+| `canEdit(entity, item?)`    | Edit permission       | Yes        | With `own: true` + no item → allows (new/unsaved). With item → checks ownership               |
+| `canDelete(entity, item?)`  | Delete permission     | Yes        | With `own: true` + no item → **RETURNS FALSE**. Must pass item                                |
+| `canPublish(entity)`        | Publish permission    | No         | Checks `pw` includes `"p"`                                                                    |
+| `canUnpublish(entity)`      | Unpublish permission  | No         | Checks `pw` includes `"u"`                                                                    |
+| `canAction(action, entity)` | Custom boolean action | No         | Checks `permission[action] === true`                                                          |
+
+All return `Promise<boolean>`.
+
+### OwnableItem Interface
+
+```ts
+interface OwnableItem {
+  createdBy?: { id: string } | null;
+}
+```
+
+---
+
+## Use Case Implementation Patterns
+
+### Get Use Case (Read + Ownership Gate)
+
+The Get use case is the **central ownership gate** — mutation use cases that delegate to GetById inherit ownership enforcement automatically.
+
+```ts
+import { Result } from "@webiny/feature/api";
+import { GetByIdUseCase as UseCaseAbstraction, GetByIdRepository } from "./abstractions.js";
+import { MyPermissions } from "~/domain/permissions.js";
+import { NotAuthorizedError } from "~/domain/errors.js";
+
+class GetByIdUseCaseImpl implements UseCaseAbstraction.Interface {
+  constructor(
+    private permissions: MyPermissions.Interface,
+    private repository: GetByIdRepository.Interface
+  ) {}
+
+  async execute(id: string): UseCaseAbstraction.Return {
+    // 1. Entity-level read check
+    if (!(await this.permissions.canRead("entity"))) {
+      return Result.fail(new NotAuthorizedError());
+    }
+
+    // 2. Fetch
+    const result = await this.repository.execute(id);
+    if (result.isFail()) {
+      return result;
+    }
+
+    // 3. Item-level ownership check
+    if (!(await this.permissions.canAccess("entity", result.value))) {
+      return Result.fail(new NotAuthorizedError());
+    }
+
+    return result;
+  }
+}
+
+export const GetByIdUseCase = UseCaseAbstraction.createImplementation({
+  implementation: GetByIdUseCaseImpl,
+  dependencies: [MyPermissions.Abstraction, GetByIdRepository]
+});
+```
+
+### List Use Case (Read + Own Records Filter)
+
+```ts
+import { IdentityContext } from "@webiny/api-core/features/security/IdentityContext/index.js";
+
+class ListUseCaseImpl implements UseCaseAbstraction.Interface {
+  constructor(
+    private permissions: MyPermissions.Interface,
+    private identityContext: IdentityContext.Interface,
+    private repository: ListRepository.Interface
+  ) {}
+
+  async execute(params: UseCaseAbstraction.Params): UseCaseAbstraction.Return {
+    if (!(await this.permissions.canRead("entity"))) {
+      return Result.fail(new NotAuthorizedError());
+    }
+
+    const where = { ...params.where };
+
+    // Filter to own records if needed
+    if (await this.permissions.onlyOwnRecords("entity")) {
+      const identity = this.identityContext.getIdentity();
+      where.createdBy = identity.id;
+    }
+
+    return this.repository.execute({ ...params, where });
+  }
+}
+
+// Dependencies must include IdentityContext
+dependencies: [MyPermissions.Abstraction, IdentityContext, ListRepository];
+```
+
+**Important:** The list `where` type must include `createdBy?: string`. For CMS-based entities, `CmsEntryListWhere` already has this.
+
+### Update Use Case (Edit + Item-Level Check)
+
+```ts
+class UpdateUseCaseImpl implements UseCaseAbstraction.Interface {
+  constructor(
+    private permissions: MyPermissions.Interface,
+    private getById: GetByIdUseCase.Interface, // Delegates ownership gate
+    private repository: UpdateRepository.Interface
+  ) {}
+
+  async execute(id: string, data: UpdateData): UseCaseAbstraction.Return {
+    // 1. Entity-level edit check (no item yet)
+    if (!(await this.permissions.canEdit("entity"))) {
+      return Result.fail(new NotAuthorizedError());
+    }
+
+    // 2. Fetch original (enforces canRead + canAccess via GetById)
+    const getResult = await this.getById.execute(id);
+    if (getResult.isFail()) {
+      return getResult;
+    }
+
+    const original = getResult.value;
+
+    // 3. Item-level edit check (defense in depth)
+    if (!(await this.permissions.canEdit("entity", original))) {
+      return Result.fail(new NotAuthorizedError());
+    }
+
+    // ... events + repository
+  }
+}
+```
+
+### Delete Use Case (CRITICAL: Item-Level Delete)
+
+**`canDelete` with `own: true` and no item returns `false`.**
+
+Unlike `canEdit` (which returns `true` for `own: true` + no item), `canDelete` requires the item to verify ownership. The delete use case MUST fetch the item first.
+
+```ts
+class DeleteUseCaseImpl implements UseCaseAbstraction.Interface {
+  async execute(params: Params): UseCaseAbstraction.Return {
+    // Fetch first (enforces canRead + canAccess via GetById)
+    const getResult = await this.getById.execute(params.id);
+    if (getResult.isFail()) {
+      return Result.fail(getResult.error);
+    }
+
+    const item = getResult.value;
+
+    // Item-level delete check — MUST pass the item
+    if (!(await this.permissions.canDelete("entity", item))) {
+      return Result.fail(new NotAuthorizedError());
+    }
+
+    // ... events + repository
+  }
+}
+```
+
+### Publish Use Case (Publish + Ownership)
+
+```ts
+class PublishUseCaseImpl {
+  async execute(params: Params): UseCaseAbstraction.Return {
+    // 1. Entity-level publish check
+    if (!(await this.permissions.canPublish("entity"))) {
+      return Result.fail(new NotAuthorizedError());
+    }
+
+    // 2. Fetch (enforces ownership via GetById)
+    const getResult = await this.getById.execute(params.id);
+    if (getResult.isFail()) {
+      return getResult;
+    }
+
+    // 3. Item-level ownership check (defense in depth)
+    if (!(await this.permissions.canAccess("entity", getResult.value))) {
+      return Result.fail(new NotAuthorizedError());
+    }
+
+    // ... events + repository
+  }
+}
+```
+
+---
+
+## Gotchas
+
+1. **`canDelete` without item + `own: true` = `false`** — Always pass the item to `canDelete`. Fetch first, then check.
+2. **`canEdit` without item + `own: true` = `true`** — Intentional: allows editing new/unsaved records.
+3. **`canAccess` without item = `true`** — Only checks entity-level access, not ownership.
+4. **List where type** — Ensure the `where` interface includes `createdBy?: string` for own-scope filtering.
+5. **`as const`** — The schema MUST use `as const` for TypeScript to narrow entity IDs in method signatures.
+6. **Dependencies order** — DI constructor params must match the `dependencies` array order exactly.
+
+## Related Skills
+
+- **webiny-api-architect** — Architecture overview, Services vs UseCases, feature structure
+- **webiny-use-case-pattern** — UseCase implementation, Result handling, decorators
+- **webiny-dependency-injection** — Injectable services catalog

package/skills/api/use-case-pattern/SKILL.md

@@ -2,20 +2,19 @@
 name: webiny-use-case-pattern
 context: webiny-api
 description: >
-  Generic UseCase implementation pattern — DI, Result handling, extension registration.
-  Use this skill to understand how to implement, inject, or override any Webiny UseCase.
+  UseCase implementation pattern — DI, Result handling, error types, decorators, CMS repositories,
+  entry mappers, and schema-based permissions. Use this skill to implement, inject, override, or
+  decorate any Webiny UseCase, or to build repositories that persist data via CMS.
 ---
 
 # UseCase Pattern
 
 ## What It Is
 
-A **UseCase** is a named operation that encapsulates business logic (e.g., `CreateTenantUseCase`, `PublishEntryUseCase`). Each UseCase is a DI abstraction with a single `execute` method.
+A **UseCase** is a single-method orchestrator that encapsulates one business operation (e.g., `CreateTenantUseCase`, `PublishEntryUseCase`). Each UseCase is a DI abstraction with an `execute` method that returns `Result<T, E>`.
 
 ## Interface Shape
 
-Every UseCase follows this pattern:
-
 ```ts
 interface SomeUseCase.Interface {
     execute(input: Input): Promise<Result<ReturnType, ErrorType>>;
@@ -28,7 +27,7 @@ interface SomeUseCase.Interface {
 
 ## How to Use a UseCase
 
-UseCases are injected as dependencies into EventHandlers or other UseCases via DI.
+UseCases are injected as dependencies into EventHandlers, other UseCases, or GraphQL resolvers via DI.
 
 ```ts
 import { SomeUseCase } from "webiny/api/<category>";
@@ -78,6 +77,10 @@ export default SomeUseCase.createImplementation({
 
 ## Registration
 
+**YOU MUST include the full file path with the `.ts` extension in the `src` prop.** For example, use `src={"@/extensions/my-extension.ts"}`, NOT `src={"@/extensions/my-extension"}`. 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
 // In your app's configuration
 <Api.Extension src={"@/extensions/my-extension.ts"} />
@@ -85,18 +88,354 @@ export default SomeUseCase.createImplementation({
 
 Deploy with: `yarn webiny deploy api --env=dev`
 
+---
+
+## Error Handling Pattern
+
+### Domain-Specific Errors
+
+Every feature defines errors extending `BaseError`. Never use generic `Error` for validation or business rule failures.
+
+```ts
+// domain/errors.ts
+import { BaseError } from "@webiny/feature/api";
+
+export class EntityNotFoundError extends BaseError {
+    override readonly code = "Entity/NotFound" as const;
+    constructor(id: string) {
+        super({ message: `Entity with id "${id}" was not found!` });
+    }
+}
+
+export class EntityPersistenceError extends BaseError<{ error: Error }> {
+    override readonly code = "Entity/Persist" as const;
+    constructor(error: Error) {
+        super({ message: error.message, data: { error } });
+    }
+}
+
+export class EntityValidationError extends BaseError<{ message: string }> {
+    override readonly code = "Entity/Validation" as const;
+    constructor(message: string) {
+        super({ message, data: { message } });
+    }
+}
+```
+
+### Typed Error Unions in Abstractions
+
+Define an `IErrors` interface mapping error names to types, then create a union via `[keyof IErrors]`:
+
+```ts
+// features/createEntity/abstractions.ts
+import { createAbstraction, Result } from "@webiny/feature/api";
+import { NotAuthorizedError } from "@webiny/api-core/features/security/shared/errors.js";
+import { EntityPersistenceError, EntityModelNotFoundError, EntityCreationError } from "~/api/domain/errors.js";
+
+// REPOSITORY errors
+export interface ICreateEntityRepositoryErrors {
+    persistence: EntityPersistenceError;
+    modelNotFound: EntityModelNotFoundError;
+    creation: EntityCreationError;
+}
+
+type RepositoryError = ICreateEntityRepositoryErrors[keyof ICreateEntityRepositoryErrors];
+
+export interface ICreateEntityRepository {
+    execute(entity: Entity): Promise<Result<Entity, RepositoryError>>;
+}
+
+export const CreateEntityRepository = createAbstraction<ICreateEntityRepository>(
+    "MyExt/CreateEntityRepository"
+);
+
+export namespace CreateEntityRepository {
+    export type Interface = ICreateEntityRepository;
+    export type Error = RepositoryError;
+    export type Return = Promise<Result<Entity, RepositoryError>>;
+}
+
+// USE CASE errors — superset of repository errors
+export interface ICreateEntityUseCaseErrors {
+    persistence: EntityPersistenceError;
+    modelNotFound: EntityModelNotFoundError;
+    creation: EntityCreationError;
+    notAuthorized: NotAuthorizedError;
+}
+
+type UseCaseError = ICreateEntityUseCaseErrors[keyof ICreateEntityUseCaseErrors];
+
+export interface ICreateEntityUseCase {
+    execute(input: CreateEntityInput): Promise<Result<Entity, UseCaseError>>;
+}
+
+export const CreateEntityUseCase = createAbstraction<ICreateEntityUseCase>(
+    "MyExt/CreateEntityUseCase"
+);
+
+export namespace CreateEntityUseCase {
+    export type Interface = ICreateEntityUseCase;
+    export type Input = CreateEntityInput;
+    export type Error = UseCaseError;
+    export type Return = Promise<Result<Entity, UseCaseError>>;
+}
+```
+
+### Result Pattern
+
+```ts
+// Success
+return Result.ok(value);
+
+// Failure
+return Result.fail(new EntityNotFoundError(id));
+
+// Check result
+if (result.isFail()) {
+    return Result.fail(result.error);
+}
+
+// Access value
+const value = result.value;
+```
+
+Never use `result.isError()`, `result.getError()`, or `result.getValue()` — these do not exist.
+
+---
+
+## UseCase Implementation
+
+```ts
+// features/createEntity/CreateEntityUseCase.ts
+import { CreateEntityUseCase as UseCaseAbstraction, CreateEntityRepository } from "./abstractions.js";
+import { Result } from "@webiny/feature/api";
+import { IdentityContext } from "@webiny/api-core/exports/api/security.js";
+import { NotAuthorizedError } from "@webiny/api-core/features/security/shared/errors.js";
+import { Entity } from "~/shared/Entity.js";
+import { EntityId } from "~/api/domain/EntityId.js";
+
+class CreateEntityUseCase implements UseCaseAbstraction.Interface {
+    constructor(
+        private identityContext: IdentityContext.Interface,
+        private repository: CreateEntityRepository.Interface
+    ) {}
+
+    async execute(input: UseCaseAbstraction.Input): UseCaseAbstraction.Return {
+        if (!this.identityContext.getPermission("mypackage.entity")) {
+            return Result.fail(new NotAuthorizedError({ message: "Not authorized to create entities!" }));
+        }
+
+        const entity = Entity.from({
+            id: EntityId.from(input.id),
+            values: { name: input.name, status: "disabled" }
+        });
+
+        const result = await this.repository.execute(entity);
+        if (result.isFail()) {
+            return Result.fail(result.error);
+        }
+
+        return Result.ok(result.value);
+    }
+}
+
+export default UseCaseAbstraction.createImplementation({
+    implementation: CreateEntityUseCase,
+    dependencies: [IdentityContext, CreateEntityRepository]
+});
+```
+
+**Rules:**
+- Class implements `UseCaseAbstraction.Interface`
+- Constructor params typed with `.Interface` from their abstractions
+- Return type uses `UseCaseAbstraction.Return`
+- `dependencies` array matches constructor parameter order exactly
+- Export as `default`
+
+---
+
+## CMS Repository Pattern
+
+Repositories use CMS use cases to persist data. Always resolve the CMS model first.
+
+```ts
+// features/createEntity/CreateEntityRepository.ts
+import { Entity } from "~/shared/Entity.js";
+import { EntityCreationError, EntityModelNotFoundError } from "~/api/domain/errors.js";
+import { CreateEntityRepository as RepositoryAbstraction } from "./abstractions.js";
+import { Result } from "@webiny/feature/api";
+import { CreateEntryUseCase } from "@webiny/api-headless-cms/exports/api/cms/entry.js";
+import { GetModelUseCase } from "@webiny/api-headless-cms/exports/api/cms/model";
+import { ENTITY_MODEL_ID } from "~/shared/constants.js";
+
+class CreateEntityRepository implements RepositoryAbstraction.Interface {
+    constructor(
+        private getModelUseCase: GetModelUseCase.Interface,
+        private createEntryUseCase: CreateEntryUseCase.Interface
+    ) {}
+
+    async execute(entity: Entity): RepositoryAbstraction.Return {
+        const modelResult = await this.getModelUseCase.execute(ENTITY_MODEL_ID);
+        if (modelResult.isFail()) {
+            return Result.fail(new EntityModelNotFoundError());
+        }
+
+        const createResult = await this.createEntryUseCase.execute(modelResult.value, {
+            id: entity.id,
+            values: {
+                name: entity.values.name,
+                status: entity.values.status
+            }
+        });
+
+        if (createResult.isFail()) {
+            return Result.fail(new EntityCreationError(createResult.error));
+        }
+
+        return Result.ok(entity);
+    }
+}
+
+export default RepositoryAbstraction.createImplementation({
+    implementation: CreateEntityRepository,
+    dependencies: [GetModelUseCase, CreateEntryUseCase]
+});
+```
+
+### Common CMS Use Cases for Repositories
+
+```ts
+import { CreateEntryUseCase } from "@webiny/api-headless-cms/exports/api/cms/entry.js";
+import { GetEntryByIdUseCase } from "@webiny/api-headless-cms/exports/api/cms/entry.js";
+import { GetEntryUseCase } from "@webiny/api-headless-cms/exports/api/cms/entry.js";
+import { UpdateEntryUseCase } from "@webiny/api-headless-cms/exports/api/cms/entry.js";
+import { ListLatestEntriesUseCase } from "@webiny/api-headless-cms/exports/api/cms/entry.js";
+import { EntryId } from "@webiny/api-headless-cms/exports/api/cms/entry.js";
+import { GetModelUseCase } from "@webiny/api-headless-cms/exports/api/cms/model";
+import { ListModelsUseCase } from "@webiny/api-headless-cms/exports/api/cms/model.js";
+```
+
+**Rules:**
+- Always resolve the CMS model first via `GetModelUseCase`
+- Wrap CMS errors in domain-specific errors
+- Register repositories in **singleton scope**
+- Export as `default`
+
+---
+
+## Entry-to-Entity Mapper
+
+When repositories return CMS entries, use a mapper to convert to domain types:
+
+```ts
+// features/shared/EntryToEntityMapper.ts
+import { Entity as EntityClass } from "~/shared/Entity.js";
+import type { Entity, EntityDto, EntityValues } from "~/shared/Entity.js";
+
+export class EntryToEntityMapper {
+    static toEntity(entry: { entryId: string; values: EntityValues }): Entity {
+        return EntityClass.from({
+            id: entry.entryId,
+            values: entry.values
+        });
+    }
+}
+```
+
+- Static methods only — no instance state
+- Used by repositories, not by use cases directly
+- Handle null/undefined values with defaults where appropriate
+
+---
+
+## UseCase Decorators
+
+Decorators add cross-cutting concerns (authorization, logging, validation) without modifying the core use case.
+
+```ts
+// features/getEntityById/decorators/GetEntityByIdWithAuthorization.ts
+import { GetEntityByIdUseCase } from "../abstractions.js";
+import { Result } from "@webiny/feature/api";
+import { IdentityContext } from "@webiny/api-core/exports/api/security.js";
+import { NotAuthorizedError } from "@webiny/api-core/features/security/shared/errors.js";
+
+class GetEntityByIdWithAuthorizationImpl implements GetEntityByIdUseCase.Interface {
+    constructor(
+        private identityContext: IdentityContext.Interface,
+        private decoratee: GetEntityByIdUseCase.Interface  // decoratee is LAST
+    ) {}
+
+    async execute(id: string): GetEntityByIdUseCase.Return {
+        if (!this.identityContext.getPermission("mypackage.entity")) {
+            return Result.fail(new NotAuthorizedError());
+        }
+        return this.decoratee.execute(id);
+    }
+}
+
+export const GetEntityByIdWithAuthorization = GetEntityByIdUseCase.createDecorator({
+    decorator: GetEntityByIdWithAuthorizationImpl,
+    dependencies: [IdentityContext]  // does NOT include decoratee
+});
+```
+
+### Registering a Decorator
+
+```ts
+// features/getEntityById/feature.ts
+import { createFeature } from "@webiny/feature/api";
+import GetEntityByIdUseCase from "./GetEntityByIdUseCase.js";
+import GetEntityByIdRepository from "./GetEntityByIdRepository.js";
+import { GetEntityByIdWithAuthorization } from "./decorators/GetEntityByIdWithAuthorization.js";
+
+export const GetEntityByIdFeature = createFeature({
+    name: "GetEntityById",
+    register(container) {
+        container.register(GetEntityByIdUseCase);
+        container.register(GetEntityByIdRepository).inSingletonScope();
+        container.registerDecorator(GetEntityByIdWithAuthorization);
+    }
+});
+```
+
+**Rules:**
+- Implements the same interface as the use case it decorates
+- Constructor: extra dependencies first, `decoratee` **last**
+- Use `UseCaseAbstraction.createDecorator(...)` — the `dependencies` array does NOT include the decoratee
+- Register with `container.registerDecorator()`, not `container.register()`
+- Can modify input before delegating, output after, or short-circuit with an error
+
+---
+
+## Schema-Based Permissions
+
+For implementing authorization in use cases, see the **webiny-api-permissions** skill. It covers:
+- Permission schema definition with `createPermissions`
+- All permission methods (`canRead`, `canEdit`, `canDelete`, `canPublish`, `onlyOwnRecords`, etc.)
+- Use case patterns for every CRUD operation (get, list, update, delete, publish)
+- Own-record scoping and item-level ownership checks
+- Testing patterns and permission object shapes
+
+---
+
 ## Resolving Types (MANDATORY)
 
 **Before writing any code that calls a UseCase or accesses its return types, you MUST read the source file listed in the catalog's `Source` field to verify the exact method signatures, input parameters, return types, and error types. Do not assume or guess property names from memory.**
 
-To see the exact types for a specific UseCase:
-
-1. Read the `abstractions.ts` file from the catalog `Source` path — it contains the `Interface` with the full method signature, input types, and error union.
-2. If the interface references domain types (e.g., `CmsEntry`, `CmsModel`), follow the import and read that type declaration too.
-3. Only use properties and method signatures that are confirmed to exist in the source type declarations.
+1. Read the `abstractions.ts` file from the catalog `Source` path
+2. If the interface references domain types, follow the import and read that type declaration
+3. Only use properties and method signatures confirmed in the source
 
 ## Key Rules
 
-- Always check `result.isOk()` or `result.isFail()` before accessing `.value` or `.error`
+- Always check `result.isFail()` before accessing `.value` or `.error`
 - 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, anti-patterns
+- **webiny-api-permissions** — Schema-based permissions, CRUD authorization patterns, testing
+- **webiny-event-handler-pattern** — EventHandler lifecycle, domain event publishing
+- **webiny-custom-graphql-api** — GraphQL schema creation with UseCase DI
+- **webiny-dependency-injection** — Injectable services catalog