1 files changed, 87 insertions, 0 deletions
diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md
new file mode 100644
index 0000000..fac102a
--- /dev/null
+++ b/.github/copilot-instructions.md
@@ -0,0 +1,87 @@
+# Zen C Copilot Instructions
+
+These instructions are **MANDATORY** for all code generation and review tasks in the Zen C project.
+
+## 1. Memory Management (Critical)
+*   **Arena Allocation**: The compiler uses a bump-pointer arena allocator.
+    *   **MUST USE**: `xmalloc`, `xcalloc`, `xrealloc`, `xstrdup` (defined in `src/utils/utils.c`).
+    *   **NEVER USE**: Standard `malloc`, `calloc`, `free` (unless interfacing with an external library that strictly requires owned heap memory, like CJSON).
+*   **Destructors/Freeing**:
+    *   `free(ptr)` is `#defined` to `((void)0)` in `src/zprep.h`. It is a no-op.
+    *   Do **NOT** attempt to free AST nodes or types. `ast_free` is a no-op.
+    *   Memory is reclaimed only when the process exits. Design your data structures accordingly (append-only is fine).
+
+## 2. AST and Type System
+*   **Creation**: Use `ast_create(NODE_TYPE)` to allocate new nodes.
+*   **Type Representation**:
+    *   Use `Type` struct (defined in `src/ast/ast.h`).
+    *   Use `type_new(TYPE_KIND)` helper.
+    *   `type_to_string(t)` and `type_to_c_string(t)` return arena-allocated strings. Do not worry about freeing them.
+*   **Traversal**:
+    *   The compiler uses **Recursive Descent** with **Switch Statements** on `node->type`.
+    *   Do NOT introduce Visitor patterns or callback tables unless consistent with existing code.
+
+## 3. Parser Patterns
+*   **Context**: `ParserContext *ctx` is the god-object. It MUST be passed to almost every function in parsing, analysis, and codegen.
+    *   **Signature Rule**: `ReturnType func_name(ParserContext *ctx, ...)`
+*   **Token Consumption**:
+    *   Use `expect(lexer, TOKEN_TYPE, "error message")` for mandatory tokens.
+    *   For optional tokens, check `l->token.type` and assume `lexer_next(l)` is used to advance (verify specific helper availability).
+*   **Error Handling**:
+    *   **Fatal**: `zpanic("msg")` or `zpanic_at(token, "msg")`. Exits immediately (or delegates to LSP handler).
+    *   **Warning**: `zwarn("msg")` or `zwarn_at(token, "msg")`.
+    *   **Semantic Errors**: Prefer `zpanic_at` for type errors to give line/col info.
+
+## 4. Code Generation (C Backend)
+*   **Generic Mangling**:
+    *   Generic structs (e.g., `Slice<int>`) are mangled to `Slice_int` **IF AND ONLY IF** the instantiated struct exists (checked via `find_struct_def_codegen`).
+    *   **Fallback**: If the mangled struct (e.g. `Async_int`) does not exist, use the base name (`Async`). This handles opaque types like `Async<T>` correctly.
+    *   See `emit_c_decl` in `src/codegen/codegen_utils.c` for the canonical implementation.
+*   **Function Signatures**:
+    *   Use `emit_func_signature(ctx, out, node, override_name)` to handle modifiers, return types, and arguments correctly.
+*   **Output**: Use `fprintf(out, ...)` where `out` is the `FILE*`.
+
+## 5. Coding Style & Conventions
+*   **Formatting**:
+    *   Indentation: 4 spaces.
+    *   Braces: **ALWAYS** Use braces `{}` for control flow (`if`, `while`, `for`), even for single lines.
+    *   Opening brace on the **NEXT** line (Allman style).
+*   **Naming**:
+    *   Structs/Enums: `PascalCase`.
+    *   Functions/Variables: `snake_case`.
+    *   Macros/Constants: `SCREAMING_SNAKE_CASE`.
+    *   Private/Static: No strict prefix, but `static` keyword is mandatory for internal file-scope functions.
+*   **Iterators**:
+    *   When implementing iteration in compiler (C code): Use `while (node) { ... node = node->next; }` for linked lists (`ASTNode`, `StructRef`).
+
+## 6. Standard Library (Zen C Definitions)
+*   **Arrays**: Use `for val in arr` syntax (direct iteration).
+*   **Vectors**: `Vec<T>` is a dynamic array.
+*   **Strings**: `string` in Zen C maps to `char*` in C. `kstring` or `zstr` are higher-level wrappers.
+
+## 7. Common Pitfalls
+*   **Unused Variables**: The compiler builds with `-Wall -Werror` (or similar strictness). Cast unused vars to void: `(void)var_name;`.
+## 8. Zen C Language Rules (For writing .zc files)
+*   **Syntax**:
+    *   Variables: `let x = 10;`, `let y: const int = 20;`.
+    *   Constants: `def MAX = 100;` (compile-time).
+    *   Functions: `fn name(arg: type) -> ret { ... }`.
+    *   Structs: `struct Point { x: int; y: int; }`.
+    *   Enums: `enum Shape { Circle(float), Rect(float, float) }`.
+*   **Memory & Resources**:
+    *   **Move Semantics**: Structs/Enums are moved by default on assignment/pass-by-value.
+    *   **Defer**: Use `defer stmt;` to run cleanup at scope exit.
+    *   **Drop**: Implement `impl Drop for T` for RAII.
+*   **Arrays & Slices**:
+    *   **Iteration**: Use `for val in arr` (direct iteration supported).
+    *   **Slices**: `Slice<T>` is a view. `int[N]` auto-converts to slice in loops.
+*   **Generics**:
+    *   Syntax: `struct Box<T> { val: T; }`.
+*   **Concurrency**:
+    *   Use `async fn` and `await` keyword.
+    *   `Async<T>` is the opaque future type.
+*   **Standard Library**:
+    *   Import with `import "std/io.zc"`, `import "std/vec.zc"`.
+    *   Use `println "msg"` (shorthand) or `printf`.
+*   **Testing**:
+    *   Use `test "name" { ... }` blocks for unit tests.