Clarify catalog parsing, protected-file matching, and recipe requirements in docstrings

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() {

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);
 

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