Merge pull request #2989 from port-labs/ai-docs-updates

AI docs updates

Author: hadar-co

docs/ai-interfaces/AGENTS.md

@@ -0,0 +1,148 @@
+---
+sidebar_class_name: hidden
+title: AGENTS.md - AI Documentation Maintenance Guide
+---
+
+# AGENTS.md - AI Documentation Maintenance Guide
+
+This is a hidden guide for AI agents to understand how to maintain and update the AI interfaces documentation in Port Docs.
+
+## File Structure
+
+The AI interfaces documentation files are located in:
+- `/docs/ai-interfaces/` - Main documentation files
+- `/src/data/mcpTools.js` - MCP tool definitions (JSON file)
+- `/src/components/ToolsList/` - React component that displays tools from `mcpTools.js`
+
+## Common Tasks
+
+### Update MCP Tools
+
+To add, update, or remove MCP tools:
+
+1. **Update the file**: `src/data/mcpTools.js`
+2. **Ask for clarification**: Determine if the tool is for `builder` only or for both `developer` and `builder` roles
+3. The `ToolsList` component automatically reads from this file and displays tools in the documentation
+
+### Set Feature Beta Status
+
+When asked to mark a feature as **open beta** or **closed beta**, use the appropriate component:
+
+#### For Open Beta Features
+
+Use the `BetaFeatureNotice` component:
+
+```markdown
+import BetaFeatureNotice from '/docs/generalTemplates/_beta_feature_notice.md'
+
+<BetaFeatureNotice id="ai-form" />
+```
+
+**Location**: Place this after the page title (H1) and before the main content.
+
+#### For Closed Beta Features
+
+Use the `ClosedBetaFeatureNotice` component:
+
+```markdown
+import ClosedBetaFeatureNotice from '/docs/generalTemplates/_closed_beta_feature_notice.md'
+
+<ClosedBetaFeatureNotice id="feature-id" />
+```
+
+**Location**: Place this after the page title (H1) and before the main content.
+
+**ID**: Use a specific feature identifier (e.g., `"slack-app"`). Check `/docs/generalTemplates/_closed_beta_feature_notice_defs.js` for available IDs and their custom messages. You might need to create a new definition, ask the user for this.
+
+### Add New LLM Model
+
+To add a new LLM model to the documentation:
+
+1. **Identify the model name and providers**: Determine the exact model identifier (e.g., `gpt-5`) and which providers support it (e.g., Anthropic, AWS Bedrock).
+
+2. **Update the main documentation file**: Edit `docs/ai-interfaces/port-ai/llm-providers-management/overview.md`:
+
+3. **Note about API reference files**: The API reference files in `docs/api-reference/` (like `general-purpose-ai-interactions.api.mdx`, `invoke-a-specific-agent.api.mdx`, etc.) are auto-generated from OpenAPI specifications. These will be updated automatically when the backend API is updated. You don't need to manually edit these files.
+
+### Update MCP Installation Instructions
+
+The MCP installation instructions are maintained in a reusable component that is imported into the main documentation page.
+
+**Location**: `/docs/generalTemplates/_mcp-installation.md`
+
+**Usage**: This component is imported in `docs/ai-interfaces/port-mcp-server/overview-and-installation.md`.
+
+**What you could update**:
+- Add new client support
+- Update client instructions
+- Update disclaimers/warnings/admonitions
+
+### Update Feature Support Matrix
+
+The Feature Support Matrix table shows which capabilities are supported across Port's AI interfaces.
+
+**Location**: `docs/ai-interfaces/overview.md` - in the "Feature Support Matrix" section
+
+**Structure**:
+- **Rows**: Each Port AI interface (Port MCP Server, Port AI Invocation, Port AI Agents, Port AI Chat Widget, Port Slack App, Port AI Assistant)
+- **Columns**: Capabilities/features (Context Lake Query, Run Actions, Manage Blueprints, etc.)
+- **Indicators**: 
+  - ✅ = Supported
+  - ❌ = Not supported
+
+**Column Ordering Rules**:
+1. **First columns**: Features that have at least one ✅ (supported by at least one interface)
+2. **Last columns**: Features that have all ❌ (not supported by any interface)
+3. **Final column**: "Manage Data Mapping" should always be the last column (it has all ❌)
+
+**Current column order** (from first to last):
+1. Feature (row identifier)
+2. Context Lake Query
+3. Run Actions
+4. Manage Blueprints
+5. Manage Entities
+6. Manage Scorecards
+7. Manage Actions
+8. Reuse Prompts
+9. Invoke AI Agents
+10. Manage Pages & Widgets (all ❌)
+11. Manage Integrations (all ❌)
+12. Manage Data Mapping (all ❌ - must be last)
+
+**When updating**:
+- If a new feature is added that has all ❌, add it before "Manage Data Mapping" (which must remain last)
+- If a feature's support status changes from all ❌ to having at least one ✅, move it to the appropriate position in the first group
+- If a new AI interface is added, add it as a new row
+- If a new capability is added, determine its position based on whether it has any ✅ or all ❌
+
+**Format**:
+- Use markdown table format
+- Wrap the table in `<div style={{overflowX: 'auto'}}>` for horizontal scrolling on smaller screens
+- Use emojis ✅ and ❌ (not text symbols)
+
+### Update Monthly Limits
+
+When asked to update the monthly quota/limit for AI invocations:
+
+1. **Identify all locations**: Search for mentions of monthly limits/quota in the AI interfaces documentation:
+   - `docs/ai-interfaces/port-ai/api-interaction.md` - Contains rate limits section and example JSON responses
+   - `docs/ai-interfaces/port-ai/overview.md` - Contains limits section and FAQ entries
+
+2. **Update text descriptions**: Replace the quota number in all text descriptions (e.g., "20 AI invocations per month" → "50 AI invocations per month")
+
+3. **Update example JSON**: Update the `monthlyLimit` value in example JSON responses to match the new limit. Also update `remainingQuota` to be one less than the limit (e.g., if limit is 50, remainingQuota should be 49)
+
+4. **Files to check**:
+   - `docs/ai-interfaces/port-ai/api-interaction.md` - Lines with "Monthly Quota" section and JSON examples
+   - `docs/ai-interfaces/port-ai/overview.md` - Lines with "Monthly Quota" section and FAQ entries
+
+5. **Search pattern**: Look for patterns like:
+   - "20 AI invocations per month"
+   - `"monthlyLimit": 20`
+   - "Default quota: 20"
+
+**Note**: The API reference files in `docs/api-reference/` are auto-generated from OpenAPI specifications and will be updated automatically when the backend API is updated. You don't need to manually edit these files.
+
+## Other Tasks
+
+For other tasks not listed above, ask for clarification from the user. Once understood, add a new section to the "Common Tasks" section of this file.

docs/ai-interfaces/ai-agents/build-an-ai-agent.md

@@ -5,12 +5,11 @@ title: Build an AI agent
 
 # Build an AI agent
 
-:::info Closed Beta
-Port's AI offerings are currently in closed beta and will be gradually rolled out to users by the end of 2025.
-:::
-
 import Tabs from "@theme/Tabs"
 import TabItem from "@theme/TabItem"
+import BetaFeatureNotice from '/docs/generalTemplates/_beta_feature_notice.md'
+
+<BetaFeatureNotice id="ai-form" />
 
 :::info Built on Port AI
 AI Agents are built on top of [Port AI](/ai-interfaces/port-ai/overview) and leverage its underlying capabilities for data access, security, and execution. This guide focuses on agent-specific building techniques.
@@ -118,7 +117,7 @@ From [john-123](https://github.com/john-123)
 <details>
 <summary><b>I don't see an option to add an AI agent (Click to expand)</b></summary>
 
-Make sure you have [access to the AI agents feature](/ai-interfaces/ai-agents/overview#access-to-the-feature). Note that it's currently in closed beta and requires special access. If you believe you should have access, please contact our support.
+Make sure you have [access to the AI agents feature](/ai-interfaces/ai-agents/overview#access-to-the-feature). If you believe you should have access, please contact our support.
 </details>
 
 <details>

docs/ai-interfaces/ai-agents/interact-with-ai-agents.md

@@ -5,12 +5,11 @@ title: Interact with AI agents
 
 # Interact with AI agents
 
-:::info Closed Beta
-Port's AI offerings are currently in closed beta and will be gradually rolled out to users by the end of 2025.
-:::
-
 import Tabs from "@theme/Tabs"
 import TabItem from "@theme/TabItem"
+import BetaFeatureNotice from '/docs/generalTemplates/_beta_feature_notice.md'
+
+<BetaFeatureNotice id="ai-form" />
 
 :::info Built on Port AI
 AI Agents are specialized implementations built on top of [Port AI](/ai-interfaces/port-ai/overview), designed for machine-to-machine communication and autonomous operations within defined domains.
@@ -54,6 +53,8 @@ The widget provides a chat interface where you can ask questions and receive res
 
 The widget will inherit all the agent's configuration including the prompts, conversation starters, tool access, etc.
 
+**Context Awareness**: The widget automatically understands the context of the page and entity where it's located. For example, when placed on a team entity page, you can ask questions like "What is this team's lead time for change?" or "How many open bugs does the team have?" without needing to specify the team name.
+
 Conversation starters appear in the initial state, helping users understand what they can ask the agent. Users can either click a starter to begin a new chat or type their own question.
 <img src='/img/ai-agents/AIAgentsWidgetConversationStarters.png' width='80%' border='1px' />
 

docs/ai-interfaces/ai-agents/overview.md

@@ -6,13 +6,11 @@ title: Overview
 import Tabs from "@theme/Tabs"
 import TabItem from "@theme/TabItem"
 import PortTooltip from "/src/components/tooltip/tooltip.jsx"
-import ClosedBetaFeatureNotice from '/docs/generalTemplates/_closed_beta_feature_notice.md'
+import BetaFeatureNotice from '/docs/generalTemplates/_beta_feature_notice.md'
 
 # AI agents overview
 
-:::info Closed Beta
-Port's AI offerings are currently in closed beta and will be gradually rolled out to users by the end of 2025.
-:::
+<BetaFeatureNotice id="ai-form" />
 
 :::info Built on Port AI
 AI Agents are specialized implementations built on top of [Port AI](/ai-interfaces/port-ai/overview), designed for specific domains and machine-to-machine communication. For general AI capabilities and human interaction, see [Port AI](/ai-interfaces/port-ai/overview).

docs/ai-interfaces/ai-chat-widget.md

@@ -24,6 +24,7 @@ The AI Chat Widget is a dashboard component that:
 - **Uses configured tools**: Operates with the specific [Port AI tools](/ai-interfaces/port-ai/overview#port-ai-tools) you select.
 - **Customizable placement**: Can be embedded in any dashboard layout.
 - **Respects permissions**: Only accesses data based on user permissions.
+- **Context-aware**: Automatically understands the page and entity context where it's located, allowing you to ask questions about the specific entity or page without explicitly mentioning it.
 
 ## Widget Configuration
 
@@ -82,6 +83,17 @@ Users can type their own questions and requests directly into the chat interface
 - Show visual indicators when tools are being used.
 - Provide links to relevant Port pages and actions.
 
+### Context Awareness
+
+The AI Chat Widget automatically understands the context of the page and entity where it's located. This means you can ask questions about the specific entity or page without needing to explicitly mention it.
+
+**Examples:**
+- On a **team entity page**: "What is this team's lead time for change?" or "How many open bugs does the team have?"
+- On a **service entity page**: "What's the deployment status?" or "Show me recent incidents"
+- On a **dashboard**: Questions will be answered in the context of the dashboard's scope
+
+The widget uses this context to provide more relevant and accurate responses, making it easier to get information about the specific entity or page you're viewing.
+
 ### Tool Transparency
 The widget interface provides enhanced capabilities and visual indicators showing which tools are being used:
 
@@ -314,4 +326,17 @@ For comprehensive information, see [Security Considerations](#security-considera
 - [Data Privacy & Retention](/ai-interfaces/port-ai/security-and-data-controls#data-privacy--retention) - How your data is handled and stored.
 </details>
 
+<details>
+<summary><b>Does the widget understand the context of the page it's on? (Click to expand)</b></summary>
+
+Yes! The AI Chat Widget automatically understands the context of the page and entity where it's located. This means you can ask questions about the specific entity or page without needing to explicitly mention it.
+
+**Examples:**
+- On a **team entity page**: "What is this team's lead time for change?" or "How many open bugs does the team have?"
+- On a **service entity page**: "What's the deployment status?" or "Show me recent incidents"
+- On a **dashboard**: Questions will be answered in the context of the dashboard's scope
+
+The widget uses this context to provide more relevant and accurate responses. Learn more in [Context Awareness](#context-awareness).
+</details>
+
 The AI Chat Widget provides a powerful way to bring [Port AI](/ai-interfaces/port-ai/overview) capabilities directly into your team's daily workflows through customized dashboard experiences.

docs/ai-interfaces/overview.md

@@ -5,7 +5,7 @@ title: Overview
 
 # AI Interfaces Overview
 
-Port's AI interfaces provide intelligent assistance across your entire software development lifecycle. Our AI capabilities are currently in **open beta**, with Slack App in **closed beta**.
+Port's AI interfaces provide intelligent assistance across your entire software development lifecycle. All AI features are currently in **open beta**.
 
 We're committed to developing AI responsibly, maintaining high standards of data privacy and security. **[Learn more about our security & data controls →](/ai-interfaces/port-ai/security-and-data-controls)**
 
@@ -82,7 +82,7 @@ The MCP Server provides AI machine interface capabilities that are compatible wi
 **[Set up MCP Server →](/ai-interfaces/port-mcp-server/overview-and-installation)**
 
 ### Slack App
-Interact with Port's AI capabilities directly from Slack. Ask questions, run actions, and get insights without leaving your team communication platform. **Currently in closed beta** - we are not accepting new applications at the moment and will update once it moves to open beta.
+Interact with Port's AI capabilities directly from Slack. Ask questions, run actions, and get insights without leaving your team communication platform.
 
 **[Learn about the Slack App →](/ai-interfaces/slack-app)**
 
@@ -100,6 +100,23 @@ Set up the **MCP Server** to bring Port's AI capabilities directly into your dev
 ### For Team Collaboration
 Use the **Slack App** to make AI insights available to your entire team in your communication platform.
 
+## Feature Support Matrix
+
+The following table shows which capabilities are supported across Port's AI interfaces:
+
+<div style={{overflowX: 'auto'}}>
+
+| Feature | Context Lake Query | Run Actions | Manage Blueprints | Manage Entities | Manage Scorecards | Manage Actions | Reuse Prompts | Invoke AI Agents | Manage Pages & Widgets | Manage Integrations | Manage Data Mapping |
+|--------------------------------|-------------------|-------------------|-------------------|-------------------|-------------------|-------------------|-------------------|-------------------|-------------------|-------------------|-------------------|
+| **Port MCP Server** | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ |
+| **Port AI Invocation** | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ |
+| **Port AI Agents** | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ |
+| **Port AI Chat Widget** | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ | ❌ | ❌ | ❌ |
+| **Port Slack App** | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ |
+| **Port AI Assistant** | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ |
+
+</div>
+
 ## Frequently Asked Questions
 
 <details>
@@ -109,7 +126,7 @@ Port offers four main AI interfaces:
 - **Port AI Assistant**: Chat interface for quick questions and insights.
 - **AI Agents**: Customizable workflows for automations.
 - **MCP Server**: IDE integration for development workflows.
-- **Slack App**: Team collaboration interface (closed beta).
+- **Slack App**: Team collaboration interface.
 </details>
 
 <details>
@@ -129,7 +146,7 @@ If you're a developer who works primarily in an IDE, consider starting with the
 
 For custom workflows or automation, explore **AI Agents**. **[Learn about AI Agents →](/ai-interfaces/ai-agents/overview)**
 
-For team collaboration, try the **Slack App** to bring AI insights into your communication platform (closed beta). **[Explore Slack App →](/ai-interfaces/slack-app)**
+For team collaboration, try the **Slack App** to bring AI insights into your communication platform. **[Explore Slack App →](/ai-interfaces/slack-app)**
 </details>
 
 <details>
@@ -138,7 +155,7 @@ For team collaboration, try the **Slack App** to bring AI insights into your com
 - **Port AI Assistant**: Open beta - available to all users.
 - **MCP Server**: Open beta - available to all users.
 - **AI Agents**: Open beta - available to all users.
-- **Slack App**: Closed beta - not accepting new applications at the moment.
+- **Slack App**: Open beta - available to all users.
 </details>
 
 <details>