From ff4055a044e5299b8378fbcb354d8063348743ea Mon Sep 17 00:00:00 2001
From: Henrik Jess Nielsen <henrik@i80.dk>
Date: Fri, 14 Aug 2026 18:01:53 +0200
Subject: [PATCH] docs(readme): add confirmed LSP feature-coverage table with
 live examples

Documents the full capability audit results (hover/definition/references/
symbols/formatting/codeAction/signatureHelp/foldingRange/workspaceSymbol)
per language endpoint, plus concrete before/after examples captured from
live requests against production.
---
 README.md | 64 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 64 insertions(+)

diff --git a/README.md b/README.md
index aa878f1..5d97630 100644
--- a/README.md
+++ b/README.md
@@ -13,6 +13,70 @@ Provides smart autocomplete on top of standard LSPs:
 
 → See **[EDITOR_SETUP.md](EDITOR_SETUP.md)** for editor configuration and a full feature overview.
 
+## LSP feature coverage
+
+Full capability audit against production (verified 2026-08-14) — everything below
+is confirmed working end-to-end over the live WebSocket endpoints, not just in
+theory:
+
+| Feature | Bicep (`/bicep`) | Python (`/python`) | YAML (`/yaml`) |
+|---|---|---|---|
+| Completions (+ internal catalogs) | ✅ | ✅ | ✅ |
+| Hover | ✅ | ✅ | ✅ |
+| Go to definition | ✅ | ✅ | — |
+| Find references | ✅ | ✅ | — |
+| Document symbols | ✅ | ✅ | — |
+| Document formatting | ✅ | ✅ | — |
+| Code actions | ✅ | ✅ | — |
+| Signature help | ✅ *(iLSP-provided)* | ✅ | — |
+| Folding range | ✅ *(iLSP-provided)* | ✅ | — |
+| Workspace symbol | ✅ *(iLSP-provided)* | ❌ (pylsp doesn't implement it) | — |
+| Diagnostics | ✅ | ✅ | ✅ |
+
+Bicep.LangServer itself (v0.46.1, latest) doesn't implement signature help,
+folding range, or workspace symbol — iLSP answers these three locally in the
+proxy (`ilsp/bicep_lsp/local_features.py`) instead of forwarding to a backend
+that would just error or return nothing.
+
+### Confirmed examples (live against `wss://ilsp.i80.dk/bicep`)
+
+**Role-array completion** — cursor inside `roles: [...]` returns all 682 Azure
+built-in roles:
+```
+roles: ['KEY_VAULT_SECRETS_USER', 'STORAGE_BLOB_DATA_CONTRIBUTOR', <cursor>]
+→ 682 items: ACCESS_REVIEW_OPERATOR_SERVICE_ROLE, ACRDELETE, ACRIMAGESIGNER, ACRPULL, ACRPUSH, ...
+```
+
+**Go to definition** — jumping from a variable usage to its declaration:
+```bicep
+var storageName = '${projectName}storage'   # ← declared here (line 2)
+resource sa '...' = {
+  name: storageName                          # ← cursor here → jumps to line 2
+}
+```
+
+**Find references** — from the `storageName` declaration, finds both places
+it's used: the string interpolation `${projectName}storage` isn't a reference,
+but the `resource sa { name: storageName }` property assignment is — returns
+the declaration itself plus that 1 real usage (2 results total).
+
+**Document symbols** — outline for a file with params/vars/resources/modules:
+```
+location, projectName, storageName, sa, roleAssignment, storageId
+```
+
+**Signature help** — cursor right after `resourceId(`:
+```
+resourceId(resourceType, resourceName1, resourceName2...)
+                ^ active parameter highlighted
+```
+
+**Folding range** — every multi-line `{}`/`[]`/`()` block returned as a
+collapsible region (nested blocks included).
+
+**Workspace symbol** — searching `"storage"` across all open documents in the
+editor session returns `storageName`, `storageId`, etc.
+
 ## Quick start
 
 ```bash