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.

tools/chatgui-android/headless/headless_control.h

@@ -1,32 +1,9 @@
-/*
- * headless_control.h — JSON control socket for uTun headless mode
- *
- * JSON line protocol:
- *   Request:  {"id":N,"cmd":"<command>",...params}
- *   Response: {"id":N,"ok":true,"data":{...}} | {"id":N,"ok":false,"error":"..."}
- *   Event:    {"event":"<type>",...}
- *
- * Commands:
- *   ping           — alive check
- *   status         — node info, uptime, connections
- *   connect        — STCP connect to peer
- *   disconnect     — STCP disconnect
- *   connections    — list active connections
- *   create_channel — create chat channel
- *   channels       — list channels
- *   send           — send message to channel
- *   messages       — get messages from channel
- *   debug_level    — get/set debug levels
- *   subscribe      — subscribe to events
- *   join           — join channel via invite link
- *   quit           — disconnect client
- *
- * Events (after subscribe):
- *   log      — {"event":"log","level":"info","cat":"ETCP","msg":"..."}
- *   msg      — {"event":"msg","ch":"id","author":"hex","ts":123}
- *   peer_online/offline
- *   channel_created/joined
- */
+/* Каркас TCP-управления Android headless: init → регулярный poll → destroy в одном потоке.
+ * ua сейчас не используется; основной рабочий API чата — src/chat/chat_headless_control.h.
+ * JSON line: {"id":N,"cmd":"..."} → {"id":N,"ok":true,"data":...} либо error.
+ * ping/status/connections/debug_level возвращают заглушки; subscribe/quit управляют клиентом.
+ * join/chat_setting обращаются к запущенному instance_lite; прочие команды дают not implemented.
+ * event/broadcast_log отправляют JSON подписанным клиентам. Этот модуль сам ядро не запускает. */
 #ifndef HEADLESS_CONTROL_H
 #define HEADLESS_CONTROL_H