@neocompose/cli 0.50.10 → 0.51.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@neocompose/cli",
-  "version": "0.50.10",
+  "version": "0.51.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.50.10 -->
+<!-- reviewed-through-cli: 0.51.1 -->
 
 # Neo Compose CLI
 
@@ -229,8 +229,9 @@ AudioClipRegistry AudioClips = new() {
 Use `Images.Sword.Slice(0)` for a sprite and `AudioClips.SwordHit` for audio.
 Registry declarations and their image/audio paths may be in any project folder
 outside ignored/private directories. Update the registry path when moving a
-binary file. Renaming the registry symbol or replacing bytes
-retains the file ID.
+binary file. Renaming the registry symbol or replacing bytes retains the file
+ID when the declaration keeps its `@id`; keep the symbol aligned with the
+persisted file name, or set `@settings(name: ...)` explicitly.
 Omitting `@settings(template: ...)` uses the complete built-in Unity import
 defaults for that file kind.
 

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

@@ -6,6 +6,7 @@ NeoFlow dialogue graphs.
 ## Contents
 
 - World object contracts
+- Cell patterns and grid queries
 - Sorting and optional children
 - Structured leaves
 - Object variants and lookup folders
@@ -24,6 +25,37 @@ For world layer links, derive a concrete project class from
 `targetLayer` relation. Do not add value-level target metadata or ask painting
 operations to create/repair relation targets.
 
+## Cell patterns and grid queries
+
+`NeoCellPattern` stores an immutable ordered list of `Vector2Int` offsets.
+Its constructor copies the input list and preserves duplicates. Use `Box`,
+`Cross`, `Ring`, `Rect`, or `Line` for common shapes, and `Center`,
+`FourNeighbors`, `EightNeighbors`, or `Empty` for presets. `Cells(origin)`
+returns absolute cells in pattern order.
+
+```neo
+NeoCellPattern neighbors = NeoCellPattern.Box(1, excluding: .Center);
+NeoCellPattern custom = new(offsets: [new(-1, 0), new(2, 1)]);
+```
+
+On a placed `NeoObject`, `this.Cell` returns its grid cell.
+`this.GetObjects<Plant>(neighbors)` returns matching placed objects in the
+same grid, filtered to `Plant` and subclasses. `this.GetTile(neighbors)`
+returns the first tile found in pattern order, or null. These queries track
+empty cells as well as hits, so a getter updates when a new neighbor appears.
+Calling them on an unplaced object is an error.
+
+`WithCenter`, `WithoutCenter`, `Translate`, and `Union` return patterns.
+`Union` removes duplicate offsets while preserving first occurrence order.
+Box, Cross, and Line include the origin by default. Use `excluding: .Center`
+to omit it. Line's `length` is the number of steps beyond the origin, so
+`Line(new(1, 0), 3)` contains four cells.
+
+The SDK uses the existing `NeoCellPattern` type and `GetCells(origin)` API.
+Replace old boolean factory arguments with `NeoCellPatternExcluding.None`
+or `.Center`. To retain Line's old default, pass
+`excluding: NeoCellPatternExcluding.Center` explicitly.
+
 ## Tile placements
 
 Use `@tile(VoidTile)` on a `NeoTileInstance` construction to select its tile
@@ -388,6 +420,8 @@ Require destinations for triggers, options, and outcomes. Permit terminal
 text/actions to fall through. Keep all statements for
 `Actions Empty = new();` inside its body.
 
-After editing, run `neo dialogue dryrun <dialogue-ref>`. Exit 1 means the graph
+After editing, run `neo dialogue dryrun <dialogue-ref>`. It prepares the local
+project candidate, including new dialogues and pending schema or value changes,
+without fetching or committing server content. Exit 1 means the graph
 would fail on device. Keep every dialogue edit in the tracked `.neoflow` source
 and commit it with `neo push`.

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

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

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

@@ -39,6 +39,20 @@ records. If the remote head is unchanged, pull preserves the local source
 without compiling it; use `neo status` to inspect local edits and diagnostics.
 An undo/reset metadata change invalidates the cursor and causes a safe
 full-snapshot fallback.
+
+After a compiler upgrade, run `neo pull` with `.neo/state.json` intact. When
+remote changes affect only compiler-owned bodies or timestamps, pull refreshes
+the cached records before local compilation and leaves authored files and
+managed binaries untouched. It handles both changed-record pulls and full
+snapshot refreshes. Added or deleted records, authored changes, and unresolved
+conflicts still require the normal merge path.
+
+Keep `.neo/state.json`: it holds the merge baseline and source placements.
+Normal pull refuses existing production sources without that baseline. To
+deliberately replace a checkout whose state is gone, back it up first and use
+`neo pull --force`; the CLI recovers custom paths from the remaining declarations.
+The force pull replaces local source with the server version.
+
 Pull pins every page and snapshot batch to one published generation and logical
 revision. If either changes during assembly, the CLI discards the attempt and
 restarts. Upgrade the CLI together with the P83 server read protocol.

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

@@ -121,6 +121,10 @@ entry and its declared type is the entry type; `public Set<Config> Configs`
 selects several. An initializer body for a single-select lookup returns one
 entry, never a set.
 
+The CLI also accepts `List<T>` with `selection: .Multi` on a member. Emitted
+source uses `Set<T>`; constructor and function parameters must use `Set<T>`
+to carry selection semantics.
+
 Declare a multicast event as `NeoAction<…>`. Its value is an ordered listener
 set, so give it a bracketed list of method groups — never a lambda, and never
 a bare method group — and never mark it `required`: the rest state is the

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

@@ -64,6 +64,12 @@ Declare a bodyless NeoScript contract with `abstract`, for example
 `public abstract bool Equals(Item other);`. Reserve `native` for host-provided
 functions; concrete NeoScript overrides inherit the abstract signature.
 
+Inside an override body, use `base.Member(args)` or `base.Property` to invoke
+its nearest ancestor implementation. The ancestor receives the same `this`,
+so ordinary virtual calls inside that implementation still reach the most
+derived override. `base` outside an override or targeting an abstract member
+is a compile error. Base constructors and stored-field reads are not supported.
+
 Use the shared language service through focused commands:
 
 ```sh

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

@@ -214,9 +214,12 @@ creates a pending file with a provisional deterministic symbol. Status,
 diff, and dry-run do not rewrite its registry. A successful push creates the
 record, uploads verified bytes, and materializes its declaration and ID.
 
-Edit the typed registry declaration directly when an explicit symbol or
-non-default template is needed before push. With no template annotation, the
-CLI persists the complete built-in Unity defaults for the file kind.
+Registry symbols derive deterministically from the persisted file name. For
+example, `tree.cherryblossom.png` becomes `TreeCherryblossom`. Keep an authored
+declaration aligned with that spelling, or set an explicit persisted name such
+as `@settings(name: "TreeCherryBlossom.png")` when the binary path should stay
+different. With no template annotation, the CLI persists the complete built-in
+Unity defaults for the file kind.
 
 Pull/push compare server-verified SHA-256, not storage ETags. A divergent
 binary keeps local bytes and writes the verified remote side under