Docs: short end-to-end tutorial (build, edit, debug, troubleshooting)

TUTORIAL.md

@@ -0,0 +1,79 @@
+# Theia-Modula-2: Short Tutorial
+
+Modula-2 Studio is a GNU Modula-2 IDE built on Eclipse Theia (`modula2-ide/`).
+
+It gives you: `.mod`/`.def` highlighting, snippets, auto-uppercasing, outline / hover / go-to-definition / rename, `gm2` Build-Run, GDB debug, and `modula2.json` projects.
+
+## 1. Prerequisites
+
+```bash
+node --version  # >=24
+yarn --version  # 1.x Classic
+gm2 --version
+gdb --version
+```
+
+Debian/Ubuntu: `sudo apt install gm2 gdb binutils`
+
+## 2. Build and run
+
+```bash
+cd modula2-ide
+yarn
+yarn build
+yarn start:browser   # http://localhost:3000
+# or
+yarn start:electron
+```
+
+## 3. Open an example
+
+1. Open folder `examples/hello/`
+2. Look at:
+   - `src/Main.mod` — sample program
+   - `modula2.json` — project descriptor:
+
+```json
+{
+  "name": "Hello",
+  "compiler": {"type": "gnu-modula-2", "path": "gm2", "options": []},
+  "sourceDirectories": ["src"],
+  "main": "src/Main.mod"
+}
+```
+
+## 4. Edit Modula-2
+
+- Create `Foo.mod` / `Foo.def`. Keywords auto-uppercase (`begin` -> `BEGIN`, but `beginning` is left alone).
+- Try: hover, `F12` go-to-definition, `Shift+F12` references, `F2` rename, `Ctrl+Shift+O` outline.
+- Snippets: `mod`, `proc`, `if`, `defmod`.
+
+Commands (via `F1` / Ctrl+Shift+P):
+
+- `Modula-2: New Modula-2 Project / New Module / New Definition Module`
+- `Modula-2: Validate Project`
+- `Modula-2: About Modula-2 IDE`
+
+## 5. Build and run
+
+With `modula2.json` open in workspace:
+
+- `F1 > Modula-2: Build` — builds `bin/<name>`
+- `Modula-2: Build File / Clean / Rebuild / Run`
+- Or terminal: `gm2 -o bin/Hello src/Main.mod && ./bin/Hello`
+
+Build errors appear in Problems panel, click to jump to source.
+
+## 6. Debug
+
+1. Build with `Modula-2: Build` (passes `-g` by default, so breakpoints bind).
+2. Set breakpoint in gutter.
+3. `Run > Start Debugging`, type `modula2`. `program` defaults to `bin/<name>`.
+
+You get: continue/step over/into/out, call stack, Locals + Module scopes, hover/evaluate.
+
+## 7. Troubleshooting
+
+- Language features missing: check `plugins/modula2-language/` was synced by `yarn build:language`.
+- `gm2 not found`: set `"compiler": {"path": "/usr/bin/gm2"}` in `modula2.json`.
+- Debug `program not found`: run `Modula-2: Build` first.