docs: add feature support matrix with verification methodology

Add a feature support matrix to README documenting LSP feature compatibility
across Pyright, Pyrefly, and ty backends. Includes emoji indicators for
support status and notes for partial support cases.

Create docs/FEATURE_VERIFICATION.md with methodology for maintaining the
table using the test suite as source of truth (xfail markers document
known limitations).

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

Author: Mazyod

README.md

@@ -64,6 +64,41 @@ The following LSPs are available out of the box:
 - [Pyrefly](https://github.com/facebook/pyrefly)
 - [ty](https://github.com/astral-sh/ty) - Astral's fast Python type checker
 
+## Feature Support Matrix
+
+### Legend
+
+| Symbol | Meaning |
+|--------|---------|
+| :white_check_mark: | Fully supported |
+| :warning: | Partial support (see notes) |
+| :x: | Not supported |
+| :grey_question: | Not tested / Not exposed in API |
+
+### Features by Backend
+
+> Last verified: basedpyright 1.36.2, Pyrefly 0.48.2, ty 0.0.12
+
+| Feature | Pyright | Pyrefly | ty | Notes |
+|---------|:-------:|:-------:|:--:|-------|
+| Diagnostics | :white_check_mark: | :white_check_mark: | :warning: | ty requires files on disk |
+| Hover | :white_check_mark: | :white_check_mark: | :white_check_mark: | ty shows type only, not variable name |
+| Completion | :white_check_mark: | :white_check_mark: | :warning: | ty requires files on disk |
+| Completion Resolution | :white_check_mark: | :x: | :white_check_mark: | Pyrefly: not yet supported |
+| Signature Help | :white_check_mark: | :white_check_mark: | :white_check_mark: | |
+| Rename | :white_check_mark: | :warning: | :warning: | Pyrefly: disabled for external files; ty: requires files on disk |
+| Semantic Tokens | :white_check_mark:\* | :white_check_mark: | :white_check_mark: | \*basedpyright recommended for extended features |
+| Go to Definition | :grey_question: | :grey_question: | :grey_question: | Not exposed in Session API |
+| Find References | :grey_question: | :grey_question: | :grey_question: | Not exposed in Session API |
+| Code Actions | :grey_question: | :grey_question: | :grey_question: | Not exposed in Session API |
+| Formatting | :grey_question: | :grey_question: | :grey_question: | Not exposed in Session API |
+
+> See [Feature Verification Guide](docs/FEATURE_VERIFICATION.md) for methodology on maintaining this table.
+
+For detailed backend limitations:
+- [Pyrefly Known Limitations](lsp_types/pyrefly/KNOWN_LIMITATIONS.md)
+- [ty Known Limitations](lsp_types/ty/KNOWN_LIMITATIONS.md)
+
 ### Pyright Example
 
 ```python

docs/FEATURE_VERIFICATION.md

@@ -0,0 +1,98 @@
+# Feature Verification Guide
+
+This document describes how to verify and update the feature support matrix in the README.
+
+## Verification Process
+
+### Step 1: Run the Test Suite
+
+```bash
+uv run pytest tests/test_session.py -v
+```
+
+Tests are parametrized across all backends (Pyright, Pyrefly, ty). Key indicators:
+- **PASSED**: Feature works for that backend
+- **XFAIL**: Known limitation, documented with reason
+- **FAILED**: Regression or new issue
+
+### Step 2: Review xfail Markers
+
+In `tests/test_session.py`, search for `xfail` to find documented limitations:
+
+```python
+# Example from test_session_diagnostics:
+if backend_name == "ty":
+    pytest.xfail("ty requires files on disk for diagnostics")
+```
+
+Each xfail message explains why the feature is limited.
+
+### Step 3: Check Backend Capabilities
+
+Each backend declares its LSP capabilities in `get_lsp_capabilities()`:
+- `lsp_types/pyright/backend.py`
+- `lsp_types/pyrefly/backend.py`
+- `lsp_types/ty/backend.py`
+
+Features declared here indicate what the client advertises to the server.
+
+### Step 4: Review Known Limitations
+
+- [Pyrefly Known Limitations](../lsp_types/pyrefly/KNOWN_LIMITATIONS.md)
+- [ty Known Limitations](../lsp_types/ty/KNOWN_LIMITATIONS.md)
+
+## Updating the Feature Table
+
+### When to Update
+
+1. **After adding new Session API methods**: Add test, run it, update table
+2. **After upgrading backend versions**: Re-run tests, check for improvements, update version line
+3. **After backend releases announce new features**: Test and document
+
+### Updating Version Numbers
+
+Update the "Last verified" line in README when re-testing:
+
+```bash
+# Check installed versions
+pyright --version      # or basedpyright --version
+pyrefly --version
+ty --version
+```
+
+### Status Symbols
+
+| Symbol | Meaning | When to Use |
+|--------|---------|-------------|
+| :white_check_mark: | Fully supported | Test passes without xfail |
+| :warning: | Partial support | Test has xfail or conditional skip |
+| :x: | Not supported | Feature fails or is documented as unsupported |
+| :grey_question: | Unknown | Not exposed in Session API or not tested |
+
+### Adding Notes
+
+- Keep notes concise (under 50 characters)
+- Reference the specific limitation (e.g., "requires files on disk")
+- Use semicolons to separate multiple backend notes
+
+## Evidence Mapping
+
+| Feature | Test Function | Lines to Check |
+|---------|---------------|----------------|
+| Diagnostics | `test_session_diagnostics` | xfail around line 72 |
+| Hover | `test_session_hover` | format check around line 142 |
+| Completion | `test_session_completion` | xfail around line 258 |
+| Completion Resolution | `test_session_completion` | skip condition around line 286 |
+| Signature Help | `test_session_signature_help` | No xfails expected |
+| Rename | `test_session_rename` | xfails around lines 154, 158 |
+| Semantic Tokens | `test_session_semantic_tokens` | No xfails expected |
+
+## Untested Features
+
+Features declared in backend capabilities but not exposed in Session API:
+- Go to Definition (Pyrefly, ty declare it)
+- Find References (Pyrefly, ty declare it)
+- Code Actions
+- Formatting
+
+To test these, use the low-level `LSPProcess` API directly.