docs: add Autonomous Agents documentation tab to AI Builder Portal

docs/docs.json

@@ -617,6 +617,23 @@
               }
             ]
           },
+          {
+            "tab": "Autonomous Agents",
+            "icon": "robot",
+            "groups": [
+              {
+                "group": "Autonomous Agents",
+                "pages": [
+                  "rde/agents/overview",
+                  "rde/agents/getting-started",
+                  "rde/agents/agent-blueprints",
+                  "rde/agents/managing-runs",
+                  "rde/agents/linear-integration",
+                  "rde/agents/agent-template"
+                ]
+              }
+            ]
+          },
           {
             "tab": "For Users",
             "icon": "user",

docs/rde/admin/blueprint-management.mdx

@@ -15,6 +15,10 @@ From a technical perspective, each blueprint maps to a **Qovery project and envi
 
 As an admin, you decide what each blueprint contains, who can access it, and what it can connect to. This is where governance happens - invisibly to the builder, but completely under your control. The blueprint itself is a standard Qovery environment, managed through the Qovery Console, CLI, or [Terraform](/rde/admin/blueprint-management#managing-blueprints-with-terraform) as usual.
 
+<Info>
+Blueprints come in two types: **Workspace Blueprints** (the default, covered on this page) and **Agent Blueprints** (for autonomous AI agents). When you click "Create Blueprint", a chooser dialog lets you select the type. For agent blueprint configuration, see [Agent Blueprints](/rde/agents/agent-blueprints).
+</Info>
+
 ## Registering a Blueprint
 
 <Steps>

docs/rde/agents/agent-blueprints.mdx

@@ -0,0 +1,133 @@
+---
+title: "Agent Blueprints"
+description: "Configure blueprints for autonomous AI agents - runtime selection, repository setup, Linear integration, and resource tuning."
+---
+
+import RdePreviewWarning from "/snippets/rde-preview-warning.mdx";
+
+<RdePreviewWarning />
+
+## Overview
+
+An agent blueprint is a blueprint with autonomous mode enabled. It defines which AI runtime to use, which repositories to clone, and how to connect to your project tracker. When a matching issue appears in Linear, the system launches a workspace from this blueprint and runs the agent autonomously.
+
+Agent blueprints share the same underlying infrastructure as workspace blueprints - lifecycle states, target cluster selection, and Qovery environment mapping all work the same way. See [Blueprint Management](/rde/admin/blueprint-management) for those shared concepts.
+
+## Workspace vs Agent Blueprints
+
+| Aspect | Workspace Blueprint | Agent Blueprint |
+|---|---|---|
+| **Purpose** | Human development environment | Autonomous AI agent |
+| **Trigger** | User creates workspace from catalog | Agent @mentioned or assigned on issue |
+| **Appears in catalog** | Yes | No |
+| **Additional config** | None | Runtime, repositories, Linear mapping |
+| **Lifecycle states** | Testing / Enabled / Disabled | Testing / Enabled / Disabled |
+| **Target cluster** | Configurable | Configurable |
+| **Access control** | ACLs apply | N/A (not in user catalog) |
+
+## Configuration Reference
+
+These settings are specific to agent blueprints. They control which runtime executes the agent, how the agent connects to Linear, and how many runs can execute concurrently.
+
+| Setting | Type | Default | Description |
+|---|---|---|---|
+| **Autonomous Enabled** | Boolean | `false` | Enables autonomous mode on the blueprint. When disabled, the blueprint behaves as a standard workspace blueprint. |
+| **Agent Runtime** | Enum | `claude` | The AI coding runtime that drives the agent. See [Runtime Details](#runtime-details) for options. |
+| **Linear Team** | String or null | `null` | The Linear team whose issues the agent monitors. Required when autonomous mode is enabled. |
+| **In-Progress State** | String or null | `null` | The Linear workflow state the issue transitions to when the agent claims it. Required when autonomous mode is enabled. |
+| **In-Review State** | String or null | `null` | The Linear workflow state the issue transitions to when the agent opens a pull request. Optional. |
+| **Needs-Human State** | String or null | `null` | The Linear workflow state the issue transitions to when the agent fails or times out. Optional. |
+| **System Prompt** | String | (empty) | Optional instructions prepended to the issue context when the agent starts. Use this to provide project-specific guidance to the AI runtime. |
+| **Max Concurrent Runs** | Number | `3` | Maximum number of issues the agent works on simultaneously. Each concurrent run launches a separate workspace. |
+| **Run Timeout** | Number (minutes) | `60` | Maximum duration for a single agent run. The workspace is stopped when the timeout is reached, and the issue transitions to the Needs-Human state if configured. |
+
+## Runtime Details
+
+Each agent blueprint specifies one AI coding runtime. The runtime determines which CLI tool runs inside the workspace and which API key environment variable is required.
+
+| Runtime | CLI Command | API Key Env Var |
+|---|---|---|
+| Claude Code | `claude -p` | `ANTHROPIC_API_KEY` |
+| OpenCode | `opencode run` | `ANTHROPIC_API_KEY` |
+| Codex | `codex --full-auto` | `OPENAI_API_KEY` |
+| Gemini CLI | `gemini -p` | `GEMINI_API_KEY` |
+| Cursor CLI | `cursor-agent` | `ANTHROPIC_API_KEY` |
+
+## Resource Defaults
+
+Agent blueprints created through the wizard use these default resource allocations. You can adjust them under **Advanced** during creation or by editing the blueprint later.
+
+| Resource | Default |
+|---|---|
+| CPU | 4000 mCPU (4 vCPU) |
+| Memory | 4096 MB (4 GB) |
+| Storage | 10 GB |
+
+The target cluster defaults to the first non-production cluster in your organization.
+
+## Git Provider Support
+
+Agent blueprints support three git providers for cloning repositories, pushing branches, and creating pull requests:
+
+| Provider | Supported |
+|----------|-----------|
+| GitHub | Yes |
+| GitLab | Yes |
+| Bitbucket | Yes |
+
+The provider is detected automatically from the repository URL configured in the blueprint. The agent template handles authentication, branch creation, and PR creation for all three providers.
+
+## Official Agent Template
+
+Agent blueprints created through the wizard use the [official agent template](https://github.com/Qovery/autonomous-agent-template) (`ghcr.io/qovery/autonomous-agent-template:latest`) as the base Docker image. This image includes all five AI runtimes, development tooling, and the autonomous entrypoint script.
+
+You can extend the template with project-specific dependencies by creating a custom Dockerfile that builds on top of the official image. See [Agent Template](/rde/agents/agent-template) for details on customization, environment variables, and the governance proxy.
+
+## API Key Management
+
+The API key for the selected runtime is stored as an environment variable on the blueprint's Qovery environment. Different runtimes use different environment variable names - see the [Runtime Details](#runtime-details) table for the mapping.
+
+The key is set during blueprint creation when you enter it in the wizard. To update it later:
+
+1. Open the Qovery Console.
+2. Navigate to the project and environment backing the agent blueprint.
+3. Edit the environment variables and update the relevant API key.
+
+<Info>
+The API key is stored encrypted and injected into the workspace container at launch. It is never exposed in the portal UI after initial entry.
+</Info>
+
+## Editing Agent Blueprint Settings
+
+To modify an existing agent blueprint:
+
+1. Navigate to **Admin > Blueprints** in the portal.
+2. Click the blueprint name to open its settings.
+3. Select the **Autonomous** tab.
+
+From this tab you can:
+
+- Enable or disable autonomous mode
+- Change the AI runtime
+- Update the Linear team and workflow state mappings
+- Adjust concurrency limits and run timeout
+
+<Warning>
+The **In-Progress State** is required for the agent to claim issues. If autonomous mode is enabled but no In-Progress state is set, the save button is disabled and the agent cannot run. Configure this field before enabling autonomous mode.
+</Warning>
+
+If the portal does not have Linear connected via OAuth, a warning is displayed on the Autonomous tab prompting you to connect Linear first. See [Linear Integration](/rde/agents/linear-integration#connecting-linear) for setup instructions.
+
+## Next Steps
+
+<CardGroup cols={3}>
+  <Card title="Getting Started" icon="play" href="/rde/agents/getting-started">
+    Set up your first autonomous agent from scratch.
+  </Card>
+  <Card title="Managing Runs" icon="list-check" href="/rde/agents/managing-runs">
+    Monitor active runs, review results, and troubleshoot failures.
+  </Card>
+  <Card title="Linear Integration" icon="arrows-rotate" href="/rde/agents/linear-integration">
+    Configure labels, workflow states, and issue routing.
+  </Card>
+</CardGroup>

docs/rde/agents/agent-template.mdx

@@ -0,0 +1,191 @@
+---
+title: "Agent Template"
+description: "The official Docker image template for running autonomous AI agents on Qovery - architecture, environment variables, customization, and governance."
+---
+
+import RdePreviewWarning from "/snippets/rde-preview-warning.mdx";
+
+<RdePreviewWarning />
+
+## Overview
+
+The [autonomous agent template](https://github.com/Qovery/autonomous-agent-template) is the official Docker image for running headless AI agents on Qovery. When deployed as a workspace, the container automatically fetches a Linear issue, runs an AI agent, opens a pull request, and exits.
+
+You can use the template directly or extend it with project-specific dependencies.
+
+## Quick Start
+
+### Use the image directly
+
+```dockerfile
+FROM ghcr.io/qovery/autonomous-agent-template:latest
+
+# Add your project-specific dependencies
+RUN apt-get update && apt-get install -y your-deps
+```
+
+### Or build from source
+
+```bash
+git clone https://github.com/Qovery/autonomous-agent-template.git
+cd autonomous-agent-template
+docker build -t my-autonomous-agent .
+```
+
+Then register the image as a blueprint in the portal and enable autonomous mode. See [Getting Started](/rde/agents/getting-started) for the full walkthrough.
+
+## How the Agent Run Works
+
+When the portal launches a workspace from the template, the container executes a 7-step autonomous cycle:
+
+<Steps>
+  <Step title="Start governance proxy">
+    If configured, the entrypoint starts an HTTP proxy that intercepts all outbound traffic from the agent and applies organization policies (allowlists, secret detection, rate limiting).
+  </Step>
+
+  <Step title="Fetch the Linear issue">
+    The script reads the issue ID from environment variables, calls the Linear API, and writes the issue title and description to a task file.
+  </Step>
+
+  <Step title="Clone the repository and create a branch">
+    The target repository is cloned using the configured git token. A branch is created automatically from the issue key and title (e.g., `agent/ENG-123-fix-login-validation`).
+  </Step>
+
+  <Step title="Run the AI agent">
+    The configured runtime executes headlessly with the task file as the prompt:
+
+    | Runtime | Command |
+    |---------|---------|
+    | Claude Code | `claude -p "<task>"` |
+    | OpenCode | `opencode run "<task>"` |
+    | Codex | `codex --full-auto "<task>"` |
+    | Gemini CLI | `gemini -p "<task>"` |
+    | Cursor CLI | `cursor-agent "<task>"` |
+
+    The command is wrapped in a `timeout` using the configured run timeout. Exit code 124 indicates a timeout.
+
+    During execution, the agent can stream live progress updates to Linear via the portal's progress endpoint. These appear as real-time "thought" activities in the Linear issue, giving your team visibility into what the agent is doing.
+  </Step>
+
+  <Step title="Commit and push">
+    If the agent made code changes, they are committed and pushed to the branch. If no changes were made, the run reports a failure ("no code changes").
+  </Step>
+
+  <Step title="Open a pull request">
+    A PR is created on the git provider (GitHub, GitLab, or Bitbucket) with the issue context in the body. The PR title includes the Linear issue key.
+  </Step>
+
+  <Step title="Report results">
+    The container calls back to the portal API to record the result. The portal then emits structured activities to the Linear agent session - updating the plan to completed, adding external URLs (dashboard link, PR link), and posting a response or error activity visible inline in Linear. A lifecycle comment is also posted on the issue for audit purposes. The workspace is automatically cleaned up after completion.
+  </Step>
+</Steps>
+
+## Environment Variables
+
+These variables are injected automatically by the portal when it launches the workspace. You do not set them manually.
+
+| Variable | Description |
+|----------|-------------|
+| `LINEAR_API_TOKEN` | Linear API token for reading issues and posting comments |
+| `LINEAR_ISSUE_ID` | Linear issue node ID to work on |
+| `LINEAR_ISSUE_KEY` | Human-readable issue key (e.g., `ENG-123`) |
+| `RDE_AUTONOMOUS_AGENT` | Runtime to use: `claude`, `opencode`, `codex`, `gemini`, or `cursor` |
+| `RDE_RUN_CALLBACK_URL` | Portal API callback URL for reporting results |
+| `RDE_RUN_TIMEOUT_MIN` | Hard timeout for the agent run (minutes) |
+| `RDE_LINEAR_STATE_REVIEW_ID` | Linear workflow state ID for the In-Review transition (optional) |
+| `RDE_LINEAR_STATE_FAILED_ID` | Linear workflow state ID for the Needs-Human transition (optional) |
+| `ANTHROPIC_API_KEY` | API key for Claude Code, OpenCode, or Cursor runtimes |
+| `OPENAI_API_KEY` | API key for Codex runtime |
+| `GEMINI_API_KEY` | API key for Gemini CLI runtime |
+| `BLUEPRINT_GIT_REPOSITORY` | Target repository URL |
+| `BLUEPRINT_GIT_TOKEN` | Git token for clone, push, and PR creation |
+| `BLUEPRINT_GIT_PROVIDER` | Git provider: `github`, `gitlab`, or `bitbucket` |
+
+## Git Provider Support
+
+The template supports three git providers for cloning repositories, pushing branches, and creating pull requests:
+
+| Provider | Value | PR API |
+|----------|-------|--------|
+| GitHub | `github` | GitHub REST API |
+| GitLab | `gitlab` | GitLab REST API |
+| Bitbucket | `bitbucket` | Bitbucket REST API |
+
+The provider is determined by the `BLUEPRINT_GIT_PROVIDER` environment variable, which is set automatically based on the repository URL configured in the agent blueprint.
+
+## RDE Configuration
+
+The template includes a `.config.rde.qovery.yml` file that customizes which components are installed by the Qovery RDE install script. It disables web IDE components that are not needed for headless autonomous mode while keeping all AI runtimes and development tooling.
+
+**Enabled components:**
+- All AI runtimes (Claude Code, OpenCode, Codex, Cursor)
+- Development tools (Node.js, Python, Ruby, Go)
+- Git tooling (gh CLI, Qovery CLI)
+- Terminal utilities (zellij, fzf, ripgrep)
+
+**Disabled components:**
+- Code Server (web IDE) - not needed for headless mode
+- Standard entrypoint - replaced by the autonomous entrypoint
+- Browser-based extensions and resources
+
+See [Blueprint Management](/rde/admin/blueprint-management#official-workspace-template) for details on the RDE install script and `.config.rde.qovery.yml` configuration.
+
+## Agent Governance Proxy
+
+When the `RDE_PROXY_SCRIPT_GZ_B64` environment variable is set, the template starts an HTTP proxy before running the agent. This proxy intercepts all outbound HTTP/HTTPS traffic from the AI agent and enforces organization policies.
+
+The proxy supports:
+- **Allowlists** - restrict which external hosts the agent can reach
+- **Secret detection** - prevent accidental exfiltration of credentials
+- **Rate limiting** - throttle API calls to prevent abuse
+- **Kill switch** - immediately halt all agent egress
+
+The proxy runs on port 8877 and is transparent to the agent. All outbound traffic is routed through it automatically.
+
+<Info>
+The governance proxy is configured at the organization level by the Qovery team. Contact Qovery support to enable and configure proxy policies for your autonomous agents.
+</Info>
+
+## Customizing the Template
+
+To extend the template for your project:
+
+```dockerfile
+FROM ghcr.io/qovery/autonomous-agent-template:latest
+
+# Add project-specific dependencies
+RUN apt-get update && apt-get install -y \
+    postgresql-client \
+    redis-tools
+
+# Add custom agent instructions
+COPY AGENTS.md /home/coder/project/AGENTS.md
+
+# Add custom scripts
+COPY my-setup.sh /usr/local/bin/my-setup.sh
+RUN chmod +x /usr/local/bin/my-setup.sh
+```
+
+Common customizations:
+- **Project dependencies** - install language-specific packages or system libraries your codebase requires
+- **Agent instructions** - add an `AGENTS.md` or `.claude/` directory with project-specific context for the AI agent
+- **Setup scripts** - run initialization steps before the agent starts (e.g., database migrations, seed data)
+- **Additional tools** - install linters, formatters, or test frameworks the agent needs
+
+<Tip>
+Keep the base image as your `FROM` layer and add customizations on top. This ensures you get updates to the AI runtimes, governance proxy, and core scripts automatically when the base image is updated.
+</Tip>
+
+## Next Steps
+
+<CardGroup cols={3}>
+  <Card title="Getting Started" icon="play" href="/rde/agents/getting-started">
+    Set up your first autonomous agent from scratch.
+  </Card>
+  <Card title="Agent Blueprints" icon="cubes" href="/rde/agents/agent-blueprints">
+    Configure runtime, repositories, and Linear integration.
+  </Card>
+  <Card title="Linear Integration" icon="arrows-rotate" href="/rde/agents/linear-integration">
+    Configure the issue flow, labels, and workflow states.
+  </Card>
+</CardGroup>