@neocompose/cli 0.75.2 → 0.76.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@neocompose/cli",
-  "version": "0.75.2",
+  "version": "0.76.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.75.2 -->
+<!-- reviewed-through-cli: 0.76.1 -->
 
 # Neo Compose CLI
 
@@ -211,8 +211,12 @@ copies, use the editor's duplicate action or copy the initializer without IDs.
 Scalars may have several owners. If those values diverge in web, pull keeps
 the different server values by inlining the differing uses. Initializer
 aliases are local source organization, not runtime globals or server records.
-Use their names as complete value initializers; executable expressions such as
-`BASE + 1` cannot access these local declarations.
+Complete member and collection entries compose owned values, including inside
+constructor-backed initializers. A class local used as a constructor argument or
+executable operand refers to its single stored instance. Nested targets need an
+existing `@id` or an authored UUID-v4; a direct static owner supports pending IDs.
+Scalar executable expressions such as `BASE + 1` still require inlining the
+scalar expression. Locals are unavailable inside executable closures.
 The shared editor offers extract-to-file on a selected complete initializer,
 inline on its sole use, and duplicate at a use. Move the created file freely.
 

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

@@ -66,8 +66,9 @@ new GlassFloorTile { Cell = new(9, -4) }
 
 Layer-link `Tiles` lists contain these values directly. `NeoTileInstance` and
 `@tile(...)` are removed. A tile's `Name`, `Sprite`, and `SmartTile` are
-`readonly` declaration members. Override them on a subclass; a placement
-initializer cannot assign them. `Cell` is the placement's writable field.
+class-level `readonly` members: tiles render per class, so override them on a
+subclass. Push rejects a placement that sets them. `Cell` is the placement's
+writable field.
 
 Object `PlacementTiles` is a `List<NeoPlacementTile>`. Each entry marks a
 footprint cell with its own `Cell` member. It is independent of `NeoTile`. Rendered

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.75.2 -->
+<!-- reviewed-through-cli: 0.76.1 -->
 ```
 
 The quoted version above is checked too, so this instruction cannot go stale

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

@@ -166,6 +166,30 @@ a User class reads only `root.User`. Other code reads `root.User` but can't
 assign, mutate, construct, or invoke User data. Lookups and listeners don't
 cross between User and Save data; Session lookups may target `root.User`.
 
+`readonly` is init-only, as in C#, and independent of storage. A field
+initializer, a constructor body, an object initializer block, or an authored
+value sets it; nothing writes it after construction. It is valid on Save,
+Session, Immutable, and User classes, but not with Writable storage. It may
+read a header parameter:
+
+```neo
+class MixerGroup(string name) {
+  public readonly string Name = name;
+  public readonly List<MixerChannel> Children = [];
+  public float Volume = 1;
+}
+```
+
+Readonly is shallow. A readonly collection's membership is fixed, while its
+entries' members follow their own storage and mutability. User class members
+still declare no storage.
+
+A readonly member declared as a literal (no initializer or constructor call)
+that reads neither `this` nor a constructor argument and holds nothing
+writable is a constant. Instances share its declared value and store nothing
+until a constructor or initializer block writes it. A readonly collection or
+initializer is still built per instance.
+
 `@index(member: Field, kind: .Unique)` and
 `@column(member: Field, width: ..., visibility: ..., pin: ..., overflow: ...)`
 are repeatable List annotations. `member:` is a bare field name on the entry
@@ -369,8 +393,8 @@ Accept settlement only from:
 
 1. The member's own initializer expression.
 2. Assignment on every reachable path in `init` or a constructor body.
-3. A call-site initializer entry when using an otherwise valid construction
-   path.
+3. A call-site initializer entry, in value source and NeoScript bodies alike,
+   when using an otherwise valid construction path.
 
 Do not infer settlement from a side effect inside another function. Require
 full `if`/`else` coverage when an assignment is conditional.
@@ -434,7 +458,22 @@ class PlacedItem<
 }
 ```
 
-Executable object initializer blocks can set immutable stored members on the newly constructed instance, including nested `new` expressions. Ordinary assignments after construction remain subject to storage restrictions. `readonly` declarations still change only through class defaults.
+Object initializer blocks can set `readonly` members of the newly constructed
+instance, including nested `new` expressions. Ordinary assignments after
+construction remain subject to storage and `readonly` restrictions.
+
+Runtime construction never supplies an Immutable member: an initializer block,
+constructor body, base-clause argument, or generated C# factory cannot set one.
+The value is never stored with the instance. When the declaration, including
+every row it owns, reads neither `this` nor a constructor argument, and no
+value of its type holds a writable member, the member is a constant and every
+instance shares one value. Otherwise each instance evaluates the declared
+initializer with its own `this` and constructor arguments, again after a
+reload. A method group such as `selector: SelectTorso` binds `this`.
+`Clone()` shares an authored Immutable value or a constant and re-evaluates a
+per-instance one. A class with a required Immutable member and
+no initializer cannot be constructed at runtime; only authored values construct
+it.
 
 Populated unordered member defaults, such as `@settings(kind: .Unordered)` with
 `List<Entry> Entries = [new Entry()]`, are constructed by an initializer for

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

@@ -154,9 +154,10 @@ Object initializers are available in method bodies and `.spec.neo` tests:
 var tile = new DirtWetTile { Cell = Vector2Int(3, -2) };
 ```
 
-Construction runs first. Each initializer entry then uses ordinary assignment
-rules in source order, including property setters, access checks, and readonly
-restrictions. Initializer expressions read the caller's scope.
+An entry that settles a required member is evaluated with construction, as the
+constructor argument it stands in for. The remaining entries then use ordinary
+assignment rules in source order, including property setters, access checks,
+and readonly restrictions. Initializer expressions read the caller's scope.
 
 ## Nullability and ownership
 

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

@@ -90,6 +90,45 @@ formatting moves its ID above the declaration. Do not put an ID in both places.
 A local initializer such as `Delivery DeliveryRow = new()` retains `Delivery`
 when consumed by a base-class member. Aliases retain that same concrete type.
 
+Complete local member and collection initializers also work inside constructions
+that execute a constructor. Each local composes its owned subtree and preserves
+its concrete class:
+
+```neo
+AudioFolder SFX_FOLDER = new("Sound effects") {
+  Children = [UI_VOLUME, GAMEPLAY_VOLUME]
+};
+AudioSettings AUDIO_SETTINGS = new() { Main = SFX_FOLDER };
+```
+
+In constructor arguments and executable operands, a class local names its one
+stored instance instead of constructing a copy:
+
+```neo
+@id("86ac7c7d-8d3b-4642-9def-cdf32643bdc5")
+DeliveryQuest HARD_AS_STONE = new();
+// The core quest list owns HARD_AS_STONE.
+WorkflowStep UNLOCK = new QuestUnlockStep(HARD_AS_STONE);
+```
+
+The referenced local must have exactly one owning placement. A nested target
+needs its existing `@id`. A structurally owned list entry can also use an unused
+UUID-v4 in the same push. For a local nested inside an evaluated constructor,
+leave it idless on the first push; push assigns its actual identity before it can
+be referenced. Do not assign a fresh UUID to that nested construction. A direct static owning member can supply an idless local's pending identity.
+Aliases of that static local work too. A member default is a construction template,
+so its local does not identify a single stored instance. Unowned locals, ambiguous
+placements, and cycles are errors at source. Constructor argument type checking
+still applies. Canonical construction arguments may use `Reference<Type>(id: "…")`.
+
+Owned locals inside evaluated initializers need directly addressable fields, list
+entries, or literal dictionary keys; inline the construction when a computed key
+or other executable expression prevents tracking its owning path.
+
+Scalar locals remain complete-initializer bindings; inline their expressions when
+using them in arithmetic or constructor arguments. Closure bodies cannot capture
+project authoring locals.
+
 Nested class/list rows remain independently addressable and keep inline IDs:
 
 ```neo