1 files changed, 87 insertions, 0 deletions

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..46218d9
--- /dev/null
+++ b/README.md
@@ -0,0 +1,87 @@
+# Zig for Nova
+
+Zig language support – ZLS, LLDB, Tree-Sitter grammar
+
+## Requirements
+
+- [Zig](https://ziglang.org/download/) installed and on `PATH` (or configured in extension preferences)
+- [ZLS](https://github.com/zigtools/zls)\* for language intelligence
+- [LLDB DAP](https://lldb.llvm.org/use/lldbdap.html)\* for debugging (discovered automatically via `xcrun` or `PATH`; install the Xcode Command Line Tools if absent: `xcode-select --install`)
+
+\* optional but recommended for full experience
+
+## Why
+
+A personal project to learn Zig without leaving Nova and without giving up the comfort of language server and debugging features.
+
+## Features
+
+### Editing
+
+- Syntax highlighting for `.zig` and `.zon`
+- Code folding for blocks, declarations, and control-flow expressions
+- Document symbols (outline, breadcrumbs, Go to Symbol)
+- Diagnostics, completion, hover, go to definition, find references, select all references, formatting (all via ZLS)
+- Inline compiler errors from `zig build`
+
+### Tasks
+
+- **Zig Package**: build and run a Zig package in the Nova console
+- **Zig Package (macOS Terminal)**: build and run in the external Terminal app for interactive CLIs
+- **Zig Debug**: build in Debug mode and launch under the debugger, with configurable console and stop-on-entry
+- A clean action on every runnable template that removes `.zig-cache`, `zig-cache`, and `zig-out`
+
+### Debugging
+
+- Breakpoint support in Zig source files
+- LLDB-based debug adapter, auto-discovered via `xcrun` or `PATH`
+
+## Configuration
+
+Global settings live under **Nova Preferences > Extensions > Zig**.
+Per-workspace overrides live under **Project Settings > Zig** and take precedence.
+
+### Tooling
+
+Paths to the `zig`, `zls`, and `lldb-dap` executables. Leave any blank to discover from `PATH`.
+
+### Language Server
+
+- Enable or disable ZLS
+- Allow ZLS to run its build/check on save
+- Log ZLS traffic to the Extension Console (for troubleshooting)
+
+## Troubleshooting
+
+### A large part of the file turns red after one error
+
+The parser may report a broad recovery range when it hits an incomplete expression (for example, `MyError.`), and Nova highlights that entire range. Fix the first syntax error shown and the overlay should narrow to the real error locations.
+
+## Development
+
+The Tree-sitter parser is built from the vendored grammar snapshot under `vendor/tree-sitter-zig`. The pinned upstream commit is recorded in `vendor/tree-sitter-zig/VENDORING.md`.
+
+Rebuild the parser dylib:
+
+```sh
+./Scripts/build-parser.sh
+```
+
+Bump the vendored snapshot (and rebuild):
+
+```sh
+./Scripts/update-parser.sh           # upstream HEAD
+./Scripts/update-parser.sh <ref>     # specific tag, branch, or SHA
+```
+
+Validate the extension bundle:
+
+```sh
+/Applications/Nova.app/Contents/SharedSupport/nova extension validate .
+```
+
+## Attributions
+
+The Zig logo is the work of the [Zig Software Foundation](https://ziglang.org) and is licensed under [CC BY-SA 4.0](https://creativecommons.org/licenses/by-sa/4.0/). The zig-debug@2x.png is a derivative of the original logo, improving pixel alignment at 32px size.
+
+The Tree-sitter grammar for Zig is sourced from [github.com/tree-sitter-grammars/tree-sitter-zig](https://github.com/tree-sitter-grammars/tree-sitter-zig).