diff --git a/CHANGELOG.md b/CHANGELOG.md
index 7622e26..9c83ca7 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,5 +1,8 @@
 # Changelog
 
+## [tooling] — 2026-03-17
+- Added Linguist submission prep files: `languages/Rey.yaml`, `languages/samples/Rey.rey`, `LINGUIST.md`
+
 ## [fix] — 2026-03-17
 - Added array methods: `.length()` and `.push()`
 - Allowed typed empty array assignment like `var xs: [int] = []`
diff --git a/LINGUIST.md b/LINGUIST.md
new file mode 100644
index 0000000..c860387
--- /dev/null
+++ b/LINGUIST.md
@@ -0,0 +1,39 @@
+# Rey — GitHub Linguist submission prep
+
+This repo contains **Rey**, an experimental programming language and interpreter written in Rust.
+
+This directory layout is intended to prepare a future PR to `github-linguist/linguist` so GitHub can recognize `.rey` files as the **Rey** language (syntax highlighting on GitHub, language stats, etc.).
+
+## Repo links
+- Rey language repo: https://github.com/rey-language/rey
+- GitHub Linguist: https://github.com/github-linguist/linguist
+
+## Proposed Linguist metadata
+- `.gitattributes` marks `*.rey` as `linguist-language=Rey`
+- `languages/Rey.yaml` contains the language definition (format mirrors Linguist language YAML entries)
+- `languages/samples/Rey.rey` is a clean consolidated sample for tests/highlighting
+
+## Sample sources
+The sample is consolidated from existing test fixtures:
+- `compiler/v1/src/tests/arrays.rey`
+- `compiler/v1/src/tests/array_methods.rey`
+- `compiler/v1/src/tests/functions.rey`
+- `compiler/v1/src/tests/property_access.rey`
+- `compiler/v1/src/tests/full_demo.rey`
+
+## Sample code
+```rey
+// see languages/samples/Rey.rey for the full sample
+func main(): Void {
+    var xs: [int] = [];
+    xs.push(1);
+    println(xs.length());
+}
+```
+
+## How this maps to a future Linguist PR
+In `github-linguist/linguist`, this would translate to:
+- Adding `.rey` + metadata to Linguist’s language definitions
+- Adding `languages/samples/Rey.rey` (or equivalent) as the sample used for detection/highlighting tests
+
+This repo keeps the metadata and sample here to make the upstream PR straightforward.
diff --git a/languages/Rey.yaml b/languages/Rey.yaml
new file mode 100644
index 0000000..dd2cec0
--- /dev/null
+++ b/languages/Rey.yaml
@@ -0,0 +1,7 @@
+name: Rey
+type: programming
+color: "#eb4c3b"
+extensions:
+  - ".rey"
+tm_scope: source.rey
+ace_mode: text
diff --git a/languages/samples/Rey.rey b/languages/samples/Rey.rey
new file mode 100644
index 0000000..4343803
--- /dev/null
+++ b/languages/samples/Rey.rey
@@ -0,0 +1,37 @@
+// Rey sample for GitHub Linguist
+
+func add(a: int, b: int): int {
+    return a + b;
+}
+
+func main(): Void {
+    // typed empty array + methods + builtins
+    var xs: [int] = [];
+    xs.push(1);
+    xs.push(2);
+    println(xs.length());
+    println(len(xs));
+
+    // dictionaries + property access
+    var user = {name: "Rey", id: 42};
+    if (user.id > 10) {
+        println("ok");
+    } else {
+        println("no");
+    }
+
+    // loops + range + break/continue
+    var sum: int = 0;
+    for i in range(1, 10) {
+        if (i == 3) { continue; }
+        if (i == 6) { break; }
+        sum = sum + i;
+    }
+    println(sum);
+
+    while (sum > 0) {
+        sum = sum - 1;
+    }
+
+    println(add(2, 3));
+}
diff --git a/primer.md b/primer.md
index 805a737..55e32bd 100644
--- a/primer.md
+++ b/primer.md
@@ -52,3 +52,6 @@ Run any of them with cargo run -- src/tests/.rey
 ## For next session
 - Consider tightening the language spec (what is int vs float at runtime, truthiness rules, dictionary key restrictions).
 - Add negative tests for type errors once there's a harness for expected-failure cases.
+- Submit upstream PRs:
+  - `github-linguist/linguist` for Rey language recognition
+  - VSCode Marketplace publish for `rey-vscode/` (optional)