@neocompose/cli 0.87.2 → 0.88.0

package/skills/neocompose-cli/references/sync/conflicts-and-recovery.md

@@ -0,0 +1,68 @@
+# Conflicts and recovery
+
+## Conflicts
+
+Pull merges disjoint fields and children, and merges collection and graph
+children by ID, never by index. Conflicting scalars, edges, order,
+delete/edit pairs, and binaries become explicit conflicts whose source fails
+compilation on purpose.
+
+- Edit the source to the intended final state, or run `neo resolve --mine` or
+  `--theirs` for a deliberate whole-side choice. Then pull, review, dry-run,
+  and push. There is no force-CAS path.
+- Either side adopts the server as the new base for the conflicts it
+  settles: `--theirs` then reads clean, `--mine` reads as an ordinary local
+  update.
+- One record is one conflict however many files declare it. `neo resolve`
+  settles all of its files together and refuses a partly resolved record.
+- Resolution keeps the chosen lines and their line endings (LF, CRLF, or
+  mixed). Choosing a deleted side removes the file; deletion placeholders are
+  display text. Empty and comment-only files stay files.
+- Against a server-side deletion, keeping the record restores it as a create
+  guarded by an absent-record check; removing it accepts the deletion.
+- Pull warns when a conflicted record's local base strands newly downloaded
+  descendant rows. Resolve it with `--mine` or `--theirs` before pushing.
+- Compiled initializer IR and other server-derived metadata never cause a
+  conflict by themselves.
+- Binary conflicts keep local bytes; the server copy is under
+  `.neo/conflicts/files/<file-id>/`.
+
+`value-base-desync` means the workspace base no longer names value rows its
+own files project, so a plan would delete live rows. Nothing is planned; run
+`neo pull` and retry. As a warning, it reports without blocking.
+
+## Interrupted pushes
+
+If a push committed but rewriting source failed, `neo pull` resumes the saved
+result before checking the remote head. Status and push require that
+recovery first. Interrupted file writes resume without parsing a half-written
+checkout. If a file changed again after the plan was saved, recovery stops and
+names it; save that edit separately, restore the file to its pre-rewrite or
+generated content, then run `neo pull`.
+
+## .neo/state.json
+
+It holds the merge baseline, source placements, and the recovery journal.
+Keep it. Normal pull refuses existing source without a baseline. To replace a
+checkout whose state is gone, back it up and run `neo pull --force`, which
+recovers custom paths from the remaining declarations and replaces local
+source with the server version.
+
+## neo doctor
+
+`neo doctor` checks format, compiler, extension cache, source, files, and the
+last pull's document integrity, and fails on malformed records. Pull first to
+audit the current head.
+
+- The partition audit follows ownership: a lookup may reference a value in a
+  different partition.
+- It also reports base rows that no file projects and no record names. These
+  are invisible to `neo status`.
+- `--json` includes a `repair` entry per finding for targeted repair.
+- `--fix` repairs only `unprojected-value-row` findings: it lists each orphan
+  root with its row count, confirms, and deletes them in batches. Each row
+  carries the last pull's CAS base and each transaction expects the previous
+  head, so a stale audit fails instead of deleting a row that gained an
+  owner; a workspace with no recorded head is refused. `--yes` skips the
+  prompt. `--fix` has no `--json` form.
+- After a reviewed `--fix`, pull and run doctor again.

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

@@ -0,0 +1,96 @@
+# Sync commands
+
+What `pull`, `status`, `diff`, and `push` do beyond the workflow in
+[SKILL.md](../../SKILL.md). Open a leaf from [References](#references) for
+conflicts and recovery, branches and releases, or Unity export.
+
+## Pull
+
+- Normal pull fetches only changed records and merges them three-way by
+  record identity. If the remote head is unchanged it leaves source alone
+  without compiling; use `neo status` for local diagnostics.
+- It skips records whose hashes match the saved baseline, including echoes of
+  this checkout's last push, and refreshes records whose remote change touches
+  only compiler-owned bodies or timestamps without rewriting authored files.
+- It keeps declaration placement, spelling, comments, and file grouping by
+  stable ID. New server declarations use the default layout; system
+  declarations default to a `System` subfolder under their category.
+  Ownership comes from the reserved system identity, not the name.
+- `--reset` regenerates canonical source and managed binaries, keeping
+  recorded declaration paths. `--force` discards local edits for the server
+  version. Both bypass push recovery. Use them only when that loss is
+  intended.
+- `--regenerate-source-names` replaces generated dialogue symbols with
+  readable names and rewrites references.
+- Pull refuses a baseline holding a compiled body this CLI rejects and names
+  the record. If pull can't refresh it, back up local edits and run
+  `neo pull --force`.
+
+## Status and diff
+
+`neo status` and `neo diff` show every pending change, grouped by owning
+source, including newly authored value seeds. Diagnostics carry
+file:line:column, such as invalid constructor parameter types. A failed class
+or constructor declaration blocks candidate preparation.
+
+Deleting a class or collection declaration also deletes its hidden entry
+members, nested lists and dictionaries included; replacing a collection with
+a scalar deletes abandoned entries. Entries used by surviving declarations
+stay. If you deleted a member before pulling remote instance values, pull
+keeps them in the deletion plan. Review these derived deletions before
+pushing.
+
+## Dry-run
+
+`neo push --dry-run` rehearses the whole commit locally: source emission,
+pending-ID assignment, transport shapes, hashes, repeat verification,
+compilation, schema-commit materialization, seeded structural rows, and
+whole-graph validation. It never prompts, uploads, commits, or rewrites
+source. Pending getters and functions compile before initializers evaluate,
+even on a first push, and initializers resolve pending dependencies first;
+cycles report the participating values. It also checks derived-edge extractor compatibility against metadata
+from the last pull; run `neo pull` if that metadata is missing.
+
+A clean dry-run doesn't guarantee a clean push. The server still checks the
+live head, per-change CAS bases, authorization, row shapes, file staging, and
+admission.
+
+## Push
+
+- Push recompiles only bodies affected by changed declarations, prepares the
+  transaction once before confirmation, and reuses it after.
+  `--force-recompile` (with or without `--dry-run`) sweeps every body; use it
+  only to diagnose stale derived IR.
+- One accepted push atomically commits records, main-locale text, bindings,
+  and staged file metadata. Pending IDs and source rewrites become real only
+  after acceptance.
+- Normal push hashes the authored source it read and does not re-lower the
+  whole tree. A lowering mismatch therefore surfaces on the next canonical
+  pull; dry-run is the full source-to-record proof.
+- `non-fast-forward`: someone committed after your pull. Pull, then push.
+- `base-hash-conflict`: pull and resolve.
+- `version-bump-required`: inspect the classification and pass
+  `--accept-bump` only when intended.
+- Completion arrives through a live subscription, with progress every five
+  seconds. A disconnect doesn't cancel the durable job.
+
+## Output and diagnostics
+
+Interactive commands show phase spinners; `NO_COLOR` removes color only. JSON
+and piped output contain no animation. Set `NEO_COMPOSE_TRACE_PERFORMANCE=1`
+to write `neo-performance` JSON spans to stderr (`startedMs` relative to the
+process, `durationMs` per operation; nested spans overlap, so don't sum
+them).
+
+## References
+
+- [Conflicts and recovery](conflicts-and-recovery.md): merge conflicts,
+  `neo resolve`, `value-base-desync`, interrupted pushes, `.neo/state.json`,
+  `neo doctor` and `--fix`.
+- [Branches, releases, and access](branches-and-history.md): branches, merge,
+  releases, history rewrites, login profiles, tokens, flags.
+- [Unity export](unity-export.md): `neo export`, `neo dev`, local exports,
+  workspace lock.
+- [Testing](../neoscript/testing-and-migrations.md): `neo test`,
+  `neo script`, `neo migrate`.
+- [Localization](../values/defaults-and-localization.md#neo-loc): `neo loc`.

package/skills/neocompose-cli/references/sync/unity-export.md

@@ -0,0 +1,47 @@
+# Unity export
+
+`neo export` builds the Unity export from the working copy, offline, into the
+directories the Unity project's `NeoComposeConfig` asset names: `project.json`
+with a partition index, `Partitions/*.json` value rows, localization files,
+and generated C# under `<generatedTypesDirectory>/Generated/`.
+`Library/NeoCompose/export.json` is written last for Unity to ingest.
+
+- Only changed files are written. Codegen is skipped when schema inputs are
+  unchanged, but content is still validated. Repeated exports, undos, and
+  reverts reuse cached results after verifying output bytes.
+- The Unity project comes from `unityConfigPath`. Without it, an interactive
+  export offers to link the one config asset naming this project; scripts get
+  an error with the line to add. `--unity-project <dir>` exports elsewhere
+  without linking (agent rigs use it).
+- Export stops before writing on a source error, a file conflict, a
+  `download` file action, an error diagnostic, or an unchanged project file
+  whose bytes differ from the pulled file.
+- Keep `NeoGeneratedFiles.json` with the generated files; it preserves
+  `.meta` GUIDs across type renames.
+- Export reports an error when an animation clip target doesn't match its
+  owner or one of its constructed base types.
+
+Status and export stay clean when animation defaults use initializers or
+constructor arguments select collection rows through Lookups.
+
+## Local exports
+
+A clean working copy exports the pulled head; diagnostic location shifts
+alone don't count as local changes. Local edits, `Files/` bytes included, make
+the export local: `project.json` gets `metadata.localExport`, Unity fails
+player builds and keeps saves under `NeoCompose/LocalExport`, and a push or a
+clean export ends it.
+
+IDs minted for local declarations, including getters used in NeoFlow
+interpolation, are kept in `.neo/export.json`'s `identityLedger`, so the next
+push commits the IDs Unity already saw. A push re-exports into a Unity project
+that received a local export.
+
+## neo dev
+
+`neo dev` watches source, binaries, ignore rules, workspace state, and config,
+then exports in batches (20 ms quiet period, capped at 250 ms). Edits during
+an export go into the next batch. It never pulls or pushes.
+
+Pull, push, branch, merge, resolve, init, and export take turns through
+`.neo/workspace.lock`; a lock whose process died is taken over.

package/skills/neocompose-cli/references/values/defaults-and-localization.md

@@ -0,0 +1,86 @@
+# Defaults, overrides, and localization
+
+## Virtual members and sparse overrides
+
+Omitted members are virtual projections of the instance's recorded
+constructor or variant and follow later edits to that source.
+
+- Writing a member creates a sparse override with a deterministic projected
+  ID. Removing it from an existing initializer resets the override and
+  resumes tracking. Both transitions must show in `neo diff`.
+- Spelling a declared default verbatim is the same as omitting it: a leaf
+  equal to its declaration, or a bare construction the declaration wholly
+  settles, mints no override. Spelling an unchanged child default such as
+  `FPS = 8` is a no-op even when siblings own rows. A stored row that already
+  spells its default becomes sparse on its next authored edit.
+- Adding a different child default keeps sibling row identities.
+- A stored class with no construction record still inherits literal
+  declaration defaults (`FoodInfo.Quality = .OneStar` fills an existing row
+  that stores only its price). Don't add an override to repair that. Required
+  fields with no applicable default remain errors.
+- Defaulted members can be added without recreating existing instances.
+- Editing an inline child keeps the outer construction's call-site values for
+  its other fields while its variant selection matches; a different variant
+  gives it an independent recipe.
+
+## Emitted defaults
+
+A member whose default constructs its declared type emits `= new()`; a
+subclass default keeps its type (`Base Value = new Derived();`). Edit the
+declaration to change the shared default, or assign inside an instance
+initializer to override one instance. A nullable member with no default
+stays bare; an explicit null default emits `= null`.
+
+Generic arguments are types, not defaults: a required generic member needs a
+value at construction unless a member declaration supplies a default. Pull
+keeps incomplete stored objects for repair; add the initializer or default
+before testing or pushing. An override without a local initializer inherits
+the base default; an explicit `= null` is a literal nullable default.
+
+## Construction rebuilds
+
+Source is authoritative for a construction. Editing its constructor
+arguments, a static's included, rebuilds it in place on push:
+
+- the value keeps its ID and rows at unchanged positions keep theirs,
+- added entries create rows and removed entries delete them,
+- overrides the new construction no longer produces are deleted, so keep
+  intended overrides in the construction's `{ ... }` block.
+
+Switching to another overload or shared argument rebuilds even when argument
+values compare equal; owned inline arguments still compare by contents. A
+construction whose class changed fails with `construction-arguments-conflict`;
+delete and recreate the value instead.
+
+## Localized text
+
+- Write main-locale text directly in localizable string initializers. Never
+  author localized-text IDs in place of prose.
+- Equal main-locale text on the same declared member shares one localization
+  record across overrides and instances. Different members keep separate
+  contexts.
+- Editing a class default updates inheriting instances; editing one instance
+  doesn't change the default. Reverting an instance to its default restores
+  the shared record and archives an unreferenced unique one.
+- An empty string stores no localization ID. Nullability, not text length,
+  decides whether the member is required.
+
+## neo loc
+
+Source files hold only main-locale text. Use `neo loc` for other locales,
+statuses, comments, archives, and repair:
+
+```sh
+neo loc locales
+neo loc list
+neo loc set <textId> <locale> "text"
+neo loc status-set <textId> <locale> <statusId>
+neo loc comment-set <textId> <locale> "comment"
+neo loc archive <textId>
+neo loc restore <textId>
+```
+
+Batches go on stdin or `--file` as a JSON array where supported. `neo loc`
+doesn't rewrite source; run `neo pull` after it (or any web edit) before
+further edits or a push. A write refused because another commit landed is
+run again.

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

@@ -0,0 +1,71 @@
+# Managed files
+
+Images (PNG, JPEG, GIF, SVG) and audio clips are declared in typed registries
+and stored as tracked binaries. SVG keeps its original bytes everywhere; the
+CLI never rasterizes it.
+
+## Registries
+
+```neo
+ImageRegistry Images = new() {
+  @id("sword-image-file-id")
+  @settings(template: PixelArt)
+  NeoImage Sword = new("Files/Images/Sword.png");
+}
+
+AudioClipRegistry AudioClips = new() {
+  @id("sword-hit-audio-file-id")
+  @settings(template: SoundEffect)
+  NeoAudioClip SwordHit = new("Files/AudioClips/SwordHit.wav");
+}
+```
+
+- `Images.Sword.Slice(0)` is a sprite; `AudioClips.SwordHit` is a clip. A bare
+  `Images.Sword` is only a file ID, valid in file-valued contexts such as
+  `SpriteInfo.FileId`.
+- Registries and binaries may sit in any non-ignored folder. Update the path
+  when moving a binary.
+- Renaming the symbol or replacing bytes keeps the file ID when `@id` stays.
+- Symbols derive from the persisted file name (`tree.cherryblossom.png`
+  becomes `TreeCherryblossom`). Keep the symbol aligned or set
+  `@settings(name: "TreeCherryBlossom.png")`. The name must end with the
+  binary's extension because pull rebuilds the path from it.
+- Without `@settings(template: ...)`, the CLI stores the complete built-in
+  Unity import defaults for the file kind. Template-backed settings may hold
+  sparse leaf paths such as `platformSettings.standalone.maxTextureSize` or
+  `spriteSettings.pivot.x`; keep them so untouched settings inherit.
+
+A declaration can live in its own file, listed by name in the registry. The
+declaration carries `@id`, `@settings`, and the path, and must be listed
+exactly once:
+
+```neo
+// Values/Audio/SWORD_HIT.neo
+@id("sword-hit-audio-file-id")
+@settings(template: SoundEffect)
+NeoAudioClip SWORD_HIT = new("Files/AudioClips/SwordHit.wav");
+
+// Files/AudioClips.neo
+AudioClipRegistry AudioClips = new() {
+  NeoAudioClip SwordHit = SWORD_HIT;
+}
+```
+
+## Adding, replacing, removing
+
+- Drop a supported binary under `Files/Images/` or `Files/AudioClips/` to
+  create a pending file with a provisional symbol. Status, diff, and dry-run
+  don't rewrite the registry; a successful push creates the record, uploads
+  verified bytes, and writes its declaration and ID.
+- Remove the declaration to delete a file. A declaration whose binary is
+  missing is an error.
+- Pull keeps unchanged entries, comments, and order; new remote entries
+  append, deleted ones are removed in place.
+
+## Transfers and conflicts
+
+Pull and push compare server-verified SHA-256, byte length, and MIME type.
+Pull downloads up to eight files at once, reuses matching local bytes, and
+verifies every download before replacing anything; a failed transfer leaves
+files intact. A diverged binary keeps local bytes and writes the server copy
+under `.neo/conflicts/files/<file-id>/`.

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

@@ -0,0 +1,97 @@
+# Identities
+
+## Keep, omit, or author
+
+- Keep every existing `@id` through rename, reorder, and file moves. Renaming
+  a member with its ID keeps its value graph; update initializer keys to the
+  new name and keep child IDs.
+- A copy gets a new ID.
+- New records omit `@id`. A successful real push assigns and inserts it;
+  dry-run and failed pushes leave source unchanged.
+- Never match an existing ordered row by index or payload. A bare row is a
+  pending create.
+- Never invent IDs for rows whose identity derives from an owner role: root
+  and static bindings, projected values, and constructor arguments (named or
+  positional), whose identity comes from the schema key the parameter
+  settles.
+
+Nested class and list rows keep inline IDs:
+
+```neo
+Tags = [
+  @id("story-tag-item-id")
+  "story",
+];
+```
+
+## Authored UUIDs
+
+When a same-push structural reference has no symbol, path, or unique-key
+form, give the new row a never-used UUID-v4 `@id` and reference it in the same
+edit. The server checks shape and uniqueness. Reusing an existing ID means
+update, not create. Dry-run keeps a valid authored UUID-v4 on a new nested
+member or dictionary value. A malformed unknown ID is an error at its
+annotation: remove it or supply an unused UUID-v4. Prefer generated IDs.
+
+## Moving a nested value
+
+A stored nested class value may keep its UUID-v4 when moved to an empty,
+compatible class field on another existing parent, if all of these hold:
+
+- the old owning declaration is removed in the same push,
+- both fields declare the same non-generic class and storage rules,
+- exactly one ownership path remains to the same root or static binding
+  through ordinary class fields, and
+- both paths use inherited storage and automatic distribution, with no member
+  overrides.
+
+Moves of projected values, constructor-owned slots, partitioned values,
+generic instances, unordered-list entries, or into newly constructed parents
+are refused. Omit the ID to create a new value there instead.
+
+## Local initializer IDs
+
+An existing row ID may precede a local declaration. It names the initializer
+row, not a stored global:
+
+```neo
+@id("existing-quest-row-id")
+Quest HardAsStone = new Quest() { Name = "Hard as stone" };
+```
+
+`Quest HardAsStone = @id("...") new Quest();` is accepted and formatted to the
+form above. Never put an ID in both places. A local keeps its concrete type
+when a base-typed member consumes it.
+
+## Locals as constructor arguments
+
+In constructor arguments and executable operands, a class local names its one
+stored instance rather than building a copy. Its owning placement keeps it,
+so a constructor that stores it needs a `Reference` field:
+
+```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);
+
+class QuestUnlockStep(DeliveryQuest quest) : WorkflowStep {
+  public Reference<DeliveryQuest> Quest = quest;
+}
+```
+
+- The local needs exactly one owning placement. Unowned locals, ambiguous
+  placements, and cycles are source errors.
+- A nested target needs its existing `@id`. A structurally owned list entry
+  may use an unused UUID-v4 in the same push.
+- A local nested inside an evaluated constructor stays idless on first push;
+  push assigns its identity before it can be referenced. Don't give it a fresh
+  UUID.
+- A direct static owner supplies a pending identity for an idless local, and
+  aliases of that static local work too.
+- A member default is a construction template, so its local is not a single
+  stored instance.
+- Owned locals inside evaluated initializers need directly addressable fields,
+  list entries, or literal dictionary keys. Inline the construction when a
+  computed key hides the owning path.
+- Canonical construction arguments may use `Reference<Type>(id: "...")`.

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

@@ -0,0 +1,151 @@
+# References
+
+`Reference<T>` names one stored row. `T` may be any value type, collections
+and other references included; code types such as `Action<int>` are rejected.
+
+## Handles and slots
+
+- A handle has a class, interface, List, Set, or Dictionary `T`. The
+  reference is the object: `Reference<Item>` reads as `Item`, and assigning an
+  `Item` rebinds it. A handle never owns, so it can't hold a new list or a
+  query result.
+- A slot has any other `T` (`bool`, numbers, `string`, enums, vectors, `Color`,
+  sprites, audio clips, `NeoVariant<T>`, `NeoDialogueReference`, or one
+  `Reference<U>`). It names another member and reads and writes that member's
+  value.
+
+Inside a generic body, `Reference<T>` takes the category of `T`'s binding.
+
+## Declaring lookups
+
+```neo
+public Reference<Config> Config;            // one row, reads as Config
+public Set<Reference<Config>> Configs;      // several, reads as Set<Config>
+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
+  selections.
+- `@settings(collection: Owner.Member)` binds a class reference to one
+  collection. Unbound references select any stored row of `T` or a subclass,
+  or any member slot of type `T`. A bound reference can't be a generic
+  argument. Settings on `T` itself are an error; the language server's quick
+  fix respells them.
+- The lookup class must be assignable to the collection's entry class; a
+  subclass may narrow it. An `NPC` lookup can't select from `List<Quest>`.
+- A class-constrained generic lookup (`Reference<TAsset>` with
+  `TAsset extends HeldItemAsset`) may bind a collection of the bound class.
+  Overrides that specialize the target keep the collection setting.
+- A single reference's initializer body returns one row, never a set.
+- `Reference<T>` satisfies interface `T Foo { get; }` or `{ get; set; }` and
+  abstract `T Foo { get; }`.
+- Generated C# exposes a read-only interface; call `TryWritable` to write.
+
+## Defaults
+
+```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);
+```
+
+- 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.
+- List and dictionary defaults may hold slot references, nested too:
+  `List<Reference<int>> Counts = [Reference(root.Save.Bits)]`. Each instance
+  owns the collection; entries target the original slots.
+
+## Source forms
+
+```neo
+Reference(Assets.Capitol)
+Reference(root.Player.Gold)
+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<NeoDialogue>(id: "capitol-dialogue-id")
+```
+
+- Prefer a symbol or root path. A slot always names a member path or `id:`.
+- `key:` needs a unique index. Omit `index:` when there is exactly one.
+- Use `id:` when the ID is all you have. Unknown named arguments are errors.
+- `withProvenance: true` (executable NeoScript only, default false) selects
+  the nearest `sourceValueId` clone of an authored row in the receiver's
+  ownership graph. It is not a member-default form.
+- `key:` and `id:` work in declaration defaults; a key there resolves after
+  every pass, so it may name a row the same push creates.
+- `Reference(value)` keeps an evaluated class value's identity; it neither
+  clones nor wraps. An optional type argument checks the target.
+- Animation and frame-override targets are selectors, not references; see
+  [animation](../world/animation.md#child-selectors).
+
+## 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.
+
+```neo
+this.A = 5;                       // writes 5 into A's target
+this.A = this.Count;              // writes Count's value into A's target
+this.A = this.B;                  // A now names B's target
+this.A = Reference(this.Count);   // A now names Count
+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.
+- Constructors may initialize their own reference fields but can't write
+  through external targets.
+- `==` compares handles by identity and slots by value. Collections of
+  references compare entries by target, so `Set<Reference<int>>` holds
+  distinct slots. Narrow `Reference<T>?` before writing through it.
+- The target row decides every write: asset-owned targets error, `readonly`
+  targets reject writes after initialization, a Save target accepts them.
+- Slot `OnChanged` listeners fire on rebinding and on target changes.
+
+## Same-push resolution
+
+Declaration and file order don't matter within a push, and cyclic identity
+references are legal. After the push, targets must exist (rows deleted by the
+edit don't count) and satisfy assignability, membership, multiplicity, and
+group constraints.
+
+A projection may assign existing class values to lookup storage directly:
+
+```neo
+EligibleIngredients = root.Assets.Crafting.FurnaceRecipes
+  .Select((MachineRecipe recipe) => recipe.Ingredient)
+  .ToSet()
+```
+
+Lookup assignment still needs an existing backing row.
+
+`collectionValue` settings name the collection itself
+(`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.
+Invalid reference settings are errors, never silently dropped.
+
+## Init-built objects
+
+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
+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.