Merge branch 'main' into PORT-ai-security-agent

Author: PeyGis

.gitignore

@@ -27,4 +27,4 @@ yarn-error.log*
 .github/script/__pycache__
 
 # Generated guide metadata
-src/components/guides-section/guide-metadata.json
+/src/components/guides-section/guide-metadata.json

archive/complete-use-cases/_iac-templates.md

@@ -71,7 +71,7 @@ Forwarding                    https://1234-5678-9101-112-1314-1516-abcd-efgh-ijk
 
 Keep the `Forwarding URL` for later use.
 
-### Setup Port resources
+### Set up Port resources
 
 First, set up a Blueprint for an S3 bucket in Port.
 

docs/_quickstart.md

@@ -114,7 +114,7 @@ Take a look at your `Service` blueprint, it has a `Production Readiness` scoreca
 
 **Learn more:**
 
-- [Promote scorecards](https://docs.port.io/promote-scorecards/overview)
+- [Promote scorecards](https://docs.port.io/scorecards/overview)
 
 ---
 

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

@@ -11,7 +11,7 @@ import TabItem from "@theme/TabItem"
 Port provides granular control to make sure every user can only execute and invoke the actions that are relevant for them.
 
 :::tip
-This section covers the self-service actions section of Port's RBAC functionality, while it is not a prerequisite, it is highly recommended you also go over Port's [permission controls](/sso-rbac/rbac/rbac.md).
+This section covers the self-service actions section of Port's RBAC functionality, while it is not a prerequisite, it is highly recommended you also go over Port's [permission controls](/sso-rbac/users-and-teams/manage-users-teams).
 
 In order to manage who can view which pages in Port, check out [page permissions](/customize-pages-dashboards-and-plugins/page/page-permissions.md).
 :::

docs/actions-and-automations/create-self-service-experiences/setup-ui-for-action/setup-ui-for-action.md

@@ -1,5 +1,5 @@
 ---
-title: Setup Actions
+title: Set up Actions
 ---
 
 import ApiRef from "/docs/api-reference/\_learn_more_reference.mdx";
@@ -8,7 +8,7 @@ import Tabs from "@theme/Tabs"
 import TabItem from "@theme/TabItem"
 import PortTooltip from "/src/components/tooltip/tooltip.jsx"
 
-# Setup frontend
+# Set up frontend
 
 <center>
 

docs/actions-and-automations/setup-backend/webhook/examples/terraform-no-code-resource-provisioning.md

@@ -71,7 +71,7 @@ Forwarding                    https://1234-5678-9101-112-1314-1516-abcd-efgh-ijk
 
 Keep the `Forwarding URL` for later use.
 
-### Setup Port resources
+### Set up Port resources
 
 First, set up a [blueprint](/build-your-software-catalog/customize-integrations/configure-data-model/setup-blueprint/setup-blueprint.md) for an S3 bucket in Port.
 

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

@@ -143,6 +143,37 @@ curl 'https://api.port.io/v1/agent/<AGENT_IDENTIFIER>/invoke?stream=true' \\
   --data-raw '{"prompt":"What is my next task?"}'
 ```
 
+**Processing Quota Information:**
+
+When processing the streaming response, you'll receive quota usage information in the final `done` event. Here's a JavaScript example of how to handle this:
+
+```javascript showLineNumbers
+const eventSource = new EventSource(apiUrl);
+
+eventSource.addEventListener('done', (event) => {
+  const data = JSON.parse(event.data);
+  
+  if (data.quotaUsage) {
+    const { remainingRequests, remainingTokens, remainingTimeMs } = data.quotaUsage;
+    
+    // Check if quota is running low
+    if (remainingRequests < 10 || remainingTokens < 10000) {
+      console.warn('Quota running low, consider rate limiting');
+      // Implement rate limiting logic
+    }
+    
+    // Schedule next request after quota reset if needed
+    if (remainingRequests === 0) {
+      setTimeout(() => {
+        // Safe to make next request
+      }, remainingTimeMs);
+    }
+  }
+  
+  eventSource.close();
+});
+```
+
 **Using MCP Server Backend Mode via API:**
 
 You can override the agent's default backend mode by adding the `use_mcp` parameter:
@@ -182,7 +213,13 @@ event: execution
 data: Your final answer from the agent.
 
 event: done
-data: {}
+data: {
+  "maxRequests": 200,
+  "remainingRequests": 193,
+  "maxTokens": 200000,
+  "remainingTokens": 179910,
+  "remainingTimeMs": 903
+}
 ```
 
 **Possible Event Types:**
@@ -242,11 +279,30 @@ The final textual answer or a chunk of the answer from the agent for the user. F
 <details>
 <summary><b><code>done</code> (Click to expand)</b></summary>
 
-Signals that the agent has finished processing and the response stream is complete.
+Signals that the agent has finished processing and the response stream is complete. This event also includes quota usage information for managing your API limits.
 
-```json
-{}
+```json showLineNumbers
+{
+  "quotaUsage": {
+    "maxRequests": 200,
+    "remainingRequests": 193,
+    "maxTokens": 200000,
+    "remainingTokens": 179910,
+    "remainingTimeMs": 903
+  }
+}
 ```
+
+**Quota Usage Fields:**
+- `maxRequests`: Maximum number of requests allowed in the current rolling window
+- `remainingRequests`: Number of requests remaining in the current window
+- `maxTokens`: Maximum number of tokens allowed in the current rolling window  
+- `remainingTokens`: Number of tokens remaining in the current window
+- `remainingTimeMs`: Time in milliseconds until the rolling window resets
+
+:::tip Managing quota usage
+Use the quota information in the `done` event to implement client-side rate limiting and avoid hitting API limits. When `remainingRequests` or `remainingTokens` are low, consider adding delays between requests or queuing them for later execution.
+:::
 </details>
 
 </TabItem>
@@ -344,6 +400,8 @@ Port applies limits to AI agent interactions to ensure fair usage across all cus
 - **Query limit**: ~40 queries per hour.
 - **Token usage limit**: 800,000 tokens per hour.
 
+You can view your quota limits are available in the API response.
+
 :::caution Usage limits
 Usage limits may change without prior notice. Once a limit is reached, you will need to wait until it resets.  
 If you attempt to interact with an agent after reaching a limit, you will receive an error message indicating that the limit has been exceeded.
@@ -448,6 +506,17 @@ Ensure that:
 The AI invocation entity contains the `feedback` property where you can mark is as `Negative` or `Positive`. We're working on adding a more convenient way to rate conversation from Slack and from the UI.
 </details>
 
+<details>
+<summary><b>What are the usage limits and how can I know them? (Click to expand)</b></summary>
+
+Port applies the following limits to AI agent interactions:
+- **Query limit**: ~40 queries per hour
+- **Token usage limit**: 800,000 tokens per hour
+
+You can monitor your current usage in the final `done` event showing your remaining requests, tokens, and reset time.
+
+</details>
+
 <details>
 <summary><b>How is my data with AI agents handled? (Click to expand)</b></summary>