docs(chain): fix merge_chains documentation on genesis block replacement

[gyanranjanpanda]

Fix incorrect documentation about genesis block replacement

Fixes #2095 (part 1)

The Problem

I noticed the docs for merge_chains said that trying to replace the genesis block would always fail with a CannotConnectError. But when I looked at the tests, there's actually a test case called "fix blockhash before agreement point" that does exactly that - it replaces the genesis block and expects it to succeed!

Here's the test:

chain: local_chain![(0, hash!("im-wrong")), (1, hash!("we-agree"))],
update: chain_update![(0, hash!("fix")), (1, hash!("we-agree"))],
exp: ExpectedResult::Ok { ... } // This passes!

So the docs were misleading - genesis replacement is actually allowed as long as there's agreement at a higher block.

What I Changed

I updated the documentation to match what the code actually does:

Before: Said genesis replacement always fails
After: Explains that genesis replacement is fine when the update is consistent and has a point of agreement at a higher height

I also cleaned up the wording to make it clearer when CannotConnectError actually happens.

Testing

Ran the full test suite:

cargo test -p bdk_chain

All 58 tests pass ✅

Impact

This is just a documentation fix - no code changes, no breaking changes. Just making the docs match reality so developers aren't confused.

Note

Issue #2095 mentioned two problems. This PR fixes the first one (genesis block docs). The second issue about chain reorgs is a known limitation that's being worked on in #2091.