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/opus_codec.h

@@ -1,3 +1,9 @@
+/* opus_codec — владеющие обёртки encoder/decoder libopus для int16 interleaved PCM.
+ * create принимает частоту и 1/2 канала; неположительная частота → 48000, неверные каналы → моно.
+ * Encoder/decoder имеют состояние потока; каждому нужен один последовательный владелец.
+ * frame_samples — отсчёты НА КАНАЛ: PCM вмещает frame_samples*channels элементов.
+ * encode возвращает байты Opus, decode — отсчёты на канал; отрицательное значение означает ошибку.
+ * out_cap — байты; decode с data=NULL/len=0 использует PLC libopus. Освобождение — соответствующим destroy. */
 #ifndef OPUS_CODEC_H
 #define OPUS_CODEC_H