feat(examples): fork-and-evaluate demo + v2.1.0 release (Phase 3b)

Demonstrates the State Twin pattern's multi-scenario decision-making
claim with a worked example. Builds a twin via LiveProvider against
USDC/WETH V3 mainnet, forks the twin N=50 ways under hand-specified
price scenarios, runs SimulatePriceMove against each fork, aggregates
into a distribution, applies a 70%-breach IL<-5% rule for hold-vs-
rebalance recommendation.

- python/examples/state_twin_fork_evaluate.py: canonical demo script
  (script only per D14; notebook deferred)
- --offline flag for MockProvider eth_dai_v3 fallback (CI, no-RPC,
  doc-build environments)
- 70% threshold + IL < -5% rule for the recommendation per D17 —
  illustrative not prescriptive; consumers calibrate their own
- copy.deepcopy(lp) used for forking per D15; PoolSnapshot.clone()
  not added (deepcopy was sufficient at N=50, sub-second wall clock)
- Sanity check confirms forks are independent (different scenarios
  produce different IL outputs)

Version bump 2.1.0a3 -> 2.1.0 (final). CHANGELOG collapsed from three
alpha entries into one coherent v2.1.0 entry; pre-release alphas noted
as a footnote for traceability.

This is NOT an agent. It's a Python script demonstrating the substrate
pattern. DeFiMind / LLM orchestration remain explicitly out of scope
per STATE_TWIN_COMPLETION_PLAN.md.

With this commit, State Twin Completion is functionally complete.
v2.1.0 tagged locally. PyPI push is the next-day operational task —
NOT performed by this commit.

Tests: 686 passed, 11 skipped. No regressions.

Refs: doc/state_twin_execution/STATE_TWIN_PHASE_3.md

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

DeFiPy v2.0.0 — Python SDK for Agentic DeFi

Phase 1 technical ship. Three new modules (defipy.tools, defipy.twin,
MCP server demo at python/mcp/) make DeFiPy's 22 primitives agent-ready
without coupling the library to any specific LLM framework. End-to-end
loop verified live in Claude Desktop.

See CHANGELOG.md and doc/execution/DEFIPY_V2_SHIPPED.md for details.

Release 1.2.0: add AnalyzePosition primitive, web3scout as [book] extra

- Introduce primitives/ package as the go-forward architecture for
  state-analyzing operations. First primitive AnalyzePosition decomposes
  an LP position into IL, fee income, and net PnL with a structured
  PositionAnalysis return type. 14 unit tests cover entry conditions,
  post-price-move behavior, APR annualization, and diagnosis categories.

- Move web3scout from install_requires to extras_require as [book].
  Core defipy (math, analytics, primitives) no longer depends on chain
  integration. Book readers running chapter 9 agents install via
  'pip install defipy[book]'. The /agents/ subpackage is kept for
  book-reader continuity but its imports in __init__.py are now
  wrapped in try/except so 'import defipy' works without web3scout.

- Bump protocol package floors: uniswappy >= 1.7.7, balancerpy >= 1.0.6,
  stableswappy >= 1.0.5 to match today's coordinated releases.

- Add resources/run_clean_test_suite.sh as the release gate: creates a
  fresh venv, installs the full ecosystem editably, runs each package's
  pytest suite in dependency order.

- Rewrite README install section: specify Python 3.10+, show [book]
  pattern explicitly, add concrete brew/apt commands for gmpy2 system
  libraries, fix missing 'cd defipy' in source install instructions.

- Add .claude/, .venv_ci/, .DS_Store to .gitignore.

Version bump 1.1.0 -> 1.2.0.

update to include abstract interface