document-integration-docs

name	document-integration-docs
description	Document Home Assistant integrations in the current split-page format.

Usage: /document-integration-docs <domain> [epic-or-issue]

Document the <domain> integration in the current Home Assistant split-page documentation format. Use an existing ./source/_integrations/<domain>.markdown page when present. If it does not exist, create it from the current integration documentation template.

Keep the main context small. Use sub-agents for discovery and review. Do not trust the epic, issue text, or existing docs unless Core confirms them. Treat https://raw.githubusercontent.com/home-assistant/developers.home-assistant/master/docs/documenting/integration-docs-examples.md as the canonical template for split pages. Treat https://raw.githubusercontent.com/home-assistant/developers.home-assistant/master/docs/documenting/yaml-style-guide.md as the YAML style source for all YAML examples. Do not loosely imitate it. Follow its structure closely unless Core implementation makes a specific section inapplicable.

Stage 1: inventory with a sub-agent

Launch a sub-agent to inspect what exists:

• ./source/_integrations/<domain>.markdown, if present
• If you have Home Assistant Core and Frontend checked out, inspect:
  • ../core/homeassistant/components/<domain>/conditions.yaml
  • ../core/homeassistant/components/<domain>/services.yaml
  • ../core/homeassistant/components/<domain>/triggers.yaml
  • ../core/homeassistant/components/<domain>/strings.json
  • ../frontend/src/translations/en.json
• any existing split pages for <domain> in:
  • ./source/_triggers
  • ./source/_conditions
  • ./source/_actions

The sub-agent must return only this compact inventory:

Domain: <domain>

Triggers to document:
- key: <domain>.<trigger_key>
  title: <title>
  description: <description>
  target domains: [...]
  options: [...]

Conditions to document:
- key: <domain>.<condition_key>
  title: <title>
  description: <description>
  target domains: [...]
  options: [...]

Actions to document:
- key: <domain>.<action_key>
  title: <title>
  description: <description>
  target domains: [...]
  fields: [...]

Categories not implemented:
- ...

Existing split pages:
- ...

Existing integration page:
- present: <yes/no>
- useful existing content: <short summary or none>

UI wording:
- trigger behavior labels: ...
- condition behavior labels: ...
- action-specific labels: ...
- automation example action labels to mirror: ...

Important implementation notes:
- ...

Mismatches between epic/issue text and Core:
- ...

Rules for Stage 1:

• Core is the source of truth.
• Verify categories from Core, not from the issue.
• Verify exact keys from YAML or implementation.
• Verify supported target entity domains.
• Verify behavior labels from frontend strings.
• If actions exist, capture the current UI action label forms once in Stage 1 and reuse them later instead of doing extra lookups during writing.
• Keep the output short and factual.
• If the integration page does not exist yet, say so and continue from Core and the current templates.
• Note any mismatch between existing split pages and the current developer examples template.

Stage 2: template and style extraction with a sub-agent

Launch a sub-agent to inspect:

• ./source/_integrations/_integration_docs_template.markdown
• https://raw.githubusercontent.com/home-assistant/developers.home-assistant/master/docs/documenting/integration-docs-examples.md
• https://raw.githubusercontent.com/home-assistant/developers.home-assistant/master/docs/documenting/general-style-guide.md
• https://raw.githubusercontent.com/home-assistant/developers.home-assistant/master/docs/documenting/yaml-style-guide.md
• relevant include snippets under ./source/_includes
• 2-4 existing files across integrations, triggers, conditions, and actions

The sub-agent must return only this:

Integration page requirements:
- ...
- automation examples section requirement: ...

Trigger page requirements:
- required includes in order: ...
- required heading flow: ...
- required UI wording: ...
- Good to know guidance: ...

Condition page requirements:
- required includes in order: ...
- required heading flow: ...
- required UI wording: ...
- Good to know guidance: ...

Action page requirements:
- required includes in order: ...
- required heading flow: ...
- required UI wording: ...
- Good to know guidance: ...

Common pitfalls to avoid:
- ...

Focus on include order, heading expectations, UI wording, Good to know placement, and the integration-level automation examples section. Keep it compact.

The sub-agent must explicitly call out mandatory split-page sections and include order from the developer examples template, including sections that are often missing in older docs.

Stage 3: write or update the docs

Using only the distilled outputs from Stage 1 and Stage 2:

1. Create or update ./source/_integrations/<domain>.markdown.
2. Create or update one split page per trigger.
3. Create or update one split page per condition.
4. Create or update one split page per action.
5. If a category is not implemented, do not create pages for it.
6. If split pages already exist, update them instead of duplicating them.

Hard requirements:

• In the integration page, if triggers, conditions, and actions all exist, use {% include integrations/triggers_conditions_actions.md %}.
• If one or more of those categories does not exist, do not use triggers_conditions_actions.md.
• Instead, include only the applicable lines below, separated by blank lines:
  • {% include integrations/triggers.md %}
  • {% include integrations/conditions.md %}
  • {% include integrations/actions.md %}
• Ensure the integration page has an ## <Integration name> automation examples section that follows the current integration template.
• Add that section even if it was missing before the migration.
• In that section, example headings must be level-3 headings prefixed with Automation:.
• The integration-page automation examples must match the documented split pages and use the same feature names and behavior.
• Do not document unsupported Core features.
• When documenting a for attribute in options or fields, document its type as string, not time.
• Do not use Markdown H1 headings.
• Keep blank lines around headings and Liquid blocks.
• Follow the Home Assistant YAML style guide for all YAML examples.
• In UI options and YAML options sections, list default values when applicable.
• Use sentence-style capitalization.
• Prefer globally understood wording.
• Avoid region-specific household terms.
• Avoid invented workflows like “Away mode” unless explicitly framed as user-created.
• If using a helper, explicitly say it must be created separately and use {% term helper %} where appropriate.
• For trigger, condition, and action pages, follow the developer examples template section-for-section unless a section is truly not applicable.
• Do not omit a template section just because the older page for this integration did not have it.
• Keep include order aligned with the developer examples template.
• Keep heading flow aligned with the developer examples template and the headings produced by includes.
• Keep UI-step and options-section structure aligned with the developer examples template.
• If deviating from the template, do so only for a Core-based reason and keep the deviation minimal.

UI wording requirements:

• Do not prefix selected UI items with the domain.
• Trigger pages must say: Select what you want to monitor. Under **By target** ...
• Condition pages must say: Select what you want to check. Under **By target** ...
• Action pages must say: Select what you want to control. Under **By target** ...
• In automation examples, do not repeat the domain in UI action names. Use the action label without the Domain: prefix.
• If the current UI label is Light: Turn on light, write Turn on light.
• If the current UI label would read awkwardly with the domain, such as Lock: Lock lock, write only the non-prefixed label.
• Use the action labels from their related strings.json in Core to make sure they match what users see in the UI.

Split-page naming rules:

• Triggers: source/_triggers/<domain>.<trigger_key>.markdown
• Conditions: source/_conditions/<domain>.<condition_key>.markdown
• Actions: source/_actions/<domain>.<action_key>.markdown

Use exact Core keys.

Each trigger, condition, and action page must have:

• a strong introductory context explaining when it is useful
• exactly two concrete automation examples for different use cases

Example rules:

• Examples must match what the page claims.

• Prefer standard Home Assistant concepts like time, sun, person/zone, notifications, locks, lights, alarm control panels, scripts, and automations.

• Do not invent unsupported modes, flows, or features.

• Do not imply a helper exists unless you explicitly say it is user-created.

• In automation examples, do not list default values such as default for or behavior values.

• In automation examples, use the correct full action labels, such as Lock lock or Turn on switch, not shortened labels like Lock or Turn on.

• For examples that use the mobile notification action, use this pattern to refer to the mobile device:

  In UI:

  - **Action**: Send a notification message
    - **Target**: My Device (`notify.my_device`)
  

  In YAML:

  actions:
    - action: notify.send_message
      target:
        entity_id: notify.my_device
      data:
        message: >
          ...
  

• If there are other **Target** items in UI lists, they should be nested with two spaces under the trigger/action/condition above them.

Stage 4: review with a sub-agent

Launch a sub-agent to review the updated files against Core, templates, includes, and developer examples.

It must return only:

Problems found:
- [severity] <file>: <issue>

Passed checks:
- <check>

Required review checks:

• integration page uses {% include integrations/triggers_conditions_actions.md %} only when triggers, conditions, and actions all exist
• if one or more categories is missing, the integration page uses only the applicable individual include lines with blank lines between them
• integration page contains the ## <Integration name> automation examples section when required by the current template
• integration-page example headings are level 3 and start with Automation:
• integration-page automation example content is consistent with the split pages
• split pages follow the current developer examples template closely
• no mandatory split-page template section was omitted without a Core-based reason
• split pages contain required includes
• include order matches the developer examples template
• heading levels align with include-generated headings
• section order matches the developer examples template
• UI wording matches current developer examples
• selected item labels do not use Domain: Label
• trigger steps use Select what you want to monitor. Under **By target** ...
• condition steps use Select what you want to check. Under **By target** ...
• action steps use Select what you want to control. Under **By target** ...
• automation examples do not use Domain: Label for action names
• automation example action names reuse the current non-prefixed UI label form already captured during Stage 1
• unavailable / unknown notes are in Good to know
• every documented feature exists in Core
• no unsupported feature was invented
• examples are realistic and globally understandable
• in YAML options, for is documented as type: string and the format is explained in the description
• UI options and YAML options sections list default values when applicable
• automation examples do not list default values such as for for or behavior
• automation examples use correct full action labels such as Lock lock or Turn on switch
• YAML examples follow the Home Assistant YAML style guide
• helper usage, if any, is explicitly framed as user-created

Stage 5: fix and re-review

If the review sub-agent reports problems:

• fix them
• run one more compact review pass
• stop only when no material issues remain

Final response

Return:

Summary:
- ...

Files updated:
- ...

Files created:
- ...

Categories intentionally not documented:
- <category>: <reason>

Mismatches found between epic/issue text and Core:
- ...

Assumptions:
- ...