@webiny/mcp 6.3.0-beta.2 → 6.3.0-beta.3

package/skills/generated/api/tenant-manager/SKILL.md

@@ -2,7 +2,7 @@
 name: webiny-api-tenant-manager-catalog
 context: webiny-api
 description: >
-  API — Tenant Manager — 2 abstractions.
+  API — Tenant Manager — 9 abstractions.
   Tenant management event handlers and use cases.
 ---
 
@@ -19,6 +19,36 @@ Tenant management event handlers and use cases.
 
 ## Abstractions
 
+---
+**Name:** `CreateAndInstallTenantUseCase`
+**Import:** `import { CreateAndInstallTenantUseCase } from "webiny/api/tenant-manager"`
+**Source:** `@webiny/tenant-manager/api/features/CreateAndInstallTenant/abstractions.ts`
+
+---
+**Name:** `CreateTenantUseCase`
+**Import:** `import { CreateTenantUseCase } from "webiny/api/tenant-manager"`
+**Source:** `@webiny/tenant-manager/api/features/CreateTenant/abstractions.ts`
+
+---
+**Name:** `DisableTenantUseCase`
+**Import:** `import { DisableTenantUseCase } from "webiny/api/tenant-manager"`
+**Source:** `@webiny/tenant-manager/api/features/DisableTenant/abstractions.ts`
+
+---
+**Name:** `EnableTenantUseCase`
+**Import:** `import { EnableTenantUseCase } from "webiny/api/tenant-manager"`
+**Source:** `@webiny/tenant-manager/api/features/EnableTenant/abstractions.ts`
+
+---
+**Name:** `GetCurrentTenantUseCase`
+**Import:** `import { GetCurrentTenantUseCase } from "webiny/api/tenant-manager"`
+**Source:** `@webiny/tenant-manager/api/features/GetCurrentTenant/abstractions.ts`
+
+---
+**Name:** `GetTenantByIdUseCase`
+**Import:** `import { GetTenantByIdUseCase } from "webiny/api/tenant-manager"`
+**Source:** `@webiny/tenant-manager/api/features/GetTenantById/abstractions.ts`
+
 ---
 **Name:** `TenantExtensions`
 **Kind:** type
@@ -32,3 +62,8 @@ Tenant management event handlers and use cases.
 **Description:** Extend the tenant content model with custom fields.
 
 ---
+**Name:** `UpdateTenantUseCase`
+**Import:** `import { UpdateTenantUseCase } from "webiny/api/tenant-manager"`
+**Source:** `@webiny/tenant-manager/api/features/UpdateTenant/abstractions.ts`
+
+---

package/skills/generated/infra/SKILL.md

@@ -46,8 +46,7 @@ Infrastructure extensions.
 ---
 **Name:** `AdminPulumi`
 **Import:** `import { AdminPulumi } from "webiny/infra/admin"`
-**Source:** `@webiny/project/abstractions/features/pulumi/AdminPulumi.ts`
-**Description:** Implement this abstraction to add custom Pulumi code to Admin.
+**Source:** `@webiny/project-aws/abstractions/features/pulumi/AdminPulumi.ts`
 
 ---
 **Name:** `AdminStackOutputService`
@@ -102,8 +101,7 @@ Infrastructure extensions.
 ---
 **Name:** `ApiPulumi`
 **Import:** `import { ApiPulumi } from "webiny/infra/api"`
-**Source:** `@webiny/project/abstractions/features/pulumi/ApiPulumi.ts`
-**Description:** Implement this abstraction to add custom Pulumi code to API.
+**Source:** `@webiny/project-aws/abstractions/features/pulumi/ApiPulumi.ts`
 
 ---
 **Name:** `ApiStackOutputService`
@@ -153,8 +151,7 @@ Infrastructure extensions.
 ---
 **Name:** `CorePulumi`
 **Import:** `import { CorePulumi } from "webiny/infra/core"`
-**Source:** `@webiny/project/abstractions/features/pulumi/CorePulumi.ts`
-**Description:** Implement this abstraction to add custom Pulumi code to Core.
+**Source:** `@webiny/project-aws/abstractions/features/pulumi/CorePulumi.ts`
 
 ---
 **Name:** `CoreStackOutputService`

package/skills/mailer-smtp/SKILL.md

@@ -0,0 +1,98 @@
+---
+name: webiny-mailer-smtp
+description: >
+  Use when configuring SMTP email/mailer settings in a Webiny project.
+  Triggers on: "configure email", "set up SMTP", "mailer config", "sending emails",
+  "email not working", "configure mailer", "SMTP password", "Api.Mailer.Smtp".
+---
+
+# Mailer SMTP Configuration
+
+## TL;DR
+
+Add `<Api.Mailer.Smtp ... />` to your `webiny.config.tsx` to configure SMTP email delivery at build time. The component serializes the settings into the build artifact — always pass the password via an environment variable, never hard-code it. Deploy the API after making changes.
+
+## Core Pattern
+
+```tsx
+import { Api } from "@webiny/project-aws/api";
+
+<Api.Mailer.Smtp
+    host={"smtp.example.com"}
+    port={587}
+    user={"smtp-user"}
+    password={process.env.SMTP_PASSWORD!}
+    from={"noreply@example.com"}
+    replyTo={"support@example.com"}   {/* optional */}
+/>
+```
+
+Place this inside the JSX returned by your config component in `webiny.config.tsx`, alongside other `<Api.*>` extensions.
+
+## Props Reference
+
+| Prop       | Type     | Required | Description                                    |
+| ---------- | -------- | -------- | ---------------------------------------------- |
+| `host`     | `string` | Yes      | SMTP server hostname                           |
+| `port`     | `number` | Yes      | SMTP server port (positive integer)            |
+| `user`     | `string` | Yes      | SMTP authentication username                   |
+| `password` | `string` | Yes      | SMTP authentication password — **use env var** |
+| `from`     | `string` | Yes      | Default sender address                         |
+| `replyTo`  | `string` | No       | Default reply-to address                       |
+
+`from` and `replyTo` are validated by the [`email-addresses`](https://www.npmjs.com/package/email-addresses) package against RFC 5322.
+
+## Full Example (`webiny.config.tsx`)
+
+```tsx
+import React from "react";
+import { Api, Admin, Core } from "@webiny/project-aws/api";
+
+const MyConfig = () => {
+  return (
+    <>
+      {/* ... other extensions ... */}
+
+      {/* Mailer: configure SMTP transport via code */}
+      <Api.Mailer.Smtp
+        host={"smtp.sendgrid.net"}
+        port={587}
+        user={"apikey"}
+        password={process.env.SENDGRID_API_KEY!}
+        from={"noreply@acme.com"}
+        replyTo={"support@acme.com"}
+      />
+    </>
+  );
+};
+```
+
+Add `SENDGRID_API_KEY=your-secret` to your `.env` file (never commit it).
+
+## Common Mistakes
+
+| Mistake                                                                                        | Fix                                                           |
+| ---------------------------------------------------------------------------------------------- | ------------------------------------------------------------- |
+| Hard-coding the password                                                                       | Use `process.env.SMTP_PASSWORD!`                              |
+| `process.env.SMTP_PASSWORD` undefined at build time → "expected string, received object" error | Ensure the env var is set before deploying                    |
+| `from`/`replyTo` value fails validation                                                        | Must be a valid RFC 5322 mailbox address                      |
+| Settings not taking effect                                                                     | Run `yarn webiny build api` after editing `webiny.config.tsx` |
+
+## Quick Reference
+
+```bash
+# After editing webiny.config.tsx, build the API
+yarn webiny build api
+```
+
+> **Note:** This command only works in a `dev` environment. For other environments, run `yarn webiny build api --env=YOUR_ENV` instead.
+
+```ts
+// Environment variable in .env
+SMTP_PASSWORD = your - smtp - password - here;
+```
+
+## Related Skills
+
+- `webiny-project-structure` — Where `webiny.config.tsx` lives and how extensions are structured
+- `webiny-local-development` — Running and deploying locally

package/skills/project-structure/SKILL.md

@@ -26,7 +26,6 @@ my-webiny-project/
 │   ├── global.css
 │   ├── index.html
 │   └── robots.txt
-├── eslint.config.js     # ESLint configuration
 ├── package.json         # Single package.json for the whole project
 ├── tsconfig.json        # Single TypeScript config
 ├── webiny.config.tsx    # Main configuration -- all extensions registered here

package/skills/webiny-sdk/SKILL.md

@@ -6,10 +6,14 @@ description: >
   Use this skill when the developer is building a Next.js, Vue, Node.js, or any external app
   that needs to fetch or write content to Webiny, set up the SDK, use the Result pattern,
   list/get/create/update/publish entries, filter and sort queries, use TypeScript generics
-  for type safety, work with the File Manager, list languages, trigger or monitor background tasks,
-  or create API keys programmatically.
+  for type safety, work with the File Manager, list languages, trigger or monitor background tasks, or create API keys programmatically.
   Covers read vs preview mode, the `values` wrapper requirement, correct method names,
-  the `fields` required parameter, and background task management via `sdk.tasks`.
+  and the `fields` required parameter, and background task management via `sdk.tasks`. Also covers common SDK errors and troubleshooting
+  — especially "Content model '<modelName>' not found" (which usually means the API key
+  lacks permission, not that the model is missing) and the Website Builder starter
+  pitfall of reusing NEXT_PUBLIC_WEBSITE_BUILDER_API_KEY for Headless CMS reads (that key
+  has no CMS permissions by default and needs either extension or replacement with a
+  CMS-scoped key).
 ---
 
 # Webiny SDK
@@ -499,6 +503,110 @@ Abort task:           webiny.tasks.abortTask({ id, message? })
 Filter logs by task:  webiny.tasks.listLogs({ where: { task: "id" } })
 ```
 
+## Troubleshooting
+
+The SDK's error messages describe the _server's_ view of the world, which sometimes hides
+the real cause. The patterns below have all bitten real projects — when you hit one of
+these errors, walk through the checklist before assuming the schema or framework is at
+fault.
+
+### `"Content model '<modelName>' not found."`
+
+This error literally means the **currently authenticated principal cannot see** a model
+with that ID — not necessarily that the model is missing. There are three things to
+check, in order:
+
+1. **Does the model actually exist?** Open Webiny Admin → Headless CMS → Models and
+   confirm the `modelId` matches exactly (case-sensitive — `productCategory`, not
+   `ProductCategory` or `product-category`).
+2. **Is the model published / not private?** A model that's only created in code but not
+   yet deployed (or that's defined as `.private(...)` instead of `.public(...)`) will not
+   be visible via the public Read API.
+3. **Does the API key have permission to read this model?** This is by far the most
+   common cause when the model clearly exists. The CMS returns "not found" rather than
+   "forbidden" on purpose, so an attacker can't probe the schema with an unauthorized
+   key. Open Settings → API Keys → _your key_ and verify it has at least:
+   - **Headless CMS** access (`cms.contentEntry`, `cms.contentModel`, etc.)
+   - The relevant model group selected (or "All groups")
+   - For private models: the matching `read` permission scope
+
+   Fix: grant the missing permission to the key, save, and retry. No code change needed.
+
+### Using the wrong API key (Website Builder key for Headless CMS reads)
+
+The Website Builder starter ships with `NEXT_PUBLIC_WEBSITE_BUILDER_API_KEY`. That key
+exists for the WB editor itself and, **by default, only has Website Builder permissions
+— it has no access to any Headless CMS models.** Reusing it to power
+`webiny.cms.listEntries(...)` from a Server Component is the most common cause of
+"Content model not found" in WB projects, because to the CMS the request looks just like
+an unauthorized one.
+
+You have two ways to fix this:
+
+1. **Recommended — use a separate, CMS-scoped API key.** Generate a new key in Webiny
+   Admin (Settings → API Keys) granting only the CMS permissions the public site needs
+   (typically read on the relevant model groups), expose it as a different env var, and
+   pass it into the SDK:
+
+   ```dotenv
+   # .env
+   NEXT_PUBLIC_WEBSITE_BUILDER_API_KEY=...    # for the WB editor only
+   WEBINY_CMS_READ_TOKEN=...                  # for SDK calls from Server Components
+   ```
+
+   ```typescript
+   // lib/webiny.ts
+   import { Webiny } from "@webiny/sdk";
+
+   export const webiny = new Webiny({
+     token: process.env.WEBINY_CMS_READ_TOKEN!, // ← NOT the WB key
+     endpoint: process.env.NEXT_PUBLIC_WEBSITE_BUILDER_API_HOST!,
+     tenant: process.env.NEXT_PUBLIC_WEBSITE_BUILDER_API_TENANT || "root"
+   });
+   ```
+
+   Keeping read and editor permissions on separate keys is also better for revocation
+   and the principle of least privilege.
+
+2. **Less recommended — extend the existing WB key with CMS permissions.** Open the WB
+   API key in Settings → API Keys and add the required Headless CMS permissions to it.
+   This works, but the same token now controls both the editor and public reads, which
+   makes scoping and rotation harder later.
+
+> **Heads-up:** `NEXT_PUBLIC_*` env vars are inlined into the client bundle by Next.js.
+> Anything you put behind that prefix is publicly visible. A read-only CMS token that's
+> scoped to public content is fine to expose; an editor or write-capable token is not —
+> for those, use a non-`NEXT_PUBLIC_` env var and only read it from Server Components or
+> Route Handlers.
+
+### Other quick-hit checks
+
+- **`endpoint` has a trailing slash.** The SDK appends `/graphql` itself, so a trailing
+  slash produces a malformed URL and every call fails. Strip it.
+- **`tenant` is wrong.** In multi-tenant setups, the default `"root"` tenant won't see
+  models defined under another tenant. Confirm the tenant ID matches the one that owns
+  the model.
+- **Wrong endpoint host.** WB projects sometimes have separate Admin and Read API
+  hostnames. The SDK should always point at the **Read** API (the public CloudFront
+  URL), not the Admin host.
+- **`fields` parameter omitted.** This throws at request time with a different message,
+  but if you see schema-level errors before any data comes back, double-check that every
+  call passes a non-empty `fields: [...]`.
+
+## Quick Reference
+
+```
+Install:          npm install @webiny/sdk
+Import:           import { Webiny } from "@webiny/sdk";
+Type import:      import type { CmsEntryData } from "@webiny/sdk";
+Initialize:       new Webiny({ token, endpoint, tenant })
+Result check:     result.isOk() -> result.value.data / result.error.message
+API endpoint:     yarn webiny info (in your Webiny project) -- NO trailing slash
+Preview mode:     pass preview: true to listEntries / getEntry
+fields required:  every method needs a fields: string[] array
+values wrapper:   createEntry/updateEntryRevision data must use { values: { ... } }
+```
+
 ## Related Skills
 
 - `webiny-api-cms-content-models` -- Define the models you query with the SDK

package/skills/website-builder/SKILL.md

@@ -5,10 +5,13 @@ description: >
   Building Website Builder editor components, theming, and CMS integration using
   @webiny/website-builder-nextjs. Use this skill when the developer wants to create editor
   components for the Website Builder, register components with createComponent, define
-  configurable inputs (text, number, boolean, color, select, file, slot, lexical),
-  set up component groups, customize the theme (CSS variables, createTheme, Tailwind bridge,
-  fonts), build Server Components that fetch CMS data, or understand the WB architecture
-  (Admin iframe + Next.js). Also use for anything related to the Website Builder starter kit.
+  configurable inputs (text, number, boolean, color, select, file/image, slot, lexical, object,
+  tags), type the component's props correctly (especially file/image inputs, which are objects
+  with { src, width, height, ... } and NOT plain strings, and lexical inputs which are
+  { html, state } objects), set up component groups, customize the theme (CSS variables,
+  createTheme, Tailwind bridge, fonts), build Server Components that fetch CMS data, or
+  understand the WB architecture (Admin iframe + Next.js). Also use for anything related to
+  the Website Builder starter kit.
 ---
 
 # Website Builder
@@ -167,6 +170,90 @@ Use a namespaced string: `"YourNamespace/ComponentName"`. Component names are st
 
 Each factory accepts: `name`, `label`, `description`, `defaultValue`, and type-specific options.
 
+### TypeScript prop types for each input
+
+The input factories above define what the editor sidebar shows. Separately, each input
+produces a value at runtime that's passed into your React component via `props.inputs`.
+**The runtime shape is not always a primitive** — the most important case is `file` /
+image inputs, which are objects, not strings. Typing them as `string` compiles but
+breaks as soon as you try to read `.src`, `.width`, etc.
+
+Use this table as the source of truth when you write the `ComponentProps<T>` generic for
+a component. These shapes come from the actual SDK usage (see e.g.
+`@webiny/website-builder-nextjs/editorComponents/Image.d.ts` in the project's
+`node_modules` for the canonical file-input shape).
+
+| Input factory         | Type of `inputs.<name>` in the component                                                                                                                       |
+| --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `createTextInput`     | `string`                                                                                                                                                       |
+| `createLongTextInput` | `string`                                                                                                                                                       |
+| `createNumberInput`   | `number`                                                                                                                                                       |
+| `createBooleanInput`  | `boolean`                                                                                                                                                      |
+| `createColorInput`    | `string` (CSS color value, e.g. `"#4632f5"` or `"var(--wb-theme-color-primary)"`)                                                                              |
+| `createDateInput`     | `string` (ISO-8601, e.g. `"2026-04-16T14:06:00.000Z"`)                                                                                                         |
+| `createSelectInput`   | `string` (the `value` of the chosen option)                                                                                                                    |
+| `createRadioInput`    | `string` (the `value` of the chosen option)                                                                                                                    |
+| `createTagsInput`     | `string[]`                                                                                                                                                     |
+| `createFileInput`     | `{ id: string; name: string; size: number; mimeType: string; src: string; width: number; height: number }` — **object, NOT a string.** Use `.src` for the URL. |
+| `createLexicalInput`  | `{ html?: string; state?: string }` — render with `<div dangerouslySetInnerHTML={{ __html: inputs.<name>.html ?? "" }} />`                                     |
+| `createObjectInput`   | An object literal matching the shape of its nested `fields` (e.g. `{ street: string; city: string; zip: string }`)                                             |
+| `createSlotInput`     | `React.ReactNode` (rendered children). With `list: true`, the factory wraps inside the field value — see Grid pattern below.                                   |
+
+#### List inputs (`list: true`)
+
+When an input is declared with `list: true` (either directly, or via a factory like
+`createTagsInput` which does it internally), the type in the component becomes an array
+of the base type:
+
+- `createFileInput({ list: true })` → `Array<{ id; name; src; … }>`
+- `createObjectInput({ name: "rows", list: true, fields: [...] })` → an array of objects
+  matching the `fields` shape.
+- `createSlotInput({ name: "columns", list: true, ... })` → an array of `{ children: React.ReactNode }` (see the Grid component in `@webiny/website-builder-react` for the reference pattern).
+
+#### Worked example: image + rich-text component
+
+```tsx
+import React from "react";
+import type { ComponentProps } from "@webiny/website-builder-nextjs";
+
+interface FeatureCardInputs {
+  headline: string;
+  body: { html?: string };
+  image: {
+    id: string;
+    name: string;
+    size: number;
+    mimeType: string;
+    src: string;
+    width: number;
+    height: number;
+  };
+  tags: string[];
+}
+
+export function FeatureCard({
+  inputs: { headline, body, image, tags }
+}: ComponentProps<FeatureCardInputs>) {
+  return (
+    <article>
+      <h3>{headline}</h3>
+      {image?.src && (
+        <img src={image.src} width={image.width} height={image.height} alt={headline} />
+      )}
+      {body?.html && <div dangerouslySetInnerHTML={{ __html: body.html }} />}
+      <ul>
+        {tags.map(tag => (
+          <li key={tag}>{tag}</li>
+        ))}
+      </ul>
+    </article>
+  );
+}
+```
+
+Note how `image` is typed as the full object, not a plain `string` — otherwise the
+component would compile but blow up at runtime when it tried to read `image.src`.
+
 ## Component Groups
 
 Groups organize the editor's component palette: