@neocompose/cli 0.89.0 → 0.89.1

package/dist/test-worker.mjs

@@ -22918,8 +22918,12 @@ var FunctionTypeInference = class {
         const value = actual.parameterTypes[index];
         if (value !== void 0) this.add(value, expected, "exact");
       });
-    } else if (pattern.kind === "reference" && actual.kind === "reference") {
-      this.add(actual.target, pattern.target, "exact");
+    } else if (pattern.kind === "reference") {
+      this.add(
+        actual.kind === "reference" ? actual.target : actual,
+        pattern.target,
+        "exact"
+      );
     }
   }
   fix(index) {
@@ -33327,11 +33331,14 @@ function resolveMemberForValueRow(row, ctx, visited) {
       ctx.__valueOverlay
     );
     if (parent === null) continue;
-    const parentMember = resolveMemberForValueRow(
-      parent,
-      ctx,
-      new Set(visited)
-    );
+    let parentMember = resolveMemberForValueRow(parent, ctx, new Set(visited));
+    if (parentMember?.kind === 21 /* Generic */) {
+      parentMember = substituteMember(
+        parentMember,
+        runtimeParentGenericEnv(parent, ctx, /* @__PURE__ */ new Set()),
+        ctx.vm.members
+      );
+    }
     if (parentMember !== null && isMemberTupleBase(parentMember)) {
       const memberId = parentMember.elementMemberIds[Number(link.key)];
       return memberId === void 0 ? null : evalMemberById(ctx.vm, memberId);
@@ -50834,7 +50841,9 @@ function indexCalls(tokens, pairs, lexed) {
     const name = tokens[index];
     const openIndex = callOpenParenIndex(tokens, index);
     const open = tokens[openIndex];
-    if (!name || name.kind !== "identifier") continue;
+    if (!name) continue;
+    const expression = [")", "]", "!"].includes(name.text) && openIndex === index + 1;
+    if (name.kind !== "identifier" && !expression) continue;
     if (!open || open.kind !== "punctuation" || open.text !== "(") continue;
     const previous = tokens[index - 1];
     const targetTyped = isContextualNew(name, previous, open);
@@ -50863,14 +50872,19 @@ function indexCalls(tokens, pairs, lexed) {
         segmentStart = token.end;
         segmentStartIndex = cursor + 1;
       }
+      if (tokens[cursor + 1]?.text === "<") {
+        const genericOpen = callOpenParenIndex(tokens, cursor);
+        if (genericOpen >= 0) cursor = genericOpen - 1;
+      }
     }
     if (segmentStart < (close?.start ?? lexed.end)) {
       ranges.push(lexed.source.range(segmentStart, close?.start ?? lexed.end));
       names2.push(callArgumentLabel(tokens, segmentStartIndex, limit));
     }
+    const namedKind = contextualKeyword ? "constructor" : "function";
     calls.push({
-      kind: contextualKeyword ? "constructor" : "function",
-      name: name.text,
+      kind: expression ? "expression" : namedKind,
+      name: expression ? "delegate" : name.text,
       nameRange: name.range,
       ...contextualKeyword ? { contextualKeywordRange: contextualKeyword.range } : {},
       ...targetTyped ? { targetTyped: true } : {},
@@ -52690,6 +52704,10 @@ var StrictNeoScriptResolver = class _StrictNeoScriptResolver {
     if (expected === void 0) return;
     this.requireAssignable(resolved.type, expected, expression.pos, "value");
   }
+  /** Type a source expression with the same call binding rules as executable code. */
+  resolveExpressionType(expression) {
+    return this.resolveExpression(expression, this.initialScope()).type;
+  }
   persistedListenerCompletions(receiver, expected) {
     const scope = this.initialScope();
     let receiverType = this.context.thisClass;
@@ -54956,8 +54974,7 @@ var StrictNeoScriptResolver = class _StrictNeoScriptResolver {
         );
     }
   }
-  resolveMemberRowOf(place, scope) {
-    const optional2 = place.optional === true;
+  resolveMemberRowOf(place, scope, resolved) {
     if ((this.context.kind === "initializer" || this.context.kind === "initializerExpression") && this.delegateCaptureContexts.length === 0 && referencePlaceRoot(place) === "this") {
       const text = referencePlaceText(place) ?? "this";
       throw new CompileError(
@@ -54965,12 +54982,12 @@ var StrictNeoScriptResolver = class _StrictNeoScriptResolver {
         place.pos
       );
     }
-    const slot = this.resolveMemberNatural(
+    const slot = resolved ?? this.resolveMemberNatural(
       place.receiver,
       place.name,
       scope,
       place.pos,
-      optional2
+      place.optional === true
     );
     const member = slot.symbol;
     if (member === void 0) {
@@ -54988,19 +55005,55 @@ var StrictNeoScriptResolver = class _StrictNeoScriptResolver {
         place.pos
       );
     }
-    const read = slot.optionalChainType ?? slot.type;
-    const stored = member.lookup !== void 0 && member.lookup.multiselect !== true && read.kind !== "reference" ? {
-      kind: "reference",
-      target: { ...read, nullable: false },
-      ...isNullable(read) ? { nullable: true } : {}
-    } : read;
-    const type2 = this.referenceType(stored, optional2);
+    const type2 = this.memberReferenceType(slot, place.optional === true);
     if (type2.kind !== "reference") return slot;
     return {
       pointer: { type: "rowOf" /* RowOf */, place: slot.pointer },
       type: type2
     };
   }
+  memberReferenceType(slot, optional2) {
+    const read = slot.storedType ?? slot.optionalChainType ?? slot.type;
+    const stored = slot.symbol?.lookup !== void 0 && slot.symbol.lookup.multiselect !== true && read.kind !== "reference" ? {
+      kind: "reference",
+      target: { ...read, nullable: false },
+      ...isNullable(read) ? { nullable: true } : {}
+    } : read;
+    return this.referenceType(
+      stored,
+      optional2 || slot.optionalChainType !== void 0
+    );
+  }
+  /** Only stored member slots can acquire a reference from an expected type. */
+  implicitReferenceType(expression, value) {
+    if (expression.kind !== "member") return void 0;
+    if (value.symbol === void 0 || value.symbol.computed === true)
+      return void 0;
+    return this.memberReferenceType(value, expression.optional === true);
+  }
+  referenceInferenceType(expression, value, pattern) {
+    const read = this.readReferences(value, pattern).type;
+    if (pattern.kind !== "reference" || read.kind === "reference") return read;
+    return this.implicitReferenceType(expression, value) ?? read;
+  }
+  contextualReferenceType(expression, value, expected) {
+    const read = this.readReferences(value, expected).type;
+    if (expected.kind !== "reference" || isNeoScriptTypeAssignable(read, expected, this.project))
+      return read;
+    const reference = this.implicitReferenceType(expression, value);
+    return reference !== void 0 && isNeoScriptTypeAssignable(reference, expected, this.project) ? reference : read;
+  }
+  /** Use the same slot identity for explicit and expected-type references. */
+  contextualReference(expression, value, scope, expected) {
+    const read = this.readReferences(value, expected);
+    if (expected?.kind !== "reference" || isNeoScriptTypeAssignable(read.type, expected, this.project))
+      return read;
+    const reference = this.implicitReferenceType(expression, value);
+    if (expression.kind === "member" && reference !== void 0 && isNeoScriptTypeAssignable(reference, expected, this.project)) {
+      return this.resolveMemberRowOf(expression, scope, value);
+    }
+    return read;
+  }
   /** Whether assigning `target` rebinds a reference to a handle. */
   holdsHandleReference(target) {
     if (target.type.kind === "reference") {
@@ -55609,13 +55662,15 @@ var StrictNeoScriptResolver = class _StrictNeoScriptResolver {
     });
   }
   resolveExpression(expression, scope, expected, convertSequence = true) {
-    const value = this.readReferences(
+    const value = this.contextualReference(
+      expression,
       this.resolveReferenceExpression(
         expression,
         scope,
         expected,
         convertSequence
       ),
+      scope,
       expected
     );
     return convertSequence ? this.convertSequence(value, expected) : value;
@@ -57137,7 +57192,8 @@ var StrictNeoScriptResolver = class _StrictNeoScriptResolver {
       }
       entryType = common;
     }
-    if (expected?.kind === "set" && this.context.kind === "initializer") {
+    const referenceSelection = expected?.kind === "set" && this.context.kind === "initializer" && (expected.elementType.kind === "reference" || hasReferenceEquality(expected.elementType, this.project));
+    if (expected?.kind === "set" && this.context.kind === "initializer" && !referenceSelection) {
       const element = expected.elementType;
       const spelling = element.kind === "named" && this.project.typeById.get(element.typeId)?.kind === "enum" ? `.Option or ${this.describe({ ...element, nullable: false })}.Option values` : "literal values";
       throw new CompileError(
@@ -57155,7 +57211,7 @@ var StrictNeoScriptResolver = class _StrictNeoScriptResolver {
         "NeoScript strict compiler produced a non-list wire type for a list literal."
       );
     }
-    return {
+    const list = {
       pointer: {
         type: "listLiteral" /* ListLiteral */,
         typeInfo: wire,
@@ -57164,6 +57220,18 @@ var StrictNeoScriptResolver = class _StrictNeoScriptResolver {
       type: type2,
       entries: resolved
     };
+    return referenceSelection ? this.resolveCollectionQuery(
+      list,
+      {
+        kind: "list",
+        keyType: { kind: "primitive", name: "int" },
+        valueType: entryType
+      },
+      "ToSet",
+      [],
+      scope,
+      pos
+    ) : list;
   }
   resolveDictionaryLiteral(entries, scope, expected, pos) {
     const expectedDictionary = expected?.kind === "dictionary" ? expected : void 0;
@@ -57874,7 +57942,12 @@ var StrictNeoScriptResolver = class _StrictNeoScriptResolver {
         const rootEntry = scope.lookupFlowRoot(pathRoot(path));
         if (rootEntry) {
           const narrowed = scope.lookupNarrowedType(path, rootEntry);
-          if (narrowed) resolved = { ...resolved, type: narrowed };
+          if (narrowed)
+            resolved = {
+              ...resolved,
+              storedType: resolved.type,
+              type: narrowed
+            };
         }
       }
     }
@@ -60593,17 +60666,28 @@ var StrictNeoScriptResolver = class _StrictNeoScriptResolver {
       args,
       scope
     );
-    return resolveNeoScriptDeclaredConstructorOverload(
+    const resolve = (implicit) => resolveNeoScriptDeclaredConstructorOverload(
       declared,
       named.map((name, index) => {
         const inferred = inferredTypes?.[index];
-        if (!inferred) return { name };
+        const argument2 = args[index];
+        if (!inferred || !argument2) return { name };
         return {
           name,
-          matchesParameter: (parameter3) => isNeoScriptTypeAssignable(inferred, parameter3.type, this.project)
+          matchesParameter: (parameter3) => implicit && parameter3.type.kind === "reference" && isContextualReferenceExpression(argument2) ? this.targetTypedArgumentFits(argument2, parameter3.type, scope) : isNeoScriptTypeAssignable(
+            implicit ? this.contextualReferenceType(
+              argument2,
+              inferred,
+              parameter3.type
+            ) : inferred.type,
+            parameter3.type,
+            this.project
+          )
         };
       })
     );
+    const direct = resolve(false);
+    return direct.kind === "ambiguous" ? resolve(true) : direct;
   }
   /**
    * Types for the §6.1.1 step-2 tie-break, computed only when several
@@ -60624,7 +60708,9 @@ var StrictNeoScriptResolver = class _StrictNeoScriptResolver {
       const argument2 = args[index];
       if (!argument2) return null;
       try {
-        return this.resolveExpression(argument2, scope).type;
+        if (isContextualReferenceExpression(argument2))
+          this.typeOverloadEntries(argument2, scope);
+        return this.resolveReferenceExpression(argument2, scope);
       } catch (error) {
         if (error instanceof CompileError) return null;
         throw error;
@@ -60994,7 +61080,8 @@ var StrictNeoScriptResolver = class _StrictNeoScriptResolver {
       (argument2) => this.overloadArgumentKind(argument2, scope)
     );
     argumentsList2.forEach((argument2, index) => {
-      if (kinds[index] !== "typed") this.typeOverloadEntries(argument2, scope);
+      if (kinds[index] !== "typed" || isContextualReferenceExpression(argument2))
+        this.typeOverloadEntries(argument2, scope);
     });
     const typed = argumentsList2.map(
       (argument2, index) => kinds[index] === "targetTyped" ? void 0 : this.resolveReferenceExpression(argument2, scope)
@@ -61042,11 +61129,11 @@ var StrictNeoScriptResolver = class _StrictNeoScriptResolver {
       const fits = argumentsList2.every((argument2, index) => {
         const parameter3 = requiredAt(parameters, index).type;
         const resolved = typed[index];
-        if (resolved === void 0 || argument2.kind === "tuple" || kinds[index] === "numeric" && parameter3.kind === "tuple") {
+        if (resolved === void 0 || parameter3.kind === "reference" && isContextualReferenceExpression(argument2) || argument2.kind === "tuple" || kinds[index] === "numeric" && parameter3.kind === "tuple") {
           return this.targetTypedArgumentFits(argument2, parameter3, scope);
         }
         return this.typedArgumentFits(
-          this.readReferences(resolved, parameter3).type,
+          this.contextualReferenceType(argument2, resolved, parameter3),
           requiredAt(kinds, index),
           parameter3
         );
@@ -61218,6 +61305,12 @@ var StrictNeoScriptResolver = class _StrictNeoScriptResolver {
       }
       case "annotated":
         return this.entryFits(argument2.expression, parameter3, scope);
+      case "coalesce":
+        return this.entryFits(
+          argument2.left,
+          { ...parameter3, nullable: true },
+          scope
+        ) && this.entryFits(argument2.right, parameter3, scope);
       case "conditional": {
         const { trueScope, falseScope } = this.conditionalBranchScopes(
           argument2,
@@ -61297,12 +61390,12 @@ var StrictNeoScriptResolver = class _StrictNeoScriptResolver {
    */
   entryFits(argument2, parameter3, scope) {
     const kind = this.overloadArgumentKind(argument2, scope);
-    if (kind === "targetTyped" || argument2.kind === "tuple" || kind === "numeric" && parameter3.kind === "tuple") {
+    if (kind === "targetTyped" || parameter3.kind === "reference" && isContextualReferenceExpression(argument2) || argument2.kind === "tuple" || kind === "numeric" && parameter3.kind === "tuple") {
       return this.targetTypedArgumentFits(argument2, parameter3, scope);
     }
-    const resolved = isPureArgument(argument2) ? this.resolveExpression(argument2, scope) : this.overloadEntries.get(argument2) ?? this.resolveReferenceExpression(argument2, scope);
+    const resolved = isPureArgument(argument2) ? this.resolveReferenceExpression(argument2, scope) : this.overloadEntries.get(argument2) ?? this.resolveReferenceExpression(argument2, scope);
     return this.typedArgumentFits(
-      this.readReferences(resolved, parameter3).type,
+      this.contextualReferenceType(argument2, resolved, parameter3),
       kind,
       parameter3
     );
@@ -61345,6 +61438,10 @@ var StrictNeoScriptResolver = class _StrictNeoScriptResolver {
       case "annotated":
         visit(argument2.expression, scope);
         return;
+      case "coalesce":
+        visit(argument2.left, scope);
+        visit(argument2.right, scope);
+        return;
       case "conditional": {
         visit(argument2.condition, scope);
         const { trueScope, falseScope } = this.conditionalBranchScopes(
@@ -61529,19 +61626,16 @@ var StrictNeoScriptResolver = class _StrictNeoScriptResolver {
       pos,
       inferred?.typeArguments
     );
-    if (signature.typeArguments.length > 0)
-      this.options.onCallResolved?.(pos, {
-        ...symbol,
-        type: signature.returnType,
-        returnType: signature.returnType,
-        parameters: signature.parameters,
-        typeParameters: (symbol.typeParameters ?? []).map(
-          (parameter3, index) => ({
-            ...parameter3,
-            type: requiredAt(signature.typeArguments, index)
-          })
-        )
-      });
+    this.options.onCallResolved?.(pos, {
+      ...symbol,
+      type: signature.returnType,
+      returnType: signature.returnType,
+      parameters: signature.parameters,
+      typeParameters: (symbol.typeParameters ?? []).map((parameter3, index) => ({
+        ...parameter3,
+        type: requiredAt(signature.typeArguments, index)
+      }))
+    });
     const wireTypeArguments = signature.typeArguments.length ? {
       typeArguments: signature.typeArguments.map(
         (argument2) => toWireType(argument2, this.project)
@@ -61716,7 +61810,12 @@ var StrictNeoScriptResolver = class _StrictNeoScriptResolver {
       const prior = choice?.preResolved[index];
       const cached = inferred?.resolved.get(argument2);
       let resolved;
-      if (prior !== void 0) resolved = this.readReferences(prior, target);
+      if (prior !== void 0 && !(target?.kind === "reference" && isContextualReferenceExpression(argument2) && !isNeoScriptTypeAssignable(
+        this.readReferences(prior, target).type,
+        target,
+        this.project
+      )))
+        resolved = this.readReferences(prior, target);
       else if (cached && (sameCompilationType(cached.type, expected) || cached.pointer.type === "callFunction" /* CallFunction */)) {
         resolved = cached;
       } else {
@@ -61725,6 +61824,7 @@ var StrictNeoScriptResolver = class _StrictNeoScriptResolver {
         const compile = () => this.resolveExpression(argument2, scope, target);
         resolved = weighed ?? (argument2.kind === "lambda" && lambdas ? this.inLambdaFrame(lambdas, argument2, compile) : compile());
       }
+      resolved = this.contextualReference(argument2, resolved, scope, target);
       resolved = this.convertSequence(resolved, target);
       if (!isUnknown(expected)) {
         this.requireReferenceArgument(
@@ -61799,7 +61899,10 @@ var StrictNeoScriptResolver = class _StrictNeoScriptResolver {
       if (!hasIndependentTypeEvidence(argument2)) return;
       const prior = weighed?.typed[index];
       if (prior !== void 0) {
-        inference.add(this.readReferences(prior, void 0).type, pattern);
+        inference.add(
+          this.referenceInferenceType(argument2, prior, pattern),
+          pattern
+        );
         return;
       }
       const group = pattern.kind === "delegate" ? this.inferredMethodGroupTarget(argument2, probe) : null;
@@ -61810,10 +61913,13 @@ var StrictNeoScriptResolver = class _StrictNeoScriptResolver {
           pattern
         );
       } else {
-        const resolved = weighed?.contextless.get(argument2) ?? this.resolveExpression(argument2, probe);
+        const resolved = weighed?.contextless.get(argument2) ?? this.resolveReferenceExpression(argument2, probe);
         weighed?.contextless.set(argument2, resolved);
         resolvedArguments.set(argument2, resolved);
-        inference.add(resolved.type, pattern);
+        inference.add(
+          this.referenceInferenceType(argument2, resolved, pattern),
+          pattern
+        );
       }
     });
     const error = inference.solve(callbacks, (callback, inputs) => {
@@ -64883,7 +64989,7 @@ var StrictNeoScriptResolver = class _StrictNeoScriptResolver {
     }
     return canonicalPath(target) ?? "the slot";
   }
-  /** P112 §3.1. A value never converts to a reference, since it has no row. */
+  /** A transient value has no stored slot to pass by reference. */
   requireReferenceArgument(source, target, parameter3, pos) {
     if (target.kind !== "reference") return;
     if (source.kind === "reference") return;
@@ -64892,7 +64998,7 @@ var StrictNeoScriptResolver = class _StrictNeoScriptResolver {
     const value = this.describe(source);
     const article = /^[aeiou]/i.test(value) ? "an" : "a";
     throw new CompileError(
-      `Argument \`${parameter3}\` needs a ${this.describe(target)}, not ${article} ${value}. Wrap a member path in Reference() to pass a stored ${this.describe(read)}.`,
+      `Argument \`${parameter3}\` needs a ${this.describe(target)}, not ${article} ${value}. Pass a stored ${this.describe(read)} member instead.`,
       pos
     );
   }
@@ -67165,6 +67271,7 @@ function weighedLambda(probes, expected) {
   if (probe === void 0 || probe.type.kind !== "delegate") return void 0;
   if (probe.needsReturnContext !== true && sameCompilationType(probe.type.returnType, expected.returnType))
     return probe;
+  if (expected.returnType.kind === "reference") return void 0;
   return probe.retype?.(expected.returnType);
 }
 function replaceReturns(instructions, replaced) {
@@ -67287,6 +67394,9 @@ function andList(texts) {
   if (texts.length <= 2) return texts.join(" and ");
   return `${texts.slice(0, -1).join(", ")}, and ${texts[texts.length - 1]}`;
 }
+function isContextualReferenceExpression(expression) {
+  return expression.kind === "conditional" || expression.kind === "switchExpression" || expression.kind === "coalesce" || expression.kind === "annotated";
+}
 function isPureArgument(expression) {
   switch (expression.kind) {
     case "litInt":

package/package.json

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

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

@@ -109,7 +109,7 @@ The marker near the top of `SKILL.md` must exactly match the package version,
 and this quoted copy is checked too:
 
 ```html
-<!-- reviewed-through-cli: 0.89.0 -->
+<!-- reviewed-through-cli: 0.89.1 -->
 ```
 
 Keep this skill on current behavior. Upgrade steps, rollout prerequisites,

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

@@ -26,7 +26,8 @@ public Reference<int> TrackedStat;          // another member's int
 
 - `Reference<T>` also works as a parameter, collection element, dictionary
   value, and unbound generic argument (`Box<Reference<int>>`), and keeps that
-  storage type through push and pull. Use `Set<T>` parameters for several
+  storage type through push and pull, including nested generic collections
+  and named tuples. Use `Set<T>` parameters for several
   selections.
 - `@settings(collection: Owner.Member)` binds a class reference to one
   collection. Unbound references select any stored row of `T` or a subclass,
@@ -47,20 +48,31 @@ public Reference<int> TrackedStat;          // another member's int
 
 ```neo
 public Reference<Item> StarterSeed = root.Assets.Items.Index.Slug["seed.carrot"]!;
-public Reference<int> Gold = Reference(root.Player.Gold);
-public Reference<string> Greeting = Reference(root.Npcs.Index.Slug["mira"]!.Greeting);
-public Reference<NeoVariant<Tree>> Look = Reference(root.Garden.Felled);
+public Reference<int> Gold = root.Player.Gold;
+public Reference<string> Greeting = root.Npcs.Index.Slug["mira"]!.Greeting;
+public Reference<NeoVariant<Tree>> Look = root.Garden.Felled;
 ```
 
 - An unbound handle default may name its row by a unique index: a `root`
   path to a List, `.Index.<Name>`, and a string literal key. Other shapes are
   initializer code.
-- Slot defaults wrap a member path in `Reference()`. A plain value is not a
-  default, and `this` doesn't exist yet. A `NeoVariant<T>` member's own
-  default stays the bare variant path.
+- Slot defaults accept compatible stored member paths directly; `Reference()`
+  remains valid. Literals and computed values cannot supply a slot, and `this`
+  does not exist yet. A `NeoVariant<T>` member's own default stays the bare
+  variant path.
 - List and dictionary defaults may hold slot references, nested too:
-  `List<Reference<int>> Counts = [Reference(root.Save.Bits)]`. Each instance
+  `List<Reference<int>> Counts = [root.Save.Bits]`. Each instance
   owns the collection; entries target the original slots.
+- `Set<Reference<T>>` selections can mix bare paths and explicit references.
+  Computed selections deduplicate by target identity, not by current value.
+  A literal selection of fixed targets must not repeat the same target.
+- A bare path to an existing reference copies its current target when the
+  object is constructed. Later rebinding of that source reference does not
+  rebind the copy.
+- A nullable target still needs a stored row. Pin an otherwise absent
+  nullable member in its owner's initializer, for example
+  `new() { Maybe = null }`, before referencing it. A declaration default alone
+  does not create that row.
 
 ## Source forms
 
@@ -89,11 +101,18 @@ Reference<NeoDialogue>(id: "capitol-dialogue-id")
 
 ## Runtime semantics
 
-`Reference(place)` forms a reference to a stored member: `this.Gold`,
-`root.Player.Gold`, `item.Count`. Locals, parameters, list or dictionary
-elements, vector components, getters, query results, and new values have no
-row. When `Selected` is `Reference<Item>`, `Reference(this.Selected)` is
-`Reference<Reference<Item>>`. Access checks apply where it is formed.
+When executable code expects `Reference<T>`, pass a compatible stored member
+such as `this.Gold`, `root.Player.Gold`, or `item.Count` directly. This works
+for constructor and function arguments, returns, typed locals, object
+initializers, and collection entries. The reference keeps following that
+slot when its value changes. `Reference(place)` remains valid when an
+explicit reference is needed.
+
+Locals, parameters, list or dictionary elements, vector components, getters,
+query results, and new scalar values have no row. A narrowed nullable member
+still names its declared storage type. When `Selected` is `Reference<Item>`,
+`Reference(this.Selected)` is `Reference<Reference<Item>>`. Access checks
+apply where the reference is formed.
 
 ```neo
 this.A = 5;                       // writes 5 into A's target
@@ -106,8 +125,8 @@ this.A += 1;                      // reads A's target, writes it back
 - Assigning a same-typed reference rebinds; anything else writes through.
   `this.A = c ? first : second` rebinds when both arms are references, writes
   when both are scalars, and reads the chosen target when mixed.
-- A plain value never becomes a reference: passing `3` to a `Reference<int>`
-  parameter is an error.
+- A value without a stored slot never becomes a reference: passing `3` to a
+  `Reference<int>` parameter is an error.
 - Constructors may initialize their own reference fields but can't write
   through external targets.
 - `==` compares handles by identity and slots by value. Collections of
@@ -138,6 +157,10 @@ Lookup assignment still needs an existing backing row.
 (`root.Assets.Quests.Daily` or `Reference(root.Assets.Quests.Daily)`) and
 follow the same rules. The path may cross construction defaults and
 declarations from the same push; no preliminary push or manual ID is needed.
+Pull emits bare paths in `collectionValue` settings when the target is reachable
+from a root; otherwise it retains `Reference(id: "...")`. Lookup variant folder
+bindings and `.Bind(root.Assets.Items.Index.Slug["seed.carrot"]!)` use the same
+implicit reference conversion.
 Invalid reference settings are errors, never silently dropped.
 
 ## Init-built objects
@@ -145,7 +168,7 @@ Invalid reference settings are errors, never silently dropped.
 An object `Root.neo` writes is init-built when its class has an `init` block.
 A declaration binding may name a member inside it, and push stores that
 member's row. A reference captured by `init` or a constructor
-(`new Rule(Reference(this.Weather))`) keeps its target's row. Status refuses a
+(`new Rule(this.Weather)`) keeps its target's row. Status refuses a
 value row's reference to a member of an init-built object (bind it from a
 declaration instead) and a binding to a class or list that an `init` block
 builds.

package/skills/neocompose-cli/references/world/variants.md

@@ -86,7 +86,7 @@ class root.
 NeoLookupVariantFolder<ExampleObject, NeoSortingLayer> Root = new(
   path: "",
   collection: Assets.SortingLayers,
-  collectionValue: Reference(root.Assets.SortingLayers),
+  collectionValue: root.Assets.SortingLayers,
 );
 
 @id("736dddf8-2881-47e1-a1d3-55fb65ea9f2a")
@@ -97,13 +97,14 @@ NeoLookupVariant<ExampleObject, NeoSortingLayer> Layered = new(
 ```
 
 - `collection` names the eligible list member; `collectionValue` the stored
-  list whose rows it enumerates. Prefer the `Reference(root...)` form pull
+  list whose rows it enumerates. Prefer the bare `root...` path pull
   emits.
 - Lookup `initialize` receives the row; lookup `apply` receives the object,
   then the row.
 - A `NeoLookupVariant<TObject, TValue>` member holds an unbound handle. A
   plain `NeoVariant<TObject>` member may pick one row with
-  `.Bind(Reference(...))`; never bind a row to the lookup-handle type.
+  `.Bind(root.Assets.Items.Index.Slug["seed.carrot"]!)`; explicit
+  `Reference(...)` remains valid. Never bind a row to the lookup-handle type.
 
 ## Type restrictions