Merge upstream/master into feat/settings-ui + address Patch76 review

Conflicts:
- homeassistant-addon-dev/{config.yaml,translations/en.yaml,DOCS.md,start.py}:
  combined homeassistant-ai#1030 beta flags (filesystem/yaml/custom-component) with this
  PR's new dev-only options (tool_search_max_results, disabled_tools,
  pinned_tools). New options stay dev-only per homeassistant-ai#942 channel convention.
- src/ha_mcp/server.py: combined homeassistant-ai#955's _apply_search_keyword_enrichment
  refactor with this PR's settings-visibility apply step. Order:
  tools -> enhanced -> skills -> _apply_settings_visibility ->
  _apply_search_keyword_enrichment -> _apply_tool_search.
- homeassistant-addon/start.py: kept homeassistant-ai#806 migrate_skills_as_tools_default
  + relocated supervisor-token validation; added new env var exports.

Patch76 review fixes:
- G1: Mount settings UI under MCP secret_path so Docker/standalone clients
  share the same auth-by-obscurity as the MCP endpoint. Add-on continues
  to mount at root for HA ingress proxy. Routes don't register at all
  when neither path is available (stdio mode, or HTTP without secret).
  Moved register_settings_routes out of _initialize_server into the HTTP
  entry points (_run_http_server, _run_oauth_server, addon start.py).
- G2: Wire tool_search_max_results through CategorizedSearchTransform;
  enforce 2-10 range in Pydantic Field and addon-dev schema int(2,10)?.
- G3: 400 instead of 500 when POST body is JSON but not an object.
- G4: Use SUPERVISOR_TOKEN, not /data existence, to detect add-on mode
  in _get_config_path. Matches the rest of the module.
- G5: HTML-escape interpolated tool metadata in the settings JS.
- G6: Comment explaining MANDATORY_TOOLS vs DEFAULT_PINNED_TOOLS overlap.
- G7: Add ha_install_mcp_tools stub to FEATURE_GATED_TOOLS; rewrite stub
  copy to point at docs/beta.md (covers both stable and dev paths post-homeassistant-ai#942).
- G9: Keep enable_yaml_config_editing guard with defense-in-depth comment;
  drop the discard so AND semantics apply (UI off OR toggle off -> tool off).
- G12: Restore .env.example trailing newline.

Tests cover non-dict body, garbage state values, route mounting under
secret_path, _get_config_path env-driven path, FEATURE_GATED_TOOLS
beta-system alignment, and the G9 AND-semantics regression.

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

Author: kingpanther13

.env.example

@@ -43,4 +43,4 @@ LOG_LEVEL=INFO
 
 # Optional: MCP Server Configuration
 MCP_SERVER_NAME=ha-mcp
-# MCP_SERVER_VERSION defaults to the package version (e.g. 6.7.2)
+# MCP_SERVER_VERSION defaults to the package version (e.g. 6.7.2)

.gemini/styleguide.md

@@ -71,6 +71,7 @@ All MCP tools MUST follow `ha_<verb>_<noun>` pattern:
 - `ha_set_*` — create/update operations
 - `ha_delete_*` — remove operations
 - `ha_call_*` — execute operations
+- `ha_manage_*` — multi-modal tools combining several operations behind one interface
 
 Flag MEDIUM severity if tools don't follow this pattern.
 
@@ -101,11 +102,12 @@ Flag HIGH severity if errors use plain exceptions or dict returns instead of str
 These rules apply to new or modified tool docstrings in the PR diff only -- not to pre-existing docstrings in unchanged files.
 
 **Flag MEDIUM severity when a new or modified tool docstring:**
-- Does not start with an action verb (`Returns...` should be `Get...`; valid verbs: `Get`, `List`, `Search`, `Create`, `Update`, `Delete`, `Remove`, `Execute`, `Call`)
+- Does not start with an action verb (`Returns...` should be `Get...`; valid verbs: `Get`, `List`, `Search`, `Create`, `Update`, `Delete`, `Remove`, `Execute`, `Call`, `Manage`)
 - Is missing entirely or is still a placeholder
 - References a non-existent tool (e.g., `ha_get_domain_docs` -- the correct name is `ha_get_skill_home_assistant_best_practices`)
 - Embeds a full parameter schema instead of deferring to `ha_get_skill_home_assistant_best_practices`
 - Is a workflow-entry tool but gives no hint about the next natural tool to call
+- Multi-line docstring does not follow the structure template: (1) what the tool does, (2) when NOT to use it with preferred alternatives, (3) when to use it, (4) caveats. See AGENTS.md "Tool Docstrings" for details.
 
 **Do NOT flag:**
 - Concise one-liners on straightforward tools (progressive disclosure: brief by default)

.github/workflows/dependabot-auto-merge.yml

@@ -13,7 +13,7 @@ jobs:
     steps:
       - name: Fetch Dependabot metadata
         id: metadata
-        uses: dependabot/fetch-metadata@v2
+        uses: dependabot/fetch-metadata@v3
         with:
           github-token: "${{ secrets.GITHUB_TOKEN }}"
 

.github/workflows/deploy.yml

@@ -29,7 +29,7 @@ jobs:
       - name: Setup Node
         uses: actions/setup-node@v6
         with:
-          node-version: "20"
+          node-version: "22"
           cache: npm
           cache-dependency-path: site/package-lock.json
 
@@ -43,7 +43,7 @@ jobs:
         run: npm run build
 
       - name: Upload artifact
-        uses: actions/upload-pages-artifact@v4
+        uses: actions/upload-pages-artifact@v5
         with:
           path: ./site/dist
 

.github/workflows/gemini-triage.yml

@@ -30,7 +30,7 @@ jobs:
     steps:
       - name: Check if workflow should run
         id: check
-        uses: actions/github-script@v8
+        uses: actions/github-script@v9
         with:
           script: |
             let issue;
@@ -134,7 +134,7 @@ jobs:
 
       - name: Get issue number
         id: issue_number
-        uses: actions/github-script@v8
+        uses: actions/github-script@v9
         with:
           script: |
             const issueNumber = context.payload.inputs?.issue_number || context.issue.number;
@@ -143,7 +143,7 @@ jobs:
 
       - name: Post initial "working" comment
         id: initial_comment
-        uses: actions/github-script@v8
+        uses: actions/github-script@v9
         with:
           script: |
             const issueNumber = ${{ steps.issue_number.outputs.number }};
@@ -158,7 +158,7 @@ jobs:
 
       - name: Fetch full issue thread
         id: issue_data
-        uses: actions/github-script@v8
+        uses: actions/github-script@v9
         with:
           script: |
             const issueNumber = ${{ steps.issue_number.outputs.number }};
@@ -207,7 +207,7 @@ jobs:
       - name: Build completeness check prompt
         id: build_prompt
         if: needs.should_run.outputs.skip_preanalysis != 'true'
-        uses: actions/github-script@v8
+        uses: actions/github-script@v9
         env:
           ISSUE_TYPE: ${{ steps.issue_data.outputs.issue_type }}
           ISSUE_TITLE: ${{ steps.issue_data.outputs.issue_title }}
@@ -533,7 +533,7 @@ jobs:
 
       - name: Update comment and labels
         if: always() && steps.initial_comment.outputs.comment_id
-        uses: actions/github-script@v8
+        uses: actions/github-script@v9
         env:
           EVALUATE_RESULT: ${{ steps.evaluate.outputs.summary }}
           EVALUATE_ERROR: ${{ steps.evaluate.outputs.error }}

.github/workflows/release-publish.yml

@@ -21,22 +21,100 @@ jobs:
     if: ${{ github.event_name == 'workflow_dispatch' || github.event.workflow_run.conclusion == 'success' }}
     outputs:
       version: ${{ steps.version.outputs.version }}
+      release_tag: ${{ steps.version.outputs.release_tag }}
+      should_publish: ${{ steps.version.outputs.should_publish }}
     steps:
       - uses: actions/checkout@v6
         with:
           ref: master
           fetch-depth: 0
 
-      - name: Extract version from pyproject.toml
+      # Guard against the workflow_run trigger firing on odd-week SemVer Release
+      # runs that were correctly gated out. A SemVer Release whose biweekly-gate
+      # / check-changes / semantic-release jobs all skipped still ends with
+      # conclusion=success (skipped != failed), which would otherwise republish
+      # the existing stable version from master HEAD with whatever post-tag
+      # commits have accumulated — same :stable / :latest label, different bits.
+      # Publish only when master HEAD is at the latest stable tag's commit.
+      - name: Verify master is at the latest stable tag
         id: version
         run: |
-          VERSION=$(grep '^version = ' pyproject.toml | sed 's/version = "\(.*\)"/\1/')
-          echo "version=$VERSION" >> $GITHUB_OUTPUT
-          echo "Release version: $VERSION"
+          set -euo pipefail
+
+          # Resolve the latest stable tag. A real failure (corrupt repo, shallow
+          # clone missing tags, etc.) should fail loudly — only exit-code 128
+          # from `git describe` means "no matching tags exist in history" and is
+          # benign for a fresh repo with no stable releases yet.
+          set +e
+          LATEST_TAG=$(git describe --tags --abbrev=0 --match 'v[0-9]*' --exclude '*dev*' 2>&1)
+          DESCRIBE_RC=$?
+          set -e
+          if [ "$DESCRIBE_RC" -eq 128 ]; then
+            echo "::warning::No stable tag found; skipping Release Publish."
+            echo "should_publish=false" >> "$GITHUB_OUTPUT"
+            echo "version=" >> "$GITHUB_OUTPUT"
+            echo "release_tag=" >> "$GITHUB_OUTPUT"
+            echo "## Release Publish skipped" >> "$GITHUB_STEP_SUMMARY"
+            echo "No stable tag found in repository." >> "$GITHUB_STEP_SUMMARY"
+            exit 0
+          elif [ "$DESCRIBE_RC" -ne 0 ]; then
+            echo "::error::git describe failed (rc=$DESCRIBE_RC): $LATEST_TAG"
+            exit "$DESCRIBE_RC"
+          fi
+          echo "release_tag=$LATEST_TAG" >> "$GITHUB_OUTPUT"
+          echo "Latest stable tag: $LATEST_TAG"
+
+          # Read the version from pyproject.toml AT THE TAG, not master HEAD, so
+          # we publish what was tagged even if master has advanced. Prevents the
+          # "workflow_dispatch bumped pyproject ahead of tag" corner case.
+          VERSION=$(git show "$LATEST_TAG:pyproject.toml" \
+            | grep '^version = ' | sed 's/version = "\(.*\)"/\1/')
+          if [ -z "$VERSION" ]; then
+            echo "::error::Could not parse version from $LATEST_TAG:pyproject.toml"
+            exit 1
+          fi
+          echo "version=$VERSION" >> "$GITHUB_OUTPUT"
+          echo "Tagged pyproject version: $VERSION"
+
+          TAG_SHA=$(git rev-list -n 1 "$LATEST_TAG")
+          HEAD_SHA=$(git rev-parse HEAD)
+
+          # Normal release weeks: semver-release tags the release commit, then
+          # pushes follow-up housekeeping commits to master (changelog sync,
+          # addon version bump — all `[skip ci]`). HEAD != tag in that case,
+          # but the release IS current. Mirror semver-release.yml's check-changes
+          # logic: block only if there are releasable (feat/fix/perf) commits
+          # on master since the tag that would have produced a new version.
+          RELEASABLE=$(git log "$LATEST_TAG..HEAD" --oneline \
+            --grep='^feat' --grep='^fix' --grep='^perf' || true)
+
+          if [ -n "$RELEASABLE" ]; then
+            if [ "${{ github.event_name }}" = "workflow_dispatch" ]; then
+              echo "::notice::Manual dispatch: unreleased feat/fix/perf commits exist on master since $LATEST_TAG. Forcing republish of $LATEST_TAG from the tag ref (master HEAD $HEAD_SHA is being ignored)."
+              echo "## Release Publish — forced republish" >> "$GITHUB_STEP_SUMMARY"
+              echo "Building \`$LATEST_TAG\` ($TAG_SHA); unreleased commits on master were ignored." >> "$GITHUB_STEP_SUMMARY"
+            else
+              echo "::notice::Unreleased feat/fix/perf commits exist on master since $LATEST_TAG; no new release to publish — skipping."
+              echo "should_publish=false" >> "$GITHUB_OUTPUT"
+              echo "## Release Publish skipped" >> "$GITHUB_STEP_SUMMARY"
+              echo "master has releasable commits since the latest stable tag \`$LATEST_TAG\` but no new tag was cut, so republishing \`$LATEST_TAG\` would be misleading." >> "$GITHUB_STEP_SUMMARY"
+              echo "This is expected on biweekly-gate odd weeks; the re-triggered \`workflow_run\` is being correctly ignored." >> "$GITHUB_STEP_SUMMARY"
+              exit 0
+            fi
+          fi
+
+          echo "should_publish=true" >> "$GITHUB_OUTPUT"
+          echo "Release version: $VERSION (tag $LATEST_TAG)"
+          echo "## Release Publish — $VERSION" >> "$GITHUB_STEP_SUMMARY"
+          echo "Building from tag \`$LATEST_TAG\` ($TAG_SHA)." >> "$GITHUB_STEP_SUMMARY"
+          if [ "$TAG_SHA" != "$HEAD_SHA" ]; then
+            echo "(master HEAD is $HEAD_SHA — post-tag housekeeping commits only, no releasable changes.)" >> "$GITHUB_STEP_SUMMARY"
+          fi
 
   publish_pypi:
     name: Publish PyPI package
     needs: prepare
+    if: ${{ needs.prepare.outputs.should_publish == 'true' }}
     runs-on: ubuntu-latest
     environment:
       name: pypi
@@ -49,7 +127,7 @@ jobs:
     steps:
       - uses: actions/checkout@v6
         with:
-          ref: master
+          ref: ${{ needs.prepare.outputs.release_tag }}
           fetch-depth: 0
 
       - name: Install uv
@@ -67,6 +145,7 @@ jobs:
   publish_docker:
     name: Publish Docker image
     needs: prepare
+    if: ${{ needs.prepare.outputs.should_publish == 'true' }}
     runs-on: ubuntu-latest
     permissions:
       contents: read
@@ -76,7 +155,7 @@ jobs:
     steps:
       - uses: actions/checkout@v6
         with:
-          ref: master
+          ref: ${{ needs.prepare.outputs.release_tag }}
           fetch-depth: 0
 
       - name: Set up Docker Buildx
@@ -121,7 +200,7 @@ jobs:
     name: Publish MCP server manifest
     needs: [publish_pypi, publish_docker, prepare]
     runs-on: ubuntu-latest
-    if: ${{ always() }}
+    if: ${{ always() && needs.prepare.outputs.should_publish == 'true' }}
     permissions:
       contents: read
       id-token: write  # Required for MCP Registry OIDC authentication
@@ -137,7 +216,7 @@ jobs:
       - uses: actions/checkout@v6
         if: ${{ needs.publish_pypi.result == 'success' && needs.publish_docker.result == 'success' }}
         with:
-          ref: master
+          ref: ${{ needs.prepare.outputs.release_tag }}
           fetch-depth: 0
 
       - name: Install MCP Publisher CLI

.github/workflows/renovate.yml

@@ -31,7 +31,7 @@ jobs:
         uses: actions/checkout@v6
 
       - name: Self-hosted Renovate
-        uses: renovatebot/github-action@v46.1.8
+        uses: renovatebot/github-action@v46.1.11
         with:
           configurationFile: renovate.json
           token: ${{ secrets.GITHUB_TOKEN }}

AGENTS.md

@@ -134,27 +134,58 @@ gh issue list --state open --json number,title,labels --jq '.[] | select(.labels
 gh pr view <PR> --json comments --jq '.comments[] | {author: .author.login, created: .createdAt}'
 
 # Check inline review comments (specific to code lines)
-gh api repos/homeassistant-ai/ha-mcp/pulls/<PR>/comments --jq '.[] | {path: .path, line: .line, author: .author.login, created_at: .created_at}'
+gh api repos/homeassistant-ai/ha-mcp/pulls/<PR>/comments --jq '.[] | {id, path, line, author: .user.login, created_at}'
 
 # Check for unresolved review threads
 gh pr view <PR> --json reviews --jq '.reviews[] | select(.state == "COMMENTED") | .body'
 ```
 
 **Resolve threads:**
-After addressing a comment, **ALWAYS post a comment explaining the resolution, then mark the thread as resolved**:
+After addressing a comment, **ALWAYS post a comment explaining the resolution, then mark the thread as resolved**.
+
+When there are inline review comments, do **both**: reply on each inline thread *and* post a PR-level review comment summarising the changes. The inline replies document the per-thread resolution where future readers expect it; the PR-level comment gives a single summary for anyone scanning the PR timeline.
+
+**Always resolve the inline thread after replying**, unless the reply is asking the reviewer for further clarification (in which case leave the thread open so they can respond). An unresolved thread signals "still needs attention"; don't leave resolved work in that state. Unresolved threads also **block the PR from merging even after a maintainer has approved it** — the merge button stays disabled until every thread is marked resolved.
 
 ```bash
-# 1. FIRST: Post comment explaining what was done
-gh pr review <PR> --comment --body "✅ Fixed in [commit]. [Explanation]"
+# 1a. Reply on each inline thread via the /replies sub-endpoint.
+#     <comment-id> is the numeric ID from:
+#       gh api repos/homeassistant-ai/ha-mcp/pulls/<PR>/comments --jq '.[].id'
+gh api repos/homeassistant-ai/ha-mcp/pulls/<PR>/comments/<comment-id>/replies \
+  -f body="✅ Fixed in [commit]. [Explanation]"
 # OR for dismissed suggestions:
-gh pr review <PR> --comment --body "📝 Not addressing because [reason]."
+gh api repos/homeassistant-ai/ha-mcp/pulls/<PR>/comments/<comment-id>/replies \
+  -f body="📝 Not addressing because [reason]."
+
+# 1b. Also post a PR-level review comment summarising the batch of changes:
+gh pr review <PR> --comment --body "✅ Addressed review feedback in [commit]. [Summary]"
+
+# If there are no inline comments (just a general review), the PR-level
+# review comment alone is sufficient.
+
+# 2. THEN: Resolve each thread. The GraphQL input field is `threadId` — NOT
+#    `pullRequestReviewThreadId`, which GitHub rejects. The thread node ID
+#    (PRRT_...) comes from a reviewThreads query; match databaseId against
+#    the inline-comment numeric ID to pick the right one:
+gh api graphql -f query='
+query {
+  repository(owner: "homeassistant-ai", name: "ha-mcp") {
+    pullRequest(number: <PR>) {
+      reviewThreads(first: 100) {
+        nodes {
+          id isResolved path line
+          comments(first: 1) { nodes { databaseId } }
+        }
+      }
+    }
+  }
+}'
 
-# 2. THEN: Resolve the thread
 gh api graphql -f query='mutation($threadId: ID!) {
-  resolveReviewThread(input: {pullRequestReviewThreadId: $threadId}) {
+  resolveReviewThread(input: {threadId: $threadId}) {
     thread { id isResolved }
   }
-}' -f threadId=<thread_id>
+}' -f threadId=<PRRT_...>
 ```
 
 **Why comment first:**
@@ -419,6 +450,7 @@ src/ha_mcp/
 - `delete` — delete dashboards, config entries, or files (`ha_config_delete_dashboard`, `ha_delete_file`)
 - `remove` — remove registry items (`ha_remove_entity`, `ha_config_remove_area`)
 - `call` — execute (`ha_call_service`)
+- `manage` — multi-modal tools combining several operations behind one interface (`ha_manage_addon`)
 
 ### Tool Structure
 Create `tools_<domain>.py` in `src/ha_mcp/tools/`. Registry auto-discovers it.
@@ -441,7 +473,8 @@ class DomainTools:
         # Add to the docstring above only when genuinely needed:
         # RELATED TOOLS: ha_next(): why to call this after (workflow-entry tools only)
         # EXAMPLES: ha_<verb>_<noun>("realistic_value")  -- non-obvious call patterns only
-        # NOTE / WARNING: non-obvious gotcha or destructive side-effect
+        # When NOT to use: route to preferred alternatives
+        # Caveats: destructive side-effects, non-obvious gotchas
         # For complex schemas: use ha_get_skill_home_assistant_best_practices
 
 def register_<domain>_tools(mcp, client, **kwargs):
@@ -455,7 +488,7 @@ def register_<domain>_tools(mcp, client, **kwargs):
 The single-line template is the default -- extend it only where it genuinely helps.
 
 **Required for every tool:**
-- Starts with an action verb (`Get`, `List`, `Search`, `Create`, `Update`, `Delete`, `Remove`, `Execute`, `Call`)
+- Starts with an action verb (`Get`, `List`, `Search`, `Create`, `Update`, `Delete`, `Remove`, `Execute`, `Call`, `Manage`)
 - One sentence describing what the tool does (not how)
 
 **Add `RELATED TOOLS` when** the tool is a workflow entry point and the natural next step is not obvious.
@@ -464,8 +497,16 @@ Example: `ha_search_entities` hints at `ha_get_state`.
 **Add `EXAMPLES` when** the tool has multiple modes or non-obvious parameters.
 Omit when a single required parameter makes the call self-evident.
 
-**Add `NOTE` or `WARNING` when** there is a non-obvious gotcha, a destructive side-effect,
-or a behavioral quirk that causes silent failures if ignored.
+**For multi-line docstrings, follow this structure** (based on
+[Anthropic's tool design guidance](https://www.anthropic.com/engineering/writing-tools-for-agents)):
+1. What the tool does (required first sentence, action verb)
+2. When NOT to use it — name the preferred alternatives
+3. When to use it — valid use cases
+4. Caveats — consequences, post-actions, destructive side-effects
+
+Consequence statements are plain prose: "This permanently deletes the dashboard.
+A backup is created before every edit." Route safety concerns through `annotations`
+(`destructiveHint`, `idempotentHint`, `readOnlyHint`), not docstring keywords.
 
 **Defer complex schemas** instead of embedding them:
 `# For complex schemas: use ha_get_skill_home_assistant_best_practices`