Further docs cleanup (#1256)

Author: jayhack

docs/capabilities/capabilities.mdx

@@ -1,6 +1,6 @@
 ---
-title: "Agent Capabilities"
-sidebarTitle: "Overview"
+title: "How Codegen Agents Work"
+sidebarTitle: "How it Works"
 icon: "gear"
 iconType: "solid"
 ---
@@ -28,7 +28,7 @@ graph TD
  A3[GitHub issue comment] --> A
 ```
 
-### 1. Trigger `@codegen` from Your Tools
+### 1. Users Trigger `@codegen` to Perform Tasks
 
 Agents activate seamlessly from the platforms you already use:
 
@@ -40,7 +40,7 @@ Agents activate seamlessly from the platforms you already use:
 - **[GitHub](/integrations/github)** - Comment on issues or PRs to request changes
 - **[API](http://localhost:3001/api-reference/agents/create-agent-run)** - Programmatically trigger agents for automated workflows
 
-### 2. Work in Secure Sandboxes
+### 2. `@codegen` Performs Work in Secure Sandboxes
 
 Once triggered, agents work in **[isolated sandbox environments](/sandboxes/overview)** where they can:
 
@@ -49,7 +49,7 @@ Once triggered, agents work in **[isolated sandbox environments](/sandboxes/over
 - Make changes and validate them before committing
 - Access your repository context while maintaining security
 
-### 3. Create and Manage Pull Requests
+### 3. Users Receive Completed Pull-Requests
 
 Agents create **[GitHub pull requests](/integrations/github)** with:
 
@@ -58,7 +58,7 @@ Agents create **[GitHub pull requests](/integrations/github)** with:
 - Clean, tested code ready for review
 - Proper commit messages following your conventions
 
-### 4. Monitor and Auto-fix Issues
+### 4. Agents Monitor and Auto-fix PR Issues
 
 The **[Checks Auto-fixer](/capabilities/checks-autofixer)** ensures quality by:
 
@@ -67,7 +67,7 @@ The **[Checks Auto-fixer](/capabilities/checks-autofixer)** ensures quality by:
 - Pushing targeted fixes to resolve issues
 - Retrying up to 3 times before escalating to humans
 
-### 5. Respond to Follow-ups
+### 5. Agents Respond to Follow-ups
 
 Agents remain active to handle questions and refinements:
 

docs/capabilities/claude-code.mdx

@@ -0,0 +1,135 @@
+---
+title: "Claude Code Integration"
+sidebarTitle: "Claude Code"
+icon: "code"
+---
+
+Claude Code brings the power of Anthropic's coding assistant directly into your development workflow through Codegen. Whether you're running Claude locally or in the cloud, Codegen provides the infrastructure to enhance your AI coding experience with telemetry, integrations, and seamless deployment options.
+
+<Frame>
+ <video
+ controls
+ src="https://res.cloudinary.com/dbikr6pew/video/upload/v1757996504/Claude_Code_Integration_coe5sm.mp4"
+ className="aspect-[3340/2160]"
+ />
+</Frame>
+
+## Cloud Logging for Local Sessions
+
+Every local Claude Code session is automatically logged to the cloud through the Codegen CLI. This seamless integration means your local development gains enterprise-grade observability without any extra configuration.
+
+When you run Claude through `codegen`, you get:
+
+- **Persistent history** across all your local Claude sessions
+- **Searchable conversations** accessible from any device
+- **Team visibility** into AI-assisted development patterns
+- **Audit trails** for compliance and debugging
+
+<Note>
+ Sessions appear instantly at [codegen.com/agents](https://codegen.com/agents),
+ making it easy to share context with teammates or continue work from another
+ machine.
+</Note>
+
+## Connect Claude Code to Codegen Tools
+
+Claude Code running through Codegen automatically gains access to all your connected integrations via MCP (Model Context Protocol). This transforms Claude from a coding assistant into a full development platform orchestrator.
+
+Your existing Codegen integrations work seamlessly:
+
+- **Slack** - Send updates and coordinate with your team
+- **Linear/Jira** - Update tickets and track progress
+- **GitHub** - Create PRs and manage repositories
+- **Databases** - Query and modify data safely
+- **Custom tools** - Any MCP server you've configured
+
+No additional setup required - if it's connected to Codegen, Claude can use it.
+
+<Tip>
+ MCP integration means Claude can perform complex workflows like "When tests
+ fail, create a Linear ticket and notify the team on Slack" - all in a single
+ command.
+</Tip>
+
+## Run Background Agents from your Terminal
+
+Keep your terminal free while Claude handles long-running tasks. Background agents run asynchronously, perfect for automation that doesn't need constant supervision.
+
+## Remote Sandbox Execution
+
+Configure Claude Code as your default agent to run in Codegen's secure cloud sandboxes. This provides consistent, scalable environments for all your AI-assisted development.
+
+<Card
+ title="Set Claude Code as Default"
+ icon="toggle-on"
+ href="https://codegen.com/settings/model"
+>
+ Enable Claude Code mode to run all agents in secure sandboxes with full
+ integration support.
+</Card>
+
+Remote execution benefits:
+
+- **Consistent environments** across your team
+- **Pre-configured tools** and dependencies
+- **Scalable compute** for resource-intensive tasks
+- **Security isolation** from your local machine
+
+## Getting Started
+
+### Local Claude with Cloud Benefits
+
+Get up and running in three simple steps:
+
+1. Install the Codegen CLI:
+
+ ```bash
+ uv tool install codegen
+ ```
+
+2. Authenticate with your account:
+
+ ```bash
+ codegen login
+ ```
+
+3. Run Claude with full telemetry:
+ ```bash
+ codegen claude "Help me refactor this authentication module"
+ ```
+
+Your session immediately appears in the cloud with full integration access.
+
+<Tip>
+ The first time you run `codegen claude`, it will download the Claude Code
+ binary. Subsequent runs start instantly.
+</Tip>
+
+## Analytics and Insights
+
+Transform your Claude Code usage into actionable intelligence. The analytics dashboard provides deep insights into how AI is transforming your development workflow.
+
+Track key metrics:
+
+- **Token usage** to understand costs and optimize prompts
+- **Task completion rates** and success patterns
+- **Integration usage** showing which tools Claude uses most
+- **Team adoption** identifying power users and best practices
+
+Access detailed analytics at [codegen.com/analytics](https://codegen.com/analytics).
+
+<Tip>
+ Use analytics to identify repetitive tasks that could be automated with
+ background agents, maximizing your team's productivity gains.
+</Tip>
+
+## What's Next
+
+Claude Code integration is just the beginning. We're actively working on:
+
+- OpenAI Codex support for GPT-4 workflows
+- Gemini CLI integration for Google's models
+- Enhanced MCP protocol features
+- Custom model deployment options
+
+Join our [community Slack](https://community.codegen.com) to stay updated and share your Claude Code workflows with other developers.

docs/capabilities/pr-review.mdx

@@ -4,7 +4,7 @@ sidebarTitle: "PR Review"
 icon: "microscope"
 ---
 
-Codegen provides a configurable AI code review feature similar to CodeRabbit, Graphite, or Greptile as a first-class feature.
+Codegen provides AI code review as a first-class supported feature.
 
 <Frame>
  <video
@@ -24,7 +24,9 @@ Codegen provides a configurable AI code review feature similar to CodeRabbit, Gr
 
 ## How It Works
 
-When you open a PR or push new commits, Codegen agents analyze the changes and provide:
+When PR review is enabled on a repo, a Codegen agent will spin up to leave a detailed review.
+
+This includes:
 
 - **Inline comments** on specific lines with actionable feedback
 - **Security scanning** for vulnerabilities and unsafe patterns

docs/capabilities/triggering-codegen.mdx

@@ -0,0 +1,98 @@
+---
+title: "Triggering Codegen"
+sidebarTitle: "Triggering Agents"
+icon: "play"
+---
+
+Codegen is designed to work where you work. Trigger agents from your existing tools and they'll respond right where the conversation started.
+
+## Trigger Methods
+
+### From Your Tools
+
+- **[Slack](/integrations/slack)** - Mention `@codegen` in any channel or DM
+- **[Linear](/integrations/linear)** - Assign issues to Codegen or mention in comments
+- **[Jira](/integrations/jira)** - Assign issues to Codegen or `@mention` in comments
+- **[ClickUp](/integrations/clickup)** - Assign tasks to Codegen or mention in comments
+- **[Monday.com](/integrations/monday)** - Assign items to Codegen or mention in comments
+- **[GitHub](/integrations/github)** - Comment on PRs or issues with `@codegen-agent`
+
+### From Codegen
+
+- **[Web UI](https://codegen.com/new)** - Start a new agent run directly from the dashboard
+- **[CLI](/introduction/cli)** - Run `codegen agent create "your task"` from your terminal
+- **[API](/api-reference/agents/create-agent-run)** - Trigger programmatically for automated workflows
+
+## How Agent Context Works
+
+### One Agent Per Context
+
+Each context gets its own dedicated agent:
+
+- **Slack** - Each thread is a separate agent. Follow-up messages in the same thread route to the same agent
+- **Linear/Jira/ClickUp/Monday** - Each ticket is a separate agent. All comments on that ticket go to the same agent
+- **GitHub** - Each issue or PR is a separate agent. All comments stay with the same agent
+
+### Shared Context with PRs
+
+When an agent creates a PR:
+
+- The agent **always monitors its own PR** and responds to comments
+- Agents triggered from tickets (Linear, Jira, etc.) share context between the ticket and any PRs they create
+- Follow-up requests on either the ticket or PR route to the same agent
+- **Automatically fixes broken tests** - When CI checks fail, the agent wakes up and pushes fix commits
+
+<Note>
+ This means you can start a conversation in Linear, have the agent create a PR,
+ then continue the discussion on either platform - it's all the same agent with
+ full context.
+</Note>
+
+<Tip>
+ Follow-up messages always go to the same agent. Whether you're continuing a
+ Slack thread, commenting on a ticket, or reviewing a PR - the agent maintains
+ full conversation history.
+</Tip>
+
+Learn more about automatic test fixing in the **[Checks Auto-fixer](/capabilities/checks-autofixer)** documentation.
+
+## All Agents Created Equal
+
+No matter where you trigger from, your request:
+
+1. Routes to a dedicated agent for that context
+2. Runs in secure [sandboxes](/sandboxes/overview)
+3. Has access to all your [integrations](/integrations/integrations)
+4. Creates trackable runs visible at [codegen.com/agents](https://codegen.com/agents)
+
+## Automatic Triggers
+
+Codegen supports certain automated triggers as first-class citizens. These activate without manual intervention to maintain code quality:
+
+- **[Checks Auto-fixer](/capabilities/checks-autofixer)** - Automatically fixes failing CI checks on agent PRs
+- **[PR Review](/capabilities/pr-review)** - Provides instant code review feedback on all PRs
+
+<Note>
+ These automations work alongside manual triggers. An agent fixing broken tests
+ can still respond to comments on its PR or the original ticket that triggered
+ it.
+</Note>
+
+## Learn More
+
+<CardGroup cols={2}>
+ <Card
+ title="Configure Integrations"
+ icon="plug"
+ href="/integrations/integrations"
+ >
+ Set up GitHub, Slack, and other tools
+ </Card>
+
+ <Card title="CLI Documentation" icon="terminal" href="/introduction/cli">
+ Trigger agents from your terminal
+ </Card>
+ <Card title="API Reference" icon="code" href="/api-reference/overview">
+ Build custom workflows and automations
+ </Card>
+</CardGroup>

docs/docs.json

@@ -17,19 +17,21 @@
  "group": "Overview",
  "pages": [
  "introduction/overview",
- "introduction/prompting",
  "introduction/support",
  "introduction/community",
  "introduction/about",
+ "introduction/prompting",
  "introduction/faq"
  ]
  },
  {
- "group": "Capabilities",
+ "group": "Guides",
  "pages": [
  "capabilities/capabilities",
+ "capabilities/triggering-codegen",
  "capabilities/checks-autofixer",
  "capabilities/pr-review",
+ "capabilities/claude-code",
  "capabilities/analytics",
  "introduction/cli",
  "introduction/sdk"
@@ -41,7 +43,6 @@
  "settings/settings",
  "settings/repo-rules",
  "settings/model-configuration",
- "settings/claude-code",
  "settings/agent-behavior",
  "settings/agent-permissions",
  "settings/team-roles",

docs/integrations/clickup.mdx

@@ -6,7 +6,15 @@ icon: "feather"
 
 import { COMMUNITY_SLACK_URL } from "/snippets/links.mdx";
 
-Integrate Codegen with your ClickUp workspace to enable AI-powered task creation and project management. Codegen can create tasks, update statuses, manage dependencies, and coordinate development workflows across your team.
+Codegen supports ClickUp as a first-class integration. Assign issues, create issues, perform triage and more.
+
+<Frame>
+ <video
+ controls
+ src="https://res.cloudinary.com/dbikr6pew/video/upload/v1758064133/ClickUp_ysxp5s.mp4"
+ className="aspect-[3340/2160]"
+ />
+</Frame>
 
 ## Installation