@neocompose/cli 0.87.2 → 0.88.0

package/skills/neocompose-cli/references/declarations/initializers.md

@@ -0,0 +1,100 @@
+# Initializers
+
+Member defaults: what they may read, when they compute, generic and
+Immutable construction, and edits to stored constructions.
+
+## Initializer scope
+
+- Field initializers may read their class's static members unqualified,
+  inherited ones included: `public int First = Run();`,
+  `public static int Copy = Number;`.
+- Eager initializers can't read `this` or instance members. Defer such reads
+  in a lambda or method group. `List<int> Values = [this.Number + 1]` is an
+  error; `() => this.Number`, `Read`, and `new Callback { Read = Read }` are
+  fine.
+- A static naming another static copies a value
+  (`public static int B = Holder.A;`). Class and collection statics already
+  own their value; use `Clone()` or `Reference`.
+- Inherited initializers read parameters from the constructor that declared
+  them; a storage-only override keeps that scope.
+- Omitted constructor fields use their defaults. Writable collection defaults
+  belong to each instance. Fields without defaults stay absent, and `null`
+  arguments to generated member-wise constructors mean omission.
+
+## Computed initializers
+
+A default that isn't a closed literal stores as a computed initializer and
+replays for omitted members in push, web, and SDK. A stored override stays
+pinned until reset.
+
+- Calls, operators (`public float Derived = Flags.Start / Flags.Scale;`), and
+  direct field or property reads (local, qualified static, or via a stable
+  root path) are computed. `protected int Slots = FeatureFlags.StartInventorySize;`
+  reads the current value at each construction instead of baking it in.
+- Root paths such as `root.Save.World.Time.Year` stay executable even when
+  `World` and `Time` exist only through construction defaults, including
+  inside `new() { Year = root.Save.World.Time.Year }`.
+- Literal-only positions: dictionary keys (string literals, or option literals
+  for enum keys) and Color components. Instance member defaults need numeric
+  literal vector components; statics may compute them
+  (`new Vector2(Probe.X, 1)`).
+- Parenthesize a computed list or dictionary entry that has an `@id`:
+  `@id("row") (A.B / A.C)`. Push adds these parentheses when it assigns IDs.
+
+## Generic construction
+
+- A generic class without a declared constructor is built with its type
+  arguments: `new Box<int> { Item = 4 }` or target-typed `new() { Item = 4 }`.
+  `new Box()` is an open generic and rejected. A `T` field is required unless
+  `T` is nullable (`new Box<int?>()` may omit it).
+- Inside the class, construct with its own parameter
+  (`public Bag<T> B = new Bag<T>();`); one with fields or entries runs per
+  instance. Wrapping the parameter (`new Bag<List<T>>()`) is rejected.
+- Type arguments must satisfy `extends` in bodies too. A written argument list
+  names every parameter (`item is Tool<Asset>` fails when `Tool` has two); a
+  bare `item is Tool` is allowed.
+- Delegates may be type arguments (`Box<NeoDelegate<int, int>>`); `NeoAction`
+  may not.
+- Header parameters may initialize generic collection fields
+  (`class Box<T>(List<T> value) { public List<T> Value = value; }`), also for
+  `Dictionary<string, T>`, nested collections, and stored instances such as
+  `public static Box<int> Value = new([1, 2]);`.
+- Collection type arguments such as `new Box<List<int>>([1, 2])` work even if
+  no field declares that collection type. Every authored type argument is
+  validated, nested ones included: `new Box<List<MissingType>>()` fails.
+- Generics may nest (`Box<Box<int>>`, `Box<List<Box<int>>>`); each `new` keeps
+  its own type arguments.
+
+## Immutable members
+
+Runtime construction never supplies an Immutable member: no initializer
+block, constructor body, base argument, or generated C# factory can set one,
+and it is never stored with the instance.
+
+- If the declaration and every row it owns read neither `this` nor
+  constructor arguments, and no value of its type holds a writable member, it
+  is a constant shared by every instance.
+- Otherwise each instance evaluates the initializer with its own `this` and
+  arguments, again after reload. A method group such as
+  `selector: SelectTorso` binds `this`.
+- `Clone()` shares an authored or constant Immutable value and re-evaluates a
+  per-instance one.
+- A class with a required Immutable member and no initializer can only be
+  constructed by authored values.
+
+## Stored constructions
+
+- Editing a stored object's constructor arguments rebuilds it in place under
+  the same identity; see [defaults and overrides](../values/defaults-and-localization.md#construction-rebuilds).
+  Initializers that read it wait for the replacement.
+- Objects built by an implicit constructor may settle required fields in
+  their object body. Keep that body when adding a parameterless constructor;
+  an empty argument list needs no invented arguments.
+- Populated unordered defaults (`@settings(kind: .Unordered)` with
+  `List<Entry> Entries = [new Entry()]`) are built per instance by an
+  initializer. Nested unordered lists keep their stored values.
+- A field, entry, or dictionary value can't place something already owned
+  elsewhere (`Bag = [Shared.Pattern]`, or a constructor parameter stored in an
+  ordinary field). Use `Clone()` or `Reference`.
+- You may remove a constructor and replace every call in the same edit; push
+  prepares the new calls with the schema change.

package/skills/neocompose-cli/references/declarations/member-kinds.md

@@ -0,0 +1,107 @@
+# Member kinds
+
+Interface-typed members, sets, actions, lifecycle hooks, and stored tuples.
+`Reference<T>` lookups are in [references](../values/references.md).
+
+## Interface-typed members
+
+An interface may type a field (nullable, `readonly`, or `static` too), a
+`List`/`Set`/`Dictionary` entry, a generic argument, a parameter, or
+`Reference<I>`. Each row holds its own class, which must implement it.
+
+```neo
+interface IContainer<T extends Item> {
+  List<T> Contents { get; }
+}
+
+class Crate<T extends Item> : IContainer<T> {
+  public List<T> Contents = [];
+}
+
+class Player {
+  public IContainer<Seed>? Pouch = new Crate<Seed>();
+  public List<IContainer<Seed>> Racks = [];
+}
+```
+
+- Construct a class, never the interface (`new IContainer<Seed>()` is an
+  error).
+- An open class fits an interface slot only when the interface fills every
+  class parameter, as `Crate<T> : IContainer<T>` does; otherwise store a
+  closed subclass.
+- A class implements a given interface once across its `extends` chain.
+  Interface arguments are in-scope type parameters or types containing none
+  (`IContainer<List<T>>` is an error). `is` checks need the arguments.
+- `NeoVariant<I>` is an error. `@index` on interface entries is an error;
+  `@column` may name an interface property.
+- Interfaces carry no storage. A row fits only when its class allows the
+  storage it lives in; the compiler, push, and commit refuse misfits.
+- A variant or animation override that puts a different class in an
+  interface slot replaces the slot's row.
+- Constraints may be interfaces (`T extends IContainer<Seed>`).
+- Generated C# types the slot by the generated interface. Assigning a non-Neo
+  C# implementation, or a row the interface doesn't determine, throws and
+  names the slot.
+
+## Sets
+
+`Set<T>` is insertion-ordered and holds no duplicates. The element decides
+storage:
+
+- enum `Set<Trait>`: multi-select enum
+- `Set<Reference<T>>`: multi-select lookup
+- `Set<NeoDialogueReference>`: multi-select dialogue lookup
+- anything else: an owned set of rows, like a List
+
+```neo
+@index(member: Slug, kind: .Unique)
+public Set<Quest> ActiveQuests = [];
+public Set<int> LuckyNumbers = [3, 7];
+public Set<Trait> Traits = [.Brave];
+```
+
+- Owned sets hold `bool`, `int`, `float`, `decimal`,
+  `@settings(format: .Plain) string`, vectors, `Color`, sprites, audio clips,
+  classes, or interfaces. Not nullables, collections, variants, delegates, or
+  actions. Class entries are unique by row, values by value.
+- `@index`/`@column` work as on a List; `kind:` is an error.
+- `selection:` is an error everywhere: `Set<T>` selects many, `T` one. The
+  language server's quick fix rewrites `@settings(selection: .Multi)` to a
+  `Set<...>` type.
+- A default literal that repeats a value fails push. `List<Trait>` stays an
+  ordered list.
+- Constructor mutations such as `Bag.Add(7)` keep entries as backing rows;
+  existing entries keep their identities.
+- Use `Set<T>` parameters for several selections.
+
+## Actions
+
+Declare multicast events as `NeoAction<...>` with a bracketed list of method
+groups: `public NeoAction<int> OnDamaged = [PlayHitFlash, ApplyDamage];`.
+Invocation, subscription, and `Clear()` rules are in
+[delegates and listeners](../neoscript/delegates-and-listeners.md#actions).
+
+## Lifecycle interfaces
+
+- `INeoOnLoad`/`INeoOnUnload` run when an instance becomes live and stops
+  being live.
+- `INeoUnity*` interfaces (`INeoUnityUpdate`, `INeoUnityOnTriggerEnter2D`, ...)
+  run for a rendered `NeoObjectBase` in play mode.
+- Their member names (`OnLoad`, `Update`, ...) are reserved: declare one only
+  as the public immediate instance method implementing its interface, never
+  `@effect`.
+- Subscribe Session actions in `OnLoad` and remove them in `OnUnload`. Use
+  `@effect` for data reactions and keep `Update` for true per-frame work.
+
+## Stored tuples
+
+```neo
+public (int Count, bool Enabled) State = (3, true);
+public (int, (string Label, int Count))? Detail = null;
+```
+
+Each position has a derived descriptor; author no descriptor IDs. Relabeling
+keeps identity. Changing arity or moving positions needs a migration. A
+required tuple without a default must be supplied at construction. Owned
+class and collection elements follow the single-owner rule. Tuple
+expressions are in [types and narrowing](../neoscript/types-and-narrowing.md#tuples).

package/skills/neocompose-cli/references/declarations/overloads.md

@@ -0,0 +1,50 @@
+# Overloads
+
+## Declaring
+
+```neo
+class Inventory {
+  public int Add(Item item) { return 1; }
+  public int Add(Item item, int count) { return count; }
+  public int Add(List<Item> items) { return items.Count; }
+}
+```
+
+- A class's overload set holds every same-named function it declares or
+  inherits. Static and instance, NSFunction and native, generic and
+  non-generic functions mix freely.
+- Any two need different parameter types after dropping nullability,
+  substituting base type arguments, and renaming function type parameters by
+  position. `Add(Item)` and `Add(Item?)` collide, so do `F()` and `F<T>()`;
+  `Find<T = Item>(T value)` occupies `Find(Item)`.
+- At most one function per name and class may be dispatched (`abstract`,
+  `virtual`, `override`, or an interface implementation). Overrides target
+  that one.
+- Interfaces can't overload. When several class functions share an interface
+  function's name, the one with matching parameters implements it.
+- `Equals` and names a platform type declares (lifecycle hooks,
+  `OnTriggerEnter2D`) can't be overloaded. A function can't share a name with
+  a field, property, getter, or action.
+- Overloads generate C# overloads. A plain overload stores under the key
+  `Name#<memberId>`; a dispatched or lone function keeps `Name`.
+
+## Calling
+
+Resolution happens at compile time over every overload the receiver's type
+sees. A type qualifier sees static ones, an instance receiver instance ones.
+
+- An overload applies when the argument count fits its required plus default
+  parameters and each argument converts. Lambdas, method groups, `null`,
+  collection literals, and `.North` apply by shape.
+- Closer parameter types win: exact beats conversion, `Bag` beats `Item` when
+  `Bag : Item`. Ties go to the overload filling no defaults, then the
+  non-generic one. Anything else is ambiguous: `Scale(float)` and
+  `Scale(decimal)` can't take an `int`; write `2.0` or `2m`.
+- Generic overloads take explicit type arguments or infer them. One whose
+  arguments can't be inferred isn't a candidate: beside `F(int a, string b)`,
+  `F<T>(T a, T b)` takes `F(1, 2)` but not `F(1, "a")`.
+- Method groups pick the overload exactly matching the target delegate type
+  in assignments, `+=`, `OnChanged`, `@listeners`, and delegate arguments.
+  `var f = Read` is an error for an overloaded `Read`.
+- Tests and eval name a delegate type or signature; see
+  [testing](../neoscript/testing-and-migrations.md).

package/skills/neocompose-cli/references/dialogues.md

@@ -0,0 +1,145 @@
+# Dialogues
+
+NeoFlow `.neoflow` files, dialogue groups, labels, and triggering dialogues
+from NeoScript.
+
+## Dialogue files
+
+Each `.neoflow` file has exactly one top-level, non-generic
+`sealed class Name : NeoDialogue` that overrides `Trigger Trigger` once and
+declares no other types.
+
+```neoflow
+@id("capitol-dialogue-id")
+@settings(name: "Capitol: cold boot", saveOptionChoices: true)
+sealed class CapitolColdBoot : NeoDialogue {
+  @primary Outpost capitol = Assets.Capitol;
+  Player player = Player.Current;
+
+  @id("trigger-id")
+  override Trigger Trigger = new(group: CapitolDialogues.High) => Welcome;
+
+  @id("welcome-node-id")
+  Text Welcome = new(name: "Welcome!") {
+    """
+    Hello, {player.Name}.
+    """
+
+    @id("continue-option-id")
+    Option Continue = new() {
+      """
+      Continue.
+      """
+      return Finish;
+    }
+  }
+
+  @id("finish-node-id")
+  Text Finish = new() {
+    """
+    Until next time.
+    """
+  }
+}
+```
+
+- Mark `@primary` explicitly; never infer it. In a `.Lookup` group the
+  `@primary` binding is the lookup value that triggers the dialogue; without
+  one it never triggers.
+- Dialogue bindings are flow-wide; node bindings are scoped to the node and
+  its children.
+- Each persisted condition use, action invocation, mutation, pause, option,
+  and node has its own owner-scoped ID. New ones omit it until push.
+- Go to a destination with `= new(...) => Next;` or a trailing block with
+  `return Next;`. Never author `to:`. Triggers, options, and outcomes need
+  destinations; terminal text and actions may fall through. Keep every
+  statement of `Actions Empty = new();` inside its body.
+- Prose lowers to localized-text records. Existing translations survive
+  pushes. A prose block's content and closing `"""` follow its opening
+  `"""`, so re-indenting never changes the text.
+- New getters used in prose interpolation need no `@id`.
+
+After editing, run `neo dialogue dryrun <dialogue-ref>`. It prepares the
+local candidate, including pending schema and value changes, without fetching
+or committing. Exit 1 means the graph would fail on device.
+
+## Groups
+
+```neo
+NeoDialogueGroup QuestUnlocks = new(kind: .Standard, parent: Quests, name: "Unlocks");
+
+NeoDialogueGroup FishingVictory = new(
+  kind: .Lookup,
+  collection: Assets.FishEncounters,
+  collectionValue: Reference(root.Assets.FishEncounters),
+);
+```
+
+- `name:` sets the stored name when it should differ from the local
+  identifier; omitted, it uses the identifier. Unity generates its API from
+  the stored name (`Quests.Unlocks`). Pull keeps the local identifier and file
+  by `@id`; a remote rename updates `name:`.
+- Triggers accept `group: QuestUnlocks.Medium` or
+  `group: Quests.Unlocks.Medium`. Qualified paths use display names converted
+  to identifiers. Sibling groups that collide on a segment need distinct local
+  aliases.
+- Priority groups are `NeoPriorityGroup` declarations.
+- Lookup groups use the same collection paths as lookup members. The
+  collection may be created in the same push without IDs. Values without a
+  root path keep `Reference(id: "...")`.
+
+## Labels
+
+For `Text`, `Actions`, `Conditions`, `Option`, and `Outcome`, an omitted
+`name:` takes the label from a custom symbol: `Option Accept = new()` is
+labeled `Accept` whatever its prose. Dialogue classes do the same without
+`@settings(name:)`.
+
+- Generated symbols (`Text1`, `Actions2`, `Option1_2`, `Outcome1`, `Node_...`)
+  stay unlabeled for their own kind. A symbol from another kind is custom:
+  `Option Text1` is labeled `Text1`.
+- Explicit names win: `name: ""` clears a label, `name: null` clears an
+  optional graph label. Pull writes explicit empty names where omission would
+  infer one and drops names equal to the inferred symbol.
+- `Trigger` never infers a label. Reusable condition and action functions use
+  their function name as `sourceFunctionName`; rename the function and its
+  uses to change it. Linked-value aliases keep their `sourceName`. Labels
+  never affect IDs or destinations.
+- `neo pull --regenerate-source-names` replaces generated dialogue symbols
+  with readable ones and rewrites references.
+
+## Triggering dialogues from NeoScript
+
+`root.Dialogues` mirrors the generated C# `Dialogues` folders and groups.
+
+```neo
+public bool TryTalk() {
+  return root.Dialogues.NPCs.Talk.TryTrigger(this, () => {
+    this.AfterTalk();
+  });
+}
+
+public bool HasSomethingToSay => root.Dialogues.NPCs.Talk.CanTrigger(this);
+```
+
+- `root.Dialogues` has `TryTrigger(string dialogueId, onFinish)`,
+  `CanTrigger(string dialogueId)`, `VisitCount(pointer)`, and
+  `HasVisited(pointer)`.
+- A standard group has `TryTrigger(onFinish)` and `CanTrigger()`. A lookup
+  group takes a stored row of its entry class: `TryTrigger(value, onFinish)`,
+  `CanTrigger(value)`.
+- `NeoDialogueReference` has `id`, `TryTrigger(onFinish)`, and `CanTrigger()`.
+  `Set<NeoDialogueReference>` elements are bare IDs; pass them to
+  `root.Dialogues.TryTrigger`.
+- `onFinish` is an optional `NeoDelegate<void>` that runs when the dialogue
+  finishes, fails, or is disposed.
+- `TryTrigger` compiles only in functions (effects, lifecycle hooks,
+  listeners included) and dialogue actions. `CanTrigger`, `VisitCount`, and
+  `HasVisited` are reads. Folders and groups aren't values. User-class code
+  can't trigger dialogues.
+- Unity queues accepted requests and shows one at a time through
+  `Dialogues.OnTrigger`. Requests for the running or a queued dialogue return
+  false, as does everything when the game has no `OnTrigger` handler.
+- `neo test`, `neo script eval`, dry runs, and the web editor have no dialogue
+  runtime: `TryTrigger` and `CanTrigger` return false and `onFinish` never
+  runs.

package/skills/neocompose-cli/references/neoscript/collections.md

@@ -0,0 +1,98 @@
+# Collection builtins
+
+Queries and mutations on `List`, `Set`, and `Dictionary` values. Collection
+declarations and storage live in
+[member kinds](../declarations/member-kinds.md).
+
+## Counting and matching
+
+- `items.Count` and `items.Count()` give the size; `items.Count(pred)` counts
+  matches without building a list. Same forms on Set and Dictionary.
+- `Any()`, `Any(pred)`, and `All(pred)` short-circuit. Empty input has
+  `Any() == false` and `All(...) == true`.
+- `First`, `FirstOrDefault`, `Last`, `LastOrDefault`, `Single`, and
+  `SingleOrDefault` take zero arguments or one predicate. `First`/`Last` throw
+  on no match. `Single` throws unless exactly one matches; `SingleOrDefault`
+  still throws on several. `OrDefault` forms return nullable entries and
+  `null` on no match. Enum sets return enum values.
+- Dictionary callbacks take `(key, value)`, as in
+  `Where((key, value) => key == ToolType.Pickaxe)`.
+
+## Queries
+
+`Where`, `Select`, `SelectMany`, `OrderBy`, `OrderByDescending`, `Skip`,
+`Take`, `SkipWhile`, `TakeWhile`, `Reverse()`, and `Concat(other)` return
+eager, read-only lists. Queries over a Set, such as `Where` and `OrderBy`,
+return a Set; `ToSet()` turns a List into one.
+
+```neo
+return this.Beds
+  .SelectMany((bed) => bed.Plants)
+  .Where((plant) => plant.Ready)
+  .OrderBy((plant) => plant.Name)
+  .Take(10);
+```
+
+- `SelectMany` needs a non-null list or set from its selector.
+- Sorting is stable, evaluates each key once, compares strings ordinally, and
+  accepts bool, int, float, decimal, or string keys (nullable too). Null sorts
+  first ascending and last descending.
+- `ThenBy`/`ThenByDescending` follow `OrderBy`. An inferred `var` keeps that
+  ability; List/Set annotations, function boundaries, and non-ordering queries
+  erase it. Ordering costs O(n log n * k) for k key levels. Mutating the
+  snapshot through a writable alias makes `ThenBy` throw until a new `OrderBy`.
+- Negative skip/take counts behave as zero.
+- Read-only results keep entry identity and grant no extra write access to
+  entries.
+
+## Reductions
+
+- `Sum`, `Average`, `Min`, `Max` take zero arguments or one selector.
+  Sum/Average need int, float, or decimal; Min/Max also accept strings and
+  bools. Nulls are skipped. `Sum` of empty input is zero; the others return
+  null for nullable input and throw for required input. Average of ints is
+  float. Decimal math stays exact; decimal Average rounds half-even within 28
+  digits. Float `Min` stops at the first NaN; `Max` prefers ordinary values.
+- `MinBy(sel)`/`MaxBy(sel)` return the first entry with the winning key,
+  skipping null keys unless all are null. Empty input throws unless the entry
+  type is nullable.
+- List and Set have `Aggregate(fn)`, `Aggregate(seed, fn)`, `Distinct()`, and
+  `Zip(other, fn)`. An empty unseeded `Aggregate` throws. `Distinct` keeps
+  first occurrences by `Contains` equality. `Zip` stops at the shorter input.
+- `GroupBy(sel)` returns a read-only dictionary of read-only lists.
+  `ToDictionary(keySel[, valueSel])` keys must be non-null strings or enums;
+  duplicate keys throw.
+- `.Keys` and `.Values` return read-only lists in dictionary order;
+  integer-looking string keys come before other strings, in numeric order.
+
+## Mutation
+
+These apply to writable collections and are statements:
+
+- `items.Insert(index, value)` accepts 0 through `items.Count` (append);
+  other indices throw.
+- `items.Remove(value)` removes the first equal entry; a missing value is a
+  no-op. `items.IndexOf(value)` (lists only) returns the first index or `-1`.
+- `items.Sort()` sorts scalar entries; `items.Sort((l, r) => l.Score - r.Score)`
+  takes an int comparison. Sort is stable, keeps identity, rejects mutating
+  the list through aliases while comparing, and leaves the order unchanged if
+  a comparison fails.
+
+`Contains`, `IndexOf`, `Remove`, `Distinct`, and `ToSet` compare classes,
+interfaces, collections, and references by identity and other values by value.
+Decimals compare numerically (`1.0` equals `1.00`) while keeping their scale
+for display; strings such as `"1.0"` and `"1.00"` stay distinct.
+
+## List.Repeat
+
+```neo
+List<int> scores = List.Repeat(0, 10);
+List<InventoryItemStack?> slots = List.Repeat<InventoryItemStack?>(null, slotCount);
+```
+
+The entry type comes from the value joined with the assignment context, like
+a list literal, so `List.Repeat(0, 4)` assigned to `List<float>` holds floats.
+Put type arguments on the call, never the qualifier: `List<int>.Repeat` is an
+error and bare `List` is not a value. `count` must be an `int`; a negative
+count throws at runtime. The value and then the count evaluate exactly once,
+so a reference-typed value repeats the same reference.

package/skills/neocompose-cli/references/neoscript/control-flow.md

@@ -0,0 +1,123 @@
+# Control flow
+
+Conditionals, loops, switch, and errors. The shapes match C#; this page lists
+where NeoScript differs or restricts.
+
+## Conditional and logical operators
+
+`cond ? a : b` binds looser than `??`, `||`, and `&&`, associates right, and
+evaluates only the chosen arm. Both arms need a common assignable type or must
+fit the expected type. `&&` binds tighter than `||`; both short-circuit.
+
+## Loops
+
+`for`, `foreach`, `while`, and `do { } while (...);` work as in C#. `while`
+and `do` bodies need braces. `break` exits the nearest loop or switch; `continue` targets the
+nearest loop, including from a switch inside a loop, and re-checks `while`
+conditions.
+
+A `foreach` receiver must be non-null. The loop snapshots membership and order
+at entry, so adding or removing rows does not change its iterations.
+`foreach (var value in dictionary)` binds values. Deconstruct to get keys:
+
+```neo
+foreach (var (key, value) in this.Damage) {
+  if (key == ToolType.Pickaxe) {
+    ApplyDamage(value);
+  }
+}
+foreach ((ToolType key, float value) in this.Damage) { ApplyDamage(value); }
+```
+
+Deconstruction needs a dictionary local or member path; assign a computed
+receiver to a local first. Keys are snapshotted at entry and each value is
+read through `dictionary[key]`, so a removed key follows normal missing-key
+behavior. Both bindings are read-only; writes through a writable entry still
+work. Enum-keyed dictionaries yield enum keys.
+
+## Switch statements
+
+Selectors are `int`, `string`, `bool`, enum, or nullable forms of these, with
+compile-time constant labels. Stack labels to share a body. End every
+reachable non-empty section with `break`, `return`, `throw`, or a valid
+`continue`. No implicit fallthrough, pattern cases, guards, or `goto`.
+
+```neo
+switch (direction) {
+  case Direction.North:
+    Move(0, 1);
+    break;
+  case Direction.East:
+  case Direction.West:
+    Stop();
+    break;
+  default:
+    throw $"Unknown direction: {direction}";
+}
+```
+
+## Switch expressions
+
+`value switch { pattern => result, ... }` arms take constants, `null`, type
+patterns (`Damage`), declaration patterns (`Damage damage`), or `_`, each
+with an optional `when` guard. Arms test in order; the selector runs once.
+
+```neo
+closed class HitResult {}
+sealed class Miss : HitResult {}
+sealed class Damage : HitResult { public int Amount = 0; }
+
+class Combat {
+  public string Describe(HitResult result) => result switch {
+    Miss => "miss",
+    Damage damage when damage.Amount > 10 => "strong hit",
+    Damage damage => $"{damage.Amount}",
+  };
+}
+```
+
+Switch expressions must be exhaustive: every bool/enum option or
+closed-class branch, plus `null` for nullable input; other types need a
+covering type or `_`. A guard counts toward coverage only if it is literally
+`true`. Missing and unreachable arms are compile errors. Property,
+relational, list, and positional patterns are unsupported.
+
+## Errors
+
+Throw a string or a `NeoError` subclass; a string throw creates a `NeoError`.
+Every error has a read-only `Message`. Subclass `NeoError` for typed data.
+
+```neo
+try {
+  return GetUnsafe();
+}
+catch (NeoArgumentError error) when (error.Message != "") {
+  Report(error.Message);
+  throw;
+}
+catch (NeoError error) {
+  return Fallback();
+}
+finally {
+  ReleaseResource();
+}
+```
+
+- A try needs a catch, a finally, or both. Catch bindings are read-only.
+- Typed catches match subclasses. `catch (string message)` matches every
+  ordinary error and binds its Message. An unfiltered base catch must follow
+  the catches it covers.
+- Filters run before intervening finally blocks, even across calls. A false or
+  failing filter continues the search. Bare `throw;` rethrows from a catch.
+- Finally runs on normal completion, return, break, continue, and ordinary
+  errors. The return value is computed before cleanup. An error escaping
+  finally replaces the pending one; an error caught inside it does not.
+  Return and loop transfers can't leave a finally block (a nested loop may
+  break or continue), and bare `throw` inside it needs its own inner catch.
+- Runtime failures are `NeoNullReferenceError`, `NeoIndexOutOfRangeError`,
+  `NeoKeyNotFoundError`, `NeoArgumentError`, `NeoArithmeticError`, and
+  `NeoInvalidOperationError`. Unexpected native failures become `NeoHostError`
+  with Message `"Check logs for more details."`.
+- Execution limits, unavailable preview natives, cancellation, and invalid
+  compiled data can't be caught. Completed writes are never rolled back.
+  Suspended Unity calls keep their cleanup until resumed; abandonment skips it.