Document Go compatibility matrix and support policy

Author: mgomes

README.md

@@ -163,6 +163,7 @@ Long-form guides live in `docs/`:
 - `docs/typing.md` – gradual typing: annotations, nullable `?`, positional/keyword binding, and return checks.
 - `docs/examples/` – runnable scenario guides (campaign reporting, rewards, notifications, module usage, and more).
 - `docs/releasing.md` – GoReleaser workflow for changelog and GitHub release automation.
+- `docs/compatibility.md` – supported Go versions and CI coverage notes.
 - `ROADMAP.md` – versioned implementation checklist and release roadmap.
 
 ## Development

ROADMAP.md

@@ -335,7 +335,7 @@ Goal: improve day-to-day developer productivity and interpreter robustness.
 
 - [ ] Add smoke tests for docs examples to CI.
 - [ ] Add release checklist automation for changelog/version bumps.
-- [ ] Add compatibility matrix notes for supported Go versions.
+- [x] Add compatibility matrix notes for supported Go versions.
 
 ### v0.19.0 Definition of Done
 

docs/compatibility.md

@@ -0,0 +1,15 @@
+# Go Compatibility Matrix
+
+VibeScript currently targets the Go toolchain version declared in `go.mod`.
+
+| Go Version | Status | CI Coverage | Notes |
+| --- | --- | --- | --- |
+| `1.26.x` | Supported | `ubuntu-latest`, `macos-latest`, `windows-latest` | Primary development and release target. |
+| `<1.26` | Unsupported | None | May fail to build or run correctly. |
+| `>1.26` | Best effort | None | Expected to work, but not yet part of the pinned CI matrix. |
+
+## Policy Notes
+
+- The minimum supported Go version is the `go` directive in `go.mod`.
+- Before `v1.0`, minimum-version bumps may happen in minor releases.
+- Compatibility changes are tracked in `ROADMAP.md` and release notes.

docs/introduction.md

@@ -32,3 +32,4 @@ dives on specific topics.
   helpers with `require` and module search paths.
 - `stdlib_core_utilities.md` – examples for JSON, regex, random IDs, numeric
   conversion, and common time parsing helpers.
+- `compatibility.md` – supported Go versions and CI coverage expectations.