docs(builtins): correct enable semantics — builtins default to disabled

cupcake-core/src/engine/builtins.rs

@@ -58,7 +58,7 @@ pub struct BuiltinsConfig {
 /// Configuration for always_inject_on_prompt builtin
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct AlwaysInjectConfig {
-    /// Whether this builtin is enabled (defaults to true)
+    /// Whether this builtin is enabled (defaults to false; must be set explicitly)
     #[serde(default = "default_enabled")]
     pub enabled: bool,
 
@@ -74,7 +74,7 @@ fn default_enabled() -> bool {
 /// Configuration for git_pre_check builtin
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct GitPreCheckConfig {
-    /// Whether this builtin is enabled (defaults to true)
+    /// Whether this builtin is enabled (defaults to false; must be set explicitly)
     #[serde(default = "default_enabled")]
     pub enabled: bool,
 
@@ -86,7 +86,7 @@ pub struct GitPreCheckConfig {
 /// Configuration for post_edit_check builtin
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct PostEditCheckConfig {
-    /// Whether this builtin is enabled (defaults to true)
+    /// Whether this builtin is enabled (defaults to false; must be set explicitly)
     #[serde(default = "default_enabled")]
     pub enabled: bool,
 
@@ -127,7 +127,7 @@ pub enum ContextSource {
 /// Configuration for rulebook_security_guardrails builtin
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct RulebookSecurityConfig {
-    /// Whether this builtin is enabled (defaults to true)
+    /// Whether this builtin is enabled (defaults to false; must be set explicitly)
     #[serde(default = "default_enabled")]
     pub enabled: bool,
 
@@ -151,7 +151,7 @@ fn default_protected_paths() -> Vec<String> {
 /// Configuration for protected_paths builtin
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct ProtectedPathsConfig {
-    /// Whether this builtin is enabled (defaults to true)
+    /// Whether this builtin is enabled (defaults to false; must be set explicitly)
     #[serde(default = "default_enabled")]
     pub enabled: bool,
 
@@ -171,7 +171,7 @@ fn default_protected_paths_message() -> String {
 /// Configuration for git_block_no_verify builtin
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct GitBlockNoVerifyConfig {
-    /// Whether this builtin is enabled (defaults to true)
+    /// Whether this builtin is enabled (defaults to false; must be set explicitly)
     #[serde(default = "default_enabled")]
     pub enabled: bool,
 
@@ -193,7 +193,7 @@ fn default_git_block_no_verify_message() -> String {
 /// Configuration for system protection builtin (global only)
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct SystemProtectionConfig {
-    /// Whether this builtin is enabled (defaults to true)
+    /// Whether this builtin is enabled (defaults to false; must be set explicitly)
     #[serde(default = "default_enabled")]
     pub enabled: bool,
 
@@ -213,7 +213,7 @@ fn default_system_protection_message() -> String {
 /// Configuration for sensitive data protection builtin (global only)
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct SensitiveDataProtectionConfig {
-    /// Whether this builtin is enabled (defaults to true)
+    /// Whether this builtin is enabled (defaults to false; must be set explicitly)
     #[serde(default = "default_enabled")]
     pub enabled: bool,
 
@@ -233,7 +233,7 @@ fn default_sensitive_data_message() -> String {
 /// Configuration for cupcake execution protection builtin (global only)
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct CupcakeExecProtectionConfig {
-    /// Whether this builtin is enabled (defaults to true)
+    /// Whether this builtin is enabled (defaults to false; must be set explicitly)
     #[serde(default = "default_enabled")]
     pub enabled: bool,
 
@@ -253,7 +253,7 @@ fn default_cupcake_exec_message() -> String {
 /// Configuration for enforce_full_file_read builtin
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct EnforceFullFileReadConfig {
-    /// Whether this builtin is enabled (defaults to true)
+    /// Whether this builtin is enabled (defaults to false; must be set explicitly)
     #[serde(default = "default_enabled")]
     pub enabled: bool,
 

docs/docs/reference/builtin-config.md

@@ -44,9 +44,9 @@ signals:
 # Builtins provide common security patterns without writing Rego policies.
 # Each builtin can be enabled/disabled and configured independently.
 #
-# IMPORTANT: Builtins are ENABLED BY DEFAULT when configured.
-# Simply configuring a builtin (even with just empty settings) enables it.
-# To disable, either remove the configuration or set 'enabled: false'.
+# IMPORTANT: Builtins must be explicitly enabled with 'enabled: true'.
+# Configuring a builtin alone does NOT enable it - the 'enabled' field
+# defaults to false. To turn one on, set 'enabled: true' on its block.
 #
 # FILE PROTECTION BUILTINS (Two-Tier System):
 # 1. protected_paths: Makes specific paths read-only (read allowed, write blocked)
@@ -61,7 +61,7 @@ builtins:
   # Note: This builtin only works with Claude Code due to context injection support.
 
   # claude_code_always_inject_on_prompt:
-  #   # enabled: true  # Optional - defaults to true when configured
+  #   enabled: true  # Required to activate (defaults to false)
   #   context:
   #     # Static text context
   #     - "Follow SOLID principles and write comprehensive tests"
@@ -97,7 +97,7 @@ builtins:
   # feedback about syntax errors, type issues, or style violations.
 
   # post_edit_check:
-  #   # enabled: true  # Optional - defaults to true when configured
+  #   enabled: true  # Required to activate (defaults to false)
   #   # Checks by file extension
   #   by_extension:
   #     "rs":
@@ -185,11 +185,12 @@ builtins:
 
 ### Enabling/Disabling Builtins
 
-By default, builtins are **enabled when configured**. You don't need `enabled: true` explicitly:
+Builtins must be **explicitly enabled** with `enabled: true`. Configuring a builtin alone does not activate it — the `enabled` field defaults to `false`:
 
 ```yaml
 # This enables the builtin
 git_pre_check:
+  enabled: true
   checks:
     - command: "npm test"
 ```

docs/docs/tutorials/claude-code.md

@@ -159,7 +159,7 @@ The point here is that cupcake ships with numerous built-in rego rulesets.
 
 **`Built-ins` are special policies that:**
 
-- Are enabled by default in `rulebook.yml`
+- Are enabled in `rulebook.yml` with `enabled: true`
 - Protect critical system functionality
 - Cannot be easily bypassed, even by AI agents
 - Provide layered security (global + project level)

docs/docs/tutorials/cursor.md

@@ -146,7 +146,7 @@ Cursor was blocked by the `rulebook_security_guardrails` builtin, which protects
 
 **`Built-ins` are special policies that:**
 
-- Are enabled by default in `rulebook.yml`
+- Are enabled in `rulebook.yml` with `enabled: true`
 - Protect critical system functionality
 - Cannot be easily bypassed by AI agents
 - Provide layered security (global + project level)

docs/docs/tutorials/opencode.md

@@ -150,7 +150,7 @@ What happened? OpenCode was blocked by the `rulebook_security_guardrails` builti
 
 **`Built-ins` are special policies that:**
 
-- Are enabled by default in `rulebook.yml`
+- Are enabled in `rulebook.yml` with `enabled: true`
 - Protect critical system functionality
 - Cannot be easily bypassed, even by AI agents
 - Provide layered security (global + project level)

fixtures/init/base-config.yml

@@ -29,9 +29,9 @@ signals:
 # Builtins provide common security patterns without writing Rego policies.
 # Each builtin can be enabled/disabled and configured independently.
 #
-# IMPORTANT: Builtins are ENABLED BY DEFAULT when configured. 
-# Simply configuring a builtin (even with just empty settings) enables it.
-# To disable, either remove the configuration or set 'enabled: false'.
+# IMPORTANT: Builtins must be explicitly enabled with 'enabled: true'.
+# Configuring a builtin alone does NOT enable it - the 'enabled' field
+# defaults to false. To turn one on, set 'enabled: true' on its block.
 #
 # FILE PROTECTION BUILTINS (Two-Tier System):
 # 1. protected_paths: Makes specific paths read-only (read allowed, write blocked)
@@ -64,11 +64,11 @@ builtins:
   # ---------------------------------------------------------------------------
   # Inject additional context with every user interaction. Useful for project
   # guidelines, current state awareness, or team conventions.
-  # Note: Builtins are enabled by default when configured. Use 'enabled: false' to disable.
+  # Note: Builtins must be explicitly enabled with 'enabled: true' (default: false).
   # Note: This builtin only works with Claude Code due to context injection support.
 
   # claude_code_always_inject_on_prompt:
-  #   # enabled: true  # Optional - defaults to true when configured
+  #   enabled: true  # Required to activate (defaults to false)
   #   context:
   #     # Static text context
   #     - "Follow SOLID principles and write comprehensive tests"
@@ -104,7 +104,7 @@ builtins:
   # feedback about syntax errors, type issues, or style violations.
 
   # post_edit_check:
-  #   # enabled: true  # Optional - defaults to true when configured
+  #   enabled: true  # Required to activate (defaults to false)
   #   # Checks by file extension
   #   by_extension:
   #     "rs":