novac 2.0.1 → 2.2.0

package/novac/README.md

@@ -0,0 +1,1823 @@
+# novac Language Reference
+
+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.
+
+---
+
+## 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)
+
+---
+
+## Comments
+
+```nova
+// single-line comment
+/! also a single-line comment
+/* multi-line block comment */
+
+/?/ core.print("executed at lex time")  // executable comment — runs during lexing
+```
+
+---
+
+## Preprocessor Directives
+
+```nova
+#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
+```
+
+---
+
+## 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' }
+```
+
+### Destructuring
+
+```nova
+let { a, b } = obj
+let { a: renamed, b: other = "default" } = obj
+let [first, second] = arr
+let [head, ...tail] = arr
+```
+
+### Smart Variable Modifiers
+
+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
+```
+
+```nova
+// $ 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
+
+```nova
+interface Serializable {
+  serialize(): string
+  deserialize(data: string): bool
+  name?: string               // optional member
+}
+interface Extended extends Serializable, Printable { }
+```
+
+### Enum
+
+```nova
+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
+
+```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 | `=` `+=` `-=` `*=` `/=` `%=` `**=` `&&=` `\|\|=` `??=` `=>` `\|>` |
+
+---
+
+## Strings & F-Strings
+
+```nova
+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(', ')}"
+```
+
+---
+
+## Control Flow
+
+### If / Else
+
+```nova
+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
+
+```nova
+unless (cond) { }    // runs when cond is false
+until (cond) { }     // runs while cond is false
+repeat (n) { }       // runs exactly n times
+```
+
+### While / Do-While
+
+```nova
+while (cond) { }
+do { } while (cond)
+```
+
+### For
+
+```nova
+for (let i = 0; i < 10; i++) { }
+for (let item of array) { }
+for (let key in object) { }
+```
+
+### Each
+
+```nova
+each item of array { }
+each item, index of array { }
+```
+
+### Switch / Case
+
+```nova
+switch (value) {
+  case 1: core.print("one"); break;
+  default: core.print("other"); break;
+}
+```
+
+### Match
+
+```nova
+match (value) {
+  when 1            { }
+  when 2, 3         { }              // comma = multi-pattern
+  when 1..10        { }              // range
+  when "ok" where cond { }          // with guard
+  default           { }
+}
+```
+
+### 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
+guard (cond) {
+  // body runs only when cond is TRUE (passes through)
+} else {
+  // runs when cond is FALSE
+}
+```
+
+### When
+
+```nova
+when cond do { }     // runs body once if cond is truthy
+when cond then { }   // same
+```
+
+### Where (scoped bindings)
+
+```nova
+where (base = 100, rate = 0.15) {
+  let tax = base * rate
+}
+```
+
+### With
+
+```nova
+with (object) {
+  // object properties brought into scope
+}
+with option featureFlag {
+  // body runs with flag set; removed after block
+}
+```
+
+### Loop (Classic iteration)
+
+```nova
+loop item in iterable { }
+```
+
+### Foreach (Classic key-value)
+
+```nova
+foreach(collection)(key, value) { }
+foreach(collection)(key, value, length) { }   // third var = total length
+```
+
+### Wait (sync sleep)
+
+```nova
+wait(1000)   // blocks for 1000ms (Atomics.wait, fallback: child process)
+```
+
+### Time Block
+
+```nova
+time {
+  // times this block; prints elapsed ms on completion
+}
+```
+
+---
+
+## Functions
+
+### Named Functions
+
+```nova
+func add(a, b) => {
+  give a + b
+}
+function greet(name) {
+  return f"Hello {name}"
+}
+```
+
+### 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
+
+```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
+```
+
+### Arrow Functions
+
+```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
+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')
+```
+
+### 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
+
+```
+
+### Pipe Operator
+
+```nova
+let result = 5 |> double |> addOne
+```
+
+---
+
+## Classes
+
+```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
+
+```nova
+class Box {
+  _val: 0
+  get value()  { give this._val; }
+  set value(v) { this._val = v; }
+}
+```
+
+### Decorators
+
+```nova
+@logged
+@deprecated("use newFn")
+class OldClass {
+  @readonly
+  name: "old"
+}
+```
+
+---
+
+## Pattern Matching
+
+```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                { }
+}
+```
+
+---
+
+## Events
+
+```nova
+emit "eventName"
+emit "eventName", payload
+
+on "eventName" (data) {
+  core.print(data)
+}
+
+// Internal: fires on every statement execution step
+on "nv:tick" () { }
+```
+
+---
+
+## Error Handling
+
+```nova
+try {
+  riskyOp()
+} catch (err) {
+  core.print(f"caught: {err}")
+} finally {
+  cleanup()
+}
+
+try { riskyOp() } catch { }   // no binding — catch without name
+
+throw "plain string"
+throw new Error("typed")
+
+assert condition
+assert condition, "failure message"
+
+expt "expectedOutput" from {
+  core.print("expectedOutput")
+}
+```
+
+---
+
+## Modules & Namespaces
+
+### Import
+
+```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
+```
+
+### Namespace
+
+```nova
+namespace Math {
+  func add(a, b) => { give a + b }
+}
+Math::add(1, 2)
+using namespace Math   // bring all members into scope
+```
+
+### Using / Unuse
+
+```nova
+using featureFlag
+using namespace MyNS
+unuse featureFlag
+```
+
+### Environment Variable
+
+```nova
+env VAR_NAME   // reads process.env.VAR_NAME; throws if undefined
+```
+
+---
+
+## HTTP & Networking
+
+### First-Class HTTP Verbs
+
+```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.
+
+### Fetch
+
+```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
+```
+
+---
+
+## @classic — Classic Compatibility Block
+
+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
+@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
+}
+```
+
+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
+func migrate() => {
+  @classic {
+    backup session = currentSession
+    temp session = "migration" => {
+      runMigration()
+    }
+    retrieve session
+  }
+}
+```
+
+### 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 |
+```
+
+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
+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)`
+
+```nova
+WhileLoop({}).cond(() => n < 32).do(() => { n *= 2 }).maxIter(100).run()
+```
+
+### `IfBlock(opts)`
+
+```nova
+IfBlock({ cond: score >= 90, then: () => "A" })
+  .elseIf(score >= 80, () => "B").else(() => "F").run()
+```
+
+### `MatchBlock(subject)`
+
+```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()
+```
+
+### `TryCatch()`
+
+```nova
+TryCatch().try(() => { throw "oops" }).catch(e => core.print(e)).finally(() => {}).run()
+```
+
+### `Pipeline(initial)`
+
+```nova
+Pipeline([1,2,3,4,5]).filter(x => x % 2 == 0).map(x => x*x).take(2).collect()
+```
+
+| 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
+FuncDef({ args: ["a", "b"], body: (a, b) => a + b }).named("add").call(10, 32)
+```
+
+### `Timer()`
+
+```nova
+let t = Timer(); t.start(); t.lap(); let ms = t.stop()
+t.elapsed   // ms since start
+t.laps      // NovaArray of lap times
+```
+
+### `Counter(initial, step)`
+
+```nova
+let c = Counter(0); c.increment(5); c.decrement(2); c.clamp(0, 100); c.value
+```
+
+### `Stack()` / `Queue()` / `LinkedList()`
+
+```nova
+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
+```
+
+### `State(initial)`
+
+```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")
+```
+
+### `Observable(initial)` / `Signal(initial)`
+
+```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()`
+
+```nova
+Validator().required().type("number").min(0).max(100).validate(50)
+// { valid: true, errors: [], value: 50 }
+```
+
+| 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
+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_()
+```
+
+### `Router()`
+
+```nova
+let router = Router()
+router.on("/api/users/(.*)", id => f"user {id}").default(p => f"404: {p}")
+router.dispatch("/api/users/42")   // "user 42"
+```
+
+### `EventBus()`
+
+```nova
+let bus = EventBus()
+bus.on("data", v => {}).once("ready", () => {}).off("data", handler)
+bus.emit("data", 42); bus.events()
+```
+
+### `Memo(fn, keyFn?)` / `Lazy(fn)`
+
+```nova
+let m = Memo(x => x * x * x)
+m.call(5); m.stats; m.clear(); m.invalidate(5)
+
+let lazy = Lazy(() => expensiveOp())
+lazy.value; lazy.reset(); lazy.map(fn)
+```
+
+---
+
+## 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.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` |
+
+---
+
+## Standard Built-ins (`bstd` / `import_builtin`)
+
+### `Air`
+
+Object of references to all novac core modules keyed by filename.
+
+### `Chalk`
+
+ANSI terminal colors (same API as `chalk` npm package):
+
+```nova
+import_builtin Chalk
+core.print(Chalk.red("error"))
+core.print(Chalk.bold.green("success"))
+```
+
+### `History`
+
+File-backed input history stored as `.184.<name>`:
+
+`getKey(name)` `exists(key)` `createHistory(key)` `appendHistory(key, item, mode?, index?)` `readHistory(key)` `rawSetHistory(key, array)` `rawGetHistory(key)` `clearHistory(key)`
+
+### `Input`
+
+Synchronous terminal input with full line-editing:
+
+```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.
+
+### `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`
+
+### `ConfigFile`
+
+```nova
+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)
+```
+
+### `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()
+```
+
+### `Crypto`
+
+```nova
+import_builtin Crypto
+Crypto.hash("data")             // SHA-256 hex
+Crypto.hash("data", "sha512")   // any Node.js crypto algo
+```
+
+### `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
+import_builtin Zip
+await Zip.zip(["a.txt"], "out.zip")
+await Zip.unzip("out.zip", "./output/")
+```
+
+---
+
+## Array Methods
+
+Auto-dispatched on any NovaArray:
+
+`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
+```
+
+### `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
+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
+```
+
+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
+// novac myapp.nova hello world --port 8080 --debug @prod +cache
+
+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
+```
+
+### 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
+// 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 }) }
+}
+```
+
+```nova
+// 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"
+```
+
+```nova
+// novac deploy.nova @production +cache
+if (cli.addrs.production) {
+  core.print("Deploying to production")
+}
+if (cli.additions.cache) {
+  core.print("Cache warming enabled")
+}
+```
+
+---
+
+## Threads
+
+```nova
+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()`.
+
+
+Read also: NVML readme (./kits/kitnovacweb/README.md)