---
configuration:
  backup_hint:
    name: Full-HA snapshot suggestion level (LLM-facing)
    description: |-
      Tunes the wording of the hint the LLM sees in the
      `ha_manage_backup(scope='snapshot')` tool description for when to
      suggest a full Home Assistant tarball backup before risky operations
      (e.g. mass device deletes). Affects ONLY this one LLM-facing prompt
      sentence.

      For per-edit automatic snapshots of automations / scripts / helpers /
      etc., use the separate **Enable auto-backup of edits** toggle below.
  secret_path:
    name: Secret path override
    description: |
      Optional custom HTTP path for the MCP server. Leave empty to use the auto-generated secure path.
  enable_tool_search:
    name: Enable tool search
    description: >-
      Replace the full tool catalog with search-based discovery. Reduces
      idle context from ~46K to ~5K tokens. ⚠️ Do NOT enable this if you
      use Claude in Sonnet or Opus modes — those models have their own
      built-in tool search / deferred tools, which conflicts with ours.
      To use ha-mcp's tool search with Claude, disable Claude's built-in
      tool search first; otherwise leave this off. Use this only with
      LLMs that lack native deferred tools (e.g. Claude Haiku, local
      OpenAI-compatible models) or with smaller context windows. Tools
      are found via ha_search_tools and executed via categorized proxies
      (read/write/delete). Requires restart to take effect.
  enable_tool_security_policies:
    name: Enable Tool Security Policies (advanced)
    description: >-
      Gate high-stakes tool calls (lock/alarm control, automation writes,
      etc.) behind user approval. When a guarded tool is called, the agent
      tells the user to open the Tool Security Policies tab in the web UI
      and click Approve before the call proceeds. Per-tool rules with
      optional argument conditions are configured in the Tool Security
      Policies tab. Off by default. Requires restart to take effect.
  read_only_mode:
    name: Read Only Mode
    description: >-
      Toggles all write tools off, and removes ability for tools to make
      any write or destructive calls. Mixed read/write tools (backups,
      add-ons, energy preferences, voice pipelines, and code mode when
      enabled) stay available with their write operations blocked. Same
      toggle as the web UI Tools tab. Off by default. Requires restart to
      take effect.
  enable_beta_features:
    name: Enable beta features (master)
    description: >-
      ⚠ DANGER — these tools can PERMANENTLY DAMAGE your Home Assistant
      installation. They write to your YAML config, your filesystem,
      install custom components, run arbitrary sandboxed Python, and
      edit tool docstrings the AI sees. There is no warranty and no
      support guarantee — you enable them at your OWN RISK. Take a
      Home Assistant backup before turning this on, and never enable
      in production without one. Master gate for the 5 experimental
      sub-flags below; sub-flags are ignored at runtime while this
      master is off, even when explicitly set to true. The same
      toggle is also surfaced in the web settings UI under "Beta
      features (dangerous)" — either surface reflects the other on
      restart.
  enable_yaml_config_editing:
    name: Enable YAML config editing (beta)
    description: >-
      Beta feature. Allows AI assistants to add, replace, or remove
      top-level keys in configuration.yaml and packages/*.yaml. Only
      whitelisted keys are allowed (e.g., template, sensor,
      command_line, mqtt, knx); core keys like homeassistant, http,
      and recorder are blocked. Each edit validates YAML syntax, runs
      a config check, and creates an automatic backup. Changes to
      most keys require a full HA restart to take effect. See
      docs/beta.md for known limitations. Dedicated tools
      (automations, scripts, scenes, helpers, template sensors)
      should be preferred when available. 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_yaml_edit_confirm:
    name: Require confirmation for YAML edits (diff preview)
    description: >-
      Sub-toggle of YAML config editing, ON by default (recommended).
      The first ha_config_set_yaml call returns a unified diff of
      exactly what would change on disk plus a confirm token and writes
      nothing; the edit only lands when the call is repeated with that
      token. Exists so unintended changes outside the requested edit
      are caught before they reach disk (issue #1720). Turn off only to
      save one round-trip per edit.
  enable_yaml_packages_automation:
    name: Allow automation in packages/*.yaml
    description: >-
      Sub-toggle of YAML config editing. When on, ha_config_set_yaml
      accepts yaml_path='automation' inside packages/*.yaml. When off,
      the call is rejected both client-side and server-side. The
      storage-mode tool (ha_config_set_automation) is unaffected.
      Default OFF; only takes effect when "Enable YAML config editing"
      above is also on.
  enable_yaml_packages_script:
    name: Allow script in packages/*.yaml
    description: >-
      Sub-toggle of YAML config editing. When on, ha_config_set_yaml
      accepts yaml_path='script' inside packages/*.yaml. When off, the
      call is rejected both client-side and server-side. The
      storage-mode tool (ha_config_set_script) is unaffected. Default
      OFF; only takes effect when "Enable YAML config editing" above is
      also on.
  enable_yaml_packages_scene:
    name: Allow scene in packages/*.yaml
    description: >-
      Sub-toggle of YAML config editing. When on, ha_config_set_yaml
      accepts yaml_path='scene' inside packages/*.yaml. When off, the
      call is rejected both client-side and server-side. The
      storage-mode tool (ha_config_set_scene) is unaffected. Default
      OFF; only takes effect when "Enable YAML config editing" above is
      also on.
  enable_code_mode:
    name: Enable custom tool sandbox (beta)
    description: >-
      Beta feature. Enables the ha_manage_custom_tool tool, which
      lets AI assistants create, run, save, and delete custom Python
      code in a secure sandbox when no built-in tool can handle the
      request. Code runs in an isolated interpreter with no filesystem
      or arbitrary network access. Sandbox code can hit the HA REST
      API (api_get/api_post), send WebSocket commands (ws_send), call
      existing MCP tools (call_tool), or remove a saved tool
      (delete_saved_tool). Saved tools persist to
      /data/saved_tools.json by default so they survive add-on
      restarts. See docs/beta.md for known limitations. 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_auto_backup:
    name: Enable auto-backup of edits
    description: >-
      Captures a per-entity snapshot before every wrapped write/destructive
      MCP tool call (automation, script, scene, helper, dashboard, label,
      category, group, zone, area, calendar, todo, entity, integration, and
      sibling remove/delete tools). Snapshots are saved as YAML files under
      /data/ha_mcp_backups/ (override via HAMCP_BACKUP_DIR) and listed,
      restored, or deleted via the Backups tab in the web settings UI or
      via ha_manage_backup(scope='edits', ...). Best-effort — failures log
      a WARNING but never block the underlying write. On by default;
      uncheck to opt out. Requires restart to take effect.
  auto_backup_throttle_minutes:
    name: Auto-backup throttle (minutes)
    description: >-
      Per-entity throttle window. 0 (default) captures a snapshot on every
      wrapped write. N>0 captures at most one snapshot per N minutes per
      entity. Range 0–1440.
  auto_backup_retain_per_entity:
    name: Auto-backup retention (per entity)
    description: >-
      Maximum number of snapshots kept per entity. Older snapshots beyond
      this cap are rotated out on each successful capture. Default 100,
      range 1–10000.
  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.
  enable_mandatory_bps:
    name: Attach best-practice skills on writes
    description: >-
      Master switch for the write-tool skill content delivery feature
      (issue #1182). When enabled (default), the six config write tools
      (automations, scripts, scenes, helpers, dashboards, raw YAML)
      attach the canonical Home Assistant best-practice reference files
      under `skill_content` on every successful write, plus auto-embed
      any reference sections cited by best-practice warnings. Each tool
      also exposes a per-call `MandatoryBPS` parameter the agent can
      set to false on subsequent calls once it has the content. When
      this master switch is off, NO skill_content goes out regardless
      of the per-call parameter or BP warnings. Leave on if your LLM
      benefits from inline guidance; turn off to minimise tokens when
      using an LLM that has the best-practice files indexed via skills
      or another retrieval path. Requires restart to take effect.
  enable_filesystem_tools:
    name: Enable filesystem tools (beta)
    description: >-
      Sets HAMCP_ENABLE_FILESYSTEM_TOOLS=true. Enables direct file
      read/write access to your Home Assistant filesystem. WARNING:
      This gives the MCP server sensitive direct file access to your
      system. Only enable if you trust the AI assistant with file
      operations. 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_custom_component_integration:
    name: Enable custom component integration (beta)
    description: >-
      Sets HAMCP_ENABLE_CUSTOM_COMPONENT_INTEGRATION=true. Enables the
      ha_install_mcp_tools installer tool, which can help install the
      ha_mcp_tools custom component. This setting does not control
      whether the MCP server loads or interacts with the custom
      component, and it is not required for filesystem tools to
      function. Only enable if you want to allow the AI assistant to
      use the installer tool. 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_dashboard_screenshot:
    name: Enable dashboard screenshot mode (beta)
    description: >-
      Beta feature — disabled by default. Adds the ha_get_dashboard_screenshot
      tool plus include_screenshot / return_screenshot options on the dashboard
      get/set tools, so AI assistants can see a rendered PNG of a Lovelace
      dashboard (e.g. to verify one they just created). Rendering runs in a
      separate, opt-in engine — balloob's "Puppet" add-on (headless Chromium) —
      which you install once (add balloob's add-on repository, then install
      "Puppet") and give a long-lived access token; on Docker/Container
      deployments you run that engine as a sidecar and set
      HAMCP_DASHBOARD_SCREENSHOT_ENGINE_URL.
      Nothing heavy is installed unless you both enable this and install the
      engine. 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.
  tool_search_max_results:
    name: Tool search max results
    description: >-
      Maximum number of tools returned by ha_search_tools when tool
      search is enabled. Lower values (2-3) save context tokens but
      may miss relevant tools. Range: 2-10. Requires restart.
  disabled_tools:
    name: Disabled tools (comma-separated)
    description: >-
      Tools listed here are forced off and locked in the web Settings UI
      (Tools tab) — they cannot be re-enabled there without unsetting this
      option first. A small set of mandatory tools (ha_search_entities,
      ha_get_overview, ha_get_state, ha_report_issue, ha_get_skill_guide,
      ha_manage_backup) cannot be disabled and keep running even if listed
      here. Comma-separated tool names (e.g. ha_call_event,ha_eval_template).
  pinned_tools:
    name: Pinned tools (comma-separated)
    description: >-
      Tools listed here are locked pinned — they appear at the top of the
      Tools tab and cannot be unpinned from the web Settings UI without
      unsetting this option first. Useful in combination with Tool Search.
      Comma-separated tool names.
  verify_ssl:
    name: Verify TLS certificate
    description: >-
      Verify the Home Assistant server's TLS certificate. The add-on
      connects via the Supervisor proxy, so this normally has no effect
      and should stay enabled. Disable only if you've reconfigured the
      add-on to talk to HA over a public HTTPS hostname with a self-signed
      certificate or hostname mismatch. Disabling weakens transport
      security — leave on unless you know you need it. Requires restart
      to take effect.
