diff --git a/docs/architecture/README.md b/docs/architecture/README.md
new file mode 100644
index 0000000..887c81d
--- /dev/null
+++ b/docs/architecture/README.md
@@ -0,0 +1,37 @@
+# Architecture diagram
+
+
+
+Snapshot: 2026-08-27. Light/dark theme via `prefers-color-scheme`.
+
+## What
+
+- **Left column:** external (Client, Tailscale, Keenetic) + lan + all 22 overlay networks. One block = one network.
+- **Right column:** all stacks. Inside each stack — its nodes (containers).
+
+## How to update
+
+1. Re-fetch live state from the cluster:
+ ```
+ curl http://docker_socket_proxy:2375/networks | python3 -m json.tool > /tmp/nets.json
+ curl http://docker_socket_proxy:2375/services | python3 -m json.tool > /tmp/services.json
+ curl http://docker_socket_proxy:2375/tasks?filters='{"desired-state":"running"}' > /tmp/tasks.json
+ ```
+2. Compare counts/labels against `standalone-adaptive.svg`. Update blocks that changed.
+3. For new stacks/services: add a stack rect in the right column + 1+ node rects inside.
+4. For new networks: add a network block in the left column at the matching height.
+
+Convention:
+- `class="net-fill"` — overlay network (amber border)
+- `class="net-external-fill"` — Keenetic/lan (slate)
+- `class="ext-client-fill"` — Client (violet border)
+- `class="stack-fill"` — running stack (cyan border)
+- `class="node-fill"` — running container
+- `class="node-dead"` — dead/disabled (red dashed)
+- IPs in node title reflect current state — refresh when IPs change
+
+## Sources
+
+- `docker_socket_proxy` (read-only): `/networks`, `/services`, `/tasks`, `/containers/{id}/json`
+- `admin/ansible` repo: `poc/*/stack-compose.yml` for stack definitions
+- Gitea admin API: `POST /api/v1/repos/admin/ansible/issues` for tickets about drift
diff --git a/docs/architecture/mermaid.md b/docs/architecture/mermaid.md
new file mode 100644
index 0000000..a1cbab8
--- /dev/null
+++ b/docs/architecture/mermaid.md
@@ -0,0 +1,253 @@
+# Architecture diagram — full prod map
+
+> **Snapshot:** 2026-08-27 · sources: `docker_socket_proxy` + gitea admin API
+>
+> **Two views:**
+> - This file — **Mermaid flow** (high-level topology, all elements)
+> - `standalone-adaptive.svg` — **per-node detail** (IPs, container names)
+
+```mermaid
+flowchart LR
+ %% ==================== EXTERNAL ====================
+ subgraph EXT[" "]
+ direction TB
+ Client["Client
tailscale"]:::client
+ Keenetic["Keenetic
DNS · TLS"]:::external
+ Tailscale["Tailscale
subnet router"]:::external
+ lan["lan
192.168.1.0/24"]:::external
+
+ Client -->|https| Tailscale
+ Tailscale --> Keenetic
+ Keenetic -->|TLS term| lan
+ end
+
+ %% ==================== INGRESS / EGRESS ====================
+ subgraph IO[" "]
+ direction TB
+ ingress["ingress
10.0.0.0/24"]:::egress
+ proxy_egress["squid_egress
hermes_proxy
admin"]:::egress
+ nginx_nets["nginx_ingress
nginx_default
(DEAD)"]:::egress
+
+ lan -.->|egress| ingress
+ end
+
+ %% ==================== STACKS (deployed via brencher) ====================
+ subgraph BRENCHER_DEPLOYED["via brencher (PROFILES env)"]
+ direction TB
+ b_gitea["gitea"]:::stack
+ b_hermes["hermes"]:::stack
+ b_hermes_infra["hermes_infra"]:::stack
+ b_immich["immich"]:::stack
+ b_gmail_mcp["gmail_mcp"]:::stack
+ b_torrserv["torrserv_proxy"]:::stack
+ b_brencher2["brencher2
(deploy tool)"]:::deploy
+ end
+
+ ingress --> b_gitea
+ ingress --> b_hermes
+ ingress --> b_hermes_infra
+ ingress --> b_immich
+ ingress --> b_gmail_mcp
+ ingress --> b_torrserv
+
+ proxy_egress -.-> b_hermes_infra
+
+ b_brencher2 -.->|deploys| b_gitea
+ b_brencher2 -.->|deploys| b_hermes
+ b_brencher2 -.->|deploys| b_immich
+ b_brencher2 -.->|deploys| b_hermes_infra
+ b_brencher2 -.->|deploys| b_gmail_mcp
+ b_brencher2 -.->|deploys| b_torrserv
+
+ %% ==================== STACKS (standalone, not via brencher) ====================
+ subgraph STANDALONE["standalone (compose или ручной deploy)"]
+ direction TB
+ s_dsp["docker_socket_proxy"]:::stack
+ s_lampa["lampa-jackett
(compose)"]:::stack
+ s_photosHelper["photosHelper
(DEAD · Replicas: 0)"]:::dead
+ s_nginx["nginx
(DEAD · Replicas: 0)"]:::dead
+ s_registry["registry
(DEAD · Replicas: 0)"]:::dead
+ end
+
+ ingress --> s_dsp
+ ingress --> s_lampa
+
+ %% ==================== ZOMBIE STACKS (volumes only, no services) ====================
+ subgraph ZOMBIE["zombie stacks (volumes orphaned)"]
+ direction TB
+ z_nextcloud["nextcloud
(4 volumes)"]:::dead
+ z_portainer["portainer
(1 volume)"]:::dead
+ z_swarmpit["swarmpit
(1 volume)"]:::dead
+ z_sstp["sstp · softether
(4 volumes)"]:::dead
+ z_test["test
(1 volume)"]:::dead
+ z_torr_cache["torr_cache
(1 volume)"]:::dead
+ z_beszel["beszel-poc
(2 volumes)"]:::dead
+ end
+
+ %% ==================== EPHEMERAL (gitea act_runner jobs) ====================
+ subgraph EPHEMERAL["gitea act_runner ephemeral jobs"]
+ direction TB
+ eph_jobs["~48 exited
ephemeral job pods
(random names)"]:::ephemeral
+ end
+
+ b_gitea -.->|spawns| eph_jobs
+
+ %% ==================== INTERNAL NETS (one per stack) ====================
+ subgraph INTERNAL["internal nets (12)"]
+ direction TB
+ gitea_net["gitea_gitea"]:::internal
+ hermes_net["hermes_hermes"]:::internal
+ hi_net["hermes_infra_default"]:::internal
+ immich_net["immich_default"]:::internal
+ gmail_net["gmail_mcp_default"]:::internal
+ torr_net["torrserv_proxy_default"]:::internal
+ brencher2_nets["brencher2-net +
brencher2_default"]:::internal
+ dsp_net["dsp_default"]:::internal
+ lampa_net["lampa_default"]:::internal
+
+ b_gitea --> gitea_net
+ b_hermes --> hermes_net
+ b_hermes_infra --> hi_net
+ b_immich --> immich_net
+ b_gmail_mcp --> gmail_net
+ b_torrserv --> torr_net
+ b_brencher2 --> brencher2_nets
+ s_dsp --> dsp_net
+ s_lampa --> lampa_net
+ end
+
+ %% ==================== VOLUMES (153 total) ====================
+ subgraph VOLS["volumes (153 total, 18 mounted · 135 orphaned)"]
+ direction TB
+ vol_active["active: gitea_data · immich_* ·
hermes_*_data · brencher_tmp ·
docker_socket_proxy_*_data ·
torrserv_proxy_data · lampa_*"]:::volumes
+ vol_orphaned["orphaned: 119 (no stack) ·
nextcloud · portainer · sstp ·
swarmpit · test · torr_cache ·
beszel-poc · immich_postgres"]:::dead
+ end
+
+ %% ==================== SECRETS / CONFIGS (403 from socket proxy) ====================
+ subgraph SECRETS["secrets & configs (read-only proxy: 403)"]
+ direction TB
+ sec_known["known to exist in gitea app.ini:
LFS_JWT_SECRET · JWT_SECRET ·
SECRET_KEY · INTERNAL_TOKEN"]:::secret
+ sec_hermes["hermes-agent runtime secrets
(gmail creds · telegram token)"]:::secret
+ end
+
+ %% ==================== STYLING ====================
+ classDef client fill:#0f172a,stroke:#a78bfa,color:#ddd6fe
+ classDef external fill:#1e293b,stroke:#94a3b8,color:#cbd5e1
+ classDef egress fill:#052e16,stroke:#22c55e,color:#bbf7d0
+ classDef stack fill:#0c4a6e,stroke:#22d3ee,color:#cffafe
+ classDef dead fill:#1f1717,stroke:#fb7185,color:#fecaca,stroke-dasharray: 4 2
+ classDef deploy fill:#422006,stroke:#fbbf24,color:#fde68a
+ classDef ephemeral fill:#1e1b4b,stroke:#818cf8,color:#c7d2fe,stroke-dasharray: 2 2
+ classDef internal fill:#1e1b4b,stroke:#818cf8,color:#c7d2fe
+ classDef volumes fill:#0f172a,stroke:#475569,color:#cbd5e1
+ classDef secret fill:#0f172a,stroke:#f59e0b,color:#fde68a,stroke-dasharray: 3 2
+```
+
+## Полная картина прода
+
+### 🟢 Running stacks (12)
+
+**Через `brencher` (PROFILES env):**
+1. **gitea** — gitea_server + gitea_runner (act_runner для CI)
+2. **hermes** — hermes-agent + hermes-gateway
+3. **hermes_infra** — squid + sarg + hermes-ui + hermes-gateway + docker_socket_proxy + brencher-state-proxy
+4. **immich** — server + database + redis + machine-learning
+5. **gmail_mcp** — gmail-mcp-server + telegram-mcp-server
+6. **torrserv_proxy** — reverseproxy + fileserver
+7. **brencher2** — второй deploy tool (сам себя не деплоит)
+
+**Standalone (не через brencher):**
+8. **docker_socket_proxy** — standalone, для hermes-gateway
+9. **lampa-jackett** — docker-compose, port 9117
+
+**DEAD services (но стек определён):**
+10. **photosHelper** (Replicas: 0, 1 volume)
+11. **nginx** (Replicas: 0, 2 services, 5 volumes)
+12. **registry** (Replicas: 0, 1 volume)
+
+### 🟡 Zombie stacks (volumes, но 0 running services)
+
+Volumes остались после того как сервисы удалили. 4–5 volumes на стек:
+
+- **nextcloud** (4 volumes · config + данные)
+- **sstp** (4 volumes · SoftEther VPN, конфиг + logs)
+- **portainer** (1 volume · swarm UI)
+- **swarmpit** (1 volume · swarm UI)
+- **test** (1 volume)
+- **torr_cache** (1 volume)
+- **beszel-poc** (2 volumes · monitoring POC)
+
+### 🟣 Ephemeral: gitea act_runner job pods
+
+Когда CI job запускается в gitea, `act_runner` создаёт **ephemeral контейнер** со случайным именем (`romantic_wozniak`, `compassionate_goodall` и т.п.). После завершения контейнер остаётся в `exited` state. На текущий момент ~48 таких exited контейнеров.
+
+Реестр: image `ghcr.io/immich-app/runner-images:ubuntu-latest` (определён в `poc/gitea/config.yaml`).
+
+### 🔴 Volumes (153 total)
+
+- **18 mounted** в running контейнеры
+- **135 orphaned** (либо от zombie-стеков, либо anonymous)
+
+Основные используемые:
+- `gitea_data` — критичные данные gitea (NFS на 192.168.1.96:/root/volumes/gitea)
+- `immich_*` — uploads, model-cache, postgres
+- `hermes_infra_*_data`, `hermes_hermes_*_data`
+- `brencher_tmp`, `brencher2_tmp` — git clones
+- `lampa_jackett_config`
+- `torrserv_proxy_data`
+
+### 🔐 Secrets & configs
+
+`/configs` и `/secrets` через socket-proxy **403** (требуется POST:1). Известные по другим источникам:
+
+**В gitea `/data/gitea/conf/app.ini`:**
+- `LFS_JWT_SECRET`
+- `JWT_SECRET` (oauth2)
+- `SECRET_KEY`
+- `INTERNAL_TOKEN`
+
+**В hermes-agent runtime:**
+- Gmail API creds (для gmail_mcp server)
+- Telegram bot token (для telegram_mcp server)
+
+**Swarm configs** (из `poc/gitea/stack-compose.yml`):
+- `runner_config` — `config.yaml` для act_runner
+
+### 🗑️ Dead-overlay сети (сеть есть, контейнеров нет)
+
+- `nginx_ingress` (10.0.3.0/24) — для nginx-proxy, но nginx Replicas=0
+- `nginx_default` (10.0.4.0/24) — то же
+
+Сети **живые** в swarm mesh, но не используются.
+
+## Что НЕ показывает эта диаграмма
+
+- Конкретные IP контейнеров (см. `standalone-adaptive.svg`)
+- Cross-stack сети в деталях (см. SVG)
+- Точные timestamps exited containers
+- Полный список 119 orphaned volumes без stack'а
+
+## Как обновить
+
+Запусти в этом окружении:
+
+```bash
+# Stacks & services
+curl http://docker_socket_proxy:2375/services | jq -r '.[] | .Spec.Labels["com.docker.stack.namespace"]' | sort -u
+
+# Volumes per stack
+curl http://docker_socket_proxy:2375/volumes | jq -r '.Volumes[] | "\(.Name) \(.Labels["com.docker.stack_namespace"] // "no-stack")"'
+
+# Ephemeral containers (exited)
+curl http://docker_socket_proxy:2375/containers/json?all=1 | jq '[.[] | select(.State=="exited")] | length'
+
+# BRENCHER profiles (env var)
+curl http://docker_socket_proxy:2375/containers/brencher_brencher-backend* 2>/dev/null
+```
+
+## Связанные
+
+- `standalone-adaptive.svg` — per-node detail (IPs, container names)
+- `admin/ansible#5` — re-deploy hermes_squid
+- `admin/ansible#6` — pre-create socket_proxy overlay
+- `admin/ansible#7` — gitea stack deploy / app.ini fix
diff --git a/docs/architecture/standalone-adaptive.svg b/docs/architecture/standalone-adaptive.svg
new file mode 100644
index 0000000..e68f64b
--- /dev/null
+++ b/docs/architecture/standalone-adaptive.svg
@@ -0,0 +1,487 @@
+
+
\ No newline at end of file