Merge branch 'main' into setup-task-manager-ai-agent-with-new-agent-tool-call

Author: sivanel97

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/context-lake.md

@@ -0,0 +1,113 @@
+---
+sidebar_position: 9
+title: Context Lake
+sidebar_label: Context Lake
+---
+
+import Tabs from "@theme/Tabs"
+import TabItem from "@theme/TabItem"
+
+# Context lake
+
+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

@@ -9,6 +9,14 @@ Port's AI interfaces provide intelligent assistance across your entire software
 
 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