Fix outdated auth and intent API reference documentation to match core

[balloob]

Proposed change

Corrects the auth and intent API reference docs to match current Home Assistant Core:

• auth_auth_provider.md — async_login_flow now takes a context: AuthFlowContext | None parameter; updated the documented signature.
• auth_api.md — documented the current dedicated POST /auth/revoke endpoint for revoking a refresh token, and noted the old /auth/token action=revoke form is deprecated (kept for backwards compatibility). Removed the invalid "client_icon": null from the auth/long_lived_access_token example (the schema is vol.Optional("client_icon"): str, so null fails validation).
• intent_conversation_api.md — the response data object no longer emits a top-level targets array; IntentResponse.as_dict() puts only success and failed lists (of {name, type, id} targets) into data. Reshaped the examples/prose accordingly, and added the missing floor target type.
• intent_builtin.md — removed HassToggle from the deprecated intents list/section; it is a currently registered, supported intent.

Type of change

• Document existing features within Home Assistant
• Document new or changing features for which there is an existing pull request elsewhere
• Spelling or grammatical corrections, or rewording for improved clarity
• Editing or restructuring documentation guidelines
• Changes to the backend of this documentation
• Remove stale or deprecated documentation

Checklist

• I have read and followed the documentation guidelines.
• I have verified that my changes render correctly in the documentation.

Additional information

• This PR fixes or closes issue: fixes #
• Link to relevant existing code or pull request: auth/providers/__init__.py, components/auth/__init__.py, helpers/intent.py

🤖 Generated with Claude Code

---

Generated by Claude Code

Summary by CodeRabbit

• Documentation
  • Updated refresh-token revocation documentation to use a dedicated revocation endpoint (POST /auth/revoke), including revised form-field examples, notes about client_id being unnecessary, and behavior details (HTTP 200 with empty body) plus backward-compatibility for the deprecated flow.
  • Adjusted the AuthProvider documentation for the updated async_login_flow signature with an optional context parameter.
  • Updated intent conversation API response examples to match the new data.success/data.failed per-target structure.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 00a20902-8425-486a-a49a-a0cd8f289afb

📥 Commits

Reviewing files that changed from the base of the PR and between 124ae18 and 144f5dc.

📒 Files selected for processing (1)

• docs/intent_conversation_api.md

🚧 Files skipped from review as they are similar to previous changes (1)

• docs/intent_conversation_api.md

---

📝 Walkthrough

Walkthrough

Documentation updates revise auth revocation behavior, the documented AuthProvider.async_login_flow signature, and intent conversation response examples and field descriptions.

Changes

Documentation updates

Layer / File(s)	Summary
Auth revocation docs docs/auth_api.md	Documents POST /auth/revoke with token=..., empty-body HTTP 200 responses, deprecated action=revoke behavior on /auth/token, and removes client_icon from the long-lived access token example.
AuthProvider signature docs docs/auth_auth_provider.md	Documents async_login_flow as accepting an optional context: AuthFlowContext | None parameter.
Intent conversation response docs docs/intent_conversation_api.md	Rewrites action_done and query_answer examples and text to use data.success and data.failed target lists, and adds floor to the target ordering guidance.

Estimated code review effort: 2 (Simple) | ~10 minutes

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly summarizes the main documentation refresh for auth and intent API references.
Description check	✅ Passed	The template is mostly complete and clearly explains the doc updates, selected change type, checklist, and code links.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch claude/dev-docs-home-assistant-compare-9xinvk-api-reference

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[balloob]

let's keep it as deprecated.

[balloob]

Done — reverted that change so HassToggle stays in the deprecated intents list and section (pushed in 124ae18). The rest of the PR (auth revoke endpoint, client_icon, and the intent_conversation_api targets reshape) is unchanged.

---

Generated by Claude Code

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/intent_conversation_api.md`:
- Around line 95-114: The target-ordering section in intent_conversation_api.md
is missing floor even though the schema table already includes it, so the
target-type list is inconsistent. Update the ordered target list in the
action_done response example/docs to include floor alongside the other target
types, using the same terminology as the schema table and the surrounding
success/failed target descriptions.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: e5787d33-893b-42ff-894d-62e0e3e79b3f

📥 Commits

Reviewing files that changed from the base of the PR and between 1b7c60f and 124ae18.

📒 Files selected for processing (3)

• docs/auth_api.md
• docs/auth_auth_provider.md
• docs/intent_conversation_api.md