Merge pull request #88 from senyo888/develop

Release v2.0.9: promote develop to main

Author: senyo888

AGENTS.md

@@ -85,7 +85,7 @@ Humidity Intelligence is a deterministic Home Assistant environmental control en
 ## HA Lab Operational Validation Boundary
 
 - HA Lab may be used as Operational Beta Validation Infrastructure for beta deploys, post-deploy read-only checks, diagnostics review, and generated-card/entity-map sanity evidence.
-- HA Lab evidence is advisory process evidence only. It is not release authority, runtime authority, stable Home Assistant authority, or a substitute for Bella, Aetherwing, AetherCore, and Senyo gates.
+- HA Lab evidence is advisory process evidence only. It is not release authority, runtime authority, stable Home Assistant authority, or a substitute for Bella, Aetherwing, AetherCore, and maintainer gates.
 - HA Lab work must preserve source identity, exact version, target boundary, mutation classification, rollback evidence, and public/private documentation separation.
 - HA Lab validation must not authorize autonomous Home Assistant mutation, restarts, reloads, helper changes, dashboard mutation, output writes, stable runtime access, tags, releases, or PR merges.
 - Public docs and PRs may summarize HA Lab status in sanitized terms, but local reports, credentials, target URLs, private entity IDs, and machine-specific details must remain local-only.

ARCHITECTURE.md

@@ -80,6 +80,76 @@ and exposed without crashing the control loop.
 
 Optional frontend cards and UI dependencies must never block backend functionality.
 
+## External Service Authority
+
+External Home Assistant calls to `pause_control`, `resume_control`,
+`create_dashboard`, `purge_files`, `dump_diagnostics`, `self_check`,
+`v205_release_check`, `dump_cards`, `view_cards`, `flash_lights`, and
+`create_local_backup` require an admin user context whether they target one config
+entry or all entries. The read-only `list_saved_versions` service is also admin-gated
+because it exposes package-local snapshot inventory through a persistent
+notification. An `entry_id` narrows a target only; it is not an authorization bypass.
+
+Contextless background automation/script calls are intentionally rejected. Supported
+external use originates from an authenticated admin UI or API session; any future
+automated trusted route requires separate design approval.
+
+First-run dashboard creation may use a trusted internal setup helper only after the
+user explicitly selects dashboard creation in config flow. First-run card export,
+option-triggered regeneration, and release-check test exports use a separate trusted
+internal card exporter so admin-gating the public `dump_cards` and `view_cards`
+handlers does not break integration-owned continuity. Startup refresh remains
+cache-only and does not claim a filesystem export. Neither helper is exposed as a
+contextless service bypass. The config entry records a dashboard identifier only
+after registration succeeds. Dashboard creation authorization is separate from later
+dashboard visibility.
+
+Runtime-owned visual alerts call a separate trusted internal flashing helper after
+the deterministic engine has selected an alert lane. The public `flash_lights`
+service is admin-gated and is not the engine's control path; it cannot create,
+reorder, or override a lane decision.
+
+Generated-artifact purge must validate its full fixed target set before mutation,
+show the exact existing file and configured dashboard targets in a completed blocking
+notification before deletion, reject paths outside the direct owned basename set and
+non-regular filesystem objects, and report partial failures truthfully.
+
+Caller-selectable diagnostics and release-check report basenames must match
+`humidity_intelligence_*.json` and are written only inside the owned
+`<config>/humidity_intelligence/exports/` directory. Directory verification,
+creation, temporary writes, atomic replacement, cleanup, and report purge stay
+descriptor-relative, reject symlink/non-regular targets, and fail closed without a
+config-root fallback. In-process writes are serialized; concurrent same-name calls
+produce complete JSON and the last atomic replacement wins without promising caller
+invocation order. The fixed self-check report uses the same writer and exact
+`<config>/humidity_intelligence/exports/humidity_intelligence_self_check.json`
+destination. Entry-scoped purge owns no export report. Only an unscoped all-entry
+purge may remove the exact default diagnostics and fixed self-check exports;
+release-check, custom, and legacy config-root reports remain retained.
+
+Generated card YAML is written only inside
+`<config>/humidity_intelligence/ui/`. Directory verification, creation, temporary
+writes, atomic replacement, and cleanup are descriptor-relative and no-follow,
+reject symlink and non-regular targets, revalidate directory/file identity, and fail
+closed without a config-root fallback. Same-name writes are serialized. Multi-entry
+installations use entry-qualified filenames; single-entry installations retain the
+unqualified default names. Exact default/per-entry card and release-check test-card
+exports are purge-owned. Custom card names and legacy root YAML are retained.
+Adding a second entry re-exports every loaded entry with qualified names; removing
+back to one entry re-exports the remaining entry with unqualified names. Superseded
+owned-UI names are retained non-destructively, are no longer refreshed by HI, and
+remain externally readable until an exact purge. Config-entry removal owns only the
+removed entry's exact default/release-test UI exports and registered dashboard; it
+does not own reports, custom card exports, or legacy root files. When removal returns
+a multi-entry installation to one entry, the remaining entry's qualified files stay
+retained while fresh unqualified exports are written.
+Registered Lovelace dashboard YAML remains separately owned at
+`<config>/dashboards/<url_path>.yaml`.
+
+Dynamic state or attribute text rendered through generated-card HTML must be escaped
+at the HTML sink. The V1 Mobile presentation remains available but deprecated through
+v2.0.9; any removal requires a separately approved v2.1 migration contract.
+
 ## Home Assistant And HACS Boundaries
 
 Config flow, options flow, entity registry behavior, services, translations,

CHANGELOG.md

@@ -8,14 +8,98 @@ This project follows a practical changelog format for Home Assistant and HACS us
 
 ## Unreleased
 
+No unreleased changes.
+
+## 2.0.9 - 2026-07-28
+
 - Added the optional HI Support Bundle Inspector to the Pages artifact as a
-  separate, noindex preflight at `/humidity-intelligence/inspector/`. Diagnostic
-  parsing and handoff generation remain browser-local with zero automatic or
-  network diagnostic-content egress; the only export is user-triggered copying of
-  the allowlisted handoff. Native Home Assistant diagnostics remain the preferred
+  separate, noindex preflight at `/humidity-intelligence/inspector/`. Diagnostic parsing and
+  handoff generation remain browser-local with zero automatic or network
+  diagnostic-content egress; the only export is user-triggered copying of the
+  allowlisted handoff. Native Home Assistant diagnostics remain the preferred
   support attachment and the repository/Wiki remain support truth. Wiki update
-  status: `no-op` because existing diagnostics guidance remains authoritative.
+  status: `updated`; existing diagnostics guidance remains authoritative, and the
+  Services Reference now documents the final external service permission boundaries.
   Release-documentation status: `updated` by this entry.
+- Set integration metadata to stable `2.0.9`, aligned the release documentation, and
+  extended the backward-compatible `v205_release_check` manifest contract through
+  the v2.0.9 beta/rc/stable line. GitHub Releases and HACS remain the authoritative
+  publication and installed-package records.
+- Removed the HACS `country` metadata so Humidity Intelligence can be listed
+  globally instead of being limited to the GB store scope.
+- Restricted custom filenames for `dump_diagnostics` and `v205_release_check` to
+  the exact lowercase `humidity_intelligence_*.json` namespace so those report
+  writers cannot overwrite unrelated basename files in the Home Assistant config
+  folder. Defaults are unchanged. Automations or scripts using another custom
+  report filename must be updated, and Home Assistant must be fully restarted after
+  installing the package update; a config-entry reload alone is insufficient.
+- Moved caller-selectable diagnostics and release-check reports into the owned
+  `<config>/humidity_intelligence/exports/` directory with descriptor-relative
+  no-follow directory creation, same-directory atomic replacement, and no config-root
+  fallback. Existing config-root reports are retained without automatic migration.
+  Report consumers must update their full path. Concurrent writes are serialized and
+  the last atomic replacement wins. Entry-scoped purge does not delete export reports;
+  only unscoped all-entry purge may remove the exact default diagnostics export,
+  while release-check and custom reports remain retained.
+- Completed the runtime-owned artifact namespace: the fixed entity-bearing
+  `self_check` report now uses the secure report writer at
+  `<config>/humidity_intelligence/exports/humidity_intelligence_self_check.json`,
+  while generated `dump_cards`, `view_cards`, setup/options, and release-test card
+  YAML now writes under `<config>/humidity_intelligence/ui/`. Startup refresh remains
+  cache-only. Existing root
+  JSON/YAML is retained without copy, dual-write, symlink, move, or automatic
+  deletion; consumers must update paths after verifying fresh owned-directory output.
+- Clarified the setup/options UI and service/support guidance for existing users:
+  first-run and options notifications point to exact owned UI paths, `dump_cards`
+  versus `view_cards` notification behavior is explicit, legacy root cards are marked
+  stale, and retained-file manual cleanup is documented without wildcard or
+  registered-dashboard deletion.
+- Added descriptor-relative, no-follow, same-directory atomic YAML replacement with
+  directory/file identity revalidation and no config-root fallback. External
+  `self_check`, `dump_cards`, and `view_cards` calls now require authenticated admin
+  context before work begins; trusted integration-owned UI regeneration calls the
+  internal exporter directly. Adding a second entry re-exports all loaded entries
+  with qualified card names; removing back to one re-exports the remaining entry
+  with unqualified names while retaining the remaining entry's superseded qualified
+  files for exact purge.
+- Narrowed cleanup to exact owned artifacts. Entry-scoped purge may remove the
+  selected entry's default and release-test card exports plus its registered
+  dashboard, but no reports. Unscoped all-entry purge may also remove the fixed
+  default diagnostics and self-check reports. Config-entry removal separately owns
+  only the removed entry's exact default/release-test card exports and registered
+  dashboard. Custom card/report names, release-check reports, remaining-entry
+  superseded qualified files, and legacy root artifacts remain retained.
+- Required authenticated admin user context for every `dump_diagnostics` and
+  `v205_release_check` call. Non-admin, unknown-user, and contextless background
+  callers are rejected before report lookup, cache work, path resolution, writes, or
+  notifications. Direct authenticated admin UI/API calls remain supported.
+- Required admin user context for targeted and all-entry `pause_control` /
+  `resume_control` calls, explicit `create_dashboard`, and `purge_files`. Existing
+  background automations/scripts whose action context has no `user_id` can no longer
+  invoke those mutation services, even when configured by an admin. Use an
+  authenticated admin UI or API session; any future automated trusted route requires
+  separate design approval. First-run dashboard creation remains available through
+  the trusted config-entry setup path.
+- Required authenticated admin user context for every external `flash_lights`,
+  `create_local_backup`, and `list_saved_versions` call. Non-admin, unknown-user,
+  and contextless callers are rejected before light, snapshot, or inventory work.
+  `list_saved_versions` remains read-only but is gated because its persistent
+  notification exposes package-local snapshot metadata. Engine-owned visual alerts
+  use a separate trusted internal helper after deterministic lane selection, so
+  alert continuity, entity semantics, and lane ordering are unchanged.
+- Made `purge_files` validate its complete fixed set of direct HI-generated file and
+  configured-dashboard targets before mutation, publish the exact existing target
+  preview with a blocking notification, reject unsafe/non-regular filesystem
+  candidates, and report file or dashboard deletion failures as an incomplete purge.
+- Escaped dynamic room, target-profile, condensation, and mould text in the V1 Mobile
+  source and gallery templates. V1 Mobile remains exportable through v2.0.9 but is
+  deprecated for new dashboards in favor of V2 Mobile; removal is deferred to a
+  separate v2.1 migration proposal. Existing pasted V1 cards must be re-exported and
+  re-copied to receive the escaping fix.
+- Redacted private Home Assistant URLs and hosts, local network addresses, bearer
+  credentials and tokens, device IDs, local user paths, and Home Assistant entity IDs from
+  locally generated issue-triage body summaries before Markdown/HTML escaping.
+  Public issue links remain available for maintainer triage.
 
 ## 2.0.8 - 2026-07-05