[rasika-chivate]

Documents existing finalization behavior after source loss for PCSM 1.1.0. Initial sync must be complete. Users can finalize and use the target, but finalization cannot establish that all source changes reached it.

Jira: https://perconadev.atlassian.net/browse/PCSM-295

Changes and placement

• docs/install/usage.md: adds Finalize after losing the source cluster under Finalize the replication, before finalization status. Includes missing-data warning, initial-sync and progress checks, pause caveat, and links to finalization/index checks.
• docs/limitations.md: adds Finalization after source loss with a link to the procedure.
• docs/faq.md: adds Can I use the target if the source cluster goes down? beside the failure-handling answer.

Existing pages remain in navigation. New headings appear automatically in page TOCs; no new navigation section or page is needed, so mkdocs-base.yml is unchanged.

Claim-to-source map

Claim	Source
Finalize succeeds after source loss on replica sets and sharded clusters; initial sync prerequisite; writable finalized target	Adnan's testing, April 24 and writes-in-flight testing, April 28
Finalized state does not guarantee complete data; target may be stale, especially after a pause	Comments 457914 and 458575 above
Review lagTimeSeconds and lastReplicatedOpTime; placement in Usage, Limitations and FAQ; existing behavior rather than a new feature	Adnan's September 3 guidance, Rasika's placement approval
initialSync.completed, status field names, CLI/API syntax, finalization.completed, unsuccessful index reporting	Existing docs/api.md GET /status and POST /finalize; docs/install/usage.md finalization sections; docs/multiple-targets.md completion checks on main
Release scope	User confirmed 1.1.0 and main; Jira fix version is 1.1.0

No feature implementation PR is linked in the ticket. This is a documentation-only clarification based on recorded tests and SME guidance. No claims about guaranteed data loss size, timing, or freshness are made.

Validation

• git diff --check passed; complete diff reviewed.
• Standard mkdocs build passed using the existing documentation dependencies.
• Verified all new page TOC entries, warning rendering, and added internal paths and anchors.
• Existing unrelated warning remains in about-docs.md for reference/contributing.md.
• No live cluster commands were run.

[Copilot]

Warning

Copilot couldn't run its full agentic review because it didn't start before the timeout. Make sure your repository has a runner available, or add a copilot-code-review.yml file specifying one with the runs-on attribute. See the docs for more details.

Copilot review overview

Review effort: Lite
Findings: 1

Open (1)

• This relative link is likely incorrect from docs/limitations.md. It currently points to… · New

What changed in this PR

Documents existing finalization behavior when the source cluster is lost (PCSM 1.1.0), emphasizing that finalization can succeed without guaranteeing the target is fully caught up, and pointing users to prerequisite checks and a step-by-step procedure.

Changes:

• Added a limitation describing why finalization after source loss can’t guarantee complete data.
• Added a new “Finalize after losing the source cluster” procedure with warnings and specific status fields to review.
• Added an FAQ entry that links to the procedure and summarizes the risk/requirements.

File	Description
docs/​limitations.md	Adds an explicit limitation + link to the detailed procedure.
docs/​install/​usage.md	Introduces a new procedural section with warnings, prerequisites, and follow-up checks.
docs/​faq.md	Adds a user-facing Q&A summarizing the behavior and linking to the procedure.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

Copilot review overview

🟢 Approval recommended

The documentation is consistent, appropriately cautions users, and uses valid existing status fields and links.

Review effort: Balanced
Findings: None

Resolved since last review (1)

• This relative link is likely incorrect from docs/limitations.md. It currently points to…

[rasika-chivate]

Checked the actual content against all review comments, including those already marked resolved. Completed the remaining gaps in three separate commits.

Review comment	Remaining fix	Commit
4229920779	docs/faq.md, Can I use the target if the source cluster goes down?: completed the prerequisite update. PCSM must keep running, the replication state must not be failed, and PCSM cannot start or restart while the source is unavailable. The matching usage paragraph was already correct and left unchanged.	0b43024
4232176954	docs/install/usage.md, Finalize after losing the source cluster: the reviewed lastReplicatedOpTime / lagTimeSeconds guidance was already present. Corrected step 2 indentation and placed the completeness caveat within that step so the prerequisite procedure renders correctly.	c9f4c82
4232243169	docs/install/usage.md, Finalize after losing the source cluster and Unsuccessful indexes: corrected step 3 indentation and qualified the general retry description. With the source unavailable, only failed indexes can be recreated from stored specifications; incomplete and inconsistent indexes cannot be rechecked and remain reported even when finalization completes.	67ac490

Validation: MkDocs build, git diff --check, rendered TOC/macros, FAQ prerequisites, both three-step procedures, and internal links/anchors passed. Git metadata plugins were disabled for the local build. GitHub file contents match the validated content. The new diff touches only the FAQ and usage guide (6 insertions, 5 deletions).

GitHub Vale passed.

The limitations link raised by Copilot was already correct; verified its rendered destination and anchor, so docs/limitations.md remains unchanged. Existing correct review fixes, unrelated FAQ content covered in PR #89, and the existing about-docs.md missing-link warning were deliberately left alone. No review feedback remains unresolved. Review threads were already resolved and remain so. No new Copilot review was requested in this comment-fix pass.

[Copilot]

🔵 Needs a closer look

SME confirmation is needed for PCSM 1.1.0 source-unavailable startup and index-recovery claims affecting data-loss decisions, because linked testing and implementation evidence is unavailable and existing API documentation does not establish those behaviors.

No open issues 🎉

_{Review effort: Balanced}