diff --git a/docs/LIGHT.md b/docs/LIGHT.md
index ef81fe1b..19722599 100644
--- a/docs/LIGHT.md
+++ b/docs/LIGHT.md
@@ -246,6 +246,23 @@ The complete UI and runtime truth table lives in
 - Golden: `lighting-opaque-glow-two-doorways-dark` and the other `lighting-*`
   scenes, re-shot and approved 2026-08-11.
 
+## Which surfaces render pools
+
+Pools — and therefore wall shadows — exist on the **full plan only**:
+`houseplan-card` and the geometry editors. `visibilityPolygon()`
+(`src/light-visibility.ts`) is imported by those surfaces and by nothing else.
+
+`houseplan-space-card` takes the static path (`renderSpaceStatic()` in
+`src/space-render.ts`) and deliberately has no live radial pools; it shares the
+room fills and the independent data/base projection with the full plan, so a lit
+room is painted flat. Without a pool there is no shape to occlude, so the compact
+card shows no wall shadows. This is a cost decision, not an omission: the pool
+layer is the heaviest thing the product renders — it owns its own performance
+workflow, budgets and a per-run smoke (`large-house-glow-overlay-v1`).
+
+Reported from the field as a bug (#370), because the user guide promised that
+markers share everything with the full plan and said nothing about light.
+
 ## Performance
 
 The large cold geometry recalculation (20 rooms, 20 partitions, 14 columns,
diff --git a/docs/USER-GUIDE.md b/docs/USER-GUIDE.md
index 42eeb612..57d55c76 100644
--- a/docs/USER-GUIDE.md
+++ b/docs/USER-GUIDE.md
@@ -761,6 +761,14 @@ text sizing. `cycle` enables automatic space changes; interaction pauses it for
 hover, drag, more-info or actions. A footer button opens the full plan. Use it
 for compact dashboard navigation, not for home control.
 
+**Light is deliberately different here.** The compact card paints the flat fill
+of a lit room and the data-mode fills, but it builds no radial light pools from
+the lamps. Consequently it draws no wall shadows either: a shadow exists only as
+the shape of a pool, and with no pools there is nothing to occlude. The full plan
+computes the pools and how walls, openings and columns block them
+(`docs/LIGHT.md`); that is the most expensive part of the render, and it is
+exactly what the compact card trades away for being cheap.
+
 ```yaml
 type: custom:houseplan-space-card
 space: ground
diff --git a/docs/USER-GUIDE.ru.md b/docs/USER-GUIDE.ru.md
index 6bdde42f..0d51a3db 100644
--- a/docs/USER-GUIDE.ru.md
+++ b/docs/USER-GUIDE.ru.md
@@ -1482,6 +1482,13 @@ House Plan скрывает только собственную шапку. Ша
 план, но не открывают подсказки или more-info. Единственный интерактивный
 элемент — нижняя кнопка перехода.
 
+**Свет здесь другой, и это намеренно.** Компактная карточка рисует ровную
+заливку освещённой комнаты и заливки data-режимов, но не строит радиальные пулы
+света от ламп. Значит, на ней нет и теней от стен: тень существует только как
+форма пула, и без пулов затенять нечего. Полный план считает пулы и перекрытие
+светом стен, проёмов и колонн (`docs/LIGHT.md`) — это самая дорогая часть
+отрисовки, и компактная карточка платит за свою дешевизну именно ею.
+
 ```yaml
 type: custom:houseplan-space-card
 space: ground_floor