Clean up chain docs + smart-contract address records — heima.json is the single source of truth

[hanwencheng]

Problem

On-chain contract addresses and deployer/wallet EOAs are duplicated across many docs and files, so they drift. The same SidecarRegistry / EntryPoint / paymaster address is hand-written in several places, and there is no enforcement that they agree.

The intended hierarchy of truth is:

• Prod contract addresses → crates/agentkeys-core/chain-profiles/heima.json — the versioned machine source of truth (.contracts[] + contract_set_version), compiled into the broker/daemon via include_str!. Mirrored to scripts/operator-workstation.env by heima-bring-up.sh / heima-deploy-paymaster.sh.
• Test contract addresses (parallel set) → scripts/operator-workstation.test.env + the TEST_* GitHub secrets.
• Wallet (EOA) addresses → the env files (*_DEPLOYER_ADDR_HEIMA, BROKER_SPONSOR_SIGNER_ADDRESS_HEIMA).
• Human prose (docs/spec/deployed-contracts.md) → ABI/cutover/version notes only; no address table (already the policy — it defers to the chain profile).

No doc should re-write a literal address that already lives in one of those sources; it should anchor to the source (link + a jq/grep resolve command) instead.

Already done (partial, in the #230 PR)

• docs/chain-setup.md §Wallets, contracts & funding map — de-addressed: contracts/wallets referenced by heima.json / env-var name, with resolve commands; the funding diagram + "which wallet do I fund" table use env-vars, no hex.
• docs/operator-runbook-wallet-rotation.md — no literal addresses; identification defers to the chain-setup map.

Remaining cleanup (this issue)

1. Sweep every chain/contract doc for literal addresses that duplicate heima.json / the env files, and replace with an anchor + resolve command. Candidates to audit: docs/arch.md §5/§6, docs/spec/deployed-contracts.md (confirm it truly carries no address table), docs/spec/heima-eth-gap.md, docs/plan/chain/*.md, docs/operator-runbook-account-auth-cutover.md, any docs/wiki/* chain page, and hardcoded.md.
2. Confirm + document the source-of-truth hierarchy in one place (likely deployed-contracts.md header, which arch.md §5 indexes) so future docs know to anchor, not copy.
3. Add a CI guard (extend scripts/check-deployed-contracts-sync.sh) that fails if a tracked doc reintroduces a literal 0x… contract address that should be an anchor (allowlist the prose registry + historical/superseded notes). Per the "fold systemic fixes into enforcement" rule — a doc-only convention without a gate will rot.
4. Reconcile the test-side records: operator-workstation.test.env is the test SoT but the TEST_* GitHub secrets are a second copy set by ci-set-github-secrets.sh; document that the script is the sync path and the env file is authoritative.

Related (separate work, not this issue)

• CI ERC-4337 parity: the test stack has no EntryPoint / P256AccountFactory / VerifyingPaymaster (its ENTRYPOINT_ADDRESS_HEIMA= keys are intentionally empty; the bundler degrades per Decouple UserOp submission from the broker into an ERC-4337 bundler #230). Bringing CI to full parity with prod (so it has ERC-4337 wallet/contract addresses too) is a deployment task tracked separately — it touches the same records this issue tidies, so do that first.

Acceptance

• No tracked doc outside the source-of-truth files contains a literal contract address that duplicates heima.json (verified by the new CI guard).
• arch.md §5 + deployed-contracts.md state the hierarchy explicitly.
• bash scripts/check-deployed-contracts-sync.sh passes and now also gates doc address-literals.