From a250d96c63da2817af8c373b637f63594c55baf5 Mon Sep 17 00:00:00 2001
From: Emin Arslan <me@emin.engineer>
Date: Wed, 4 Feb 2026 21:52:16 +0300
Subject: [PATCH] core_ast: remove letrec comment

---
 doc/env.md               | 41 ++++++++++++++++++++++++++++++++++++++++
 lib/compiler/core_ast.ml |  1 -
 2 files changed, 41 insertions(+), 1 deletion(-)
 create mode 100644 doc/env.md

diff --git a/doc/env.md b/doc/env.md
new file mode 100644
index 0000000..6df89f7
--- /dev/null
+++ b/doc/env.md
@@ -0,0 +1,41 @@
+This document holds my design notes for lexical and global environments
+for this compiler. I have not yet named the language.
+
+# Environments
+
+An environment is an integral part of the runtime of the language.
+There is a global environment that holds the values of all global
+symbols.
+
+Lexical environments generally don't exist in practice, instead we use
+flat closures. When a closure is created at runtime, all free variables
+it uses are packaged as part of the function object, then the function
+body uses a GetFree instruction to get those free variables by an index.
+
+Free variables are propagated from inner closures outwards. This is necessary,
+as this also handles multiple-argument functions gracefully.
+
+
+```scheme
+(let ((a 10))
+  (print (+ a 5)))
+```
+
+
+## Global Definitions
+
+Any symbol defined through a top-level `define` form is made globally available
+after the definition form.
+
+This is the most common use for define.
+
+Generally any symbol appearing in the body of a function, will only be compiled
+to access that symbol. The symbol is only accessed once the function is called.
+Thus, you can create mutually recursive functions at the top level with no issue.
+
+## Local Definitions
+
+It is valid to use `define` forms in body sections. Informally, a body section
+is the body of most built-in forms, including `lambda`, `let`, and `letrec`.
+
+
diff --git a/lib/compiler/core_ast.ml b/lib/compiler/core_ast.ml
index 4319810..5a0e2e0 100644
--- a/lib/compiler/core_ast.ml
+++ b/lib/compiler/core_ast.ml
@@ -16,7 +16,6 @@ type expression =
   | Var of string
   | Apply of expression * expression
   | Lambda of string * expression
-  (*| LetRec of (string * expression) list * expression   *)
   | If of expression * expression * expression
   | Set of string * expression
   | Begin of expression list