1 files changed, 126 insertions, 0 deletions
diff --git a/tree-sitter/dsk/dsk-cli/README.md b/tree-sitter/dsk/dsk-cli/README.md
new file mode 100644
index 0000000..d07a9dd
--- /dev/null
+++ b/tree-sitter/dsk/dsk-cli/README.md
@@ -0,0 +1,126 @@
+# dsk-cli
+
+DSL Development Kit (DSK) – a CLI that helps you design, build, test, and ship Tree-sitter based Domain-Specific Languages (DSLs) with a convention-over-configuration workflow.
+
+## Why this is helpful
+- **Lower barrier to entry**: Generate a working Tree-sitter `grammar.js` from examples via an interactive flow.
+- **No boilerplate**: One command builds both a C static library and a Node.js addon package.
+- **Fast iteration**: Built-in watch mode (`dsk dev`) and testing (`dsk test`).
+- **Editor-ready**: Generate Tree-sitter highlight queries and editor scaffolds (Neovim, Emacs, VS Code).
+- **Consistent outputs**: Standardized project layout and generated artifacts under `generated/` and `dist/`.
+
+## Prerequisites
+- macOS or Linux
+- [Bun](https://bun.sh) (to run `dsk`)
+- [tree-sitter CLI](https://tree-sitter.github.io/tree-sitter/creating-parsers#installation) (`npm i -g tree-sitter-cli` or `brew install tree-sitter`)
+- C toolchain: clang/gcc and `ar` (macOS: `xcode-select --install`, Ubuntu: `build-essential`)
+- For the generated JS addon builds: Python 3 and make are typically required by node-gyp (the template depends on `node-gyp`)
+
+## Install (for developing this CLI)
+```bash
+bun install
+bunx tsc
+bun link  # optional: exposes `dsk` on your PATH during development
+```
+
+## Quickstart (creating a DSL)
+```bash
+# 1) Scaffold a new DSL project interactively
+dsk new my-lang --interactive
+
+# 2) Move into the project directory
+cd my-lang
+
+# 3) Build (generates parser, C lib, and JS addon)
+dsk build
+
+# 4) Run tests (expects corpus in `corpus/` or queries)
+dsk test -v
+
+# 5) Iterate with watch mode
+dsk dev --debounce 150
+
+# 6) Generate editor highlighting scaffolds
+dsk highlight
+
+# 7) Package outputs for distribution
+dsk package
+```
+
+## Command reference
+
+### `dsk new <name> [--interactive]`
+Creates a new DSL project. With `--interactive`, it asks for examples and infers common token patterns, then generates a starter `grammar.js` and project structure using templates.
+
+### `dsk build` [--verbose] [--skip-c] [--skip-js]
+Builds your DSL:
+- Runs `tree-sitter generate`
+- Builds a C static library and header under `generated/c/`
+- Creates a Node.js addon package under `generated/js/` (compiles via node-gyp)
+
+Outputs:
+- `generated/c/include/<dsl>.h`
+- `generated/c/lib/lib<dsl>.a`
+- `generated/js/` (package.json, binding.gyp, compiled addon, copied `src/`)
+
+### `dsk test` [-u|--update] [-f|--filter <regex>] [--cwd <dir>] [-v|--verbose] [patterns...]
+Thin wrapper around `tree-sitter test` that streams output directly.
+- `--update`: updates expected output snapshots
+- `--filter <regex>`: only run tests whose description matches
+- `--cwd <dir>`: run tests in a different directory
+- `--verbose`: pass through verbose output
+
+Examples:
+```bash
+dsk test
+dsk test -v -f numbers
+dsk test -u corpus/examples.txt
+```
+
+### `dsk dev` [--debounce <ms>] [--quiet] [-v|--verbose]
+Watches `grammar.js` and on changes runs `dsk build` then `dsk test`.
+- `--debounce <ms>`: delay rebuild after changes (default: 150)
+- `--quiet`: suppress non-error logs
+- `--verbose`: pass to `dsk build` (more detailed build logs)
+
+### `dsk highlight`
+Generates highlighting assets and editor scaffolds:
+- `generated/editors/tree-sitter/highlights.scm`
+- `generated/editors/neovim/setup-instructions.md`
+- `generated/editors/emacs/<lang>-mode.el`
+- `generated/editors/vscode/syntaxes/<lang>.tmLanguage.json`
+- `generated/editors/vscode/language-configuration.json`
+
+### `dsk package`
+Packages build outputs into `dist/`:
+- Archives `generated/c/` as `dist/c-artifacts.tar.gz`
+- Packs the JS addon under `generated/js/` via `bun pack` (falls back to `npm pack`)
+
+### `dsk self:package`
+Builds and packages the `dsk` CLI itself into a tarball under `release/`.
+```bash
+dsk self:package
+# → release/dsk-cli-<version>.tgz
+```
+
+## Project structure (generated DSL project)
+- `grammar.js`: Tree-sitter grammar
+- `src/`: generated parser sources after `tree-sitter generate`
+- `corpus/`: test cases for `tree-sitter test`
+- `generated/`: build outputs (C and JS targets)
+- `generated/editors/`: highlight queries and editor scaffolds
+- `dist/`: packaged artifacts
+
+## Notes about the JS addon template
+- Depends on `node-addon-api` and `node-gyp` (declared in template `package.json`)
+- `binding.gyp` includes Node-API headers and defines `NAPI_VERSION=8`
+- Builds via `npm install` or `bun install` in `generated/js/` (auto-detected)
+
+## Troubleshooting
+- `tree-sitter` not found: install with `npm i -g tree-sitter-cli` or `brew install tree-sitter`
+- C compiler not found: macOS `xcode-select --install`; Linux install `build-essential`
+- node-gyp build issues: ensure Python 3 and make are available; re-run `dsk build -v`
+
+---
+
+This project was created using `bun init` in bun v1.1.29. [Bun](https://bun.sh) is a fast all-in-one JavaScript runtime.