[DO NOT MERGE] feat: agents documentation

.cursor/skills/pre-pr-review-fixes/SKILL.md

@@ -0,0 +1,83 @@
+---
+name: pre-pr-review-fixes
+description: Fix pull request feedback before opening or updating a PR. Use when the user asks to address reviewer comments, clean up docs/style issues before PR, or apply repeated feedback patterns (wording, headings, spacing, capitalization, markdown tables, and consistency fixes).
+disable-model-invocation: true
+---
+
+# Pre-PR Review Fixes
+
+Use this skill to systematically apply reviewer feedback before creating or updating a PR.
+
+## When to use
+
+- User asks to "fix PR comments" or "address review feedback"
+- User asks to "prepare this for PR" or "clean this up before PR"
+- Same reviewer repeatedly flags style/structure issues across multiple files
+
+## Why this is a skill (not a rule)
+
+- This workflow is task-specific and should run on demand.
+- A global rule would trigger too often and add overhead to unrelated tasks.
+- Skills are easier to extend with new reviewer patterns over time.
+
+## Inputs expected
+
+- PR URL or PR number
+- Reviewer name(s) to prioritize (if applicable)
+- Optional scope limits (files/folders)
+
+## Workflow
+
+1. Fetch review feedback
+   - Pull top-level review summaries and inline comments.
+   - Filter to actionable reviewer comments (ignore bot noise unless requested).
+2. Build an action list
+   - Group comments by file and section.
+   - Normalize into concrete edits (wording, formatting, structure, examples, links).
+   - Deduplicate repeated comments and mark global patterns to apply throughout.
+3. Apply fixes in files
+   - Edit only requested/scope-relevant files.
+   - Keep existing technical intent; change style/clarity unless behavior changes are requested.
+4. Validate
+   - Run lints on edited files.
+   - Re-read changed sections to ensure comment intent is fully addressed.
+5. Report back
+   - List updated files.
+   - Map key edits to reviewer themes.
+   - Call out any comments that were ambiguous or not applicable.
+
+## Common docs fixes checklist
+
+- Add a context paragraph before a heading/table when needed
+- Avoid bold text as faux headings; use real heading levels
+- Use italics (not bold) for light emphasis when requested
+- Remove extra blank lines (keep one empty line between blocks)
+- Fix incomplete/ambiguous phrasing
+- Standardize reference style: "For ..., refer to [Link](url)."
+- Replace vague endings like `etc.` with explicit wording
+- Keep capitalization consistent across bullets/tables
+- Ensure markdown tables are valid and readable
+
+## Comment triage rules
+
+- **Apply directly:** explicit suggestions and clear style requests
+- **Apply throughout:** repeated reviewer guidance across multiple files
+- **Ask user before changing:** unclear product intent, technical behavior changes, or conflicting reviewer guidance
+- **Skip with note:** non-actionable comments (for example, design critique with no available source/update path)
+
+## Output format to user
+
+Use this structure:
+
+1. Files changed
+2. What was fixed (by reviewer theme)
+3. What was not changed (and why)
+4. Validation result (lint/tests run)
+
+## Extension notes
+
+To extend this skill, add:
+
+- A `patterns.md` file with reviewer-specific conventions
+- A `commands.md` file with reusable `gh` queries for PR feedback
+- Team-specific wording conventions for docs pages

content/docs/agents/add-connect-components.mdx

@@ -0,0 +1,5 @@
+---
+title: "Add Connect Components"
+pageTitle: 'Novu Agents Add Connect Components'
+description: 'Add Connect UI components so users can link accounts and channels to your agent.'
+---

content/docs/agents/deploy-your-agent.mdx

@@ -0,0 +1,5 @@
+---
+title: "Deploy Your Agent"
+pageTitle: 'Novu Agents Deployment'
+description: 'Deploy your Novu Agent to production environments.'
+---

content/docs/agents/get-started/core-concepts.mdx

@@ -0,0 +1,184 @@
+---
+title: "Core Concepts"
+pageTitle: 'Core Concepts'
+description: "Understand the core entities, lifecycle, and building blocks inside Novu's Agent Communication Infrastructure implementation."
+icon: Blocks
+---
+
+import { HomeIcon } from 'lucide-react';
+
+
+Novu for Agents is built around a set of concepts, these concepts are how Novu implements Agent Communication Infrastructure (ACI).
+
+## The mental model
+
+Novu for Agents connects messaging platform to your agent logic through a standard communication layer. This communication can be bi-directional, a user can message your agent, and your agent can proactively reach out to a user.
+
+When a user sends a message or interacts with your agent from a connected platform, the inbound flow works like this. Novu receives it, resolves identity and conversation state, and forwards the full context to your server. Your agent processes the message and replies, then Novu delivers the response back to the platform. The flow works like this:
+
+Here's what happens at each step:
+
+### Receive and identify
+
+Novu receives the platform webhook and normalizes it into a standard format. It matches the platform user, for example, a Slack user ID to a Novu subscriber. Known users get their full profile attached, while unknown users are tracked as anonymous until identity is resolved.
+
+### Load conversation
+
+Novu creates a new conversation, if this is the first message or loads the existing one. The message history, metadata, and subscriber information are assembled into a single context object.
+
+### Your handler
+
+Novu calls your handler with the complete context: the message, conversation history, subscriber, and platform details. You process it with your LLM, business logic, or whatever system you've chosen, and call `ctx.reply()` to respond.
+
+### Deliver and persist
+
+Novu delivers the reply to the correct thread on the platform, persists it in the conversation history, and records the activity. Every message, signal, and status change is visible in the dashboard.
+
+Your server never talks to the platform directly. It receives a context object and returns a reply, Novu handles everything else.
+
+## Key entities
+
+Four core entities make up the system.
+
+### Agents
+
+An agent is the entity you create in Novu when you want to expose agent logic through one or more communication providers.
+
+Each agent has a name, an identifier, and a set of event handlers that define how your application responds to conversation events. An agent can be connected to one or more providers, such as Slack, Microsoft Teams, WhatsApp, or email.
+
+The agent doesn't define your AI model, prompts, tools, or business logic. It gives Novu a bridge to the application code where that logic runs. The provider handles where the user communicates. The agent handles how your application responds.
+
+### Providers connection
+
+A provider connection connects an agent to a messaging platform. Providers are the surfaces where users interact with your agent. A provider connection gives Novu the credentials and configuration needed to receive events from that provider and deliver responses back to it.
+
+Each provider has its own setup flow and platform capabilities. Some providers support reactions, typing indicators, attachments, rich cards, or message editing. Others may support only a subset of those behaviors. Novu normalizes provider events before passing them to your agent handler, so your code works with a consistent interface instead of provider-specific webhook payloads.
+
+This is what makes the architecture channel agnostic, you won't see anything related to Slack or WhatsApp or email in your agent code. Novu takes care of translating messages downstream to each provider's specific format and capabilities.
+
+### Conversations
+
+A conversation is the stateful thread where communication happens. When a user sends a message from a connected provider, Novu creates a new conversation or loads the existing one for that thread. The conversation includes the message history, metadata, participants, status, and platform context needed to process the next interaction.
+
+A conversation can include multiple participants. The agent is one participant in the conversation, but it is not the conversation itself. This distinction matters when you inspect conversations in the dashboard or build agent behavior around conversation state. A Slack thread, email thread, or other provider-specific thread maps to a conversation in Novu automatically.
+
+The conversations follow a simple lifecycle, a conversation starts as active when the first message arrives. Messages, actions, and reactions continue updating the conversation while it remains active. The conversation can be marked as resolved when the agent calls the resolve signal. When a conversation is resolved, the resolve handler fires and an optional summary is stored.
+
+If a user sends a new message after a conversation has been resolved, the conversation automatically reopens so the interaction can continue.
+
+### Participants and subscriber identity
+
+Participants are the people, agents, or systems involved in a conversation. When a user messages your agent from a provider, Novu tries to resolve that platform user to a known subscriber. 
+
+- If a match exists, then the handler receives subscriber information such as the subscriber ID, name, or email.
+- If no match exists, then the user is tracked as a platform user and your handler should account for cases where subscriber data is unavailable.
+
+Once identity is resolved later, they are upgraded to a full subscriber and future messages include their subscriber data.
+
+Subscriber identity helps your agent personalize responses, look up account details, or decide whether a conversation should be escalated. Identity resolution is provider-aware, a Slack user, or email sender may each have different identifiers at the provider level that Novu resolves to a single subscriber.
+
+## The bridge surface
+
+Novu exposes a consistent set of building blocks to your agent code. These are the same regardless of which provider the message came from or what brain you've plugged in.
+
+### Event handlers
+
+Event handlers are functions that respond to events in a conversation. Your agent can respond to four event types:
+
+| Handler | When it runs | Common use case |
+|---------|-------------|-----------------|
+| `onMessage` | A user sends a message in the conversation | Process the message and reply |
+| `onAction` | A user clicks a button or selects a value in an interactive card | Handle form submissions, button clicks, or dropdown selections |
+| `onReaction` | A user adds or removes a reaction | Capture feedback or trigger a follow-up |
+| `onResolve` | The conversation is marked as resolved | Clean up state, log analytics, or send a summary |
+
+Handlers are where the communication layer connects to your application logic. For example, an `onMessage` handler receives the user's message, passes the conversation context to an LLM or custom function, and sends the response back through Novu.
+
+### Context object
+
+Each event handler receives a context object. The context object gives your handler the information it needs to understand the current event and respond to it. Depending on the event type, it can include:
+* The incoming message.
+* The current conversation state and metadata.
+* The resolved subscriber (when available).
+* Recent conversation history.
+* Provider information.
+* Platform-specific details, such as thread or channel identifiers.
+* Methods for replying, updating metadata, triggering workflows, or resolving the conversation.
+
+The context object is the single interface between Novu's communication layer and your agent logic. Your code doesn't need to talk directly to Slack, Microsoft Teams, WhatsApp, or email, everything flows through the context.
+
+### Replies and interactions
+
+A reply sends a message back into the conversation. Agents can reply with different content types depending on the provider and platform capabilities: plain text, markdown with files, or interactive cards.
+
+Interactive cards let your agent send structured responses with components such as buttons, dropdowns, links, and text inputs. When a user interacts with a card, the `onAction` handler fires with the action ID and selected value.
+
+Replies are user-facing, use them when the agent needs to communicate something back to the participant in the conversation.
+
+### Signals
+
+Signals are system-facing actions your agent can perform during a conversation. Use signals when your handler needs to update state, trigger another process, or close a conversation, without necessarily sending another message to the user.
+
+| Signal | What it does |
+|--------|-------------|
+| Metadata | Stores key-value data on the conversation that persists across messages |
+| Trigger | Starts a Novu workflow from within the conversation |
+| Resolve | Marks the conversation as resolved with an optional summary |
+
+A useful way to think about the difference: replies communicate with the user, signals update the system around the conversation. A single handler invocation can do both, reply to the user, store a sentiment score in metadata, trigger an escalation workflow, and resolve the conversation.
+
+Signals aren't sent immediately when you call them. They're queued in memory and batched together with your next reply call in a single request. If your handler finishes without calling reply handler, any pending signals are still sent automatically.
+
+## Conversations and workflows
+
+ACI's conversation model and Novu's workflows are designed to work together. A conversation can trigger a workflow.
+
+For example, a user chatting with an agent in Slack asks it to prepare a report and send it via email. The agent calls a trigger function to fire a Novu workflow that handles the email delivery using the same workflow infrastructure your team might already have in place.
+
+A workflow can convert into a conversation. For example, you send a weekly digest notification to a user's email. The user replies to that email with a follow-up question, and that reply enters ACI as a new conversation with the agent. What started as a one-directional notification becomes a back-and-forth exchange.
+
+This connection means ACI is not a replacement for Novu's workflow system — it's an extension of it. The structured, predictable nature of transactional workflows and the open-ended, freeform nature of agent conversations are complementary. The value is in the combination of the two within the same platform.
+
+## How the Concepts Work Together
+
+Here is the end-to-end flow when a user messages your agent:
+
+1. A user sends a message to your agent from Slack.
+2. Novu receives the Slack event through the provider connection.
+3. Novu maps the Slack thread to a conversation and resolves the platform user to a subscriber when possible.
+4. Novu calls the agent's `onMessage` handler with the context object.
+5. Your handler passes the message and conversation context to your agent logic.
+6. Your agent logic decides what should happen next.
+7. Your handler sends a reply, emits signals, or both.
+8. Novu delivers the reply back to the Slack thread.
+9. Novu records the messages, participants, metadata, signals, and conversation status.
+
+The same agent logic works across all connected providers because Novu handles the provider-specific communication layer. Connecting a new provider does not require changing your agent code.
+
+## Next steps
+
+Now that you understand the core concepts, continue with:
+
+<Cards>
+  <Card
+    icon={<HomeIcon />}
+    href="/agents/getting-started/quickstart"
+    title="Quickstart"
+  >
+    Create your first agent, connect a provider, and send a message.
+  </Card>
+  <Card
+    icon={<HomeIcon />}
+    href="/agents/agent-bridge/agent-definition"
+    title="Agent bridge"
+  >
+  Deep dive into defining agents, event handlers, context, replies, and signals.Create your first agent, connect a provider, and send a message.
+  </Card>
+  <Card
+    icon={<HomeIcon />}
+    href="/agents/agent-logic/overview"
+    title="Agent logic"
+  >
+    Connect your preferred framework or runtime.
+  </Card>
+</Cards>

content/docs/agents/get-started/meta.json

@@ -0,0 +1,3 @@
+{
+  "pages": ["what-is-aci", "core-concepts", "quickstart"]
+}

content/docs/agents/get-started/quickstart.mdx

@@ -0,0 +1,6 @@
+---
+title: "Quickstart"
+pageTitle: 'Novu Agents Quickstart'
+description: 'Get started with Novu Agents'
+icon: Zap
+---