diff --git a/docs/settings/repo-rules.mdx b/docs/settings/repo-rules.mdx
index cfacab723..2c79b5cd6 100644
--- a/docs/settings/repo-rules.mdx
+++ b/docs/settings/repo-rules.mdx
@@ -47,12 +47,14 @@ Codegen automatically searches for the following types of rule files in your rep
 - **`.windsurfrules`** - Windsurf AI editor rules
 - **`**/*.mdc`** - Markdown files with `.mdc` extension anywhere in the repository
 - **`.cursor/rules/**/*.mdc`** - Markdown files in the `.cursor/rules/` directory structure
+- **`CLAUDE.md`**, **`AGENTS.md`**, **`AGENT.md`** - top-level docs commonly used to instruct AI agents
 
 ### How Automatic Detection Works
 
 1. **File Discovery**: When you switch to a repository, Codegen uses `ripgrep` to search for files matching the supported patterns
 2. **Content Extraction**: The content of discovered files is read and processed
-3. **Size Limitation**: All rule files combined are truncated to fit within 3,000 characters total to ensure optimal performance
+- **New**: The content is encoded to preserve formatting during transport, then decoded before being presented to the agent
+3. **Size Limitation (25k global budget)**: All rule files combined are truncated to fit within a 25,000 character global budget to ensure optimal performance
 4. **Context Integration**: The rule content is automatically included in the agent's context alongside any manual repository rules
 
 ### Example Rule Files
@@ -82,6 +84,10 @@ Prefer functional components over class components in React
 - Include request/response validation
 ```
 
+### Visibility in UI
+
+When rules are discovered, they are displayed in the AgentTrace under the `SetActiveCodebase` tool card as "Repository Rules (Filesystem)". You can expand each entry to preview the content and open the source file on GitHub.
+
 ### Benefits of Automatic Rule Files
 
 - **Version Control**: Rule files are committed with your code, ensuring consistency across team members
@@ -94,7 +100,7 @@ Prefer functional components over class components in React
 </Tip>
 
 <Warning>
-  If your rule files exceed 3,000 characters combined, they will be automatically truncated. Consider keeping rule files concise or splitting them into multiple focused files.
+  If your rule files exceed the global 25,000 character budget, they will be truncated per-file and/or at the aggregate level. Keep rule files concise or split them into focused files.
 </Warning>
 
 ## Common Use Cases and Examples
diff --git a/docs/settings/repo-rules.tsx b/docs/settings/repo-rules.tsx
index a78f4726c..8f2c49920 100644
--- a/docs/settings/repo-rules.tsx
+++ b/docs/settings/repo-rules.tsx
@@ -14,6 +14,40 @@ When an agent is assigned a task on a repository with defined rules, those rules
 
 For example, if you have a rule like "Always use tabs for indentation," the agent will be reminded of this preference before it starts writing or modifying code in that repository.
 
+## Automatic Rule File Detection
+
+In addition to manual repository rules, Codegen automatically discovers and includes agent rule files from your repository when the agent starts working on it. This discovery happens whenever the `set_active_codebase` tool initializes work on a repo.
+
+### Supported Rule File Patterns
+
+Codegen searches for the following patterns:
+
+- **`.cursorrules`** (Cursor)
+- **`.clinerules`** (Cline)
+- **`.windsurfrules`** (Windsurf)
+- **`**/*.mdc`** (any `.mdc` file in the repo)
+- **`.cursor/rules/**/*.mdc`** (files under `.cursor/rules/`)
+- **`CLAUDE.md`**, **`AGENTS.md`**, **`AGENT.md`** (top-level agent instruction docs)
+
+### How it works
+
+1. Discovery via `ripgrep`
+2. Content is read and encoded to preserve formatting during transport, then decoded
+3. A global size budget of **25,000 characters** is enforced across all discovered files
+4. The resulting content is combined with your manual Repository Rules and provided to the agent
+
+### Visibility in the UI
+
+Discovered rule files are rendered in AgentTrace under the `SetActiveCodebase` tool card as "Repository Rules (Filesystem)". Expand entries to preview content and open the source on GitHub.
+
+<Tip>
+  Automatic rule files are merged with manual Repository Rules to give the agent repository-specific context.
+</Tip>
+
+<Warning>
+  If discovered rule files exceed the global 25,000 character budget, content will be truncated. Keep files concise or split by area of concern.
+</Warning>
+
 ## Accessing and Configuring Repository Rules
 
 You can typically find and configure Repository Rules within the settings page for each specific repository in the Codegen web UI.