Markup attribute reference

First enable element selection and prepare a scenario. This reference covers element identification and its attributes.

Identify Selectable Elements

These are considered selectable:

• elements with data-ai-context-id, data-ai-label, data-ai-kind, data-ai-action, data-ai-kb-doc-id, data-ai-kb-query, data-ai-reveals-context-id, or data-ai-reveal-action;
• standard elements button, a, input, textarea, select, label, summary;
• text and structural elements article, section, li, p, h1-h6;
• elements with the roles button, link, menuitem, tab, checkbox, combobox, radio, option, searchbox, or textbox;
• elements with aria-label or aria-labelledby.

data-ai-section by itself only describes the section. If you need to select the entire block, add data-ai-label, data-ai-kind or data-ai-context-id to it.

The selected-element label comes from the first available source: data-ai-label, aria-labelledby, an associated or nearby label, aria-label, title, placeholder, and finally visible text. Fix ordinary HTML/ARIA labeling first. Use data-ai-label when the interface label is not clear outside its page context.

For repeated rows and cards, always provide data-ai-entity-type and data-ai-entity-id as a pair. The shared data-ai-context-id describes the kind of element, such as a lead row, while the entity pair identifies one specific lead. Attributes are read from the selected element itself and are not inherited from its parent: repeat the entity pair on a separately selectable button inside a repeated card. If several visible elements use the same context key, an action without this pair is ambiguous and is not performed. Providing only one of the two attributes is also invalid.

Add the Required Attributes

All values are strings. The limits in this table match the amount of data that the widget retains in selected-element context.

Attribute	Purpose	Limit / example
data-ai-area	Stable name of a large page area.	Up to 80 characters; for example header, navigation, content, form, or modal.
data-ai-section	Semantic section within the page.	Up to 120 characters; for example catalog, checkout-payment, or profile-settings.
data-ai-label	Human-readable element name that makes sense outside the page.	Up to 180 characters.
data-ai-kind	Element type in product terminology.	Up to 80 characters; for example primary-action, form-field, or product-card.
data-ai-action	Meaning of the element's action.	Up to 120 characters; for example cart.add or checkout.pay. It does not authorize execution.
data-ai-context-id	Stable documentation link and exact action target.	Up to 120 characters; use a lowercase dot-separated key such as checkout.payment.submit.
data-ai-kb-doc-id	Direct reference to a known stable knowledge-base document ID.	Up to 80 characters. Do not use it as the primary link for re-imported MD documentation.
data-ai-kb-query	Fallback knowledge-base search phrase.	Up to 240 characters; for example how to pay for an order.
data-ai-entity-type	Type of a concrete entity in a repeated list.	Up to 80 characters; for example product, plan, or order.
data-ai-entity-id	ID of the concrete entity.	Up to 120 characters; for example a SKU or public plan ID. Always use it with data-ai-entity-type.
data-ai-reveals-context-id	Context key or key root revealed by this trigger.	One or more space-separated keys; up to 2,000 characters in total.
data-ai-reveal-action	How to reveal a hidden target.	click, hover, or focus; defaults to click.
data-ai-value	Current custom-select value or an option value used by selection actions.	For example off. Never place secrets here; this is the selection value, not its label.

For actions on the host page, the widget compares data-ai-context-id, data-ai-entity-type, and data-ai-entity-id with case and punctuation preserved: Catalog.save and catalog.save, or item-a and item_a, are different keys. Pass them unchanged to commands and documentation. A data-ai-reveals-context-id value must match the target key or its root: catalog reveals catalog.save, but not catalogue.save or Catalog.save.

data-ai-action describes the element's purpose but does not replace site-side authentication, authorization, or confirmation. data-ai-reveals-context-id and data-ai-reveal-action are only needed for custom menus and panels; the widget detects standard aria-controls, popovertarget, commandfor, and <details>/<summary> relationships itself.

For data-ai-context-id to be extracted from Markdown during knowledge-base upload, use no more than 120 characters and at least two non-empty dot-separated parts. Parts may contain Latin letters, digits, _, and -. For example, checkout.payment.submit is valid; payment, checkout..submit, and a key containing a space are not.

Do not put passwords, tokens, email, phone, personal data, or secret service IDs in attributes. Attribute values and the selected element's visible text are sent to the agent with the question.

Markup examples cover forms, cards, and custom select controls. To help the agent find instructions, link the keys to Markdown documentation.