docs: troubleshooting guide + production notes

- docs/troubleshooting.md — 13 секций с реальными grабельками которые мы
  прошли: cudaIpcOpenEventHandle invalid device context (pid namespace),
  s6-overlay vs pid share, scale_cuda missing (cuda-llvm + stdbit.h glibc 2.36),
  libcuframes not found install paths, ffbuild/ missing source, GMP no working
  compiler (long-long reliability), zlib.net deprecated URL, RTSP/RTP UDP
  docker NAT, gitea actions Node version
- docs/architecture.md — Appendix A "Production deployment notes" с реальными
  observations после 24h+ run: что подтвердилось, что доработали, что не учли
- docs/requirements.md — production deployment matrix + Docker namespace
  requirements таблица (cross-container CUDA IPC требует 5 условий)

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

docs/architecture.md

@@ -423,3 +423,84 @@ mosaic + RTSP-server. После v1 cuframes:
 3. После Phase 0 — review результатов, корректировка дизайна (если CUDA IPC
    повёл себя не как ожидали)
 4. Phase 1+ по плану
+
+---
+
+# Appendix A — Production deployment notes (post-v0.1.0)
+
+Реальные наблюдения после первого production deployment (Frigate + cctv-processor
+на RTX 5090, 24h+ uptime). Обновляется по мере накопления опыта.
+
+## Что подтвердилось из изначального дизайна
+
+- **CUDA IPC handshake через cudaIpcEventHandle_t работает стабильно** — нет
+  ни одного torn frame за 24+ часов на 2 consumer'ах.
+- **EXTERNAL ownership** (publisher передаёт свои pre-allocated CUDA pointers)
+  необходим для FFmpeg-based publisher — иначе нужен extra cudaMemcpy из FFmpeg's
+  hwframe pool в library-managed pool.
+- **Unix socket handshake** ОК — простой, debug'абельный (`socat` для inspect).
+- **POSIX shm для header + atomic seq counters** — race-free на reader side.
+
+## Что пришлось доработать в v0.1.0 vs initial design
+
+- **CMake install rules** изначально не предусмотрены. Downstream проекты
+  делали `cmake --install` → пустой prefix. Fix: `install(TARGETS ...)` +
+  `install(DIRECTORY include/cuframes ...)`. Лессон — install rules должны
+  быть в day 1.
+- **Variable HINTS в find_library**: пользователи делают install в разные
+  prefix'ы. HINTS для downstream `find_library(cuframes)` должны включать
+  `$PREFIX/lib`, `$PREFIX/lib64`, и `build-dir/libcuframes/` для local-dev.
+
+## Что не учли в дизайне (открытые grабли — см. troubleshooting.md)
+
+### Cross-container CUDA IPC требует **shared pid + ipc namespace**
+
+`cudaIpcOpenEventHandle` validates IPC peer через `/proc/<pid>/...`. Если
+consumer container не в same PID namespace что publisher — fail с
+`invalid device context`.
+
+Это **incompatible** с s6-overlay-based containers (linuxserver.io stack,
+Frigate), требующими PID 1 для self. Workaround: только `ipc:` shared,
+accept race window (works на Frigate в практике потому что подключается
+первым после publisher restart). **Real fix planned v0.2**: socket-based
+context validation вместо `/proc` reliance.
+
+### Publisher-side resize нужен для consumers без cuda-llvm
+
+Большинство downstream FFmpeg builds — без `--enable-cuda-llvm` (на платформах
+с glibc < 2.38 эта опция не собирается, нужен `stdbit.h`). Без cuda-llvm нет
+`scale_cuda` filter. Consumer вынужден CPU-resize либо отключать hwaccel.
+
+**Fix planned v0.2**: publisher принимает `--scale=WxH` и делает GPU resize
+до publish. Consumer получает уже scaled frames, scale_cuda не нужен.
+
+### Encoded packet sharing — отсутствует в v0.1
+
+cuframes v0.1 раздаёт **только decoded** NV12. Для `record` use case
+(`-c:v copy` mux без decode) consumer всё ещё открывает свой RTSP — лимит
+камеры на concurrent streams (4-5 у Dahua) hit'ится.
+
+**v0.2 spec**: parallel encoded-packets ring + `cuframes_packets://`
+demuxer. См. [issue #2](https://git.goldix.org/gx/cuframes/issues/2).
+
+## Production setup (gold path)
+
+```
+                           ┌─► Frigate (FFmpeg cuframes:// demuxer) → detect
+Camera RTSP ─► publisher ──┤
+   (1× NVDEC)               └─► cctv-processor (CuframesSource C++ API) → motion+RTSP-encode→TV
+```
+
+| Метрика | Without cuframes (baseline) | С cuframes v0.1 |
+|---|---|---|
+| NVDEC operations на parking-камеру | 2 (Frigate detect + cctv detect) | **1** (publisher) |
+| VRAM extra cost | 0 (каждый своё) | ~3 MB (ring 6×460KB sub-stream) |
+| RTSP camera load | 2 streams | **1** stream |
+| Uptime (verified) | n/a | 24h+ без drops |
+
+## См. также
+
+- [docs/troubleshooting.md](troubleshooting.md) — конкретные грабли + fixes
+- [BENCHMARKS.md](../BENCHMARKS.md) — измерения
+- [docs/integrations/frigate.md](integrations/frigate.md) — guide для Frigate
+- [ROADMAP.md](../ROADMAP.md) — v0.2/v0.3/v1.0