From 50136b2ffd157d9d2b73af45ae55e749504e8391 Mon Sep 17 00:00:00 2001
From: windyboy <windyboy@gmail.com>
Date: Sat, 29 Aug 2026 20:25:53 +0800
Subject: [PATCH] =?UTF-8?q?docs(hass):=20W1N-238=20=E2=80=94=20scribe=20co?=
 =?UTF-8?q?nfig=20split=20to=20scribe.yaml=20+=20templates/=20merge=20incl?=
 =?UTF-8?q?ude?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Scribe 3.8.0 block moved verbatim from configuration.yaml to
  /homeassistant/scribe.yaml (scribe: !include scribe.yaml); YAML stays
  authoritative, import semantics unchanged.
- template: switched to !include_dir_merge_list templates; new
  quick_sensors.yaml scaffold (top-level list, quick_ prefix, unique_id
  required; pure sums stay min_max per W1N-233).
- Verified post-restart 2026-08-29 20:19 CST: core check ok, scribe
  connection on, states_written 18581→19426, template entities = 12,
  no scribe/template log errors. Backup configuration.yaml.bak-20260829-201724-w1n238.
---
 hosts/hass.windy.lan.md | 29 +++++++++++++++++++++++++++--
 1 file changed, 27 insertions(+), 2 deletions(-)

diff --git a/hosts/hass.windy.lan.md b/hosts/hass.windy.lan.md
index 6b25509..de7b4b2 100644
--- a/hosts/hass.windy.lan.md
+++ b/hosts/hass.windy.lan.md
@@ -322,9 +322,12 @@ deployed 2026-08-18 from `216cc99` (backup
 ### Scribe long-term history (verified 2026-08-29)
 
 - **Scribe 3.8.0** (`/homeassistant/custom_components/scribe/`), configured from
-  `configuration.yaml` (`scribe:` block; config entry
+  `/homeassistant/scribe.yaml` — W1N-238 moved the block out of
+  `configuration.yaml` on 2026-08-29 (main config now carries
+  `scribe: !include scribe.yaml`; content moved verbatim; backup
+  `configuration.yaml.bak-20260829-201724-w1n238`). Config entry
   `01KC2VFJWEQ3XDHY6TQKHPDVRB`, `source: import` — UI "Configure → Advanced"
-  edits are overridden by the YAML on restart; treat YAML as authoritative).
+  edits are overridden by the YAML on restart; treat YAML as authoritative.
 - TimescaleDB at `192.168.55.15:5432/scribe` (DB user `hass`; host in inventory,
   see [hosts/pgdb.md](../hosts/pgdb.md)). Database re-initialized 2026-08-29 14:06 CST
   (user-handled; earlier `relation "entities" does not exist` errors resolved).
@@ -351,6 +354,28 @@ deployed 2026-08-18 from `216cc99` (backup
 - Recorder stays external-Postgres with `purge_keep_days: 30` for daily UI
   history; Scribe is the permanent archive.
 
+### Config layout: scribe.yaml + templates/ merge (W1N-238, verified 2026-08-29)
+
+- `configuration.yaml` line 29: `scribe: !include scribe.yaml`; line 9:
+  `template: !include_dir_merge_list templates`. No `packages/`.
+- `scribe.yaml` (config root): the Scribe block, content identical to the
+  former inline one; import semantics unchanged.
+- `templates/`: `csg_sensors.yaml` (12 template sensors, top-level **list**)
+  + `quick_sensors.yaml` (scaffold for Quick-derived `quick_*` sensors, empty
+  list with convention header). **`!include_dir_merge_list` merges per-file
+  lists; non-list files are silently skipped** — every file in `templates/`
+  must be a top-level list (`- sensor:` blocks). Directory include only picks
+  up `*.yaml`, so the `.bak` / `.pre-*` backups in the dir are ignored. After
+  adding sensors, verify template-platform entity count = 12 + N (entity
+  registry `platform: template`).
+- Convention (per review + W1N-233): pure sums/averages stay min_max helpers
+  (e.g. `sensor.dang_qian_zong_gong_lu`); only template-logic derivations
+  (ladder pricing, cross-entity conditions) go into `quick_sensors.yaml`.
+- Post-change verification 20:19 CST: `ha core check` ok, 92 s restart
+  (2026.8.3), `binary_sensor.scribe_database_connection` on,
+  `scribe_states_written` 18581→19426 growing, template entities still 12,
+  csg sensors numeric, no scribe/template log errors.
+
 ### Timescale Plotly card + database reader (verified 2026-08-29)
 
 Chart stack over the Scribe TimescaleDB archive. Upstream pair (no HACS;