@neocompose/cli 0.87.2 → 0.88.0

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

@@ -1,30 +1,17 @@
 # CLI development
 
-Use this reference only when changing the CLI, language service, package, or
-the skill itself. Project authors usually do not need it.
-
-## Contents
-
-- Source of truth
-- Feature-spec status
-- Shared implementation contract
-- Package and release maintenance
-- Verification
+Read only when changing the CLI, language service, package, or this skill.
+Project authors don't need it.
 
 ## Source of truth
 
-Treat the current CLI compiler, shared-language implementation, contract
-registry, tests, and generated corpus as the executable source of truth. Use
-the feature specs to understand intent and edge cases, but do not call the old
-umbrella project-source document complete: it predates P38–P52 and contains
-obsolete authoring examples.
-
-When a spec status header disagrees with released implementation and tests,
-verify the shipped package and implementation PR before teaching the feature.
-
-## Feature-spec status
+The CLI compiler, shared language implementation, contract registry, tests,
+and generated corpus are the executable truth. Specs explain intent and edge
+cases. When a spec's status header disagrees with the released
+implementation and tests, check the shipped package and implementation PR
+before teaching the feature.
 
-Read the relevant specs in full:
+Specs to read in full when relevant:
 
 - [P38 complete schema declarations](https://github.com/ryanbliss/neo-compose-specs/blob/main/new-features/complete/p38-neo-source-complete-schema-declarations.md)
 - [P39 authored system schema](https://github.com/ryanbliss/neo-compose-specs/blob/main/new-features/complete/p39-neo-authored-system-schema.md)
@@ -33,8 +20,8 @@ Read the relevant specs in full:
 - [P42 structured leaf fields](https://github.com/ryanbliss/neo-compose-specs/blob/main/new-features/complete/p42-addressable-structured-leaf-fields.md)
 - [P43 initializers and constructors](https://github.com/ryanbliss/neo-compose-specs/blob/main/new-features/complete/p43-neoscript-initializers-and-constructors.md)
 - [P44 nested-row provenance](https://github.com/ryanbliss/neo-compose-specs/blob/main/new-features/complete/p44-authored-provenance-for-nested-class-rows.md)
-- [P45 deferred runtime-child provenance](https://github.com/ryanbliss/neo-compose-specs/blob/main/new-features/p45-provenance-for-runtime-children.md)
-- [P46 proposed provenance hardening](https://github.com/ryanbliss/neo-compose-specs/blob/main/new-features/p46-provenance-hardening.md)
+- [P45 runtime-child provenance, not implemented](https://github.com/ryanbliss/neo-compose-specs/blob/main/new-features/p45-provenance-for-runtime-children.md)
+- [P46 provenance hardening, proposal](https://github.com/ryanbliss/neo-compose-specs/blob/main/new-features/p46-provenance-hardening.md)
 - [P47 same-push references](https://github.com/ryanbliss/neo-compose-specs/blob/main/new-features/p47-same-push-value-references.md)
 - [P48 animation segments](https://github.com/ryanbliss/neo-compose-specs/blob/main/new-features/p48-sprite-animation-segments.md)
 - [P49 required construction](https://github.com/ryanbliss/neo-compose-specs/blob/main/new-features/p49-required-constructors-and-settled-members.md)
@@ -46,105 +33,101 @@ Read the relevant specs in full:
 - [P61 initializer materialization](https://github.com/ryanbliss/neo-compose-specs/blob/main/new-features/complete/p61-initializer-materialization.md)
 - [P64 NeoScript unit testing and push hooks](https://github.com/ryanbliss/neo-compose-specs/blob/main/new-features/p64-neoscript-unit-testing-and-push-hooks.md)
 
-P38–P44, P47–P52, P55, P60–P61, and the initial P64 test/push-hook vertical slice
-are implemented. P45 remains deliberately deferred; do not
-build or teach runtime-child provenance. P46 is a hardening proposal, not an
-authoring capability. P52's document header still says proposed, but try/catch
-shipped in CLI 0.18; implementation and parity tests take precedence over that
-stale header.
-
-CLI 0.61 adds `while` and `do / while` loops, ordinal string `Replace`,
-ordered-list `Insert`, and method calls whose results may be discarded.
-See the [NeoScript reference](neoscript.md) for authoring syntax and limits.
-
-CLI 0.71 adds collection queries, negative declaration patterns, and native
-Debug output with authored stack traces. Compiled test caches include the
-relative spec path because source coordinates are part of the compiled body.
-Keep Debug output on stderr, including during JSON test runs.
-
-## Shared implementation contract
-
-Manifest contracts, document comparison, normalization, and three-way merge
-live in `packages/manifest`. Contract generation and its registry live in
-`packages/manifest/schema-contract`. Web, backend, and CLI consumers import
-`@neocompose/manifest`; production application code must not import CLI internals.
-
-The CLI uses plain document snapshots and shared runtime functions. Keep Retree and web view models out of its imports. The headless architecture check follows CLI imports, and `cli/build.mjs` rejects UI modules and packages in the actual bundle metadata.
-
-Keep parsing, strict resolution, formatting, diagnostics with authored file and expression ranges, symbols, and
-NeoScript compilation in the browser-safe `@neocompose/neoscript-language`
-service. Monaco, VS Code, CLI, trusted server, and corpus tooling must consume
-that shared implementation. Do not add language intelligence to one adapter.
-
-Resolve disk formatting through the Node-only `node-format-options` entrypoint
-and `.editorconfig`; keep filesystem configuration out of browser imports.
-Format regenerated source before compiling it so cached source ranges match
-the written files. Preserve authored source when a push changes no source tokens.
-
-Keep evaluation in `@neocompose/neoscript-runtime` and shared schema/value
-contracts in `@neocompose/models`. Models depend on language and manifest;
-runtime depends on those packages. App context projection, database adapters,
-and reactive hosts remain in the app. Packages must not import host code.
-Boundary and import-cycle checks run with `npm run lint:architecture`;
-`npm run test:runtime-package` checks a standalone custom database host.
-
-Keep project context refreshable without accumulating stale Monaco providers or
-LSP state. Preserve diagnostics, completion, hover, signatures, definition,
-references, implementations, rename, symbols, semantic tokens, code actions, and formatting
-parity for `.neo` and `.neoflow`.
-
-The CLI prepares every push with the server's own preparation code: it
-compiles changed NeoScript bodies and callers affected by schema-contract
-changes, materializes values, and validates the whole graph against the pulled
-head. The server accepts that preparation only from a CLI on its NeoScript
-compiler revision and re-checks the head, authorization, row shapes, and CAS
-bases. A modified CLI can therefore write bad rows to a project its user may
-already write; keep preparation in shared `src/database` code rather than
-forking it in the CLI. The server still verifies a push's uploaded
-project-file bytes, and web editor commits use the shared client preparation protocol.
-Unrelated source files are not uploaded or recompiled on every push.
-Optional source maps missing from valid stored bodies do not request a backfill.
-Formatting-only source location changes do not create pushes, including when
-other records change. Stored initializer recipes, computed member defaults, and
-inline constructor delegates preserve their pulled code and compiled bodies when
-source tokens are unchanged. String-literal content remains significant.
-Evaluation maps the current local layout; authored edits,
-dependency changes, and explicit forced recompilation retain their normal compile scope. A CLI lowering mismatch on a normal push is exposed by the next
-canonical pull; `neo push --dry-run` remains the complete source-to-record
-rehearsal.
-
-A committed push result is journaled in `.neo/state.json` before source
-projection. If projection fails, `neo pull` consumes that result and preserves
-later local edits before fetching newer remote changes. Do not advance the merge
-base without preserving recovery, or retry the write as a new push. Candidate
-value projection shares the push envelope completion; persisted physical rows
-and content hashes remain the merge base.
+## Package boundaries
+
+- Manifest contracts, document comparison, normalization, and three-way merge
+  live in `packages/manifest`; contract generation in
+  `packages/manifest/schema-contract`. Consumers import
+  `@neocompose/manifest`. Production app code never imports CLI internals.
+- The CLI uses plain document snapshots and shared runtime functions. Retree
+  and web view models stay out; the headless architecture check and
+  `cli/build.mjs` reject UI modules in the bundle.
+- Parsing, resolution, formatting, diagnostics with authored ranges, symbols,
+  and NeoScript compilation live in the browser-safe
+  `@neocompose/neoscript-language`. Monaco, VS Code, CLI, server, and corpus
+  tooling all consume it; never add language intelligence to one adapter.
+  Keep diagnostics, completion, hover, signatures, navigation, rename,
+  symbols, semantic tokens, code actions, and formatting at parity for
+  `.neo` and `.neoflow`, and keep project context refreshable without stale
+  Monaco providers or LSP state.
+- Disk formatting goes through the Node-only `node-format-options` entrypoint
+  and `.editorconfig`. Format regenerated source before compiling so cached
+  ranges match written files.
+- Evaluation lives in `@neocompose/neoscript-runtime`, schema/value contracts
+  in `@neocompose/models`. Models depend on language and manifest; runtime on
+  those. App context projection, database adapters, and reactive hosts stay
+  in the app. `npm run lint:architecture` checks boundaries and cycles;
+  `npm run test:runtime-package` checks a standalone database host.
+- Compiled test caches include the relative spec path because source
+  coordinates are part of the compiled body. Debug output stays on stderr,
+  including in JSON test runs.
+
+## Push preparation
+
+The CLI prepares every push with the server's own preparation code: compile
+changed bodies and schema-affected callers, materialize values, validate the
+whole graph against the pulled head. The server accepts that preparation only
+from a CLI on its NeoScript compiler revision and re-checks head,
+authorization, row shapes, CAS bases, and uploaded file bytes. A modified CLI
+can therefore write bad rows to a project its user may already write, so keep
+preparation in shared `src/database` code instead of forking it. Web editor
+commits use the shared client preparation protocol.
+
+- Unchanged source files are neither uploaded nor recompiled. Changed bodies
+  share one schema projection; each compiles once for local evaluation and
+  once against minted IDs.
+- Formatting-only location changes create no push. Stored initializer
+  recipes, computed defaults, and inline constructor delegates keep pulled
+  code and compiled bodies when tokens are unchanged; string content still
+  counts. Missing optional source maps don't request a backfill.
+- Push hashes the authored inputs it read (paths and formatting included);
+  the same bytes and base keep reconnect identity across candidate UUID
+  allocation.
+- Durable preparation is chosen from the semantic record workload. Staging
+  reads one plan per bounded batch with an atomic write per physical chunk.
+- Each command uses one authenticated Convex websocket. Push sends compressed
+  JSON through `clientCommits.commit` when there are no staged files and it
+  decodes to at most 512 KiB; otherwise it streams `begin`, `appendChunks`,
+  and `seal`. The CLI pins the deployment through the authenticated app
+  origin before sending a session token.
+- A committed result is journaled in `.neo/state.json` before source
+  projection. Never advance the merge base without preserving recovery, and
+  never retry the write as a new push. Further result pages are downloaded
+  and counted before the base advances; edits made while waiting trigger fresh
+  analysis.
+- Full pulls size pages to Convex limits, fetch ranges concurrently, and pin
+  every page to one published generation and logical revision, restarting if
+  either changes. Undo/reset metadata changes invalidate the incremental
+  cursor and fall back to a full snapshot.
 
 ## Package and release maintenance
 
-Keep the npm artifact native JavaScript. Do not publish `.csproj`, `.cs`,
-`.dll`, Roslyn host metadata, generated C# SDK output, or trusted server-only
-wrappers.
+Publish native JavaScript only: no `.csproj`, `.cs`, `.dll`, Roslyn host
+metadata, generated C# SDK output, or trusted server-only wrappers.
 
-The marker near the top of `SKILL.md` must exactly match the package version:
+The marker near the top of `SKILL.md` must exactly match the package version,
+and this quoted copy is checked too:
 
 ```html
-<!-- reviewed-through-cli: 0.87.2 -->
+<!-- reviewed-through-cli: 0.88.0 -->
 ```
 
-The quoted version above is checked too, so this instruction cannot go stale
-while the skill advances.
+Keep this skill on current behavior. Upgrade steps, rollout prerequisites,
+and release history belong in release notes.
 
-For every CLI behavior change, audit the affected skill/references in the same
-feature PR and add a unique `.changeset/*.md` release note. Leave versions,
-changelogs, and these markers unchanged. `npm run version:packages` combines
-fragments in a release PR and advances the markers after those feature reviews.
-`npm run doctor` and package verification still check marker/version agreement
-and the newest changelog entry. See `.changeset/README.md` in the repository.
+For every CLI behavior change, update the affected skill pages in the same
+feature PR and add a unique `.changeset/*.md`. Leave versions, changelogs,
+and markers alone; `npm run version:packages` advances them in the release
+PR. `npm run doctor` and package verification check marker/version agreement
+and the newest changelog entry. See `.changeset/README.md`.
 
-Keep `agents/openai.yaml` and every directly linked reference inside the
-published `skills/neocompose-cli/` tree. Keep the frontmatter limited to
-`name` and `description`.
+Skill layout: `SKILL.md` links domain pages, and each domain page links its
+own leaves. Put new detail in the narrowest leaf that owns the API, and keep
+`SKILL.md` and domain pages to rules that apply across their branch. Every
+Markdown file must be reachable from `SKILL.md` by relative links inside the
+published `skills/neocompose-cli/` tree; `npm --prefix cli run skill:check`
+and package verification enforce it. Keep `agents/openai.yaml` in that tree.
+Frontmatter holds only `name` and `description`.
 
 ## Verification
 
@@ -152,14 +135,15 @@ Run focused language/compiler tests for changed behavior, then:
 
 ```sh
 python3 <skill-creator>/scripts/quick_validate.py cli/skills/neocompose-cli
+npm --prefix cli run skill:check
 npm --prefix cli run test:package
 npm run typecheck
 npm run doctor
 ```
 
 Also run contract/corpus checks, Monaco/browser parity, VSIX packaging, and
-interactive sample no-op verification when the corresponding implementation
-surface changes. Evaluator or candidate-materialization changes also require an
-actual `neo test` run against the affected full-project candidate; focused
-Vitest coverage does not replace that end-to-end command. Run `npm run doctor`
-last; do not rerun successful suites only because doctor formatted files.
+interactive sample no-op checks when those implementations change. Evaluator
+or candidate-materialization changes also need a real `neo test` against the
+affected full-project candidate; Vitest doesn't replace it. Run
+`npm run doctor` last, and don't rerun passing suites just because doctor
+formatted files.

package/skills/neocompose-cli/references/declarations/annotations-and-storage.md

@@ -0,0 +1,112 @@
+# Annotations and storage
+
+Typed annotations on declarations and members. Never author `@system`; system
+types visible in source may carry it, which does not license copying it. Keep
+annotations separate rather than inventing a metadata bag, and use numeric
+literals for numeric limits.
+
+## Annotation list
+
+- `@settings(...)`: format, search, collection, and editor constraints. Use
+  contextual enum cases: `@settings(format: .Plain)`,
+  `@settings(kind: .Unordered)`. Before a `List`/`Set` element or `Dictionary`
+  value type it configures entries:
+  `List<@settings(format: .Plain) string>`,
+  `Dictionary<string, @settings(min: 0) int>`. Only the declaring member spells
+  entry settings; overrides share them.
+- `@storage(allowed: ...)`: on classes and members. See [Storage](#storage).
+- `@visibility(.Hidden)`: classes only; absence means visible.
+- `@relations(...)`: only on the source class of a specialized direct
+  relation.
+- `@distribution(kind: .Sparse | .Packed)`: only on a value-owning member or
+  override. `.Sparse` gives the value its own row; `.Packed` stores it in the
+  parent's row and shares the parent's document-size limit (an oversized
+  write fails). Omit it unless the choice must be explicit: absence means
+  automatic on a declaration and inherit on an override. `.Packed` is
+  rejected on an unordered List.
+- `@effect`: on an immediate, parameterless `void` instance function with a
+  NeoScript or abstract body. Unity runs it for every live instance and reruns
+  it when data it read changes; the web editor, `neo test`, and dry runs never
+  run it. Overrides inherit it; `@effect(kind: .None)` stops it. Prefer it to
+  polling or hand-relayed changes.
+- `@index(member: Field, kind: .Unique)` and `@column(member: Field, ...)`
+  with `width`, `visibility`, `pin`, and `overflow`: repeatable List
+  annotations naming a bare entry-class field. An index takes a non-localizable string or single-select
+  enum. A column may target `__other__` for subclass-added fields. Declare
+  indexes only on the original List member; `@index` on an override is an
+  error. A List field may override an abstract List getter.
+- `@listeners(...)`: see
+  [delegates and listeners](../neoscript/delegates-and-listeners.md#persisted-wiring).
+
+Defaults and settings must be statically analyzable. Enum initializer errors
+are reported at the authored expression, including inside extracted locals
+and for missing dictionary option keys.
+
+## Storage
+
+Member `@storage(allowed:)` is `.Immutable`, `.Save`, `.Session`, or
+`.Writable`; omit it to inherit the placement parent's storage.
+
+`.Writable` is always runtime-writable and resolves by placement: Save under
+a Save parent, Session under a Session or Immutable parent. Use it for
+members that NeoScript or animation clips write and that should persist
+exactly when their owner does.
+
+```neo
+class AnimationSpriteObject(SpriteInfo sprite) : NeoSpriteObject {
+  @storage(allowed: .Writable)
+  public override Vector3 Size = new(1, 1, 0);
+}
+```
+
+- Overrides below a `.Writable` member may be `.Writable`, `.Save`,
+  `.Session`, or omitted; never `.Immutable`, `.Inherit`, or `readonly`.
+- Statics, `readonly` members, and project roots can't be `.Writable`.
+- On a class, `.Writable` means every placement resolves to Save or Session.
+  Subclasses may narrow to `.Save` or `.Session`. Undeclared statics of such a
+  class are Session.
+
+## User data
+
+`root.User` holds per-player data shared by every save, such as settings.
+Only User classes go there:
+
+```neo
+@storage(allowed: .User)
+class AudioPrefs {
+  public float Volume = 1;
+}
+```
+
+- Base and subclasses must also be User classes.
+- Members declare no `@storage` and no stored statics. Every named type must
+  be User-safe: primitives, enums, User classes, collections and delegates of
+  those, and interfaces with User-safe signatures.
+- Code in a User class reads only `root.User`. Other code may read
+  `root.User` but not assign, mutate, construct, or invoke User data.
+- Lookups and listeners don't cross between User and Save data; Session
+  lookups may target `root.User`.
+
+## readonly and constants
+
+`readonly` is C# init-only and independent of storage. A field initializer,
+constructor body, object initializer, or authored value sets it; nothing
+writes it later. It's valid on Save, Session, Immutable, and User classes,
+not with Writable, and may read header parameters:
+
+```neo
+class MixerGroup(string name) {
+  public readonly string Name = name;
+  public readonly List<MixerChannel> Children = [];
+}
+```
+
+Readonly is shallow: a readonly collection's membership is fixed, entries
+follow their own rules.
+
+A readonly member declared as a literal (no initializer or constructor call) that
+reads neither `this` nor constructor arguments and holds nothing writable is
+a constant: instances share it and store nothing until a constructor or
+initializer writes it. Readonly collections and initializers still build per
+instance. Immutable member constants are covered in
+[initializers](initializers.md#immutable-members).

package/skills/neocompose-cli/references/declarations/constructors.md

@@ -0,0 +1,164 @@
+# Constructors
+
+Header and declared constructors, settlement, parameter defaults, and
+inheritance. Member defaults are in [initializers](initializers.md).
+
+## Header constructors
+
+Put one required constructor on the class header when the whole body needs
+its parameters:
+
+```neo
+class Foo(string bar, bool isFun) {
+  public string Bar = bar;
+  public bool IsFun;
+
+  init {
+    IsFun = isFun;
+  }
+}
+
+Foo value = new(bar: "BAR", isFun: true) { IsFun = false };
+```
+
+- Header parameters are in scope in every instance member. Field
+  initializers, collection entries, object initializers, and lambdas read them
+  per construction, so `public NeoDelegate<int> Value = () => n;` returns each
+  instance's own `n`. A lambda may also read `this` (`() => n + this.M`); the
+  rest of an initializer can't.
+- Statics can't read header parameters.
+- At most one `init` block.
+- A header constructor disables implicit parameterless `new` and forbids
+  other constructor overloads. Its derived identity takes no `@id`.
+
+## Declared constructors
+
+Declare overloadable constructors as members when each body owns its own
+parameters:
+
+```neo
+class Foo {
+  public string Bar;
+  public bool IsFun;
+
+  public Foo(string bar, bool isFun) {
+    this.Bar = bar;
+    this.IsFun = isFun;
+  }
+}
+```
+
+Their parameters are visible only in that body, never in member initializers.
+Each declared constructor must settle every required member itself; a
+call-site block can't repair an invalid constructor.
+
+## Required members and settlement
+
+```neo
+class Result {
+  public string Value;   // required
+  public bool Ok = true; // settled by default
+  public string? Note;   // settled by implicit null
+}
+```
+
+A required member is settled only by:
+
+1. its own initializer,
+2. assignment on every reachable path of `init` or a constructor body (full
+   `if`/`else` coverage), or
+3. a call-site initializer entry on an otherwise valid construction.
+
+Side effects inside other functions never count.
+
+Construction order: base construction, member initializers, `init` or
+constructor body, then the call-site block, which wins where it refines an
+earlier value. Call-site blocks may set `readonly` members of the new
+instance, including nested `new` expressions.
+
+When a construction leaves a member unsettled, the diagnostic points at `new`
+with the member declaration as a related location. Unrelated valid root
+initializers still take part in reference checking.
+
+## Parameter defaults
+
+```neo
+class Foo(string bar = "BAR", int volume = 3) {
+  public string Bar = bar;
+  public string Shout(string text = "hey", bool loud = true) {
+    return loud ? text.ToUpper() : text;
+  }
+}
+
+Foo a = new();             // all defaults
+Foo b = new(bar: "bar");   // volume defaults
+```
+
+- Allowed on class headers, declared constructors, native functions,
+  NSFunctions, and interface functions. Not on deferred functions, delegates,
+  actions, closures, or overrides.
+- Constants only: bool/int/float/decimal literals (optional leading `-`),
+  non-interpolated strings, `.Option` enum literals, and `null` on a nullable
+  parameter. Defaulted parameters come last. `Type? name` without a default is
+  still mandatory.
+- Function calls drop only a trailing suffix; constructor calls name any
+  subset covering the non-defaulted parameters. Interface implementations
+  restate defaults exactly.
+- Enum defaults store the option ID, so renaming the option only changes the
+  emitted spelling.
+
+## Inheritance
+
+```neo
+class Base(string name) {
+  public string Name = name;
+}
+
+class Child(string name, int rank) : Base(name) {
+  public int Rank = rank;
+}
+```
+
+When the base has no constructor, settle its required members in a base
+initializer block:
+
+```neo
+class Child(string name) : Base {
+  Name = name,
+  Enabled = false
+} {
+}
+```
+
+- `: Base()` or `: Base` runs a zero-argument or fully defaulted base
+  constructor when one exists. If the base has only declared constructors, it
+  uses member initializers and the base block without a base constructor. A
+  required base constructor can't be skipped. A declared constructor's
+  `: base()` must call one when the base declares one.
+- A subclass that omits required base arguments or leaves an inherited
+  required member unsettled is rejected. Bind generic base arguments
+  explicitly when needed.
+- Base-constructor arguments use the constructed class's concrete generic
+  bindings, including an `Item<T>` parameter forwarded through its base chain.
+- Constraints may construct another generic from a sibling parameter:
+
+```neo
+class PlacedItem<
+  TData extends InventoryStackData,
+  TItem extends InventoryItem<TData>
+>(TItem item) {
+  public TData Data = item.DefaultData.Clone();
+}
+```
+
+## Object initializer syntax
+
+Entries are separated by commas; a trailing comma is optional. A semicolon
+inside the braces is an error; one after the closing brace ends the
+declaration:
+
+```neo
+AudioSettings AUDIO_SETTINGS = new() {
+  Main = new AudioMixerGroupSettingsFolder("Main", "Master", "MasterVolume", []),
+};
+```

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

@@ -0,0 +1,103 @@
+# Declarations
+
+Rules for classes, interfaces, enums, and members. Open a leaf from
+[References](#references) for annotations, constructors, special member
+kinds, or overloads.
+
+## Shape
+
+Declare classes, interfaces, and enums only at the top level of definition
+`.neo` files, never inside a type, body, accessor, lambda, initializer,
+migration, or `.neoflow` file (NeoFlow has its own single-dialogue rule). The
+declared identifier is the schema name; there is no separate display name.
+
+```neo
+@id("interface-named-id")
+interface INamed {
+  @id("named-name-id")
+  string Name { get; }
+
+  @id("named-use-id")
+  void Use(SomeClass context);
+}
+
+@id("class-item-id")
+@storage(allowed: .Immutable)
+abstract class Item<TContext extends SomeClass> : INamed {
+  @id("item-name-id")
+  @settings(searchBy: .MemberKey)
+  public virtual string Name = "";
+
+  @id("item-use-id")
+  public abstract void Use(TContext context);
+
+  @id("item-load-id")
+  public native async bool Load(TContext context);
+}
+```
+
+The `@id`s above are pulled IDs. New declarations omit them; push assigns them.
+Never put `@id` on inferred list/dictionary entry types or derived structural
+descriptors.
+
+## Modifiers
+
+`public`, `protected`, `private`, `static`, `virtual`, `abstract`, `sealed`,
+and `override` follow C#.
+
+- `sealed`: an instantiable leaf. It may extend a class, can't be extended or
+  abstract, and can be sealed only while it has no subclasses.
+- `closed`: implicitly abstract, an exhaustive subtype family for switch
+  expressions. Don't combine with `abstract` or `sealed`. Descendants stay open
+  unless sealed or closed. Every generic parameter of a direct subclass must
+  appear in its base construction.
+- A read-only override may narrow a class or interface contract to an
+  assignable class or derived interface, or to non-null. Generated C# keeps
+  the inherited type.
+
+## Members
+
+- Kind and optionality come from the type and its nullability. The
+  initializer is the default.
+- A non-null member without a default is required. A nullable member without
+  a default is implicitly `null`. See
+  [constructors](constructors.md#required-members-and-settlement).
+- Omitted fields of an instance stay virtual and track later default edits
+  until overridden. See [defaults and overrides](../values/defaults-and-localization.md).
+- Use `.Case` only where context fixes one enum type, otherwise
+  `EnumType.Case`. Constructor parameters supply that context, including
+  substituted generic types. An integer is not an enum option.
+- An explicit construction must be assignable to its receiving type,
+  generic arguments included.
+
+## Names
+
+Keywords are case-sensitive. Qualified member labels, schema keys, registry
+entries, and enum options live in their owner's namespace and may reuse
+builtin names such as `Set`, `List`, or `Math`; `Set` and `Dictionary` are also
+legal parameter names. Grammar keywords stay reserved. Top-level declarations
+and bindings may not shadow `Math`, and `this`, `root`, and `context` can't be
+parameters.
+
+## Relations
+
+Keep generic project relations as typed top-level declarations in
+`Relations.neo`; the compiler derives owned descriptor and generic binding
+identities. A world layer link is a project subclass of `NeoTileLayerLink` or
+`NeoObjectLayerLink` that resolves exactly one `targetLayer` relation. The
+relation is the whole binding; add no value-level target metadata.
+
+## References
+
+- [Annotations and storage](annotations-and-storage.md): `@settings`,
+  `@storage` (Save/Session/Writable/User), `readonly` and constants,
+  `@index`/`@column`, `@distribution`, `@effect`, `@visibility`.
+- [Constructors](constructors.md): header and declared constructors, `init`,
+  required-member settlement, parameter defaults, inheritance.
+- [Initializers](initializers.md): member defaults, what they may read,
+  computed defaults, generic and Immutable construction, stored-construction
+  edits.
+- [Member kinds](member-kinds.md): interface-typed members, `Set<T>`,
+  `NeoAction`, lifecycle interfaces, stored tuples.
+- [Overloads](overloads.md): declaring overloads and how calls pick one.
+- [References](../values/references.md): `Reference<T>` lookup members.