@neocompose/cli 0.87.2 → 0.89.0

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.

package/skills/neocompose-cli/references/neoscript/delegates-and-listeners.md

@@ -0,0 +1,107 @@
+# Delegates, actions, and listeners
+
+Lambdas, `NeoDelegate`, method groups, `NeoAction` events, `OnChanged`
+subscriptions, and `@listeners` wiring.
+
+## Lambdas and delegates
+
+```neo
+NeoDelegate<int, int> twice = (x) => x * 2;
+List<Item> ready = this.Items.Where((item) => item.Count > 0);
+```
+
+- Lambdas may be returned, stored, or assigned to typed locals. They capture
+  surrounding locals and parameters by value when created.
+- `(x) => x * 2` equals `(x) => { return x * 2; }`. In a void delegate the
+  expression must call or assign. Parenthesize a dictionary-literal body:
+  `() => ({ "a": 1 })`.
+- Call any non-null delegate expression directly: `callbacks[0](value)`,
+  `(cond ? a : b)()`, `Factory.Make()()`. Force-unwrap a nullable one first:
+  `callbacks["key"]!()`. Void delegates are statements only.
+- Inside a class body, invoke delegate and action members directly:
+  `Selector()`, `OnUpdated()`.
+
+## Delegate field defaults
+
+- Instance delegate defaults compile against the declared signature; each
+  instance binds `this` to itself. Invalid bodies are reported at the
+  declaration.
+- Static delegate fields use static class scope: no `this`, no instance
+  members. A static delegate cannot copy another class's delegate field,
+  inherited ones included; wrap it as `() => Other.Call()`.
+- A default may name a method group bare. `Value = Read` or `this.Read` binds
+  each instance to its own `Read`. A qualified group (`Holder.Read`) must be
+  static. Signature mismatches are reported at the declaration.
+- When a function is overloaded, a method group picks the overload whose
+  parameters exactly match the target delegate type. `var f = Read` is an
+  error then; give `f` a delegate type. See [overloads](../declarations/overloads.md).
+
+## Actions
+
+`NeoAction<...>` is a multicast event whose value is an ordered listener set.
+Bare `NeoAction` takes no arguments; `NeoAction<void>` is invalid.
+
+```neo
+public NeoAction<int> OnDamaged = [PlayHitFlash, ApplyDamage];
+```
+
+- Default it with a bracketed list of method groups. Never a lambda, never a
+  bare method group, never `required`; its rest state is the empty set.
+- Subscribe and unsubscribe with `+=` and `-=` on the member. These are
+  durable writes deduplicated by target, so re-running a subscription can't
+  double-subscribe. External public callers may subscribe and unsubscribe
+  only.
+- Only the declaring class and subclasses may invoke it (as a statement) or
+  call `this.OnUpdated.Clear()`. `Clear()` follows the member's storage and
+  writability. An action is never a value, a return type, or assigned with `=`.
+- A nested default such as `Watcher = new() { OnTally = [Handle] }` may
+  target an inherited generic method on the enclosing instance and binds to
+  that instance. Explicit receivers keep their captured instance.
+- An instance-bound listener reachable from a stable root keeps its path
+  (`[root.Assets.OnDamage]`). Pull refuses a bound receiver with no
+  deterministic `root.*` path.
+
+## OnChanged on fields
+
+```neo
+owner.Field.OnChanged += receiver.Handler;
+owner.Field.OnChanged -= receiver.Handler;
+owner.Field.OnChanged.Clear();
+```
+
+The field must be a writable stored instance member. Handlers are
+noncapturing, return void, and accept the field's type. Bindings to Session
+receivers stay Session-only. Gameplay hosts dispatch after the write batch;
+authoring, replay, migration, and dialogue dry-run hosts keep the wiring but
+never call handlers. `Clear()` removes every handler, `@listeners` defaults
+included, in both Save and Session wiring.
+
+## OnChanged on getters
+
+`this._quantity.Value.OnChanged += this.QuantityChanged` subscribes to an
+instance getter. The subscription lives in memory for the play session, so
+subscribe from a function, effect, lifecycle hook, or dialogue action, never
+a constructor, initializer, or migration.
+
+- Subscribing reads the getter once. The handler then gets a fresh result
+  whenever a dependency changes, even if the result is equal; several changes
+  before the next call produce one call.
+- `Clear()` ends it; constructors can't call it on a getter. Static getters,
+  `base.Value`, and `@listeners` can't observe getters.
+- `neo test` dispatches after each test-body statement, so the next statement
+  sees handler effects. Getters reading through `Clone()` or grid queries may
+  fire more often there than in Unity. Other TypeScript hosts validate but
+  never call handlers.
+
+## Persisted wiring
+
+```neo
+@listeners(Count: [root.Save.Tracker.CountChanged], Label: [root.Save.Tracker.LabelChanged])
+new Counter()
+```
+
+Each named argument must be a writable stored field; order is free. For a
+virtual owner, use the existing nested positional override; changing only
+its listeners must not add a value override. An omitted field inherits its
+listeners. `[]` suppresses inherited listeners and disappears when nothing is
+inherited.

package/skills/neocompose-cli/references/neoscript/math-and-random.md

@@ -0,0 +1,114 @@
+# Math and random
+
+Numeric types, operators, `Math`, `NeoRandom`, and vector/Color math.
+
+## Numeric types
+
+`int` retains whole-number precision; division truncates toward zero.
+`float` literals, stored values, and
+every float arithmetic step round to 32 bits, matching Unity. `decimal` is
+exact base-10; use it for currency and other values that must not drift.
+Float literals use `0.5`, not `0.5f`; decimal literals use `0.5m`.
+
+## Bitwise operators
+
+`~`, `&`, `^`, `|`, `<<`, `>>`, `>>>` and their compound forms take
+non-nullable `int` operands only. Enums, bools, float literals such as `1.0`,
+and decimals are rejected; use `Set<Enum>` for enum membership.
+
+```neo
+int mask = (region << 8) | (tile & 255);
+mask &= ~2;
+```
+
+Operands wrap to signed int32 and every result is signed int32. Shift counts
+use their low five bits (32 means 0, -1 means 31). `>>` extends the sign;
+`>>>` fills with zero but still returns signed, so `-1 >>> 1` is 2147483647.
+Operands evaluate once, left to right. Write shifts without spaces
+(`x >> 1`, never `x > > 1`).
+
+Precedence, tightest first: unary, switch expressions, `* / %`, `+ -`, shifts,
+comparisons, equality and `is`, `&`, `^`, `|`, `&&`, `||`, `??`, `?:`.
+
+## Math
+
+`Math` has C# names and semantics: `Min`, `Max`, `Clamp`, `Round`, `Floor`,
+`Ceiling`, `Truncate`, `Abs`, `Sign`, `Sqrt`, `PI`, `E`.
+
+```neo
+return Math.Clamp(this.Quality + bonus, 0, 10);
+```
+
+Results follow the argument types: all-`int` gives `int`, any `float` gives
+`float`, any `decimal` gives `decimal`, and `decimal` never mixes with `float`.
+`Round`, `Floor`, `Ceiling`, and `Truncate` are the float-to-int conversions:
+they return `int` for int/float input, keep `decimal` as `decimal`, and throw
+on non-finite input. `Round` rounds midpoints to even. `Sign` returns `int`;
+`Sqrt` takes int or float only.
+
+`Pow`, `Exp`, `Log`, `Log10`, `Sin`, `Cos`, `Tan`, `Asin`, `Acos`, `Atan`,
+`Atan2(y, x)`, `Lerp`, `InverseLerp`, `MoveTowards`, `Repeat`, and `PingPong`
+take int/float and return float, rounding int inputs to float32 first.
+Decimal and nullable operands are rejected. Angles are radians. `Lerp` and
+`InverseLerp` clamp to [0, 1]; a negative `MoveTowards` delta moves away;
+`Repeat`/`PingPong` need finite t and a finite positive length.
+
+`Math` is a builtin qualifier, not a value. No class, enum, parameter, or
+local may shadow it, but a qualified member may be named `Math`
+(`this.Math`).
+
+## Random
+
+```neo
+NeoRandom.Seed = 17;                 // reset the shared stream
+int index = NeoRandom.Range(0, items.Count);
+float chance = NeoRandom.Value();
+var weather = new NeoRandom(42);     // independent stream; seed required
+float temperature = weather.Range(-1.0, 1.0);
+```
+
+- Shared and instance streams have the same methods. Keep an instance in a
+  field when calls should share its progress; constructing it inside each call
+  restarts from the seed.
+- `Value()` includes 0 and 1. Int `Range(min, max)` excludes max; float
+  `Range` includes both bounds. Equal bounds consume no draw. Reversed int
+  bounds still include the original min and exclude the original max;
+  reversed float bounds swap.
+- Int bounds must fit int32, float bounds must be finite, seeds must be safe
+  integers. Reading `Seed` returns the assigned value; every assignment
+  restarts the stream.
+- Stream progress and reseeding last for the session only. Getters that read
+  `Seed` refresh after reseeding; getters that only draw cache normally.
+- Stored initializers replay independently of gameplay streams. A
+  construction that drew random values keeps its owned values as overrides
+  until it is edited or rebuilt.
+
+For repeatable runs pass a signed decimal seed: `neo test --seed 17` or
+`neo script eval --seed 17 --returns float 'return NeoRandom.Value();'`. Each
+test gets a fresh stream shared by its hooks and body. Without `--seed`, tests
+use the project-fingerprint seed printed in the report and other sessions use
+host entropy.
+
+## Vectors and Color
+
+`Vector2`, `Vector3`, `Vector2Int`, and `Vector3Int` support `+`, `-`, unary
+`-`, scalar multiply in either order, and scalar divide. Both vector operands
+must be the same type. Int vectors take only int scalars and truncate on
+division; float vectors take int or float. Division by zero throws. `==` is
+exact component equality. Int vectors never convert implicitly to float
+vectors.
+
+```neo
+Vector2 heading = (target - position).normalized;
+Vector2 step = Vector2.MoveTowards(position, target, speed);
+```
+
+Every vector has read-only `magnitude` and `sqrMagnitude`, static `Distance`,
+`Min`, `Max`, and constants `zero`, `one`, `up`, `down`, `left`, `right` (3D
+adds `forward`, `back`). Float vectors add `normalized`, `Dot`, `Lerp`, and
+`MoveTowards`; `Vector3` adds `Cross`. `normalized` returns zero at magnitude
+0.00001 or less.
+
+`Color.Lerp(a, b, t)` interpolates all four channels. Vector and Color `Lerp`
+clamp t to [0, 1]. Arithmetic results and constants are fresh values;
+component writes keep the ordinary vector aliasing rules.

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

@@ -0,0 +1,113 @@
+# NeoScript
+
+NeoScript is C#-shaped, statically typed, and sandboxed. This page holds the
+rules every body follows. Open a leaf from [References](#references) only when
+the task uses that API.
+
+## Bodies live inline
+
+Write getters, setters, functions, constructors, dialogue logic, and group
+logic inline in their owning `.neo` or `.neoflow` declaration. Never create
+`Scripts/<Class>/<Member>.neo` sidecars.
+
+```neo
+public bool HasVisited => this.VisitCount > 0;
+
+public int Clamped {
+  get => Math.Clamp(this.Raw, 0, 10);
+  set(int value) { this.Raw = value; }
+}
+
+public bool Unlocked(int level) => this.Level >= level;
+```
+
+- `=> expr;` is sugar for a one-`return` block, on getter-only properties,
+  accessors, and functions. In a void context it must call or assign
+  (`void Ping() => this.OnUpdated();`). Pull writes one-line single returns as
+  `=>` and keeps setters as blocks; push keeps whichever form you wrote.
+- `=>` after an `=` initializer is a NeoFlow destination, not a body.
+- A property has at most one getter and one setter. Setters are
+  `set(int value) { ... }` with the property type and the name `value`; an
+  empty body is a valid no-op.
+- Bodyless members must be `abstract` (`public abstract int Count { get; }`,
+  even in an abstract class), `native` (host-provided only), or interface
+  contracts. `async` alone is not enough. Use a field such as
+  `public int Count = 0;` for stored data.
+- In an override, `base.Member(args)` or `base.Property` calls the nearest
+  ancestor implementation with the same `this`. `base` outside an override,
+  on an abstract member, for base constructors, or for stored-field reads is
+  an error.
+
+## Names and calls
+
+- Inside a class body, unqualified names resolve against that class.
+- Calls may be statements even when they return a value; the result is
+  discarded (`this.Items.Remove(item);`).
+- `new MissingClass(5)` needs a declared type everywhere. Contextual `new(...)`
+  uses the expected type.
+- An error inside a referenced initializer is reported at that initializer's
+  own file and position. Fix it there, not at the `Reference(...)` use.
+
+## Nullability
+
+Never access a nullable receiver directly. Narrow with a condition, or use
+`?.`, `??`, or `!` when failure is intended:
+
+```neo
+if (player.Target != null) {
+  return player.Target.Name;
+}
+return player.Target?.Name ?? "Unknown";
+```
+
+Narrowing details, `is` patterns, and interface guards are in
+[types and narrowing](types-and-narrowing.md).
+
+## Identity and writes
+
+- `==`, `Contains`, `IndexOf`, and `Remove` compare classes, interfaces, and
+  collections by identity, and primitives, enums, vectors, and media by value.
+- Runtime ownership decides whether a write is allowed: Immutable, Save,
+  Session, setter, or otherwise writable. The body kind does not.
+  A constructor writes only its own `this`. A structured-leaf field inherits
+  its receiver's storage.
+- Object initializers work in bodies and specs:
+  `var tile = new DirtWetTile { Cell = Vector2Int(3, -2) };`. Entries that
+  settle required members run with construction; the rest are ordinary
+  assignments in source order.
+
+## Check your work
+
+Run `neo script check --all` or `neo test` after NeoScript edits. Both build
+the prospective project from local source, so new code needs no push first.
+
+## References
+
+Read only the leaf the task needs:
+
+- [Math and random](math-and-random.md): numeric types, bitwise operators,
+  `Math`, `NeoRandom` streams and seeds, vector and Color math.
+- [Strings](strings.md): string members, `Parse`/`TryParse`, number formats.
+- [Collections](collections.md): LINQ-style queries, reductions, ordering,
+  `Insert`/`Remove`/`Sort`, `List.Repeat`, membership equality.
+- [Control flow](control-flow.md): `?:`, loops, dictionary deconstruction,
+  switch statements and expressions, try/catch/finally, error types.
+- [Types and narrowing](types-and-narrowing.md): null and type narrowing,
+  patterns, `Equals`, generic functions and inference, tuples.
+- [Delegates and listeners](delegates-and-listeners.md): lambdas, method
+  groups, `NeoAction`, `OnChanged` subscriptions, `@listeners`.
+- [Checking, testing, and migrations](testing-and-migrations.md):
+  `neo script`, `neo test`, `Debug`, `neo migrate`.
+
+Related branches:
+
+- [References](../values/references.md): `Reference<T>` handles and slots.
+- [Extensions](../declarations/extensions.md): typed receiver functions and computed properties.
+- [Overloads](../declarations/overloads.md): declaring and calling overloads.
+- [Constructors](../declarations/constructors.md) and
+  [initializers](../declarations/initializers.md): construction order and
+  what member defaults may read.
+- [Dialogues](../dialogues.md#triggering-dialogues-from-neoscript):
+  `TryTrigger`, `CanTrigger`, visit counts.
+- [Grids and cell patterns](../world/grids-and-cell-patterns.md):
+  `GetObjects`, `GetTiles`, `GetArea`.

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

@@ -0,0 +1,47 @@
+# Strings, parsing, and formatting
+
+## String members
+
+Strings have `Length`, `Substring(startIndex[, length])`, `IndexOf`,
+`LastIndexOf`, `Replace(search, replacement)`, `Split(separator)`,
+`PadLeft`/`PadRight(totalWidth[, paddingChar])`, `Trim`, `TrimStart`, and
+`TrimEnd`, plus statics `string.Join(separator, values)`,
+`string.IsNullOrEmpty`, and `string.IsNullOrWhiteSpace`.
+
+- Lengths and indices count UTF-16 code units. Every comparison is ordinal and
+  case-sensitive. Whitespace is C#'s `char.IsWhiteSpace` set.
+- `Replace` replaces every non-overlapping match and returns a new string. The
+  search must be nonempty and neither argument may be null.
+- `Split` keeps empty entries and returns a new list.
+- `Join` takes `List<string>` or `Set<string>`. Convert other entries first:
+  `values.Select(v => $"{v}")`.
+- `s?.Length` is an error. Use `string.IsNullOrEmpty(s)` or narrow first.
+
+```neo
+List<string> parts = this.Text.Trim().Split(" ");
+int quantity = int.TryParse(parts[1]) ?? 0;
+return $"{slot.ToString("D3")} {price.ToString("N2")}";
+```
+
+## Parsing
+
+`int.Parse`, `float.Parse`, and `decimal.Parse` accept ASCII digits with an
+optional sign (plus a fraction for float/decimal and an exponent for float)
+after trimming ASCII whitespace. They throw on anything else or on a value the
+type can't hold; `TryParse` returns `null` instead. `decimal.Parse` never
+rounds: more than 28 significant or fractional digits is an error.
+
+## Formatting
+
+Numbers format only with an explicit format: `D<n>` (int only, zero-padded),
+`F<n>` (fixed point), or `N<n>` (fixed point with `,` grouping). `n` is 0 to
+28 and defaults to 2 (1 for `D`). Float rounds half to even from its exact
+value, decimal rounds half away from zero, and an all-zero result has no `-`.
+For plain text, interpolate: `$"{value}"`.
+
+## Int-to-float conversion
+
+An int assigned to `float` rounds to float32. This applies to arguments,
+returns, collection entries, `List.Repeat` with a float entry type, and int
+search arguments to `Contains`/`IndexOf` on float collections. Nullable
+assignments keep `null`.

package/skills/neocompose-cli/references/neoscript/testing-and-migrations.md

@@ -0,0 +1,73 @@
+# Checking, testing, debugging, and migrations
+
+## Script commands
+
+```sh
+neo script check --all
+neo script check --this Outpost --returns string 'return $"{this.Name}!";'
+neo script check --mode setter --member ComputedName 'root.Session.Name = value;'
+neo script check --mode nsfunction --member Outpost.RefreshUnlock 'return this.Level > 0;'
+neo script compile --mode nsfunction --member Outpost.RefreshUnlock 'return this.Level > 0;'
+neo script eval --returns string 'return root.Assets.Outposts[0].FullDisplayText;'
+neo script eval --function Outpost.RefreshUnlock --this-value <id> --args '[3]'
+neo script eval --function "Inventory.Add(Item, int)"
+```
+
+Prefer `--json` in automation. `check --all` rebuilds the prospective project
+from local source only, including dialogue, migration, and text-variable
+bodies, so new declarations need no prior push or network fetch. `eval` uses
+authored values and the web evaluator, reports effects, and never commits
+them. A signature selects one overload of an overloaded function.
+
+## neo test
+
+`neo test` compiles the complete pending candidate, including idless nested
+construction rows, and validates the graph. Tests must pass before the first
+push; do not add IDs or push to get compiled initializer bodies. Invalid
+production source stops the run. It skips the extra source round trip that
+`neo push --dry-run` performs.
+
+- Specs live in colocated `*.spec.neo` files that never sync. Object
+  initializers work there as in bodies.
+- Files run in parallel on up to four CPU workers. Set `test.maxWorkers` in
+  `neo.json`, pass `--maxWorkers <n>`, or `--runInBand`. Hook and test order
+  within a file is preserved; fixtures and mocks stay isolated.
+- `--seed <n>` replays `NeoRandom`; see [math and random](math-and-random.md#random).
+- Unchanged project and spec inputs reuse local caches. JSON
+  `timings.executeMs` and `timings.workerStartupMs` give elapsed phase times;
+  summed worker time can exceed them.
+- Mock or spy on an overloaded function by naming its delegate type:
+  `mock.function<NeoDelegate<int, Item, int>>(Pricing.Quote)`.
+
+## Debug output
+
+`Debug.Log`, `Debug.LogWarning`, and `Debug.LogError` are void statements.
+`Debug.Assert(condition, message)` logs when the condition is false. None of
+them throw. Assert evaluates both arguments every time, even when a host sink
+is disabled.
+
+```neo
+Debug.Assert(this.Items.Any(), "Expected at least one item");
+```
+
+Messages carry NeoScript line/column locations and stack frames when source
+metadata exists. The CLI logs to stderr so JSON stdout stays parseable.
+Getter re-evaluation can log again. `Debug` is a builtin qualifier; an
+authored local or class named `Debug` wins.
+
+## Migrations
+
+Migrations are tracked action files under `Migrations/`:
+
+```sh
+neo migrate new <name> --target <ClassName|project>
+neo migrate list
+neo migrate check
+neo migrate run [--dry-run] [--skip-invalid]
+neo migrate prune
+```
+
+Run `check` first. Review storage ownership and every write; compiling does
+not make an action writable. `run` reads the project from the server and
+prepares writes locally like push. If another commit lands meanwhile, it is
+refused; run it again.