1 files changed, 67 insertions, 0 deletions
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..4e77c14
--- /dev/null
+++ b/README.md
@@ -0,0 +1,67 @@
+# Zig Extension for Nova — Development Guide
+
+## Overview
+
+This repository contains the Zig language extension for Nova. For user documentation, see [Zig.novaextension/README.md](Zig.novaextension/README.md).
+
+## Development
+
+### Parser
+
+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
+```
+
+### Validation
+
+Validate the extension bundle:
+
+```sh
+/Applications/Nova.app/Contents/SharedSupport/nova extension validate Zig.novaextension/
+```
+
+### Testing
+
+Manual test cases are documented in [TESTING.md](TESTING.md). Run the test suite:
+
+```sh
+cd examples/test-suite && zig build test
+```
+
+## Architecture
+
+### Extension Structure
+
+- `Zig.novaextension/` — Nova extension bundle
+  - `Scripts/main.js` — Extension entry point, task system, ZLS client, debugger
+  - `extension.json` — Manifest with task templates, config schema, language definitions
+  - `Syntax/` — Syntax definitions and Tree-Sitter integration
+  - `Commands/` — Custom commands and menu items
+- `vendor/tree-sitter-zig/` — Vendored Tree-Sitter grammar
+- `examples/` — Example projects for testing and demonstration
+- `build/` — Build artifacts (not in use)
+
+### Key Components
+
+**Language Server Integration** — ZLS is launched on activation and provides completions, hover, go-to-definition, and diagnostics via the Nova language client API.
+
+**Task System** — Four task templates (`zigBuildRun`, `zigTest`, `zigDebug`, `zigWatch`) wrap `zig build` subcommands with configurable arguments.
+
+**Issue Collection** — Compiler diagnostics are parsed into a JSON file and loaded into Nova's issue collection for inline gutter annotations.
+
+**Debugger** — LLDB-DAP is auto-discovered and used to debug Zig binaries via breakpoints and step controls.
+
+## License
+
+The extension's source code is licensed under the BSD 2-Clause License (see [`LICENSE`](LICENSE)). Bundled assets and vendored third-party code carry their own licenses, documented in [`NOTICES.md`](NOTICES.md).