Promote the v2 README to README.md ahead of the first v2 beta

[maxisbey]

The repo front page still documents v1 while every release cut from main is a v2 pre-release. This makes the v2 README (README.v2.md) the root README.md ahead of the beta, and retires the machinery that kept README.md frozen at v1.

What changed

• README.md is now the v2 README (README.v2.md is deleted). The banner is rewritten as a [!CAUTION] callout that makes the status unmissable: this documents the v2 alpha/beta pre-release line, breaking changes are expected between pre-releases, do not use it in production, and v1.x (linked) is the stable line. The banner no longer hardcodes a version pin or the beta date (both went stale the moment a release was cut), drops the backwards-compatibility-shims promise in favor of the migration-guide pointer, and scopes the "installers don't pick pre-releases" claim to pip/uv, where it's actually true.
• Freeze machinery removed: the readme-v1-frozen pre-commit hook, the "Check README.md is not modified" CI step with its override-readme-freeze label gate, and the --readme flag on scripts/update_readme_snippets.py (no caller left — the script now reads README.md, full stop). tests/test_examples.py lints README.md again, and tests/docs_src/test_shape.py names the README instead of globbing for two.
• Dead config from the same family deleted rather than renamed: the ruff hook exclude: (unmatchable under types: [python]), the [tool.ruff] extend-exclude README entries (ruff never selects .md), the SKIP: env in shared.yml (neither listed hook exists in the config), and the examples/ trigger on the readme-snippets hook (the v1 README that embedded examples/ files is gone; the README now embeds only docs_src/). Verified inert: ruff format --check / ruff check are byte-identical before and after.
• pyproject.toml: readme = "README.md" — PyPI already publishes the v2 long description; this keeps it working after the rename.
• RELEASE.md: new step 1 — bump the version examples in README.md and the docs in the commit that gets tagged, since the tagged commit's README is the PyPI long description. Deliberate updates replace the frozen file.
• AGENTS.md / CONTRIBUTING.md / examples/README.md updated to match reality (the examples bullets now say what actually embeds/links what).

What deliberately did not change

• Docs publishing: deploy-docs.yml builds v1.x at / and main at /v2/ from docs/ — the README isn't an input, and the v2 docs stay under /v2/ until v2 is stable.
• examples/snippets/ stays: workspace members, imported by tests/server/mcpserver/test_integration.py, and referenced by docs/migration.md. Consolidating them into stories/ remains a follow-up — note for that PR: the test-module import has to move too.
• The v1 monolith README is gone from main but reachable in git history; the v1.x branch carries its own (slimmer) v1 README plus the restructured v1 docs, which is where the banner points.

Notes for reviewers

• The in-repo TODO markers said to do this "when v2 is released"; doing it at the beta is deliberate — from here on the front page documents the pre-release line, with the banner as the guard.
• This PR's own CI runs the edited workflow and pre-commit config (pull_request runs use the merge ref), so the freeze check cannot block it and no override-readme-freeze label is needed. Required status checks are unaffected (all-green only; the freeze check was a step, not a job).
• [!CAUTION] renders as a red alert on GitHub. PyPI's renderer doesn't support alert syntax, so future pre-release pages will show the literal [!CAUTION] line at the top of the description — accepted: the bold "do not use in production" sentence carries the warning there, and the PyPI front page stays on the latest v1.x release until v2 goes stable.
• Old deep links to blob/main/README.v2.md and to v1 README section anchors stop resolving; the banner is the redirect. Permalinks at historical SHAs keep working.
• Sequencing: merge before tagging v2.0.0b1, so the beta's PyPI page is built from this README.
• Follow-up (repo settings, not code): delete the now-unused override-readme-freeze label.

_{AI Disclaimer}

[cubic-dev-ai]

No issues found across 12 files

<sub>Tip: cubic can generate docs of your entire codebase and keep them up to date. Try it here.

Re-trigger cubic</sub>

[claude]

LGTM — docs/CI-config-only change with no runtime code touched; the README promotion and freeze-machinery removal look mechanically correct.

Extended reasoning...

Overview

This PR promotes README.v2.md to README.md, deletes the v1 monolith README from main, and removes the machinery that kept the old README frozen: the readme-v1-frozen pre-commit hook, the CI freeze-check step and its SKIP env, the --readme flag on scripts/update_readme_snippets.py, and related dead config (extend-exclude, ruff hook exclude). It also updates pyproject.toml's readme field, RELEASE.md's process steps, and the two tests that reference the README path. No SDK runtime code under src/ is touched.

Security risks

None. The change is documentation, build/CI configuration, a small simplification of a doc-tooling script, and test path updates. The removed CI step was a README freeze guard, not a security control.

Level of scrutiny

Low. Cross-checking the pieces against each other holds up: the readme-snippets pre-commit hook and CI step both run --check with no --readme argument, matching the script's new hard-coded README.md; the removed SKIP env referenced hooks that no longer exist in the config; the new README's snippet block is byte-identical to docs_src/index/tutorial001.py, so the snippet check passes; tests/test_examples.py and tests/docs_src/test_shape.py now point at README.md, which exists; and pyproject.toml already published the v2 long description, so the readme field change preserves behavior. The only non-mechanical aspect — promoting the v2 README at the beta rather than at the stable release — is an explicitly stated, easily reversible project decision documented in the PR description.

Other factors

The bug hunting system found no issues, and the affected paths are exercised by the PR's own CI (pre-commit, readme-snippets check, and the README-linting tests run against the merge ref), so any mismatch would surface there rather than at runtime.

[claude]

I didn't find any bugs — the script, test, and CI/pre-commit changes are all consistent with the README rename — but this PR sets project direction (promoting the v2 pre-release README to the repo front page and PyPI long description ahead of the in-repo "when v2 is released" TODOs, plus the release-process change), so it deserves a maintainer's sign-off rather than an automated approval.

Extended reasoning...

Overview

This PR promotes README.v2.md to README.md, deletes the v1 monolith README from main, and retires the freeze machinery around it: the readme-v1-frozen pre-commit hook, the CI "README.md is not modified" step and its label gate, the --readme flag on scripts/update_readme_snippets.py, and several inert config entries (ruff excludes, SKIP env). Tests (tests/test_examples.py, tests/docs_src/test_shape.py) are repointed at README.md, pyproject.toml updates the readme field, and RELEASE.md gains a new step about bumping version examples before tagging. No runtime library code under src/ is touched.

Security risks

None. The changes are documentation, CI/pre-commit configuration, a small refactor of a docs-tooling script, and test path updates. Removing the README freeze hook and CI step has no security impact; it only relaxes a self-imposed editorial guard.

Level of scrutiny

The mechanical correctness bar is low and the pieces hold together: the snippet hook trigger now matches README.md and docs_src/, which is what the new README embeds; the script's only caller dropped the --readme flag in the same PR; the snippet source docs_src/index/tutorial001.py exists; and the new README's Python blocks lint cleanly under the existing find_examples config. However, the substance of the PR is a project-direction decision — making the pre-release line the repo front page and the PyPI long description before v2 is stable, contrary to the in-repo TODO markers that said to do this at release — plus a release-process change. That is a maintainer judgment call, not something an automated reviewer should ratify.

Other factors

The bug-hunting system found no issues, and the PR description is thorough about what was deliberately left unchanged (docs publishing, examples/snippets/) and the known trade-offs (PyPI not rendering [!CAUTION], broken deep links to README.v2.md). There were no prior reviews or comments on the PR at the time of this review. Existing CI (readme-snippets check, docs build, pre-commit) directly exercises most of the changed configuration, which limits the risk of a silent breakage.