Document copy-db's blob companion directory and restore steps

[kriszyp]

Companion to HarperFast/harper#2098 (fixes HarperFast/harper#2048).

copy-db previously left the database's file-backed blobs behind, so a copy moved to another host, or restored under a different database name, silently lost every blob. It now copies each blob root to <target>-blobs/<rootIndex>/ alongside the database file, and refuses a target — or a companion directory — that already exists rather than merging the copy into it.

Documents:

• the blob companion directory, its <rootIndex> layout, and the restore steps (including restoring under a different database name, which is where the blob roots have to be placed by hand), plus that a multi-root database needs every <rootIndex> tree restored into the slot of the same index
• that neither the target path nor its -blobs companion directory may already exist — stricter than earlier v5 releases, so a script re-copying to a fixed path has to remove both first (CLI parameter list)
• that only Blob values are file-backed (Bytes values live inside the record), and that the roots are <storage.blobPaths[n]>/<database>
• that the companion directory is written only for blob roots that exist on disk — an unmounted blobPaths volume produces a database-file-only copy without failing the command
• that copy compaction is LMDB-only: copy-db fails on a RocksDB source, while compact-on-start skips RocksDB and multi-environment databases
• that the backup compactOnStartKeepBackup retains is the pre-compaction database file only, so it is a compaction rollback rather than a point-in-time backup (LMDB get_backup has the same limitation)

For the human reviewer

• The v5.3.0 badge is an inference. Fix copy-db producing a silently corrupt, non-restorable database copy harper#2098 is still open and carries no milestone; core package.json is at 5.2.2, so the next minor is v5.3.0. If #2098 lands elsewhere, the four <VersionBadge type="changed" version="v5.3.0" /> tags and the three "As of v5.3.0" sentences need updating. This PR should not merge before #2098.
• No release-notes/v5-lincoln/5.3.md exists, so the 5.3 copy-db change has no release-note entry — the reviewers flagged this against AGENTS.md. That file covers a whole release, so it is left for the release-notes pass rather than created here.
• Two reviewer findings are core defects, not docs changes, and are left for Fix copy-db producing a silently corrupt, non-restorable database copy harper#2098: copy-db exits 0 when every blob root is missing on disk (an unmounted blobPaths volume yields a database-file-only copy that a backup script records as success), and a failed or interrupted copy leaves its partial target and -blobs directory behind for the operator to remove by hand. Both are documented here as behavior; neither is fixed here.
• reference/backups/overview.md:35 tells LMDB users to reach for get_backup or volume snapshots without mentioning that get_backup omits blobs. Not touched in this PR — same gap, different page.

Verification

• npm run build passes. The two broken anchors it reports are pre-existing and in files this PR does not touch (backups/overview, release-notes/v5-lincoln/5.1).
• npx prettier --check clean on both changed files.
• Every claim checked against Fix copy-db producing a silently corrupt, non-restorable database copy harper#2098's bin/copyDb.ts (target and companion existence guards, the populatedRoots short-circuit, the RocksDB rejection, the compact-on-start skips) and resources/blob.ts getBlobPathsForDatabaseName (roots are <storage.blobPaths[n]>/<database>), and the get_backup engine behavior against reference/backups/operations.md.

Refs HarperFast/harper#2048

Generated by Claude Opus 5.

_{Review-Coverage: authored=claude; ran=codex; blocked=gemini(no-output); declined=cursor-grok,cursor-composer,domain; rounds=5 @ 5caf515}

_{Human-Review-Need: 4 @ 5caf515}

[gemini-code-assist]

Code Review

This pull request updates the documentation for the harper copy-db command and database compaction, adding details about file-backed blobs, target path constraints, and database engine applicability (LMDB vs. RocksDB). The review feedback suggests adding <VersionBadge> elements to properly document these behavior changes on existing surfaces, following repository guidelines.

[github-actions]

🚀 Preview Deployment

Your preview deployment is ready!

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

This preview will update automatically when you push new commits.

[DavidCockerill]

Approving. No findings.

"The copy is not restorable without this directory" in bold is the sentence that matters, and it is not hedged. Anyone who took a copy-db backup before this was written could reasonably believe they hold a restorable copy and not.

The <rootIndex> explanation earns its length: preserving the source root's position is what lets a multi-root database restore each root to its original slot, and writing a README.md into the directory recording the mapping means the copy carries its own restore instructions rather than depending on someone finding this page later. Showing the restore under a different database name is also the case people actually hit.

The LMDB-only scope appears in both the CLI reference and the compaction page, so a reader arriving from either gets it.

_{— DAIvid (Claude Opus 5)}

[github-actions]

🚀 Preview Deployment

Your preview deployment is ready!

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

This preview will update automatically when you push new commits.

[Ethan-Arrowood]

@kriszyp fyi you have some ghost commits in here! Not a big deal cause I'll squash merge anyways but just calling out incase.

[Ethan-Arrowood]

I'm going to review this myself shortly, but rerequesting reviews since additional commits were pushed since the previous approvals. I thought GH was supposed to do this automatically; maybe thats buried in a setting somewhere.