docs: developer-first README; relocate SDK-audit commands to docs/research.md

[Reddimus]

Why

The README opened with a maintainer-facing "Upstream SDK / spec discovery" block (npm/pip commands for auditing other SDKs) — sitting between the title and the value prop, before Features or Quick Start. That's the first thing a new C++ developer saw. This restructures the README to be easy to read, install, set up, keep up to date, and use, and moves the auditing commands to where they belong.

What changed

Relocation (the core ask):

• The artifact-discovery commands move out of the README into docs/research.md → new "Reproducing the artifact audit" subsection right after "SDK Versions Analyzed" (it's a contributor/parity concern, and research.md already holds the SDK comparison + parity matrix). Commands refreshed to current parity targets (kalshi-typescript, kalshi-python-sync/async 3.16.0); dropped the stale kalshi@0.0.5 / kalshi-python==2.1.4 pins.

Developer-first reorder:

• Hero (title + badges + crisp what/why) → Features → Quick start (FetchContent pinned to v0.4.8 with tests/examples off → get API keys → minimal ~10-line first call) → Versioning & staying up to date → Usage → Architecture → Building from source / development → API Coverage → Documentation → Contributing → License → References.
• New Versioning section: SemVer + pre-1.0 caveat, CHANGELOG, release-discovery flow, how to bump the pinned GIT_TAG, and the kalshi::VERSION single-source-of-truth guard.
• Exact prerequisite install lines (apt-get / brew) for openssl/libcurl/libwebsockets; documented KALSHI_BUILD_TESTS/KALSHI_BUILD_EXAMPLES.

Bug fixes found along the way:

• Clone URL your-org → Reddimus (both the FetchContent GIT_REPOSITORY and the git clone).
• Stale "155 tests" → "160+ tests" (actual 163; drift-resistant).
• Resolved the "(Coming soon)" API-reference stub → points at docs/README.md.
• Corrected the CI note (macOS/Windows run build+test, lint is Linux-only).

Preserved + verified

• All substantive content kept — full 75-method API-coverage list (verified zero methods dropped), both REST + WebSocket usage examples, both mermaid diagrams, build-options + build-targets tables.
• markdownlint-cli2: 0 errors across all 13 files.
• Usage-example code spot-checked against the public headers in include/kalshi/ (compiles).

Authored via a 7-agent analysis → synthesis → adversarial-verification workflow; the verify pass caught the CI-description inaccuracy and confirmed the examples compile. Docs-only — no code touched.