@eventcatalog/core 3.34.0 → 3.35.1

package/dist/docs/development/ask-your-architecture/04-skills/01-introduction.md

@@ -0,0 +1,40 @@
+---
+sidebar_position: 1
+keywords:
+- AI Skills
+- Claude Code
+- documentation generation
+sidebar_label: Introduction
+title: AI Skills
+description: Pre-built AI skills to help you document your architecture with EventCatalog
+---
+
+EventCatalog Skills are pre-built instructions that teach AI agents how to work with your EventCatalog project. Install a skill and your AI agent gains the ability to generate correct documentation, following EventCatalog conventions and best practices.
+
+Skills work with any AI coding agent that supports the skills format (e.g. [Claude Code](https://claude.ai/code)).
+
+## Why use skills?
+
+When you ask an AI agent to generate EventCatalog documentation, it doesn't know about EventCatalog's frontmatter format, folder structure, or component conventions. Skills solve this by providing the agent with structured instructions and reference material.
+
+With skills installed, you can ask your agent things like:
+
+- "Document my OrderService that receives OrderCreated events and sends OrderConfirmed events"
+- "Create a Payments domain with a PaymentService, PaymentProcessed event, and ProcessPayment command"
+- "Look at my src/ directory and generate EventCatalog documentation for the services and events you find"
+- "Document the checkout flow from cart submission through payment processing to order confirmation"
+
+The agent will generate properly formatted `index.mdx` files with correct frontmatter, schemas, and visualizations.
+
+## Available skills
+
+| Skill | Description |
+|-------|-------------|
+| [Catalog Documentation Creator](https://github.com/event-catalog/skills) | Generates EventCatalog documentation files (services, events, commands, queries, domains, flows, channels, containers) with correct frontmatter, folder structure, and best practices. |
+| [Flow Wizard](https://github.com/event-catalog/skills) | Guides you through documenting a business flow step by step in a conversational session, cross-referencing your existing catalog resources to link services, events, and commands automatically. |
+
+## Getting started
+
+Head to the [installation guide](/docs/development/ask-your-architecture/skills/installation) to add skills to your project.
+
+**Source code:** [github.com/event-catalog/skills](https://github.com/event-catalog/skills)

package/dist/docs/development/ask-your-architecture/04-skills/02-installation.md

@@ -0,0 +1,60 @@
+---
+sidebar_position: 2
+keywords:
+- AI Skills
+- installation
+sidebar_label: Installation
+title: Installing AI Skills
+description: How to install EventCatalog AI skills for your AI coding agent
+---
+
+## CLI install (recommended)
+
+Use [npx skills](https://github.com/vercel-labs/skills) to install skills directly into your project:
+
+```bash
+# Install all EventCatalog skills
+npx skills add event-catalog/skills
+
+# Install a specific skill
+npx skills add event-catalog/skills --skill catalog-documentation-creator
+```
+
+This copies the skill files into your project's `.claude/skills/` directory where your AI agent can access them.
+
+## Clone and copy
+
+Clone the repository and copy the skills you need:
+
+```bash
+git clone https://github.com/event-catalog/skills.git
+cp -r skills/skills/catalog-documentation-creator .claude/skills/
+```
+
+## Git submodule
+
+Add as a submodule for easy updates:
+
+```bash
+git submodule add https://github.com/event-catalog/skills.git .claude/skills/eventcatalog
+```
+
+When new skills are released, pull updates with:
+
+```bash
+git submodule update --remote
+```
+
+## Fork and customize
+
+Fork the repository and tailor skills to your team's conventions:
+
+1. Fork [event-catalog/skills](https://github.com/event-catalog/skills) on GitHub
+2. Modify skills to match your naming conventions, ownership patterns, and schema formats
+3. Install from your fork:
+
+```bash
+npx add-skill https://github.com/YOUR_ORG/eventcatalog-skills
+```
+
+This is useful when your team has specific conventions for IDs, owners, or folder structures that differ from the defaults.

package/dist/docs/development/ask-your-architecture/04-skills/_category_.json

@@ -0,0 +1,11 @@
+{
+  "label": "Skills",
+  "position": 4,
+  "collapsible": true,
+  "collapsed": true,
+  "link": {
+    "type": "generated-index",
+    "slug": "/development/ask-your-architecture/skills",
+    "description": "Pre-built AI skills for generating EventCatalog documentation"
+  }
+}

package/dist/docs/development/ask-your-architecture/05-slack-integration/01-introduction.md

@@ -0,0 +1,63 @@
+---
+sidebar_position: 1
+keywords:
+- Slack Bot
+- Slack Integration
+sidebar_label: Introduction
+title: Slack integration
+description: Query architecture documentation directly from Slack
+---
+
+import PlanBanner from '@site/src/components/MDX/PlanBanner';
+
+<PlanBanner plan="Scale" />
+
+The EventCatalog Slack Bot connects to your EventCatalog MCP server, allowing teams to query architecture documentation directly from Slack. Ask questions about events, services, domains, and schemas without leaving your workspace.
+
+The slack bot is self hosted, you own your data and deployment.
+
+<div className="flex justify-center items-center gap-4 flex-col">
+  <img src="/img/slack.png" alt="EventCatalog Slack Bot" className="rounded-lg" style={{ width: '30%', height: 'auto' }} />
+  <span className="text-center text-sm text-gray-500">Example of the EventCatalog Slack Bot in action asking about the OrderCreated event</span>
+</div>
+
+## How it works
+
+1. You configure the bot with your own AI provider and model (e.g. Anthropic, OpenAI, Google)
+1. Users @mention the bot or post in dedicated channels
+2. The bot queries your EventCatalog MCP server
+3. AI-powered responses appear in threads to keep channels organized
+
+## Key features
+
+- **@Mention anywhere** - Add the bot to any channel and ask questions
+- **Dedicated channels** - Create auto-reply channels for architecture questions
+- **Multiple AI providers** - Works with Anthropic, OpenAI, or Google
+- **Self-hosted** - Your data stays private, you control your data and deployment
+- **Socket Mode** - No public URL or webhooks needed
+- **Custom tools support** - Bring your own integrations for real-time data
+
+## Custom tools
+
+The Slack bot supports [custom tools](/docs/development/ask-your-architecture/eventcatalog-assistant/bring-your-own-tools) defined in your `eventcatalog.chat.js` file. This means you can bring real-time data into your Slack conversations:
+
+- Query production metrics from Datadog or Prometheus
+- Check service health and uptime
+- Look up on-call engineers from PagerDuty
+- Fetch queue depths from Kafka
+- Any custom integration your team needs
+
+Custom tools work automatically - the AI decides when to use them based on user questions. Ask "who is on-call for OrderService?" and get live data directly in Slack.
+
+## Prerequisites
+
+- EventCatalog instance (with configured MCP server) running in [SSR mode](/docs/development/deployment/build-ssr-mode)
+- [EventCatalog Scale license](https://eventcatalog.cloud)
+- Slack workspace with app creation permissions
+- API key for your chosen AI provider
+
+## Repository
+
+The EventCatalog Slack Bot is open source:
+
+[github.com/event-catalog/eventcatalog-slack-bot](https://github.com/event-catalog/eventcatalog-slack-bot)

package/dist/docs/development/ask-your-architecture/05-slack-integration/02-slack-app-setup.md

@@ -0,0 +1,154 @@
+---
+sidebar_position: 2
+keywords:
+- Slack Bot
+- Slack App
+sidebar_label: Slack app setup
+title: Slack app setup
+description: Create and configure your Slack app
+---
+
+import PlanBanner from '@site/src/components/MDX/PlanBanner';
+
+<PlanBanner plan="Scale" />
+
+Create a Slack app to enable the EventCatalog bot in your workspace. You can create the app using a manifest (recommended) or manually configure all settings.
+
+## Create from manifest (recommended)
+
+The fastest way to get started. The manifest automatically configures all required permissions and settings.
+
+### Steps
+
+1. Navigate to [api.slack.com/apps](https://api.slack.com/apps)
+2. Click **Create New App** → **From an app manifest**
+3. Select your workspace and click **Next**
+4. Choose **YAML** and paste this manifest:
+
+```yaml
+display_information:
+  name: EventCatalog Bot
+  description: Query your EventCatalog directly from Slack
+  background_color: "#000000"
+
+features:
+  bot_user:
+    display_name: EventCatalog
+    always_online: true
+
+oauth_config:
+  scopes:
+    bot:
+      - app_mentions:read
+      - chat:write
+      - reactions:read
+      - reactions:write
+      - channels:history
+
+settings:
+  event_subscriptions:
+    bot_events:
+      - app_mention
+      - message.channels
+  interactivity:
+    is_enabled: false
+  org_deploy_enabled: false
+  socket_mode_enabled: true
+  token_rotation_enabled: false
+```
+
+5. Click **Next**, review the summary, and click **Create**
+
+### Get credentials
+
+After creating the app, collect three credentials needed to run the bot.
+
+#### App-Level Token
+
+1. Go to **Basic Information** → **App-Level Tokens**
+2. Click **Generate Token and Scopes**
+3. Name: `socket-mode-token`
+4. Add scope: `connections:write`
+5. Click **Generate** and copy the token (starts with `xapp-`)
+6. Save this as `SLACK_APP_TOKEN`
+
+#### Bot Token
+
+1. Go to **OAuth & Permissions**
+2. Click **Install to Workspace**
+3. Review permissions and click **Allow**
+4. Copy the **Bot User OAuth Token** (starts with `xoxb-`)
+5. Save this as `SLACK_BOT_TOKEN`
+
+#### Signing Secret
+
+1. Go to **Basic Information** → **App Credentials**
+2. Copy the **Signing Secret**
+3. Save this as `SLACK_SIGNING_SECRET`
+
+<details>
+<summary>Setup Slack app manually</summary>
+
+If you prefer to configure settings yourself, follow these steps.
+
+### Create the app
+
+1. Navigate to [api.slack.com/apps](https://api.slack.com/apps)
+2. Click **Create New App** → **From scratch**
+3. Name your app (e.g., "EventCatalog Bot") and select your workspace
+4. Click **Create App**
+
+### Enable Socket Mode
+
+1. Click **Socket Mode** in the left sidebar
+2. Toggle **Enable Socket Mode** to On
+3. Create an App-Level Token when prompted:
+   - Name: `socket-mode-token`
+   - Scope: `connections:write`
+4. Click **Generate**
+5. Copy the token (starts with `xapp-`) - this is `SLACK_APP_TOKEN`
+
+### Configure permissions
+
+1. Click **OAuth & Permissions** in the left sidebar
+2. Scroll to **Scopes** → **Bot Token Scopes**
+3. Add these scopes:
+   - `app_mentions:read` - Receive @mention events
+   - `chat:write` - Send messages
+   - `reactions:read` - Read reactions
+   - `reactions:write` - Add and remove reactions
+   - `channels:history` - Read public channel messages
+
+### Enable events
+
+1. Click **Event Subscriptions** in the left sidebar
+2. Toggle **Enable Events** to On
+3. Expand **Subscribe to bot events**
+4. Add these events:
+   - `app_mention`
+   - `message.channels`
+
+### Install the app
+
+1. Click **OAuth & Permissions** in the left sidebar
+2. Click **Install to Workspace**
+3. Review permissions and click **Allow**
+4. Copy the **Bot User OAuth Token** (starts with `xoxb-`) - this is `SLACK_BOT_TOKEN`
+
+### Get signing secret
+
+1. Click **Basic Information** in the left sidebar
+2. Scroll to **App Credentials**
+3. Copy the **Signing Secret** - this is `SLACK_SIGNING_SECRET`
+
+</details>
+
+## Optional: Private channels and DMs
+
+By default, the bot only reads thread context in public channels. To enable thread context in private channels and DMs, add these additional scopes:
+
+- `groups:history` - Private channels
+- `im:history` - Direct messages
+- `mpim:history` - Group DMs
+
+After adding scopes, reinstall the app to your workspace.

package/dist/docs/development/ask-your-architecture/05-slack-integration/03-installation.md

@@ -0,0 +1,169 @@
+---
+sidebar_position: 3
+keywords:
+- Slack Bot
+- Installation
+sidebar_label: Installation
+title: Installation
+description: Install and configure the bot
+---
+
+import PlanBanner from '@site/src/components/MDX/PlanBanner';
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+<PlanBanner plan="Scale" />
+
+Install the EventCatalog Slack Bot locally or deploy it to your infrastructure. The bot runs as a long-lived process that maintains a connection to Slack.
+
+## Install locally
+
+### Clone repository
+
+```bash
+git clone https://github.com/event-catalog/eventcatalog-slack-bot.git
+cd eventcatalog-slack-bot
+```
+
+### Install dependencies
+
+<Tabs>
+  <TabItem value="npm" label="npm" default>
+    ```bash
+    npm install
+    ```
+  </TabItem>
+  <TabItem value="pnpm" label="pnpm">
+    ```bash
+    pnpm install
+    ```
+  </TabItem>
+</Tabs>
+
+### Configure environment
+
+Create a `.env` file with your credentials:
+
+```bash
+# EventCatalog Scale License (Required)
+EVENTCATALOG_SCALE_LICENSE_KEY=XXXX-XXXX-XXXX-XXXX-XXXX-XXXX
+
+# Slack Credentials (Required)
+SLACK_BOT_TOKEN=xoxb-...
+SLACK_APP_TOKEN=xapp-...
+SLACK_SIGNING_SECRET=...
+
+# AI Provider (at least one required)
+ANTHROPIC_API_KEY=sk-ant-...
+# OPENAI_API_KEY=sk-...
+# GOOGLE_GENERATIVE_AI_API_KEY=...
+```
+
+### Create configuration
+
+Create `eventcatalog-bot.config.ts`:
+
+```typescript
+export default {
+  eventCatalog: {
+    url: 'http://localhost:3000',
+    // Optional: Add authentication headers
+    // headers: {
+    //   'Authorization': 'Bearer your-token',
+    // },
+  },
+  ai: {
+    provider: 'anthropic', // 'anthropic' | 'openai' | 'google'
+    // model: 'claude-sonnet-4-20250514', // Optional: override default model
+    maxSteps: 5,
+    temperature: 0.4,
+  },
+  slack: {
+    // Optional: Channel IDs for auto-reply (bot responds to all messages)
+    autoReplyChannels: [],
+    // Optional: Custom icon URL for bot messages
+    icon: 'https://www.eventcatalog.dev/img/logo.png',
+    // Optional: Custom username for bot messages
+    username: 'EventCatalog',
+  },
+};
+```
+
+### Start the bot
+
+<Tabs>
+  <TabItem value="npm" label="npm" default>
+    ```bash
+    npm run dev
+    ```
+  </TabItem>
+  <TabItem value="pnpm" label="pnpm">
+    ```bash
+    pnpm dev
+    ```
+  </TabItem>
+</Tabs>
+
+Or with a custom config path:
+
+<Tabs>
+  <TabItem value="npm" label="npm" default>
+    ```bash
+    npm run dev -- --config ./my-config.ts
+    ```
+  </TabItem>
+  <TabItem value="pnpm" label="pnpm">
+    ```bash
+    pnpm dev --config ./my-config.ts
+    ```
+  </TabItem>
+</Tabs>
+
+## Configuration reference
+
+### eventCatalog
+
+| Option | Type | Required | Description |
+|--------|------|----------|-------------|
+| `url` | string | Yes | URL of your EventCatalog instance |
+| `headers` | object | No | Authentication headers if needed |
+
+### ai
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `provider` | string | Required | AI provider: `anthropic`, `openai`, or `google` |
+| `model` | string | Provider default | Model to use (see [supported models](#supported-ai-providers)) |
+| `maxSteps` | number | 5 | Maximum tool-calling steps (1-20) |
+| `temperature` | number | 0.4 | AI temperature (0-2) |
+
+### slack
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `autoReplyChannels` | string[] | [] | Channel IDs where bot auto-replies to all messages |
+| `icon` | string | EventCatalog logo | Custom icon URL for bot messages |
+| `username` | string | 'EventCatalog' | Custom display name for bot messages |
+
+## Supported AI providers
+
+| Provider | Environment Variable | Default Model |
+|----------|---------------------|---------------|
+| Anthropic | `ANTHROPIC_API_KEY` | `claude-sonnet-4-20250514` |
+| OpenAI | `OPENAI_API_KEY` | `gpt-4o` |
+| Google | `GOOGLE_GENERATIVE_AI_API_KEY` | `gemini-2.0-flash` |
+
+You can override the default model in your configuration. For a full list of available models, see the [Vercel AI SDK Providers documentation](https://ai-sdk.dev/providers/ai-sdk-providers).
+
+```typescript
+ai: {
+  provider: 'anthropic',
+  model: 'claude-opus-4-20250514', // Use a different model
+}
+```
+
+## License key
+
+Get your EventCatalog Scale license key from [eventcatalog.cloud](https://eventcatalog.cloud). A 14-day free trial is available.
+
+The license key must be set as the `EVENTCATALOG_SCALE_LICENSE_KEY` environment variable.