diff --git a/README.md b/README.md
new file mode 100644
index 0000000..f5d984d
--- /dev/null
+++ b/README.md
@@ -0,0 +1,58 @@
+# fasmg syntax support
+
+Generated syntax-highlighting assets and validation fixtures for the
+[flat assembler g](https://github.com/tgrysztar/fasmg) language.
+
+The repository keeps a Python description of the grammar in `scripts/spec.py`
+and generates editor-facing outputs under `dist/`:
+
+- `dist/fasmg.tmLanguage.json` — TextMate-compatible grammar JSON.
+- `dist/fasmg.udl.xml` — Notepad++ user-defined language XML.
+
+It also contains a starter Tree-sitter projection in `tree-sitter-fasmg/` and
+assembler fixtures in `test_suit/`.
+
+## Repository layout
+
+| Path | Purpose |
+| --- | --- |
+| `scripts/spec.py` | Single source of truth for token groups and regex fragments. |
+| `scripts/gen_all.py` | Regenerates all checked-in syntax outputs in `dist/`. |
+| `scripts/lint_grammar.py` | Compiles grammar regexes as a fast sanity check. |
+| `scripts/validate.py` | Runs `test_suit/pass` and `test_suit/fail` fixtures against a real `fasmg` executable. |
+| `dist/` | Generated TextMate and Notepad++ artifacts. |
+| `test_suit/` | Known-valid and known-invalid fasmg source fixtures. |
+| `tree-sitter-fasmg/grammar.js` | Tree-sitter grammar entry point. |
+| `tree-sitter-fasmg/queries/` | Tree-sitter highlight, local-symbol, and fold queries. |
+
+## Quick checks
+
+From the repository root:
+
+```sh
+python3 -m py_compile scripts/*.py
+python3 scripts/gen_all.py --lint
+python3 scripts/lint_grammar.py dist/fasmg.tmLanguage.json
+```
+
+When a `fasmg` binary is available, also run the assembler-backed fixture
+validation:
+
+```sh
+python3 scripts/validate.py --fasmg /path/to/fasmg
+```
+
+Without `--fasmg`, `scripts/validate.py` searches `PATH` and a few local Windows
+checkout locations.
+
+## Regenerating outputs
+
+After editing `scripts/spec.py` or either generator, refresh the checked-in
+artifacts with:
+
+```sh
+python3 scripts/gen_all.py --lint
+```
+
+Review the resulting `dist/` diff before committing so generated files stay in
+sync with the Python specification.