From ed4ac972b3784a0120710e81f3392907709fb5dc Mon Sep 17 00:00:00 2001
From: Sergey Matyunin <s.matyunin@justbusiness.site>
Date: Fri, 4 Sep 2026 16:56:50 +0300
Subject: [PATCH] docs: close alpha review findings

Issue: #448
User-Visible: no
---
 AGENTS.md             | 23 +++++++++++------------
 docs/RELEASE-NOTES.md | 14 ++++++++++++--
 2 files changed, 23 insertions(+), 14 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index ad58e5f5..33fa6396 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -399,21 +399,20 @@ Chromium — a `1e-6`-tolerance magnet-snap on the opening-*placement* path. It
 reproduces against the pristine committed bundle, so treat it as
 pre-existing/pixel-precision, not a regression you introduced.
 
-## Labs flags
+## Alpha experiments
 
 `src/labs.ts` is the single registry and resolver for hidden presentation
-experiments. Activate a live flag through `?hp-labs=<id>` or the shared hash
-grammar, remove it with `-<id>`, and use `off` to clear the set. Do not add a
-YAML/config switch for a Labs-only experiment. A new entry needs a unique
-lowercase id, issue, numeric-core `since`, numeric-core `expires`, summary and
-unit/browser coverage. Invalid or duplicate registry entries fail closed.
+experiments. One browser-local switch controls the complete set known to the
+installed build: `hp_alpha=1` in query or the shared hash grammar enables and
+persists it, while `hp_alpha=0` disables and persists it. Do not add per-feature
+URL/storage keys or a YAML/config switch. The legacy `hp-labs` grammar and
+`houseplan_card_labs_v1` storage are ignored and never migrated.
 
-Expiry is exclusive and ignores prerelease suffixes: an entry expiring at
-`1.65.0` is unavailable in `1.65.0-beta.1`. Before that cycle, either remove the
-experiment or graduate it through its own reviewed issue; never extend expiry as
-an incidental change. Labs may alter presentation only and must not gate data,
-migrations, stores, HA actions or network calls. Current renderer details are in
-`docs/ISOMETRIC.md`.
+A new registry entry needs a unique lowercase id, issue, summary and
+unit/browser coverage; it does not get `since` or `expires`. Invalid or duplicate
+entries fail closed. Alpha capabilities may alter presentation only and must not
+gate data, migrations, stores, HA actions or network calls. Current renderer
+details are in `docs/ISOMETRIC.md`.
 
 Demo harness render quirk: the fake `hass` in `demo.html` is set once, so opening the
 page directly in a browser renders the floor plan but **device icons only appear
diff --git a/docs/RELEASE-NOTES.md b/docs/RELEASE-NOTES.md
index a9752965..93e78904 100644
--- a/docs/RELEASE-NOTES.md
+++ b/docs/RELEASE-NOTES.md
@@ -5,7 +5,12 @@
 - Скрытый 3-D Просмотр снова доступен тестировщикам через единый бессрочный
   ключ `hp_alpha=1`; старое включение `hp-labs=iso` намеренно не переносится
   ([#448](https://github.com/Matysh/houseplan-card/issues/448)).
-- В Просмотре и киоске клик или тап по комнате теперь центрирует её и вписывает видимый пол и стены с полями 10%; подпись комнаты даёт то же действие с клавиатуры ([#152](https://github.com/Matysh/houseplan-card/issues/152)).
+- В Просмотре и киоске клик или тап по комнате теперь центрирует её и вписывает
+  видимый пол и стены с полями 10%, а подпись даёт то же действие с клавиатуры;
+  мебель примагничивается к обеим физическим граням наружной стены, а стрелки
+  сдвигают выбранный объект подложки ровно на одну клетку
+  ([#152](https://github.com/Matysh/houseplan-card/issues/152),
+  [#447](https://github.com/Matysh/houseplan-card/issues/447)).
 - Администратор может включить диагностику Zigbee-сети и при наведении видеть только прямые связи выбранного устройства из снимка ZHA или Zigbee2MQTT, не закрывая план полной сеткой ([#54](https://github.com/Matysh/houseplan-card/issues/54)).
 - Мелкие исправления и улучшения.
 
@@ -14,7 +19,12 @@
 - Hidden 3-D View is available to testers again through the single indefinite
   `hp_alpha=1` switch; the former `hp-labs=iso` state is intentionally not
   migrated ([#448](https://github.com/Matysh/houseplan-card/issues/448)).
-- In View and kiosk, clicking or tapping a room now centres it and fits its visible floor and walls with 10% margins; the room label offers the same action from the keyboard ([#152](https://github.com/Matysh/houseplan-card/issues/152)).
+- In View and kiosk, clicking or tapping a room now centres it and fits its
+  visible floor and walls with 10% margins, while the label offers the same
+  keyboard action; furniture snaps to either physical face of an exterior wall,
+  and Arrow keys move a selected Background object by exactly one grid cell
+  ([#152](https://github.com/Matysh/houseplan-card/issues/152),
+  [#447](https://github.com/Matysh/houseplan-card/issues/447)).
 - Administrators can enable Zigbee diagnostics and hover a device to see only its direct links from a ZHA or Zigbee2MQTT snapshot, without covering the plan with the full mesh ([#54](https://github.com/Matysh/houseplan-card/issues/54)).
 - Small fixes and improvements.