@neocompose/cli 0.27.1 → 0.29.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@neocompose/cli",
-  "version": "0.27.1",
+  "version": "0.29.0",
   "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.27.1 -->
+<!-- reviewed-through-cli: 0.29.0 -->
 
 # Neo Compose CLI
 

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

@@ -109,12 +109,14 @@ override replaces the whole leaf.
 Frame overrides may change `Enabled`, `FlipX`, and `SortingOrder`; they may
 not add, remove, or reorder `Children`.
 
-Address direct children through selector delegates. A selector should implement
-the project's own stable identity contract, such as an immutable `Name`, slug,
-or semantic position; do not turn a mutable object-row ID back into identity by
-returning `Reference<T>(id: "...")`. Missing optional child slots are skipped
-with diagnostics when the authored slot is absent, while stale pre-provenance
-placements may still fail closed.
+Address direct children through selector delegates. Prefer the project's own
+stable identity contract, such as an immutable `Name`, slug, or semantic
+position. When a selector means one specific authored child slot whose
+placement clones carry `sourceValueId`, return
+`Reference<T>(id: "<authored-child-id>", withProvenance: true)`. The flag is
+opt-in and defaults to `false`; without it the ID is matched exactly. Missing
+optional child slots are skipped with diagnostics when the authored slot is
+absent, while stale pre-provenance placements may still fail closed.
 
 A placement row carries its `assetClassId` binding and optional `assetValueId`
 override beside its schema keys. They are row provenance, not declared schema:
@@ -176,11 +178,11 @@ class LegPart : NeoObject {
 ```
 
 Selectors may also be compatible inline closures. Prefer a named function when
-the identity rule is reused or deserves an explicit failure message. Never use
-a selector merely to wrap `Reference<T>(id: "...")`; that recreates the
-row-ID coupling selectors were introduced to remove. For new track rows, omit
-`@id` and let the successful push assign it. Preserve IDs already present on
-pulled rows.
+the identity rule is reused or deserves an explicit failure message. An exact
+`Reference<T>(id: "...")` recreates the row-ID coupling selectors were
+introduced to remove; use `withProvenance: true` only for a deliberately
+authored slot identity. For new track rows, omit `@id` and let the successful
+push assign it. Preserve IDs already present on pulled rows.
 
 A selector argument such as `this.SelectPants` is evaluated in the lexical
 scope of the class that declares the clip. Here `this` is the `LegPart`, not

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

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

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

@@ -152,6 +152,41 @@ them from member initializers. Each declared constructor must settle every
 required member on its own; a call-site block cannot repair an invalid
 constructor declaration.
 
+## Parameter default values
+
+Default a parameter with `= <constant>` on class headers, declared
+constructors, native functions, NSFunctions, and interface functions:
+
+```neo
+class Foo(string bar = "BAR", int volume = 3) {
+  public string Bar = bar;
+
+  public string Shout(string text = "hey", bool loud = true) {
+    return loud ? text.ToUpper() : text;
+  }
+}
+
+Foo a = new();                 // fully defaulted header: all defaults apply
+Foo b = new(bar: "bar");       // volume fills from its default
+```
+
+Use only constants: bool, int, float, and decimal literals (optional leading
+`-`), string literals without interpolation, leading-dot enum options
+(`.North`), and `null` on a nullable parameter. Place every defaulted
+parameter after every non-defaulted one. `Type? name` stays nullable-and-
+mandatory unless it also declares a default — nullability and defaultedness
+are independent.
+
+Omit defaulted arguments at call sites: function calls bind positionally and
+drop only a trailing suffix; constructor calls name a subset that covers
+every non-defaulted parameter. When several overloads match, the one filling
+in the fewest defaults wins, and a residual tie is a declaration-time error.
+Implementations of an interface function restate its defaults exactly.
+
+Do not default parameters of deferred functions, delegates, actions,
+closures, or overrides. Enum defaults store the option id, so renaming the
+option changes the emitted `.Option` spelling without a record change.
+
 ## Required constructors and settlement
 
 Put one required constructor on the class header when the entire class body

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

@@ -83,6 +83,7 @@ supports:
 Reference(Assets.Capitol)
 Reference(root.Assets.Cosmetics.Pants)
 Reference<Outpost>(id: "capitol-value-id")
+Reference<NeoSpriteObject>(id: "authored-child-id", withProvenance: true)
 Reference<PantsAsset>(key: "pants.long")
 Reference<PantsAsset>(key: "pants.long", index: Slug)
 Reference<Dialogue>(id: "capitol-dialogue-id")
@@ -95,14 +96,20 @@ Reference<Dialogue>(id: "capitol-dialogue-id")
 - Use the generic `id:` form when the ID is the only target information. A
   `Reference` call whose argument is neither `id:` nor `key:` is rejected by
   name rather than read as an ID.
+- Inside executable NeoScript, add `withProvenance: true` when the ID names an
+  authored row and the reference must select its nearest `sourceValueId` clone
+  in the lexical receiver's ownership graph. The parameter defaults to `false`;
+  absent or explicit `false` keeps exact-ID behavior. This option is not a
+  persisted member-default form.
 - Both forms are legal in a member's declaration default, not only inside a
   value graph. A key written there resolves after every pass has run, so it may
   name a row the same push creates.
 - Keep genuine structural references ID-based when their collection has no
   stable symbol, path, or key surface. Animation track and frame-override
   targets are selectors, not structural references: encode a stable
-  project-owned identity such as `Name` or slug in the selector instead of
-  wrapping a row ID in `Reference<T>(id: "...")`.
+  project-owned identity such as `Name` or slug. The exception is an authored
+  child slot whose placement clones retain `sourceValueId`: select that slot
+  with `Reference<T>(id: "...", withProvenance: true)`.
 
 Declaration and file order do not affect resolution within one push. Cyclic
 identity references are legal because they resolve IDs rather than evaluate a