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.

src/chat/chat_core_priv.h

@@ -1,8 +1,8 @@
 /*
  * chat_core_priv.h — внутренний заголовок для под-модулей chat_core
  *
- * Предоставляет доступ к глобальному состоянию g_cc и общим хелперам.
- * Не включать извне chat/ — только для chat_core*.c.
+ * Предоставляет per-instance chat_core_ctx через CC(inst), общие SQL/сериализационные хелперы
+ * и внутренние операции частей chat_core/member_sync. Не включать извне chat/.
  */
 
 #ifndef CHAT_CORE_PRIV_H
@@ -73,7 +73,7 @@ static inline size_t b64_decode(const char* src, size_t src_len, uint8_t* dst, s
     return out;
 }
 
-/* ── Глобальное состояние (определено в chat_core.c) ── */
+/* ── Состояние одного экземпляра (создаётся в chat_core.c) ── */
 
 struct ms_props_cbk;    /* member_sync.c */
 struct ms_apply_cbk;    /* member_sync.c */

src/chat/chat_headless_control.h

@@ -6,8 +6,10 @@
  *   Response: {"id":N,"ok":true,"data":{...}} | {"id":N,"ok":false,"error":"..."}
  *   Event:    {"event":"<type>",...}
  *
- * Commands: ping, status, channels, members, messages, send, invite,
- *           invite_nodes, connect, create_channel, subscribe, quit
+ * Команды каналов, DM, звонков/рации и настроек — в tools/chatcli_commands.txt;
+ * диспетчер реализации — chat_headless_control.c. Аудио PCM использует отдельные call/radio_headless сокеты.
+ * init регистрирует listener и события chat_event, destroy закрывает клиентов и снимает подписку.
+ * Все вызовы и команды исполняются в uasync-потоке экземпляра.
  */
 #ifndef CHAT_HEADLESS_CONTROL_H
 #define CHAT_HEADLESS_CONTROL_H

src/chat/invite_build.h

@@ -3,7 +3,7 @@
  *
  * Общий модуль для всех GUI (desktop chatgui, Android, headless CLI).
  * Логика выбора «лучшего узла» перенесена из tools/chatgui-android/jni_bridge.
- * Работает в uasync-потоке, использует общий контекст g_cc.
+ * Работает в uasync-потоке, использует chat_core_ctx конкретного UTUN_INSTANCE.
  */
 #ifndef INVITE_BUILD_H
 #define INVITE_BUILD_H

src/chat/invite_link.h

@@ -1,8 +1,11 @@
 /*
  * invite_link.h — invite-ссылки utun:// для каналов
  *
- * Формат: utun:// + base64(version | password? | channel_id | [header | pubkey | addrs]+)
- * Совместим с десктопной (Qt) и Android (Kotlin) версиями.
+ * Версия 0x03: utun:// + base64(version | pass_len/password | channel_id | join_key |
+ * reality_has/params | блоки pubkey/addrs). ID/port кодируются big-endian; nodeId выводится из pubkey.
+ * Общий формат с desktop Qt и Android Kotlin. Сам кодек не подключает узел и не регистрирует join_key.
+ * decode: 0/-1; encode: длина base64 без utun:// и NUL/-1; serialize_addrs: число байтов/-1.
+ * Буферы предоставляет вызывающий; encode завершает строку NUL.
  */
 #ifndef INVITE_LINK_H
 #define INVITE_LINK_H