docs: update file inventory and module header contracts

Refresh both AGENTS guides and clarify module purpose, usage, ownership, threading, return values and wire formats in headers. Remove the unused timeout_heap freed_count field and unimplemented getter.

lib/debug_config.h

@@ -80,7 +80,7 @@ typedef int debug_category_t;
 /* Debug configuration structure */
 typedef struct {
     debug_level_t level;                   // Global debug level (default: ERROR)
-    debug_level_t category_levels[DEBUG_CATEGORY_COUNT];  // Per-category levels (0 = disabled)
+    debug_level_t category_levels[DEBUG_CATEGORY_COUNT];  // Уровень категории: NONE наследует общий, DISABLED выключает
     int timestamp_enabled;                 // Include timestamps in output
     int function_name_enabled;             // Include function names
     int file_line_enabled;                 // Include file:line info
@@ -99,18 +99,19 @@ extern debug_config_t g_debug_config;
 void debug_config_init(void);
 
 /* Set debug level */
-// итоговый level = max (global level - здесь задается, category level)
+// Общий уровень применяется к категориям с уровнем NONE.
 void debug_set_level(debug_level_t level);
 
-/* Set debug level for specific category (0 = disabled, otherwise uses that level) */
+/* Уровень категории заменяет общий; NONE наследует его, DISABLED подавляет вывод. */
 void debug_set_category_level(debug_category_t category, debug_level_t level);
 
-/* Enable/disable specific categories */
+/* enable фиксирует текущий общий уровень; disable возвращает к наследованию (NONE).
+ * Для полного выключения использовать debug_set_category_level(cat, DEBUG_LEVEL_DISABLED). */
 void debug_enable_category(debug_category_t category);
 void debug_disable_category(debug_category_t category);
 void debug_set_categories(debug_category_t categories);
 
-/* Set masks directly */
+/* Установка уровня одной категории (аргумент categories — индекс, не битовая маска). */
 void debug_set_masks(debug_category_t categories, debug_level_t level);
 
 /* Configure output options */
@@ -126,7 +127,7 @@ int debug_reopen_log(void);
 void debug_enable_console(int enable);
 
 
-// IP address to string (static buffer, single-threaded)
+// IP/sockaddr в строку: результат возвращается по значению, освобождать не требуется.
 typedef struct {
     char str[54];  // INET6_ADDRSTRLEN(45) + 6chars (:port) + \0
 } ip_str_t;