Adding an EVM chain is an undocumented procedure, and each request misses a different step

Four open issues ask to add a chain - #2230 (Arc testnet), #2444 (Ethereum Hoodi), #2473 (HyperEVM mainnet) and #2493 (Somnia Shannon Testnet). Each one re-derived the procedure from scratch and each missed a different piece of it. That is not four contributors being careless; it is a procedure that exists but is not where anyone can find it, and is incomplete where it is.

**Reason.** A complete chain addition touches at minimum `lib/rpc/rpc-config.ts` (`PUBLIC_RPCS` and `CHAIN_CONFIG`, the latter load-bearing - `getRpcUrlByChainId` throws for an unknown chain id, so the seed script crashes without it), and `scripts/seed/seed-chains.ts` in three separate places: `DEFAULT_CHAINS`, `EXPLORER_CONFIG_TEMPLATES` keyed by chain id, and `chainToDefaultIdMap` keyed by name. That third one is the trap: a name missing from it drops the explorer config with a `console.warn` and the seed still exits zero.

Beyond that, and undocumented anywhere: both copies of `INDEPENDENT_TOKEN_LIST_CHAIN_IDS` (`components/overlays/wallet/chain-utils.ts` and `app/api/supported-tokens/route.ts`, kept in sync by hand), `plugins/blockscout/chains.ts` for Blockscout-backed explorers, `lib/web3/gas-strategy.ts` overrides, `lib/scan/networks.ts`, and `docs/api/chains.md` - which, if touched, drags in `specs/api-coverage.json` and a `pnpm check:api-docs` rerun or CI fails.

And the piece with no in-repo trace at all: `defaultPrimaryWss` is nullable, and `keeperhub-events/event-tracker/src/listener/workflow-mapper.ts` refuses to register any Event trigger on a chain without it, silently. A chain can be added, enabled, and quietly unable to carry an Event trigger. Nothing warns.

**Evidence that the split procedure is failing, not just undocumented.** `KeeperHub/chain-config` merged `arc-testnet` and `arc-mainnet` on 2026-09-10, and keeperhub `staging` has zero Arc references - so by that repo's own stated semantics ("this repo overrides fields on chains that already exist in that list"), those entries currently do nothing. The out-of-band half of #2230 landed first and is inert. Separately, 0G Mainnet has one seeded token and is absent from `INDEPENDENT_TOKEN_LIST_CHAIN_IDS`, which by the rationale written at `chain-utils.ts:4-8` means the wallet modal renders "Not available" for its other stablecoins. Both are the same failure: a step that is real, undocumented, and therefore skipped.

**Scope.** Documentation and one guard. `.claude/commands/add-chain.md` is a 139-line procedure that already covers most of this correctly, including `chainToDefaultIdMap` - but it is a maintainer-only slash command, `CONTRIBUTING.md` contains no occurrence of "chain" or "onboard", and there is no page under `docs/`. It is also incomplete: it omits both `INDEPENDENT_TOKEN_LIST_CHAIN_IDS` copies, the blockscout and gas-strategy touchpoints, the docs/api-coverage coupling, and the WSS consequence entirely, and it mentions Parameter Store once in passing.

Does not touch: any individual chain's addition. The four open requests stay open and are judged on their own facts - collapsing them would strand three contributors' verified work.

**Plan.** Promote `add-chain.md` into contributor-facing documentation, referenced from `CONTRIBUTING.md` and `ISSUES.md`; add the touchpoints it omits; state the keeperhub-first-then-chain-config ordering and that the chain-config half is maintainer-only, so a contributor knows where their PR ends; state the WSS requirement and what a null one costs. Then one guard with teeth: a test that fails when a `DEFAULT_CHAINS` entry has no `chainToDefaultIdMap` entry, replacing the `console.warn`. Deduplicating `INDEPENDENT_TOKEN_LIST_CHAIN_IDS` is worth doing in the same pass but is separable if it grows.

I am opening this on ourselves rather than asking any of the four contributors to carry it.

Start with .claude/commands/add-chain.md, then inspect CONTRIBUTING.md, ISSUES.md, and the named chain touchpoints in lib/rpc/rpc-config.ts and scripts/seed/seed-chains.ts. Document the complete contributor and maintainer workflow, including WSS and API-doc coupling, and add a test that rejects DEFAULT_CHAINS entries missing from chainToDefaultIdMap. Verify the relevant checks and test suite pass.

Written by the indexing model from the issue text.