docs(): Introduce docs platform (#11643)

Author: scopsy

docs/.mintignore

@@ -0,0 +1,10 @@
+# Mintlify automatically ignores these files and directories:
+# .git, .github, .claude, .agents, .idea, node_modules,
+# README.md, LICENSE.md, CHANGELOG.md, CONTRIBUTING.md
+
+# Draft content
+drafts/
+*.draft.mdx
+
+# Non-documentation files
+skills-lock.json

docs/AGENTS.md

@@ -0,0 +1,33 @@
+> **First-time setup**: Customize this file for your project. Prompt the user to customize this file for their project.
+> For Mintlify product knowledge (components, configuration, writing standards),
+> install the Mintlify skill: `npx skills add https://mintlify.com/docs`
+
+# Documentation project instructions
+
+## About this project
+
+- This is a documentation site built on [Mintlify](https://mintlify.com)
+- Pages are MDX files with YAML frontmatter
+- Configuration lives in `docs.json`
+- Use the Mintlify MCP server, `https://mcp.mintlify.com`, to edit content and settings via MCP
+- Use the Mintlify docs MCP server, `https://www.mintlify.com/docs/mcp`, to query information about using Mintlify via MCP
+
+## Terminology
+
+{/* Add product-specific terms and preferred usage */}
+{/* Example: Use "workspace" not "project", "member" not "user" */}
+
+## Style preferences
+
+{/* Add any project-specific style rules below */}
+
+- Use active voice and second person ("you")
+- Keep sentences concise — one idea per sentence
+- Use sentence case for headings
+- Bold for UI elements: Click **Settings**
+- Code formatting for file names, commands, paths, and code references
+
+## Content boundaries
+
+{/* Define what should and shouldn't be documented */}
+{/* Example: Don't document internal admin features */}

docs/README.md

@@ -0,0 +1,55 @@
+# Mintlify Starter Kit
+
+Use the starter kit to get your docs deployed and ready to customize.
+
+Click the green **Use this template** button at the top of this repo to copy the Mintlify starter kit. The starter kit contains examples with
+
+- Guide pages
+- Navigation
+- Customizations
+- API reference pages
+- Use of popular components
+
+**[Follow the full quickstart guide](https://starter.mintlify.com/quickstart)**
+
+## AI-assisted writing
+
+Set up your AI coding tool to work with Mintlify:
+
+```bash
+npx skills add https://mintlify.com/docs
+```
+
+This command installs Mintlify's documentation skill for your configured AI tools like Claude Code, Cursor, Windsurf, and others. The skill includes component reference, writing standards, and workflow guidance.
+
+See the [AI tools guides](/ai-tools) for tool-specific setup.
+
+## Development
+
+Install the [Mintlify CLI](https://www.npmjs.com/package/mint) to preview your documentation changes locally. To install, use the following command:
+
+```
+npm i -g mint
+```
+
+Run the following command at the root of your documentation, where your `docs.json` is located:
+
+```
+mint dev
+```
+
+View your local preview at `http://localhost:3000`.
+
+## Publishing changes
+
+Install our GitHub app from your [dashboard](https://dashboard.mintlify.com/settings/organization/github-app) to propagate changes from your repo to your deployment. Changes are deployed to production automatically after pushing to the default branch.
+
+## Need help?
+
+### Troubleshooting
+
+- If your dev environment isn't running: Run `mint update` to ensure you have the most recent version of the CLI.
+- If a page loads as a 404: Make sure you are running in a folder with a valid `docs.json`.
+
+### Resources
+- [Mintlify documentation](https://mintlify.com/docs)

docs/agents.mdx

@@ -0,0 +1,82 @@
+---
+title: "Overview"
+description: "Connect your AI agents to chat platforms and communication channels with Novu's Agent Communication Infrastructure (ACI)."
+icon: "plug"
+---
+
+
+Novu Connect is built on the [Agent Communication Infrastructure (ACI)](/agents/get-started/what-is-aci), the infrastructure layer that handles how agents communicate, so your agents can hold real conversations across messaging platforms with users, on the channels they already use.
+
+ACI draws a hard boundary between two concerns:
+
+* **Communication infrastructure**: Webhook ingestion, message normalization, conversation state, identity resolution, and delivery across channels. ACI owns this layer.
+
+* **Agent intelligence**: Your LLM, prompts, tools, managed agent configuration, business logic, or custom runtime. You own this layer.
+
+The result is that you can create an agent once and make it available across connected channels. ACI routes messages in, sends replies out, preserves conversation context, and removes the need to rebuild communication plumbing for every platform.
+
+<Card href="/agents/get-started/what-is-aci" title="What is ACI?" icon="circle-question-mark">
+  Learn how ACI works, what it solves, and where it draws the line between infrastructure and intelligence.
+</Card>
+
+## Connect the agent
+
+Novu Connect accepts two kinds of [agent brains](/platform/additional-resources/glossary#agent-brain). You choose how you want to bring it.
+
+### External connectors
+
+Delegate the agent logic entirely to a managed platform such as Claude Managed Agents. You configure the agent's behavior, system prompt, tools, skills, and MCP servers and the platform runs the intelligence.
+
+<Card href="/agents/managed-agent/overview" title="Managed agent" icon="sparkles">
+  Set up a fully managed agent powered by Claude. No custom server code required.
+</Card>
+
+### Custom code
+
+Write your own agent logic. Handle events, call any LLM or API, and reply using the Novu agent SDK. Compatible with AI SDK, LangChain, OpenAI SDK, and any custom code of your choosing.
+
+<Card href="/agents/custom-code-agent/quickstart" title="Custom code agent" icon="square-code">
+  Build an agent with full control over logic, tools, and event handling.
+</Card>
+
+## How a conversation flows
+
+ACI turns channel-specific messages into a standard communication flow between the user and your agent brain.
+
+1. A user sends a message on Slack, Teams, WhatsApp, or another supported channel.
+2. Novu ingests the webhook, normalizes the event, and resolves the user's identity.
+3. Novu sends the event to your agent brain with full conversation context.
+4. Your agent processes the message and responds. 
+5. Novu delivers the reply back to the correct platform thread.
+6. Novu persists the conversation and makes it visible in the Connect dashboard.
+
+## Start building
+
+<Card href="/agents/managed-agent/quickstart" title="Quickstart" icon="zap">
+  Follow the quickstart to create your first agent, connect a Slack provider, and send your first message in under 5 minutes.
+</Card>
+
+## Learn more
+
+Explore the full documentation to go deeper on any part of Novu Connect.
+
+<Columns cols={2}>
+  <Card href="/agents/get-started/what-is-aci" title="What is ACI?" icon="circle-question-mark">
+    Understand the infrastructure layer and the problem it solves.
+  </Card>
+  <Card href="/agents/get-started/mental-model" title="Mental model" icon="brain-circuit">
+    How inbound messages flow from a channel through to your agent and back.
+  </Card>
+  <Card href="/agents/get-started/agents-and-providers" title="Agents and providers" icon="blocks">
+    How agents and provider connections work, and which channels are supported.
+  </Card>
+  <Card href="/agents/managed-agent/overview" title="Managed agent" icon="sparkles">
+    Configure a fully-managed agent powered by Claude.
+  </Card>
+  <Card href="/agents/custom-code-agent/quickstart" title="Custom code quickstart" icon="zap">
+    Connect a Slack provider and send your first message in under five minutes.
+  </Card>
+  <Card href="/agents/conversations" title="Conversation observability" icon="messages-square">
+    Monitor, inspect, and manage live agent conversations.
+  </Card>
+</Columns>

docs/agents/conversations.mdx

@@ -0,0 +1,49 @@
+---
+title: "Agent Conversations"
+description: 'View agent conversations, their history, lifecycle, and observability in the Novu dashboard.'
+icon: "messages-square"
+---
+
+Novu provides full observability for agent conversations across both managed agents and custom code agents. You can view and manage conversations in the Novu dashboard. Go to the Activity Feed page and switch to the **Agent Conversations** tab.
+
+## Conversation lifecycle
+
+Every agent conversation follows the same state machine, regardless of agent type:
+
+![Agent conversation lifecycle](/images/agents/conversations/lifecycle.png)
+
+| State | What it means |
+| --- | --- |
+| **Active** | The conversation is ongoing. Messages increment the count, metadata can be updated, and the last activity timestamp is refreshed. |
+| **Resolved** | The conversation has been closed. For custom code agents, this happens when the handler calls `ctx.resolve()` and the `onResolve` handler fires. For managed agents, the platform can resolve the conversation based on its reasoning. An optional summary is stored. |
+| **Reopened** | If a user sends a new message after the conversation was resolved, it automatically reopens and becomes active again. |
+
+## What the dashboard shows
+
+Navigate to your agent's detail page to see all conversations, their status, and a complete timeline of activity.
+
+<video autoPlay loop muted playsInline src="/images/agents/conversations/manage-agent-conversations.mp4" />
+
+- **Conversation list**: all conversations for the agent, with status (active / resolved), last message preview, message count, and last activity timestamp.
+- **Full message history**: every message exchanged between the user and the agent, including rich content (cards, markdown, files).
+- **Metadata**: key-value pairs stored on the conversation. In custom code agents, these are set via `ctx.metadata.set()`. In managed agents, the platform may store internal state.
+- **Signal activity**: a log of signals fired during the conversation (metadata changes, workflow triggers, resolve events). This applies to custom code agents that use signals.
+- **Tool use activity**: for managed agents, the dashboard shows which tools the agent called during each turn, including built-in tools and MCP servers.
+- **Participant details**: which subscribers and platform users are part of each conversation, with identity resolution status.
+- **Platform context**: which provider and thread the conversation is happening on.
+
+## Supported platforms
+
+Both managed agents and custom code agents support the same set of chat providers:
+
+| Platform | Status | Notes |
+| --- | --- | --- |
+| Slack | Available | Text, markdown, files, interactive cards, reactions, typing indicators. File uploads require the `files:write` bot scope. |
+| Microsoft Teams | Available | Text, markdown, files, and cards via Bot Framework. Dashboard includes a guided onboarding flow with one-click app package download. |
+| WhatsApp | Available | Text, markdown, interactive buttons. Inbound media is surfaced via attachments; outbound file attachments are not supported yet. |
+| Email | Available | Text, markdown, files, interactive cards, emoji reactions (Gmail only). |
+| Telegram | Available | Text, markdown, files, reactions, typing indicators. |
+
+<Note>
+  Platform capabilities might vary. For example, typing indicators are only shown on platforms that support them, and message editing depends on platform adapter support.
+</Note>

docs/agents/custom-code-agent/concepts.mdx

@@ -0,0 +1,132 @@
+---
+title: "Concepts"
+description: 'Entities, lifecycle, and handler building blocks for a custom code agent with Novu.'
+icon: "brain"
+---
+
+
+These are the ideas behind Novu for Agents (Agent Communication Infrastructure, or ACI). You write handler code; Novu handles providers, delivery, and conversation state.
+
+## Inbound flow
+
+Users can message your agent, and your agent can message back. When someone interacts on a connected platform, Novu resolves identity and conversation state, forwards a context object to your server, then delivers your reply to the right thread.
+
+![Inbound message flow](/images/agents/custom-code-agent/concept-inbound-flow.png)
+
+| Step | What Novu does |
+| --- | --- |
+| **Receive and identify** | Normalizes the platform webhook. Maps the platform user (for example a Slack user ID) to a Novu subscriber when possible. Known users get full profiles; unknown users stay anonymous until resolved. |
+| **Load conversation** | Creates or loads the conversation for that thread. Assembles message history, metadata, and subscriber data into one context object. |
+| **Your handler** | Calls your code with message, history, subscriber, and platform details. You run your LLM or business logic and call `ctx.reply()`. |
+| **Deliver and persist** | Sends the reply to the provider thread, stores it in history, and logs activity in the dashboard. |
+
+Your server never calls Slack, Teams, or email APIs directly. It gets a context object and returns a reply; Novu handles the rest.
+
+## Key entities
+
+### Agent
+
+The dashboard object that connects your code to one or more chat providers. Each agent has a name, identifier, and event handlers.
+
+It does not define your model, prompts, tools, or business rules. It is the bridge to the app where that logic lives. The provider is where the user chats; the agent is how your app responds.
+
+### Provider connection
+
+Credentials and config that link an agent to a platform (Slack, Teams, WhatsApp, email, and others).
+
+Setup and capabilities differ per provider (reactions, typing indicators, attachments, cards, message edits, and so on). Novu normalizes inbound events before your handler runs, so you work with one interface instead of provider-specific webhooks. Your handler code stays provider-agnostic; Novu translates outbound replies per platform.
+
+### Conversation
+
+The stateful thread for a chat. Novu creates or loads it when a message arrives. It holds history, metadata, participants, status, and platform context.
+
+The agent is a participant, not the conversation itself (relevant when you read threads in the dashboard). A Slack thread, email thread, or similar maps to one Novu conversation.
+
+**Lifecycle:** **Active** from the first message until resolved. **Resolved** when the agent emits the resolve signal (`onResolve` runs; optional summary stored). **Reopened** automatically if the user messages again after resolution.
+
+### Participants and identity
+
+Novu maps platform users to subscribers when it can:
+
+- **Match found:** handler gets subscriber ID, name, email, and related fields.
+- **No match:** user is tracked as a platform user; write handlers that tolerate missing subscriber data.
+
+Later resolution upgrades them to a full subscriber. Identity is provider-aware (Slack user ID vs email sender, and so on) but can resolve to one subscriber record. Use it for personalization, account lookup, and escalation rules.
+
+## Bridge surface
+
+The same handler API applies no matter which provider sent the event or which model you use.
+
+### Event handlers
+
+| Handler | When it runs | Typical use |
+| --- | --- | --- |
+| `onMessage` | User sends a message | Process text and reply |
+| `onAction` | User clicks a button or selects from a card | Forms, buttons, dropdowns |
+| `onReaction` | User adds or removes a reaction | Feedback, follow-ups |
+| `onResolve` | Conversation marked resolved | Cleanup, analytics, summary |
+
+Handlers connect Novu's delivery layer to your app. An `onMessage` handler might pass context to an LLM and return a reply through Novu.
+
+### Context object
+
+Each handler receives a context with some or all of:
+
+- Incoming message
+- Conversation state and metadata
+- Resolved subscriber (when available)
+- Recent history
+- Provider and platform details (thread, channel IDs)
+- Methods to reply, set metadata, trigger workflows, or resolve
+
+That object is the only interface your code needs. You do not integrate Slack, Teams, WhatsApp, or email separately in the handler.
+
+### Replies vs signals
+
+**Replies** are user-visible messages: plain text, markdown with files, or interactive cards (buttons, dropdowns, links, inputs). Card interactions fire `onAction` with `actionId` and value.
+
+**Signals** update state without necessarily sending another chat message:
+
+| Signal | What it does |
+| --- | --- |
+| Metadata | Key-value data on the conversation, persists across turns |
+| Trigger | Starts a Novu workflow from the thread |
+| Resolve | Marks the conversation resolved, optional summary |
+
+Replies talk to the user; signals update the system around the conversation. One handler turn can reply, set metadata, trigger a workflow, and resolve.
+
+Signals queue in memory and batch with your next `ctx.reply()` in one request. If the handler exits without calling `ctx.reply()`, pending signals still send.
+
+## Conversations and workflows
+
+Conversations and Novu workflows share the same account:
+
+- **Conversation to workflow:** User asks in Slack for a report by email; handler calls `ctx.trigger()` and an existing workflow sends the email.
+- **Workflow to conversation:** User replies to a digest email; that reply opens a new agent conversation.
+
+ACI extends Novu's workflow system; it does not replace it. Transactional workflows and open-ended chat work together on one platform.
+
+## Full flow (example: Slack)
+
+1. User messages the agent in Slack.
+2. Novu receives the event via the provider connection.
+3. Novu maps the thread to a conversation and resolves the subscriber when possible.
+4. Novu calls `onMessage` with the context object.
+5. Your handler passes message and history to your agent logic.
+6. Your logic decides the next action.
+7. Handler sends a reply, signals, or both.
+8. Novu posts the reply to the Slack thread.
+9. Novu records messages, participants, metadata, signals, and status.
+
+The same handler code works on every connected provider; adding a provider does not require changing agent logic.
+
+## Next steps
+
+<Columns cols={2}>
+  <Card icon="house" href="/agents/custom-code-agent/quickstart" title="Quickstart">
+    Create an agent, connect Slack, and get a reply in-thread.
+  </Card>
+  <Card icon="brain" href="/agents/custom-code-agent/connect-your-first-agent" title="Connect your first agent">
+    Walk through a full support-bot handler file.
+  </Card>
+</Columns>