@neocompose/cli 0.81.3 → 0.81.4

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## 0.81.4
+
+### Patch Changes
+
+- 7ed5870: Reject values on boolean flags so `push --dry-run=true` cannot silently perform a real commit. Use bare switches such as `--dry-run` and `--help`.
+- 887fb8c: Reject unused branch flags and unsupported dry-run requests before command execution, so branch creation and other mutating commands cannot silently ignore a requested preview.
+- 6631cef: Refuse initialization into a nonempty directory, apart from Git metadata, so init cannot overwrite existing source or managed files without consent.
+- b2a688d: Resolve source conflicts with CRLF or mixed line endings while preserving the selected source bytes and formatting.
+- 743783d: Refuse branch switches with unpushed changes, conflicts, invalid source, or pending push recovery so switching cannot silently discard local work.
+- b0b945f: Report constructor parameter errors at their source location instead of crashing
+  with an internal missing-constructor manifest error during status or push.
+- c11209a: Fix lookup initializers losing row identities in projected selection sets.
+  Accept Reference(value) for evaluated class values, including collection
+  callbacks, while preserving type checking and the original value identity.
+
 ## 0.81.3
 
 ### Patch Changes

package/dist/neo.mjs

@@ -19229,6 +19229,11 @@ function parseArgs(argv) {
       const equals = arg.indexOf("=");
       const name = arg.slice(2, equals < 0 ? void 0 : equals);
       if (equals >= 0) {
+        if (BOOLEAN_FLAGS.has(name)) {
+          throw new NeoCliUsageError(
+            `--${name} does not accept a value. Pass --${name} to enable it, or omit the flag.`
+          );
+        }
         flags.set(name, arg.slice(equals + 1));
         continue;
       }
@@ -19283,6 +19288,38 @@ function assertAllowedFlags(args, allowed) {
     );
   }
 }
+function assertCommandFlags(args) {
+  const subcommand = args.positional[0];
+  if (args.command === "branch") {
+    const allowed = /* @__PURE__ */ new Set(["api"]);
+    if (subcommand === "list") {
+      allowed.add("json");
+      allowed.add("all");
+    }
+    if (subcommand === "create") allowed.add("from");
+    if (subcommand === "refresh") allowed.add("dry-run");
+    assertAllowedFlags(args, allowed);
+  }
+  if (!args.flags.has("dry-run")) return;
+  switch (args.command) {
+    case "push":
+    case "merge":
+    case "refresh":
+      return;
+    case "branch":
+      if (subcommand === "refresh") return;
+      break;
+    case "release":
+      if (subcommand === "cut") return;
+      break;
+    case "migrate":
+      if (subcommand === "run") return;
+      break;
+  }
+  throw new NeoCliUsageError(
+    `Flag "--dry-run" is not supported by neo ${args.command}${subcommand === void 0 ? "" : ` ${subcommand}`}. No changes were made.`
+  );
+}
 var NeoCliUsageError, BOOLEAN_FLAGS, KNOWN_FLAGS, TEST_ONLY_FLAGS;
 var init_args = __esm({
   "src/args.ts"() {
@@ -33735,7 +33772,48 @@ var init_strict_resolver = __esm({
             );
           case "call": {
             const receiverValue = this.callReceiver(expression.callee, scope);
-            if (expression.callee.kind === "ident" && expression.callee.name === "Reference" && Array.isArray(expression.typeArguments)) {
+            if (expression.callee.kind === "ident" && expression.callee.name === "Reference") {
+              if (expression.args.length === 1 && expression.argumentNames?.[0] == null) {
+                if ((expression.typeArguments?.length ?? 0) > 1) {
+                  throw new CompileError(
+                    "Reference accepts at most one generic target type.",
+                    expression.pos
+                  );
+                }
+                const explicit = expression.typeArguments?.[0];
+                const targetType = explicit === void 0 ? void 0 : this.resolveType(explicit);
+                const target = this.resolveExpression(
+                  expression.args[0],
+                  scope,
+                  targetType
+                );
+                const type = targetType ?? target.type;
+                if (type.kind !== "typeParameter" && !(type.kind === "named" && this.project.typeById.get(type.typeId)?.kind === "class")) {
+                  throw new CompileError(
+                    "Reference(value) requires a class value.",
+                    expression.pos
+                  );
+                }
+                if (!isNeoScriptTypeAssignable(target.type, type, this.project)) {
+                  throw new CompileError(
+                    `Reference target ${this.describe(target.type)} is not assignable to ${this.describe(type)}.`,
+                    expression.pos
+                  );
+                }
+                if (expected !== void 0 && !isNeoScriptTypeAssignable(type, expected, this.project)) {
+                  throw new CompileError(
+                    `Reference target ${this.describe(type)} is not assignable to ${this.describe(expected)}.`,
+                    expression.pos
+                  );
+                }
+                return { ...target, type };
+              }
+              if (expression.typeArguments === void 0) {
+                throw new CompileError(
+                  'Reference requires one class value, or Reference<T>(id: "...").',
+                  expression.pos
+                );
+              }
               const [referenceTypeArgument] = expression.typeArguments;
               if (expression.typeArguments.length !== 1 || referenceTypeArgument === void 0) {
                 throw new CompileError(
@@ -45719,6 +45797,7 @@ function validateExpression(expression, expected, scope, environment, uri, range
       validateReferenceExpression(
         expression,
         expected,
+        scope,
         environment,
         uri,
         range2,
@@ -46496,7 +46575,10 @@ function inferExpressionType(expression, scope, environment) {
       const explicit = expression.typeArguments?.[0];
       if (explicit) return semanticAstType(explicit);
       const target = expression.args[0] ? referenceTargetPath(expression.args[0]) : null;
-      return target ? environment.referenceTargets.get(target)?.type : void 0;
+      const symbolType = target ? environment.referenceTargets.get(target)?.type : void 0;
+      if (symbolType !== void 0) return symbolType;
+      const argument2 = expression.args[0];
+      return argument2 === void 0 ? void 0 : inferExpressionType(argument2, scope, environment);
     }
     return environment.functions.get(expression.callee.name)?.[0]?.returnType;
   }
@@ -46544,7 +46626,7 @@ function subscriptKeyType(receiver) {
   if (receiver?.name === "List") return primitiveType("int");
   return void 0;
 }
-function validateReferenceExpression(expression, declared, environment, uri, range2, diagnostics) {
+function validateReferenceExpression(expression, declared, scope, environment, uri, range2, diagnostics) {
   const expected = declared?.name === "NeoDialogueReference" ? { ...declared, name: "NeoDialogue" } : declared;
   const typeArguments = expression.typeArguments ?? [];
   const names = expression.argumentNames ?? [];
@@ -46632,6 +46714,7 @@ function validateReferenceExpression(expression, declared, environment, uri, ran
   if (path !== null && path.startsWith("root.")) return;
   const target = path ? environment.referenceTargets.get(path) : void 0;
   if (!target) {
+    if (path === null || scope.has(path.split(".")[0])) return;
     malformed(
       "Reference target must be a local value, stored static value, or dialogue class symbol."
     );
@@ -54564,7 +54647,7 @@ var init_registry = __esm({
   "../packages/manifest/schema-contract/registry.mjs"() {
     "use strict";
     PROJECT_SCHEMA_CONTRACT = Object.freeze({
-      cliVersion: "0.81.3",
+      cliVersion: "0.81.4",
       projectFileUploadBatchSize: 32,
       documentRecords: {
         member: {
@@ -93948,6 +94031,7 @@ function evaluateMemberInitializer(args) {
     __constructedFieldSchemaKeysByValue: /* @__PURE__ */ new WeakMap(),
     __createdStorageKeyDeclarations: args.storageKeyDeclarations ?? /* @__PURE__ */ new Map()
   };
+  let evaluatedContext = ctx;
   const result = (() => {
     try {
       return evaluateNSGetterWithEffects(
@@ -93956,6 +94040,9 @@ function evaluateMemberInitializer(args) {
         args.argumentValues ?? [],
         {
           exportInitializerValues: true,
+          inspectResult: (_value, runtimeContext) => {
+            evaluatedContext = runtimeContext;
+          },
           // Seeded rows already hold their placement.
           ...args.sessionValues === void 0 ? {
             initializerResult: {
@@ -93981,7 +94068,7 @@ function evaluateMemberInitializer(args) {
       args.member,
       result.value,
       created,
-      ctx
+      evaluatedContext
     );
   }
   const rootRow = initializerRootRow(result.value, created);
@@ -96947,7 +97034,9 @@ function isNamePath(expression) {
 }
 function isLiteralCall(expression) {
   if (expression.callee.kind === "ident" && expression.callee.name === "Reference") {
-    return true;
+    if (expression.argumentNames?.some((name) => name !== null)) return true;
+    const argument2 = expression.args[0];
+    return expression.args.length === 1 && argument2 !== void 0 && (isNamePath(argument2) || argument2.kind === "litString");
   }
   return expression.callee.kind === "member" && expression.callee.name === "Slice";
 }
@@ -97341,21 +97430,15 @@ function lowerClassConstructors(context, declaration, classId, lowerParameterTyp
   const declared = declaration.constructors.map((declared2) => {
     const id2 = declaredConstructorId2(declaration, declared2);
     const base = context.baseConstructors.get(id2);
-    const parameters = declared2.parameters.map((parameter4) => {
-      const parameterType = lowerParameterType(parameter4.type, declaration);
-      return {
-        name: parameter4.name,
-        type: parameterType,
-        default: lowerParameterDefault(
-          context,
-          parameter4,
-          parameterType,
-          `${declaration.name}.${declared2.name}(${parameter4.name})`
-        ),
-        source: span({ source: parameter4.source }),
-        selectionSpan: span({ source: parameter4.source })
-      };
-    });
+    const parameters = declared2.parameters.map(
+      (parameter4) => lowerConstructorParameter(
+        context,
+        parameter4,
+        declaration,
+        lowerParameterType,
+        `${declaration.name}.${declared2.name}(${parameter4.name})`
+      )
+    );
     const baseArguments = lowerBaseArguments(
       context,
       declaration,
@@ -97400,26 +97483,41 @@ function lowerRequiredConstructor(context, declaration, classId, lowerParameterT
       selectionSpan: sourceSpan
     },
     classId,
-    arguments: required2.parameters.map((parameter4) => {
-      const parameterType = lowerParameterType(parameter4.type, declaration);
-      return {
-        name: parameter4.name,
-        type: parameterType,
-        default: lowerParameterDefault(
-          context,
-          parameter4,
-          parameterType,
-          `${declaration.name}(${parameter4.name})`
-        ),
-        source: span({ source: parameter4.source }),
-        selectionSpan: span({ source: parameter4.source })
-      };
-    }),
+    arguments: required2.parameters.map(
+      (parameter4) => lowerConstructorParameter(
+        context,
+        parameter4,
+        declaration,
+        lowerParameterType,
+        `${declaration.name}(${parameter4.name})`
+      )
+    ),
     code: requiredConstructorBody(required2.body, base?.code),
     ...baseArguments.length === 0 ? {} : { baseArguments },
     ...baseInitializerFields.length === 0 ? {} : { baseInitializerFields }
   };
 }
+function lowerConstructorParameter(context, parameter4, declaration, lowerParameterType, path) {
+  try {
+    const type = lowerParameterType(parameter4.type, declaration);
+    return {
+      name: parameter4.name,
+      type,
+      default: lowerParameterDefault(context, parameter4, type, path),
+      source: span({ source: parameter4.source }),
+      selectionSpan: span({ source: parameter4.source })
+    };
+  } catch (error) {
+    if (error instanceof SchemaSourceError) throw error;
+    throw new SchemaSourceError(
+      error instanceof Error ? error.message : String(error),
+      parameter4.source.uri,
+      parameter4.source.range.start.line + 1,
+      parameter4.source.range.start.character + 1,
+      "schema-lowering"
+    );
+  }
+}
 function requiredConstructorRecordId(classId) {
   return isPendingId(classId) ? pendingRequiredConstructorId(classId) : derivedRequiredConstructorId(classId);
 }
@@ -97533,6 +97631,7 @@ var init_lower_constructors = __esm({
     init_pending_id();
     init_declared_constructors();
     init_required_constructor_id();
+    init_source_diagnostics();
     init_declared_constructors2();
     init_lower_parameter_defaults();
     init_init_source();
@@ -148727,6 +148826,11 @@ function computeStatus(workspace, options, conflictedFiles, parseErrors, parseWa
         Object.values(loweringRecords)
       )
     });
+    if (failedDeclarations.size > 0 && validAnalysis.schema.classes.some(
+      (declaration) => failedDeclarations.has(declaration)
+    )) {
+      return refusedStatus(conflictedFiles, parseErrors, parseWarnings);
+    }
     const loweredMemberIds = new Set(
       manifest.members.map((member) => member.id)
     );
@@ -159758,7 +159862,7 @@ function projectSignatureHelp(analysis, document, position) {
     );
   }
   if (callee.text === "Reference") {
-    const parameters = ["symbol or id", "withProvenance = false"];
+    const parameters = ["class value, symbol, or id", "withProvenance = false"];
     return signatureResult(
       "Reference",
       parameters,
@@ -189657,7 +189761,13 @@ var init_exports = {};
 __export(init_exports, {
   runInit: () => runInit
 });
-import { existsSync as existsSync19, mkdirSync as mkdirSync14, readFileSync as readFileSync25, writeFileSync as writeFileSync15 } from "node:fs";
+import {
+  existsSync as existsSync19,
+  mkdirSync as mkdirSync14,
+  readFileSync as readFileSync25,
+  readdirSync as readdirSync7,
+  writeFileSync as writeFileSync15
+} from "node:fs";
 import { join as join23, resolve as resolve4 } from "node:path";
 async function runInit(options) {
   let projectId = options.projectId;
@@ -189758,6 +189868,16 @@ async function runInit(options) {
   if (existsSync19(join23(root, NEO_CONFIG_FILE))) {
     throw new Error(`"${join23(root, NEO_CONFIG_FILE)}" already exists.`);
   }
+  if (existsSync19(root)) {
+    const existing = readdirSync7(root).find(
+      (name) => name !== ".git" && name !== ".gitignore"
+    );
+    if (existing !== void 0) {
+      throw new Error(
+        `Cannot initialize ${JSON.stringify(root)} because it contains ${JSON.stringify(existing)}. Choose an empty directory, or back up and move existing files first.`
+      );
+    }
+  }
   mkdirSync14(root, { recursive: true });
   await acquireWorkspaceLock(root, "init");
   ensurePrivateStateIgnored(root);
@@ -193079,7 +193199,7 @@ import { createHash as createHash18, randomUUID as randomUUID8 } from "node:cryp
 import {
   existsSync as existsSync20,
   mkdirSync as mkdirSync15,
-  readdirSync as readdirSync7,
+  readdirSync as readdirSync8,
   readFileSync as readFileSync27,
   realpathSync as realpathSync2,
   renameSync as renameSync10,
@@ -194373,7 +194493,7 @@ function testBuildFiles(root) {
   if (!existsSync20(root)) return [];
   const files = [];
   const visit = (directory) => {
-    for (const entry of readdirSync7(directory, { withFileTypes: true })) {
+    for (const entry of readdirSync8(directory, { withFileTypes: true })) {
       if (entry.isSymbolicLink()) continue;
       const path = join24(directory, entry.name);
       if (entry.isDirectory()) visit(path);
@@ -197660,6 +197780,47 @@ function findVersion(versions, ref) {
     (version) => version.id === ref || version.name === ref || version.semver.label === ref
   );
 }
+function assertCleanBranchSwitch(workspace) {
+  assertNoPendingPushRecovery(workspace);
+  const records3 = Object.values(workspace.state.records);
+  for (const record7 of records3) {
+    if (record7.conflictServerHash !== void 0) {
+      throw new Error(
+        "Cannot switch branches with unresolved record conflicts. Run neo resolve before switching."
+      );
+    }
+  }
+  if (records3.length === 0) {
+    const inputs = listProjectExportInputsV4(workspace.root);
+    if (inputs.sources.length === 0 && inputs.binaries.length === 0) return;
+  }
+  const status = computeWorkspaceStatus2(workspace);
+  if (status.conflictedFiles.length > 0) {
+    throw new Error(
+      "Cannot switch branches with unresolved conflicts. Resolve them before switching."
+    );
+  }
+  if (status.parseErrors.length > 0) {
+    throw new Error(
+      "Cannot switch branches while local source has errors. Run neo status and fix or back up your edits before switching."
+    );
+  }
+  if (status.changes.length > 0) {
+    throw new Error(
+      "Cannot switch branches with unpushed changes. Push or back up your edits first; use neo pull --force only to deliberately discard them."
+    );
+  }
+  if (status.authoredValueSeeds.size > 0) {
+    throw new Error(
+      "Cannot switch branches with unpushed value seeds. Push or back up your edits first; use neo pull --force only to deliberately discard them."
+    );
+  }
+  if ((status.binaryChanges?.length ?? 0) > 0) {
+    throw new Error(
+      "Cannot switch branches with pending file changes. Run neo status and settle those changes before switching."
+    );
+  }
+}
 async function runBranch(workspace, subcommand, positional, fromRef) {
   if (subcommand === "list") {
     const { versions } = await loadVersionMetadata(workspace);
@@ -197750,9 +197911,13 @@ async function runBranch(workspace, subcommand, positional, fromRef) {
       console.log(`Already on ${displayLabel(target)}.`);
       return;
     }
+    assertCleanBranchSwitch(workspace);
     workspace.config = { ...workspace.config, versionId: target.id };
     writeWorkspaceConfig(workspace.root, workspace.config);
-    workspace.state = { records: {} };
+    workspace.state = {
+      records: workspace.state.records,
+      localValues: workspace.state.localValues
+    };
     writeWorkspaceState(workspace.root, workspace.state);
     success(
       `Switched to ${color.bold(displayLabel(target))} ${color.dim(`(${target.id})`)}. Pulling\u2026`
@@ -198212,6 +198377,8 @@ var init_branch = __esm({
     init_value_comparison();
     init_ui();
     init_pull();
+    init_workspace_status();
+    init_push_recovery();
     init_http();
     init_project_transaction();
     displayLabel = projectVersionDisplayLabel;
@@ -201237,7 +201404,7 @@ var dev_exports = {};
 __export(dev_exports, {
   runDev: () => runDev
 });
-import { readdirSync as readdirSync8, statSync as statSync6, watch } from "node:fs";
+import { readdirSync as readdirSync9, statSync as statSync6, watch } from "node:fs";
 import { basename as basename5, dirname as dirname15, join as join27, resolve as resolve6 } from "node:path";
 import { emitKeypressEvents } from "node:readline";
 async function runDev(root, loadWorkspace2, options) {
@@ -201370,7 +201537,7 @@ function countsAsExportInput(root, relativePath, event, directories) {
 function rememberDirectories(root, relativePath, directories) {
   let entries;
   try {
-    entries = readdirSync8(join27(root, relativePath), { withFileTypes: true });
+    entries = readdirSync9(join27(root, relativePath), { withFileTypes: true });
   } catch (error) {
     if (error instanceof Error && "code" in error) {
       if (error.code === "ENOENT") return;
@@ -201549,18 +201716,19 @@ function resolveMarkers(source, side) {
   const output = [];
   let mode = "outside";
   for (const line of lines) {
-    if (line.startsWith("<<<<<<<")) {
+    const marker = line.endsWith("\r") ? line.slice(0, -1) : line;
+    if (marker.startsWith("<<<<<<<")) {
       if (mode !== "outside") {
         throw new Error("Nested conflict markers are not supported.");
       }
       mode = "local";
       continue;
     }
-    if (line === "=======" && mode === "local") {
+    if (marker === "=======" && mode === "local") {
       mode = "server";
       continue;
     }
-    if (line.startsWith(">>>>>>>")) {
+    if (marker.startsWith(">>>>>>>")) {
       if (mode !== "server") {
         throw new Error("Unbalanced conflict markers.");
       }
@@ -201847,7 +202015,7 @@ There is no --keep-current: preserving current semantic state defines flatten.
 async function main() {
   const args = parseArgs(process.argv.slice(2));
   if (args.command === "--version") {
-    console.log("0.81.3");
+    console.log("0.81.4");
     return;
   }
   if (args.command === null || args.command === "help" || args.command === "--help" || args.command === "-h") {
@@ -201859,6 +202027,7 @@ async function main() {
     return;
   }
   assertKnownFlags(args);
+  assertCommandFlags(args);
   if (WORKSPACE_LOCK_COMMANDS.has(args.command)) {
     const root = findWorkspaceRoot(process.cwd());
     if (root !== null) {

package/dist/test-worker.mjs

@@ -35697,6 +35697,7 @@ function evaluateMemberInitializer(args) {
     __constructedFieldSchemaKeysByValue: /* @__PURE__ */ new WeakMap(),
     __createdStorageKeyDeclarations: args.storageKeyDeclarations ?? /* @__PURE__ */ new Map()
   };
+  let evaluatedContext = ctx;
   const result = (() => {
     try {
       return evaluateNSGetterWithEffects(
@@ -35705,6 +35706,9 @@ function evaluateMemberInitializer(args) {
         args.argumentValues ?? [],
         {
           exportInitializerValues: true,
+          inspectResult: (_value, runtimeContext) => {
+            evaluatedContext = runtimeContext;
+          },
           // Seeded rows already hold their placement.
           ...args.sessionValues === void 0 ? {
             initializerResult: {
@@ -35730,7 +35734,7 @@ function evaluateMemberInitializer(args) {
       args.member,
       result.value,
       created,
-      ctx
+      evaluatedContext
     );
   }
   const rootRow = initializerRootRow(result.value, created);
@@ -40073,7 +40077,48 @@ var StrictNeoScriptResolver = class _StrictNeoScriptResolver {
         );
       case "call": {
         const receiverValue = this.callReceiver(expression.callee, scope);
-        if (expression.callee.kind === "ident" && expression.callee.name === "Reference" && Array.isArray(expression.typeArguments)) {
+        if (expression.callee.kind === "ident" && expression.callee.name === "Reference") {
+          if (expression.args.length === 1 && expression.argumentNames?.[0] == null) {
+            if ((expression.typeArguments?.length ?? 0) > 1) {
+              throw new CompileError(
+                "Reference accepts at most one generic target type.",
+                expression.pos
+              );
+            }
+            const explicit = expression.typeArguments?.[0];
+            const targetType = explicit === void 0 ? void 0 : this.resolveType(explicit);
+            const target = this.resolveExpression(
+              expression.args[0],
+              scope,
+              targetType
+            );
+            const type = targetType ?? target.type;
+            if (type.kind !== "typeParameter" && !(type.kind === "named" && this.project.typeById.get(type.typeId)?.kind === "class")) {
+              throw new CompileError(
+                "Reference(value) requires a class value.",
+                expression.pos
+              );
+            }
+            if (!isNeoScriptTypeAssignable(target.type, type, this.project)) {
+              throw new CompileError(
+                `Reference target ${this.describe(target.type)} is not assignable to ${this.describe(type)}.`,
+                expression.pos
+              );
+            }
+            if (expected !== void 0 && !isNeoScriptTypeAssignable(type, expected, this.project)) {
+              throw new CompileError(
+                `Reference target ${this.describe(type)} is not assignable to ${this.describe(expected)}.`,
+                expression.pos
+              );
+            }
+            return { ...target, type };
+          }
+          if (expression.typeArguments === void 0) {
+            throw new CompileError(
+              'Reference requires one class value, or Reference<T>(id: "...").',
+              expression.pos
+            );
+          }
           const [referenceTypeArgument] = expression.typeArguments;
           if (expression.typeArguments.length !== 1 || referenceTypeArgument === void 0) {
             throw new CompileError(
@@ -59593,7 +59638,7 @@ var INITIALIZER_KEY_PLACEHOLDER = new RegExp(
 
 // ../packages/manifest/schema-contract/registry.mjs
 var PROJECT_SCHEMA_CONTRACT = Object.freeze({
-  cliVersion: "0.81.3",
+  cliVersion: "0.81.4",
   projectFileUploadBatchSize: 32,
   documentRecords: {
     member: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@neocompose/cli",
-  "version": "0.81.3",
+  "version": "0.81.4",
   "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.3 -->
+<!-- reviewed-through-cli: 0.81.4 -->
 
 # Neo Compose CLI
 
@@ -88,6 +88,10 @@ neo doctor
 Use `node cli/bin/neo.mjs` while developing the repository. Pass explicit flags
 and IDs in automation. Non-TTY/CI commands never wait for pickers or confirms.
 
+`neo init` requires a new or empty destination, apart from `.git` and
+`.gitignore`. It refuses other existing entries before writing anything; choose
+a separate directory when recovering a checkout whose config is missing.
+
 Require `formatVersion: 4` in `neo.json`. There is no format-3 reader or
 upgrader. Reconstruct an authoritative format-4 checkout with `neo init`.
 

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

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

@@ -29,6 +29,11 @@ neo push
 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.
+A failed class or constructor declaration blocks candidate preparation.
+
 Use `neo pull --regenerate-source-names` to replace generated default dialogue
 names with readable ones. It keeps chosen names and rewrites references. Use
 `--reset` to regenerate canonical source and managed binaries. Reset retains
@@ -151,6 +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.
+
 Resolve source conflicts by editing the final intended source. Use
 `neo resolve --mine` or `neo resolve --theirs` only for a deliberate whole-side
 choice. Pull, inspect, dry-run, and retry; there is no force-CAS path.
@@ -228,6 +236,11 @@ neo history status --run <run-id>
 neo history resume --run <run-id>
 ```
 
+Branch switching requires a clean working copy. Unpushed source or binary
+changes, unresolved conflicts, source errors, and pending push recovery stop the
+switch before it changes the selected version or baseline. Push or back up edits
+first; use `neo pull --force` only when discarding them is intended.
+
 Treat branches as copy-on-write forks and releases as immutable snapshots. The
 server derives the minimum compatibility bump; a caller may only raise it.
 Require the release login profile for release operations.
@@ -294,6 +307,12 @@ so concurrent environments sharing one OS user cannot read, overwrite, or
 delete each other's tokens. Login, logout, and authenticated commands all
 honor both variables.
 
+Boolean flags are switches: pass `--dry-run` or `--help` without a value.
+Values such as `--dry-run=true` are rejected before a command runs.
+`--dry-run` is supported by push, merge, refresh, branch refresh, release cut,
+and migrate run. Other commands reject it before taking action. Branch options
+are scoped to their subcommands; branch create does not support dry-run.
+
 Pass explicit project/version IDs and flags in automation. Prefer `--json` for
 machine-readable output and do not depend on interactive pickers or confirms.
 

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

@@ -180,6 +180,22 @@ 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:
+
+```neo
+EligibleIngredients = root.Assets.Crafting.FurnaceRecipes
+  .Select((MachineRecipe recipe) => recipe.Ingredient)
+  .ToSet()
+```
+
+Writing `Reference(recipe.Ingredient)` inside the callback is also valid.
+`Reference(value)` preserves an evaluated class value and its identity; it does
+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.
+
 Use the `Reference` intrinsic. Prefer the most readable form the target
 supports:
 
@@ -197,9 +213,8 @@ Reference<NeoDialogue>(id: "capitol-dialogue-id")
 - 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.
-- 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.
+- Use the generic `id:` form when the ID is the only target information.
+  Unrecognized named arguments are rejected rather than read as IDs.
 - 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`;