@neocompose/cli 0.81.5 → 0.82.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@neocompose/cli",
-  "version": "0.81.5",
+  "version": "0.82.1",
   "description": "Neo Compose native project-source CLI with bidirectional sync.",
   "license": "MIT",
   "type": "module",

package/skills/neocompose-cli/SKILL.md

@@ -9,7 +9,7 @@ description: >-
   `@neocompose/cli` or `node cli/bin/neo.mjs` in the neo-compose repository.
 ---
 
-<!-- reviewed-through-cli: 0.81.5 -->
+<!-- reviewed-through-cli: 0.82.1 -->
 
 # Neo Compose CLI
 

package/skills/neocompose-cli/references/animation-and-world-authoring.md

@@ -229,6 +229,9 @@ NeoLookupVariant<ExampleObject, NeoSortingLayer> Layered = new(
 - `NeoLookupVariant<TObject, TValue>` members retain an unbound lookup handle.
   A plain `NeoVariant<TObject>` member may select one concrete row with
   `.Bind(Reference(...))`; do not bind a row to the lookup-handle member type.
+- Variant selections compare equal with `==` when their target class, variant,
+  and bound lookup row match; repeated reads of `Variants.Base` are equal.
+  `!=` is the inverse, and an unset optional selection remains distinct from Base.
 - `NeoVariantFolder` and `NeoLookupVariantFolder` are top-level authoring
   records, never member or parameter types. Variant handle types are supported
   as the dedicated Variant member kind, but remain invalid as collection entry,

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

@@ -129,7 +129,7 @@ wrappers.
 The marker near the top of `SKILL.md` must exactly match the package version:
 
 ```html
-<!-- reviewed-through-cli: 0.81.5 -->
+<!-- reviewed-through-cli: 0.82.1 -->
 ```
 
 The quoted version above is checked too, so this instruction cannot go stale

package/skills/neocompose-cli/references/commands-and-sync.md

@@ -30,8 +30,7 @@ neo push --dry-run --force-recompile
 ```
 
 `neo status` reports invalid constructor parameters at their `.neo` file, line,
-and column. Fix the reported parameter type before pushing. For example,
-constructor parameters use `Item`; `Reference<Item>` declares member storage.
+and column. Fix the reported parameter type before pushing.
 A failed class or constructor declaration blocks candidate preparation.
 
 Use `neo pull --regenerate-source-names` to replace generated default dialogue
@@ -157,7 +156,9 @@ become real only after acceptance.
 ## Conflicts and files
 
 Conflict resolution accepts LF, CRLF, and mixed line endings. It retains the
-selected source lines and their existing line endings.
+selected source lines and their existing line endings. Choosing a deleted side
+removes the source file; deletion placeholders are display text, not authored
+source. Empty files and ordinary comment-only files remain files.
 
 Resolve source conflicts by editing the final intended source. Use
 `neo resolve --mine` or `neo resolve --theirs` only for a deliberate whole-side

package/skills/neocompose-cli/references/declarations-and-construction.md

@@ -251,17 +251,24 @@ Editing an inline child preserves the outer construction's call-site values for
 its other fields. The child keeps that construction while its variant selection
 matches; selecting a different variant gives it an independent recipe.
 
-Declare a lookup member as `Reference<T>`. `public Reference<Config> Config`
-selects one row and reads as `Config`. `public Set<Reference<Config>> Configs`
-selects several and reads as `Set<Config>`. An initializer body for a single
-reference returns one row, never a set. `T` with `@settings(collection:)` is an
-error; the language server's quick fix respells it.
-
-`@settings(collection: Owner.Member)` binds the reference to one collection.
-Without it the reference is unbound: it selects any stored row of `T` or a
-subclass, anywhere in the project. The selected row's store decides writes. A
-write through it to a Save row lands, and to an asset row it errors. Its
-generated C# property is the read-only interface; call `TryWritable` to write.
+Declare a lookup member as `Reference<T>`. `T` can be any value type except
+code types; see the NeoScript reference for handle and slot references.
+`public Reference<Config> Config` selects one row and reads as `Config`.
+`public Set<Reference<Config>> Configs` selects several and reads as
+`Set<Config>`. `public Reference<int> TrackedStat` names another member's int.
+`Reference<T>` also works as a collection element, a dictionary value, and an
+unbound generic argument such as `Box<Reference<int>>`. An initializer body for
+a single reference returns one row, never a set. `T` with
+`@settings(collection:)` is an error; the language server's quick fix respells
+it.
+
+`@settings(collection: Owner.Member)` binds a class reference to one
+collection. Without it the reference is unbound: it selects any stored row of
+`T` or a subclass, or any member slot of type `T`, anywhere in the project. A
+bound reference can't be a generic argument. The selected row's store decides
+writes. A write through it to a Save row lands, and to an asset row it errors.
+Its generated C# property is the read-only interface; call `TryWritable` to
+write.
 
 An unbound default can name its row by a unique index:
 
@@ -272,6 +279,20 @@ public Reference<Item> StarterSeed = root.Assets.Items.Index.Slug["seed.carrot"]
 The receiver is a `root` path to a List, `.Index.<Name>` is a unique index on
 it, and the key is a string literal. Any other shape stays initializer code.
 
+A slot reference's default wraps a member path in `Reference()`. The path may
+use the same index segments. A plain value isn't a default, and `this` doesn't
+exist yet:
+
+```neo
+public Reference<int> TrackedStat = Reference(root.Player.Gold);
+public Reference<string> Greeting = Reference(root.Npcs.Index.Slug["mira"]!.Greeting);
+public Reference<NeoVariant<Tree>> Look = Reference(root.Garden.Felled);
+```
+
+A `NeoVariant<T>` member's own default stays the bare variant path. A
+`Reference<NeoVariant<T>>` names a member that holds a variant, so its default
+is a `Reference()` member path.
+
 A `Reference<T>` member satisfies an interface `T Foo { get; }` or
 `{ get; set; }` and an abstract `T Foo { get; }`.
 
@@ -287,6 +308,10 @@ element picks the storage:
 - `Set<NeoDialogueReference>` is a multi-select dialogue lookup.
 - Any other element makes an owned Set whose entries are rows, like a List.
 
+Constructor mutations such as `Bag.Add(7)` keep owned collection entries as
+backing rows during export and sparse replay. Existing entries retain their
+identities; added entries receive stable identities under the instance.
+
 An owned Set holds `bool`, `int`, `float`, `decimal`,
 `@settings(format: .Plain) string`, vectors, `Color`, sprites, audio clips,
 or a class. Elements can't be nullable, collections, variants, delegates,
@@ -587,6 +612,9 @@ its own type arguments during first push and stored replay. Editing a nested
 constructor argument rebuilds its projected fields in place, including fields
 stored inside a packed parent; push followed by pull leaves a clean checkout.
 
+Sparse children with their own declared constructor replay that constructor
+when reconciling edits, including when passed as an aggregate argument.
+
 Schema export retains a constructed default's generic arguments, including
 nested collection references. For example, a `NeoAnimationClip<ArmPart>`
 default constructs `new NeoAnimationClip<ArmPart>` and its frames reference

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

@@ -7,6 +7,7 @@ runtime ownership, evaluation, and migrations.
 
 - Inline bodies and snippets
 - Nullability and ownership
+- References
 - Numeric builtins
 - Collection builtins
 - Conditional and logical operators
@@ -276,6 +277,53 @@ Save, Session, Setter, or otherwise writable. A constructor writes only its
 `this` instance. A writable structured-leaf field still inherits the receiver's
 effective storage restrictions.
 
+## References
+
+`Reference<T>` names one stored row. `T` can be any value type, including
+collections and other references. Code types such as `Action<int>` are
+rejected. `T` picks one of two categories:
+
+- A handle is a class, interface, list, set, or dictionary. The reference is the
+  object itself, so `Reference<Item>` reads as `Item`. Assigning an `Item`
+  rebinds it.
+- A slot is any other value type: `bool`, numbers, `string`, enums, vectors,
+  `Color`, sprites, audio clips, `NeoVariant<T>`, `NeoDialogueReference`, or a
+  single `Reference<U>`. The reference names another member and reads and writes
+  that member's value. It converts to its `T` by reading.
+
+`Reference(place)` forms a reference to a stored member, such as `this.Gold`,
+`root.Player.Gold`, `Npc.Mood`, or `item.Count`. Its type comes from the
+member's declaration. When `Selected` is `Reference<Item>`,
+`Reference(this.Selected)` is `Reference<Reference<Item>>` and names the
+selection slot itself. Locals, parameters, list or dictionary elements, vector
+components, getters, query results, and new values have no row to reference.
+Access checks apply where the reference is formed.
+
+Assigning to a reference rebinds it when the right side is a reference of the
+same type. Otherwise the value is written into the target:
+
+```neo
+this.A = 5;                       // writes 5 into A's target
+this.A = this.Count;              // writes Count's value into A's target
+this.A = this.B;                  // A now names B's target
+this.A = Reference(this.Count);   // A now names Count
+this.A += 1;                      // reads A's target, writes it back
+```
+
+A plain value never becomes a reference: passing `3` to a `Reference<int>`
+parameter is an error. A handle reference never owns, so it can't hold a new
+list or a query result.
+
+`==` compares handles by identity and slots by value. A collection of
+references compares entries by target, so a `Set<Reference<int>>` holds
+distinct slots. Narrow a `Reference<T>?` with a null check before writing
+through it.
+
+The target row decides every write. Writing an asset-owned target errors, and a
+`readonly` target can't be written after initialization. A slot reference's
+`OnChanged` listeners fire when it rebinds and when its target's value changes.
+Inside a generic body, `Reference<T>` takes the category of `T`'s binding.
+
 ## Numeric types
 
 `int` is a 32-bit integer and `float` is a 32-bit float, matching C#. Float

package/skills/neocompose-cli/references/values-identities-and-references.md

@@ -180,9 +180,9 @@ is one such row — its identity comes from the schema key its parameter settles
 
 ## Same-push references
 
-`Reference<T>` and `Set<Reference<T>>` declare lookup storage. Their runtime
-values are `T` and `Set<T>`, so a projection can assign existing class values
-directly:
+`Reference<T>` and `Set<Reference<T>>` declare lookup storage. For a class
+`T`, their runtime values are `T` and `Set<T>`, so a projection can assign
+existing class values directly:
 
 ```neo
 EligibleIngredients = root.Assets.Crafting.FurnaceRecipes
@@ -196,12 +196,19 @@ not clone it or turn it into a separate wrapper object. An optional generic
 argument checks the target type. Lookup assignment still requires an existing
 backing row and enforces its declared target and collection constraints.
 
+A class-constrained generic lookup may select from a collection of its bound
+class. For example, `Reference<TAsset>` with `TAsset extends HeldItemAsset`
+may use `@settings(collection: CosmeticAssets.HeldItems)` when that collection
+holds `HeldItemAsset`. Derived classes may specialize the target and override
+the member; retain the collection setting on each override.
+
 Use the `Reference` intrinsic. Prefer the most readable form the target
 supports:
 
 ```neo
 Reference(Assets.Capitol)
 Reference(root.Assets.Cosmetics.Pants)
+Reference(root.Player.Gold)
 Reference<Outpost>(id: "capitol-value-id")
 Reference<NeoSpriteObject>(id: "authored-child-id", withProvenance: true)
 Reference<PantsAsset>(key: "pants.long")
@@ -209,7 +216,9 @@ Reference<PantsAsset>(key: "pants.long", index: Slug)
 Reference<NeoDialogue>(id: "capitol-dialogue-id")
 ```
 
-- Use a symbol or root path when source can name the value directly.
+- Use a symbol or root path when source can name the value directly. A
+  value-type reference such as `Reference<int>` always names a member path or
+  an `id:`; a plain value is an error.
 - Use `key:` only for a collection with a unique index. Omit `index:` when the
   collection has exactly one usable unique index; supply the bare member name
   when it has more than one.