Merge branch 'main' into PORT-streamline-iac-with-ai

Author: PeyGis

docs/actions-and-automations/setup-backend/webhook/port-execution-agent/usage.md

@@ -88,6 +88,8 @@ Use the following Helm values:
 - Set `selfSignedCertificate.enabled` to `true`.
 - Put your PEM-encoded CA content in `selfSignedCertificate.certificate`.
 
+The certificate should be mounted to `/usr/local/share/ca-certificates/`.
+
 `REQUESTS_CA_BUNDLE` is an environment variable used to specify a custom Certificate Authority (CA) bundle for verifying SSL/TLS certificates in HTTPS requests.
 
 Set `REQUESTS_CA_BUNDLE` to the file path of your CA bundle, which should contain one or more CA certificates in PEM format.
@@ -103,10 +105,11 @@ This configuration directs the `requests` library to use the specified CA bundle
 
 Use the following Helm values:
 - Keep your certificate via `selfSignedCertificate` as above.
-- Add other certificates by supplying files via `extraVolumes` and mounting them with `extraVolumeMounts` into the container.
+- Add other certificates by supplying files via `extraVolumes` and mounting them with `extraVolumeMounts` into the container at `/usr/local/share/ca-certificates/<your-cert-name>.crt`.
 
-:::info Certificate file requirement
-Each certificate must be provided in a separate PEM file. Files containing multiple certificates are not supported.
+:::info Certificate file requirements
+- Each certificate must be provided in a separate PEM file. Files containing multiple certificates are not supported.
+- Certificates must be mounted to `/usr/local/share/ca-certificates/` with a `.crt` file extension.
 :::
 
 ## Next Steps

docs/ai-interfaces/ai-agents/_category_.json

@@ -1,4 +1,4 @@
 {
   "label": "AI agents",
-  "position": 4
+  "position": 5
 }

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

@@ -1,5 +1,5 @@
 ---
-sidebar_position: 3
+sidebar_position: 4
 title: AI Chat Widget
 sidebar_class_name: hidden
 ---

docs/ai-interfaces/overview.md

@@ -22,15 +22,23 @@ The foundational AI infrastructure that powers all intelligent responses within
 **[Learn more about Port AI →](/ai-interfaces/port-ai/overview)**
 
 ### Port AI Assistant
-The fastest way to get started with Port's AI capabilities. A chat interface that provides instant answers about your SDLC.
+The fastest way to get started with Port's AI capabilities. An out-of-the-box chat interface available through a floating button that requires zero configuration.
 
-**Use Port AI Assistant to ask:**
+**Use Port AI Assistant to:**
+* Ask questions about your software catalog and actions.
+* Get help with Port features and documentation.
+* Execute actions with approval mode safety.
+* Explore your data without complex queries.
+
+**Example questions:**
 * "Which services are failing security checks?"
-* "When was the last successful deployment of the payment service?"
+* "How do I deploy the auth service to production?"
+* "Give me a weekly summary of open bugs"
 * "Who owns this component?"
-* "What's the deployment frequency of team X?"
 
-Perfect for developers who need quick insights and contextual information about their development environment.
+Perfect for immediate insights without dedicated customizations. No agents, no configuration - just start asking questions.
+
+**[Learn more about Port AI Assistant →](/ai-interfaces/port-ai-assistant)**
 
 
 ### AI Agents
@@ -99,15 +107,15 @@ Port offers four main AI interfaces:
 <details>
 <summary>What's the difference between Port AI Assistant and AI Agents? (Click to expand)</summary>
 
-**Port AI Assistant** is designed for immediate, ad-hoc questions and provides instant answers about your development environment. It's perfect for quick insights and exploratory queries.
+**Port AI Assistant** is designed for immediate use with zero configuration. It provides instant answers about your development environment through a floating chat button. It's perfect for quick insights, exploratory queries, and learning about Port. **[Learn more →](/ai-interfaces/port-ai-assistant)**
 
-**AI Agents** are pre-configured, customizable entities designed for specific workflows and automations. They're built for machine-to-machine interactions and complex, domain-specific processes.
+**AI Agents** are customizable entities designed for specific workflows and automations. They're built for machine-to-machine interactions and complex, domain-specific processes that require dedicated configuration. **[Learn more →](/ai-interfaces/ai-agents/overview)**
 </details>
 
 <details>
 <summary>Which AI interface should I start with? (Click to expand)</summary>
 
-For most users, start with **Port AI Assistant** - it provides immediate value with no setup required. You can ask questions and get insights right away. **[Get started with Port AI Assistant →](/ai-interfaces/port-ai/overview)**
+For most users, start with **Port AI Assistant** - it provides immediate value with no setup required. Available through a floating button, you can ask questions and get insights right away. **[Get started with Port AI Assistant →](/ai-interfaces/port-ai-assistant)**
 
 If you're a developer who works primarily in an IDE, consider starting with the **MCP Server** for seamless integration with your development workflow. **[Set up MCP Server →](/ai-interfaces/port-mcp-server/overview-and-installation)**
 
@@ -119,7 +127,7 @@ For team collaboration, try the **Slack App** to bring AI insights into your com
 <details>
 <summary>What's the current availability status of Port's AI features? (Click to expand)</summary>
 
-- **Port AI Assistant**: Open beta - available to all users.
+- **Port AI Assistant**: Closed beta - gradually rolling out to users.
 - **MCP Server**: Open beta - available to all users.
 - **AI Agents**: Closed beta - requires application and approval.
 - **Slack App**: Closed beta - requires application and approval.

docs/ai-interfaces/port-ai-assistant.md

@@ -0,0 +1,200 @@
+---
+sidebar_position: 2
+title: Port AI Assistant
+---
+
+# Port AI Assistant
+
+:::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.
+:::
+
+The Port AI Assistant is the fastest way to start using AI with Port - no configuration required. Available through a floating chat button, it provides instant, intelligent answers about your software catalog, actions, and Port's capabilities.
+
+## What is the Port AI Assistant?
+
+The Port AI Assistant is an out-of-the-box chat interface that:
+
+- **Requires no setup**: Start asking questions immediately without defining agents or configurations.
+- **Always accessible**: Available through a floating button whenever you have access to Port AI.
+- **Comprehensive knowledge**: Understands your catalog, actions, and Port documentation.
+- **Safe by default**: Uses read-only [MCP tools](/ai-interfaces/port-mcp-server/available-tools) and approval mode for actions.
+- **Fastest experience**: Get answers without the customization overhead of [AI Agents](/ai-interfaces/ai-agents/overview).
+
+Built on [Port AI](/ai-interfaces/port-ai/overview), the assistant operates using [Port AI's developer tools](/ai-interfaces/port-ai/overview#port-ai-tools) in safe mode - meaning all actions run in **approval mode** (you get a link to review and execute) and uses read-only tools for data queries. The assistant also has access to Port's documentation through a dedicated MCP tool.
+
+## How to Use the Port AI Assistant
+
+The Port AI Assistant is available through a floating chat button in the Port interface. Simply click the button at the bottom-right corner to open the chat interface and start asking questions.
+
+<img src='/img/ai-agents/AIChatInitialState.png' width='70%' border='1px' />
+
+Once you ask a question, the assistant analyzes your request and uses the appropriate tools to provide a comprehensive response.
+
+<img src='/img/ai-agents/AIChatAskQuestion.png' width='40%' border='1px' />
+
+After processing your request, you'll receive a detailed answer along with any relevant actions or next steps.
+
+<img src='/img/ai-agents/AIChatFinalResponse.png' width='40%' border='1px' />
+
+## Example Questions
+
+The Port AI Assistant can help with a wide variety of questions out of the box:
+
+<details>
+<summary><b>Service Ownership & Information</b></summary>
+
+- "Who owns the payment service?"
+- "What services does the platform team own?"
+- "Show me all microservices owned by the Backend team"
+- "What is the checkout service about?"
+- "What are the dependencies of the OrderProcessing service?"
+
+</details>
+
+<details>
+<summary><b>Deployment & Operations</b></summary>
+
+- "How do I deploy the auth service to production?"
+- "When was the last successful deployment of the payment service?"
+- "Show me failed deployments from last week"
+- "What's deployed in production today?"
+- "What's the deployment frequency of team X?"
+
+</details>
+
+<details>
+<summary><b>Quality & Compliance</b></summary>
+
+- "Which services are failing security checks?"
+- "Give me a weekly summary of open bugs"
+- "What's preventing the InventoryService from reaching Gold level?"
+- "Show me services with high bug counts"
+- "What's our overall security score?"
+
+</details>
+
+<details>
+<summary><b>Incidents & Monitoring</b></summary>
+
+- "Show me active incidents"
+- "Which services had an incident in the last 30 days?"
+- "Who is on call for the payment service?"
+- "What is our mean time to resolution?"
+
+</details>
+
+<details>
+<summary><b>Tasks & Workflow</b></summary>
+
+- "What tasks are assigned to me?"
+- "Show me my urgent Jira tickets"
+- "How many issues were closed by the frontend team this month?"
+- "What PRs are waiting for my review?"
+
+</details>
+
+<details>
+<summary><b>Port Usage & Help</b></summary>
+
+- "How do I create a new blueprint?"
+- "What's the best way to set up scorecards?"
+- "How can I trigger an action via API?"
+- "Show me how to configure RBAC permissions"
+
+</details>
+
+
+## Security & Permissions
+
+The Port AI Assistant respects your organization's security controls:
+
+- **RBAC compliance**: Only accesses data you have permissions to view.
+- **Safe operation**: Read-only tools for data queries.
+- **Action approval**: All actions require your explicit approval before execution.
+- **Audit trail**: All interactions are logged as [AI invocations](/ai-interfaces/port-ai/overview#ai-invocations).
+- **Access control**: Access to the Port AI Assistant is controlled through the `_ai_invocation` blueprint permissions. Learn more about [controlling access to Port AI](/ai-interfaces/port-ai/overview#controlling-access-to-port-ai).
+
+For comprehensive security information, see [AI Security and Data Controls](/ai-interfaces/port-ai/security-and-data-controls).
+
+## Frequently Asked Questions
+
+<details>
+<summary><b>Do I need to configure anything to use the Port AI Assistant? (Click to expand)</b></summary>
+
+No! The Port AI Assistant works out of the box. As soon as you have access to Port AI, you can start asking questions through the floating chat button. No setup, no configuration, no agent definitions required.
+
+</details>
+
+<details>
+<summary><b>Can the Port AI Assistant run actions on my behalf? (Click to expand)</b></summary>
+
+The assistant can help you execute actions, but it operates in **approval mode**. This means:
+1. It will identify the right action for your request
+2. It will populate the action parameters based on context
+3. It will provide you a link to review and complete the action
+4. You maintain full control over execution
+
+This approach ensures safety while making actions easier to discover and use.
+
+</details>
+
+<details>
+<summary><b>What's the difference between Port AI Assistant and AI Agents? (Click to expand)</b></summary>
+
+**Port AI Assistant** is designed for:
+- Immediate use with zero configuration
+- General-purpose questions across your entire catalog
+- Interactive exploration and ad-hoc queries
+- Human interaction and learning
+
+**[AI Agents](/ai-interfaces/ai-agents/overview)** are designed for:
+- Domain-specific expertise and workflows
+- Machine-to-machine communication
+- Autonomous operations and automations
+- Customized behavior for specific use cases
+
+The assistant is the fastest way to get started, while agents provide advanced customization for specialized needs.
+
+</details>
+
+<details>
+<summary><b>What data can the Port AI Assistant access? (Click to expand)</b></summary>
+
+The assistant uses [Port AI's developer tools](/ai-interfaces/port-ai/overview#port-ai-tools), which include read-only access to your data model, entities, scorecards, self-service actions, and Port documentation. All data access respects your organization's RBAC policies - you can only access data you have permissions to view. Learn more about [Port AI's security controls](/ai-interfaces/port-ai/security-and-data-controls).
+
+</details>
+
+<details>
+<summary><b>Can the Port AI Assistant help me learn how to use Port? (Click to expand)</b></summary>
+
+Yes! The assistant has comprehensive knowledge of Port's documentation and can help you:
+- Understand how features work
+- Learn best practices
+- Troubleshoot issues
+- Discover new capabilities
+
+Try asking questions like "How do I create a blueprint?" or "What's the best way to set up scorecards?"
+
+</details>
+
+<details>
+<summary><b>When should I use the Port AI Assistant vs other AI interfaces? (Click to expand)</b></summary>
+
+**Use the Port AI Assistant** when you want immediate AI access with zero configuration. It's perfect for quick questions, exploratory queries, learning Port, and ad-hoc analysis.
+
+**Use AI Chat Widgets** (with [AI Agents](/ai-interfaces/ai-agents/overview)) when you need customized AI experiences embedded in dashboards - configure prompts, conversation starters, and specific tool selections for team-specific workflows.
+
+**Use AI Agents** for domain-specific expertise, machine-to-machine communication, and autonomous operations that require advanced customization.
+
+</details>
+
+<details>
+<summary><b>Are there usage limits for the Port AI Assistant? (Click to expand)</b></summary>
+
+Yes, the Port AI Assistant uses the same [usage limits as Port AI](/ai-interfaces/port-ai/overview#limits-and-usage). These limits are at the organization level and include hourly rate limits and monthly quotas.
+
+Monitor your usage through [AI invocations](/ai-interfaces/port-ai/overview#ai-invocations) in your Port catalog.
+
+</details>
+

docs/ai-interfaces/port-ai/_category_.json

@@ -1,4 +1,4 @@
 {
   "label": "Port AI",
-  "position": 2
+  "position": 3
 }

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

@@ -95,7 +95,7 @@ For detailed information about tool selection patterns, API usage examples, and
 Port AI can be accessed through several interfaces, each designed for different use cases:
 
 ### Port AI Assistant
-The **Port AI Assistant** provides a dedicated, out-of-the-box user experience that requires no configuration. It offers a complete chat interface optimized for interacting with your Port data. *(Coming soon - comprehensive documentation)*
+The **[Port AI Assistant](/ai-interfaces/port-ai-assistant)** provides a dedicated, out-of-the-box user experience that requires no configuration. Available through a floating button, it offers instant access to AI-powered insights about your catalog, actions, and Port documentation - with zero setup required.
 
 ### AI Chat Widget  
 The [AI Chat Widget](/ai-interfaces/ai-chat-widget) is a customizable interface that platform engineers can embed in dashboards. It allows configuration of:
@@ -183,6 +183,24 @@ Port AI respects your organization's security controls:
 
 For detailed security information, see [AI Security and Data Controls](/ai-interfaces/port-ai/security-and-data-controls).
 
+### Controlling Access to Port AI
+
+Access to Port AI is controlled through the `_ai_invocation` blueprint's permissions. Users who have permission to **register** new AI invocation entities will be able to access and use Port AI interfaces, including the Port AI Assistant.
+
+To configure who can access Port AI:
+
+1. Navigate to your **Data Model** in Port
+2. Search for the `_ai_invocation` blueprint
+3. Go to the **Permissions** tab
+4. Under the **Entities** section, configure the **Register** permission
+5. Only users with the "register" permission will have access to Port AI
+
+<img src='/img/ai-agents/AIInvocationPermissions.png' width='85%' border='1px' />
+
+:::tip User access control
+By controlling who can register AI invocations, you can manage which users in your organization have access to Port AI features. This includes access to the Port AI Assistant, AI Chat Widgets, and API-based interactions.
+:::
+
 ## Technical Limitations
 
 :::tip MCP Tools Limitations
@@ -277,7 +295,7 @@ Port AI supports two primary interaction types:
 <summary><b>How can I interact with Port AI? (Click to expand)</b></summary>
 
 You can interact with Port AI through multiple interfaces:
-- **Port AI Assistant** - Dedicated chat interface *(documentation coming soon)*
+- **[Port AI Assistant](/ai-interfaces/port-ai-assistant)** - Out-of-the-box chat interface via floating button (no configuration required).
 - [AI Chat Widget](/ai-interfaces/ai-chat-widget) - Customizable dashboard widgets
 - API integration - For custom applications and external workflows
 - [AI Agents](/ai-interfaces/ai-agents/overview) - Specialized implementations built on Port AI

docs/ai-interfaces/port-mcp-server/_category_.json

@@ -1,4 +1,4 @@
 {
   "label": "MCP server",
-  "position": 4
+  "position": 6
 }

docs/ai-interfaces/slack-app.md

@@ -1,5 +1,5 @@
 ---
-sidebar_position: 6
+sidebar_position: 7
 title: Slack App
 ---