Merge branch 'main' into improve-k8s-docs

Author: nivm-port

docs/actions-and-automations/setup-backend/create-update-entity/create-update-entity.md

@@ -1,3 +1,6 @@
+import Tabs from "@theme/Tabs"
+import TabItem from "@theme/TabItem"
+
 # Create/update entity
 
 In some cases, we don't want to run complex logic via a workflow or pipeline, but rather want our backend to simply create or update an entity in our software catalog.  
@@ -33,15 +36,15 @@ To use this backend type, you will need to define the following fields:
     | `team` | The team/s this entity will belong to. |
     | `icon` | The icon of the entity. |
     | `properties` | The properties of the entity, in `"key":"value"` pairs where the key is the property's identifier, and the value is its value. |
-    | `relations` | The relations of the entity, in `"key":"value"` pairs where the key is the relation's identifier, and the value is the related entity's identifier. |
+    | `relations` | The relations of the entity, in `"key":"value"` pairs where the key is the relation's identifier, and the value is the related entity's identifier (for single relations) or an array of identifiers (for "many" relations). |
 
 ### Use jq to map the entity
 
 All fields in the `mapping` object can be mapped using `jq` expressions, by wrapping the value in double curly braces `{{ }}`.  
 
 For example, say we want to assign the initiator of the action to a new entity when it is created, we can take his email from the action run object and assign it to a property named `assignee`:
 
-```json
+```json showLineNumbers
 {
   "identifier": "someTaskEntity",
   "title": "Some Task",
@@ -55,3 +58,106 @@ For example, say we want to assign the initiator of the action to a new entity w
 :::tip Test your mapping
 You can use the `Test JQ` button in the bottom-left corner to test your mapping against the action's schema.
 :::
+
+## Map entity relations
+
+When creating or updating entities, you often need to establish relations with other entities. The mapping approach depends on whether you're dealing with single or multiple entity inputs.
+
+
+<Tabs groupId="relation-mapping" defaultValue="single" values={[
+{label: "Single Entity", value: "single"},
+{label: "Array Entity", value: "array"},
+{label: "Flexible Mapping", value: "flexible"}
+]}>
+
+<TabItem value="single">
+
+For a single entity relation, map the entity identifier directly:
+
+```json showLineNumbers
+{
+  "identifier": "myServiceEntity",
+  "title": "My Service",
+  "properties": {},
+  "relations": {
+    "domain": "{{ .inputs.domain }}"
+  }
+}
+```
+
+</TabItem>
+
+<TabItem value="array">
+
+When your action accepts [array entity inputs](/docs/actions-and-automations/create-self-service-experiences/setup-ui-for-action/user-inputs/entity.md#array), you need to extract the identifiers from the array using the `map(.identifier)` pattern:
+
+```json showLineNumbers
+{
+  "identifier": "myUserEntity", 
+  "title": "My User",
+  "properties": {},
+  "relations": {
+    "skills": "{{ .inputs.skills | map(.identifier) }}"
+  }
+}
+```
+
+:::info Array entity inputs
+When users select multiple entities from an [entity array input](/docs/actions-and-automations/create-self-service-experiences/setup-ui-for-action/user-inputs/entity.md#array), the input contains an array of entity objects. Each object includes both `identifier` and `title` properties, but relations can only reference entity identifiers.
+:::
+
+</TabItem>
+
+<TabItem value="flexible">
+
+For maximum flexibility, you can create a conditional mapping that handles both single entity and array entity inputs:
+
+```json showLineNumbers
+{
+  "identifier": "myProjectEntity",
+  "title": "My Project", 
+  "properties": {},
+  "relations": {
+    "dependencies": "{{ .inputs.dependencies | if type == \"array\" then map(.identifier) else .identifier end }}"
+  }
+}
+```
+
+This pattern automatically:
+- Extracts identifiers from arrays when multiple entities are selected
+- Uses the identifier directly when a single entity is selected
+
+</TabItem>
+
+</Tabs>
+
+
+### Common use cases
+
+Here are some typical scenarios for mapping array relations:
+
+**Mapping skills to a user:**
+```json showLineNumbers
+"relations": {
+  "skills": "{{ .inputs.selectedSkills | map(.identifier) }}"
+}
+```
+
+**Mapping team members to a project:**
+```json showLineNumbers
+"relations": {
+  "members": "{{ .inputs.teamMembers | map(.identifier) }}"
+}
+```
+
+**Mapping dependencies between services:**
+```json showLineNumbers
+"relations": {
+  "dependsOn": "{{ .inputs.dependencies | map(.identifier) }}"
+}
+```
+
+
+:::info Entity titles in relations
+Relations can only reference entity **identifiers**, not titles. Even though entity objects contain both `identifier` and `title` properties, you must always use `.identifier` when mapping to relations.
+:::

docs/ai-agents/overview.md

@@ -89,6 +89,20 @@ The data model of AI agents includes two main blueprints:
 
 2. **AI invocations** - Each interaction made with an AI agent is recorded as an invocation. This acts as a log of everything going through your AI agents so you can monitor and improve them over time. Learn more in our [Interact with AI agents](/ai-agents/interact-with-ai-agents) guide.
 
+## Relevant guides
+
+Explore these guides to see AI agents in action and learn how to implement them in your organization:
+
+- [Generate incident updates with AI](/guides/all/generate-incident-updates-with-ai)
+- [Enrich tasks with AI-powered context](/guides/all/enrich-tasks-with-ai)
+- [Setup PR enricher AI agent](/guides/all/setup-pr-enricher-ai-agent)
+- [Setup service explorer AI agent](/guides/all/setup-service-explorer-ai-agent)
+- [Setup platform request triage AI agent](/guides/all/setup-platform-request-triage-ai-agent)
+- [Setup task manager AI agent](/guides/all/setup-task-manager-ai-agent)
+- [Setup incident manager AI agent](/guides/all/setup-incident-manager-ai-agent)
+- [Add RCA context to AI agents](/guides/all/add-rca-context-to-ai-agents)
+- [Enrich security vulnerability using AI](/guides/all/enrich-security-vulnerability-using-ai)
+
 ## Frequently asked questions
 
 <details>

docs/ai-agents/port-mcp-server.md

@@ -14,7 +14,7 @@ import TabItem from "@theme/TabItem"
     style={{borderRadius:'4px'}}
     width="568"
     height="320"
-    src="https://www.youtube.com/embed/hxUTTPSApQs" 
+    src="https://www.youtube.com/embed/WrVgQ-whBiE" 
     title="YouTube video player" 
     frameborder="0" 
     allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" 
@@ -49,6 +49,21 @@ The Port MCP Server directly enables these kinds of valuable, in-context interac
 
 ## Key capabilities and use-cases
 
+<center>
+<div className="video-container">
+  <iframe 
+    style={{borderRadius:'4px'}}
+    width="568"
+    height="320"
+    src="https://www.youtube.com/embed/hxUTTPSApQs" 
+    title="YouTube video player" 
+    frameborder="0" 
+    allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" 
+    allowfullscreen>
+  </iframe>
+</div>
+</center>
+
 The Port MCP Server enables you to interact with your Port data and capabilities directly through natural language within your chosen LLM-powered tools. Here's what you can achieve:
 
 ### Find information quickly
@@ -97,6 +112,11 @@ Receive assistance with common development and operational tasks, directly withi
 
 ![Getting instructions for new service setup](/img/ai-agents/MCPClaudeServiceSetup.png)
 
+### Find your own use cases
+
+You can use Port's MCP to find the use cases that will be valuable to you. Try using this prompt: "think of creative prompts I can use to showcase the power of Port's MCP, based on the data available in Port"
+
+
 ## Using Port MCP
 
 ### Setup

docs/api-reference/pages.mdx

@@ -6,6 +6,8 @@
 
 Port API's `pages` endpoints will undergo a structural change in the near future. The new structure will be more intuitive and easier to use.
 
+Until the new structure is released, you can refer to the [Swagger API documentation](https://api.port.io/swagger/#Pages) for the available endpoints and their usage.
+
 Currently, the `pages` endpoints allow you to:
 
 - **Create**, **update**, **delete**, and **get** pages.

docs/build-your-software-catalog/sync-data-to-catalog/git/azure-devops/mapping_extensions.md

@@ -45,4 +45,38 @@ To do so, we will use the `file://` prefix with the path of the file to tell the
             url: .remoteUrl
             // highlight-next-line
             readme: file://README.md
-```
+```
+
+## Link pipelines to repositories via selector
+You can configure your selector to include repository information in the pipeline entity mapping.
+This allows you to create a direct relationship between a pipeline and its source repository.
+
+```yaml showLineNumbers
+- kind: pipeline
+  selector:
+    query: 'true'
+    # highlight-next-line
+    includeRepo: 'true'
+  port:
+    entity:
+      mappings:
+        identifier: .id | tostring
+        title: .name
+        blueprint: '"azureDevOpsPipeline"'
+        properties:
+          url: .url
+          revision: .revision
+          folder: .folder
+        relations:
+          project: .__projectId | gsub(" "; "")
+          repository: >-
+            if .__repository
+            then .__repository.project.name + "/" + .__repository.name | gsub(" "; "")
+            else null
+            end
+```
+:::tip Recommendation
+Use this only when necessary, as including repository data requires an extra API call per pipeline, which increases the number of requests made and can impact your Azure DevOps API rate limits.
+
+If you don’t require repo-level linkage, it’s more efficient to relate pipelines → projects instead.
+:::

docs/customize-pages-dashboards-and-plugins/page/entity-page.md

@@ -43,9 +43,75 @@ Since we changed direction midway, this relation is **indirect**:
 
 When looking at the entity page of a certain `Workflow Run`, the related entities `Deployment Workflow` and `Service` automatically appear, but `Deployment` does not, since its relation is in the other direction.
 
-You can add additional entities to the `Related entities` table by clicking on the `+` button above the table.  
+### Add a Related entities tab
 
-In the form that appears, the `Related blueprint` dropdown will display all entities that are related in any way to the current entity. In our `Workflow Run` example above, we can use this button to add a `Deployment` tab to our widget.
+Click the `+` button above the table to add a custom tab.   
+
+1. Set the tab's `Name` and optional `Description`.
+
+2. Choose the `Related blueprint` you want to display.
+
+3. Pick a `Relation path`:
+
+   - **All paths** – includes all available paths from the current blueprint to the target blueprint.
+   - **Specific path** – choose one specific relation chain (multi‑hop is supported).
+
+4. (Optional) Add `Additional filters` to restrict the result set.
+
+:::tip Relation path options
+Use "all paths" for a broad overview. Choose a specific path when multiple paths exist to the same blueprint and you want the tab to reflect exactly one path.
+:::
+
+
+#### Filters and Edit JSON
+
+Selecting `Filters` opens a dialog where you can build conditions using form controls (property, operator, value).   
+You can switch to a JSON editor using the `Edit JSON` button to define the dataset directly.
+
+The dataset follows this structure:
+
+```json showLineNumbers
+{
+  "combinator": "and",
+  "rules": [
+    {
+      "property": "$title",
+      "operator": "contains",
+      "value": "awesome-package"
+    }
+  ]
+}
+```
+
+
+Use the JSON editor when you need to copy/paste filter sets, keep them in source control, or express conditions that are faster to author as JSON. You can toggle back to the form at any time.
+
+<h4>Define the tab in JSON mode</h4>
+
+You can also toggle `Json Mode` in the "Add tab" dialog to author the entire tab as JSON. An example:
+
+```json showLineNumbers
+{
+  "dataset": {
+    "combinator": "and",
+    "rules": [
+      {
+        "property": "$title",
+        "operator": "contains",
+        "value": "awesome-package"
+      }
+    ]
+  },
+  "title": "custom path package",
+  "targetBlueprint": "Package",
+  "relationPath": {
+    "path": ["service_in_env", "package"],
+    "fromBlueprint": "service_in_env_deployments"
+  }
+}
+```
+
+This JSON corresponds to a tab named `custom path package` that targets the `Package` blueprint, follows a specific path from `service_in_env_deployments` via `service_in_env` to `package`, and filters results to titles containing the letter `awesome-package`.
 
 #### Show/hide columns