CLAUDE.md

@@ -207,6 +207,19 @@ Implementation files:
 
 **Why this matters**: This enables shell-like file paths (`readme.txt`) while supporting dictionary/array access (`config.path`) without quotes, determined entirely at parse time based on lexical scope.
 
+**Array and dict literals**: Square brackets `[]` create both arrays and dicts, distinguished by content:
+- **Arrays**: Space/newline/semicolon-separated args that work like calling a function → `[1 2 3]` (call functions using parens eg `[1 (double 4) 200]`)
+- **Dicts**: NamedArg syntax (key=value pairs) → `[a=1 b=2]` 
+- **Empty array**: `[]` (standard empty brackets)
+- **Empty dict**: `[=]` (exactly this, no spaces)
+
+Implementation details:
+- Grammar rules (shrimp.grammar:194-201): Dict uses `NamedArg` nodes, Array uses `expression` nodes
+- Parser distinguishes at parse time based on whether first element contains `=`
+- Both support multiline, comments, and nesting
+- Separators: spaces, newlines (`\n`), or semicolons (`;`) work interchangeably
+- Test files: `src/parser/tests/literals.test.ts` and `src/compiler/tests/literals.test.ts`
+
 **EOF handling**: The grammar uses `(statement | newlineOrSemicolon)+ eof?` to handle empty lines and end-of-file without infinite loops.
 
 ## Compiler Architecture

example.shrimp

@@ -42,13 +42,13 @@ a-file = file.txt
 3
 
 # symbols can be assigned to functions. The body of the function comes after a colon `:`
-add = fn x y: x + y
+add = do x y: x + y
 add 1 2
 ---
 3
 
 # Functions can have multiple lines, they are terminated with `end`
-sub = fn x y:
+sub = do x y:
   x - y
 end
 
@@ -82,9 +82,25 @@ add 1 (sub 5 2)
 4
 
 
+# Arrays use square brackets with space-separated elements
+numbers = [1 2 3]
+shopping-list = [apples bananas carrots]
+empty-array = []
+
+# Dicts use square brackets with key=value pairs
+config = [name=Shrimp version=1.0 debug=true]
+empty-dict = [=]  
+
+# Nested structures work naturally
+nested = [
+  users=[
+    [name=Alice age=30]
+    [name=Bob age=25]
+  ]
+  settings=[debug=true timeout=5000]
+]
+
 # HOLD UP
 
-- how do we handle arrays?
-- how do we handle hashes?
 - conditionals
 - loops