feat(lite-docstrings): cover ha_manage_backup and ha_report_issue

docs/beta.md

@@ -12,7 +12,7 @@ Some ha-mcp tools are gated behind feature flags and disabled by default. They c
 | `ha_write_file` | `enable_filesystem_tools` (dev add-on); or web Settings UI master + sub-toggle; or `ENABLE_BETA_FEATURES=true` + `HAMCP_ENABLE_FILESYSTEM_TOOLS=true` env vars | Write files to allowed directories. Requires `ha_mcp_tools` custom component. |
 | `ha_delete_file` | `enable_filesystem_tools` (dev add-on); or web Settings UI master + sub-toggle; or `ENABLE_BETA_FEATURES=true` + `HAMCP_ENABLE_FILESYSTEM_TOOLS=true` env vars | Delete files from allowed directories. Requires `ha_mcp_tools` custom component. |
 | `ha_manage_custom_tool` | `enable_code_mode` (dev add-on); or web Settings UI master + sub-toggle; or `ENABLE_BETA_FEATURES=true` + `ENABLE_CODE_MODE=true` env vars | Sandboxed Python "escape hatch" that lets AI assistants write, run, save, and delete custom tools when no built-in tool covers the request. Code runs in pydantic-monty (no filesystem, no network); sandbox can call the HA REST API (`api_get`/`api_post`), send WebSocket commands (`ws_send`), call registered MCP tools (`call_tool`), or delete a saved tool (`delete_saved_tool`). Saved tools persist to disk via `CODE_MODE_SAVED_TOOLS_PATH` (defaults to `/data/saved_tools.json` in the dev add-on). |
-| _(behaviour flag, no new tool)_ | `enable_lite_docstrings` (dev add-on); or web Settings UI master + sub-toggle; or `ENABLE_BETA_FEATURES=true` + `ENABLE_LITE_DOCSTRINGS=true` env vars | Replaces the docstrings on a handful of heavy ha-mcp tools (automations, scripts, scenes, helpers, dashboards, `ha_call_service`, `ha_config_set_yaml`) with shorter variants that defer schema and example detail to `ha_get_skill_guide` (or its `skill://` resource). Reduces idle catalog token usage; relies on the LLM actually calling the skill tool/resource when it needs detail. See "Known limitations" below. |
+| _(behaviour flag, no new tool)_ | `enable_lite_docstrings` (dev add-on); or web Settings UI master + sub-toggle; or `ENABLE_BETA_FEATURES=true` + `ENABLE_LITE_DOCSTRINGS=true` env vars | Replaces the docstrings on 15 heavy ha-mcp tools (`ha_config_get_automation`, `ha_config_set_automation`, `ha_config_get_script`, `ha_config_set_script`, `ha_config_get_scene`, `ha_config_set_scene`, `ha_config_list_helpers`, `ha_config_set_helper`, `ha_config_get_dashboard`, `ha_config_set_dashboard`, `ha_call_service`, `ha_config_set_yaml`, `ha_search`, `ha_manage_backup`, `ha_report_issue`) with shorter variants that defer schema and example detail to `ha_get_skill_guide` (or its `skill://` resource). Reduces idle catalog token usage; relies on the LLM actually calling the skill tool/resource when it needs detail. See "Known limitations" below. |
 | `ha_get_dashboard_screenshot` (+ `include_screenshot` on `ha_config_get_dashboard`, `return_screenshot` on `ha_config_set_dashboard`) | `enable_dashboard_screenshot` (dev add-on); or web Settings UI master + sub-toggle; or `ENABLE_BETA_FEATURES=true` + `HAMCP_ENABLE_DASHBOARD_SCREENSHOT=true` env vars | Render one or more responsive Lovelace images so the AI can see what it reads or creates. Rendering runs in a separate, opt-in engine — balloob's **Puppet** add-on (headless Chromium, Apache-2.0), which you install yourself — nothing heavy is installed unless you enable this AND install the engine. |
 
 ## How to enable
@@ -125,7 +125,21 @@ Reload the `Logger` integration (or restart HA) to apply.
 
 ### `enable_lite_docstrings`
 
-Replaces the docstrings on a handful of heavy ha-mcp tools (automations, scripts, scenes, helpers, dashboards, `ha_call_service`, `ha_config_set_yaml`) with shorter variants that defer schema and example detail to `ha_get_skill_guide` (or its `skill://` resource). This is a behaviour flag, not a new tool.
+Replaces the docstrings on 15 heavy ha-mcp tools (`ha_config_get_automation`, `ha_config_set_automation`, `ha_config_get_script`, `ha_config_set_script`, `ha_config_get_scene`, `ha_config_set_scene`, `ha_config_list_helpers`, `ha_config_set_helper`, `ha_config_get_dashboard`, `ha_config_set_dashboard`, `ha_call_service`, `ha_config_set_yaml`, `ha_search`, `ha_manage_backup`, `ha_report_issue`) with shorter variants that defer schema and example detail to `ha_get_skill_guide` (or its `skill://` resource). This is a behaviour flag, not a new tool.
+
+Both lists above are checked against `_LITE_DOCSTRINGS` by `test_documented_tool_lists_cover_every_mapped_tool`, so a tool added to the mapping without a docs update fails CI rather than drifting silently.
+
+**Where the deferred detail lives.** Each mapped tool declares its destination in `_LITE_DOCSTRING_DESTINATIONS` (`src/ha_mcp/server.py`), in one of three forms, each with a matching test:
+
+| Destination | Meaning | Enforced by |
+|---|---|---|
+| `references/<file>.md`, `SKILL.md` | A file in the bundled skill pack. The lite text carries a `ha_get_skill_guide` pointer to reach it. | `test_every_lite_destination_resolves` reads the file out of the **vendored** pack — a description cannot defer to guide content that is not shipped. |
+| `tool-response:<field>` | The guidance ships in the tool's own response. Used by `ha_report_issue`, because issue reporting is ha-mcp product meta and the skill pack's CONTRIBUTING forbids coupling skill content to specific MCP tool names. | The field must actually be returned, and the lite text must name it. |
+| `self-contained` | The entry defers nothing — the trimmed text carries everything it needs. Used by `ha_manage_backup` until the skill pack ships a backup reference. | The lite text must carry **no** `ha_get_skill_guide` pointer and name no reference file, so an entry cannot quietly start advertising content the pinned submodule does not contain. |
+
+There is no exemption list: every entry is checked against the form it declares.
+
+**`BACKUP_HINT` still applies.** `ha_manage_backup`'s lite description interpolates the same `BACKUP_HINT`-derived sentence (strong/normal/weak) that its full description does, so tuning that setting is not silently cancelled by turning lite mode on.
 
 **The trade-off.** This reduces idle tool-catalog token usage but relies on the LLM actually calling the skill tool (or reading the skill resource) when it needs detail. Some models will skip the extra tool call and produce worse output than they would have with the full docstrings in front of them.
 

homeassistant-addon-dev/translations/en.yaml

@@ -140,17 +140,23 @@ configuration:
       at runtime regardless of its value here.
   enable_lite_docstrings:
     name: Enable lite tool docstrings (beta)
-    description: 'Beta feature. Replaces the docstrings on a handful of heavy ha-mcp
-      tools (automations, scripts, scenes, helpers, dashboards, ha_call_service, ha_config_set_yaml)
-      with shorter variants that defer schema and example detail to the ha_get_skill_guide
-      tool (or its skill:// resource). WARNING: this reduces idle token usage, but
-      may degrade LLM performance — the trimmed descriptions rely on the LLM actually
-      calling the skill tool or reading the skill resource for detail, which is not
-      guaranteed (some models will skip the extra tool call and end up with less guidance
-      than they had before). Best paired with a client that supports MCP resources
-      or with enable_tool_search. Requires restart to take effect. REQUIRES the master
-      "Enable beta features" toggle above (and in the web UI) to be on — otherwise
-      this sub-flag is ignored at runtime regardless of its value here.'
+    description: 'Beta feature. Replaces the docstrings on 15 heavy ha-mcp tools (ha_config_get_automation,
+      ha_config_set_automation, ha_config_get_script, ha_config_set_script, ha_config_get_scene,
+      ha_config_set_scene, ha_config_list_helpers, ha_config_set_helper, ha_config_get_dashboard,
+      ha_config_set_dashboard, ha_call_service, ha_config_set_yaml, ha_search, ha_manage_backup,
+      ha_report_issue) with shorter variants that defer schema and example detail
+      to the ha_get_skill_guide tool (or its skill:// resource). Two exceptions: ha_report_issue
+      defers to the instructions field of its own response, and ha_manage_backup defers
+      nothing at all — its trimmed text stays self-contained until the bundled skill
+      pack ships a backup reference. Tuning the Backup-hint setting still applies
+      in lite mode. WARNING: this reduces idle token usage, but may degrade LLM performance
+      — the trimmed descriptions rely on the LLM actually calling the skill tool or
+      reading the skill resource for detail, which is not guaranteed (some models
+      will skip the extra tool call and end up with less guidance than they had before).
+      Best paired with a client that supports MCP resources or with enable_tool_search.
+      Requires restart to take effect. REQUIRES the master "Enable beta features"
+      toggle above (and in the web UI) to be on — otherwise this sub-flag is ignored
+      at runtime regardless of its value here.'
   enable_mandatory_bps:
     name: Attach best-practice skills on writes
     description: 'Master switch for the write-tool skill content delivery feature