.

jayhack · jayhack · commit 00eeb3034f3a · 2025-09-14T14:58:05.000-07:00
diff --git a/docs/docs.json b/docs/docs.json
@@ -27,19 +27,21 @@
             "group": "Capabilities",
             "pages": [
               "capabilities/capabilities",
-              "introduction/api",
-              "introduction/cli",
               "capabilities/checks-autofixer",
               "capabilities/pr-review",
-              "capabilities/analytics"
+              "capabilities/analytics",
+              "introduction/cli",
+              "introduction/sdk"
             ]
           },
           {
             "group": "Settings",
             "pages": [
               "settings/settings",
               "settings/repo-rules",
-              "settings/model-configuration"
+              "settings/model-configuration",
+              "settings/agent-behavior",
+              "settings/agent-permissions"
             ]
           },
           {
diff --git a/docs/integrations/slack.mdx b/docs/integrations/slack.mdx
@@ -6,7 +6,11 @@ icon: "slack"
 
 Connect Codegen to your Slack workspace to enable seamless communication between agents and your team.
 
-<img src="/images/slack.png" className="rounded-lg" />
+<video
+  controls
+  src="https://res.cloudinary.com/dbikr6pew/video/upload/v1757886194/slack-happy-path_yjtx1c.mp4"
+  className="w-full aspect-[3456/2160] rounded-sm"
+/>
 
 Slack is the most fluid way to communicate with Codegen. Simply tag @codegen in any channel to collaborate directly and give it tasks that leverage all your other integrations. As an agent, Codegen can seamlessly work across platforms—from GitHub to Linear to your databases—all initiated from Slack. We recommend Slack as the lowest barrier entry point for all users.
 
@@ -85,15 +89,18 @@ Codegen only responds when tagged or messaged directly. Use these approaches to
 The Codegen Slack integration requires the following permissions to function effectively:
 
 ### Core Messaging Permissions
+
 - **View messages that mention @codegen** - To respond to direct mentions and requests
 - **Read message history in public and private channels** - To understand context and conversation flow
 - **Read direct messages and group chats** (`mpim:read`) - To enable private conversations with the agent in group DMs and multi-person direct messages
 - **Send messages** - To communicate responses and provide updates
 
 ### Enhanced Communication Features
+
 - **View and react with emojis** - To acknowledge messages and provide feedback through reactions
 
 ### User and Workspace Access
+
 - **View workspace members and email addresses** (`users:read.email`) - Used to map Slack user accounts to Codegen accounts for proper authentication and permission management. This ensures that when a user interacts with Codegen via Slack, their actions are properly attributed to their Codegen account and repository permissions
 - **Access shared files and attachments** - To review and work with shared content like code snippets, images, and documents
 - **Access basic channel information** - To operate appropriately within different channel contexts
diff --git a/docs/introduction/sdk.mdx b/docs/introduction/sdk.mdx
@@ -1,8 +1,7 @@
 ---
-title: "Codegen SDK"
-sidebarTitle: "API"
-icon: "bolt"
-iconType: "solid"
+title: "Python SDK"
+sidebarTitle: "Python SDK"
+icon: "python"
 ---
 
 The [Codegen SDK](https://github.com/codegen-sh/codegen-sdk) enables developers to programmatically interact with [Codegen](https://codegen.com) SWE agents via API.
diff --git a/docs/sandboxes/overview.mdx b/docs/sandboxes/overview.mdx
@@ -29,5 +29,9 @@ Agents utilize sandboxes for a variety of tasks:
 Sandboxes are typically configured per-agent run or defined within your Codegen settings. You often don't need to manage them directly, but advanced configurations might allow specifying Docker images or environment variables.
 
 <Note>
-  Sandboxes maintain file system persistence between agent interactions within the same context. For example, when continuing a conversation across different Slack messages or Linear comments, the sandbox state is preserved, allowing agents to seamlessly continue their work without losing context or having to reinstall dependencies.
+  Sandboxes maintain file system persistence between agent interactions within
+  the same context. For example, when continuing a conversation across different
+  Slack messages or Linear comments, the sandbox state is preserved, allowing
+  agents to seamlessly continue their work without losing context or having to
+  reinstall dependencies.
 </Note>{" "}
diff --git a/docs/settings/agent-behavior.mdx b/docs/settings/agent-behavior.mdx
@@ -0,0 +1,94 @@
+---
+title: "Agent Behavior"
+sidebarTitle: "Agent Behavior"
+icon: "robot"
+---
+
+Configure the types of behaviors you'd like the AI agent to exhibit. These settings control how agents interact with users and approach code modifications to ensure they align with your team's workflow preferences.
+
+## Available Behaviors
+
+### Propose Plan
+
+Control whether the codegen agent should propose a detailed implementation plan to the user before executing **all** code modifications, regardless of size or complexity.
+
+**When enabled:**
+
+- Agents will present a structured plan showing each implementation step
+- Users can review the proposed approach before any code changes are made
+- Plans include confidence levels, relevant files, and detailed descriptions
+- Provides transparency into the agent's decision-making process
+
+**When disabled:**
+
+- Agents proceed directly with code modifications
+- Faster execution for straightforward tasks
+- Users can still request plans explicitly when needed
+
+<Tip>
+  Enable this setting if you prefer to review and approve implementation
+  approaches before code changes are made, especially for critical or complex
+  repositories.
+</Tip>
+
+### Require Explicit GitHub Mentions
+
+Control whether the codegen agent should only respond to GitHub comments that explicitly mention `@codegen` or `@codegen-sh`.
+
+**When enabled:**
+
+- Agent only responds to comments containing explicit mentions
+- Provides precise control over when agents activate
+- Reduces unwanted agent responses on general discussions
+- Recommended for busy repositories with frequent comments
+
+**When disabled:**
+
+- Agent may respond to relevant comments without explicit mentions
+- More proactive agent engagement
+- Convenient for smaller teams with focused discussions
+
+<Warning>
+  In busy repositories, disabling explicit mentions may result in agents
+  responding to unintended comments. Consider your team's communication patterns
+  when configuring this setting.
+</Warning>
+
+## Configuration
+
+These behavior settings are configured at the organization level and apply to all repositories within your organization. Individual repository settings may override some behaviors where supported.
+
+Access your agent behavior settings at:
+
+<Card
+  title="Configure Agent Behavior"
+  icon="robot"
+  href="https://codegen.com/settings/behavior"
+>
+  Customize how agents interact with your team and approach code modifications.
+</Card>
+
+## Best Practices
+
+**For New Teams:**
+
+- Start with "Propose Plan" enabled to understand how agents approach problems
+- Use explicit GitHub mentions initially to control agent activation
+- Gradually adjust settings as your team becomes comfortable with agent behavior
+
+**For Experienced Teams:**
+
+- Disable "Propose Plan" for routine tasks to increase velocity
+- Consider allowing non-explicit mentions in trusted repositories
+- Customize settings based on repository criticality and team preferences
+
+**For Large Organizations:**
+
+- Enable explicit mentions to prevent noise in high-traffic repositories
+- Use "Propose Plan" for production or critical infrastructure repositories
+- Consider different settings for different types of repositories
+
+<Note>
+  Agent behavior settings help ensure that AI assistance integrates smoothly
+  with your existing development workflows and team communication patterns.
+</Note>
diff --git a/docs/settings/agent-permissions.mdx b/docs/settings/agent-permissions.mdx
@@ -1,76 +1,159 @@
 ---
 title: "Agent Permissions"
 sidebarTitle: "Agent Permissions"
-icon: "user-shield"
+icon: "shield-check"
 ---
 
-Agent Permissions allow you to configure what actions the AI agent is allowed to perform across your organization. These settings provide fine-grained control over the agent's capabilities, ensuring it operates within your team's preferred workflows and security boundaries.
+Configure what actions the AI agent is allowed to perform across your organization. These permission settings provide fine-grained control over agent capabilities to ensure they operate within your security and workflow requirements.
 
-## Accessing Agent Permissions
+## Available Permissions
 
-Agent Permission settings are applied globally for your entire organization. You can access and modify these settings by navigating to:
+### Enable PR Creation
 
-[**codegen.com/settings/permissions**](https://codegen.com/settings/permissions)
+Control whether the codegen agent is able to create pull requests in your repositories in response to user requests.
 
-<Frame caption="Agent Permissions UI at codegen.com/settings/permissions">
-  <img src="/images/agent-permissions.png" alt="Agent Permissions Configuration" />
-</Frame>
+**When enabled:**
 
-## Available Permission Settings
+- Agents can create new pull requests with code changes
+- PRs include detailed descriptions and context
+- Automatic linking to related issues and discussions
+- Supports your standard code review workflow
 
-### Enable PR Creation
+**When disabled:**
+
+- Agents can still analyze code and provide suggestions
+- Code changes are proposed but not committed
+- Manual PR creation required for implementing changes
+- Useful for read-only or advisory agent roles
 
-**Control whether the codegen agent is able to create pull requests in your repositories in response to user requests.**
+### Enable Rules Detection
 
-When enabled, the agent can automatically create pull requests when implementing features, fixing bugs, or making other code changes. When disabled, the agent will make changes locally but won't create PRs, requiring manual PR creation.
+Allow the agent to automatically detect and apply rules from various rule files in your repositories.
 
-- **Default**: Enabled
-- **Use Case**: Disable if you prefer manual PR creation or have strict PR workflows
+**Supported rule file formats:**
 
-### Enable Rules Detection
+- `.cursorrules` - Cursor AI editor rules
+- `.cursor/rules/*.mdc` - Structured rule files in Cursor directory
+- `.windsurfrules` - Windsurf AI editor rules
+- `CLAUDE.md` - Claude-specific instructions
+- `AGENTS.md` - General agent instructions
+- `AGENT.md` - Agent-specific rules
+
+**When enabled:**
+
+- Agents automatically discover and apply repository-specific rules
+- Rules are version-controlled alongside your code
+- Consistent behavior across team members and environments
+- Supports existing AI editor workflows
+
+**When disabled:**
+
+- Only manually configured repository rules are applied
+- No automatic file-based rule detection
+- Simpler rule management through web interface only
+
+### Enforce Organization-wide Signed Commits
+
+When enabled, **ALL** repositories in this organization will be required to use signed commits via GitHub's API. Individual repositories cannot override this security policy.
+
+**Security benefits:**
+
+- Cryptographic verification of commit authenticity
+- Enhanced audit trail for code changes
+- Compliance with security policies requiring commit signing
+- Protection against commit impersonation
+
+**Important considerations:**
+
+- This is an organization-wide enforcement policy
+- Individual repositories cannot disable this requirement
+- Ensures consistent security posture across all projects
+- May require additional setup for team members' GPG keys
+
+<Warning>
+  Enabling organization-wide signed commits affects all repositories and cannot
+  be overridden at the repository level. Ensure your team is prepared for this
+  requirement before enabling.
+</Warning>
+
+## Configuration
+
+Agent permissions are configured at the organization level and provide security boundaries for all agent operations within your organization.
+
+Access your agent permissions at:
+
+<Card
+  title="Configure Agent Permissions"
+  icon="shield-check"
+  href="https://codegen.com/settings/permissions"
+>
+  Control what actions agents are allowed to perform in your organization.
+</Card>
+
+## Permission Combinations
+
+### Development Teams
 
-**Allow the agent to automatically detect and apply rules from .cursorrules and .windsurfrules files in your repositories.**
+```
+✅ Enable PR Creation
+✅ Enable Rules Detection
+❌ Enforce Signed Commits (unless required)
+```
 
-This setting enables the agent to automatically discover and follow coding standards, style guides, and other rules defined in your repository's configuration files.
+Standard setup for most development teams wanting full agent capabilities.
 
-- **Default**: Enabled
-- **Use Case**: Disable if you want to manually control rule application or don't use these rule files
+### Security-Conscious Organizations
 
-### Enable Linear Self-Assign
+```
+✅ Enable PR Creation
+✅ Enable Rules Detection
+✅ Enforce Signed Commits
+```
 
-**Allow the codegen agent to self-assign Linear issues, enabling it to spin off other agents.**
+Maximum security with full agent functionality and commit verification.
 
-When enabled, the agent can assign itself to Linear issues and potentially delegate work to other agent instances for parallel processing.
+### Read-Only Advisory Mode
 
-- **Default**: Enabled
-- **Use Case**: Disable if you prefer manual issue assignment or want to limit agent autonomy
+```
+❌ Enable PR Creation
+✅ Enable Rules Detection
+❌ Enforce Signed Commits
+```
 
-### Enable Linear Auto State Change
+Agents provide analysis and suggestions without making direct code changes.
 
-**When enabled, the agent will automatically move Linear issues to 'Started' state when self-assigning them.**
+### Compliance-First Approach
 
-This setting automates the workflow by updating issue status when the agent begins work, providing better visibility into what the agent is actively working on.
+```
+✅ Enable PR Creation
+❌ Enable Rules Detection
+✅ Enforce Signed Commits
+```
 
-- **Default**: Disabled
-- **Use Case**: Enable for automatic issue tracking and improved project visibility
+Strict control with manual rule management and required commit signing.
 
 ## Best Practices
 
-### Security Considerations
+**Start Conservative:**
 
-- Review permission settings regularly to ensure they align with your team's security policies
-- Consider disabling PR creation in production environments if you require manual review processes
-- Monitor agent activity when enabling self-assignment features
+- Begin with limited permissions and expand as trust builds
+- Enable rules detection to leverage existing team practices
+- Consider PR creation permissions based on repository criticality
 
-### Workflow Integration
+**Security Considerations:**
 
-- Enable Linear Auto State Change if your team relies on Linear for project tracking
-- Coordinate permission settings with your existing CI/CD and review processes
-- Consider your team's preferred level of automation when configuring these settings
+- Enable signed commits for organizations with compliance requirements
+- Review agent-created PRs before merging, especially initially
+- Monitor agent activity through analytics and audit logs
 
-## Related Documentation
+**Team Alignment:**
 
-- [Repository Rules](/settings/repo-rules) - Configure repository-specific behavior
-- [Linear Integration](/integrations/linear) - Set up Linear workspace integration
-- [Model Configuration](/settings/model-configuration) - Configure LLM settings
+- Ensure team understands which permissions are enabled
+- Provide training on rule file formats if using rules detection
+- Establish clear processes for agent-created PRs
 
+<Note>
+  Permission settings provide essential guardrails for agent operations while
+  maintaining the flexibility to customize based on your organization's security
+  and workflow requirements.
+</Note>
diff --git a/docs/settings/settings.mdx b/docs/settings/settings.mdx
