@neocompose/cli 0.87.2 → 0.88.0

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,112 @@
+# 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.
+- [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.

package/skills/neocompose-cli/references/neoscript/types-and-narrowing.md

@@ -0,0 +1,111 @@
+# Types, narrowing, and tuples
+
+Null and type narrowing, patterns, equality, generic functions, and tuples.
+
+## Null narrowing
+
+- Null propagation continues through later required accesses in the same
+  chain: `config.Hat?.Head.Idle.Down.Frames` is null when `Hat` is null. A
+  nullable descendant still needs its own `?.`, `??`, `!`, or guard.
+- `Member` and `this.Member` share narrowing. A local or parameter named
+  `Member` shadows the member; `this.Member` still names the field.
+- Reassigning a narrowed path to a nullable value clears its facts and its
+  descendants' facts. Writes to unrelated members keep guards, also in loops.
+  A false earlier condition narrows later `else if` conditions.
+- `a ?? b` is non-null when `b` is non-null, including in constructor
+  arguments such as `new Sprite(item.Sprite ?? SpriteInfo.Empty)`.
+- Where a reference is expected, `first ?? fallback` picks the reference; a
+  present reference whose target is null does not select the fallback. In a
+  scalar context the reference reads its target first.
+- Lookup results follow the same rules.
+
+## Type patterns
+
+```neo
+if (item is not BedItem bedItem) {
+  throw "Expected a bed item";
+}
+return bedItem.Name;
+```
+
+- A binding stays in scope after a guard when every path that falls through
+  matched, including when other paths return from a nested block.
+- `value is not T name` binds only where the test is known false: the `else`
+  branch, the right of `||`, or after a rejecting guard. The operand evaluates
+  once. `not` is an ordinary identifier elsewhere.
+- Patterns follow the possible runtime type. An open class can match an
+  unrelated interface through a subclass that implements it; a sealed class
+  without it is a compile-time impossible pattern. A class implements each
+  interface once, so a value known to be `IBox<int>` never passes
+  `is IBox<string>`.
+- An interface guard such as `if (item is not IReceiver) continue;` narrows
+  `item` itself: it keeps its declared class or generic `T` members and gains
+  `IReceiver` members. Later class guards accumulate (`IReceiver` then
+  `Furnace` exposes both). Guards that return, throw, or break work the same.
+- A declaration pattern keeps the original receiver's type too: after
+  `if (item is not IReceiver receiver) return;`, `item` is unchanged and
+  `receiver` exposes `IReceiver`.
+- Generic `is` tests check whether the bound can overlap the tested type.
+- Guards also narrow named globals and static member paths, qualified or not,
+  inherited included. Assignment clears the proof. Closures must guard again
+  because the stored value can change before they run.
+- A generic receiver may call members of its class or interface constraint;
+  nullable receivers still need narrowing.
+
+## Equality
+
+`==`, `!=`, `Contains`, `IndexOf`, and `Remove` compare class, interface,
+List, Set, and Dictionary values by identity. Primitives, enums, vectors, and
+media references compare by value. The static type decides, so an
+unconstrained `T` compares by value.
+
+`Equals(other)` on a non-null generic value calls the runtime class's
+one-argument `bool Equals` (including overrides) when it has one, otherwise
+falls back to value equality. Local sets fall back to comparing current
+entries in insertion order.
+
+## Generic functions
+
+Functions, natives, and interface functions may declare type parameters with
+optional constraints and defaults:
+
+```neo
+public static T? FirstOf<T extends Item = Item>(List<T> items) => items.FirstOrDefault();
+```
+
+- Call with every type argument, omit a defaulted tail
+  (`FirstOf<Seed>(items)`), or omit `<...>` to infer from arguments.
+- Lambda inputs bind first so their returns can infer outputs, as in
+  `Map(seed, (value) => value.Price)`. Defaults fill parameters with no
+  evidence. The expected return type is not evidence. Explicit `<...>`
+  never infers the omitted tail. Conflicting types need explicit arguments;
+  inference does not invent a common ancestor.
+- Function type parameters take no `@id`. Overrides declare the same count,
+  constraints, and defaults but may rename them.
+
+Generic class arguments are invariant through inheritance: `IntBox : Box<int>`
+assigns to `Box<int>`, never `Box<string>`. Typed locals accept generic
+classes (`Box<int> box = new(1);`). Explicit lambda parameter types accept
+the full declaration grammar, including `decimal`, generics, collections, and
+nullables.
+
+## Tuples
+
+```neo
+(int Row, int Col) position = (Row: 2, Col: 3);
+var (row, col) = position;
+(int first, (bool enabled, int _)) = (1, (true, 9));
+var score = positions.Select(((r, c)) => r + c);
+```
+
+- Two or more elements. Labels are optional and don't affect type identity;
+  `Item1`, `Item2`, ... always work. Slots are immutable: replace the tuple.
+- `((r, c)) =>` takes one tuple; `(r, c) =>` takes two parameters. Recursive
+  patterns work in declarations, loop bindings, and lambda parameters. `_`
+  discards. Assignment deconstruction is unsupported.
+- Equality is recursive by element; decimal scale is ignored, classes and
+  collections compare by identity.
+- `(int, int)?` is a nullable tuple; `(int?, int)` has a nullable element.
+
+Stored tuple members are covered in
+[member kinds](../declarations/member-kinds.md#stored-tuples).

package/skills/neocompose-cli/references/sync/branches-and-history.md

@@ -0,0 +1,69 @@
+# Branches, releases, and access
+
+## Branches and releases
+
+```sh
+neo branch list
+neo branch create <name> [--from <ref>]
+neo branch switch <nameOrId>
+neo branch refresh [--dry-run]
+neo merge <branch> [--dry-run] [--migrate]
+neo release cut [--bump major|minor|patch] [--dry-run]
+```
+
+- Branches are copy-on-write forks; releases are immutable snapshots.
+- Switching needs a clean checkout. Unpushed source or binaries, conflicts,
+  source errors, and pending push recovery stop it before anything changes.
+  Push or back up first; `neo pull --force` only when discarding is intended.
+- Creation waits until the durable copy publishes. The source stays readable
+  while copying.
+- The server derives the minimum compatibility bump; a caller may only raise
+  it. Releases need the `release` login profile.
+- In Unity projects using `unityConfigPath`, branch and version switches
+  update `NeoComposeConfig.asset`.
+
+## History
+
+```sh
+neo history inspect
+neo history log
+neo history prune [--project <id|@latest|@current>]
+neo history flatten [--project <id|@latest|@current>] --version <id|@latest|@current>
+neo history apply --plan <plan-id> [--confirm-scope <project-id>[/<version-id>]]
+neo history status --run <run-id>
+neo history resume --run <run-id>
+```
+
+Rewrites need project owner or admin. `prune` and `flatten` only create
+immutable plans. `apply` starts the destructive run once the plan seals;
+production also needs the exact scope confirmation the plan shows.
+
+## Login and credentials
+
+```sh
+neo login [--api <url>] [--profile editor|release] [--save-project <id>]
+neo whoami
+neo logout [--api <url>]
+```
+
+- Inside a workspace these use its `apiBaseUrl`; `--api` wins; outside, the
+  build's default origin. Login prints the origin before storing anything.
+- Tokens use the OS credential store, falling back to a protected file. In CI
+  use `NEO_COMPOSE_TOKEN` or `--token-stdin`. The CLI refreshes its
+  short-lived JWT during long commands.
+- The editor profile can't publish releases; server scopes are the security
+  boundary.
+- `logout` deletes the credential for exactly one origin and revokes the
+  session best-effort.
+- `NEO_COMPOSE_CONFIG_HOME` (absolute path replacing
+  `$XDG_CONFIG_HOME/neo-compose`) and `NEO_COMPOSE_CREDENTIAL_NAMESPACE`
+  (keychain account scope) isolate concurrent environments on one OS user.
+
+## Automation
+
+- Pass explicit project/version IDs and flags, prefer `--json`, and never
+  depend on pickers or confirms. Non-TTY runs never wait for them.
+- Boolean flags are bare switches; `--dry-run=true` is rejected.
+- `--dry-run` exists on push, merge, refresh, branch refresh, release cut, and
+  migrate run; elsewhere it is rejected before any action. `branch create`
+  has none.