diff --git a/robot-repo-automaton/src/catalog.rs b/robot-repo-automaton/src/catalog.rs
index 2ea05282..3593f2d1 100644
--- a/robot-repo-automaton/src/catalog.rs
+++ b/robot-repo-automaton/src/catalog.rs
@@ -155,6 +155,10 @@ impl ErrorCatalog {
         })
     }
 
+    /// Extract catalogue entries from a quoted `define` form or an already
+    /// unwrapped list.
+    ///
+    /// Returns a catalogue-parse error when `value` is not a non-empty list.
     fn find_catalog_content(value: &Value) -> Result<Vec<&Value>> {
         // Handle (define error-catalog '(...)) structure
         if let Some(cons) = value.as_cons() {
diff --git a/robot-repo-automaton/src/confidence.rs b/robot-repo-automaton/src/confidence.rs
index 84aebdad..842871b3 100644
--- a/robot-repo-automaton/src/confidence.rs
+++ b/robot-repo-automaton/src/confidence.rs
@@ -298,11 +298,11 @@ impl ThresholdConfig {
     }
 }
 
-/// Check if a file is protected from bot deletion or modification.
+/// Return whether a target matches a protected basename, extension, or
+/// directory marker used to lower confidence for automated fixes.
 ///
-/// Protected files include project state, documentation, and checkpoint files
-/// that bots should NEVER delete or overwrite. These represent intentional
-/// project work that cannot be regenerated from templates.
+/// Basenames are matched case-insensitively; extension and directory matches
+/// are case-sensitive.
 fn is_protected_file(target: &str) -> bool {
     let basename = target.rsplit('/').next().unwrap_or(target);
 
diff --git a/robot-repo-automaton/src/hypatia.rs b/robot-repo-automaton/src/hypatia.rs
index 1df21804..c0502857 100644
--- a/robot-repo-automaton/src/hypatia.rs
+++ b/robot-repo-automaton/src/hypatia.rs
@@ -639,6 +639,9 @@ impl CicdHyperAClient {
 }
 
 /// Convert a verisimdb-data recipe JSON to a Rule.
+///
+/// Returns `None` unless the recipe has a string `id` and either a string
+/// `file_glob` or `pattern`.
 fn recipe_to_rule(recipe: &serde_json::Value) -> Option<Rule> {
     let id = recipe.get("id")?.as_str()?.to_string();
     let name = recipe