haconf 0.1.0__tar.gz

haconf-0.1.0/.gitignore

@@ -0,0 +1,7 @@
+.venv/
+__pycache__/
+*.pyc
+.pytest_cache/
+dist/
+build/
+*.egg-info/

haconf-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 WraithWall <contact@wraithwall.online>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

haconf-0.1.0/PKG-INFO

@@ -0,0 +1,105 @@
+Metadata-Version: 2.5
+Name: haconf
+Version: 0.1.0
+Summary: Check Home Assistant YAML and Jinja before reload — no instance needed.
+License: MIT License
+        
+        Copyright (c) 2026 WraithWall <contact@wraithwall.online>
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Requires-Python: >=3.10
+Requires-Dist: jinja2==3.1.6
+Requires-Dist: pyyaml==6.0.3
+Provides-Extra: dev
+Requires-Dist: build==1.6.1; extra == 'dev'
+Requires-Dist: pytest==8.3.4; extra == 'dev'
+Requires-Dist: twine==7.0.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# haconf
+
+Check Home Assistant YAML and Jinja before you reload — no instance needed.
+
+Status: **I1–I8 — the v1 CLI is feature-complete.** It walks a configuration
+directory, runs a robust YAML loader (duplicate keys, multi-document files,
+quoting pitfalls such as `on`/`off`/`yes`/`no` and number-looking strings,
+tab/indentation errors), applies a bundled, versioned integration catalog
+(unknown keys under a known integration are errors, integration-name case
+mistakes are errors naming the correct form, unknown integrations are
+**informational only**), checks Jinja templates (compiled with Home Assistant's
+strict environment shape, rendered against a stub of HA's documented
+functions/filters — the **real** error text surfaces, e.g. `No filter named
+'strftime'`, instead of HA core's masked shape error), and runs the I4 integrity
+checks (`!include`/`!include_dir_*` targets must exist and stay inside the config
+dir; `!secret` keys must be defined in `secrets.yaml` — values are never read or
+printed; `packages:` entries must not be empty; automation/script
+trigger/condition/action shapes; duplicate `entity_id`s reported once each;
+template references to entities neither declared in the config dir nor present in
+`.storage/core.entity_registry` are flagged).
+
+**I8 closes the three scopes the audit left open:** a `homeassistant: packages:`
+body is checked like the top level (a package name is user-chosen and is never a
+key); the nested branches are walked (`choose`, `repeat` with its `while`/`until`,
+`parallel`, `if`/`then`/`else`, `wait_for_trigger`, and `condition: and`/`or`/`not`
+recursively), so a bare string three levels down is the same error as one at the
+top; and `custom_templates/*.jinja` files are checked as Jinja through one shared
+environment, so a macro imported from a sibling file is not an "undefined name".
+A `script:` block is a map of id → script config, in `configuration.yaml`,
+`packages:` and `scripts.yaml` alike — the id is a name, the body holds the
+options.
+
+I5 completes the contract: every finding carries a **severity** (error / warning
+/ info) and a **plain-language hint**; warnings and infos pass the run unless
+`--strict` escalates warnings; findings can be **suppressed visibly** via
+`.haconfignore` or an inline `# haconf: ignore=<rule-id>` (suppressed findings
+are always counted and printed, never hidden); and `--json` emits one complete
+machine-readable object including the suppressed counts. The catalog ships as
+package data and is never fetched at runtime.
+
+Release work is complete: packaging **I5c** (`docs/RELEASE.md`), the security
+pass **I6** (`scripts/security_sweep.py`; the N8–N12 absent-behaviour tests),
+and real-config validation **I7** (`docs/REAL-CONFIG-VALIDATION.md` — two pinned
+public config repositories; the validation exposed real gaps, all fixed and
+pinned by `tests/test_i7_fixes.py`).
+
+Exit codes: `0` clean (or informational findings only) · `1` findings with at
+least one error · `64` usage. The `64` is a deliberate extension of the
+contract's 0/1 (deviation **D-HC-1**, same rationale as RestVerify's D-I1: a
+usage failure is not a lint outcome and must not collide with 1).
+
+Read-only by construction: nothing under `src/` opens a file for writing, and the
+test suite proves it (static AST check + a dynamic `open()` guard).
+
+## Development
+
+```bash
+pip install -e '.[dev]'
+python -m pytest -q                  # 174 tests, ~2 s
+python scripts/security_sweep.py     # read-only / no-network / no-eval sweep
+python -m build                      # wheel + sdist in dist/
+```
+
+The same two commands run in CI (`.github/workflows/ci.yml`) on Python 3.10,
+3.11 and 3.12, plus a packaging job that installs the built wheel into a clean
+venv and asserts the catalog is inside it while `tests/` is not.
+
+## License
+
+MIT — see [`LICENSE`](LICENSE).

haconf-0.1.0/README.md

@@ -0,0 +1,70 @@
+# haconf
+
+Check Home Assistant YAML and Jinja before you reload — no instance needed.
+
+Status: **I1–I8 — the v1 CLI is feature-complete.** It walks a configuration
+directory, runs a robust YAML loader (duplicate keys, multi-document files,
+quoting pitfalls such as `on`/`off`/`yes`/`no` and number-looking strings,
+tab/indentation errors), applies a bundled, versioned integration catalog
+(unknown keys under a known integration are errors, integration-name case
+mistakes are errors naming the correct form, unknown integrations are
+**informational only**), checks Jinja templates (compiled with Home Assistant's
+strict environment shape, rendered against a stub of HA's documented
+functions/filters — the **real** error text surfaces, e.g. `No filter named
+'strftime'`, instead of HA core's masked shape error), and runs the I4 integrity
+checks (`!include`/`!include_dir_*` targets must exist and stay inside the config
+dir; `!secret` keys must be defined in `secrets.yaml` — values are never read or
+printed; `packages:` entries must not be empty; automation/script
+trigger/condition/action shapes; duplicate `entity_id`s reported once each;
+template references to entities neither declared in the config dir nor present in
+`.storage/core.entity_registry` are flagged).
+
+**I8 closes the three scopes the audit left open:** a `homeassistant: packages:`
+body is checked like the top level (a package name is user-chosen and is never a
+key); the nested branches are walked (`choose`, `repeat` with its `while`/`until`,
+`parallel`, `if`/`then`/`else`, `wait_for_trigger`, and `condition: and`/`or`/`not`
+recursively), so a bare string three levels down is the same error as one at the
+top; and `custom_templates/*.jinja` files are checked as Jinja through one shared
+environment, so a macro imported from a sibling file is not an "undefined name".
+A `script:` block is a map of id → script config, in `configuration.yaml`,
+`packages:` and `scripts.yaml` alike — the id is a name, the body holds the
+options.
+
+I5 completes the contract: every finding carries a **severity** (error / warning
+/ info) and a **plain-language hint**; warnings and infos pass the run unless
+`--strict` escalates warnings; findings can be **suppressed visibly** via
+`.haconfignore` or an inline `# haconf: ignore=<rule-id>` (suppressed findings
+are always counted and printed, never hidden); and `--json` emits one complete
+machine-readable object including the suppressed counts. The catalog ships as
+package data and is never fetched at runtime.
+
+Release work is complete: packaging **I5c** (`docs/RELEASE.md`), the security
+pass **I6** (`scripts/security_sweep.py`; the N8–N12 absent-behaviour tests),
+and real-config validation **I7** (`docs/REAL-CONFIG-VALIDATION.md` — two pinned
+public config repositories; the validation exposed real gaps, all fixed and
+pinned by `tests/test_i7_fixes.py`).
+
+Exit codes: `0` clean (or informational findings only) · `1` findings with at
+least one error · `64` usage. The `64` is a deliberate extension of the
+contract's 0/1 (deviation **D-HC-1**, same rationale as RestVerify's D-I1: a
+usage failure is not a lint outcome and must not collide with 1).
+
+Read-only by construction: nothing under `src/` opens a file for writing, and the
+test suite proves it (static AST check + a dynamic `open()` guard).
+
+## Development
+
+```bash
+pip install -e '.[dev]'
+python -m pytest -q                  # 174 tests, ~2 s
+python scripts/security_sweep.py     # read-only / no-network / no-eval sweep
+python -m build                      # wheel + sdist in dist/
+```
+
+The same two commands run in CI (`.github/workflows/ci.yml`) on Python 3.10,
+3.11 and 3.12, plus a packaging job that installs the built wheel into a clean
+venv and asserts the catalog is inside it while `tests/` is not.
+
+## License
+
+MIT — see [`LICENSE`](LICENSE).

haconf-0.1.0/docs/AUDIT-CORRECTIONS.md

@@ -0,0 +1,29 @@
+# AUDIT corrections (I1–I7 independent audit, 2026-09-26)
+
+Produced by an independent second agent. The full report is
+`haconf-AUDIT-briefing.md` in the audit clone `/home/deploy/oss/haconf-audit`
+(it was never part of this product repo). Audit HEAD was `046ab2f`; the audit
+added no product code beyond the regression test named below.
+
+- **AUDIT-HC-1 — regression guard added (`tests/test_audit_sweep_nocompile.py`).**
+  The I6 commit `476d0ce` was committed red: the security sweep flagged
+  `re.compile` as eval/exec, so `test_sweep_passes_on_the_shipped_tree` failed
+  (`1 failed, 122 passed`) and the sweep printed `RESULT: FAIL`, while
+  `haconf-I5-I7-briefing.md` §I6 and `haconf-BUILD-BRIEFING.md` §4 paste
+  `RESULT: PASS`. The code fix (`scripts/security_sweep.py`: `calls.items()` →
+  `bare_calls.items()`) landed in I7 `af08236` and was undocumented anywhere.
+  No user-facing impact: `src/haconf` was never affected.
+- **AUDIT-HC-2 — briefing error (no code change).** `haconf-I4-briefing.md`
+  claims the suite is `88` with "+23 new tests"; its own new-test list sums to
+  27 (10 + 6 + 7 + 4) and commit `2913307` actually collects and runs **92**.
+- **AUDIT-HC-3 — premise mismatch (no code change).** There is no
+  `tests/conftest.py` and `docs/PLAN.md` has no "Test infrastructure" section.
+- **AUDIT-HC-4 — plan instruction not followed (no code change; R43 NOT minted).**
+  Plan §3 I5c says packaging/release ids are "allocated when it starts"; commit
+  `6b6f33b` and `docs/RELEASE.md` mint no R-ids.
+- **AUDIT-HC-5 — briefing set incomplete (no code change).** No
+  `haconf-I1/I2/I6/I7` briefing files exist; that content is folded into
+  `haconf-BUILD-BRIEFING.md` and `haconf-I5-I7-briefing.md`.
+
+Unverifiable (recorded, not fixed): unreadable-file handling — the audit ran as
+`root`, so `chmod 000` is bypassed. A non-root run is required to settle it.

haconf-0.1.0/docs/FINDINGS.md

@@ -0,0 +1,139 @@
+# haconf — Phase 2 findings (evidence verification + landscape)
+
+Read-only exploration, 2026-09-25. Every claim below was re-checked live against the
+sources; pasted output is trimmed only by ellipses, never reworded. No accounts were
+created and no API keys beyond those already present in this environment were used
+(the existing `GITHUB_TOKEN` was used for read-only GitHub API calls; rate limit at
+start: 5000/h, 0 used). No writes to any live system. Nothing in the RestVerify repo
+was touched.
+
+Contract: `GAP-RESEARCH-2026-09.pdf` (extracted with `pdftotext -layout`; Product 2
+section lines 93–196 of the text dump). Where the PDF and the live world disagree,
+the PDF wins for the plan and the difference is logged here.
+
+*Amendment note (2026-09-25): the operator ruled the product name **haconf**; this
+document's product-name uses now read `haconf`. Recorded evidence is untouched —
+including the PyPI naming check below, where `haconf` is registered to an unrelated
+HAProxy tool and `haccheck` is unregistered. See `haconf-PLAN.md` §4 Q1.*
+
+---
+
+## 1. Verification table — PDF Product 2 claims
+
+| # | Claim (from the PDF) | Verdict | Pasted evidence |
+|---|---|---|---|
+| 1 | `home-assistant/core#169958` exists | **MATCH** | GitHub API 200. Title: *"Config validator masks TemplateAssertionError with a generic "should be a string" error in service-call data: dicts"* |
+| 2 | …is **open** | **MISMATCH** | `state: closed`, `state_reason: not_planned`, `closed_at: 2026-08-25T10:10:34Z`, label `stale`; closed by `issue-triage-workflows[bot]` ("marked as stale"). It was already closed when the PDF's data was retrieved (2026-09-14). |
+| 3 | Quoted text matches the issue | **MATCH** | Body: *"The discrepancy between the two error reports turns a one-line fix ("`strftime` isn't a filter, use `.strftime()` method") into an extended bisection."* Comment 2 (by `t0mr0zier`): *"the config validator catches the TemplateAssertionError: No filter named 'strftime' and re-reports it as a generic "template value should be a string for dictionary value" error pointing at the surrounding data: dict."* |
+| 4 | "reported on 2026.5.0" | **MATCH** | Body field: *"### What version of Home Assistant Core has the issue? 2026.5.0"* |
+| 5 | "maintainer-side discussion confirms the masking is the defect" | **MISMATCH** | Both human commenters have `author_association: NONE` (`tdejneka`, `t0mr0zier`); the third comment is the stale bot. No maintainer participated; the issue was auto-closed stale. The masking story is the reporter's, unchallenged — but not maintainer-confirmed. |
+| 6 | `home-assistant/core#110705` | **MATCH** | 200: *"Cannot quick reload all YAML configurations"*, closed `not_planned` (2024-05-26); body: *"…because the configuration is not valid: Unexpected error calling config validator: 'NodeStrClass' object has no attribute 'items' Traceback…"* (the `[mqtt]` half of the PDF's combined quote comes from the next row) |
+| 7 | `home-assistant/home-assistant.io#29440` | **MATCH** | 200: *"I cannot make examples in MQTT Light to work"*, closed `completed`; body contains the PDF's quote verbatim: *"Cannot quick reload all YAML configurations because the configuration is not valid: Invalid config for [mqtt]: expected dictionary for dictionary value @ data['mqtt']. Got [{'light': …"* |
+| 8 | `home-assistant/frontend#26063` "closed not planned" | **MATCH** | 200: *"[automation] Misleading validation: choose.conditions does not support inline templates"*, `state: closed`, `state_reason: not_planned` (closed 2025-07-05) |
+| 9 | Community thread *Quick reload not actually reloading YAML* + quote | **MATCH** | Topic 549186, 10 posts, 3,251 views. Post 1 (`teegee`): *"I press "Quick reload" and go back to debugging my shell_command only to find out that "Quick reload" did not reload my configuration.yaml file and is still using the old path configured in my shell_command."* Date nuance: created **2023-03-18**, last post **2024-03-16** — the PDF's "(Mar 2024)" is the thread's last activity, not the quoted post. |
+| 10 | Community thread *How to troubleshoot template issue?* + quote | **MATCH** | Topic 716717, 16 posts, accepted answer. Post 4 (`mandolin`): *"…my outstanding generic question is how do you find the template issues that "Developer Tools" → YAML and "Check Configuration" finds? Whenever I get those messages, there is nothing new in the home-assistant.log or any of the System log areas."* (created 2024-04-13) |
+| 11 | HA docs quote ("does not restart … persistent notification … logs") | **MATCH** | `source/_actions/homeassistant.restart.markdown` in the docs repo: *"If the configuration check fails, Home Assistant does not restart. Instead, it creates a persistent notification with the ID `persistent_notification.homeassistant_check_config`, and the logs show what failed the check."* (The PDF omits the notification ID.) |
+| 12 | r/homeassistant "templates.yaml error" ("I didn't get any error notifications about it until the…") | **UNVERIFIABLE** | The thread exists — `reddit.com/r/homeassistant/comments/1lxslar/templatesyaml_error_name_value/` ("templates.yaml error - name & value", ~1y old) — but the quoted sentence could not be located: Reddit blocks scraping ("we do not support this site") and search does not index the phrase. Thread: MATCH; quoted line: unverified. |
+| 13 | r/homeassistant "YAML syntax is the absolute worst!" / "YAML+Jinja2 is really crappy…" | **MATCH** | Live search hit: `reddit.com/r/homeassistant/comments/1mco55h/yaml_syntax_is_the_absolute_worst/` — snippet: *"YAML+Jinja2 is really crappy due to the weird indenting and paragraph and quoting rules."* |
+| 14 | r/homeassistant "Cannot quick reload all YAML" / "yaml is fine and validates…" | **MATCH** | Live search hit: `reddit.com/r/homeassistant/comments/19dkla4/anyone_know_how_to_fix_this_cannot_quick_reload/` — snippet: *"yaml is fine and validates - i've no idea what this is - but it means i can't reload - any ideas where i look/how i fix?"* |
+| 15 | Tool 1: HA built-in Check configuration — "server-side, reload-gated, masks template errors; **no laptop/CI/pre-commit path**" | **PARTIAL MISMATCH** | Server-side + reload-gating + masking: supported (docs + the issue's own text). "Runs **only inside a running instance**" / "no laptop path": **contradicted by core's own documented, maintained CLI**: `hass --script check_config` (docs `source/_docs/tools/check_config.markdown`: *"Test any changes … without the need to restart Home Assistant"*), container form `docker exec homeassistant python -m homeassistant --script check_config --config /config`, HAOS form `ha core check` (docs include `configuration_check.md`). The script is maintained: last commits 2026-08-25, 2026-07-16, 2026-04-30, 2026-03-27, 2025-11-06. What is true: it needs the (heavy) HA install or a running container; HAOS users cannot run it on a laptop; and it does **not** fix the masking. |
+| 16 | Tool 2: "homeassistant-cli / API clients (remote check_config; same server dependency)" | **PARTIAL** | The package lives on PyPI (`homeassistant-cli` v1.0.0, 2026-04-12): *"The Home Assistant Command-line interface (``hass-cli``) allows one to work with a local or a remote Home Assistant instance…"*. Its declared GitHub home (`homeassistant-ecosystem/homeassistant-cli`, per PyPI project URLs) now **404s** — org gone — so current capabilities cannot be checked against source. "Same server dependency" is fair for any API client; a `check_config` capability is *not* evidenced in the description. |
+| 17 | Tool 3: "Online validators / yamllint (syntax-only, not HA-aware)" | **MATCH** | yamllint repo live: ★3,467, pushed 2026-09-19, `"A linter for YAML files."` — generic YAML only; the "yaml is fine and validates" failure mode is the verified reddit quote above. |
+| 18 | MVP: "~40-integration catalog" is a defensible number | **MATCH (with source)** | HA Analytics `data.json` (live): 688,333 active installations, 1,369 integrations tracked. Top-60 captured (sun, person, automation, script, scene, template, mqtt, mobile_app, cast, bluetooth, matter, input_boolean/number/select/text/datetime/button, sensor, group, zone, light-adjacent `switch_as_x`, tts, http, hue, utility_meter, recorder, …). A curated 40 covering the top usage + the demo cases is defensible; the catalog is explicit about being partial (N8/N13). |
+| 19 | MVP: "Jinja compile with strict-undefined + stubbed context" is realistic | **MATCH (with scope note)** | HA still uses Jinja2 — `homeassistant` PyPI deps: `Jinja2==3.1.6`, `PyYAML==6.0.3`. Core source: `helpers/template/__init__.py:709: return jinja2.StrictUndefined` and `L822: class TemplateEnvironment(ImmutableSandboxedEnvironment):`. The documented function/filter surface (e.g. `states()`, `is_state()` in the docs page) can be hand-stubbed. Scope note: entity *existence* cannot be inferred from config files alone → see Q4; compile-time filter errors need no stub at all. |
+| 20 | MVP: "surface the underlying error instead of masking it" is achievable offline | **MATCH (design note)** | The masking lives in HA's config-validation layer (re-reporting the `TemplateAssertionError` as a shape error — issue text above). A standalone tool that compiles templates itself gets `TemplateAssertionError: No filter named 'strftime'` directly at compile time and never passes through that layer. Caveat: HA's own wording stays HA's; and the issue is closed *not planned*, so the masking can persist in core. |
+| 21 | Gap: "no maintained local validator exists" | **MATCH (as of 2026-09-25, with two newcomers logged)** | Searches found: no maintained standalone HA-aware linter. Closest: `ludeeus/action-ha-config-check` (★22, **archived 2021**), `custom-components/config_check` (★7, archived 2021), `MacDada/HomeAssistant_ConfigCheckCli` (★0, 2024, no README), `MacSiem/ha-yaml-checker` (★1, Aug 2026 — a **Lovelace card** that runs HA's own check against your **running instance**, not standalone), `KanadeK/hasstangle` (★0, created 2026-07-30, JS/MIT — offline *automation-semantics* analyzer: "feedback loops, conflicting writes, concurrency hazards, stale entities, SARIF"; not a YAML/Jinja config linter). No pre-commit hook for user configs (searches: `legovaer/pre-commit-hooks` ★0/2023; nothing maintained). |
+| 22 | Star-traction & adoption-test claims | **MATCH (qualitative)** | No numeric star targets are given for haconf; the three community plays and the 7-point adoption test were extracted verbatim into `haconf-PLAN.md` §1. Nothing to re-measure. |
+
+Summary: **12 MATCH · 3 MISMATCH/partial-that-matter (rows 2, 5, 15) · 1 partial
+(16) · 1 UNVERIFIABLE line (12, quoted sentence only) · 5 MATCH-with-source/scope
+notes.** No load-bearing claim that would invalidate the product idea failed: the
+masking class is real and reproduced by the issue text; the demand quotes are real.
+
+---
+
+## 2. Landscape (current, with sources)
+
+**Standalone linters.** There is still no maintained, standalone, HA-aware config
+linter. The nearest things are: `ludeeus/action-ha-config-check` (★22, archived 2021)
+and `custom-components/config_check` (★7, archived 2021) — both call HA's own check,
+one from Actions against a live instance, one as a component. Two 2026 newcomers don't
+change the shape: `MacSiem/ha-yaml-checker` (★1, Aug 2026) is a Lovelace card inside a
+running HA; `KanadeK/hasstangle` (★0, created 2026-07-30, JS/MIT) is an offline
+static analyzer for *automation semantics* (loops/conflicts/stale entities, SARIF
+output), not a YAML/Jinja config checker — it is the closest "offline" neighbour and
+worth watching, not a competitor to the PDF's scope.
+
+**Offline check path in core.** HA core ships `hass --script check_config` with
+`-c/--config`, `-f/--files`, `-i/--info`, `-s`, `--json`, `--fail-on-warnings`
+(docs `source/_docs/tools/check_config.markdown`), and the docs propose
+`docker exec homeassistant python -m homeassistant --script check_config --config /config`
+for containers and `ha core check` for HAOS. The script is maintained (commits
+2025-11-06 → 2026-08-25; file exists on `dev`). So "runs only inside a running
+instance" is **not** accurate as stated — but the offline CLI needs the full HA
+install (today: Python ≥3.14.2, see below), it is unusable on HAOS from a laptop, and
+it does not un-mask (#169958). This is the nuance the plan carries in D3/§1.
+
+**Jinja2.** Still the engine, confirmed twice: `homeassistant` PyPI deps pin
+`Jinja2==3.1.6` (and `PyYAML==6.0.3`), and core's template environment uses
+`jinja2.StrictUndefined` with `TemplateEnvironment(ImmutableSandboxedEnvironment)`.
+`haconf` can pin the same Jinja2 version and mirror the strictness.
+
+**HA today.** Current core release: **2026.9.3** (published 2026-09-18; repo ★91,144,
+active daily). PyPI requires Python **>= 3.14.2** — HA has moved well past the PDF's
+"3.10+" floor for *its own* runtime. That does not bind haconf (we ship our own
+deps), but it strengthens the standalone case and means catalog work must track a
+fast-moving target; the analytics snapshot above is from the same live data.
+
+**Pre-commit / CI today.** No accepted community pre-commit hook exists for HA user
+YAML configs. The official `home-assistant/actions` repo (★48, active) ships
+`hassfest` — which validates **integration repositories** for custom-component
+developers, not user configuration — plus internal helpers. Core's own pre-commit
+setup is developer tooling. The PDF's "config-repo ecosystem" play (pre-commit +
+Action) remains open space.
+
+**Naming.** PyPI: `haccheck` → 404 (unregistered); `haconf` → exists (HAProxy
+health-check proxying service, v0.7.0), and GitHub has multiple `haconf` HAProxy
+repos (e.g. `uber-archive/haconf` ★86, archived). GitHub search for `haccheck`
+returns no repository. The PDF's spelling is the collision-free one.
+*(Ruling 2026-09-25: the product name is nevertheless **haconf**; the collision and
+its publish-name consequence are recorded in `haconf-PLAN.md` §4 Q1 / name note.
+This evidence paragraph is left as recorded.)*
+
+---
+
+## 3. Appendix — artifacts and commands
+
+Raw captures on this box (read-only fetches):
+
+- `/tmp/gap_research.txt` — `pdftotext -layout` of the contract PDF (232 lines)
+- `/tmp/haccheck_contract.txt` — the extracted Product 2 section (verbatim source of
+  `haconf-PLAN.md` §1)
+- `/tmp/hc_169958.json`, `/tmp/hc_169958_comments.json` — issue + 3 comments
+- `/tmp/hc_110705.json`, `/tmp/hc_io29440.json`, `/tmp/hc_frontend26063.json`
+- `/tmp/hc_analytics.json` — analytics.home-assistant.io `data.json` (7.45 MB)
+- `/tmp/hc_check_config.py` — core `homeassistant/scripts/check_config.py` (12,632 bytes)
+- `/tmp/hc_template.py` — core template package listing + `__init__.py` evidence
+- `/tmp/hc_docs_configuration.html`, `/tmp/hc_docs_templating.html` — rendered docs
+- GitHub search captures: `/tmp/hc_search_*.json`, `/tmp/hc_yamllint.json`, etc.
+- Firecrawl working dir: `/tmp/hc_firecrawl/` (reddit/linter searches)
+
+Key commands (all read-only GETs; GitHub used the pre-existing token):
+`pdftotext -layout …`; `curl`/`requests` to `api.github.com` (issues, search,
+contents, commits), `pypi.org/pypi/{homeassistant,homeassistant-cli,haccheck,haconf,
+yamllint,Jinja2,PyYAML}/json`, `analytics.home-assistant.io/data.json`,
+`raw.githubusercontent.com` (core + docs), `community.home-assistant.io/*.json`
+(via the webfetch path — direct requests were blocked with 403 by Cloudflare), and
+`firecrawl search` for the reddit quotes.
+
+Rated honesty: the one thing this phase could not do is run a real HA instance to pin
+the exact current voluptuous messages for the two demo cases (unknown key under
+`switch`; a template entity referencing an undefined entity). Those will be pinned as
+fixtures against the catalog at I1/I2; the error *format* was verified live from a
+real user error (`Invalid config for [mqtt]: expected dictionary for dictionary value
+@ data['mqtt']` — io#29440).
+
+---
+
+*Phase deliverable: this file + `haconf-PLAN.md`, committed together. No product
+code, no product repo, no installs. Nothing in the RestVerify repo was touched.*