kopscript 0.2.0 → 0.4.0

package/LLM.md

@@ -0,0 +1,457 @@
+# KopScript — LLM reference
+
+Complete, dense reference for generating correct KopScript (`.ks`) code. This is a spec,
+not a tutorial — see `README.md` for narrative explanation and rationale. Every construct
+below is exhaustive: if something isn't listed here, it doesn't exist in the language.
+Read the "Does not exist" section before assuming any feature from another language
+carries over.
+
+Compiles to plain ES modules.
+
+## CLI
+
+```
+ks build <file.ks>          # type-check + emit <file>.js next to the source
+ks run <file.ks>            # build, then execute with node
+ks watch <file.ks>          # build, then rebuild on every change to any file in the graph
+ks check <file.ks>          # type-check only, no output files
+ks build|check <file.ks> --json   # single JSON object on stdout instead of human text
+```
+
+`--json` output shape (also what a tool/agent should parse instead of scraping text):
+
+```json
+{ "success": false, "diagnostics": [{ "severity": "error", "message": "...", "line": 2, "col": 14, "file": "/abs/path.ks" }], "written": [] }
+```
+
+`written` is the absolute paths actually written (`build` only, and only on success — a
+failed `build` writes nothing). Exit code is `0` iff `success` is `true`. A missing entry
+file yields `{ success: false, diagnostics: [], written: [], error: "cannot find file '...'" }`.
+
+## File shape
+
+```ks
+using "./other_file";       // 0+ usings, must be a contiguous prefix at the top
+using "../lib/thing";       // relative only ("./" or "../"), no bare package names
+
+// then any number of top-level statements/declarations, in any order
+```
+
+`using` resolves `<path>.ks` relative to the current file and pulls its `public`
+top-level classes/interfaces/enums/functions/extern-decls into unqualified scope. No
+package-import mechanism — cross-package consumption goes through `extern` instead (see
+below). No circular `using` (compile error).
+
+## Types
+
+| Type | Notes |
+|---|---|
+| `number` | one numeric type, no int/float split |
+| `string` | |
+| `bool` | `true` / `false` |
+| `void` | function/method return type only |
+| `T[]` | array of `T`; `T[][]` etc. nest freely |
+| `ClassName` / `InterfaceName` / `EnumName` | any user-declared named type |
+| `(T1, T2) => R` | function type — parenthesized param types, arrow, return type |
+| `task` / `task<T>` | see Async below |
+| `state<T>` | see Reactive state below |
+| `T?` | nullable — see Nullable types below |
+| `Box<T>` | a user-declared generic class/interface — see Generics below |
+
+**Does not exist**: `any`/`unknown` as a writable annotation, a `let`/`var` keyword (see
+Declarations below — there isn't one), type inference for declarations (every
+local/`const`/param/field/return type is written out explicitly), union types, tuples,
+structural/duck typing (all typing is nominal). Generics exist but are deliberately
+scoped down — see the Generics section for exactly what's NOT supported there (multiple
+type parameters, constraints, generic functions, generic inheritance).
+
+## Declarations
+
+```ks
+number x = 5;                 // type-first local var (mutable)
+const string name = "Joe";    // type-first const
+```
+
+Top-level declarations (function/class/interface/enum/extern/raw-string) default to
+**exported** (visible via `using`) unless marked `private`. A top-level bare `number x = 5;`
+is a plain statement, not exportable — `using` only pulls in types and functions, never
+values.
+
+```ks
+private void Helper() { }     // file-local, not visible via `using`
+void Exported() { }           // default: visible via `using`
+```
+
+### Functions
+
+```ks
+number Add(number a, number b) {
+  return a + b;
+}
+async task<number> FetchValue() { return 1; }   // see Async
+```
+
+### Classes
+
+```ks
+class Dog : Animal, IBark {          // 0-1 base class + 0+ interfaces, comma-separated
+  private string name;               // field: no initializer syntax — set in constructor
+  public static number InstanceCount = 0;   // static field: initializer REQUIRED (no ctor runs for it)
+
+  public string Name { get; set; }   // auto-property, get-only or get+set
+  public string ReadOnly { get; }    // settable only within this class's own constructor
+
+  constructor(string name) : base(/* base ctor args */) {
+    this.name = name;
+  }
+
+  public virtual string Speak() { return "..."; }     // overridable
+  public override string Speak() { return "Woof"; }   // in a subclass
+  public static Dog Create(string name) { return new Dog(name); }
+}
+
+Dog d = new Dog("Rex");
+```
+
+- Visibility on members: `public` / `private` / `protected` (default when omitted: `public`).
+- `virtual`/`override` only on instance methods, not static, not fields/properties.
+- No interface-implementation keyword — implementing is structural-by-declaration: list
+  the interface in the base list and provide matching public methods, checked at compile time.
+- No nested classes/functions.
+- No multiple inheritance (at most one class in the base list; the rest must be interfaces).
+- `class Box<T> { ... }` — a single type parameter is allowed; see Generics below for the
+  full (deliberately scoped-down) rules.
+
+### Interfaces
+
+```ks
+interface IShape {
+  number Area();               // method signatures only — no fields/properties in v1
+}
+interface INamedShape : IShape { // interfaces can extend other interfaces (not classes)
+  string GetName();
+}
+interface IContainer<T> {      // interfaces take a single type parameter too — see Generics
+  T Get();
+}
+```
+
+### Enums
+
+```ks
+enum Color { Red, Green, Blue }
+Color c = Color.Red;
+```
+
+No custom values, no methods on enums.
+
+### `match` expression
+
+```ks
+string Classify(string input) {
+  return match input {
+    "cat", "dog" => "animal",     // comma = OR within one arm
+    r"^[0-9]+$" => "number",      // regex pattern, r"..."
+    _ => "unknown"                // wildcard REQUIRED — exhaustiveness-checked
+  };
+}
+```
+
+`match` is an expression (has a value), matches on literal/regex patterns only (not
+type patterns, not destructuring), and always requires a trailing `_` arm.
+
+## Statements
+
+```ks
+if (cond) { } else if (cond2) { } else { }
+while (cond) { }
+for (number i = 0; i < n; i = i + 1) { }
+foreach (number x in items) { }              // arrays only
+break; continue; return; return expr;
+try { } catch (string e) { } finally { }     // at most one catch clause; param type is your choice
+throw "message";                              // throw takes any expression, not just string
+```
+
+`throw` accepts any expression (no base exception/error type to conform to), and a
+`catch (T e)` param's type `T` is **not checked against what's actually thrown** — it
+compiles to a plain JS `catch (e) { ... }` with zero runtime type discrimination. The
+type annotation only affects what `e` type-checks as *inside* the catch block. There's
+no way to have multiple catch clauses per type (only one `catch` per `try`), and no
+built-in exception hierarchy — `catch (string e)` (matching `throw "message";`) is the
+conventional shape used throughout this codebase, but any type is legal.
+
+There is **no ternary/conditional expression** (`if` is a statement only). To get a
+conditional *value* inline, use a `match` on a `bool`-shaped case set, or (in Kopular UI
+code) the `If()` helper — see the Kopular reference.
+
+## Expressions
+
+Precedence, low → high: `=` (right-assoc) → `||` → `&&` → `==` `!=` → `<` `>` `<=` `>=`
+→ `+` `-` → `*` `/` `%` → unary `-` `!` → postfix (`.member`, `(call)`, `[index]`) → primary.
+
+```ks
+this
+new ClassName(args)
+obj.Member
+obj.Method(args)
+arr[index]
+await someTask            // only inside an async function/method body
+state(0)                  // constructs a state<T> — see below
+$"Hello {name}, you are {age} years old"   // interpolated string
+r"^[a-z]+$"               // regex literal (only meaningful as a match pattern)
+```
+
+### Lambdas
+
+```ks
+(number x) => x * x                          // expression body
+(number x, number y) => { return x + y; }    // block body
+() => this.DoThing()
+```
+
+**Every lambda parameter type is required — no inference, no bare `(x) => ...`.** A
+lambda's own first parameter cannot itself be a function type (a rare v1 parser
+limitation, not a semantic one).
+
+### Arrays
+
+```ks
+number[] xs = [1, 2, 3];
+xs.Length
+xs.Push(4)                    // NON-mutating — returns a new array, doesn't modify xs
+xs.Map((number x) => x * 2)   // -> array of whatever the callback returns
+xs.Filter((number x) => x > 1)
+xs.ForEach((number x) => { print(x); })
+```
+
+### Strings
+
+```ks
+s.Length
+s.Contains(other) / s.StartsWith(other) / s.EndsWith(other)
+s.Replace(from, to)
+s.Split(sep)          // -> string[]
+s.Trim() / s.ToUpper() / s.ToLower()
+"a" + "b"             // + is also string concatenation
+```
+
+### Async
+
+```ks
+async task<number> FetchValue() {
+  number x = await SomeOtherAsyncFn();
+  return x;
+}
+async task DoThing() { }   // bare task = "async void" with a value you can await
+```
+
+`async` requires (and is required by) a `task`/`task<T>` return type. `await` only
+legal inside an async function/method body. No async lambdas. No way to construct a
+`task` value from outside an async function body.
+
+### Reactive state — `state<T>`
+
+```ks
+state<number> count = state(0);
+count.Value                          // read/write the current value
+count.Value = count.Value + 1;
+count.Subscribe((number v) => { ... }); // called on every future .Value assignment
+```
+
+Not a use of user-declared generics (see below) — `state<T>` is one of exactly two
+hardcoded parametrized forms in the type system (the other is `task<T>`), each with only
+ever one built-in meaning, unlike a real generic class/interface.
+
+## Generics — a single type parameter on classes/interfaces
+
+```ks
+class Box<T> {
+  public T Value;
+  constructor(T v) { this.Value = v; }
+  public T Get() { return this.Value; }
+}
+
+Box<number> nb = new Box<number>(5);   // type argument required on both the type AND `new`
+Box<string> sb = new Box<string>("hi");
+print(nb.Get());                        // 5
+```
+
+One unconstrained, invariant type parameter per class/interface — the whole feature.
+Erased at codegen (JS has no generics either; `Box<number>` and `Box<string>` both
+compile to the exact same plain `class Box`), so there's no runtime cost and no way to
+inspect `T` at runtime.
+
+**Rules:**
+- The type argument is **required everywhere** a generic type is named — on the variable
+  type (`Box<number>`) and separately on `new` (`new Box<number>(...)`); a bare `Box` (no
+  argument) is a compile error, not "any"/inferred.
+- **Invariant**: `Box<Dog>` is not assignable to `Box<Animal>` even if `Dog : Animal` —
+  type arguments must match exactly, not just be compatible.
+- Nesting works: `Box<Box<number>>`, `Box<number[]>`, `Box<number>?`, `Box<number>?[]`.
+- Inside the class/interface's own body, `T` is fully abstract — you can store it, return
+  it, pass it around, but (unconstrained) you **cannot call any member on a bare `T`
+  value** (`this.value.Foo()` is a compile error: "Cannot access member 'Foo' on type
+  'T'"). This is correct, not a bug — same as an unconstrained type parameter in
+  C#/Java/TypeScript.
+
+**Does not exist (v1 scope cuts, each deliberate)**:
+- **Generic functions.** `T Identity<T>(T x)` doesn't parse — only classes and interfaces
+  take a type parameter, not free functions/methods themselves (a method *inside* a
+  generic class can use that class's own `T` freely, same as any other member).
+- **Multiple type parameters.** No `Map<K, V>` — exactly one `<T>` or none.
+- **Constraints.** No `T : IComparable` — a type parameter is always fully unconstrained,
+  which is why you can't call members on a bare `T` (see above).
+- **Generic inheritance.** A class/interface's base list can only name a *non-generic*
+  type — `class Foo : Box<number>` and even `class Foo<T> : SomeGenericBase<T>` are both
+  compile errors ("cannot extend/implement generic type '...' — not supported in v1"). A
+  generic class/interface can still extend/implement ordinary non-generic bases normally.
+- **Variance.** No `out`/`in`/covariance/contravariance — see invariance above.
+
+## Nullable types — `T?`
+
+```ks
+string? maybeName = null;               // null literal, any type-position postfix `?`
+string?[] arrOfNullable = [null, "x"];  // array OF nullable strings
+string[]? nullableArr = null;            // NULLABLE array of strings — order matters
+```
+
+`?` is a postfix modifier on any type, erased at codegen (JS already has native `null` —
+this is purely a compile-time distinction). Assignability is one-directional: a plain `T`
+is always usable where `T?` is expected (widening), but a `T?` is **never** usable where
+`T` is expected without narrowing first — accessing a member or index on an un-narrowed
+`T?` is a compile error:
+
+```ks
+void F(string? s) {
+  print(s.Length);      // ERROR: possibly-null type 'string?'
+  if (s != null) {
+    print(s.Length);     // OK — s is string here, not string?
+  }
+  print(s.Length);        // ERROR again — narrowing doesn't survive past the if
+}
+```
+
+**Narrowing is recognized in exactly these shapes** (anything else doesn't narrow):
+- `if (x != null) { ... }` — narrows `x` inside the then-branch.
+- `if (x == null) { ... } else { ... }` — narrows `x` inside the else-branch.
+- `cond1 && x.Foo` where `cond1` is `x != null` — narrows `x` for the right operand only.
+- `cond1 || x.Foo` where `cond1` is `x == null` — narrows `x` for the right operand only
+  (De Morgan's: reaching the right side of `||` means the left was false).
+- Either operand order works (`x != null` and `null != x` both narrow `x`).
+
+**Narrowing does NOT handle** (a common instinct from other languages — don't rely on
+these): an early-return guard clause (`if (x == null) { return; } use(x);` — `x` is
+*not* narrowed after the `if`, since that needs control-flow reachability analysis, not
+just scope); narrowing a member/property path (`if (this.Field != null)` narrows
+nothing — only a bare local/parameter identifier narrows); narrowing surviving
+reassignment (assigning a new value to a narrowed variable inside the narrowed block
+doesn't invalidate or restore narrowing — avoid reassigning a narrowed variable within
+the block). `x` stays narrowed for the rest of a narrowed block, including nested blocks
+inside it, since narrowing is scope-based.
+
+Comparing a value to `null` when its type **can't** be null is a compile error, not a
+silently-always-false comparison — this is a real bug-catching check, not just a style
+rule:
+
+```ks
+class Dog { }
+Dog d = new Dog();
+bool x = d == null;   // ERROR: Type 'Dog' can never be null
+```
+
+## `extern` — describing existing JS/npm code
+
+Three forms, always terminated with `;` after the closing brace for the class form:
+
+```ks
+extern number ParseFloat(string s) from "npm-package" as "parseFloat"; // `from` before `as`; omit `from` for an ambient global
+extern SomeType globalThing as "actualJsName";                          // extern value, ambient
+extern class Widget {
+  constructor();
+  string label { get; set; }         // property sig — get / get+set
+  static number Count { get; }
+  void Render();
+  virtual void Update();              // lets a real subclass `override` it
+} from "npm-package";
+```
+
+Clause order is always `from "<path>"` then `as "<jsName>"` (both optional, `from`
+first if both are present). `from "..."` omitted = ambient global (assumed to already
+exist at runtime, e.g. `document`). `as "..."` omitted = the JS-side name matches the
+KopScript-declared name exactly. Extern class members use real JS member names verbatim
+(camelCase, no rename mechanism). No inheritance modeling between two `extern class`
+declarations — each stands alone.
+
+**Never write `async` on an extern function/method signature** — declare its return type
+as `task`/`task<T>` directly (`task<string> text();`, not `async task<string> text();`).
+`async` only means something for a *body* the checker validates (legalizing `await`
+inside it, checking `return` against the unwrapped type); an extern signature has no
+body, so the keyword is simply invalid there — a parse error, not a no-op. This applies
+equally to a top-level `extern` function and an `extern class` method signature.
+
+`jsName` (the `as "..."` string) can be a dotted path, not just a bare identifier — e.g.
+`as "JSON.parse"` — since it's spliced directly into `globalThis.<jsName>` for an
+ambient binding. This is the supported way to get a *typed* (unchecked, trust-based)
+JSON value: describe the shape as its own `extern class`, then declare a parse function
+for it: `extern MyShape ParseIt(string json) as "JSON.parse";` — calling `ParseIt(text)`
+returns whatever `JSON.parse` actually parsed, typed as `MyShape` with zero runtime
+verification (the same trust model as every other `extern`).
+
+An `extern class` reachable from a real npm package — not same-project `using`, which
+only resolves relative `.ks` paths — is how KopScript consumes *any* JS dependency,
+including another KopScript-authored package published as JS (e.g. Kopular): describe
+exactly the members used, from that package's real module specifier. See Kopular's own
+`LLM.md`/README for a live example (`Component`, `Router`, `Http`, ...).
+
+## `raw string` — compile-time file embedding
+
+```ks
+raw string HeroHtml from "./hero.html";   // reads the file at compile time, type is always string
+```
+
+## Keywords (reserved, lowercase, exact match)
+
+`using extern raw from as const class interface enum constructor public private
+protected static virtual override get set return if else while for foreach in break
+continue match this base new void true false null task state async await try catch
+finally throw`
+
+Anything else (including PascalCase versions of the above, e.g. `If`, `Match`) is a
+valid identifier.
+
+## Naming convention used throughout the ecosystem
+
+Types, methods, and properties: **PascalCase** (`Speak()`, `Render()`, `Name`).
+Locals/params: **camelCase**. This is convention, not enforced by the compiler.
+
+## Does not exist (don't reach for these)
+
+Generics · `any`/`unknown` annotations ·
+a `let`/`var` keyword (locals are just `Type name = value;`) · decorators/annotations ·
+reflection · type inference on declarations · ternary expression · union/tuple types ·
+**object-literal syntax** (`{ key: value }` as a value — this doesn't exist *anywhere* in
+the grammar, not just as a type; a JS API whose signature needs one — `fetch`'s options
+argument, `addEventListener`'s options object, etc. — can't be called directly from
+KopScript at all; see Kopular's `http.ks`/`http_runtime.js` for the one established
+workaround, a small hand-written JS shim, not a language feature) ·
+structural typing · multiple class inheritance ·
+nested classes/functions · method overloading · default/optional parameters · varargs ·
+static properties with accessors (static fields only) · interface properties (interface
+*methods* only) · a real exception hierarchy or multi-type `catch` (one `catch` per
+`try`, its param type is unchecked against what's actually thrown) · a package-import
+mechanism (`using` is same-project only; cross-package = `extern`).
+
+**Sharp edge, not just "unsupported":** declaring two methods with the same name in one
+class is **not a compile error** — the second declaration silently replaces the first in
+the checker's method table, so call sites resolve against whichever was declared last
+(and its body is the only one ever emitted). If you want to offer more than one
+signature, use different names, not overloading. (Nested function/class/interface/enum
+declarations, by contrast, *are* a clean compile error: "Nested ... declarations are not
+supported".)
+
+## Diagnostics
+
+Every compiler error/warning is `{ severity, message, line, col }` (1-based). CLI output
+format: `` file:line:col - severity: message `` plus a source line and a `^` pointer.
+`DiagnosticBag.hasErrors` gates whether codegen runs at all — a program with any error
+produces no output.

package/README.md

@@ -11,6 +11,10 @@ auto-properties, enums) rather than TypeScript ones.
 Because KopScript compiles to plain JavaScript and runs on Node, it runs identically on Windows,
 macOS, and Linux — there's no native toolchain to maintain.
 
+Generating KopScript with an AI coding assistant? Point it at **[`LLM.md`](./LLM.md)** —
+a dense, complete, example-driven language spec designed to be loaded straight into an
+LLM's context, as opposed to this README's narrative explanation.
+
 ## Highlights
 
 - **Object-oriented, C#-flavored**: type-first declarations (`string Name;`, not `name: string`),
@@ -18,6 +22,13 @@ macOS, and Linux — there's no native toolchain to maintain.
   explicit `virtual`/`override` dispatch (methods are sealed unless marked `virtual`), and a full
   `public`/`protected`/`private` access model enforced at compile time.
 - **Strongly typed**: every declaration is explicitly typed and checked at compile time.
+- **Generics**: a single, unconstrained, invariant type parameter on classes and
+  interfaces (`class Box<T> { public T Value; }`) — erased at codegen with zero runtime
+  cost, the same way `task<T>`/`state<T>` already are.
+- **Nullable types with compiler-enforced null-checking**: `T?` (`string?`, `Dog?`,
+  `number[]?`) — a `T?` can't be used where a `T` is expected without an `if (x != null)`
+  check first (checked statically, not just at runtime), and comparing a value that can
+  never be null to `null` is itself a compile error.
 - **Built-in string pattern matching**: a `match` expression over strings supporting literal,
   wildcard, and regex patterns — no `if`/`else` chains required.
 - **Real multi-file programs**: `using "./shapes";` compiles a whole dependency graph
@@ -40,9 +51,9 @@ macOS, and Linux — there's no native toolchain to maintain.
   `.Subscribe((T) => void)`) for holding state and reacting to it changing — no
   Observables, no operators, no manual unsubscribe bookkeeping.
 - **A companion framework, [Kopular](https://dev.azure.com/koppinator/Koppindependence/_git/Kopular)**:
-  components, constructor-injected services (no DI container), and hash-based routing (no
-  config DSL) — built entirely on the features above, in a separate repo consumed as a
-  real package. [KopularDemo](https://dev.azure.com/koppinator/Koppindependence/_git/KopularDemo)
+  components, constructor-injected services via a composition root (no DI container), and
+  real-URL routing (no config DSL) — built entirely on the features above, in a separate
+  repo consumed as a real package. [KopularDemo](https://dev.azure.com/koppinator/Koppindependence/_git/KopularDemo)
   is a real app built on both.
 
 ## Getting started
@@ -196,6 +207,49 @@ void Announce(ISpeaker s) {
 }
 ```
 
+### Generics
+
+Classes and interfaces can take a single type parameter:
+
+```ks
+class Box<T> {
+  public T Value;
+  constructor(T v) { this.Value = v; }
+  public T Get() { return this.Value; }
+}
+
+Box<number> nb = new Box<number>(5);
+Box<string> sb = new Box<string>("hi");
+print(nb.Get());   // 5
+```
+
+The type argument is required everywhere the generic type is named — on the variable's
+declared type *and* separately on `new` (`Box<number> nb = new Box<number>(5);`, not
+just one or the other). Generics are erased at codegen exactly like `task<T>`/`state<T>`
+already are — `Box<number>` and `Box<string>` compile to the identical plain `class Box`,
+so there's no runtime cost.
+
+This is deliberately the smallest useful slice of generics, not a scaled-down promise of
+more later inside v1:
+
+- **One type parameter, invariant, unconstrained.** No `Map<K, V>` (multiple parameters),
+  no `T : ISomething` (constraints) — and because `T` is fully unconstrained, you can't
+  call any member on a bare `T` value inside the generic class's own body (that's correct
+  behavior, the same restriction C#/Java/TypeScript put on an unconstrained parameter, not
+  a bug). Invariant means `Box<Dog>` is **not** assignable to `Box<Animal>` even though
+  `Dog : Animal` — type arguments must match exactly.
+- **No generic functions.** `T Identity<T>(T x)` isn't supported — only classes and
+  interfaces take a type parameter. A method *inside* a generic class can still use that
+  class's own `T` freely; it's just not introducing a type parameter of its own.
+- **No generic inheritance.** A class or interface's base list can only name a
+  *non-generic* type. `class Foo : Box<number>` and `class Foo<T> : SomeBase<T>` are both
+  compile errors — a generic class can still extend/implement ordinary non-generic bases
+  normally, it just can't be the one on either side of a generic base relationship.
+
+See `LLM.md`'s "Generics" section for the exhaustive rules if you're generating code
+against this — nested generics (`Box<Box<number>>`, `Box<number>?[]`) and generic
+interfaces used as standalone parameter types both work and are covered there.
+
 ### Enums
 
 ```ks
@@ -513,8 +567,41 @@ foreach (number item in items) {
 ### Types (v1 scope)
 
 `number`, `string`, `bool`, `void`, `T[]` (arrays), class types, interface types, enum
-types, and function types (`(T, ...) => R`). No generics or nullable types yet — a
-possible future extension.
+types, function types (`(T, ...) => R`), nullable types (`T?`, with `null` and
+compiler-enforced null-checking — see "Nullable types" below), and a single type
+parameter on classes/interfaces (`Box<T>` — see "Generics" above).
+
+### Nullable types — `T?`
+
+```ks
+string? maybeName = null;
+void Greet(string? name) {
+  if (name != null) {
+    print("Hello, " + name);   // name is `string` here, not `string?`
+  } else {
+    print("Hello, stranger");
+  }
+}
+```
+
+`?` is a postfix modifier on any type (`Dog?`, or an array either way — `string?[]` is an
+array of nullable strings, `string[]?` is a nullable array of strings; order matters).
+It's purely a compile-time distinction — erased at codegen, since JS already has native
+`null`. The compiler enforces it in both directions:
+
+- A `T?` can never be used where a `T` is expected — accessing a member or index on one
+  is a compile error — **unless** it's been narrowed by an `if (x != null)` /
+  `if (x == null) {...} else {...}` check (either operand order, and inside a `&&`/`||`
+  short-circuit) on that exact local/parameter. Narrowing doesn't survive past the
+  checked block, doesn't follow a `this.Field` path (locals/params only), and doesn't
+  understand an early-return guard clause (`if (x == null) { return; }`) — each of those
+  would need real control-flow analysis, deliberately not taken on in v1.
+- Comparing a value to `null` when its type *can't* be null (i.e. isn't itself a `T?`) is
+  a compile error, not a silently-always-false comparison — a real static check, not
+  just a style rule.
+
+See `LLM.md`'s "Nullable types" section for the exhaustive rules if you're generating
+code against this.
 
 ### Built-ins
 
@@ -534,7 +621,7 @@ src/
   codegen.ts     AST -> JavaScript source string (readable ES2020 output)
   modules.ts     multi-file orchestration: resolves the `using` graph, checks
                  modules in dependency order, drives codegen across all of them
-  cli.ts         `ks build <file>` / `ks run <file>` entry point
+  cli.ts         `ks build|run|watch|check <file>` entry point
 examples/        sample .ks programs (examples/modules/ is a multi-file one)
 test/            vitest unit and end-to-end tests
 ```
@@ -561,11 +648,32 @@ runtime representation at all and are dropped from the emitted JS entirely.
 ks build <file.ks>   # type-check and emit <file>.js next to the source
 ks run <file.ks>     # build, then execute the emitted JS with node
 ks watch <file.ks>   # build, then rebuild on every change to any file in the graph
+ks check <file.ks>   # type-check only — no output files written
 ```
 
-During development, use `npm run ks -- <build|run|watch> <file.ks>` (backed by `tsx`),
-or run `npm run build` to compile the TypeScript compiler itself to `dist/` and use `node
-dist/cli.js` directly.
+`build` and `check` both accept `--json`, which replaces all human-readable output with a
+single JSON object on stdout — meant for CI or a tool/agent parsing the result
+programmatically instead of scraping formatted text:
+
+```json
+{
+  "success": false,
+  "diagnostics": [
+    { "severity": "error", "message": "Argument 2 has type 'string', expected 'number'", "line": 2, "col": 14, "file": "/abs/path/to/file.ks" }
+  ],
+  "written": []
+}
+```
+
+`written` lists the absolute paths of every `.js` file actually written (always empty for
+`check`, and for `build` on failure — nothing is written unless the whole graph is
+error-free). A missing entry file reports `{ "success": false, "diagnostics": [],
+"written": [], "error": "cannot find file '...'" }` instead of throwing. Exit code is 0
+exactly when `success` is `true`, both with and without `--json`.
+
+During development, use `npm run ks -- <build|run|watch|check> <file.ks>` (backed by
+`tsx`), or run `npm run build` to compile the TypeScript compiler itself to `dist/` and
+use `node dist/cli.js` directly.
 
 `watch` rebuilds on a save to *any* `.ks` file it reached while compiling — the entry and
 everything it (transitively, non-transitively per-file) `using`s — not just the entry
@@ -588,25 +696,27 @@ into your extensions folder).
 
 ## Status
 
-This is a v1 / hobby-project scope. Not yet supported: generics, nullable types, static
-auto-properties, interface properties (methods only), and nested functions/classes.
-Generics and nullable types in particular are a substantially bigger undertaking than
-everything else here — they touch the type system's core (type parameters, variance,
-constraint checking) rather than being additive features, so they're deliberately left
-for a dedicated future pass rather than bolted on.
+This is a v1 / hobby-project scope. Nullable types (`T?`) and generics (a single
+unconstrained, invariant type parameter on classes/interfaces) have both shipped — see
+above for both. What generics deliberately doesn't cover: multiple type parameters
+(`Map<K, V>`), constraints (`T : IFoo`), generic functions, generic inheritance, and
+variance — each a real, separable extension rather than a v1 oversight. Also not yet
+supported: static auto-properties, interface properties (methods only), and nested
+functions/classes.
 
 `async`/`await`, `task<T>`, and `try`/`catch`/`finally`/`throw` are now in place (see the
 language tour above) — the ceiling that's left is what's *inside* those: no async lambdas,
 and no way to build a `task` value by hand outside an `async` function body.
 
-### Toward a frontend framework: Kopular
+### A frontend framework: Kopular
 
 The language shape — modules, closures, DOM interop, `state<T>`, and `extern`/`virtual`
 subclassing across a package boundary — exists to support real UI components, not just
 scripts. That framework itself, [Kopular](https://dev.azure.com/koppinator/Koppindependence/_git/Kopular),
-lives in its own repo now rather than in `examples/` here, consumed as a real package
-(currently via a `file:` dependency, pending an npm publish of both). A real app built on
-both lives in [KopularDemo](https://dev.azure.com/koppinator/Koppindependence/_git/KopularDemo) —
-components, `state<T>`-driven reactivity, a constructor-injected service, and
-hash-based routing between two pages, verified against a real DOM via jsdom and in an
-actual browser.
+lives in its own repo, published to npm as `kopular` and consumed like any other package
+(no local checkout or `file:` dependency needed). A real app built on both lives in
+[KopularDemo](https://dev.azure.com/koppinator/Koppindependence/_git/KopularDemo) — several
+routed pages, `state<T>`-driven reactivity, constructor-injected services via a
+composition root (no DI container), structural-directive equivalents for `*ngIf`/`*ngFor`/
+`*ngSwitch`, and real-URL (History API) routing — verified against a real DOM via jsdom
+and in an actual browser.