@neocompose/cli 0.87.2 → 0.89.0

package/skills/neocompose-cli/references/neoscript/types-and-narrowing.md

@@ -0,0 +1,111 @@
+# Types, narrowing, and tuples
+
+Null and type narrowing, patterns, equality, generic functions, and tuples.
+
+## Null narrowing
+
+- Null propagation continues through later required accesses in the same
+  chain: `config.Hat?.Head.Idle.Down.Frames` is null when `Hat` is null. A
+  nullable descendant still needs its own `?.`, `??`, `!`, or guard.
+- `Member` and `this.Member` share narrowing. A local or parameter named
+  `Member` shadows the member; `this.Member` still names the field.
+- Reassigning a narrowed path to a nullable value clears its facts and its
+  descendants' facts. Writes to unrelated members keep guards, also in loops.
+  A false earlier condition narrows later `else if` conditions.
+- `a ?? b` is non-null when `b` is non-null, including in constructor
+  arguments such as `new Sprite(item.Sprite ?? SpriteInfo.Empty)`.
+- Where a reference is expected, `first ?? fallback` picks the reference; a
+  present reference whose target is null does not select the fallback. In a
+  scalar context the reference reads its target first.
+- Lookup results follow the same rules.
+
+## Type patterns
+
+```neo
+if (item is not BedItem bedItem) {
+  throw "Expected a bed item";
+}
+return bedItem.Name;
+```
+
+- A binding stays in scope after a guard when every path that falls through
+  matched, including when other paths return from a nested block.
+- `value is not T name` binds only where the test is known false: the `else`
+  branch, the right of `||`, or after a rejecting guard. The operand evaluates
+  once. `not` is an ordinary identifier elsewhere.
+- Patterns follow the possible runtime type. An open class can match an
+  unrelated interface through a subclass that implements it; a sealed class
+  without it is a compile-time impossible pattern. A class implements each
+  interface once, so a value known to be `IBox<int>` never passes
+  `is IBox<string>`.
+- An interface guard such as `if (item is not IReceiver) continue;` narrows
+  `item` itself: it keeps its declared class or generic `T` members and gains
+  `IReceiver` members. Later class guards accumulate (`IReceiver` then
+  `Furnace` exposes both). Guards that return, throw, or break work the same.
+- A declaration pattern keeps the original receiver's type too: after
+  `if (item is not IReceiver receiver) return;`, `item` is unchanged and
+  `receiver` exposes `IReceiver`.
+- Generic `is` tests check whether the bound can overlap the tested type.
+- Guards also narrow named globals and static member paths, qualified or not,
+  inherited included. Assignment clears the proof. Closures must guard again
+  because the stored value can change before they run.
+- A generic receiver may call members of its class or interface constraint;
+  nullable receivers still need narrowing.
+
+## Equality
+
+`==`, `!=`, `Contains`, `IndexOf`, and `Remove` compare class, interface,
+List, Set, and Dictionary values by identity. Primitives, enums, vectors, and
+media references compare by value. The static type decides, so an
+unconstrained `T` compares by value.
+
+`Equals(other)` on a non-null generic value calls the runtime class's
+one-argument `bool Equals` (including overrides) when it has one, otherwise
+falls back to value equality. Local sets fall back to comparing current
+entries in insertion order.
+
+## Generic functions
+
+Functions, natives, and interface functions may declare type parameters with
+optional constraints and defaults:
+
+```neo
+public static T? FirstOf<T extends Item = Item>(List<T> items) => items.FirstOrDefault();
+```
+
+- Call with every type argument, omit a defaulted tail
+  (`FirstOf<Seed>(items)`), or omit `<...>` to infer from arguments.
+- Lambda inputs bind first so their returns can infer outputs, as in
+  `Map(seed, (value) => value.Price)`. Defaults fill parameters with no
+  evidence. The expected return type is not evidence. Explicit `<...>`
+  never infers the omitted tail. Conflicting types need explicit arguments;
+  inference does not invent a common ancestor.
+- Function type parameters take no `@id`. Overrides declare the same count,
+  constraints, and defaults but may rename them.
+
+Generic class arguments are invariant through inheritance: `IntBox : Box<int>`
+assigns to `Box<int>`, never `Box<string>`. Typed locals accept generic
+classes (`Box<int> box = new(1);`). Explicit lambda parameter types accept
+the full declaration grammar, including `decimal`, generics, collections, and
+nullables.
+
+## Tuples
+
+```neo
+(int Row, int Col) position = (Row: 2, Col: 3);
+var (row, col) = position;
+(int first, (bool enabled, int _)) = (1, (true, 9));
+var score = positions.Select(((r, c)) => r + c);
+```
+
+- Two or more elements. Labels are optional and don't affect type identity;
+  `Item1`, `Item2`, ... always work. Slots are immutable: replace the tuple.
+- `((r, c)) =>` takes one tuple; `(r, c) =>` takes two parameters. Recursive
+  patterns work in declarations, loop bindings, and lambda parameters. `_`
+  discards. Assignment deconstruction is unsupported.
+- Equality is recursive by element; decimal scale is ignored, classes and
+  collections compare by identity.
+- `(int, int)?` is a nullable tuple; `(int?, int)` has a nullable element.
+
+Stored tuple members are covered in
+[member kinds](../declarations/member-kinds.md#stored-tuples).

package/skills/neocompose-cli/references/sync/branches-and-history.md

@@ -0,0 +1,69 @@
+# Branches, releases, and access
+
+## Branches and releases
+
+```sh
+neo branch list
+neo branch create <name> [--from <ref>]
+neo branch switch <nameOrId>
+neo branch refresh [--dry-run]
+neo merge <branch> [--dry-run] [--migrate]
+neo release cut [--bump major|minor|patch] [--dry-run]
+```
+
+- Branches are copy-on-write forks; releases are immutable snapshots.
+- Switching needs a clean checkout. Unpushed source or binaries, conflicts,
+  source errors, and pending push recovery stop it before anything changes.
+  Push or back up first; `neo pull --force` only when discarding is intended.
+- Creation waits until the durable copy publishes. The source stays readable
+  while copying.
+- The server derives the minimum compatibility bump; a caller may only raise
+  it. Releases need the `release` login profile.
+- In Unity projects using `unityConfigPath`, branch and version switches
+  update `NeoComposeConfig.asset`.
+
+## History
+
+```sh
+neo history inspect
+neo history log
+neo history prune [--project <id|@latest|@current>]
+neo history flatten [--project <id|@latest|@current>] --version <id|@latest|@current>
+neo history apply --plan <plan-id> [--confirm-scope <project-id>[/<version-id>]]
+neo history status --run <run-id>
+neo history resume --run <run-id>
+```
+
+Rewrites need project owner or admin. `prune` and `flatten` only create
+immutable plans. `apply` starts the destructive run once the plan seals;
+production also needs the exact scope confirmation the plan shows.
+
+## Login and credentials
+
+```sh
+neo login [--api <url>] [--profile editor|release] [--save-project <id>]
+neo whoami
+neo logout [--api <url>]
+```
+
+- Inside a workspace these use its `apiBaseUrl`; `--api` wins; outside, the
+  build's default origin. Login prints the origin before storing anything.
+- Tokens use the OS credential store, falling back to a protected file. In CI
+  use `NEO_COMPOSE_TOKEN` or `--token-stdin`. The CLI refreshes its
+  short-lived JWT during long commands.
+- The editor profile can't publish releases; server scopes are the security
+  boundary.
+- `logout` deletes the credential for exactly one origin and revokes the
+  session best-effort.
+- `NEO_COMPOSE_CONFIG_HOME` (absolute path replacing
+  `$XDG_CONFIG_HOME/neo-compose`) and `NEO_COMPOSE_CREDENTIAL_NAMESPACE`
+  (keychain account scope) isolate concurrent environments on one OS user.
+
+## Automation
+
+- Pass explicit project/version IDs and flags, prefer `--json`, and never
+  depend on pickers or confirms. Non-TTY runs never wait for them.
+- Boolean flags are bare switches; `--dry-run=true` is rejected.
+- `--dry-run` exists on push, merge, refresh, branch refresh, release cut, and
+  migrate run; elsewhere it is rejected before any action. `branch create`
+  has none.

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,63 @@
+# 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.
+
+## C# target and extension wrappers
+
+Set `codegen.csharpVersion` in `neo.json` to a numeric language version such as
+`"14"`. `latest` and `preview` are rejected. Without an override, export uses
+the supported Unity compiler mapping or the SDK's C# 9 baseline. It reads
+`codegen.unityVersion` first, then the linked Unity project's
+`ProjectSettings/ProjectVersion.txt`. `neo doctor` reports the effective target
+and its source. An unrecognized Unity version produces a baseline warning.
+
+Closed instance extension functions can generate classic C# extension methods.
+Interface receivers, open receiver types, static extensions, and computed
+extension properties require C# 14. Export omits an unavailable wrapper and
+reports its member ID, receiver, and missing capability. It keeps the member
+available to the NeoScript evaluators and SDK direct invocation API. Changing
+the target regenerates wrappers and removes obsolete owned wrapper files.

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: "...")`.