chore(docs): reduce operational ambiguity

[yordis]

• Operators need unambiguous guidance for leadership handoff, reserved stream behavior, Windows service readiness, and production monitoring.
• Keeping lifecycle and alert semantics aligned with runtime behavior reduces recovery mistakes during maintenance and incidents.

[cursor]

PR Summary

Low Risk
Changes are documentation only; they do not alter server behavior or configuration defaults.

Overview
Documentation-only updates that spell out operator workflows and runtime semantics that were previously implicit or easy to misread.

Cluster adds a Resign the current leader section: Admin UI or Operations/ResignNode, async acceptance vs completed election, read-only draining behavior, targeting the current leader, and that resignation only lowers preference rather than excluding the node.

Diagnostics introduces monitoring.md (liveness/readiness, cluster role metrics, symptom-based alerts, log correlation, production validation including controlled resignation) and links it from the diagnostics index and sidebar.

Installation adds a Windows SCM warning: startup deadline vs pre-service initialization, using /-/readiness for traffic, and optional ServicesPipeTimeout tuning.

Streams expands system events and streams with $ naming, ACL defaults, a table of system-projection output streams, unresolved links after deletes, and projection-runtime read access to generated streams.

Projections clarifies that $by_correlation_id keys off JSON metadata for the configured correlation property (replacing vague wording about “events from projections”).

^{Reviewed by Cursor Bugbot for commit 06a7561. Bugbot is set up for automated code reviews on this repo. Configure here.}

[coderabbitai]

Warning

Review limit reached

@yordis, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 55 minutes

Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.
You're only billed for reviews past your plan's rate limits ($0.25/file).

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 89ab0bac-2d5f-40a2-946d-3c98101236e3

📥 Commits

Reviewing files that changed from the base of the PR and between 0e182a9 and 06a7561.

📒 Files selected for processing (2)

• docs/diagnostics/monitoring.md
• docs/installation.md

Walkthrough

Documentation updates cover leader resignation, cluster monitoring, Windows startup readiness, correlation projections, and reserved system streams.

Changes

Operational documentation

Layer / File(s)	Summary
Cluster leader resignation docs/cluster.md	Documents Admin UI and gRPC resignation, post-resignation behavior, election handling, and client retries.
Monitoring documentation and navigation docs/diagnostics/monitoring.md, docs/diagnostics/README.md, docs/sidebar.js	Adds monitoring alerts, log correlation guidance, production checks, and diagnostics navigation.
Windows startup guidance docs/installation.md	Explains service startup deadlines and readiness-based traffic gating.
Stream and projection semantics docs/projections.md, docs/streams.md	Clarifies correlation metadata and reserved system-stream behavior.

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

Poem

A rabbit hops through docs so bright,
Leader steps down and nodes unite.
Alerts watch streams through the night,
Readiness keeps the traffic right.
Reserved names guard links in flight.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title matches the docs-focused goal of clarifying operational behavior across leader handoff, monitoring, and reserved streams.
Description check	✅ Passed	The description directly matches the documented updates about leadership handoff, reserved streams, Windows readiness, and monitoring.
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 yordis/chore-complete-operational-guidance

---

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.}

[coderabbitai]

Actionable comments posted: 1

🧹 Nitpick comments (1)

docs/diagnostics/monitoring.md (1)

58-80: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Move the subscription metrics paragraph to the Persistent subscription lag section.

The paragraph explaining persistent subscription metrics is currently placed under the Resource exhaustion section. It should be moved to the Persistent subscription lag section to group related information together.

♻️ Proposed refactor

 ### Persistent subscription lag
 
 Alert on a growing difference between the last-known and checkpointed event position for a subscription. A
 growing gap means consumers are not keeping up. Also alert on parked messages and the age of the oldest parked
 message.
+
+The persistent-subscription position metrics differ by source. Stream subscriptions expose
+`eventstore_persistent_sub_last_known_event_number` and
+`eventstore_persistent_sub_checkpointed_event_number`. Subscriptions to `$all` expose the corresponding
+`eventstore_persistent_sub_last_known_event_commit_position` and
+`eventstore_persistent_sub_checkpointed_event_commit_position` metrics.
 
 ### Projection failure
 
 Alert when `eventstore_projection_status{status="Faulted"}` is `1`, when a required projection stops
 unexpectedly, or when its progress declines. A required system projection that stops advancing can leave its
 generated streams stale.
 
 ### Resource exhaustion
 
 Alert on low free disk or memory, sustained CPU pressure, growing thread-pool pending work, or long garbage
 collection pauses. Resource pressure can increase queue time, trigger timeouts, and make a node miss cluster
 heartbeats.
-
-The persistent-subscription position metrics differ by source. Stream subscriptions expose
-`eventstore_persistent_sub_last_known_event_number` and
-`eventstore_persistent_sub_checkpointed_event_number`. Subscriptions to `$all` expose the corresponding
-`eventstore_persistent_sub_last_known_event_commit_position` and
-`eventstore_persistent_sub_checkpointed_event_commit_position` metrics.

🤖 Prompt for 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.

In `@docs/diagnostics/monitoring.md` around lines 58 - 80, Move the paragraph
beginning “The persistent-subscription position metrics differ by source” from
the Resource exhaustion section into the Persistent subscription lag section,
keeping its wording and metric names unchanged.

🤖 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/installation.md`:
- Around line 100-104: Update the ServicesPipeTimeout guidance to identify
HKLM\SYSTEM\CurrentControlSet\Control\ServicesPipeTimeout as a DWORD value
measured in milliseconds, state that Windows must be restarted for changes to
take effect, and instruct users to increase it incrementally only after
investigating the underlying startup delay.

---

Nitpick comments:
In `@docs/diagnostics/monitoring.md`:
- Around line 58-80: Move the paragraph beginning “The persistent-subscription
position metrics differ by source” from the Resource exhaustion section into the
Persistent subscription lag section, keeping its wording and metric names
unchanged.

🪄 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: f8921dd3-879b-4d24-82ed-2bd3fc508a75

📥 Commits

Reviewing files that changed from the base of the PR and between d9af4ae and 0e182a9.

📒 Files selected for processing (7)

• docs/cluster.md
• docs/diagnostics/README.md
• docs/diagnostics/monitoring.md
• docs/installation.md
• docs/projections.md
• docs/sidebar.js
• docs/streams.md