[cb1kenobi]

⊙ Problem

Publish every restore_backup through one crash-safe protocol (harper#3920) changes what restore_backup does in 5.4. The backup-and-recovery guide still says target_database needs the server stopped and that an interrupted restore always leaves the database unloadable. Its replicated-cluster runbook would also now fail, because a restore refuses to run while the node lists peers.

The v5 reference and the 5.4 release notes have moved into harper's docs/, so this PR's reference and release-note changes now ship in harper#3920 itself. Only the Learn guide, which stays in this repo, is left here.

❓ Your call: is a runbook step that removes the node's peers the right guidance?

harper#3920 refuses a restore while system.hdb_nodes or replication.routes names a peer, even one the network has isolated. The runbook now says to remove the node's peers before restoring and add them back at re-entry. The alternative is to document an override, which the code does not have.

💡 Solution

• The restore constraints now say that target_database works online as of v5.4.0, what an interrupted restore leaves (as it was, restored, or blocked), and that a restore refuses on a node with replication peers.
• Step 2 of the in-place recovery runbook removes the node's peers before restoring, and step 6 adds them back before replication reconnects.

✅ Verification

• Every new claim was checked against harper#3920's code: the fence, startup recovery and the peer census.
• Two review rounds (Codex, Gemini and the Harper domain pass) converged on the original four-page change; their findings are fixed.
• The trimmed branch differs from main only in this page.

🤖 Generated with Claude Code

Related PRs: #788 overlaps (moved the reference and 5.4 notes this PR used to edit into harper; those edits now ship in harper#3920)
Complexity: easy

_{Review-Coverage: authored=claude; ran=gemini,codex; adjudicated=domain; blocked=cursor-composer(auth); declined=cursor-grok,muse; rounds=2; full=1 @ 8e3b081}

_{Review-Attention: skim ~2m (decisions: peer-refusal-guidance, restore-option-scope) @ 8e3b081}

[gemini-code-assist]

Code Review

This pull request updates the documentation for database backup and recovery operations to align with the v5.4.0 release. The changes cover online restores using target_database, replication peer restrictions, pre-copy verification checks, crash survival behaviors, and new parameters like accept_incompatible_backup. The review feedback recommends formatting adjustments for the <VersionBadge> component, advising against its mid-sentence usage in prose and correcting its type attribute for new features.

[github-actions]

🚀 Preview Deployment

Your preview deployment is ready!

🔗 Preview URL: https://preview.harper-documentation.harperfabric.com/pr-794

This preview will update automatically when you push new commits.

[kriszyp]

Heads-up: the v5 reference and the 5.4 release notes now live in the code repos (documentation#788, harper#3944, harper-pro#1237). reference/ and release-notes/v5-lincoln/5.4.md no longer exist on main here, so this PR's changes to them need to move. Thanks for your patience with the shuffle!

• Reference pages go to docs/reference/ at the same relative path, in HarperFast/harper (in HarperFast/harper-pro for replication/, web-application-firewall/, and the Pro sections of core pages, which are _pro-*.md partials there).
• 5.4 release notes become one fragment file per change in docs/release-notes/v5-lincoln/5.4/ of the repo the change ships in. The fragment format is in harper's docs/README.md.
• If the code change this documents is still in an open PR, the docs can go in that same PR now; no companion PR needed.
• Changes to other files here (learn/, fabric/, the v4 reference) stay in this repo.

— Claude Opus 5.5

[github-actions]

🚀 Preview Deployment

Your preview deployment is ready!

🔗 Preview URL: https://preview.harper-documentation.harperfabric.com/pr-794

This preview will update automatically when you push new commits.

[github-actions]

🧹 Preview Cleanup

The preview deployment for this PR has been removed.