Merge branch 'main' into setup-the-service-explorer-ai-agent-refactor-guide

Author: sivanel97

CONTRIBUTING.md renamed to best_practices.md

@@ -1,14 +1,6 @@
-# Contributing to Port's documentation
+# Port documentation style guide
 
-Here you can find resources and guidelines on how to contribute to Port's documentation and how to correctly write and fix documentation content.
-
-## How to contribute
-
-The best way to suggest edits for an existing page is by using the "Edit this page" button at the bottom of most docs, this button will take you to the GitHub interface to make and propose changes.
-
-If you want to add a new documentation page, please fork the repository and after adding the new docs, create a PR which will be reviewed by our team.
-
-Contributions are very welcome. If you need help planning your contribution, feel free to ask us by opening an issue in this repository or by writing in our [community Slack](https://join.slack.com/t/getport/shared_invite/zt-1v5z1z1v-3~1Q1Q1).
+This document details guidelines for contributing to Port's documentation, and demonstrates how to correctly write and review documentation content.
 
 ## Styling guidelines
 

docs/actions-and-automations/actions-and-automations.md

@@ -5,10 +5,9 @@ import PortTooltip from "/src/components/tooltip/tooltip.jsx"
 One of Port's core offerings is the ability to automate and simplify the processes and routines of your developers.  
 This is done using two powerful tools:
 
-## 1. Self-service actions
+## 1. Actions
 
-Create a wide range of personalized, controlled actions that developers can use to scaffold a service, provision a cloud resource, or any other logic that serves your organization.  
-Self-service actions drive developer productivity by providing a consistent and repeatable way to perform common tasks, all with guardrails like manual approvals or consumption policies to comply with organizational standards.
+Actions are executable pieces of logic that developers or AI agents can run. You can create a wide range of personalized, controlled actions to scaffold a service, provision a cloud resource, or any other logic that serves your organization. Actions drive developer productivity by providing a consistent and repeatable way to perform common tasks, all with guardrails like manual approvals or consumption policies to comply with organizational standards.
 
 :::tip Live demo
 For real-world examples of self-service actions, check out our [live demo](https://showcase.port.io/self-serve).

docs/actions-and-automations/create-self-service-experiences/_category_.json

@@ -1,4 +1,4 @@
 {
-  "label": "Create self-service actions",
+  "label": "Create actions",
   "position": 1
 }

docs/actions-and-automations/create-self-service-experiences/create-self-service-experiences.md

@@ -14,7 +14,9 @@ import ExecuteActionLocations from '/docs/actions-and-automations/create-self-se
 </center>
 <br/>
 
-Drive developer productivity by allowing developers to use self-service actions like scaffolding a service or provisioning a cloud resource. Developer self-service drives consistency and repeatability and ensures that their routines are intuitive and clear, all with guardrails like manual approvals or consumption policies to comply with organizational standards.
+Actions are executable pieces of logic that either developers or AI agents can run. They drive developer productivity by enabling them to use actions like scaffolding a service or provisioning a cloud resource.  
+
+Actions drive consistency and repeatability and ensure that routines are intuitive and clear, all with guardrails like manual approvals or consumption policies to comply with organizational standards.
 
 Port's action model is designed to be flexible and can be used to cover a wide range of use-cases:
 
@@ -24,7 +26,7 @@ Port's action model is designed to be flexible and can be used to cover a wide r
 4. **Stateful** - every invoked action affects the software catalog by adding/modifying/deleting one or more entities.
 5. **Secure by design** - does not require keys to sensitive infrastructure by using an event-based model. All actions are audited and can include guardrails like manual approval and TTL.
 
-## 💡 Common self-service actions
+## Common self-service actions
 
 - [**Scaffold** a new service](https://docs.port.io/guides/all/scaffold-a-new-service/).
 - [**Create** a cloud resource](https://docs.port.io/guides/all/create-cloud-resource-using-iac).
@@ -37,7 +39,7 @@ In our [live demo](https://showcase.port.io/self-serve), you can see examples fo
 
 ## How does it work?
 
-1. A user **executes an action** from Port's UI interface.
+1. A user or AI agent **executes an action** from Port's UI interface or through API calls.
 2. A pre-defined **payload** containing any desired metadata about the action and its inputs is **sent** to your infrastructure.
 3. A **job is triggered** and the user gets a **continuous indication** about its progress.
 4. Once the action is running, you can use Port's API to **update Port on its status** and provide information such as **logs and links to the resulting handlers**.

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

@@ -9,9 +9,9 @@ import TabItem from "@theme/TabItem"
 
 # AI Chat Widget
 
-:::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 BetaFeatureNotice from '/docs/generalTemplates/_beta_feature_notice.md'
+
+<BetaFeatureNotice id="ai-form" />
 
 The AI Chat Widget provides a customizable interface for interacting with [Port AI](/ai-interfaces/port-ai/overview) directly within your dashboards. Platform engineers can configure the widget's prompts, conversation starters, and available developer tools to create tailored AI chat experiences for developers.
 

docs/ai-interfaces/context-lake.md

@@ -0,0 +1,117 @@
+---
+sidebar_position: 9
+title: Context Lake
+sidebar_label: Context Lake
+---
+
+import Tabs from "@theme/Tabs"
+import TabItem from "@theme/TabItem"
+
+# Context lake
+
+import BetaFeatureNotice from '/docs/generalTemplates/_beta_feature_notice.md'
+
+<BetaFeatureNotice id="ai-form" />
+
+Port's Context Lake is your unified engineering knowledge layer—connecting data from across your entire toolchain into a single, semantically-rich source of truth. It's not a separate feature, but rather the powerful result of Port's core capabilities working together to provide organizational context that AI agents, developers, and workflows can understand and act upon.
+
+## What comprises the context lake
+
+The context lake transforms scattered data across your engineering tools into unified organizational knowledge. It is built from four core components:
+
+### Software catalog - your data
+
+The [software catalog](/build-your-software-catalog) is where you define YOUR organization's data model using blueprints (services, environments, teams, deployments, incidents, etc.) and populate it with entities from all your tools. This catalog becomes your organizational semantic layer—teaching Port what "service," "deployment," or "incident" means specifically in your context, providing the schema and structure that gives meaning to your data.
+
+### Access controls - data governance
+
+[RBAC and permissions](/sso-rbac/rbac-overview) ensure that the right people and systems see the right data. Teams, roles, and policies control who can view, edit, or act on catalog data, maintaining security while enabling collaboration and providing governed access to your organizational knowledge.
+
+### Scorecards - your standards
+
+[Scorecards](/scorecards/overview) define and track your engineering standards, KPIs, and quality metrics. They encode organizational expectations—production readiness requirements, security compliance rules, operational best practices—as measurable criteria within the Context Lake, providing the organizational standards and quality signals that inform decisions.
+
+### Interface layer - how you access it
+
+Context Lake data becomes actionable through multiple interfaces: **[AI Interfaces](/ai-interfaces/overview)** where AI agents and assistants query through [Port MCP Server](/ai-interfaces/port-mcp-server/overview-and-installation) to understand your organization, **[API](/api-reference/port-api)** for programmatic access, and **[Interface Designer](/customize-pages-dashboards-and-plugins/dashboards/)** with dashboards and visualizations that surface insights to your teams—providing multiple ways to query, visualize, and act on your organizational context.
+
+## Why the context lake matters
+
+<Tabs groupId="context-lake-value" queryString>
+<TabItem value="ai-agents" label="For AI agents">
+
+Generic AI doesn't understand what "production-ready" means in YOUR organization, who owns which services, or how your deployment pipeline works. Context Lake provides this semantic understanding, enabling AI agents to:
+
+- Answer ownership questions with definitive data (not guesses from code comments).
+- Understand dependencies and relationships between services.
+- Follow your organization's standards and guardrails when taking actions.
+- Make decisions based on real-time operational context.
+
+</TabItem>
+<TabItem value="developers" label="For developers">
+
+Instead of hunting across 10 different tools to understand a service's dependencies, ownership, deployment history, or incident timeline, developers get unified context in one place. The Context Lake connects the dots automatically.
+
+**Benefits:**
+- Quick access to service ownership and team information.
+- Understand dependencies without switching between tools.
+- See complete deployment and incident history in context.
+- Get AI-powered insights based on your organization's actual data.
+
+</TabItem>
+<TabItem value="platform-teams" label="For platform teams">
+
+Define your organizational semantics once—service definitions, environment types, team structures, standards—and every tool, workflow, and AI agent can consume this shared knowledge. No more syncing configurations across systems.
+
+**Benefits:**
+- Single source of truth for organizational definitions.
+- Consistent standards across all tools and automations.
+- Reduced maintenance overhead from duplicate configurations.
+- Enable self-service while maintaining governance.
+
+</TabItem>
+</Tabs>
+
+## Context lake in action
+
+<Tabs groupId="context-lake-examples" queryString>
+<TabItem value="ownership" label="AI agent understanding ownership">
+
+**Developer asks:** "Who owns the payments service?"
+
+- **Without Context Lake:** AI guesses based on code comments or recent contributors.
+- **With Context Lake:** AI queries the catalog → sees Team relation → returns the owning team with Slack channel and on-call schedule.
+
+</TabItem>
+<TabItem value="provisioning" label="Autonomous service provisioning">
+
+**AI agent needs to provision a dev environment:**
+
+- **Without Context Lake:** Agent doesn't know company's cloud standards, naming conventions, or cost limits.
+- **With Context Lake:** Agent queries blueprints → understands allowed regions, naming patterns, tagging requirements → provisions correctly within organizational guardrails.
+
+</TabItem>
+<TabItem value="incident" label="Incident response">
+
+**Alert fires:** "payments-api pod crashing"
+
+- **Without Context Lake:** Engineer hunts through Slack, wiki, runbooks across multiple tools.
+- **With Context Lake:** Port surfaces: recent deployments, related PRs, dependent services, ownership, SLOs, past incidents—all in unified context for faster resolution.
+
+</TabItem>
+</Tabs>
+
+## Getting started
+
+Building your Context Lake is a natural part of setting up Port:
+
+1. **[Define your data model](/build-your-software-catalog)** - Create blueprints that represent your organization's entities.
+2. **[Connect your tools](/build-your-software-catalog/sync-data-to-catalog)** - Ingest data from GitHub, Kubernetes, PagerDuty, and 100+ other integrations.
+3. **[Set up relationships](/build-your-software-catalog/customize-integrations/configure-mapping#relations)** - Define how entities connect to each other.
+4. **[Configure access controls](/sso-rbac/rbac-overview)** - Ensure proper data governance.
+5. **[Define standards](/scorecards/overview)** - Create scorecards that encode your quality requirements.
+
+As you build your catalog, you're simultaneously building your Context Lake—the unified knowledge layer that powers intelligent automation and AI-driven workflows.
+
+
+

docs/ai-interfaces/overview.md

@@ -5,15 +5,23 @@ 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 AI Agents in **closed beta**.
+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**.
 
 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)**
 
+## What makes Port's AI different
+
+Port's AI interfaces are powered by its [Context Lake](/ai-interfaces/context-lake) - your unified engineering knowledge layer that connects data from across your entire toolchain. Port's AI understands YOUR organization: your service ownership, deployment patterns, team structures, quality standards, and operational context.
+
+This organizational intelligence enables AI to provide accurate answers about who owns what, make decisions within your governance guardrails, and take actions that align with your engineering standards.
+
+**[Learn more about Context Lake →](/ai-interfaces/context-lake)**
+
 ## Port's AI Offerings
 
-:::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 BetaFeatureNotice from '/docs/generalTemplates/_beta_feature_notice.md'
+
+<BetaFeatureNotice id="ai-form" />
 
 
 ### Port AI
@@ -42,7 +50,7 @@ Perfect for immediate insights without dedicated customizations. No agents, no c
 
 
 ### AI Agents
-Customize and orchestrate complicated workflows inside Port. Build intelligent agents that can be used as part of automations and engineering workflows. **Currently in closed beta.**
+Customize and orchestrate complicated workflows inside Port. Build intelligent agents that can be used as part of automations and engineering workflows.
 
 **Use AI Agents to:**
 * Automate incident response workflows
@@ -74,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.**
+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.
 
 **[Learn about the Slack App →](/ai-interfaces/slack-app)**
 
@@ -99,7 +107,7 @@ Use the **Slack App** to make AI insights available to your entire team in your
 
 Port offers four main AI interfaces:
 - **Port AI Assistant**: Chat interface for quick questions and insights.
-- **AI Agents**: Customizable workflows for automations (closed beta).
+- **AI Agents**: Customizable workflows for automations.
 - **MCP Server**: IDE integration for development workflows.
 - **Slack App**: Team collaboration interface (closed beta).
 </details>
@@ -119,18 +127,18 @@ For most users, start with **Port AI Assistant** - it provides immediate value w
 
 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)**
 
-For custom workflows or automation, explore **AI Agents** (requires closed beta access). **[Learn about AI Agents →](/ai-interfaces/ai-agents/overview)**
+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)**
 </details>
 
 <details>
 <summary>What's the current availability status of Port's AI features? (Click to expand)</summary>
 
-- **Port AI Assistant**: Closed beta - gradually rolling out to users.
+- **Port AI Assistant**: Open beta - available to all 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.
+- **AI Agents**: Open beta - available to all users.
+- **Slack App**: Closed beta - not accepting new applications at the moment.
 </details>
 
 <details>

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

@@ -3,11 +3,11 @@ sidebar_position: 2
 title: Port AI Assistant
 ---
 
+import BetaFeatureNotice from '/docs/generalTemplates/_beta_feature_notice.md'
+
 # 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.
-:::
+<BetaFeatureNotice id="ai-form" />
 
 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.
 

docs/ai-interfaces/port-ai/api-interaction.md

@@ -8,9 +8,9 @@ import TabItem from "@theme/TabItem"
 
 # Port AI API Interaction
 
-:::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 BetaFeatureNotice from '/docs/generalTemplates/_beta_feature_notice.md'
+
+<BetaFeatureNotice id="ai-form" />
 
 Port AI can be accessed programmatically through Port's API, enabling integration into custom applications and workflows. This provides the most flexible way to incorporate Port AI capabilities into your existing tools and processes.
 

docs/ai-interfaces/port-ai/context-engineering.md

@@ -8,9 +8,9 @@ import TabItem from "@theme/TabItem"
 
 # Context Engineering with Port AI
 
-:::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 BetaFeatureNotice from '/docs/generalTemplates/_beta_feature_notice.md'
+
+<BetaFeatureNotice id="ai-form" />
 
 Context engineering is the practice of constructing an optimal information environment that provides the right amount of directions, tools, and knowledge for AI systems to successfully solve problems. Unlike prompt engineering, which focuses on crafting individual requests, context engineering ensures AI has access to relevant, structured data and capabilities needed for consistent, accurate results.