1 files changed, 30 insertions, 0 deletions
diff --git a/editors/vscode/README.md b/editors/vscode/README.md
new file mode 100644
index 0000000..d60194e
--- /dev/null
+++ b/editors/vscode/README.md
@@ -0,0 +1,30 @@
+# zc for vs code
+
+this extension connects vscode to the zc language server. the server runs the compiler in check mode, so diagnostics and semantic highlighting reflect the language the compiler actually parses, including syntax introduced with parse words.
+
+features include compiler diagnostics, optimization hints, semantic highlighting, hover documentation and immediate textmate highlighting while the server starts.
+
+## install
+
+there is no build step for local installation. package the extension with `bash src/tools/mkvsix.sh`, then choose “extensions: install from vsix” in vscode. the package includes a webassembly server; if that file is unavailable, the extension can run the server in the tinyvm javascript vm, which is slower. a native server can be selected with `zc.lsp.serverPath`.
+
+## settings
+
+```json
+{
+  "zc.lsp.serverPath": "",
+  "zc.trace.server": "messages"
+}
+```
+
+an empty server path uses the bundled server. if the server exits, the extension restarts it and resends open documents.
+
+## diagnostics cache
+
+diagnostics are cached per document using a sha256 key that includes the server build, document path and text, and files read through `include`. included files are resolved from the workspace folder and from the including file's directory. saving an included file triggers checks for open documents that use it. cached diagnostics are restored from extension storage when vscode starts; workspaces with more than 300 files are not cached.
+
+## limitations
+
+the bundled webassembly server cannot read included files from disk. use a native server with `zc.lsp.serverPath` when diagnostics need filesystem access for includes. hover does not follow declarations reached through `include` yet.
+
+see `tests/drivers/lsp_test.js` for protocol tests and `src/tools/mkvsix.sh` for packaging.