docs: add workflow concurrency limits to platform limits page (#104)

* docs: add workflow concurrency limits to platform limits page

* docs: broaden best practices intro to cover all platform limits

* docs: use consistent inline code formatting for status values

Author: k1LoW

docs/reference/platform/platform-limits.md

@@ -8,9 +8,11 @@ Platform limits are enforced across different services in the Tailor Platform to
 
 ## Service Limits
 
-| Service              | Limit Type | Limit Value | Description                                                                     | Impact                                                            |
-| -------------------- | ---------- | ----------- | ------------------------------------------------------------------------------- | ----------------------------------------------------------------- |
-| Recursive Call Limit | Call Depth | 10 levels   | Max depth for nested platform-to-platform requests (pipelines, functions, etc.) | Request rejected with BadRequest error if depth exceeds 10 levels |
+| Service              | Limit Type                      | Limit Value   | Description                                                                     | Impact                                                                                  |
+| -------------------- | ------------------------------- | ------------- | ------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
+| Recursive Call Limit | Call Depth                      | 10 levels     | Max depth for nested platform-to-platform requests (pipelines, functions, etc.) | Request rejected with BadRequest error if depth exceeds 10 levels                       |
+| Workflow             | Workspace Concurrent Executions | 50 executions | Max concurrent workflow executions per workspace                                | Pending executions remain in `PENDING` status until running executions drop below the cap |
+| Workflow             | Per-Workflow Concurrent Executions | 20 executions | Max concurrent executions of a single workflow                                  | Pending executions remain in `PENDING` status until running executions drop below the cap |
 
 ## Recursive Call Detection
 
@@ -34,9 +36,28 @@ This limit prevents issues in scenarios such as:
 - Executor workflows that create cascading service calls
 - Event loops where service operations trigger events that cause the same operations to execute again
 
+## Workflow Concurrency Limits
+
+The Tailor Platform enforces concurrency limits on workflow executions at the scheduler level to prevent resource exhaustion and ensure fair scheduling across workspaces.
+
+### How It Works
+
+Two independent limits control the number of concurrent workflow executions:
+
+- **Workspace-wide limit (50)**: Caps the total number of concurrently running workflow executions within a single workspace. This prevents any one workspace from monopolizing platform resources.
+- **Per-workflow limit (20)**: Caps the number of concurrently running executions of the same workflow definition. This prevents a single high-volume workflow from starving other workflows in the workspace.
+
+When either limit is reached, new executions are not rejected. Instead, they remain in `PENDING` status and are re-evaluated on the next scheduler polling tick. Once running executions complete and slots become available, pending executions are transitioned to `RUNNING` automatically.
+
+### Behavior
+
+- Both limits are enforced independently. An execution must satisfy both limits to start running.
+- If the workspace-wide limit is reached, no new executions start in that workspace regardless of per-workflow counts.
+- If the per-workflow limit is reached for a specific workflow, other workflows in the same workspace can still start new executions (as long as the workspace-wide limit is not reached).
+
 ## Best Practices
 
-When working with services that have call depth limits, consider the following best practices:
+When working within platform limits, consider the following best practices:
 
 1. **Avoid deep service nesting**: Design workflows to minimize the depth of service-to-service calls. Consider flattening complex nested operations or using alternative patterns like event-driven architectures with proper safeguards.
 
@@ -45,3 +66,5 @@ When working with services that have call depth limits, consider the following b
 1. **Design for limits**: Anticipate depth limits and handle them gracefully in your application logic.
 
 1. **Use alternative patterns**: Consider using event-driven architectures, queuing systems, or batch processing for complex workflows that might exceed depth limits.
+
+1. **Design for workflow concurrency**: If your application triggers many workflow executions simultaneously, be aware that excess executions will queue as `PENDING`. Design your application to handle this gracefully rather than assuming immediate execution.