Further docs fixes (#1247)

Author: jayhack

docs/capabilities/analytics.mdx

@@ -1,10 +1,23 @@
 ---
-title: "Agent Analytics"
+title: "Analytics"
 sidebarTitle: "Analytics"
-icon: "chart-line"
+icon: "chart-column"
 ---
 
-Get comprehensive insights into your agent activity with detailed analytics on tool usage, costs, performance, and team productivity. Codegen provides fine-grained visibility into how agents are working across your organization.
+What impact are code agents having on your codebase (and your finances) today? How can you better deploy them across your org?
+Codegen Analytics was built to answer these questions and more.
+
+<Frame caption="Cost analytics on codegen.com/analytics">
+  <img src="/images/cost-breakdown.png" alt="Analyze cost breakdown" />
+</Frame>
+
+<Card
+  title="View Analytics Dashboard"
+  icon="chart-line"
+  href="https://codegen.com/analytics"
+>
+  Access detailed analytics on agent performance, costs, and team productivity.
+</Card>
 
 ## Key Metrics
 
@@ -37,18 +50,6 @@ Track the metrics that matter most for your development workflow:
 - **Trend analysis** - Identify patterns in agent usage and effectiveness
 - **Cost optimization** - Make informed decisions about model selection and usage
 
-## Access Analytics
-
-View your organization's analytics dashboard to get started:
-
-<Card
-  title="View Analytics Dashboard"
-  icon="chart-line"
-  href="https://codegen.com/analytics"
->
-  Access detailed analytics on agent performance, costs, and team productivity.
-</Card>
-
 ## Use Cases
 
 **Performance Optimization**

docs/capabilities/capabilities.mdx

@@ -5,59 +5,127 @@ icon: "gear"
 iconType: "solid"
 ---
 
-Codegen agents come equipped with versatile tools designed to integrate seamlessly into your development workflow.
-
-## Integrated Tool Suites
-
-Deep integrations with the tools your team already uses:
-
-<CardGroup cols={3}>
-  <Card title="GitHub" icon="github" href="/integrations/github">
-    Create and manage pull requests, automated code reviews, run CI/CD
-    workflows, sync repository changes.
-  </Card>
-  <Card title="Linear" icon="file-lines" href="/integrations/linear">
-    Create and update issues automatically, track development progress, link
-    code changes to tickets.
-  </Card>
-  <Card title="Slack" icon="slack" href="/integrations/slack">
-    Chat directly in channels, get real-time notifications, share code snippets
-    and updates.
-  </Card>
-  <Card title="Notion" icon="books" href="/integrations/notion">
-    Access workspace documentation, update pages and databases, sync development
-    information.
-  </Card>
-  <Card title="Figma" icon="figma" href="/integrations/figma">
-    Access design specifications, extract design assets, convert designs to
-    code.
-  </Card>
-  <Card title="CircleCI" icon="circle-play" href="/integrations/circleci">
-    View broken checks, analyze build logs, automatically fix failing PRs and
-    wake up on failures.
-  </Card>
-  <Card title="PostgreSQL" icon="postgres" href="/integrations/postgres">
-    Execute SQL queries directly, analyze database schemas, generate data
-    insights.
-  </Card>
-</CardGroup>
-
-## Core Features
-
-Fundamental capabilities for comprehensive development support:
-
-<CardGroup cols={2}>
-  <Card title="Code Execution Sandbox" icon="box" href="/sandboxes/overview">
-    Safely run code, install dependencies, and test changes in an isolated
-    environment.
-  </Card>
-  <Card title="Web Search" icon="globe" href="/integrations/web-search">
-    Access up-to-date information, research libraries, find documentation
-    online.
-  </Card>
-</CardGroup>
-
-<Note>
-  These capabilities allow Codegen agents to handle complex tasks across
-  multiple systems, just like a human developer.
-</Note>
+Codegen agents follow a simple but powerful workflow: they're triggered from your existing tools, work in secure sandboxes to implement changes, create pull requests, and then monitor and fix any issues that arise. This creates a seamless development experience that integrates naturally with your team's existing processes.
+
+## The Agent Happy Path
+
+Here's how Codegen agents work from start to finish:
+
+```mermaid
+graph TD
+    A[Trigger from Integration] --> B[Work in Remote Sandbox]
+    B --> C[Create Pull Request]
+    C --> D[Monitor CI Checks]
+    D --> E[Auto-fix Failed Checks]
+    E --> D
+    D --> D1[All checks pass ✓]
+    D1 --> G[Ready for Review]
+    G --> F[Respond to Follow-up Questions]
+    F --> G
+
+    A1[Slack @mention] --> A
+    A2[Linear issue assignment] --> A
+    A3[GitHub issue comment] --> A
+```
+
+### 1. Trigger `@codegen` from Your Tools
+
+Agents activate seamlessly from the platforms you already use:
+
+- **[Slack](/integrations/slack)** - Tag `@codegen` in any channel or send a direct message
+- **[Linear](/integrations/linear)** - Assign an issue to Codegen or mention it in comments
+- **[Jira](/integrations/jira)** - Assign an issue to Codegen or mention it in comments
+- **[ClickUp](/integrations/clickup)** - Assign a task to Codegen or mention it in comments
+- **[Monday.com](/integrations/monday)** - Assign an item to Codegen or mention it in comments
+- **[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
+
+Once triggered, agents work in **[isolated sandbox environments](/sandboxes/overview)** where they can:
+
+- Execute code safely without affecting your systems
+- Install dependencies and run tests
+- Make changes and validate them before committing
+- Access your repository context while maintaining security
+
+### 3. Create and Manage Pull Requests
+
+Agents create **[GitHub pull requests](/integrations/github)** with:
+
+- Detailed descriptions explaining the changes
+- Links back to the original request (Linear issue, Slack thread, etc.)
+- Clean, tested code ready for review
+- Proper commit messages following your conventions
+
+### 4. Monitor and Auto-fix Issues
+
+The **[Checks Auto-fixer](/capabilities/checks-autofixer)** ensures quality by:
+
+- Monitoring CI/CD pipeline results in real-time
+- Automatically analyzing build failures and test errors
+- Pushing targeted fixes to resolve issues
+- Retrying up to 3 times before escalating to humans
+
+### 5. Respond to Follow-ups
+
+Agents remain active to handle questions and refinements:
+
+- Respond to PR review comments with additional changes
+- Answer questions in the original Slack thread or Linear issue
+- Make adjustments based on feedback from team members
+- Provide explanations of their implementation decisions
+
+## Configuration & Customization
+
+Codegen agents can be customized to match your team's specific workflows and requirements:
+
+### Model Selection
+
+Choose from leading AI models and configure custom API keys to optimize performance and cost for your organization.
+
+<Card
+  title="Model Configuration"
+  icon="brain-circuit"
+  href="/settings/model-configuration"
+>
+  Select LLM providers, configure custom API keys, and optimize performance
+  settings.
+</Card>
+
+### Agent Behavior
+
+Control how agents interact with users and approach code modifications to ensure they align with your team's preferences.
+
+<Card title="Agent Behavior" icon="robot" href="/settings/agent-behavior">
+  Configure plan proposals, GitHub mention requirements, and interaction
+  patterns.
+</Card>
+
+### Security & Permissions
+
+Define what actions agents are allowed to perform across your organization with fine-grained permission controls.
+
+<Card
+  title="Agent Permissions"
+  icon="shield-check"
+  href="/settings/agent-permissions"
+>
+  Control PR creation, rules detection, and enforce security policies like
+  signed commits.
+</Card>
+
+<Tip>
+  Start with conservative settings and gradually expand agent capabilities as
+  your team becomes comfortable with AI assistance.
+</Tip>
+
+## Learn More
+
+Dive deeper into specific capabilities:
+
+- **[Get started with the overview](/introduction/overview)** - Complete introduction to Codegen
+- **[Explore integrations](/integrations/integrations)** - See all available platforms and tools
+- **[Understand sandboxes](/sandboxes/overview)** - Learn about the secure execution environment
+- **[Configure settings](/settings/settings)** - Customize agent behavior and permissions
+- **[View analytics](/capabilities/analytics)** - Monitor agent performance and impact

docs/capabilities/checks-autofixer.mdx

@@ -4,7 +4,7 @@ sidebarTitle: "Checks Auto-fixer"
 icon: "bell"
 ---
 
-When GitHub checks fail on a Codegen PR, Codegen agents will automatically "wake up", analyze the failure, and push fix commit.
+When GitHub checks fail on a Codegen PR, Codegen agents will automatically "wake up", analyze the failure, and push fix commits.
 
 <video
   controls
@@ -106,10 +106,3 @@ The auto-fix system integrates deeply with GitHub:
   access and the feature is enabled. It respects your repository permissions and
   team workflows.
 </Note>
-
-## Benefits
-
-- **Reduced Context Switching:** No need to manually investigate and fix CI failures
-- **Faster Iteration:** PRs get fixed automatically, keeping development velocity high
-- **Learning from Failures:** Each fix improves Codegen's understanding of your codebase
-- **24/7 Monitoring:** Works around the clock to keep your PRs in good shape

docs/docs.json

@@ -41,7 +41,8 @@
               "settings/repo-rules",
               "settings/model-configuration",
               "settings/agent-behavior",
-              "settings/agent-permissions"
+              "settings/agent-permissions",
+              "settings/team-roles"
             ]
           },
           {

docs/images/cost-breakdown.png

@@ -5,9 +5,16 @@ icon: "terminal"
 iconType: "solid"
 ---
 
-# Codegen CLI Manual
+The `codegen` CLI allows users to run and interact with agents from the terminal.
 
-Welcome to the Codegen CLI documentation. This guide covers all available commands and their usage patterns.
+<iframe
+  className="w-full aspect-video rounded-xl"
+  src="https://youtube.com/embed/sQ2XOonma0w"
+  title="YouTube video player"
+  frameBorder="0"
+  allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture"
+  allowFullScreen
+></iframe>
 
 ## Installation
 
@@ -34,11 +41,13 @@ codegen login
 **Description:** Create a new agent run with a prompt, fetch an existing agent run by ID, or pull PR branch.
 
 **Usage Patterns:**
+
 - **Create run:** `codegen agent --prompt "Your prompt"`
 - **Get run JSON:** `codegen agent --id 123 --json`
 - **Pull PR branch:** `codegen agent --id 123 pull`
 
 **Options:**
+
 - `--prompt, -p TEXT` The prompt to send to the agent (mutually exclusive with --id unless using create)
 - `--id INT` Agent run ID to fetch or pull
 - `--json` Output raw JSON response when fetching (flag)
@@ -47,6 +56,7 @@ codegen login
 - `--repo-id INT` Repository ID to use for this agent run (optional)
 
 **Positional Actions:**
+
 - `pull` Pull the PR branch associated with an agent run (requires --id)
 
 ---
@@ -56,10 +66,12 @@ codegen login
 **Description:** List and manage agent runs.
 
 **Usage Patterns:**
+
 - **List runs:** `codegen agents list`
 - **Get run details:** `codegen agents get 123`
 
 **Options:**
+
 - `--org-id INT` Organization ID (defaults to CODEGEN_ORG_ID/REPOSITORY_ORG_ID or auto-detect)
 - `--limit INT` Maximum number of runs to return (default: 10)
 - `--json` Output raw JSON response (flag)
@@ -71,10 +83,12 @@ codegen login
 **Description:** Store authentication token.
 
 **Usage Patterns:**
+
 - **Interactive login:** `codegen login`
 - **Token login:** `codegen login --token YOUR_API_TOKEN`
 
 **Options:**
+
 - `--token TEXT` API token to store
 - `--no-verify` Skip token verification (flag)
 
@@ -85,6 +99,7 @@ codegen login
 **Description:** Clear stored authentication token.
 
 **Usage Pattern:**
+
 - `codegen logout`
 
 ---
@@ -94,11 +109,13 @@ codegen login
 **Description:** Manage and switch between organizations.
 
 **Usage Patterns:**
+
 - **List organizations:** `codegen org list`
 - **Switch organization:** `codegen org switch ORG_ID`
 - **Get current organization:** `codegen org current`
 
 **Options:**
+
 - `--json` Output raw JSON response (flag)
 
 ---
@@ -108,11 +125,13 @@ codegen login
 **Description:** Manage repository configuration and environment variables.
 
 **Usage Patterns:**
+
 - **List repositories:** `codegen repo list`
 - **Configure repository:** `codegen repo config REPO_NAME`
 - **Get repository details:** `codegen repo get REPO_ID`
 
 **Options:**
+
 - `--org-id INT` Organization ID (defaults to CODEGEN_ORG_ID or auto-detect)
 - `--json` Output raw JSON response (flag)
 

docs/introduction/cli.mdx

@@ -5,7 +5,7 @@ icon: "robot"
 iconType: "solid"
 ---
 
-Codegen provides intelligent AI agents designed to seamlessly integrate into your existing developer workflows.
+Codegen helps you run frontier code agents at scale. It provides the necessary building blocks (sandboxes, integrations, telemetry) for successful enterprise code agent deployments across thousands of teams today.
 
 Think of it as an AI coworker that can understand and solve coding challenges, access your codebase instantly, and interact directly with your development tools.
 
@@ -109,3 +109,20 @@ Codegen is SOC 2 Type II certified, ensuring your code and data are handled with
     Learn how to use Codegen for common code transformation tasks.
   </Card>
 </CardGroup>
+
+## Learn More
+
+<CardGroup cols={2}>
+  <Card
+    title="Join the Community"
+    icon="people-group"
+    href="/introduction/community"
+  >
+    Connect with other developers, get help, and share your experiences in our
+    active Slack workspace.
+  </Card>
+  <Card title="About Codegen" icon="building" href="/introduction/about">
+    Learn about our mission to build fully-autonomous software engineering and
+    meet the team.
+  </Card>
+</CardGroup>