[docs] Restructure Kibana connectors docs, add disambiguation warning (#241087)

**[summary generated by Copilot]**

This pull request restructures and improves the documentation for Kibana
connectors by grouping connector types into clearer categories,
introducing new overview pages for each category, and updating
navigation and content to enhance usability and clarity. The changes
also add new snippets for connector lists, improve permissions and
management documentation, and update image formatting for consistency.

**Documentation restructuring and improved organization:**

* The connectors documentation (`connectors-kibana.md`) is reorganized
to group connectors by category (Generative AI, Elastic Stack, Alerting
and Case Management) using dropdowns and includes, making it easier to
find relevant connectors. New overview sections for permissions,
management, and configuration are added, and image formatting is
standardized.
[[1]](diffhunk://#diff-ce0006892984c70186e82411dd2d617a291bdecc9e3f4c35d3cc6213af291a1bL11-R87)
[[2]](diffhunk://#diff-ce0006892984c70186e82411dd2d617a291bdecc9e3f4c35d3cc6213af291a1bR98-R133)
* The table of contents (`toc.yml`) is updated to reflect the new
structure, introducing dedicated overview pages for GenAI, Elastic
Stack, and Alerting/Case Management connectors, each with their own
children for connector types.

**Connector lists and category pages:**

* New snippet files are added for each connector category
(`_snippets/gen-ai-connectors-list.md`,
`_snippets/elastic-connectors-list.md`,
`_snippets/alerting-cases-connectors-list.md`), and new overview pages
are created (`gen-ai-connectors.md`, `elastic-connectors.md`,
`alerting-cases-connectors.md`) to display these lists.
[[1]](diffhunk://#diff-8be5444eacdbb675de625a32f0972c934fe9142d51c40e48ff0cb147b23663e7R1-R5)
[[2]](diffhunk://#diff-1dd85ef2cc5228782b831c36cafab66679f375bb4607b719879a708a1363b801R1-R4)
[[3]](diffhunk://#diff-c8232b74a1d11ab9cde8efd92f51d2320fa27796839916fe0fe9e498f9deb2b9R1-R23)
[[4]](diffhunk://#diff-64c154aad385d5404c07db382c056daf75cbae23a9887e7bbdd3ef23a78286d2R1-R11)
[[5]](diffhunk://#diff-7f74344d72b3c9ace3c6cfb613402b5f992305188eb8578df3bbbea4433da4a4R1-R11)
[[6]](diffhunk://#diff-224d2720a3b88e0fd7eb1ac16bbac37141f73ddf38aca55145700a20f65235f2R1-R11)

**Content and linking improvements:**

* Connector descriptions are clarified and updated, with improved links
to related features and documentation (such as linking Cases connector
to the Cases documentation and clarifying Observability AI Assistant
preview status).
[[1]](diffhunk://#diff-073cf8863097190689e5216043a4edfeb739fe954fab2a82d091e89e8e867e2dL9-R9)
[[2]](diffhunk://#diff-ca2972e28132b248d8bc6d83cc461bb3a6117e60182e7504eed54d78b556bf07R2-L12)

**Image formatting and consistency:**

* All screenshots and images in the documentation are updated to use
consistent formatting, alt text, and sizing for improved accessibility
and readability.
[[1]](diffhunk://#diff-ce0006892984c70186e82411dd2d617a291bdecc9e3f4c35d3cc6213af291a1bL11-R87)
[[2]](diffhunk://#diff-ce0006892984c70186e82411dd2d617a291bdecc9e3f4c35d3cc6213af291a1bR98-R133)

---------

Co-authored-by: Nastasha Solomon <[email protected]>

Author: leemthompo

docs/reference/connectors-kibana.md

@@ -8,92 +8,83 @@ applies_to:
 ---
 # Kibana connectors [action-types]
 
-Connectors provide a central place to store connection information for services and integrations with Elastic or third party systems.
-Actions are instantiations of a connector that are linked to rules and run as background tasks on the {{kib}} server when rule conditions are met.
-{{kib}} provides the following types of connectors:
-
-* [{{bedrock}}](/reference/connectors-kibana/bedrock-action-type.md): Send a request to {{bedrock}}.
-* [Cases](/reference/connectors-kibana/cases-action-type.md): Add alerts to cases.
-* [CrowdStrike](/reference/connectors-kibana/crowdstrike-action-type.md): Send a request to CrowdStrike.
-* [D3 Security](/reference/connectors-kibana/d3security-action-type.md): Send a request to D3 Security.
-* [{{gemini}}](/reference/connectors-kibana/gemini-action-type.md): Send a request to {{gemini}}.
-* [Elastic Managed LLM](/reference/connectors-kibana/elastic-managed-llm.md): Send a request to Elastic Managed LLM.
-* [Email](/reference/connectors-kibana/email-action-type.md): Send email from your server.
-* [{{ibm-r}}](/reference/connectors-kibana/resilient-action-type.md): Create an incident in {{ibm-r}}.
-* [Index](/reference/connectors-kibana/index-action-type.md): Index data into Elasticsearch.
-* [Jira](/reference/connectors-kibana/jira-action-type.md): Create an incident in Jira.
-* [Microsoft Defender for Endpoint](/reference/connectors-kibana/defender-action-type.md): Send requests to  Microsoft Defender-enrolled hosts.
-* [Microsoft Teams](/reference/connectors-kibana/teams-action-type.md): Send a message to a Microsoft Teams channel.
-* [Observability AI Assistant](/reference/connectors-kibana/obs-ai-assistant-action-type.md): Add AI-driven insights and custom actions to your workflow.
-* [OpenAI](/reference/connectors-kibana/openai-action-type.md): Send a request to OpenAI.
-* [{{opsgenie}}](/reference/connectors-kibana/opsgenie-action-type.md): Create or close an alert in {{opsgenie}}.
-* [{{jsm}}](/reference/connectors-kibana/jsm-action-type.md): Create or close an alert in {{jsm}}.
-* [PagerDuty](/reference/connectors-kibana/pagerduty-action-type.md): Send an event in PagerDuty.
-* [SentinelOne](/reference/connectors-kibana/sentinelone-action-type.md): Send a request to SentinelOne.
-* [ServerLog](/reference/connectors-kibana/server-log-action-type.md): Add a message to a Kibana log.
-* [{{sn-itsm}}](/reference/connectors-kibana/servicenow-action-type.md): Create an incident in {{sn}}.
-* [{{sn-sir}}](/reference/connectors-kibana/servicenow-sir-action-type.md): Create a security incident in {{sn}}.
-* [{{sn-itom}}](/reference/connectors-kibana/servicenow-itom-action-type.md): Create an event in {{sn}}.
-* [Slack](/reference/connectors-kibana/slack-action-type.md): Send a message to a Slack channel or user.
-* [{{swimlane}}](/reference/connectors-kibana/swimlane-action-type.md): Create an incident in {{swimlane}}.
-* [{{hive}}](/reference/connectors-kibana/thehive-action-type.md): Create cases and alerts in {{hive}}.
-* [Tines](/reference/connectors-kibana/tines-action-type.md): Send events to a Tines Story.
-* [Torq](/reference/connectors-kibana/torq-action-type.md): Trigger a Torq workflow.
-* [{{webhook}}](/reference/connectors-kibana/webhook-action-type.md): Send a request to a web service.
-* [{{webhook-cm}}](/reference/connectors-kibana/cases-webhook-action-type.md): Send a request to a Case Management web service.
-* [xMatters](/reference/connectors-kibana/xmatters-action-type.md): Send actionable alerts to on-call xMatters resources.
-* [{{xsoar}}](/reference/connectors-kibana/xsoar-action-type.md): Create an incident in Cortex {{xsoar}}.
+:::{important}
+These Kibana connectors are used to connect to external services for GenAI, alerting, and case management use cases.
 
-::::{note}
-Some connector types are paid commercial features, while others are free. For a comparison of the Elastic subscription levels, go to [the subscription page](https://www.elastic.co/subscriptions).
+To learn about connectors for syncing data to {{es}} for search use cases, refer to [content connectors](elasticsearch://reference/search-connectors/index.md).
+:::
 
-::::
+Connectors provide a central place to store connection information for services and integrations with Elastic or third-party systems.
 
+If you're using connectors for alerting or case management, you can [create rules](docs-content://explore-analyze/alerts-cases/alerts/create-manage-rules.md) and [add actions](docs-content://explore-analyze/alerts-cases/alerts/create-manage-rules.md#defining-rules-actions-details) that use connectors to send notifications when conditions are met.
 
+{{kib}} provides connectors for LLM providers, Elastic Stack features, and third-party alerting and case management platforms.
 
-## Managing connectors [connector-management]
+## Required permissions [_required_permissions_2]
 
-Rules use connectors to route actions to different destinations like log files, ticketing systems, and messaging tools. While each {{kib}} app can offer their own types of rules, they typically share connectors. **{{stack-manage-app}} > {{connectors-ui}}** offers a central place to view and manage all the connectors in the current space.
+Access to connectors is granted based on your privileges to alerting-enabled features. For more information, go to [Security](docs-content://explore-analyze/alerts-cases/alerts/alerting-setup.md#alerting-security).
 
-% TO DO: Use `:class: screenshot`
-![Example connector listing in the {{rules-ui}} UI](images/connector-listing.png)
+## Available connectors
 
+{{kib}} provides the following connectors, grouped by category.
 
-## Required permissions [_required_permissions_2]
+:::{dropdown} Generative AI
 
-Access to connectors is granted based on your privileges to alerting-enabled features. For more information, go to [Security](docs-content://explore-analyze/alerts-cases/alerts/alerting-setup.md#alerting-security).
+:::{include} connectors-kibana/_snippets/gen-ai-connectors-list.md
+:::
 
+:::
 
-## Connector networking configuration [_connector_networking_configuration]
+:::{dropdown} Elastic Stack
 
-Use the [action configuration settings](/reference/configuration-reference/alerting-settings.md#action-settings) to customize connector networking configurations, such as proxies, certificates, or TLS settings. You can set configurations that apply to all your connectors or use `xpack.actions.customHostSettings` to set per-host configurations.
+:::{include} connectors-kibana/_snippets/elastic-connectors-list.md
+:::
+
+:::
+
+:::{dropdown} Alerting and case management
 
+:::{include} connectors-kibana/_snippets/alerting-cases-connectors-list.md
+:::
 
-## Connector list [connectors-list]
+:::
+
+::::{note}
+Some connector types are paid commercial features, while others are free. For a comparison of the Elastic subscription levels, go to [the subscription page](https://www.elastic.co/subscriptions).
+::::
+
+
+## Find available connectors [connectors-list]
 
 In **{{stack-manage-app}} > {{connectors-ui}}**, you can find a list of the connectors in the current space. You can use the search bar to find specific connectors by name and type. The **Type** dropdown also enables you to filter to a subset of connector types.
 
-% TO DO: Use `:class: screenshot`
-![Filtering the connector list by types of connectors](images/connector-filter-by-type.png)
+:::{image} images/connector-filter-by-type.png
+:alt: Filtering the connector list by types of connectors
+:screenshot:
+:::
 
 You can delete individual connectors using the trash icon. Alternatively, select multiple connectors and delete them in bulk using the **Delete** button.
 
-% TO DO: Use `:class: screenshot`
-![Deleting connectors individually or in bulk](images/connector-delete.png)
+:::{image} images/connector-delete.png
+:alt: Deleting connectors individually or in bulk
+:screenshot:
+:::
 
 ::::{note}
 You can delete a connector even if there are still actions referencing it. When this happens the action will fail to run and errors appear in the {{kib}} logs.
 
 ::::
 
 
-
 ## Creating a new connector [creating-new-connector]
 
 New connectors can be created with the **Create connector** button, which guides you to select the type of connector and configure its properties.
 
-% TO DO: Use `:class: screenshot`
-![Connector select type](images/connector-select-type.png)
+:::{image} images/connector-select-type.png
+:alt: Connector select type
+:width: 600px
+:screenshot:
+:::
 
 After you create a connector, it is available for use any time you set up an action in the current space.
 
@@ -104,18 +95,42 @@ You can also manage connectors as resources with the [Elasticstack provider](htt
 ::::
 
 
+## Managing connectors [connector-management]
+
+Rules use connectors to route actions to different destinations like log files, ticketing systems, and messaging tools. While each {{kib}} app can offer their own types of rules, they typically share connectors. **{{stack-manage-app}} > {{connectors-ui}}** offers a central place to view and manage all the connectors in the current space.
+
+:::{image} images/connector-listing.png
+:alt: Example connector listing in the {{rules-ui}} UI
+:screenshot:
+:::
+
+
+## Preconfigured connectors
+
+If you are running Kibana on-prem, you can preconfigure a connector to have all the information it needs prior to startup by adding it to the kibana.yml file. Refer to [preconfigured connectors](/reference/connectors-kibana/pre-configured-connectors.md) for more information.
+
+
+## Connector networking configuration [_connector_networking_configuration]
+
+Use the [action configuration settings](/reference/configuration-reference/alerting-settings.md#action-settings) to customize connector networking configurations, such as proxies, certificates, or TLS settings. You can set configurations that apply to all your connectors or use `xpack.actions.customHostSettings` to set per-host configurations.
+
 
 ## Importing and exporting connectors [importing-and-exporting-connectors]
 
 To import and export connectors, use the [Saved Objects Management UI](docs-content://explore-analyze/find-and-organize/saved-objects.md).
 
-% TO DO: Use `:class: screenshot`
-![Connectors import banner](images/connectors-import-banner.png)
+:::{image} images/connectors-import-banner.png
+:alt: Connectors import banner
+:screenshot:
+:width: 400px
+:::
 
 If a connector is missing sensitive information after the import, a **Fix** button appears in **{{connectors-ui}}**.
 
-% TO DO: Use `:class: screenshot`
-![Connectors with missing secrets](images/connectors-with-missing-secrets.png)
+:::{image} images/connectors-with-missing-secrets.png
+:alt: Connectors with missing secrets
+:screenshot:
+:::
 
 
 ## Monitoring connectors [monitoring-connectors]

docs/reference/connectors-kibana/_snippets/alerting-cases-connectors-list.md

@@ -0,0 +1,24 @@
+* [Observability AI Assistant](/reference/connectors-kibana/obs-ai-assistant-action-type.md): Send alerts to the AI Assistant.
+* [{{xsoar}}](/reference/connectors-kibana/xsoar-action-type.md): Create an incident in Cortex {{xsoar}}.
+* [CrowdStrike](/reference/connectors-kibana/crowdstrike-action-type.md): Send a request to CrowdStrike.
+* [D3 Security](/reference/connectors-kibana/d3security-action-type.md): Send a request to D3 Security.
+* [Email](/reference/connectors-kibana/email-action-type.md): Send email from your server.
+* [{{ibm-r}}](/reference/connectors-kibana/resilient-action-type.md): Create an incident in {{ibm-r}}.
+* [Jira](/reference/connectors-kibana/jira-action-type.md): Create an incident in Jira.
+* [{{jsm}}](/reference/connectors-kibana/jsm-action-type.md): Create or close an alert in {{jsm}}.
+* [Microsoft Defender for Endpoint](/reference/connectors-kibana/defender-action-type.md): Send requests to Microsoft Defender-enrolled hosts.
+* [Microsoft Teams](/reference/connectors-kibana/teams-action-type.md): Send a message to a Microsoft Teams channel.
+* [{{opsgenie}}](/reference/connectors-kibana/opsgenie-action-type.md): Create or close an alert in {{opsgenie}}.
+* [PagerDuty](/reference/connectors-kibana/pagerduty-action-type.md): Send an event in PagerDuty.
+* [SentinelOne](/reference/connectors-kibana/sentinelone-action-type.md): Send a request to SentinelOne.
+* [{{sn-itsm}}](/reference/connectors-kibana/servicenow-action-type.md): Create an incident in {{sn}}.
+* [{{sn-itom}}](/reference/connectors-kibana/servicenow-itom-action-type.md): Create an event in {{sn}}.
+* [{{sn-sir}}](/reference/connectors-kibana/servicenow-sir-action-type.md): Create a security incident in {{sn}}.
+* [Slack](/reference/connectors-kibana/slack-action-type.md): Send a message to a Slack channel or user.
+* [{{swimlane}}](/reference/connectors-kibana/swimlane-action-type.md): Create an incident in {{swimlane}}.
+* [{{hive}}](/reference/connectors-kibana/thehive-action-type.md): Create cases and alerts in {{hive}}.
+* [Tines](/reference/connectors-kibana/tines-action-type.md): Send events to a Tines Story.
+* [Torq](/reference/connectors-kibana/torq-action-type.md): Trigger a Torq workflow.
+* [{{webhook}}](/reference/connectors-kibana/webhook-action-type.md): Send a request to a web service.
+* [{{webhook-cm}}](/reference/connectors-kibana/cases-webhook-action-type.md): Send a request to a Case Management web service.
+* [xMatters](/reference/connectors-kibana/xmatters-action-type.md): Send actionable alerts to on-call xMatters resources.

docs/reference/connectors-kibana/_snippets/elastic-connectors-list.md

@@ -0,0 +1,4 @@
+* [Cases](/reference/connectors-kibana/cases-action-type.md): Add alerts to [Cases](docs-content://explore-analyze/alerts-cases/cases.md).
+* [Index](/reference/connectors-kibana/index-action-type.md): Index data into Elasticsearch.
+* [Observability AI Assistant](/reference/connectors-kibana/obs-ai-assistant-action-type.md): Send alerts to the AI Assistant.
+* [ServerLog](/reference/connectors-kibana/server-log-action-type.md): Add a message to a Kibana log.

docs/reference/connectors-kibana/_snippets/gen-ai-connectors-list.md

@@ -0,0 +1,5 @@
+* [AI Connector](/reference/connectors-kibana/ai-connector.md): Connect to third-party LLM services including {{bedrock}}, Azure, {{gemini}}, OpenAI, and Elastic Inference Service.
+* [{{bedrock}}](/reference/connectors-kibana/bedrock-action-type.md): Send a request to {{bedrock}}.
+* [Elastic Managed LLM](/reference/connectors-kibana/elastic-managed-llm.md): Send a request to Elastic Managed LLM.
+* [{{gemini}}](/reference/connectors-kibana/gemini-action-type.md): Send a request to {{gemini}}.
+* [OpenAI](/reference/connectors-kibana/openai-action-type.md): Send a request to OpenAI.

docs/reference/connectors-kibana/alerting-cases-connectors.md

@@ -0,0 +1,11 @@
+---
+navigation_title: Alerting and cases
+---
+# Alerting and case management connectors
+
+Use these connectors to integrate with third-party services for alerting, incident management, and case management.
+
+## Available connectors
+
+:::{include} _snippets/alerting-cases-connectors-list.md
+:::

docs/reference/connectors-kibana/cases-action-type.md

@@ -6,7 +6,7 @@ mapped_pages:
 
 # Cases connector and action [cases-action-type]
 
-The Cases connector creates cases in {{kib}} when alerts occur.
+The Cases connector creates [Cases](docs-content://explore-analyze/alerts-cases/cases.md) in {{kib}} when alerts occur.
 
 ## Create connectors in {{kib}} [define-cases-ui]
 

docs/reference/connectors-kibana/elastic-connectors.md

@@ -0,0 +1,11 @@
+---
+navigation_title: Elastic Stack
+---
+# Elastic Stack connectors
+
+Use these connectors to perform actions within the Elastic Stack.
+
+## Available connectors
+
+:::{include} _snippets/elastic-connectors-list.md
+:::

docs/reference/connectors-kibana/gen-ai-connectors.md

@@ -0,0 +1,11 @@
+---
+navigation_title: GenAI
+---
+# Generative AI connectors
+
+Use these connectors to connect to third-party large language model (LLM) services and Elastic's own LLM offerings.
+
+## Available connectors
+
+:::{include} _snippets/gen-ai-connectors-list.md
+:::

docs/reference/connectors-kibana/obs-ai-assistant-action-type.md

@@ -1,16 +1,15 @@
 ---
+applies_to:
+  serverless: preview
+  stack: preview
 navigation_title: "Observability AI Assistant"
 mapped_pages:
   - https://www.elastic.co/guide/en/kibana/current/obs-ai-assistant-action-type.html
 ---
 
 # Observability AI Assistant connector and action [obs-ai-assistant-action-type]
 
-::::{warning}
-This functionality is in technical preview and may be changed or removed in a future release. Elastic will work to fix any issues, but features in technical preview are not subject to the support SLA of official GA features.
-::::
-
-The Observability AI Assistant connector adds AI-driven insights and custom actions to your workflow.
+The Observability AI Assistant connector sends alerts to the AI Assistant, to enable adding AI-driven insights and custom actions to your workflows.
 
 To learn how to interact with the assistant through this connector, refer to the [Observability AI Assistant](docs-content://explore-analyze/ai-assistant.md) documentation.