docs: add Rule Types & Precedence (User vs Org vs Repo) + link-throughs

docs/docs.json

@@ -57,7 +57,12 @@
 					},
 					{
 						"group": "Settings",
-						"pages": ["settings/repo-rules", "settings/model-configuration"]
+						"pages": [
+							"settings/rules-overview",
+							"settings/organization-rules",
+							"settings/repo-rules",
+							"settings/model-configuration"
+						]
 					}
 				]
 			},

docs/settings/organization-rules.mdx

@@ -19,13 +19,17 @@ When you define Organization Rules, they are automatically applied to every agen
 
 ## Rule Hierarchy
 
-Organization Rules work in conjunction with Repository Rules to provide flexible rule management:
+Organization Rules work in conjunction with User Rules and Repository Rules to provide flexible rule management:
 
-1. **Organization Rules** are applied first as the baseline for all repositories
-2. **Repository Rules** can override or extend Organization Rules for specific repositories
-3. If both are defined, Repository Rules take precedence for conflicting instructions
+1. **Repository Rules** (most specific) take precedence over Organization and User Rules for that repository
+2. **Organization Rules** apply across the org and override User Rules
+3. **User Rules** (personal prompts) apply by default, unless overridden by Org or Repo rules
 
-This hierarchy allows you to set organization-wide defaults while still maintaining repository-specific customizations when needed.
+This hierarchy allows you to set organization-wide defaults while still maintaining repository-specific customizations when needed, while preserving user preferences where they don't conflict.
+
+<Note>
+For a complete overview of rule types and examples, see [Rule Types & Precedence](/settings/rules-overview).
+</Note>
 
 ## Setting Up Organization Rules
 
@@ -115,4 +119,3 @@ If the agent isn't following your rules as expected:
 - **[Model Configuration](/settings/model-configuration)**: Configure which AI model the agent uses
 
 Organization Rules provide a powerful way to maintain consistency across your entire organization while still allowing flexibility for individual repositories. Use them to establish your organization's coding culture and ensure all agent interactions align with your standards.
-

docs/settings/repo-rules.mdx

@@ -130,5 +130,5 @@ Repository rules are flexible and can be used for various purposes:
 </Tip>
 
 <Note>
-  Both manual repository rules and automatic rule files are applied *in addition* to any global prompting strategies or agent capabilities. They provide a repository-specific layer of instruction that helps ensure consistent behavior across your codebase.
+  For how Repository Rules interact with Organization and User Rules, see [Rule Types & Precedence](/settings/rules-overview).
 </Note>{" "}

docs/settings/rules-overview.mdx

@@ -0,0 +1,74 @@
+---
+title: "Rules Overview"
+sidebarTitle: "Rule Types & Precedence"
+icon: "layers"
+---
+
+Codegen supports three levels of rules that guide how the agent behaves. These rules are merged for every run and can override one another based on a clear precedence order.
+
+## The three rule types
+
+### 1) User Rules (Personal Prompts)
+- Where: Managed by each user at https://codegen.com/personal/prompts
+- Scope: Apply to runs initiated by that user, across all organizations and repositories they work on
+- Purpose: Personal preferences, style, and reminders (e.g., preferred commit style, tone for PR descriptions)
+
+### 2) Organization Rules
+- Where: Organization settings at https://codegen.com/settings/organization-rules
+- Scope: Apply to every repo and run in the organization
+- Purpose: Governance, security, and team-wide standards (e.g., no force-push, testing/coverage requirements)
+
+### 3) Repository Rules
+- Where: Repo settings at your repo page (e.g., https://codegen.com/repos/cloud/repo-rules)
+- Scope: Apply only to that repository
+- Purpose: Project- or repo-specific conventions and constraints (e.g., language choices, directory layout, commit prefixes)
+
+<Tip>
+  In addition to manual Repository Rules, Codegen auto-discovers rule files in the repo (e.g., `.cursorrules`, `.clinerules`, `.windsurfrules`, `**/*.mdc`, `.cursor/rules/**/*.mdc`, `CLAUDE.md`, `AGENTS.md`, `AGENT.md`). These are included with a global 25,000-character budget and are visible in AgentTrace under the SetActiveCodebase tool as "Repository Rules (Filesystem)".
+</Tip>
+
+## Precedence (who wins on conflict?)
+When rules conflict, the more specific layer wins.
+
+1. Repository Rules (most specific)
+2. Organization Rules
+3. User Rules (least specific)
+
+This means:
+- Repo Rules can override Org Rules and User Rules
+- Org Rules can override User Rules
+- User Rules provide defaults and personal preferences, but will not override Org/Repo mandates
+
+<Note>
+  This precedence ensures company-wide standards remain enforceable (Org Rules), while still allowing repositories to refine their own specific conventions (Repo Rules). User Rules help maintain personal productivity and consistency without breaking org or repo policies.
+</Note>
+
+## Examples
+
+- Example A: Commit messages
+  - User Rules: "Use short, descriptive commit subjects."
+  - Org Rules: "Follow Conventional Commits."
+  - Repo Rules: "Prefix commits with the service name (e.g., api:)."
+  - Result: The agent uses Conventional Commits with the repo-required prefix; the user’s personal preferences apply where they don’t conflict.
+
+- Example B: Force pushing
+  - User Rules: none
+  - Org Rules: "Never use git push --force."
+  - Repo Rules: none
+  - Result: The agent will not force push, even if asked in a user prompt.
+
+- Example C: Language choice
+  - User Rules: "Prefer TypeScript."
+  - Org Rules: none
+  - Repo Rules: "Write backend in Python (FastAPI)."
+  - Result: For this repo, the agent writes backend code in Python per repo policy; the user preference applies elsewhere.
+
+## Where to configure
+- User Rules: https://codegen.com/personal/prompts
+- Organization Rules: https://codegen.com/settings/organization-rules
+- Repository Rules: Your repo page, e.g., https://codegen.com/repos/cloud/repo-rules
+
+## Related docs
+- [Organization Rules](/settings/organization-rules)
+- [Repository Rules](/settings/repo-rules)
+