[Alerting V2][Serverless & 9.5][M2] Edit and improve get-started docs; address issues #1419 and #1420

[nastasha-solomon]

Summary

Comprehensive edits to the experimental alerting system get-started documentation. Addresses two internal tracking issues (#1419 — implicit Elasticsearch privilege grant for the Alerts privilege, and #1420 — setup prerequisites), and applies structural, editorial, and clarity improvements across all four pages in the section.

---

Content changes

get-started.md

Updated the landing page intro and all three child page descriptions to accurately reflect the current content of each page. Updated the frontmatter description.

---

get-started/setup.md

• Added a Requirements section covering license requirements (Enterprise required for Workflows-based notifications on Stack; no restriction on Serverless), data prerequisites, connectors, and space selection.
• Moved the configure-access.md cross-reference earlier in the page (after the "Confirm the UI is accessible" step) rather than only in Next steps.
• Simplified the "Turn on the system" tab-set by removing the **Requirement:** / **Steps:** heading pattern and inlining the role requirement.
• Updated frontmatter description to reflect the page's actual scope (requirements + on/off mechanics).

---

get-started/configure-access.md

Addresses #1419:

• Quick Reference table: Split the single "Query rule and episode data in Discover" row into two rows — one for .rule-events/.alert-actions (access bundled with the Alerts privilege) and one for .kibana-event-log-* (still requires a custom role).
• Triage alerts section: Added a note that granting Alerts: All or Alerts: Read automatically includes Elasticsearch read access to .rule-events and .alert-actions, with no separate index privilege needed.
• ES index access section: Rewrote to clarify the access method per data source. .rule-events and .alert-actions access is bundled with the Alerts privilege; .kibana-event-log-* still requires a custom role. Custom-role fallback preserved for the two auto-granted streams.
• Added Next steps section with a link to the tutorial and commented-out links for notifications and rules content pending PRs [Alerting V2][Serverless & 9.5][M2] Add experimental alerting features rules pages #6523 and [Alerting V2][Serverless & 9.5][M2] Adds docs for action policies, workflows, and notifications #6525.

---

get-started/create-your-first-rule.md

Structure:

• Separated environment setup (index creation, sample data) from the rule creation workflow into a dedicated Prepare your environment section with its own stepper.
• Split the single "Create the rule" stepper step into five focused steps: Open the rule editor, Write and test the detection query, Configure the alert condition, Configure the recovery condition, and Name and save the rule.
• Moved "Confirm the rule is evaluating" and "Observe the episode lifecycle" out of the Tutorial stepper and into standalone ## sections, since they're observational steps after rule creation, not part of the creation workflow itself.

Content:

• Rewrote the page intro to be high-level and inviting, with a numbered task list that previews each section and explains its purpose.
• Added a intro paragraph to "Prepare your environment", "Create the rule", and "Observe the episode lifecycle" to orient users before the steps begin.
• Added brief explanations for the detection query (what PERCENTILE, CASE, and WHERE do) and the lifecycle query (what STATS ... BY produces), for readers new to ES|QL.
• Simplified time-phase descriptions (removed redundant minute-count approximations; standardized on clock times).
• Shortened and simplified the timestamp update note.
• Improved sandbox recovery preview explanation — framed as a preview of recovery behavior rather than a "verification step."
• Fixed step numbering bug in "Observe the episode lifecycle" (step 3 was mislabeled).

Requirements section (addresses #1420):

• Replaced the manual read index privilege on .rule-events with Alerts: Read, noting that this automatically grants Elasticsearch access with no separate index privilege needed.
• Added Discover: Read as an explicit requirement.
• Added create_index and write index privileges on checkout-service-logs.
• Reformatted requirements as a table (Task / Required privilege) for scannability.

Editorial:

• Removed all em dashes throughout.
• Replaced "via" with "using".
• Replaced bold-header prose blocks with properly structured lists and tables.

---

Out of scope

• Rules reference docs (PR [Alerting V2][Serverless & 9.5][M2] Add experimental alerting features rules pages #6523)
• Action policies and notifications docs (PR [Alerting V2][Serverless & 9.5][M2] Adds docs for action policies, workflows, and notifications #6525)
• Alerts/Discover query docs (PR [Alerting V2][Serverless & 9.5][M2] Add experimental alerting features alerts pages #6527)
• ECH-specific setup behavior for the xpack.alerting_v2.enabled flag (pending engineering confirmation; placeholder comment left in setup.md)

---

Generative AI disclosure

• Yes — Cursor + Claude

[github-actions]

Elastic Docs AI PR menu

Check the box to run an AI review for this pull request.

• Review docs changes (docs-review). Status: not started.

Powered by GitHub Agentic Workflows and docs-actions. For more information, reach out to the docs team.