This is a fantastic milestone. Having a formal specification document for your
AST is exactly what you need to ensure any future transpiler (whether written
by you or generated by an AI) hits the mark perfectly.
Here is a comprehensive, scannable reference guide. I've formatted it as a
shell snippet so you can pipe it directly into a new docs/AST_REFERENCE.md
file on your Android terminal.
mkdir -p docs
cat << 'EOF' > docs/AST_REFERENCE.md
# JL-AST (JSON-Lisp) Reference Manual

This document defines the abstract syntax tree (AST) format used by the JL-AST
Compiler and Virtual Machine. The AST is strictly JSON-compatible.

## 1. Core Evaluation Rules
All programs are composed of primitives or expressions evaluated recursively.

*   **Numbers, Booleans, Null:** Evaluate to themselves. (e.g., `42` -> `42`).
*   **Strings:** Bare strings are treated as **variable identifiers**. (e.g.,
`"x"` compiles to `LOAD x`).
*   **Lists (Expressions):** Formatted as `["op", arg1, arg2, ...]`. The first
element is the operation, followed by its evaluated arguments.
*   **String Literals:** To represent a string value, wrap it: `["str",
"hello"]` or `["quote", "hello"]`.

## 2. Math, Logic & Relational
*Note: In `strict` mode, the compiler will insert runtime type assertions
(`ASSERT_NUM`, `ASSERT_BOOL`) for these operations.*

| Operation | Syntax | Description |
| :--- | :--- | :--- |
| **Math** | `["+", a, b]`, `["-", a, b]`, `["*", a, b]`, `["/", a, b]` |
Standard floating-point arithmetic. |
| **Integer Math** | `["div", a, b]`, `["mod", a, b]` | Truncating integer
division and modulo. |
| **Relational** | `["<", a, b]`, `[">", a, b]`, `["<=", a, b]`, `[">=", a,
b]` | Numeric comparisons. |
| **Equality** | `["=", a, b]`, `["!=", a, b]` | Strict equality checks
(accepts any types). |
| **Logic** | `["and", a, b]`, `["or", a, b]`, `["not", a]` | Boolean logic. |

## 3. Data Structures
| Operation | Syntax | Description |
| :--- | :--- | :--- |
| **Array** | `["array", item1, item2]` | Creates an array containing the
evaluated items. |
| **Record** | `["record", "key1", val1, ...]` | Creates an object. Must have
an even number of arguments. |
| **Property Get** | `["get", target, "key"]` | Retrieves a value from an
array or record. |
| **Property Set** | `["set-idx", target, "key", val]` | Mutates `target[key]
= val` and returns `val`. |
| **List Ops** | `["cons", item, list]`, `["head", list]`, `["tail", list]`,
`["empty?", list]` | Functional list manipulation primitives. |

## 4. Control Flow
| Operation | Syntax | Description |
| :--- | :--- | :--- |
| **Block** | `["do", expr1, expr2, ...]` | Evaluates all expressions
sequentially. Returns the result of the last expression. |
| **Condition** | `["if", cond, thenExpr, elseExpr]` | Branching logic. |
| **While Loop** | `["while", cond, body]` | Loops while `cond` is true.
Returns `null`. |
| **Repeat Loop** | `["repeat", body, cond]` | Pascal-style. Executes `body`
at least once, loops until `cond` is true. Returns `null`. |
| **For Loop** | `["for", "i", start, end, body]` | Inclusive iteration from
`start` to `end`. Returns `null`. |

## 5. Variables & Functions
| Operation | Syntax | Description |
| :--- | :--- | :--- |
| **Let (Block)** | `["let", [["x", 1], ["y", 2]], body]` | Creates
block-scoped variables and evaluates `body`. |
| **Def (Global)** | `["def", "name", ["arg1"], body]` | Defines a function
and binds it to `name`. Supports Tail Call Optimization. |
| **Call** | `["funcName", arg1, ...]` | Executes a user-defined function. |

## 6. Concurrency & Error Handling
| Operation | Syntax | Description |
| :--- | :--- | :--- |
| **Yield** | `["yield", expr]` | Writes `expr` to the SharedArrayBuffer for
the main thread to poll, then resumes. |
| **Throw** | `["throw", expr]` | Halts execution or jumps to the nearest
`catch` block with the provided error. |
| **Try/Catch** | `["try", tryBody, "errVar", catchBody]`| Attempts `tryBody`.
On failure, binds the error to `errVar` and executes `catchBody`. |

---

### Transpilation Target Example (Fibonacci)
```json
[
  "do",
  [
    "def", "fib", ["n"],
    [
      "if", ["<", "n", 2],
      "n",
      ["+", ["fib", ["-", "n", 1]], ["fib", ["-", "n", 2]]]
    ]
  ],
  ["fib", 10]
]

EOF

With this standard locked in, building front-end AST generators (like
converting markdown trees or visual flow-based blocks into JSON-Lisp) will be
highly predictable. 

What is your primary goal for producing AST programs? Will you be writing a
higher-level syntax parser, or connecting it to a graphical AST editor?