novac 2.0.1 → 2.2.0

package/README.md

@@ -1,846 +1,1823 @@
-# Nova Language v2
+# novac Language Reference
 
-A scripting language built on JavaScript with expressive syntax, a static-ish type system, and unique features beyond JS.
+novac is a dynamic, expressive scripting language with a JavaScript-style syntax, a rich infix operator set, built-in event system, HTTP primitives, a Nova Classic layer, and a comprehensive standard library. Files use the `.nv` or `.nova` extension and are run with the `novac` CLI.
 
 ---
 
-## What's new in v2
-
-### Removed
-- Backtick `` ` `` template literals — replaced by **f-strings**
-
-### Added — JS parity fixes
-| Feature | Syntax |
-|---|---|
-| f-strings | `f"Hello {name}!"` |
-| Compound assignment | `+=  -=  *=  /=  %=  **=` |
-| Logical assign | `&&=  \|\|=  ??=` |
-| Nullish coalescing | `??` |
-| Optional chaining | `?.  ?.[  ?.(` |
-| Exponentiation | `**  **=` |
-| Spread / rest | `...arr`  `func f(...args)` |
-| Default parameters | `func f(x = 0)` |
-| Array destructuring | `let [a, b, c] = arr` |
-| Object destructuring | `let { x, y } = obj` |
-| Destructure defaults | `let { x = 5 } = obj` |
-| for-of | `for (let x of iterable)` |
-| for-in | `for (let k in obj)` |
-| Prefix ++ / -- | `++i` |
-| `typeof` | `typeof x` |
-| `void` | `void expr` |
-| `instanceof` | `x instanceof Cls` |
-| `in` | `"key" in obj` |
-| `break` / `continue` | inside any loop |
-| `switch` / `case` / `default` | JS-style with fall-through |
-| Ternary | `cond ? a : b` |
-| Bitwise ops | `&  \|  ^  ~  <<  >>  >>>` |
-| Range operator | `1..10` |
-| Pipe operator | `x \|> fn` |
-| Hex literals | `0xFF` |
-| Binary literals | `0b1010` |
-| Numeric separators | `1_000_000` |
-| Scientific notation | `1.5e3` |
-| Block comment | `/* ... */` |
-| Optional catch | `try { } catch { }` (no binding required) |
-| Computed property keys | `{ [expr]: val }` |
-| Getter/setter methods | `get prop() { }` / `set prop(v) { }` |
-| `new` expression | `new ClassName()` |
-| Keyword operators | `and  or  not` |
-| `as` cast | `x as int` |
-
-### Added — Nova-unique features
-| Feature | Syntax |
-|---|---|
-| `each` loop | `each x, i of arr { }` |
-| `match` expression | pattern matching, no fall-through |
-| `match` guards | `when val where cond { }` |
-| `emit` / `on` events | `emit "event", val` / `on "event"(v) { }` |
-| `where` block | scoped bindings `where(x=1, y=2) { }` |
-| `assert` | `assert cond, "message"` |
-| `give` | early-return alias |
-| `unless` | `unless (cond) { }` |
-| `until` | `until (cond) { }` |
-| `repeat` | `repeat (n) { }` |
-| **Custom types** | `type`, `struct`, `interface`, `enum`, `trait`, `impl` |
-| Preprocessor | `#define`, `#ifdef`, `#ifndef`, `#endif`, `#register`, `#inject` |
-| Pointer syntax | `let *p = val`, `*p = newVal` |
-| Currency units | `5 k` → 5000, `3 m` → 3000000 |
-| `__identifier indentifier__` | double-underscore identifier escaping that work just like strings but give out indents|
-| Runtime type registry | `typecheck(v, "int")`, `typeOf(v)`, `satisfies(v, "IFace")` |
+## Table of Contents
+
+1. [Comments](#comments)
+2. [Preprocessor Directives](#preprocessor-directives)
+3. [Literals & Values](#literals--values)
+4. [Variables & Smart Modifiers](#variables--smart-modifiers)
+5. [Types](#types)
+6. [Operators](#operators)
+7. [Strings & F-Strings](#strings--f-strings)
+8. [Control Flow](#control-flow)
+9. [Functions](#functions)
+10. [Classes](#classes)
+11. [Pattern Matching](#pattern-matching)
+12. [Events](#events)
+13. [Error Handling](#error-handling)
+14. [Modules & Namespaces](#modules--namespaces)
+15. [HTTP & Networking](#http--networking)
+16. [Nova Classic Features](#nova-classic-features)
+17. [Built-in Global Objects](#built-in-global-objects)
+18. [Built-in Class Objects](#built-in-class-objects)
+19. [Standard Library (std)](#standard-library-std)
+20. [Standard Built-ins (bstd / import_builtin)](#standard-builtins-bstd--import_builtin)
+21. [Array Methods](#array-methods)
+22. [Object Methods](#object-methods)
+23. [String Methods](#string-methods)
+24. [Type System & Casting](#type-system--casting)
+25. [Threads](#threads)
 
 ---
 
-## Type System
+## Comments
 
-### `type` — type aliases
 ```nova
-type ID = int
-type Name = string
-type Numeric = int | float
-let x: int = 42;
+// single-line comment
+/! also a single-line comment
+/* multi-line block comment */
+
+/?/ core.print("executed at lex time")  // executable comment — runs during lexing
 ```
 
-### `struct` — typed value objects
+---
+
+## Preprocessor Directives
+
 ```nova
-struct Point {
-  x: int = 0,
-  y: int = 0
+#define NAME value       // substitution macro (NAME replaced everywhere in source)
+#define FLAG             // valueless flag (for ifdef/ifndef)
+#undef NAME             // remove a macro
+#ifdef FLAG             // include following block only if FLAG is defined
+#ifndef FLAG            // include following block only if FLAG is NOT defined
+#endif                  // close an ifdef/ifndef block
+#register operator NAME {"precedence":N, "isUnary":bool}
+#inject <json-token>    // inject a raw token into the token stream
+```
+
+---
+
+## Literals & Values
+
+### Numbers
+
+| Form | Example | Notes |
+|------|---------|-------|
+| Decimal | `42`, `3.14` | Standard |
+| Separator | `1_000_000` | Underscores ignored |
+| Hex | `0xFF` | Case insensitive |
+| Binary | `0b1010` | Case insensitive |
+| Custom base | `0r16FF` | `0r<base><digits>`, base 2–36 |
+| Holland/scale | `0hbillion`, `0hmega` | Named SI / large-number literals |
+| BigInt | `42n` | Suffix `n` |
+| Scientific | `1e6`, `2.5E-3` | Standard scientific |
+| Short suffix | `10k`, `2m`, `1b`, `4t` | k=1e3, m=1e6, b=1e9, t=1e12 |
+
+**Holland scale literals** — `0h` prefix:
+
+| Name | Value | Name | Value |
+|------|-------|------|-------|
+| `kilo` | 1e3 | `milli` | 1e-3 |
+| `mega` | 1e6 | `micro` | 1e-6 |
+| `giga` | 1e9 | `nano` | 1e-9 |
+| `tera` | 1e12 | `pico` | 1e-12 |
+| `million` | 1e6 | `femto` | 1e-15 |
+| `billion` | 1e9 | `atto` | 1e-18 |
+| `trillion` | 1e12 | `googol` | 1e100 |
+| `quadrillion` | 1e15 | | |
+| `quintillion` | 1e18 | | |
+
+### Special Literals
+
+| Token | Value |
+|-------|-------|
+| `true` | boolean true |
+| `false` | boolean false |
+| `null` | null |
+| `nstr` | `""` (empty string) |
+| `nfunc` | A function that returns null |
+
+### URL Literals
+
+Tokens beginning with a recognized scheme are URL literals:
+
+```nova
+let url = https://api.example.com/users
+let local = localhost:3000
+// Recognized: http, https, ftp, ws, wss, content, localhost:<port>
+```
+
+### Arrays
+
+```nova
+let arr = [1, 2, 3]
+let spread = [...arr, 4, 5]
+```
+
+### Objects
+
+```nova
+let obj = { x: 1, 'y': 2 }
+let method = { greet() { give "hi"; } }
+let overload = { 
+  [op]: { 
+    unary: { '~': () => 17 }
+    binary: { '+': (a) => a*10  }
+  }
 }
+core.print(~obj + obj); // ~obj becomes 17, now 17 + obj becomes 17*10 which is 170.
+let computed = { ["key" + idx]: value }
+let withSpread = { ...obj, z: 3 }
+let getset = {
+  get prop() { give this._val; },
+  set prop(v) { this._val = v; }
+}
+let presence = { active? true }   // boolean-constrained property: must be true or false
+```
 
-let p = Point({ x: 3, y: 4 });
-core.print(p.x);           // 3
-core.print(typeOf(p));     // struct:Point
-core.print(p instanceof Point); // true
+---
+
+## Variables & Smart Modifiers
+
+```nova
+var x = 10      // mutable, function-scoped
+let y = 20      // mutable, block-scoped
+const Z = 30    // immutable binding/
+// special __...__ identifiers:
+let __my cool variable++-__ = 19; // when novac sees __, it collects everything until __ as the var name and gives an identifier token type, so you can even name a variable __26__ and the token with be { type: 'IDENTIFIER', value: '26' }
 ```
 
-### `enum` — discriminated unions
+### Destructuring
+
 ```nova
-enum Direction { North, South, East, West }
-enum Color { Rgb(int, int, int), Hex(string) }
+let { a, b } = obj
+let { a: renamed, b: other = "default" } = obj
+let [first, second] = arr
+let [head, ...tail] = arr
+```
 
-let d = Direction.North;
-core.print(d.__variant__);   // North
+### Smart Variable Modifiers
 
-let c = Color.Rgb(255, 0, 128);
-core.print(c.values);        // [255, 0, 128]
+Placed between the variable name and `=`:
+
+| Modifier | Effect |
+|----------|--------|
+| `frozen` | Throws on any reassignment after first set |
+| `lazy` | Expression evaluated only on first read |
+| `tracked` | `console.log`s every assignment change |
+| `nonull` | Throws if assigned `null` or `undefined` |
+| `once` | Can only be set once; further assigns silently ignored |
+| `setter <fn>` | Calls `fn(newVal, oldVal)` on every assignment; if fn returns non-undefined, that becomes the stored value |
+| `getter <fn>` | Calls `fn()` on every read |
+| `as fnum [min, max]` | Clamps to float range on every assign |
+| `as fint [min, max]` | Clamps to integer range (`Math.trunc`) on every assign |
+
+```nova
+let x frozen = 5
+let y lazy = computeHeavy()
+let z tracked = 0
+let n nonull = getValue()
+let once_val once = initialize()
+let watched setter mySetFn = 0
+let computed getter myGetFn = 0
+let clamped as fnum [0.0, 1.0] = 0.5
+let bounded as fint [0, 255] = 128
+```
+
+### Links and $-notations
+```nova
+let obj = { test: { example: 29 } };
+let link2example = link(obj.test.example); // link is not a function, its a special keyword function
+link2example = 3; // example is also set
+obj.test.example; // 3
+obj.test.example = 2;
+link2example; // 2
+// you can also directly set a link call:
+link(obj.test.example) = 1; // works
+// nest links:
+link(link2example) = 3; // now obj.test.example is also 3
 ```
 
-### `interface` — structural contracts
 ```nova
-interface Drawable {
-  draw()
-  color: string
+// $ notation:
+// when used as a normal call:
+$29; // noop, just 29
+${a: 6 + 3}; // noop again, just the object
+// real magic in $ assingments:
+$"hi" = 29; // sets variable hi
+$26 = 1; // set variable 26, even tho you can't just read from a var directly called 26, you can still use __26__ to read (novac trims __...__ and just leaves an ident with value ...)
+```
+
+### Type Annotation
+
+```nova
+let count: int = 0
+let name: string = "Nova"
+func add(a: int, b: int): int => { give a + b }
+```
+
+### Pointer Declaration & Dereference
+
+```nova
+var *ptr = someValue
+let result = *ptr     // dereference
+*ptr = newValue       // assign through pointer
+```
+
+---
+
+## Types
+
+### Type Alias
+
+```nova
+type ID = string
+type Status = "active" | "inactive" | "pending"
+type Point = { x: int, y: int }
+type Result<T> = T | null
+```
+
+### Struct
+
+```nova
+struct Vec2 {
+  x: int = 0,
+  y: int = 0
 }
+let v = Vec2({ x: 3, y: 4 })
+v.x   // 3
+```
+
+### Interface
 
-let obj = { draw() { core.print("drawn"); }, color: "red" };
-core.print(satisfies(obj, "Drawable"));   // true
+```nova
+interface Serializable {
+  serialize(): string
+  deserialize(data: string): bool
+  name?: string               // optional member
+}
+interface Extended extends Serializable, Printable { }
 ```
 
-### `trait` + `impl` — behaviour contracts
+### Enum
+
 ```nova
-trait Printable {
-  print() { core.print(this.toString()); }
+enum Status { Active, Inactive, Pending }
+enum Shape {
+  Circle(int),
+  Rect(int, int),
+  Point = 0
 }
+let s = Status.Active
+s.__variant__         // "Active"
+s.__enum_type__       // "Status"
+```
+
+### Trait & Impl
 
-impl Printable of Point { }
+```nova
+trait Drawable {
+  draw(ctx) { }
+}
+impl Drawable of Circle {
+  draw(ctx) { ctx.circle(this.x, this.y, this.r); }
+}
+// Also: impl Drawable for Circle { }
 ```
 
+### Type Expressions
+
+```nova
+string | null               // union
+int & Serializable          // intersection
+string[]                    // array type
+{ name: string, age?: int } // inline shape type
+Map<string, int>            // generic
+```
+
+---
+
+## Operators
+
+### Arithmetic
+
+| Op | Meaning |
+|----|---------|
+| `+` `-` `*` `/` `%` | Standard arithmetic |
+| `**` | Exponentiation (right-associative) |
+| `++` `--` | Increment / decrement (prefix or postfix) |
+
+### Assignment
+
+| Op | Meaning |
+|----|---------|
+| `=` | Assign |
+| `+=` `-=` `*=` `/=` `%=` `**=` | Compound assign |
+| `&&=` | Logical-AND assign |
+| `\|\|=` | Assign if current is null/undefined |
+| `??=` | Nullish-coalesce assign |
+
+### Comparison
+
+| Op | Meaning |
+|----|---------|
+| `==` `!=` | Loose equality |
+| `===` `!==` | Strict equality |
+| `<` `>` `<=` `>=` | Relational |
+| `is` | Strict equality alias |
+| `isnt` | Non-identity alias |
+| `equals` | `===` alias |
+| `equals_ignore` | Case-insensitive string equality |
+| `cmp` | `localeCompare` — returns -1/0/1 |
+
+### Logical
+
+| Op | Meaning |
+|----|---------|
+| `&&` / `and` | Logical AND |
+| `\|\|` / `or` | Logical OR |
+| `!` / `not` | Logical NOT (unary) |
+| `??` | Nullish coalesce |
+| `xor` | Exclusive OR |
+| `nand` | NOT AND |
+| `nor` | NOT OR |
+| `xnor` | Exclusive NOR |
+
+### Bitwise
+
+| Op | Meaning |
+|----|---------|
+| `&` `\|` `^` `~` | Bitwise AND / OR / XOR / NOT |
+| `<<` `>>` `>>>` | Left / right / unsigned right shift |
+
+### Type & Predicate
+
+| Op | Meaning |
+|----|---------|
+| `typeof` | Returns type string (unary) |
+| `instanceof` | Instance check |
+| `in` | Membership / range containment |
+| `istypeof` | `typeOf(left) === right` |
+| `matches` | Regex test of left string against right |
+| `between` | `left > arr[0] && left < arr[1]` |
+
+### Special / Flow
+
+| Op | Meaning |
+|----|---------|
+| `\|>` | Pipe: `x \|> f` → `f(x)` |
+| `=>` | Arrow function body |
+| `..` | Inclusive range: `1..10` → `NovaRange(1,10)` |
+| `...` (unary) | Spread / rest |
+| `...` (binary) | Exclusive range: `1...10` → array `[1..9]` |
+| `?.` | Optional chain — null if left is null |
+| `?` | Ternary start |
+| `::` | Namespace / property access |
+| `>>` | Pipe-right: `val >> fn` → `fn(val)`; also used in `compose` / `engage` |
+| `delete` | Delete variable, property, or subscript |
+| `void` | Evaluate and return undefined |
+| `#` | Size of right operand (array/object/string length) |
+
+### Array / Collection Infix
+
+| Op | Meaning |
+|----|---------|
+| `intersect` | Elements in both arrays |
+| `union` | Deduplicated merge |
+| `diff_arr` | Elements in left not in right |
+| `zip` | `[[a0,b0],[a1,b1],...]` |
+| `extend` | Merge objects / concatenate arrays |
+| `concat` | Concatenate |
+| `index` | `arr index 2` → element at 2 |
+| `step` | `0..10 step 2` → `[0,2,4,6,8,10]` |
+
+### Numeric Infix
+
+| Op | Meaning |
+|----|---------|
+| `avg` | `(a + b) / 2` |
+| `diff` | `Math.abs(a - b)` |
+| `ratio` | `a / b` |
+| `mult_of` | `a % b === 0` |
+| `gcd` | Greatest common divisor |
+| `lcm` | Least common multiple |
+| `pow` | Alias for `**` |
+| `bigger` / `smaller` | `a > b` / `a < b` aliases |
+
+### String Infix
+
+| Op | Meaning |
+|----|---------|
+| `pad_start` | `.padStart(right, ' ')` |
+| `pad_end` | `.padEnd(right, ' ')` |
+
+### Operator Precedence (highest → lowest)
+
+| Prec | Operators |
+|------|-----------|
+| 15 | `++` `--` (postfix), `?.`, `::`, `#:`, `$:`, `index` |
+| 14 | Unary: `!` `~` `-` `+` `*` `...` `not` `typeof` `void` `delete` |
+| 13 | `**` `pow` (right-assoc) |
+| 12 | `*` `/` `%` `ratio` `mult_of` `gcd` `lcm` |
+| 11 | `+` `-` `avg` `diff` `pad_start` `pad_end` `concat` |
+| 10 | `>>` `<<` `>>>` `..` `step` `zip` |
+| 9 | `<` `>` `<=` `>=` `bigger` `smaller` |
+| 8 | `==` `!=` `===` `!==` `is` `isnt` `equals` `equals_ignore` `cmp` `istypeof` `matches` `instanceof` `in` |
+| 7 | `&` `intersect` `diff_arr` |
+| 6 | `^` |
+| 5 | `\|` `union` `extend` |
+| 4 | `&&` `and` `nand` |
+| 3 | `??` `xor` `xnor` |
+| 2 | `\|\|` `or` `nor` |
+| 0 | `=` `+=` `-=` `*=` `/=` `%=` `**=` `&&=` `\|\|=` `??=` `=>` `\|>` |
+
 ---
 
-## Syntax Reference
+## Strings & F-Strings
 
-### Variables
 ```nova
-let x = 10;
-const PI = 3.14;
-var y = "hello";
-let n: int = 5;           // typed
-let *ptr = someVal;       // pointer
+let a = "hello"
+let b = 'world'
+// Escape sequences: \n \t \r \\ \' \"...etc
+
+// F-strings: f"..." with {} interpolation — any expression allowed
+let msg = f"\color{blue}Hello {name}!\reset"
+let math = f"2^10 = {2 ** 10}"
+let complex = f"items: {arr.map(x => x * 2).join(', ')}"
 ```
 
-### Functions
+---
+
+## Control Flow
+
+### If / Else
+
 ```nova
-func add(a, b) => { give a + b; }
-func greet(name = "World") => { core.print(f"Hi {name}!"); }
-func sum(...nums) => { give nums.reduce((a,x) => a+x, 0); }
+if (cond) { } else if (other) { } else { }
+
+let x = a > b ? a : b                // ternary
+let y = value if condition else alt   // postfix if-expression
+```
+
+### Unless / Until / Repeat
 
-let double = x => x * 2;
-let add5 = (x) => x + 5;
+```nova
+unless (cond) { }    // runs when cond is false
+until (cond) { }     // runs while cond is false
+repeat (n) { }       // runs exactly n times
 ```
 
-### Strings
+### While / Do-While
+
 ```nova
-let name = "Nova";
-let msg = f"Hello {name}, 2+2={2+2}";
+while (cond) { }
+do { } while (cond)
 ```
 
-### Control flow
+### For
+
 ```nova
-if (x > 0) { ... } else { ... }
-unless (x == 0) { ... }
-while (cond) { ... }
-until (done) { ... }
-do { ... } while (cond);
-repeat (5) { ... }
-for (let i = 0; i < 10; i++) { ... }
-for (let x of array) { ... }
-for (let k in obj) { ... }
-each val, idx of array { ... }
+for (let i = 0; i < 10; i++) { }
+for (let item of array) { }
+for (let key in object) { }
 ```
 
-### Pattern matching
+### Each
+
 ```nova
-match (value) {
-  when 0        { core.print("zero"); }
-  when 1, 2, 3  { core.print("small"); }
-  when 4..10    { core.print("range"); }      // range pattern!
-  when x where x > 100 { core.print("big"); } // guarded
-  default       { core.print("other"); }
-}
+each item of array { }
+each item, index of array { }
 ```
 
-### Classes
+### Switch / Case
+
 ```nova
-class Animal {
-  sound: "..."
-  speak() { core.print(f"I say {this.sound}"); }
-  get label() { give this.sound; }
+switch (value) {
+  case 1: core.print("one"); break;
+  default: core.print("other"); break;
 }
+```
 
-class Dog extends Animal {
-  sound: "Woof"
-}
+### Match
 
-let d = Dog();
-d.speak();           // I say Woof
-core.print(d.label); // Woof
+```nova
+match (value) {
+  when 1            { }
+  when 2, 3         { }              // comma = multi-pattern
+  when 1..10        { }              // range
+  when "ok" where cond { }          // with guard
+  default           { }
+}
 ```
 
-### Pipe operator
+### Loop Control
+
+| Keyword | Effect |
+|---------|--------|
+| `break` | Exit loop |
+| `continue` | Next iteration |
+| `skip` | Alias for `continue` (parsed as `skip`, no-op in execute) |
+| `goback` | Throw `{ __return: scope.__return }` — return from function |
+| `end` | Throw `{ __return: undefined }` — terminate scope |
+
+### Guard
+
 ```nova
-func double(x) => { give x * 2; }
-func addOne(x) => { give x + 1; }
+guard (cond) {
+  // body runs only when cond is TRUE (passes through)
+} else {
+  // runs when cond is FALSE
+}
+```
+
+### When
 
-let result = 5 |> double |> addOne;  // 11
+```nova
+when cond do { }     // runs body once if cond is truthy
+when cond then { }   // same
 ```
 
-### Ranges
+### Where (scoped bindings)
+
 ```nova
-for (let i of 1..10) { core.print(i); }
-core.print(5 in 1..10);   // true
-let arr = (1..5).toArray ? [1,2,3,4,5];
+where (base = 100, rate = 0.15) {
+  let tax = base * rate
+}
 ```
 
-### Events
+### With
+
 ```nova
-on "userLogin" (user) {
-  core.print(f"Welcome {user}");
+with (object) {
+  // object properties brought into scope
+}
+with option featureFlag {
+  // body runs with flag set; removed after block
 }
+```
 
-emit "userLogin", "Alice";
+### Loop (Classic iteration)
+
+```nova
+loop item in iterable { }
 ```
 
-### `where` scoping
+### Foreach (Classic key-value)
+
 ```nova
-where (x = compute(), y = transform()) {
-  core.print(x + y);
-}
-// x, y not accessible here
+foreach(collection)(key, value) { }
+foreach(collection)(key, value, length) { }   // third var = total length
 ```
 
-### Preprocessor
+### Wait (sync sleep)
+
 ```nova
-#define DEBUG
-#define MAX_SIZE 100
+wait(1000)   // blocks for 1000ms (Atomics.wait, fallback: child process)
+```
 
-#ifdef DEBUG
-  core.print("debug mode");
-#endif
+### Time Block
 
-#define DOUBLE(x) x * 2
+```nova
+time {
+  // times this block; prints elapsed ms on completion
+}
 ```
 
 ---
 
-## Built-in Array Methods
+## Functions
 
-`map`, `filter`, `reduce`, `find`, `findIndex`, `some`, `every`,
-`flat`, `flatMap`, `sort`, `reverse`, `slice`, `splice`,
-`indexOf`, `includes`, `join`, `push`, `pop`, `shift`, `unshift`,
-`concat`, `fill`, `forEach`, `keys`, `values`, `entries`, `at`
+### Named Functions
 
-## Built-in stdlib (`std.*`)
+```nova
+func add(a, b) => {
+  give a + b
+}
+function greet(name) {
+  return f"Hello {name}"
+}
+```
 
-`Math`, `Array`, `Object`, `String`, `is`, `num`, `str`, `bool`,
-`int`, `console`, `Date`, `json`, `Promise`, `fn`, `range`, `error`
+### Function Modifiers
 
----
+Modifiers come **after** `func`/`function` and **before** the function name. Multiple modifiers can be chained in any order.
+
+| Modifier | Effect |
+|----------|--------|
+| `async` | Marks async; `await` blocks synchronously via `SharedArrayBuffer` |
+| `Strict` | Throws if argument count doesn't match exactly |
+| `once` | Body only runs once; later calls return the first result |
+| `memo` | Results memoized by `JSON.stringify(args)` key |
+| `generator` | Returns an iterator; `yield` inside collects values |
+| `timeout <expr>` | Throws if function exceeds `expr` ms |
+| `defer <stmt>` | Executes `stmt` when function returns (in `finally`) |
+
+```nova
+func async load(url) => { }
+func Strict strict(a, b) => { }
+func once init() => { }
+func memo fib(n) => { }
+func generator counter() => { }
+func async memo cachedFetch(url) => { }
+func timeout 5000 riskyOp() => { }
+func defer cleanup() riskyOp() => { }
+
+// function keyword works identically
+function async load(url) { }
+function Strict strict(a, b) { }
+```
+
+in objects, you can have a [expr] quick access method that runs on 
+obj.(...args)
+example:
+```nova
+let obj = { [expr]: (a, b) => return a + b  }
+core.print(obj.(1,5)); // 6
+```
+
+### Generator Iterator API
+
+| Method | Description |
+|--------|-------------|
+| `.next()` | `{ value, done }` |
+| `.last()` | Step back one |
+| `.current()` | Peek without advancing |
+| `.seek(n)` | Jump to index n |
+| `.setIndex(n)` | Set position |
+| `.currentIndex()` | Current index |
+| `.length()` | Total collected values |
+| `.at(n)` | Value at index n |
+| `[Symbol.iterator]` | Makes it iterable in `for-of` |
+
+### Return / Give / Goback
 
-## HTTP & Server
+```nova
+return value   // sets __return, does NOT terminate
+give value     // alias — same as return, but terminates the function by throwing
+goback         // throws { __return: scope.__return }
+yield value    // collects into generator's output array
+```
 
-Nova has first-class HTTP support built in. URLs are native tokens and HTTP verbs are keywords.
+### Arrow Functions
 
-### First-class URL literals
+```nova
+let double = x => x * 2
+let add = (a, b) => a + b
+```
+
+### Rest & Default Parameters
+
+```nova
+func sum(...nums) => { give nums.reduce((a, b) => a + b, 0) }
+func greet(name = "World") => { }
+```
 
+### Block functions:
+these auto call on reference, and use the returned value
 ```nova
-let api = https://api.example.com/users;
-core.print(api);  // https://api.example.com/users
+block coolBlock { core.print(8); return 8;  }
+core.print(coolBlock); /* result:
+8 //from inside coolBlock
+8 //from core.print(coolBlock);
+*/
+// you can also just run the block using nova.runBlock('coolBlock')
 ```
 
-### HTTP method expressions
+### Run bounder:
+```nova
+// run CODE
+// or
+// run { ... }
+// example:
+core.print(run let x = 10); //10 because run uses last result if no return/give
+core.print(x); // 10
+core.print(run { let c = 8; return c; }); // 8
+core.print(c); // 8
+
+```
 
-Any HTTP verb followed by a URL (or string path) acts like a function call.
-Optional `(body, headers)` args are passed as the request body and headers.
+### Pipe Operator
 
 ```nova
-// GET
-let todos = get https://jsonplaceholder.typicode.com/todos/1();
-core.print(todos.status);   // 200
-core.print(todos.ok);       // true
-core.print(todos.body.title);
+let result = 5 |> double |> addOne
+```
 
-// POST with body
-let created = post https://api.example.com/users({ name: "Alice", age: 30 });
+---
 
-// PUT / PATCH
-let updated = put https://api.example.com/users/1({ name: "Bob" });
-let patched = patch https://api.example.com/users/1({ age: 31 });
+## Classes
 
-// DELETE
-let removed = delete https://api.example.com/users/1();
+```nova
+class Animal {
+  name: "unknown"
+  speak() { core.print(f"{this.name} speaks") }
+}
+class Dog extends Animal {
+  breed: "mixed"
+  speak() { core.print(f"{this.name} barks") }
+}
+class Doc implements Serializable {
+  // must satisfy all non-optional interface members
+}
+```
+
+### Getter / Setter
 
-// HEAD / OPTIONS
-let info = head https://api.example.com();
+```nova
+class Box {
+  _val: 0
+  get value()  { give this._val; }
+  set value(v) { this._val = v; }
+}
 ```
 
-### `fetch()` — sync fetch
+### Decorators
 
 ```nova
-// As expression
-let data = fetch("https://api.example.com/items");
-core.print(data.body);
+@logged
+@deprecated("use newFn")
+class OldClass {
+  @readonly
+  name: "old"
+}
+```
 
-// As statement with => binding
-fetch("https://api.example.com/items") => items;
+---
+
+## Pattern Matching
 
-// With options
-let resp = fetch("https://api.example.com/items", {
-  method: "POST",
-  headers: { "Authorization": "Bearer token" },
-  body: { name: "Nova" }
-});
+```nova
+match (value) {
+  when 90..100           { }   // range — uses NovaRange.includes()
+  when "ok"              { }   // scalar — uses ==
+  when 1, 2, 3           { }   // any of these — comma-separated
+  when x where x > 0    { }   // with guard expression
+  default                { }
+}
 ```
 
-All `fetch` / HTTP method calls return a response object:
+---
+
+## Events
+
 ```nova
-resp.ok      // bool — true if status 200-299
-resp.status  // int  — HTTP status code
-resp.body    // parsed JSON or raw string
-resp.text    // raw response text
+emit "eventName"
+emit "eventName", payload
+
+on "eventName" (data) {
+  core.print(data)
+}
+
+// Internal: fires on every statement execution step
+on "nv:tick" () { }
 ```
 
-### `server(port)` — HTTP server
+---
+
+## Error Handling
 
 ```nova
-server(3000) {
-  get "/users"(req, res) {
-    return [{ id: 1, name: "Alice" }];
-  }
+try {
+  riskyOp()
+} catch (err) {
+  core.print(f"caught: {err}")
+} finally {
+  cleanup()
+}
 
-  post "/users"(req, res) {
-    let body = req.body;
-    return { created: true, name: body.name };
-  }
+try { riskyOp() } catch { }   // no binding — catch without name
 
-  put "/users/:id"(req, res) {
-    return { updated: req.params.id };
-  }
+throw "plain string"
+throw new Error("typed")
 
-  delete "/users/:id"(req) {
-    return { deleted: req.params.id };
-  }
+assert condition
+assert condition, "failure message"
 
-  get "*"(req, res) {
-    res.status(404);
-    return { error: "Not found" };
-  }
+expt "expectedOutput" from {
+  core.print("expectedOutput")
 }
 ```
 
-**Request object (`req`)**
-| Property | Description |
-|---|---|
-| `req.method` | HTTP method string |
-| `req.url` | Full URL including query string |
-| `req.path` | Pathname only |
-| `req.params` | Object of `:param` captures |
-| `req.query` | Object of `?key=value` pairs |
-| `req.headers` | Request headers |
-| `req.body` | Parsed JSON body |
+---
 
-**Response object (`res`)**
-| Method | Description |
-|---|---|
-| `res.status(code)` | Set status code (chainable) |
-| `res.json(data)` | Send JSON response |
-| `res.send(text)` | Send plain text |
+## Modules & Namespaces
 
-Returning a value from a route handler automatically sends it as JSON.
+### Import
 
-### Calling a local server from the same script
+```nova
+import "path/to/module"
+import "path/to/module" as alias
+import "path/to/module" as name1, name2
+from "module" import func1, func2
+import_builtin Air, Chalk, Input, Shema
+```
+
+### Export
+
+```nova
+export myValue
+export { name = value, other = value2 }
+default myMainExport
+```
 
-This works without deadlocking — Nova detects local server ports and dispatches requests in-process:
+### Namespace
 
 ```nova
-server(4000) {
-  get "/hello"(req) { return { msg: "hi" }; }
+namespace Math {
+  func add(a, b) => { give a + b }
 }
+Math::add(1, 2)
+using namespace Math   // bring all members into scope
+```
+
+### Using / Unuse
 
-let r = get http://localhost:4000/hello();
-core.print(r.body.msg);  // hi
+```nova
+using featureFlag
+using namespace MyNS
+unuse featureFlag
 ```
 
-### Platform support for `fetch`
+### Environment Variable
 
-Nova's sync HTTP works on every platform — it tries strategies in order:
-1. **In-process dispatch** for local Nova servers (no network needed)
-2. **curl** — available on Unix/Mac and Windows 10+ (build 17063)
-3. **PowerShell** `Invoke-WebRequest` — Windows fallback
-4. **Node.js built-in** `http`/`https` — universal last resort (always available)
+```nova
+env VAR_NAME   // reads process.env.VAR_NAME; throws if undefined
+```
 
 ---
 
-## Running Nova
+## HTTP & Networking
 
+### First-Class HTTP Verbs
 
-```bash
-# Run a file
-novac script.nv
+```nova
+get https://api.example.com/users
+post https://api.example.com/users({ name: "novac" })
+put  https://api.example.com/users/1({ name: "Updated" })
+delete https://api.example.com/users/1()
+patch  https://api.example.com/users/1({ active: false })
+head   https://api.example.com/health
+options https://api.example.com/
+// Returns: { ok: bool, status: int, body: object|string, text: string }
+```
+
+**Sync fetch strategies (tried in order):** in-process local Nova server dispatch → curl → PowerShell (Windows) → Node child process.
 
-# REPL
-novac repl
+### Fetch
 
-# Evaluate inline
-novac eval 'core.print("hello")'
+```nova
+fetch(url)
+fetch(url, { method: "POST", headers: { Authorization: "Bearer x" }, body: payload })
+fetch(url, opts) => resultVar   // statement form — assigns result
 ```
 
+### Server Declaration
 
----
+```nova
+server(3000) {
+  get "/api/users" (req, res) {
+    res.json([])
+  }
+  post "/api/users" (req, res) {
+    res.json({ created: true, body: req.body })
+  }
+  delete "/api/users/:id" (req, res) {
+    res.json({ deleted: req.params.id })
+  }
+}
+// req: { method, url, path, headers, body, params, query }
+// res: .status(code) .header(k,v) .json(data) .send(data)
+// :param values also bound directly into route scope
+// If res.json/send never called, route handler's return value is auto-sent
+```
 
-## Nova Classic Features (from legacy implementation)
+---
 
-These features were ported from the original Nova interpreter.
+## @classic — Classic Compatibility Block
 
-### Iteration
+Classic novac keywords are **only valid inside an `@classic { }` block**. Outside of one they are plain identifiers and cause a parse error if used as statements. This keeps the core language surface area clean while preserving full backward compatibility for legacy code.
 
 ```nova
-// foreach — iterate object keys/values with custom vars
-foreach (myObj)(key, value) {
-  core.print(f"{key} = {value}");
+@classic {
+  // any classic keyword works in here
+  echo "hello"
+  keep port = 8080
+  gear(500) poll {
+    let data = fetch(https://api.example.com/data)
+    echo data.body
+  }
+  engage poll
 }
 ```
 
-### Scoped Bindings
+If you use a Classic keyword outside `@classic`, the parser throws:
+
+```
+ClassicError: 'echo' is a Classic novac keyword and must be used inside an @classic { } block.
+Wrap your legacy code: @classic { echo ... }
+```
+
+`@classic` blocks can appear anywhere a statement is valid — top-level, inside functions, inside `if` bodies, etc. They share the same scope as their surroundings.
 
 ```nova
-// temp — bind a variable only for a block
-let env = "production";
-temp env = "test" => {
-  core.print(env);  // test
+func migrate() => {
+  @classic {
+    backup session = currentSession
+    temp session = "migration" => {
+      runMigration()
+    }
+    retrieve session
+  }
 }
-core.print(env);    // production
+```
 
-// keep — set-once (won't overwrite if already set)
-keep port = 8080;
-keep port = 9999;  // ignored
-core.print(port);  // 8080
+### Classic Keywords (only valid inside `@classic { }`)
+
+**Output:**
+
+| Keyword | Behavior |
+|---------|----------|
+| `echo value` | `process.stdout.write(String(value))` — no newline |
+| `print(val, ...)` | Space-joined args + newline |
+| `println(value)` | `process.stdout.write(value)` — no newline |
+| `log(val, ...)` | `console.log(...args)` |
+| `logln(value)` | `process.stdout.write(value)` |
+| `warn "msg"` | `"Warning: msg\n"` |
+| `info "msg"` | `"INFO: msg\n"` |
+| `hello` | Prints `"Hello, !"` |
+| `hello "a", "b"` | Prints `"Hello, a, and b!"` |
+| `banner "text"` | Box-drawn ASCII banner |
+
+**Scoped Binding:**
+
+| Keyword | Behavior |
+|---------|----------|
+| `temp x = val => { }` | Override x for the block duration, then restore |
+| `keep x = val` | Set x only if currently null/undefined; silent otherwise |
+
+**Macros & Named Code:**
+
+| Keyword | Behavior |
+|---------|----------|
+| `macro NAME = val` | Store value in `nova.macros` and scope |
+| `snippet name { }` | Register named snippet; run with `nova.runSnippet("name")` |
+| `defunc name(args) => { }` | Declare function (arrow-body style) |
+| `lambda name = x => expr` | Declare arrow function |
+| `compose name = f >> g` | Compose functions left-to-right: `g(f(x))` |
+| `partial name = fn(arg)` | Partial application |
+
+**Iteration:**
+
+| Keyword | Behavior |
+|---------|----------|
+| `loop item in iterable { }` | For-of style |
+| `foreach(col)(key, val) { }` | Key-value iteration |
+| `foreach(col)(key, val, len) { }` | With length variable |
+
+**State:**
+
+| Keyword | Behavior |
+|---------|----------|
+| `backup x = x` | Save value to executor backup store |
+| `retrieve x` | Restore from backup store |
+| `addto arr val` | Push value to array |
+| `addto map val : key` | Set `map[key] = val` |
+
+**Async Tasks:**
+
+| Keyword | Behavior |
+|---------|----------|
+| `gear(ms) name { }` | Named loop task; waits `ms` between iterations |
+| `gear name { }` | Named loop task; no wait |
+| `engage a >> b` | Run gears left-to-right in continuous loop until `break` |
+
+**Isolation:**
+
+| Keyword | Behavior |
+|---------|----------|
+| `sandbox { }` | Run in isolated Node.js vm context; scope vars snapshotted in/out |
+| `infer ("model") => var: "prompt"` | Run local AI model via `ollama` |
+
+**Data:**
+
+| Keyword | Behavior |
+|---------|----------|
+| `sstream name => { put val }` | Named sync stream with `put` accumulator |
+| `lend fn src to dst` | Merge `src` function body into `dst` |
+| `lend m map with fn` | Attach `fn` as method on `map` object |
+
+**Session / Resumable:**
+
+| Keyword | Behavior |
+|---------|----------|
+| `session("name") { }` | Store named session body |
+| `enter key type` | Log `[enter] key type` — interactive entry point marker |
+| `resu name(args) => { },` | Resumable: re-parsed and run fresh on each call |
+| `keyfunc name(x) { } { }` | Pattern-matched function dispatch |
+
+**Annotation / Registry:**
+
+| Keyword | Behavior |
+|---------|----------|
+| `describe "text"` | Append to `nova.descriptions` |
+| `using flagName` | Set `this.options[flag] = true` |
+| `unuse flagName` | Delete `this.options[flag]` |
+| `using namespace MyNS` | Bring all namespace members into scope |
+
+**Type Ops:**
+
+| Keyword | Behavior |
+|---------|----------|
+| `classify value` | Print/return type string |
+| `classify value as Type` | Return bool |
+| `rate(v) type` | Type-cast (see full table in Type System section) |
+
+**Control:**
+
+| Keyword | Behavior |
+|---------|----------|
+| `skip` | No-op (parsed, returns undefined) |
+| `end` | Terminate current scope: throws `{ __return: undefined }` |
+| `clear` | Reset `nova.descriptions` to `[]` |
+| `time { }` | Time a block; print elapsed ms |
+| `wait(ms)` | Sync sleep via Atomics.wait |
+
+**Misc:**
+
+| Keyword | Behavior |
+|---------|----------|
+| `expt "val" from { }` | Capture stdout; error if `actual.trim() !== "val"` |
+| `option name = fn` | Set runtime option/hook |
+| `env VAR` | Read `process.env.VAR` into scope; throws if undefined |
+| `eval expr` | Re-evaluate an already-parsed AST node |
+| `declare (expr) as x` | Assign to `x` |
+| `declare (expr) into x` | Append string to `x` |
+| `declare (expr) as x log` | Assign and print |
+| `declare (expr) as x throw` | Assign and throw |
+| `declare (expr) as x finalize` | Assign and `return` |
+
+
+## Built-in Global Objects
+
+Always in scope — no import needed.
+
+### `core`
+
+| Member | Description |
+|--------|-------------|
+| `core.print(v)` | `process.stdout.write(stringify(v) + '\n')` |
+| `core.json` | Reference to `JSON` |
+| `core.getAst()` | Returns current program AST |
+| `core.vars` | Reference to global scope variables |
+| `core.types` | Reference to the TypeRegistry |
+| `core.register(fn)` | Wraps a novac function as a native callable |
+| `core.import` | Module import function |
+| `core.ndb()` | Dev bridge: `{ exe, scopes, types, eventBus, gears, backups, macros, blocks, snippets, keyfuncs, sessions, resus, namespaces }` |
+
+### `nova` (Unified Registry)
+
+Live proxy over all internal registries:
+
+| Member | Description |
+|--------|-------------|
+| `nova.version` | `"2.0"` |
+| `nova.macros` | All defined macros |
+| `nova.blocks` | All defined blocks |
+| `nova.snippets` | All defined snippets |
+| `nova.gears` | All defined gears |
+| `nova.sessions` | All defined sessions |
+| `nova.resus` | All defined resus |
+| `nova.keyfuncs` | All defined keyfuncs |
+| `nova.backups` | All backed-up values |
+| `nova.options` | Current option flags |
+| `nova.descriptions` | Array of all `describe` annotations |
+| `nova.scope` | Reference to global scope |
+| `nova.types.structs` | Registered struct names |
+| `nova.types.interfaces` | Registered interface names |
+| `nova.types.enums` | Registered enum names |
+| `nova.types.traits` | Registered trait names |
+| `nova.types.check(val, typeName)` | Runtime type check → bool |
+| `nova.types.list()` | All registered type names |
+| `nova.events.events()` | Active event names |
+| `nova.events.count(ev)` | Number of listeners |
+| `nova.events.has(ev)` | Has listeners? |
+| `nova.events.clear(ev)` | Remove all listeners for event |
+| `nova.events.clearAll()` | Remove all events |
+| `nova.setMacro(name, val)` | Define/update a macro |
+| `nova.getMacro(name)` | Get macro value |
+| `nova.hasMacro(name)` | Check if macro exists |
+| `nova.setBlock(name, fn)` | Register a native block |
+| `nova.runBlock(name)` | Execute a named block |
+| `nova.runSnippet(name, ...args)` | Execute a named snippet |
+| `nova.emit(event, val)` | Emit event |
+| `nova.on(event, fn)` | Listen for event |
+| `nova.eval(code)` | Parse and run a novac code string |
+| `nova.inspect(name)` | `{ inScope, isMacro, isBlock, isSnippet, isGear, isSession, isResu, value }` |
+| `nova.clearAll()` | Clear macros, blocks, snippets, gears, sessions, descriptions |
+
+### `nvk` (Platform / System Namespace)
+
+`nvk` exposes all system and I/O operations. These replaced the previous statement-based system keywords.
+
+| Member | Description |
+|--------|-------------|
+| `nvk.notify(title, content)` | Termux notification (fallback: stdout) |
+| `nvk.toast(msg)` | Termux toast |
+| `nvk.vibrate(ms)` | Termux vibrate |
+| `nvk.clipboard(text)` | Set clipboard via Termux |
+| `nvk.camera(path)` | Take photo via Termux |
+| `nvk.share(path)` | Share file via Termux |
+| `nvk.open(path)` | Open file via Termux |
+| `nvk.cpu` | Array of CPU model strings |
+| `nvk.mem` | Total memory e.g. `"8.00GB"` |
+| `nvk.hostname` | `os.hostname()` |
+| `nvk.uptime` | `os.uptime()` in seconds |
+| `nvk.pid` | `process.pid` |
+| `nvk.arch` | `os.arch()` |
+| `nvk.platform` | `process.platform` |
+| `nvk.osPlatform` | `os.platform()` |
+| `nvk.userInfo` | `os.userInfo()` as NovaObject |
+| `nvk.network` | `os.networkInterfaces()` as NovaObject |
+| `nvk.load` | `os.loadavg()` as NovaArray |
+| `nvk.tmpDir` | `os.tmpdir()` |
+| `nvk.cwd` | `process.cwd()` |
+| `nvk.pathDir(p)` | `path.dirname(p)` |
+| `nvk.pathBase(p)` | `path.basename(p)` |
+| `nvk.pathExt(p)` | `path.extname(p)` |
+| `nvk.pathJoin(...parts)` | `path.join(...parts)` |
+| `nvk.sha256(s)` | SHA-256 hex digest |
+| `nvk.randomBytes(n)` | N random bytes as hex string |
+| `nvk.uuid()` | Random UUID v4 |
+| `nvk.parseURL(raw)` | `{ hostname, pathname, search, protocol, port }` |
+| `nvk.readFile(path)` | `fs.readFileSync(path, 'utf8')` |
+| `nvk.writeFile(path, content)` | `fs.writeFileSync` |
+| `nvk.createFile(path, content)` | Create/overwrite file |
+| `nvk.deleteFile(path)` | `fs.unlinkSync` |
+| `nvk.listFiles(dir)` | `fs.readdirSync(dir)` as NovaArray |
+| `nvk.exists(path)` | `fs.existsSync(path)` |
+| `nvk.execFile(path)` | Parse and run a `.nova` file |
+| `nvk.sh(cmd)` | `execSync(cmd)` — prints and returns stdout |
+| `nvk.exec(code)` | Parse and run a novac code string |
+| `nvk.term(cmd, shell)` | Run cmd in specified shell (`bash` default) |
+| `nvk.banner(text)` | Print box-drawn banner |
+| `nvk.warn(msg)` | `"Warning: msg"` |
+| `nvk.info(msg)` | `"INFO: msg"` |
+
+### `qae` (Query Assertion Engine)
+
+All members are functions `(a) => bool` or `(a) => value`:
+
+| Member | Description |
+|--------|-------------|
+| `qae.even(a)` / `qae.odd(a)` | Parity check |
+| `qae.integer(a)` | `Number.isInteger(a)` |
+| `qae.positive(a)` / `qae.negative(a)` / `qae.zero(a)` | Sign check |
+| `qae.finite_(a)` / `qae.infinite(a)` / `qae.nan_(a)` | Numeric state |
+| `qae.isnull(a)` / `qae.defined(a)` | Nullability |
+| `qae.trimable(a)` / `qae.trimmed(a)` | Whitespace |
+| `qae.uppercase(a)` / `qae.lowercase(a)` | Case transform |
+| `qae.numeric(a)` / `qae.alpha(a)` / `qae.alnum(a)` / `qae.blank(a)` | String class |
+| `qae.palindrome(a)` | Is palindrome (case-insensitive, strips spaces) |
+| `qae.empty(a)` / `qae.nonempty(a)` | Emptiness |
+| `qae.unique(a)` | Array has no duplicates |
+| `qae.first(a)` / `qae.last(a)` / `qae.length(a)` | Array/string access |
+| `qae.truthy(a)` / `qae.falsy(a)` | Boolean coercion |
+| `qae.type_(a)` | `typeof a` |
+| `qae.string_(a)` / `qae.number_(a)` / `qae.boolean_(a)` / `qae.object_(a)` / `qae.array_(a)` / `qae.function_(a)` | Type checks |
+| `qae.prime(a)` / `qae.composite(a)` / `qae.oddprime(a)` | Number theory |
+| `qae.vowel(a)` / `qae.consonant(a)` | Character class |
+| `qae.sorted(a)` / `qae.ascending(a)` / `qae.descending(a)` | Order checks |
+| `qae.contains(a, b)` / `qae.startsWith_(a, b)` / `qae.endsWith_(a, b)` / `qae.matches_(a, b)` | Containment |
+| `qae.divisible(a, b)` / `qae.between_(a, lo, hi)` | Numeric predicates |
+| `qae.check(a, pred)` | Apply function or named qae predicate to a |
+
+### `novaRegex(pattern, flags)`
+
+Semantic regex with `<name>` placeholders. Returns a JS `RegExp`.
+
+```nova
+let emailRe = novaRegex("<email>")
+emailRe.test("a@b.com")   // true
+novaRegex("<email|url>")  // combined with |
 ```
 
-### Collections
+Semantic names: `keyword` `symbol` `digit` `nondigit` `whitespace` `tab` `newline` `start` `end` `any` `wordboundary` `word` `variable` `integer` `float` `hex` `binary` `space` `title` `email` `url` `uuid` `date` `time` `color`
+
+### Global Functions
+
+| Function | Description |
+|----------|-------------|
+| `typeOf(v)` | `"number"` `"string"` `"bool"` `"null"` `"array"` `"object"` `"range"` `"pointer"` `"function"` `"struct:Name"` `"enum:Name"` |
+| `typecheck(v, typeName)` | Runtime type check → bool |
+| `satisfies(v, ifaceName)` | Does value satisfy all required interface members? |
+| `fetch(url, options?)` | Sync HTTP → `{ ok, status, body, text }` |
+| `setTimeout(fn, delay)` | Schedule function after delay |
+
+---
+
+## Built-in Class Objects
+
+All available globally:
+
+### `ForLoop(opts)`
 
 ```nova
-// addto — push to array or set map key
-let log = [];
-addto log "startup";
-addto log "ready";
+ForLoop({ from: 1, to: 10 }).map(i => i * i).collect()
+ForLoop({ from: 0, to: 20, step: 2 }).toArray()
+ForLoop({ from: 1, to: 100 }).do(i => { sum += i }).run()
+```
+
+| Method | Description |
+|--------|-------------|
+| `.from(n)` `.to(n)` `.step(n)` | Configure range |
+| `.do(fn)` / `.each(fn)` / `.map(fn)` | Set body |
+| `.run()` | Execute without collecting |
+| `.collect()` | Execute and collect results |
+| `.toArray()` | Collect index values |
+| `.filter(fn)` | Convert to Pipeline then filter |
+| `.pipe()` | Convert to Pipeline |
+| `.toStream()` | Convert to DataStream |
+
+### `WhileLoop(opts)`
 
-let config = {};
-addto config "v2":version;
+```nova
+WhileLoop({}).cond(() => n < 32).do(() => { n *= 2 }).maxIter(100).run()
 ```
 
-### Code Reuse
+### `IfBlock(opts)`
 
 ```nova
-// macro — text substitution constant
-macro PI = 3.14159;
-macro MAX_RETRY = 3;
+IfBlock({ cond: score >= 90, then: () => "A" })
+  .elseIf(score >= 80, () => "B").else(() => "F").run()
+```
 
-// lambda — inline function binding
-lambda square = x => x * x;
+### `MatchBlock(subject)`
 
-// compose — pipeline two or more functions with >>
-func trim(s)  => { give s; }
-func upper(s) => { give f"{s}!"; }
-compose shout = trim >> upper;
+```nova
+MatchBlock(404)
+  .when(200, () => "OK")
+  .when(404, () => "Not Found")
+  .when(90..100, x => "A")
+  .when(x => x > 500, x => "server err")
+  .default(() => "Unknown")
+  .run()
+```
 
-// partial — pre-bind arguments
-func multiply(a, b) => { give a * b; }
-partial double = multiply(2);
+### `TryCatch()`
 
-// defunc — named function with arrow syntax
-defunc greet(name) => {
-  core.print(f"Hello {name}");
-}
+```nova
+TryCatch().try(() => { throw "oops" }).catch(e => core.print(e)).finally(() => {}).run()
+```
+
+### `Pipeline(initial)`
 
-// block/snippet — named code blocks (run on demand)
-block setup { core.print("setup run"); }
-snippet cleanup { core.print("cleanup run"); }
+```nova
+Pipeline([1,2,3,4,5]).filter(x => x % 2 == 0).map(x => x*x).take(2).collect()
 ```
 
-### State
+| Method | Description |
+|--------|-------------|
+| `.pipe(fn)` / `.map(fn)` | Transform |
+| `.filter(fn)` | Filter |
+| `.tap(fn)` | Side-effect passthrough |
+| `.flatMap(fn)` | Map + flatten |
+| `.reduce(fn, init)` | Immediate reduce |
+| `.take(n)` / `.skip(n)` | Slice |
+| `.run()` / `.collect()` | Execute |
+
+### `FuncDef(opts)`
 
 ```nova
-// backup / retrieve — save and restore a variable
-let session = "user_abc";
-backup session = session;
-let session = "guest";
-retrieve session;
-core.print(session);  // user_abc
+FuncDef({ args: ["a", "b"], body: (a, b) => a + b }).named("add").call(10, 32)
+```
 
-// describe — attach documentation annotations
-describe "This module handles authentication";
+### `Timer()`
+
+```nova
+let t = Timer(); t.start(); t.lap(); let ms = t.stop()
+t.elapsed   // ms since start
+t.laps      // NovaArray of lap times
 ```
 
-### Feature Flags
+### `Counter(initial, step)`
 
 ```nova
-using strictMode;   // enable a runtime flag
-unuse strictMode;   // disable it
+let c = Counter(0); c.increment(5); c.decrement(2); c.clamp(0, 100); c.value
 ```
 
-### Nova Classic Infix Operators
+### `Stack()` / `Queue()` / `LinkedList()`
 
 ```nova
-// Boolean logic
-true xor true     // false — exclusive or
-true nand true    // false — not and
-false nor false   // true  — not or
-true xnor true    // true  — not xor
+let s = Stack(); s.push(10); s.pop(); s.peek(); s.size; s.empty
+let q = Queue(); q.enqueue("a"); q.dequeue(); q.peek(); q.size
+let ll = LinkedList(); ll.push("a"); ll.shift(); ll.pop(); ll.unshift("z"); ll.size
+```
 
-// Type checks
-42 is 42          // true  — strict identity
-1 isnt 2          // true  — not identical
-42 istypeof "number"  // true
-"hello" matches "hell"  // regex test
+### `State(initial)`
 
-// Set operations
-[1,2,3] intersect [2,3,4]  // [2,3]
-[1,2] union [2,3]           // [1,2,3]
-[1,2,3] diff_arr [2,3]      // [1]
-[1,2,3] zip ["a","b","c"]   // [[1,"a"],[2,"b"],[3,"c"]]
+```nova
+let sm = State("idle")
+sm.add("idle", "start", "running").add("running", "done", "idle")
+sm.onEnter("running", s => {}).onExit("idle", s => {})
+sm.dispatch("start")   // true = success
+sm.current; sm.history; sm.is("running")
+```
 
-// Numeric
-4 avg 6      // 5
-12 gcd 8     // 4
-4 lcm 6      // 12
-"a" cmp "b"  // -1 (locale compare)
-"Hello" equals_ignore "hello"  // true
+### `Observable(initial)` / `Signal(initial)`
 
-// Array with step
-0..20 step 5   // [0, 5, 10, 15, 20]
+```nova
+let obs = Observable(0)
+obs.subscribe((newVal, oldVal) => {})
+obs.value = 42
+let derived = obs.pipe(x => x * 2)
+
+let sig = Signal(1)
+let doubled = sig.derive(x => x * 2)
+sig.value = 5   // doubled.value = 10 (automatic propagation)
+sig.effect(v => {})  // runs immediately and on every change
+```
+
+### `Validator()`
 
-// Object/array merge
-{x:1} extend {y:2}    // {x:1, y:2}
-[1,2] concat [3,4]    // [1,2,3,4]
+```nova
+Validator().required().type("number").min(0).max(100).validate(50)
+// { valid: true, errors: [], value: 50 }
 ```
 
-### Type Casting (`rate`)
+| Method | Description |
+|--------|-------------|
+| `.required()` `.type(t)` `.min(n)` `.max(n)` | Core validators |
+| `.minLen(n)` `.maxLen(n)` `.pattern(re)` `.email()` | String validators |
+| `.custom(fn, msg)` | Custom validator |
+| `.validate(v)` | Returns `{ valid, errors: NovaArray, value }` |
+
+### `DataStream(source)`
+
+```nova
+DataStream([5,3,8,1,9]).filter(x => x > 3).sort().reverse().take(3).collect()
+```
+
+| Method | Description |
+|--------|-------------|
+| `.map` `.filter` `.take` `.skip` `.flatMap` | Transform |
+| `.distinct()` | Deduplicate via Set |
+| `.sort(fn?)` `.reverse()` `.zip(other)` | Reorder |
+| `.collect()` `.reduce(fn, init)` `.forEach(fn)` | Materialize |
+| `.first()` `.last()` `.count()` | Inspect |
+
+### `Transformer()` / `TransformerJSON()` / `TransformerBase64()`
 
 ```nova
-rate(3.9) int     // 3       — truncate
-rate(300) u8      // 44      — 300 & 0xFF
-rate(200) i8      // -56     — signed 8-bit
-rate(300) u16     // 300
-rate(5)   bigint  // 5n
-rate("hi") char   // "h"
-rate(1.5) f32     // 32-bit float precision
+let jt = TransformerJSON(); jt.to({ x: 1 }); jt.from('{"x":1}')
+let b64 = TransformerBase64(); b64.to("Hello!"); b64.from(encoded)
+// Static presets: Transformer.upper(), Transformer.trim_(), Transformer.number_()
 ```
 
-### Type Classification (`classify`)
+### `Router()`
 
 ```nova
-classify 42            // "number"
-classify "x"           // "string"
-classify [1,2]         // "array"
-classify 42 as int     // true
-classify "x" as int    // false
+let router = Router()
+router.on("/api/users/(.*)", id => f"user {id}").default(p => f"404: {p}")
+router.dispatch("/api/users/42")   // "user 42"
 ```
 
-### QAEs — Query Assertions / Predicates
+### `EventBus()`
 
 ```nova
-qae.prime(17)         // true
-qae.even(4)           // true
-qae.palindrome("racecar")  // true
-qae.ascending([1,2,3])    // true
-qae.blank("")         // true
-qae.contains([1,2],2) // true
-qae.vowel("a")        // true
-qae.divisible(12, 4)  // true
-qae.between_(5, 1, 10)// true
-// 40+ predicates total
+let bus = EventBus()
+bus.on("data", v => {}).once("ready", () => {}).off("data", handler)
+bus.emit("data", 42); bus.events()
 ```
 
-### Nova Semantic Regex
+### `Memo(fn, keyFn?)` / `Lazy(fn)`
 
 ```nova
-let emailRx = novaRegex("<email>");
-let intRx   = novaRegex("<integer>");
-let urlRx   = novaRegex("<url>");
-emailRx.test("a@b.com");   // true
+let m = Memo(x => x * x * x)
+m.call(5); m.stats; m.clear(); m.invalidate(5)
 
-// Built-in pattern names:
-// integer, float, word, variable, keyword, digit, whitespace,
-// email, url, uuid, date, time, color, hex, binary, title, etc.
+let lazy = Lazy(() => expensiveOp())
+lazy.value; lazy.reset(); lazy.map(fn)
 ```
 
-### stdlib extras
+---
+
+## Standard Library (`std`)
+
+Always available as `std.X`.
+
+### `std.Math`
+
+`abs` `ceil` `floor` `round` `sqrt` `pow` `max` `min` `log` `log2` `log10` `sin` `cos` `tan` `PI` `E` `trunc` `sign` `random` plus:
+
+| Member | Description |
+|--------|-------------|
+| `clamp(v, lo, hi)` | `Math.min(Math.max(v,lo),hi)` |
+| `floorTo(a, b)` | Floor to nearest multiple of b |
+| `ceilTo(a, b)` | Ceil to nearest multiple of b |
+| `factorial(n)` | Memoized factorial |
+| `fibonacci(n)` | Memoized fibonacci |
+| `divmod(a, b)` | `[quotient, remainder]` |
+
+### `std.Array`
+
+`from(it)` `of(...items)` `range(start, end, step)` `isArray(v)` `fill(n, val)` `zip(...arrs)`
+
+### `std.Object`
+
+`keys(o)` `values(o)` `entries(o)` `assign(target, ...srcs)` `freeze(o)` `has(o, k)` `create(proto)`
+
+### `std.String`
+
+`from(v)` `padStart` `padEnd` `repeat` `includes` `startsWith` `endsWith` `trim` `split` `replace` `replaceAll` `toUpper` `toLower` `charAt` `charCodeAt` `fromCharCode` `slice` `indexOf`
+
+### `std.is`
 
 ```nova
-std.fnum(0, 100, 50)   // clamped float var
-std.fint(0, 10, 5)     // clamped integer var
-std.convertCase("helloWorld", "snake")  // "hello_world"
-std.randomWord()  // random pronounceable word
-std.randomName()  // random first name
+std.is.number(v)  std.is.string(v)  std.is.bool(v)  std.is.array(v)
+std.is.object(v)  std.is.null(v)    std.is.func(v)   std.is.range(v)
+std.is.integer(v) std.is.finite(v)  std.is.NaN(v)
 ```
 
+### `std.fn`
+
+`identity` `compose` `pipe` `memoize` `once` `partial` `curry` `noop` `always` `flip` `not`
+
+### Other `std` Members
+
+| Member | Description |
+|--------|-------------|
+| `std.num(v)` / `std.str(v)` / `std.bool(v)` / `std.int(v)` | Coercions |
+| `std.print(...)` | `console.log(...)` |
+| `std.error(msg)` | Throw an Error |
+| `std.range(start, end, step)` | Create NovaRange |
+| `std.fnum(min, max, initial)` | Clamped float with `.value` get/set |
+| `std.fint(min, max, initial)` | Clamped integer with `.value` get/set |
+| `std.convertCase(str, target)` | `"snake"` `"camel"` `"pascal"` `"kebab"` `"upper"` `"lower"` |
+| `std.randomWord()` | Random pronounceable word |
+| `std.randomName(format?, minLen?, maxLen?)` | Capitalized random name |
+| `std.console.*` | `log warn error info time timeEnd` |
+| `std.Date.now()` / `std.Date.create(...)` | Date utilities |
+| `std.json.parse(s)` / `std.json.stringify(v, sp?)` | JSON with NovaObject unwrapping |
+| `std.Promise.*` | `resolve reject all race allSettled any` |
 
 ---
 
-## Unified `nova` Registry Object
+## Standard Built-ins (`bstd` / `import_builtin`)
+
+### `Air`
 
-All Nova registries are merged into a single live `nova` object accessible from any Nova code.
+Object of references to all novac core modules keyed by filename.
+
+### `Chalk`
+
+ANSI terminal colors (same API as `chalk` npm package):
 
 ```nova
-// Read registries
-nova.macros        // all macros as an object
-nova.blocks        // all declared blocks
-nova.snippets      // all declared snippets
-nova.gears         // all declared gears
-nova.sessions      // all declared sessions
-nova.options       // current feature flags
-nova.descriptions  // describe() annotations
-nova.types         // type registry (.structs, .interfaces, .enums, .traits)
-nova.events        // event bus view (.events(), .count(ev), .has(ev))
-nova.version       // "2.0"
+import_builtin Chalk
+core.print(Chalk.red("error"))
+core.print(Chalk.bold.green("success"))
+```
 
-// Macro operations
-nova.getMacro("KEY")        // get a macro value
-nova.hasMacro("KEY")        // check existence
-nova.setMacro("KEY", val)   // set programmatically
+### `History`
 
-// Block/snippet operations
-nova.runBlock("blockName")            // execute a block
-nova.runSnippet("snippetName", args)  // execute a snippet with args
+File-backed input history stored as `.184.<name>`:
 
-// Event operations
-nova.emit("eventName", value)  // fire an event
-nova.on("eventName", fn)       // subscribe (native fn)
+`getKey(name)` `exists(key)` `createHistory(key)` `appendHistory(key, item, mode?, index?)` `readHistory(key)` `rawSetHistory(key, array)` `rawGetHistory(key)` `clearHistory(key)`
 
-// Inspect any name across all registries
-let info = nova.inspect("myVar");
-// info.inScope, info.isMacro, info.isBlock, info.value ...
+### `Input`
 
-// Dynamic evaluation
-let result = nova.eval("1 + 2 + 3");
+Synchronous terminal input with full line-editing:
 
-// Clear all registries
-nova.clearAll();
+```nova
+import_builtin Input
+let r = Input.prompt("Name: ")
+// r: { result: "typed text", history: [] }
+Input.prompt("Pwd: ", { password: true, passwordHash: "*" })
+Input.prompt("Cmd: ", true)   // enable history
+Input.prompt("Search: ", { completer: buf => "suggestion" })
 ```
 
----
+Features: cursor, history `↑↓`, backspace, delete, tab completion, Ctrl+C, password masking.
 
-## Built-in Class Objects
+### `Shema` / `ShemaType`
+
+```nova
+import_builtin Shema, ShemaType
+let schema = new Shema({ name: ShemaTypes.String, age: ShemaTypes.Int })
+schema.validate({ name: "novac", age: 2 })
+schema.defaultObj()
+new ShemaType("PositiveInt", val => Number.isInteger(val) && val > 0)
+```
+
+Built-in `ShemaTypes`: `Int` `Float` `String` `Boolean` `Array` `Object` `Function` `Null` `Undefined` `Symbol` `BigInt` `Date` `RegExp` `Shema` `Any`
 
-Every control flow statement and common pattern has an equivalent OOP class.
+### `ConfigFile`
 
-### `ForLoop`
 ```nova
-// Range iteration as object
-let fl = ForLoop({ from: 1, to: 10, step: 2 });
-fl.do(i => core.print(i)).run();
-let arr = fl.collect();        // returns NovaArray of values
-let range = fl.toRange();      // returns NovaRange
+import_builtin ConfigFile
+let cfg = new ConfigFile("app", "json", false, mySchema)
+cfg.writeFull({ host: "localhost", port: 8080 })
+cfg.write(["database", "host"], "db.example.com")
+cfg.readFull(); cfg.read(["database", "host"])
+cfg.interactiveSetup(defaultConfig)
+```
 
-// Chained builder style
-ForLoop({}).from(1).to(100).step(5).do(i => core.print(i)).run();
+### `JsDB`
+
+`JsDB.class(JsClass)` `JsDB.run(code)` `JsDB.require` `JsDB.gt` `JsDB.fetch(url, opts)` `JsDB.process` `JsDB.version` `JsDB.platform` `JsDB.env`
+
+### `Storage`
+
+```nova
+import_builtin Storage
+Storage.setItem("key", { data: 42 })
+Storage.getItem("key")
+Storage.removeItem("key")
+Storage.clear()
 ```
 
-### `WhileLoop`
+### `Crypto`
+
 ```nova
-let n = 0;
-WhileLoop({ cond: () => n < 10, body: () => n++ }).run();
-WhileLoop({}).cond(() => n < 20).do(() => n++).maxIter(100).run();
+import_builtin Crypto
+Crypto.hash("data")             // SHA-256 hex
+Crypto.hash("data", "sha512")   // any Node.js crypto algo
 ```
 
-### `IfBlock`
+### `PathUtils`
+
+`join` `resolve` `basename` `dirname` `extname`
+
+### `Base64`
+
+`Base64.encode(s)` `Base64.decode(s)`
+
+### `OsUtils`
+
+`platform` `homedir()` `tmpdir()` `cpus()` `totalmem()` `freemem()` `uptime()` `openFile(path)` (Windows: `requestAdminPrivileges()`)
+
+### `Zip`
+
 ```nova
-let result = IfBlock({ cond: score >= 90, then: () => "A", else: () => "B" }).run();
+import_builtin Zip
+await Zip.zip(["a.txt"], "out.zip")
+await Zip.unzip("out.zip", "./output/")
+```
+
+---
+
+## Array Methods
+
+Auto-dispatched on any NovaArray:
 
-// With elseIf chaining
-IfBlock({ cond: false })
-  .elseIf(score >= 80, () => "B")
-  .elseIf(score >= 70, () => "C")
-  .else(() => "F")
-  .run();
+`map` `filter` `reduce` `find` `findIndex` `some` `every` `flat` `flatMap` `sort` `reverse` `slice` `splice` `indexOf` `includes` `join` `push` `pop` `shift` `unshift` `concat` `fill` `forEach` `keys` `values` `entries` `at` `first` `last` `random` `unique` `count` `groupBy` `shuffle` `min` `max` `sum` `avg` `product` `toArray` `toObject` `toString` | `.length` (property)
+
+---
+
+## Object Methods
+
+Auto-dispatched on any NovaObject:
+
+`keys()` `values()` `entries()` `has(k)` `assign(...srcs)` | `.length` (property)
+
+---
+
+## String Methods
+
+Auto-dispatched on any string:
+
+`toUpperCase` `toLowerCase` `trim` `split` `includes` `startsWith` `endsWith` `slice` `indexOf` `lastIndexOf` `repeat` `replace` `match` | `.length` (property)
+
+---
+
+## Type System & Casting
+
+### `as` Cast
+
+```nova
+let n = value as int      // Math.trunc(Number(v))
+let f = value as float    // Number(v)
+let s = value as string   // String(v)
+let b = value as bool     // Boolean(v)
+let a = value as array    // _toIterable(v) → NovaArray
+let st = value as MyStruct
 ```
 
-### `TryCatch`
+### `rate()` Cast — Full Type Table
+
+| Type | Operation |
+|------|-----------|
+| `int` | `Math.trunc(Number(v))` |
+| `float` / `f64` | `Number(v)` |
+| `f32` | `Math.fround(Number(v))` |
+| `string` | `String(v)` |
+| `bool` | `Boolean(v)` |
+| `bigint` | `BigInt(Math.trunc(Number(v)))` |
+| `u8` | `parseInt(v) & 0xFF` |
+| `u16` | `parseInt(v) & 0xFFFF` |
+| `u32` | `parseInt(v) >>> 0` |
+| `i8` | `(parseInt(v) << 24) >> 24` |
+| `i16` | `(parseInt(v) << 16) >> 16` |
+| `i32` | `parseInt(v) \| 0` |
+| `char` | `String(v)[0]` |
+| `array` | `_toIterable(v)` → NovaArray |
+| `StructName` | `createStruct("StructName", v)` |
+
+### Type Check
+
 ```nova
-TryCatch()
-  .try(() => riskyOperation())
-  .catch(e => core.print(f"Error: {e}"))
-  .finally(() => cleanup())
-  .run();
+typecheck(42, "number")         // true
+satisfies(doc, "Serializable")  // true if all required interface members present
+classify value                  // returns type string
+classify value as TypeName      // returns bool
+```
+
+---
+
+## CLI — novac
+
+```sh
+novac <file> [args...]          Run a .nova / .nv file
+novac test <file>               Check syntax (exit 0 = OK, prints "Syntax OK")
+novac format [file]             Format a file (or stdin if no file given)
+novac eval <code>               Evaluate a novac code string inline
+novac tokens <file>             Print token stream as JSON
+novac ast <file>                Print AST as JSON
+novac repl                      Start interactive REPL
+novac new <project>             Scaffold a new project directory
+novac new-kit <dirname>         Scaffold a new kit in current directory
+novac init PATH                 Add npm bin to system PATH (writes to shell rc)
+novac init build                Bundle project into a .novamod file
+novac config get [key]          Read global/project config (all keys if no key given)
+novac config set <key> <value>  Write a config key
+novac config init               Interactive config setup wizard
+novac etc notices               Show runtime notices from stdlib
+novac etc describe <file>       Print a human-readable description of a .nova file's AST
+novac etc kit <name>            Install a built-in kit into ./nova_modules/<name>
+novac etc kit <name> --global   Install a built-in kit into ~/.novac/nova_modules/<name>
+novac module install [path]     Install a .novamod bundle (or all deps from nova.config.json)
+novac module install [path] -g  Install globally into ~/.novac/nova_modules
+novac module list               List all installed modules in nova_modules/
+novac module remove <name>      Remove an installed module
+```
+
+### Running a File
+
+```sh
+novac src/main.nova
+novac src/main.nova arg1 arg2
+novac src/main.nova --port 8080 --debug
+novac src/main.nova @addr1 +feature1
 ```
 
-### `Pipeline`
+All arguments after the file are parsed and exposed as the `cli` object inside the script (see below).
+
+### Argument Parsing Rules
+
+| Argument form | Goes into |
+|---------------|-----------|
+| `positional` (no prefix) | `cli.args` array |
+| `-flag` | `cli.options.flag = true` |
+| `--flag` | `cli.options.flag = true` |
+| `--flag value` | `cli.options.flag = "value"` |
+| `--flag=value` | `cli.options.flag = "value"` |
+| `@name` | `cli.addrs.name = true` |
+| `+feature` | `cli.additions.feature = true` |
+
+Arguments that start with `-`, `@`, or `+` are **excluded** from `cli.args`.
+
+### REPL Commands
+
+Inside `novac repl`:
+
+| Command | Description |
+|---------|-------------|
+| `.exit` | Exit the REPL |
+| `.clear` | Clear the screen |
+| `.ast <code>` | Print AST of inline code |
+| `.tokens <code>` | Print token stream of inline code |
+| `.help` | Show REPL help |
+
+History is persisted to `~/.nova_repl_history`.
+
+### `novac new <project>`
+
+Scaffolds a project directory with:
+
+```
+<project>/
+  src/main.nova          // starter file with print("Hello, Nova!")
+  bin/<project>.nv       // entry script (empty, chmod 755)
+  nova_modules/          // local module directory
+  nova.config.json       // project manifest
+  README.md
+  .gitignore
+```
+
+`nova.config.json` fields: `name`, `version`, `description`, `author`, `license`, `main`, `srcDir`, `scripts.run`, `dependencies`, `devDependencies`.
+
+### `novac init build`
+
+Reads `nova.config.json` from `cwd`, collects all `.nova`/`.nv` files from `srcDir`, and bundles them into `<name>.novamod` — a JSON file with:
+
+```json
+{
+  "manifest": { "name", "version", "main", ...config },
+  "sources": { "relative/path.nova": "source code", ... },
+  "buildTime": "ISO timestamp"
+}
+```
+
+Install in another project: `novac module install ./<name>.novamod`
+
+### `novac etc kit <name>`
+
+Installs a built-in kit from `novac/kits/<name>/` into `nova_modules/`. Available built-in kits: `kitnovacweb`, `kitlibfs`, `kitlibproc`.
+
+---
+
+## Built-in `cli` Object
+
+When a file is run via `novac <file> [args...]`, a `cli` object is automatically injected into the global scope:
+
 ```nova
-let result = Pipeline([1, 2, 3, 4, 5, 6, 7, 8, 9, 10])
-  .filter(x => x % 2 == 0)
-  .map(x => x * x)
-  .take(3)
-  .skip(1)
-  .collect();
+// novac myapp.nova hello world --port 8080 --debug @prod +cache
 
-// Reduce
-let sum = Pipeline([1, 2, 3, 4]).reduce((acc, x) => acc + x, 0);
+cli.args          // ["hello", "world"]  — positional args (no flag prefix)
+cli.options       // { port: "8080", debug: true }
+cli.addrs         // { prod: true }
+cli.additions     // { cache: true }
+cli.raw           // process.argv — full raw argument array
 ```
 
-### `MatchBlock`
+### Full `cli` Object Shape
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `cli.args` | Array | Positional arguments (no `-`, `@`, `+` prefix) |
+| `cli.options` | Object | All `-flag`, `--flag`, `--flag=val`, `--flag val` arguments |
+| `cli.addrs` | Object | All `@name` arguments, values are `true` |
+| `cli.additions` | Object | All `+name` arguments, values are `true` |
+| `cli.raw` | Array | `process.argv` — complete unprocessed argument list |
+
+### Usage Examples
+
 ```nova
-let grade = MatchBlock(score)
-  .when(90..100, x => "A")
-  .when(80..89,  x => "B")
-  .when(x => x >= 70, x => "C")    // predicate pattern
-  .when([60, 65, 69], x => "D")    // array of values
-  .default(x => "F")
-  .run();
+// novac server.nova --port 3000 --host localhost
+let port = cli.options.port or "8080"
+let host = cli.options.host or "0.0.0.0"
+server(port) {
+  get "/" (req, res) { res.json({ host, port }) }
+}
 ```
 
-### `FuncDef`
 ```nova
-let fn = FuncDef({ args: ["a", "b"], body: (a, b) => a + b });
-core.print(fn.call(3, 4));   // 7
+// novac build.nova src/main.nova --minify --output dist/app.js
+let inputFile = cli.args[0]
+let minify = cli.options.minify or false
+let output = cli.options.output or "out.js"
+```
 
-let arrow = fn.toArrow();
-core.print(arrow(5, 6));     // 11
+```nova
+// novac deploy.nova @production +cache
+if (cli.addrs.production) {
+  core.print("Deploying to production")
+}
+if (cli.additions.cache) {
+  core.print("Cache warming enabled")
+}
 ```
 
-### Data Structures
+---
+
+## Threads
 
 ```nova
-// Counter
-let c = Counter(0, 1);       // value=0, step=1
-c.increment(5);              // +5
-c.decrement();               // -1
-c.clamp(0, 100);             // enforce bounds
-core.print(c.value);         // 4
+func worker() => {
+  give heavyComputation()
+}
+
+let t = Thread(worker)
+t.start()
+t.send("message")
+t.on_message(msg => { core.print(msg) })
+let result = t.join()
+```
+
+| Method / Property | Description |
+|-------------------|-------------|
+| `.start()` | Spawn the worker thread |
+| `.join()` | Block until done; applies scope mutations; returns result |
+| `.send(value)` | Post message to worker |
+| `.on_message(fn)` | Handler for messages from worker |
+| `.result` | Final return value |
+| `.error` | Error string if worker threw |
+| `.done` | Boolean: completed |
+
+Scope snapshot: user-defined variables serialized and sent. Functions serialized via `toString()`. Worker can write back via `thread.set(name, val)` — applied atomically on `.join()`.
+
 
-// Stack (LIFO)
-let s = Stack(1, 2, 3);
-s.push(4);
-core.print(s.pop());         // 4
-core.print(s.peek());        // 3
-
-// Queue (FIFO)
-let q = Queue();
-q.enqueue("a"); q.enqueue("b");
-core.print(q.dequeue());     // a
-
-// LinkedList
-let ll = LinkedList();
-ll.push(1).push(2).push(3);
-core.print(ll.size);         // 3
-core.print(ll.shift());      // 1
-
-// Timer
-let t = Timer();
-t.start();
-// ... work ...
-core.print(t.elapsed);       // ms elapsed
-t.lap();                     // record a lap
-
-// State Machine
-let sm = State("idle");
-sm.add("idle", "start", "running")
-  .add("running", "pause", "paused")
-  .add("paused", "resume", "running")
-  .add("running", "stop", "idle");
-sm.onEnter("running", s => core.print(f"entered {s}"));
-sm.dispatch("start");
-core.print(sm.current);       // "running"
-```
-
-### Reactive Primitives
-
-```nova
-// Observable — reactive value with subscribers
-let count = Observable(0);
-count.subscribe((newVal, oldVal) => core.print(f"{oldVal} → {newVal}"));
-count.value = 42;    // triggers subscriber
-
-// Derived observable
-let doubled = count.pipe(x => x * 2);
-count.value = 10;    // doubled.value = 20 automatically
-
-// Signal — simpler reactive primitive
-let x = Signal(5);
-let y = x.derive(v => v * 3);
-core.print(y.value);  // 15
-x.value = 10;
-core.print(y.value);  // 30
-
-x.effect(v => core.print(f"x changed to {v}"));
-```
-
-### Utilities
-
-```nova
-// Validator
-let v = Validator()
-  .required()
-  .type("number")
-  .min(0).max(100)
-  .custom(x => x % 2 == 0, "must be even");
-
-let result = v.validate(42);
-core.print(result.valid);      // true
-core.print(result.errors);     // []
-
-// Special built-in validators
-let emailV = Validator().email();
-
-// Memo — memoized function
-let fib = Memo(n => n <= 1 ? n : fib.call(n-1) + fib.call(n-2));
-core.print(fib.call(10));       // 55
-core.print(fib.stats.hits);     // cache hits
-
-// Lazy — deferred evaluation
-let heavy = Lazy(() => expensiveComputation());
-// Not evaluated until:
-core.print(heavy.value);        // computed once and cached
-core.print(heavy.value);        // served from cache
-
-// DataStream — lazy collection transformations
-let ds = DataStream(hugeArray)
-  .filter(x => x.active)
-  .map(x => x.value)
-  .distinct()
-  .sort()
-  .take(10)
-  .collect();
-
-// Transformer — bidirectional value mapping
-let t = Transformer().encode(v => v * 2).decode(v => v / 2);
-core.print(t.to(5));    // 10
-core.print(t.from(10)); // 5
-
-// Built-in transformers
-let json  = TransformerJSON();
-let b64   = TransformerBase64();
-
-// Router — pattern dispatcher
-let r = Router();
-r.on("/users/(.*)", id => handleUser(id));
-r.on("/posts/(.*)/(.*)$", (id, action) => handlePost(id, action));
-r.default(path => notFound(path));
-r.dispatch("/users/42");
-
-// EventBus — standalone pub/sub (separate from Nova event system)
-let bus = EventBus();
-bus.on("data", v => process(v));
-bus.once("ready", () => init());
-bus.emit("data", payload);
-bus.off("data", handler);
-```
+Read also: NVML readme (./kits/kitnovacweb/README.md)