docs: compat report uses tsx; Step 0 parity now optional

node --experimental-strip-types broke on real configs (extensionless ABI imports); npx tsx works. The
fast RPC-free coverage check leads; the --differential parity check (RPC-dependent, slower) is optional.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: dzhelezov

MIGRATION.md

@@ -6,20 +6,18 @@
 
 ---
 
-## Step 0 — Prove it (compatibility + parity, no production change)
+## Step 0 — Check compatibility (optional)
 
-Run the compatibility report against your config, pointing `PORTAL_BASE` at the portal you'll actually use (dataset availability is per-portal):
+A read-only pre-flight, in seconds and with no RPC: does the target portal serve your chains and source types? It changes nothing. Point `PORTAL_BASE` at the portal you'll actually use (dataset availability is per-portal):
 
 ```bash
 cd <your-ponder-project>
-PORTAL_API_KEY=<key> PORTAL_BASE=<portal> \
-  node <path>/harness/compat/report.ts ./ponder.config.ts --differential <your-rpc-url>
+PORTAL_BASE=<portal> npx tsx <path>/harness/compat/report.ts ./ponder.config.ts
 ```
 
-- **Coverage** — per source: is the type supported, does the target portal serve that chain's dataset, and does the network have the needed capability (traces/state-diffs, with block-range caveats). Output is a per-source `READY` / `NEEDS_*` verdict; for event + factory indexers (Uniswap, Euler, …) it's `READY NOW`.
-- **Parity** (`--differential`) — fetches the same `eth_getLogs` from Portal and your RPC and confirms they're byte-identical.
+It prints a per-source `READY` / `NEEDS_*` verdict — for event and factory indexers (Uniswap, Euler, …) it's `READY NOW`. Coverage checks whether the source type is supported, whether the portal serves that chain's dataset, and whether the network has the needed capability (traces / state-diffs, with block-range caveats).
 
-The report proves parity on *your* indexer before you change anything in production.
+**Optional — prove byte-parity.** Add `--differential <your-rpc-url>` to fetch the same `eth_getLogs` from the Portal and your RPC and confirm they're byte-identical. This one calls your RPC, so it is slower and depends on the RPC being responsive — run it when you want the proof, or skip it and go straight to the backfill.
 
 ---
 

README.md

@@ -66,7 +66,7 @@ At scale, one app indexing a real protocol (Euler V2) across all **15 chains** i
 All of Ponder's source types are supported — logs, factories, transactions, receipts, traces, block intervals, accounts; `readContract` uses your RPC. The Portal serves [130+ EVM networks](https://docs.sqd.dev/en/data/all-networks); per-network capabilities and per-portal availability vary. Check an indexer before migrating:
 
 ```bash
-node --experimental-strip-types harness/compat/report.ts ./ponder.config.ts   # → READY / NEEDS_TRACES / NO_DATASET per source
+npx tsx harness/compat/report.ts ./ponder.config.ts   # → READY / NEEDS_TRACES / NO_DATASET per source
 ```
 
 Full adoption path — check, swap, run, validate, roll back — in [`MIGRATION.md`](MIGRATION.md).