@webiny/mcp 6.1.0 → 6.2.0

package/index.d.ts

@@ -4,3 +4,5 @@ export { startMcpServer } from "./cli/McpServer.js";
 export type { IMcpServerParams } from "./cli/McpServer.js";
 export { configureMcp } from "./cli/ConfigureMcp.js";
 export type { IConfigureMcpParams } from "./cli/ConfigureMcp.js";
+export { discoverAgents, discoverPresets } from "./agents/discover.js";
+export type { AgentPreset, AgentModule } from "./agents/types.js";

package/index.js

@@ -5,5 +5,7 @@ export { ConsoleUi } from "./ui.js";
 // Core functions
 export { startMcpServer } from "./cli/McpServer.js";
 export { configureMcp } from "./cli/ConfigureMcp.js";
+// Agent discovery
+export { discoverAgents, discoverPresets } from "./agents/discover.js";
 
 //# sourceMappingURL=index.js.map

package/index.js.map

@@ -1 +1 @@
-{"version":3,"names":["ConsoleUi","startMcpServer","configureMcp"],"sources":["index.ts"],"sourcesContent":["// Ui interface and console implementation\nexport type { IUi } from \"./ui.js\";\nexport { ConsoleUi } from \"./ui.js\";\n\n// Core functions\nexport { startMcpServer } from \"./cli/McpServer.js\";\nexport type { IMcpServerParams } from \"./cli/McpServer.js\";\nexport { configureMcp } from \"./cli/ConfigureMcp.js\";\nexport type { IConfigureMcpParams } from \"./cli/ConfigureMcp.js\";\n"],"mappings":"AAAA;;AAEA,SAASA,SAAS;;AAElB;AACA,SAASC,cAAc;AAEvB,SAASC,YAAY","ignoreList":[]}
+{"version":3,"names":["ConsoleUi","startMcpServer","configureMcp","discoverAgents","discoverPresets"],"sources":["index.ts"],"sourcesContent":["// Ui interface and console implementation\nexport type { IUi } from \"./ui.js\";\nexport { ConsoleUi } from \"./ui.js\";\n\n// Core functions\nexport { startMcpServer } from \"./cli/McpServer.js\";\nexport type { IMcpServerParams } from \"./cli/McpServer.js\";\nexport { configureMcp } from \"./cli/ConfigureMcp.js\";\nexport type { IConfigureMcpParams } from \"./cli/ConfigureMcp.js\";\n\n// Agent discovery\nexport { discoverAgents, discoverPresets } from \"./agents/discover.js\";\nexport type { AgentPreset, AgentModule } from \"./agents/types.js\";\n"],"mappings":"AAAA;;AAEA,SAASA,SAAS;;AAElB;AACA,SAASC,cAAc;AAEvB,SAASC,YAAY;AAGrB;AACA,SAASC,cAAc,EAAEC,eAAe","ignoreList":[]}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@webiny/mcp",
-	"version": "6.1.0",
+	"version": "6.2.0",
 	"type": "module",
 	"main": "./index.js",
 	"bin": {
@@ -18,14 +18,14 @@
 		"directory": "dist"
 	},
 	"dependencies": {
-		"@modelcontextprotocol/sdk": "1.28.0",
+		"@modelcontextprotocol/sdk": "1.29.0",
 		"front-matter": "4.0.2",
 		"zod": "4.3.6"
 	},
 	"devDependencies": {
 		"@types/lodash": "4.17.24",
 		"@types/ncp": "2.0.8",
-		"@webiny/build-tools": "6.1.0",
+		"@webiny/build-tools": "6.2.0",
 		"execa": "5.1.1",
 		"tsx": "4.21.0",
 		"typescript": "5.9.3"
@@ -33,5 +33,5 @@
 	"scripts": {
 		"prepublishOnly": "bash ./prepublishOnly.sh"
 	},
-	"gitHead": "65e0ac1889b3392c99b8cac6cde508e1e831c715"
+	"gitHead": "3d3148358b6febbc857371930871743bec3b3939"
 }

package/skills/admin/admin-permissions/SKILL.md

@@ -2,82 +2,68 @@
 name: webiny-admin-permissions
 context: webiny-extensions
 description: >
-  Admin-side permission UI registration using Security.Permissions. Use this skill when
-  adding permission controls to the admin UI — schema-based auto-generated forms, custom
-  permission UIs with usePermissionValue/usePermissionForm, entity dependencies, and
-  the Security.Permissions component props. Covers both simple apps and complex
-  multi-entity permission schemas.
+  Admin-side permission UI registration and DI-backed permission checking.
+  Use this skill when adding permission controls to the admin UI — schema-based
+  auto-generated forms, injectable permissions via createPermissionsAbstraction/
+  createPermissionsFeature, typed hooks (createUsePermissions), the HasPermission
+  component (createHasPermission), and the Security.Permissions component props.
+  Covers both simple apps and complex multi-entity permission schemas.
 ---
 
-# Admin Permissions UI
+# Admin Permissions
 
 ## Overview
 
-Register permissions via `AdminConfig` + `Security.Permissions`. The framework auto-generates the UI from a schema and handles serialization. No form code needed for most apps.
+Permissions follow three layers: **domain** (schema), **features** (DI artifacts + registration), and **presentation** (hooks, components, UI config). The framework auto-generates the permission UI from a schema and provides injectable permission checking via the DI container.
 
-## Schema-Based (Auto-Generated UI)
+## Layer 1: Domain — Permission Schema
 
-```tsx
-import React from "react";
-import { AdminConfig } from "@webiny/app-admin";
-import { ReactComponent as Icon } from "@webiny/icons/shield.svg";
+Define the schema in `src/domain/permissionsSchema.ts`:
 
-const { Security } = AdminConfig;
+```ts
+import { createPermissionSchema } from "webiny/admin/security";
 
-export const MyPermission = () => {
-  return (
-    <AdminConfig>
-      <Security.Permissions
-        name="store-manager"
-        title="Store Manager"
-        description="Manage Store Manager permissions."
-        icon={<Icon />}
-        schema={{
-          prefix: "sm",
-          fullAccess: { name: "sm.*" },
-          entities: [
-            {
-              id: "product",
-              title: "Products",
-              permission: "sm.product",
-              scopes: ["full", "own"],
-              actions: [
-                { name: "rwd" },
-                { name: "pw" },
-                { name: "import", label: "Import products" },
-                { name: "export", label: "Export products" }
-              ]
-            },
-            {
-              id: "category",
-              title: "Categories",
-              permission: "sm.category",
-              scopes: ["full"],
-              actions: [{ name: "rwd" }]
-            },
-            {
-              id: "settings",
-              title: "Settings",
-              permission: "sm.settings",
-              scopes: ["full"]
-            }
-          ]
-        }}
-      />
-    </AdminConfig>
-  );
-};
+export const SM_PERMISSIONS_SCHEMA = createPermissionSchema({
+  prefix: "sm",
+  fullAccess: true,
+  entities: [
+    {
+      id: "product",
+      title: "Products",
+      permission: "sm.product",
+      scopes: ["full", "own"],
+      actions: [
+        { name: "rwd" },
+        { name: "pw" },
+        { name: "import", label: "Import products" },
+        { name: "export", label: "Export products" }
+      ]
+    },
+    {
+      id: "category",
+      title: "Categories",
+      permission: "sm.category",
+      scopes: ["full"],
+      actions: [{ name: "rwd" }]
+    },
+    {
+      id: "settings",
+      title: "Settings",
+      permission: "sm.settings",
+      scopes: ["full"]
+    }
+  ]
+});
 ```
 
-Render `<MyPermission />` anywhere in your app's extension component.
-
-## Schema Reference
+### Schema Reference
 
-| Field        | Type                 | Required | Description                                                    |
-| ------------ | -------------------- | -------- | -------------------------------------------------------------- |
-| `prefix`     | `string`             | Yes      | Permission prefix (e.g., `"sm"`)                               |
-| `fullAccess` | `{ name: string }`   | Yes      | Permission emitted on "Full access" (e.g., `{ name: "sm.*" }`) |
-| `entities`   | `EntityDefinition[]` | No       | Entity definitions. Omit for binary full/no access.            |
+| Field            | Type                 | Required | Description                                                                                                                          |
+| ---------------- | -------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------ |
+| `prefix`         | `string`             | Yes      | Permission prefix (e.g., `"sm"`)                                                                                                     |
+| `fullAccess`     | `true \| object`     | Yes      | `true` for standard full access. Pass an object with custom boolean flags for full-access extras (e.g., `{ canForceUnlock: true }`). |
+| `readOnlyAccess` | `boolean`            | No       | Whether to show a "Read-only access" option                                                                                          |
+| `entities`       | `EntityDefinition[]` | No       | Entity definitions. Omit for binary full/no access.                                                                                  |
 
 ### Entity Definition
 
@@ -110,19 +96,170 @@ Child entities can depend on a parent. If the parent lacks the required action,
 }
 ```
 
+### Simple Apps (No Entities)
+
+Omit `entities` for binary full/no access:
+
+```ts
+export const MA_PERMISSIONS_SCHEMA = createPermissionSchema({
+  prefix: "ma",
+  fullAccess: true
+});
+```
+
 ---
 
-## Simple Apps (No Entities)
+## Layer 2: Features — DI Artifacts + Registration
 
-Omit `entities` for binary full/no access:
+### Abstraction (`src/features/permissions/abstractions.ts`)
+
+```ts
+import { createPermissionsAbstraction } from "webiny/admin/security";
+import type { Permissions } from "webiny/admin/security";
+import { SM_PERMISSIONS_SCHEMA } from "~/domain/permissionsSchema.js";
+
+export const SmPermissions = createPermissionsAbstraction(SM_PERMISSIONS_SCHEMA);
+
+export namespace SmPermissions {
+  export type Interface = Permissions<typeof SM_PERMISSIONS_SCHEMA>;
+}
+```
+
+### Feature (`src/features/permissions/feature.ts`)
+
+```ts
+import { createPermissionsFeature } from "webiny/admin/security";
+import { SM_PERMISSIONS_SCHEMA } from "~/domain/permissionsSchema.js";
+import { SmPermissions } from "./abstractions.js";
+
+export const SmPermissionsFeature = createPermissionsFeature(SM_PERMISSIONS_SCHEMA, SmPermissions);
+```
+
+### Extension Registration
+
+Register the feature and the permission UI in your extension component:
+
+```tsx
+import { AdminConfig, RegisterFeature } from "webiny/admin/security";
+import { ReactComponent as Icon } from "@webiny/icons/shield.svg";
+import { SM_PERMISSIONS_SCHEMA } from "~/domain/permissionsSchema.js";
+import { SmPermissionsFeature } from "~/features/permissions/feature.js";
+
+const { Security } = AdminConfig;
+
+export const Extension = () => {
+  return (
+    <>
+      <RegisterFeature feature={SmPermissionsFeature} />
+      <AdminConfig>
+        <Security.Permissions
+          name="store-manager"
+          title="Store Manager"
+          description="Manage Store Manager permissions."
+          icon={<Icon />}
+          schema={SM_PERMISSIONS_SCHEMA}
+        />
+        {/* Routes, menus, etc. */}
+      </AdminConfig>
+    </>
+  );
+};
+```
+
+---
+
+## Layer 3: Presentation — Hooks & Components
+
+### `usePermissions` Hook
+
+```ts
+// src/presentation/security/usePermissions.ts
+import { createUsePermissions } from "webiny/admin/security";
+import { SmPermissions } from "~/features/permissions/abstractions.js";
+
+export const usePermissions = createUsePermissions(SmPermissions);
+```
+
+Usage:
+
+```ts
+const permissions = usePermissions();
+
+permissions.canAccess("product"); // has any access
+permissions.canRead("product"); // rwd includes "r"
+permissions.canCreate("product"); // rwd includes "w"
+permissions.canEdit("product", item); // rwd includes "w", respects own scope
+permissions.canDelete("product"); // rwd includes "d"
+permissions.canPublish("product"); // pw includes "p"
+permissions.canUnpublish("product"); // pw includes "u"
+permissions.canAction("import", "product"); // custom boolean flag
+```
+
+Entity IDs are fully typed — `canRead("bogus")` produces a type error.
+
+### `HasPermission` Component
 
 ```tsx
-<Security.Permissions
-  name="my-app"
-  title="My App"
-  description="Manage My App access permissions."
-  schema={{ prefix: "ma", fullAccess: { name: "ma.*" } }}
-/>
+// src/presentation/security/HasPermission.tsx
+import { createHasPermission } from "webiny/admin/security";
+import { SmPermissions } from "~/features/permissions/abstractions.js";
+import { SM_PERMISSIONS_SCHEMA } from "~/domain/permissionsSchema.js";
+
+export const HasPermission = createHasPermission(SmPermissions, SM_PERMISSIONS_SCHEMA);
+```
+
+Usage in JSX:
+
+```tsx
+<HasPermission entity="product">
+    {/* Rendered if user can access "product" */}
+</HasPermission>
+
+<HasPermission any={["product", "category"]}>
+    {/* Rendered if user can access ANY of these entities */}
+</HasPermission>
+
+<HasPermission all={["product", "category"]}>
+    {/* Rendered if user can access ALL of these entities */}
+</HasPermission>
+
+<HasPermission entity="product" action="read">
+    {/* Rendered if user canRead("product") */}
+</HasPermission>
+
+<HasPermission entity="product" allActions={["read", "publish"]}>
+    {/* Rendered if user canRead AND canPublish "product" */}
+</HasPermission>
+
+<HasPermission entity="product" someActions={["import", "export"]}>
+    {/* Rendered if user can do ANY of these custom actions */}
+</HasPermission>
+```
+
+---
+
+## DI Injection in Features
+
+Inject permissions into feature implementations:
+
+```ts
+import type { SmPermissions } from "~/features/permissions/abstractions.js";
+import { SmPermissions as SmPermissionsAbstraction } from "~/features/permissions/abstractions.js";
+
+class SomeFeatureImpl {
+  constructor(private permissions: SmPermissions.Interface) {}
+
+  doSomething() {
+    if (this.permissions.canEdit("product")) {
+      // ...
+    }
+  }
+}
+
+const SomeFeature = SomeAbstraction.createImplementation({
+  implementation: SomeFeatureImpl,
+  dependencies: [SmPermissionsAbstraction]
+});
 ```
 
 ---
@@ -141,12 +278,29 @@ Omit `entities` for binary full/no access:
 
 ---
 
+## File Structure
+
+```
+src/
+├── domain/
+│   └── permissionsSchema.ts          # createPermissionSchema()
+├── features/
+│   └── permissions/
+│       ├── abstractions.ts           # createPermissionsAbstraction() + namespace type
+│       └── feature.ts                # createPermissionsFeature()
+├── presentation/
+│   └── security/
+│       ├── usePermissions.ts         # createUsePermissions()
+│       └── HasPermission.tsx         # createHasPermission()
+└── Extension.tsx                     # RegisterFeature + Security.Permissions
+```
+
 ## Matching API-Side Permissions
 
 The admin schema and the API-side `createPermissions` schema should use the **same prefix, entity IDs, and action names**. This ensures the permissions emitted by the admin UI are correctly evaluated by the API.
 
 ```
-Admin:  schema={{ prefix: "sm", entities: [{ id: "product", permission: "sm.product", ... }] }}
+Admin:  createPermissionSchema({ prefix: "sm", entities: [{ id: "product", permission: "sm.product", ... }] })
 API:    createPermissions({ prefix: "sm", entities: [{ id: "product", permission: "sm.product", ... }] })
 ```
 

package/skills/admin/ui-extensions/SKILL.md

@@ -176,56 +176,25 @@ Create custom forms for Website Builder page types using Webiny's form component
 ```tsx
 // extensions/customPageTypes/RetailPageForm.tsx
 import React from "react";
-import { Grid, Input, Select } from "webiny/admin/ui";
-import { pagePathFromTitle } from "webiny/admin/website-builder";
-import type { FormApi } from "webiny/admin/form";
-import { Bind, UnsetOnUnmount, useForm, validation } from "webiny/admin/form";
+import { PageListConfig } from "webiny/admin/website-builder/page/list";
+import { Bind, UnsetOnUnmount, validation } from "webiny/admin/form";
 
-const generatePath = (form: FormApi) => () => {
-  const title = form.getValue("properties.title");
-  const language = form.getValue("extensions.language");
-
-  const titlePath = pagePathFromTitle(title ?? "");
-  const parts = [language, titlePath].filter(Boolean);
-
-  form.setValue("properties.path", `/${parts.join("/")}`);
-};
+const { PageType } = PageListConfig;
 
 export const RetailPageForm = () => {
   const form = useForm();
 
   return (
     <>
+      {/* Mount the default page form fields. */}
+      <PageType.Language />
+      <PageType.Title />
+      <PageType.Path />
+      {/* Add custom fields.*/}
       <Grid.Column span={12}>
-        <UnsetOnUnmount name={"properties.title"}>
-          <Bind name={"properties.title"} validators={[validation.create("required")]}>
-            <Input label={"Title"} onBlur={generatePath(form)} />
-          </Bind>
-        </UnsetOnUnmount>
-      </Grid.Column>
-      <Grid.Column span={12}>
-        <UnsetOnUnmount name={"extensions.language"}>
-          <Bind
-            name={"extensions.language"}
-            validators={[validation.create("required")]}
-            afterChange={generatePath(form)}
-          >
-            <Select
-              placeholder={"Select a language"}
-              label={"Language"}
-              options={[
-                { label: "English", value: "en" },
-                { label: "German", value: "de" },
-                { label: "French", value: "fr" }
-              ]}
-            />
-          </Bind>
-        </UnsetOnUnmount>
-      </Grid.Column>
-      <Grid.Column span={12}>
-        <UnsetOnUnmount name={"properties.path"}>
-          <Bind name={"properties.path"} validators={[validation.create("required")]}>
-            <Input label={"Path"} />
+        <UnsetOnUnmount name={"extensions.customField"}>
+          <Bind name={"extensions.customField"} validators={[validation.create("required")]}>
+            <Input label={"Custom Field"} />
           </Bind>
         </UnsetOnUnmount>
       </Grid.Column>

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

@@ -426,7 +426,7 @@ export const CreateEntityFeature = createFeature({
 A deployed API must **NEVER** use `process.env` to read configuration. All configuration flows through `BuildParams` via DI:
 
 ```ts
-import { BuildParams } from "webiny/api/build-params";
+import { BuildParams } from "webiny/api";
 
 class MyServiceImpl implements MyService.Interface {
   constructor(private buildParams: BuildParams.Interface) {}
@@ -672,6 +672,7 @@ Creates a feature definition that the framework loads as an extension.
 - **webiny-api-permissions** — Schema-based permissions, CRUD authorization patterns, own-record scoping, testing
 - **webiny-event-handler-pattern** — EventHandler lifecycle, domain event definition and publishing, handler abstractions
 - **webiny-custom-graphql-api** — GraphQL schema creation, dynamic inputs, namespaced mutations
+- **webiny-http-route** — Custom HTTP endpoints via `Api.Route` and `Route.Interface`
 - **webiny-v5-to-v6-migration** — Side-by-side migration patterns for AI agents
 - **webiny-full-stack-architect** — Top-level component, shared domain layer, BuildParam declarations
 - **webiny-dependency-injection** — The `createImplementation` DI pattern and injectable services

package/skills/api/http-route/SKILL.md

@@ -0,0 +1,176 @@
+---
+name: webiny-http-route
+context: webiny-extensions
+description: >
+  Adding custom HTTP routes to the API using Api.Route and Route.Interface.
+  Use this skill when the developer wants to expose a custom HTTP endpoint (GET, POST, PUT, etc.)
+  on the API Gateway alongside the GraphQL handler, implement Route.Interface with full DI support,
+  or register a custom HTTP handler in webiny.config.tsx.
+---
+
+# Custom HTTP Routes
+
+## TL;DR
+
+Add a custom HTTP route by implementing `Route.Interface` and registering it with `<Api.Route>` in `webiny.config.tsx`. The `path` and `method` props configure API Gateway and Fastify route registration. Your handler receives a framework-agnostic `Route.Request` and `Route.Reply` and supports full DI (Logger, BuildParams, UseCases, etc.).
+
+**YOU MUST include the full file path with the `.ts` extension in the `src` prop.** For example, use `src={"/extensions/MyRoute.ts"}`, NOT `src={"/extensions/MyRoute"}`. 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 a `src` prop. Named exports cause build failures here.
+
+## The Route Pattern
+
+```typescript
+// extensions/MyRoute.ts
+import { Route } from "webiny/api/route";
+import { Logger } from "webiny/api/logger";
+import { BuildParams } from "webiny/api/build-params";
+
+class MyRouteImpl implements Route.Interface {
+  constructor(
+    private logger: Logger.Interface,
+    private buildParams: BuildParams.Interface
+  ) {}
+
+  async execute(request: Route.Request, reply: Route.Reply): Promise<void> {
+    this.logger.info("Handling request", { url: request.url });
+
+    const config = this.buildParams.get<string>("MY_CONFIG");
+
+    reply.code(200).send({ status: "ok", config });
+  }
+}
+
+export default Route.createImplementation({
+  implementation: MyRouteImpl,
+  dependencies: [Logger, BuildParams]
+});
+```
+
+Register in `webiny.config.tsx`:
+
+```tsx
+<Api.Route method={"POST"} path={"/my-route"} src={"/extensions/MyRoute.ts"} />
+```
+
+## Props Reference
+
+| Prop        | Type     | Required | Description                                                                 |
+| ----------- | -------- | -------- | --------------------------------------------------------------------------- |
+| `path`      | `string` | Yes      | Route path — must start with `/`                                            |
+| `method`    | `string` | Yes      | HTTP method (see list below)                                                |
+| `src`       | `string` | Yes      | Path to the handler file (must include `.ts` extension)                     |
+| `routeName` | `string` | No       | Pulumi resource name (kebab-case). Auto-derived from path+method if omitted |
+
+## Supported HTTP Methods
+
+`DELETE`, `GET`, `HEAD`, `PATCH`, `POST`, `PUT`, `OPTIONS`, `ANY`
+
+Use `ANY` to match all HTTP methods on a given path.
+
+## Route.Request / Route.Reply Interfaces
+
+These are framework-agnostic — no Fastify types leak into user code.
+
+### `Route.Request`
+
+```ts
+interface Route.Request {
+    body: unknown;
+    headers: Record<string, string | string[] | undefined>;
+    method: string;
+    url: string;
+    params: unknown;   // path parameters, e.g. { id: "abc" }
+    query: unknown;    // query string parameters
+}
+```
+
+### `Route.Reply`
+
+```ts
+interface Route.Reply {
+    code(statusCode: number): this;   // set HTTP status code
+    send(data?: unknown): void;       // send response body
+    header(key: string, value: unknown): this;
+}
+```
+
+Chaining example:
+
+```ts
+reply.code(201).header("X-Custom", "value").send({ created: true });
+```
+
+## How It Works
+
+The `<Api.Route>` extension does two things at build/deploy time:
+
+1. **Build time** — injects two entries into `apps/api/graphql/src/extensions.ts`:
+
+   - A `createContextPlugin` that registers your handler in the DI container
+   - A `createRoute` that registers the Fastify route with the hardcoded `path` and `method`
+
+2. **Deploy time (Pulumi)** — calls `graphql.addRoute({ name, path, method })` on the `ApiGraphql` module to create the API Gateway route
+
+At request time, the handler is resolved from the DI container — so all `dependencies` (Logger, BuildParams, UseCases, etc.) are fully injected.
+
+## Example with Path Parameters
+
+```typescript
+// extensions/GetOrderRoute.ts
+import { Route } from "webiny/api/route";
+import { Logger } from "webiny/api/logger";
+
+interface OrderParams {
+  orderId: string;
+}
+
+class GetOrderRouteImpl implements Route.Interface {
+  constructor(private logger: Logger.Interface) {}
+
+  async execute(request: Route.Request, reply: Route.Reply): Promise<void> {
+    const { orderId } = request.params as OrderParams;
+    this.logger.info("Fetching order", { orderId });
+
+    // ... fetch and return order
+    reply.code(200).send({ orderId, status: "fulfilled" });
+  }
+}
+
+export default Route.createImplementation({
+  implementation: GetOrderRouteImpl,
+  dependencies: [Logger]
+});
+```
+
+```tsx
+<Api.Route method={"GET"} path={"/orders/{orderId}"} src={"/extensions/GetOrderRoute.ts"} />
+```
+
+## Key Rules
+
+- **`path` and `method` are hardcoded at build time** — the Fastify route is registered before any request arrives. Your handler does not need to specify them.
+- **DI is fully available in `execute()`** — the handler instance is resolved from the container per request, so all dependencies are injected normally.
+- **One handler per file** — each `src` file exports one `Route.createImplementation` result.
+- **Constructor param order must match the `dependencies` array** exactly.
+- **Use `.js` extensions** in all relative imports inside the handler file (ESM).
+- **Do not read `process.env`** at runtime — use `BuildParams` for configuration instead.
+
+## Quick Reference
+
+```
+Import (handler):  import { Route } from "webiny/api/route";
+Interface:         Route.Interface
+Request type:      Route.Request
+Reply type:        Route.Reply
+Export:            Route.createImplementation({ implementation, dependencies })
+Register:          <Api.Route method={"POST"} path={"/my-route"} src={"/extensions/MyRoute.ts"} />
+Deploy:            yarn webiny deploy api --env=dev
+```
+
+## Related Skills
+
+- **webiny-api-architect** — DI patterns, Services, UseCases, feature organization
+- **webiny-custom-graphql-api** — Custom GraphQL endpoints (alternative to HTTP)
+- **webiny-dependency-injection** — Injectable services catalog (Logger, BuildParams, etc.)
+- **webiny-infrastructure-extensions** — Pulumi-level infrastructure customization