fix(addon): enable ingress so the stable add-on shows the Open Web UI / Settings UI (#1486)

* fix(addon): enable ingress so the stable add-on shows the Open Web UI / Settings UI

The stable Home Assistant add-on (homeassistant-addon/) never declared
ingress, so HA rendered no "Open Web UI" button and the web Settings UI was
unreachable on stable -- even though start.py already mounts the settings
routes for the ingress proxy (#960) and #1431 wired beta access into stable's
code. Mirror the dev add-on's proven ingress block, add a regression
assertion, and document that functional addon config is not auto-synced
between the dev/stable flavors.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* test(addon): assert ingress_stream in the stable add-on config

Reviewers (Gemini + PR toolkit) noted the regression test locked ingress and
ingress_port but not ingress_stream, which the fix also added. Assert it so a
silent drop of the streaming key is caught too.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* docs(addon): document the stable web Settings UI and clarify config sync

- Add a "Tool Settings Web UI" section to the stable add-on DOCS.md (it already
  referenced the web UI / Tool Security Policies tab but never said how to open
  it); stable-adjusted from the dev flavor, dropping dev-only text-field options.
- Note in config.yaml why ingress_stream is required (streamable-HTTP transport).
- Fix AGENTS.md: changelog is synced by the "Copy changelog" step in the
  semantic-release job, not by update-addon-config (which only bumps version).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: kingpanther13 <kingpanther13@users.noreply.github.com>
Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: kingpanther13

AGENTS.md

@@ -849,6 +849,22 @@ Before adding docs to tool descriptions, test what models already know using a n
 - `repository.yaml` (root) - For HA add-on store recognition
 - `homeassistant-addon/config.yaml` - Must match `pyproject.toml` version
 
+**Two add-on flavors:** `homeassistant-addon/` (stable, slug `ha_mcp`) and
+`homeassistant-addon-dev/` (dev channel, slug `ha_mcp_dev`) are *separate*
+add-ons with *separate* `config.yaml` files.
+
+**Functional config is NOT auto-synced between them.** The release pipeline
+only syncs the *version* (the `update-addon-config` job) and the *changelog*
+(the `Copy changelog to addon directory` step in `semver-release.yml`) into
+`homeassistant-addon/`. Functional keys — `ingress`, `ports`,
+`host_network`, `options`/`schema`, etc. — must be edited **by hand** in each
+flavor. When you add a non-beta capability to the dev add-on that should also
+ship on stable (e.g. `ingress` for the web Settings UI / "Open Web UI" button),
+mirror it into `homeassistant-addon/config.yaml` **in the same PR**. Assuming
+"the release pipeline handles it" is what kept `ingress` off the stable add-on.
+Beta-only keys are the deliberate exception — see the NOTE in
+`homeassistant-addon/config.yaml` and `docs/beta.md`.
+
 **Docs**: https://developers.home-assistant.io/docs/add-ons
 
 ## API Research

homeassistant-addon/DOCS.md

@@ -321,6 +321,22 @@ Per-tool rules (including argument conditions like `args.domain in ['lock', 'ala
 
 ---
 
+## Tool Settings Web UI
+
+The add-on exposes a web-based settings page for managing which tools are available to AI assistants. Click **"Open Web UI"** on the add-on info page to access it.
+
+Features:
+- **Enable/disable individual tools** — toggle each tool on or off
+- **Pin tools** — keep tools always visible when `enable_tool_search` is on
+- **Per-group master toggle** — enable/disable all tools in a group (HACS, System, etc.) with one click
+- **Search** — filter tools by name or title
+- **Mandatory tools** — `ha_search_entities`, `ha_get_overview`, `ha_get_state`, `ha_report_issue` are always enabled and cannot be disabled
+- **Tool Security Policies tab** — when `enable_tool_security_policies` is on, approve held tool calls and manage per-tool rules here
+- **Advanced settings** — an advanced panel with a beta master toggle (plus per-feature sub-toggles) for opting into beta tools such as raw YAML editing, filesystem tools, and code mode. See [Beta Features](https://github.com/homeassistant-ai/ha-mcp/blob/master/docs/beta.md)
+- **In-UI restart** — a "Restart Add-on" button appears after saving to apply changes with one click
+
+**Important:** Tool configuration changes require an add-on restart to take effect. The UI will prompt you to restart after saving.
+
 ## Security
 
 ### Auto-Generated Secret Paths

homeassistant-addon/config.yaml

@@ -11,6 +11,17 @@ arch:
 init: false
 startup: application
 boot: manual
+# Expose the web Settings UI via Supervisor ingress (the "Open Web UI" button).
+# start.py mounts the settings routes for the ingress proxy and binds 0.0.0.0;
+# this declaration is what makes Supervisor render the button and proxy to it.
+# ingress_stream keeps the proxy streaming responses (required for the
+# streamable-HTTP MCP transport / settings UI flush behaviour).
+# Must be set here too — the release pipeline syncs only version/changelog, not
+# functional config, so ingress is NOT auto-mirrored from
+# homeassistant-addon-dev/config.yaml.
+ingress: true
+ingress_port: 9583
+ingress_stream: true
 # Enable access to Supervisor API for auto-discovery
 hassio_api: true
 # `manager` (not `default`) is required so the Supervisor token grants access

tests/addon/test_addon_structure.py

@@ -62,6 +62,23 @@ def test_config_yaml_valid(self):
         assert "ports" in config, "ports section required for HTTP transport"
         assert "9583/tcp" in config["ports"], "port 9583/tcp must be exposed"
 
+        # Verify ingress is enabled so the stable add-on exposes the web
+        # Settings UI ("Open Web UI" button). This must stay declared here —
+        # the release pipeline syncs version/changelog only, not functional
+        # config, so ingress is not auto-mirrored from the dev add-on. Locks
+        # the regression where stable shipped without the button.
+        assert config.get("ingress") is True, (
+            "ingress must be enabled so the 'Open Web UI' button / web Settings "
+            "UI is reachable on the stable add-on"
+        )
+        assert config.get("ingress_port") == 9583, (
+            "ingress_port must be 9583 (the fixed internal MCP/web port)"
+        )
+        assert config.get("ingress_stream") is True, (
+            "ingress_stream must be enabled so streamed responses flush through "
+            "the ingress proxy (streamable-HTTP MCP transport)"
+        )
+
         # Verify secret_path configuration (optional advanced override)
         assert "secret_path" not in config["options"], (
             "secret_path should be optional and omitted so Supervisor treats it as advanced"