---
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 an add-on restart to take effect — then
      reconnect or refresh the MCP server in your AI client so it reloads the
      tool list. Restarting the add-on alone does NOT refresh a client's
      cached tool list; this applies after changing any setting here.
  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_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_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.
  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.
  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.
