[codex] Add typed method alternatives and tested docs

[Code0x58]

Summary

• Move the public typing surface into alternative.pyi while keeping alternative.py focused on runtime behavior.
• Add typed and runtime support for instance methods, classmethods, and staticmethods.
• Add pyright to the dev workflow and keep PyCharm type probes as an IDE regression check.
• Run documentation Python snippets as individual pytest-collected Sybil tests and remove duplicate examples/test_*.py files in favor of Read the Docs sections.
• Update the README to describe descriptor support, IDE typing behavior, and the known JetBrains PyNestedDecoratorsInspection false-positive.

Validation

• uv sync --dev --group=docs
• uv run --dev ruff format --check --diff .
• uv run --dev ruff check .
• uv run --dev pyrefly check .
• uv run --dev pyright typing_tests
• uv run --dev mypy .
• uv run --dev pytest --verbosity=2 --cov=alternative --cov-report=xml --cov-fail-under=100 --junit-xml=test-results.xml
• uv run --group=docs sphinx-build --fail-on-warning --keep-going --builder=html docs /tmp/alternative-docs-html
• uv run --dev stubtest alternative
• scripts/pycharm-type-probes.sh
• git diff --check

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 100.00%. Comparing base (288bc48) to head (c2b3e07).
⚠️ Report is 1 commits behind head on master.
✅ All tests successful. No failed tests found.

Additional details and impacted files

@@            Coverage Diff            @@
##            master       #18   +/-   ##
=========================================
  Coverage   100.00%   100.00%           
=========================================
  Files            1         1           
  Lines          198       244   +46     
=========================================
+ Hits           198       244   +46     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.