Add documentation for environment management

documentation/docs/tutorials/configure-identity-providers.mdx → documentation/docs/administration/configure-identity-providers.mdx

@@ -5,7 +5,7 @@ sidebar_position: 7
 # Configure Identity Providers
 
 Identity providers are the token issuers your gateway trusts. When an agent endpoint is secured
-with [OAuth](./secure-agent-endpoints-with-oauth.mdx), the gateway validates incoming JWTs
+with [OAuth](../tutorials/secure-agent-endpoints-with-oauth.mdx), the gateway validates incoming JWTs
 against the identity providers configured on it. Each agent then chooses which of those
 providers it accepts.
 
@@ -89,4 +89,4 @@ deploy successfully while the gateway rejects every token at runtime.
 - A provider name is unique within a gateway.
 - `ThunderKeyManager` is the bundled default identity provider.
 - After adding a provider, secure an agent with it by following
-  [Secure Agent Endpoints with OAuth](./secure-agent-endpoints-with-oauth.mdx).
+  [Secure Agent Endpoints with OAuth](../tutorials/secure-agent-endpoints-with-oauth.mdx).

documentation/docs/administration/environment-management.mdx

@@ -0,0 +1,133 @@
+---
+sidebar_position: 2
+---
+
+# Manage Environments and Deployment Pipelines
+
+Environments and deployment pipelines are organization-level constructs that control *where* your agents run and *how* they are promoted from one stage to the next (for example `Development → Staging → Production`).
+
+- An **environment** represents a runtime context (e.g., `dev`, `test`, `staging`, `production`) where agents are deployed and executed.
+- A **deployment pipeline** defines an ordered promotion path across those environments.
+- Each **project** is assigned one deployment pipeline, and agents in that project are **promoted** along its path.
+
+Both environments and deployment pipelines live under the **Infrastructure** section of the organization-level navigation.
+
+## Prerequisites
+
+- Admin access to the WSO2 Agent Manager Console.
+- A terminal with `kubectl` and `helm` configured against your cluster (environments are provisioned and removed by a script that installs/uninstalls an API Platform Gateway via Helm).
+- At least one [AI Gateway registered](./register-ai-gateway.mdx) and active.
+
+---
+
+## Managing Environments
+
+### Navigate to Environments
+
+1. Log in to the WSO2 Agent Manager Console.
+2. Go to the organization level by closing the projects section in the top navigation.
+3. In the left sidebar, click **Environments** under the **INFRASTRUCTURE** section.
+
+   > The Environments page lists every environment with its display name, associated gateway, and whether it is a production environment.
+
+### Create an environment
+
+Environments are provisioned by a script that creates the environment in Agent Manager and installs its API Platform Gateway via Helm. The Console builds the command for you.
+
+1. Click **Create Environment**.
+2. Fill in the environment details.
+
+   | Field | Description | Example |
+   |---|---|---|
+   | **Display Name** | Human-readable name shown throughout the Console. | `Production` |
+   | **Production environment** | Mark this environment as production. Production environments are typically the last stage of a pipeline. | — |
+
+3. Copy the generated command using the copy icon. Your access token is substituted into the command automatically when you copy.
+4. Run the command from a terminal that has `kubectl` and `helm` configured against your cluster.
+
+   The script creates the environment in Agent Manager and provisions an API Platform Gateway for that environment via Helm.
+
+   > The script is idempotent — it is safe to re-run. Once it completes, the new environment appears in the list.
+
+### Delete an environment
+
+1. On the Environments page, open the **Delete** action for the environment you want to remove.
+2. Copy the generated command and run it from a terminal configured against your cluster (again with `kubectl` and `helm` configured).
+
+   The script uninstalls the environment's API Platform Gateway Helm release and then deletes the environment in Agent Manager.
+
+   > **Warning:** Deleting an environment is permanent and cannot be undone. Any agent deployed to the environment will no longer be reachable, and the deployment will be permanently deleted.
+
+:::note
+An environment cannot be deleted while it is still referenced by a deployment pipeline. Remove it from any pipeline first.
+:::
+
+---
+
+## Managing Deployment Pipelines
+
+A deployment pipeline defines the promotion path agents follow across environments. 
+
+### Navigate to Deployment Pipelines
+
+1. At the organization level, open the left sidebar.
+2. Click **Deployment Pipelines** under the **INFRASTRUCTURE** section.
+
+   > The page lists each pipeline with its promotion chain rendered.
+
+### Create a deployment pipeline
+
+1. Click **Create Pipeline**.
+2. Under **Pipeline Details**, enter:
+
+   | Field | Description | Example |
+   |---|---|---|
+   | **Display Name** | Human-readable name for the pipeline (required). | `Production Pipeline` |
+   | **Description** | Optional description. | `Dev to Prod promotion path` |
+
+3. In the pipeline chain editor, add environments in the order agents should be promoted through them. The chain must contain at least one environment and must form a single linear path.
+4. Click **Create**.
+
+### Delete a deployment pipeline
+
+1. On the Deployment Pipelines page, hover over the pipeline row and click the **Delete**  icon.
+2. Confirm in the dialog.
+
+   > **Warning:** Deleting a pipeline cannot be undone. Reassign any project that uses the pipeline to a different one first.
+
+:::note
+A deployment pipeline cannot be deleted while it is still referenced by a project. Reassign any project that uses it to a different pipeline first (see [updating a project's deployment pipeline](#update-a-projects-deployment-pipeline)).
+:::
+
+---
+
+## Update a project's deployment pipeline
+
+Every project is assigned a deployment pipeline, which determines the environments its agents can be promoted through.
+
+1. At the organization level, open the **Projects** list.
+2. Open the **Edit** action for the project you want to change.
+3. In the **Edit Project** drawer, open the **Deployment Pipeline** dropdown. Each option shows the pipeline name and its promotion chain.
+4. Select the pipeline you want and click **Update Project**.
+
+   > A deployment pipeline is required for a project. Changing it changes the promotion path available to all agents in the project.
+
+---
+
+## Promote an agent
+
+Promoting an agent deploys it from one environment to the next environment in the project's deployment pipeline.
+
+1. Open the agent and go to its **Deploy** page. Each environment in the pipeline is shown as a card.
+2. On the source environment's card, click **Promote**.
+
+   > The **Promote** button appears only when the environment has a downstream target in the project's pipeline and the agent is currently **Active** in that environment.
+
+3. In the **Promote** drawer:
+   - **Target Environment** — if the source has more than one possible next environment, select the target.
+   - **Configuration** — choose how the target is configured:
+     - Enable **Use config from source environment** to inherit the source environment's environment variables and file mounts.
+     - Leave it disabled to set environment-specific **Environment Variables** and **File Mounts** for the target environment.
+4. Click **Promote**.
+
+The same build is deployed to the target environment with the configuration you supplied. Repeat the process to advance the agent along the rest of the pipeline.

documentation/docs/getting-started/create-your-first-agent.mdx

@@ -122,7 +122,7 @@ Click **Deploy** to build and deploy the agent.
 | Tutorial | Description |
 |----------|-------------|
 | [Observe Your First Agent](../tutorials/observe-first-agent.mdx) | Set up OpenTelemetry tracing for your agent |
-| [Register an AI Gateway](../tutorials/register-ai-gateway.mdx) | Connect an LLM provider via the AI gateway |
+| [Register an AI Gateway](../administration/register-ai-gateway.mdx) | Connect an LLM provider via the AI gateway |
 | [Register an LLM Service Provider](../tutorials/register-llm-service-provider.mdx) | Add and configure LLM providers |
 | [Secure Agent Endpoints with API Keys](../tutorials/secure-agent-endpoints-with-api-keys.mdx) | Protect endpoints with API key authentication |
 | [Evaluation Monitors](../tutorials/evaluation-monitors.mdx) | Automate quality checks for your agents |

documentation/docs/tutorials/register-llm-service-provider.mdx

@@ -13,7 +13,7 @@ You can also create, list, and delete providers from the command line — see [`
 ## Prerequisites
 
 - Admin access to the WSO2 Agent Manager Console
-- At least one AI Gateway registered and active (see [Register an AI Gateway](./register-ai-gateway.mdx))
+- At least one AI Gateway registered and active (see [Register an AI Gateway](../administration/register-ai-gateway.mdx))
 - API credentials for the target LLM provider (e.g., an OpenAI API key)
 
 ---

documentation/docs/tutorials/register-mcp-proxy.mdx

@@ -16,7 +16,7 @@ Proxying an MCP server through the platform lets you:
 ## Prerequisites
 
 - Admin access to the WSO2 Agent Manager Console
-- At least one AI Gateway registered and active (see [Register an AI Gateway](./register-ai-gateway.mdx))
+- At least one AI Gateway registered and active (see [Register an AI Gateway](../administration/register-ai-gateway.mdx))
 - A reachable upstream MCP server endpoint (e.g., `https://api.example.com/mcp`)
 - Any credential the upstream MCP server requires (e.g., an API key passed in an HTTP header)
 

documentation/docs/tutorials/secure-agent-endpoints-with-oauth.mdx

@@ -6,7 +6,7 @@ sidebar_position: 8
 
 OAuth security protects platform-hosted API agent endpoints at the gateway. When enabled,
 callers must send a valid JWT, by default in the `Authorization: Bearer <token>` header. The
-gateway validates the token against the [identity providers](./configure-identity-providers.mdx)
+gateway validates the token against the [identity providers](../administration/configure-identity-providers.mdx)
 you select for the agent.
 
 OAuth and [API key security](./secure-agent-endpoints-with-api-keys.mdx) are mutually exclusive —
@@ -15,7 +15,7 @@ an agent uses one or the other, not both.
 ## Prerequisites
 
 - A platform-hosted API agent created in a project.
-- At least one [identity provider configured](./configure-identity-providers.mdx) on the
+- At least one [identity provider configured](../administration/configure-identity-providers.mdx) on the
   environment's gateway.
 
 ## Step 1: Enable OAuth During Deployment
@@ -73,5 +73,5 @@ key security cannot be active at the same time.
 
 - OAuth security applies to platform-hosted API agents.
 - Accepted issuers and audiences come from the
-  [identity providers configured on the gateway](./configure-identity-providers.mdx).
+  [identity providers configured on the gateway](../administration/configure-identity-providers.mdx).
 - An agent uses one authentication method at a time — OAuth or API key, not both.

documentation/sidebars.ts

@@ -64,6 +64,9 @@ const sidebars: SidebarsConfig = {
       label: 'Administration',
       collapsed: false,
       items: [
+        'administration/register-ai-gateway',
+        'administration/environment-management',
+        'administration/configure-identity-providers',
         'administration/instrumentation-catalog',
       ],
     },
@@ -98,11 +101,9 @@ const sidebars: SidebarsConfig = {
         'tutorials/observe-first-agent',
         'tutorials/evaluation-monitors',
         'tutorials/custom-evaluators',
-        'tutorials/register-ai-gateway',
         'tutorials/register-llm-service-provider',
         'tutorials/register-mcp-proxy',
         'tutorials/secure-agent-endpoints-with-api-keys',
-        'tutorials/configure-identity-providers',
         'tutorials/secure-agent-endpoints-with-oauth',
         'tutorials/configure-cors-for-agent-endpoints',
         'tutorials/configure-agent-llm-configuration',