@neocompose/cli 0.1.6 → 0.2.1

package/skills/neocompose-cli/SKILL.md

@@ -1,214 +1,368 @@
 ---
 name: neocompose-cli
 description: >-
-  Edit a Neo Compose project's schema as C# files and sync bidirectionally
-  with the server using the `neo` CLI. Use when asked to add/change/remove
-  custom types, attributes, or enums in a Neo Compose project, to validate or
-  evaluate NeoScript, or to batch-edit values and localized strings. The
-  working copy lives in a `neo/` directory (neo.json + Attributes/ + Enums/);
-  commands are run via `node cli/bin/neo.mjs` (repo) or `npm run neo`.
+  Edit and synchronize a Neo Compose format-v2 schema as real C# 11 plus
+  tracked NeoScript sidecars. Use for custom types, interfaces, attributes,
+  enums, templates, localization, schema-aware NeoScript, or batch content
+  edits. The working copy is a neo/ directory; run `neo` from the published
+  package or `node cli/bin/neo.mjs` in the web repository.
 ---
 
 # Neo Compose schema-as-code CLI (`neo`)
 
-The `neo/` working copy is a **git-like checkout** of a Neo Compose project
-version's schema: custom types and their attributes as one C# class per file
-under `Attributes/`, enums under `Enums/`. The server is the source of truth;
-files are a peer editor alongside the web UI. Spec:
-`specs/schema-as-code-cli.md`.
-
-In Unity projects, `neo.json` may set `unityConfigPath` (relative path to the
-game's `NeoComposeConfig.asset`) instead of `projectId`/`versionId` — the
-asset is then the single source of truth for both ids, and version-changing
-commands (`neo branch switch`, …) update the asset so the game always targets
-the same version as the working copy. Never re-add the ids to `neo.json` in
-that mode; the CLI rejects the duplication.
-
-## Core discipline
-
-1. `neo pull` before editing (and before any push after time has passed).
-2. Edit the C# files **within the constrained subset** (see below).
-3. `neo status` / `neo diff` to review, `neo push --dry-run` to preview.
-4. `neo push` to commit — atomically, with compare-and-swap base hashes.
-5. **Pull → push with no edits is always a no-op.** If `neo status` reports
-   changes right after a pull, that is a bug — report it, don't push.
-
-The CLI never guesses: anything outside the subset is a file:line:column
-error. Conflict markers in a file make it unparseable until resolved.
-
-## The C# subset
-
-- One top-level `class` (custom type) or `enum` per file.
-- Properties carry exactly one `Neo*` attribute: `NeoBool`, `NeoInt`
-  (`Min`/`Max`), `NeoFloat` (`+DecimalPoints`), `NeoString`
-  (`Localizable`/`SearchKey`),
-  `NeoDictionary`/`NeoList` (entry chains), `NeoObject` (custom type),
-  `NeoEnum`, `NeoLookup` (`CollectionId`), `NeoProperty`
-  (`Code`, optional `SetterCode`, `RetJson`),
-  `NeoSprite`/`NeoAudio` (`TemplateId`), `NeoFunction`, and
-  `NeoNSFunction` (`Code`, `RetJson`, `ArgsJson`, `Deferred`).
-- The positional string argument is the stable record id. **Omit it to
-  create**: `[NeoFloat(Min = 0)] public float? Weight { get; init; }` — push
-  assigns the id and rewrites the file canonically.
-- Property nullability IS the `required` flag: `int?` optional, `int`
-  required. Property name is the schema key (`Key`/`Name` args override).
-- Enum members: the member name is the option key (codegen symbol);
-  `[NeoEnumEntry(Text = "...")]` carries the display/localized-text id.
-- `ExtraJson` holds fields the projection doesn't express — edit it as JSON,
-  never delete it casually.
-- No method bodies, no initializers, no extra `using`s.
-
-## Conflicts
-
-Concurrent edits produce git-style `<<<<<<< local / ======= / >>>>>>> server`
-markers at member granularity. **Edit the file to the desired final state and
-push — the push IS the resolution** (it supersedes both sides). `neo resolve
---mine|--theirs` keeps one side wholesale. Markers break C# compilation on
-purpose.
-
-If push reports `base-hash-conflict`: run `neo pull` (merges or writes
-markers), resolve, push again. Never bypass with `--force`-style flags.
-
-If push reports `version-bump-required`: the server classified the change
-(e.g. `requiredBump: major` for schema changes). Re-run with
-`neo push --accept-bump` if the bump is intended.
-
-## NeoScript
-
-NeoScript is C#-flavored: typed declarations (`string x = ...;`, NOT `var`),
-`this` = the containing type instance, `root.Assets` / `root.Save` /
-`root.Session` roots. Validate before storing in a `NeoProperty` `Code` or
-`SetterCode` arg, or invoke a stored typed NeoScript Function:
+A `neo/` working copy is a Git-like checkout of one Neo Compose project
+version. C# and NeoScript are peer authoring surfaces beside the web UI; the
+server remains the shared source of truth. The current contract is format v2
+and is documented in `specs/schema-as-code-cli.md`.
 
+## Non-negotiable workflow
+
+1. Run `neo pull` before editing and before pushing after time has passed.
+2. Edit real C# 11 and the tracked `.neo` sidecars. Never edit `.neo/state.json`
+   or `.neo/tooling`.
+3. Run `neo status` or `neo diff`, then `neo push --dry-run`.
+4. Run `neo script check --all` after a schema rename or signature change.
+5. Push one reviewed atomic change with `neo push`.
+
+**Pull followed immediately by status/push must be a no-op.** If it reports
+schema changes, stop and report a round-trip bug rather than pushing it.
+
+The compiler reports file:line:column diagnostics and never guesses. Unknown
+authorable server fields fail with “CLI contract upgrade required”; they never
+hide in an opaque JSON carrier.
+
+## Setup and format requirement
+
+```sh
+npm i -g @neocompose/cli
+neo login [--api <url>] [--profile editor|release] [--save-project <id>]
+neo init --project <id> [--version <id>] [--dir neo]
+neo doctor
+```
+
+Repository development uses `node cli/bin/neo.mjs`. Agents should always pass
+explicit flags/IDs. Human terminals may show pickers and confirms; non-TTY/CI
+use fails with an actionable missing-flag diagnostic rather than blocking.
+
+`neo.json` must contain `formatVersion: 2`. A missing or different marker is
+unsupported. Preserve any source you need, then create a fresh v2 working copy:
+
+```sh
+neo init --project <id> [--version <id>] [--dir neo]
+```
+
+`neo pull --reset` is only for an existing v2 workspace; it reconstructs
+CLI-managed source from the server and refreshes the compiler SDK and analyzer.
+
+Neo never downloads or installs .NET. Compiler host discovery is:
+
+1. explicit `NEO_DOTNET_HOST`;
+2. a compatible Unity 6000 runtime;
+3. a compatible system `dotnet`.
+
+The validated selection is cached under `.neo`; `neo doctor` reports its
+path, kind, runtime/Unity version, cache status, and compiler/SDK contract
+compatibility. An invalid explicit override is a hard error.
+
+In Unity projects, `neo.json` may use `unityConfigPath` instead of
+`projectId`/`versionId`. The referenced `NeoComposeConfig.asset` is then the
+single source of truth, and branch switches update it. Never duplicate the IDs
+in `neo.json` in this mode.
+
+## Working-copy layout
+
+```text
+neo/
+  neo.json
+  NeoCompose.Schema.csproj        # netstandard2.1, C# 11, IDE-only
+  Types/                          # custom classes
+  Interfaces/                     # interface declarations
+  Enums/
+  Root.cs                         # [NeoRegistry] roots and loose members
+  Templates/                      # typed texture/audio settings
+  Localization.cs                 # typed localization settings
+  LocalizationStatuses/*.cs      # typed localization workflow statuses
+  Scripts/<Type>/<Member>.neo     # computed properties and NeoScript methods
+  Migrations/*.neo
+  .neo/
+    state.json                    # bases/CAS hashes; never hand-edit
+    dotnet-host.json
+    tooling/                      # bundled SDK, analyzer, generator, compiler
+```
+
+The schema project is not referenced by the game. `.neo/`, `bin/`, and `obj/`
+are gitignored; source and scripts are tracked.
+
+## Authoring real C#
+
+Native C# carries native meaning:
+
+- Plain, `virtual`, `abstract`, and `override` members map directly to schema
+  behavior. An override's base record identity comes from the resolved symbol.
+- Base classes, interfaces, generic parameters/arguments, and `where`
+  constraints use ordinary syntax.
+- Property type determines Neo kind; nullable annotation determines whether it
+  is optional; initializer determines its default.
+- Declaration order determines schema/enum order unless an explicit typed
+  ordering attribute is present.
+- Method parameters and return type are the function signature.
+  `Task`/`Task<T>` means deferred execution.
+- Concrete `[NeoScript]`/`[NeoFunction]` methods are C# 11 partial
+  declarations. The bundled source generator adds inert compile-only bodies.
+  Abstract functions are ordinary abstract methods.
+
+```csharp
+using System.Collections.Generic;
+using System.Threading.Tasks;
+using NeoCompose.Schema;
+
+[NeoEnum("enum-item-type")]
+public enum ItemType
+{
+    [NeoEnumOption("option-food", Text = "Food")]
+    Food,
+}
+
+[NeoType("type-inventory-item", AllowedStorage = NeoAllowedStorage.Static)]
+[NeoSchemaOrder(nameof(Name), nameof(Type), nameof(Tags), nameof(UsePrimary))]
+public abstract partial class InventoryItem<
+    [NeoId("generic-stack")] TStack>
+    where TStack : class
+{
+    [NeoMember("attribute-name"), NeoText(SearchKey = true)]
+    public virtual string Name { get; init; } = "";
+
+    [NeoMember("attribute-type")]
+    public abstract ItemType Type { get; init; }
+
+    [NeoMember("attribute-tags"), NeoList(Kind = NeoListKind.Unordered)]
+    [NeoEntries(nameof(TagEntries))]
+    public virtual IReadOnlyList<string> Tags { get; init; } = new List<string>();
+
+    private static readonly NeoEntrySettings[] TagEntries =
+    {
+        new()
+        {
+            Id = "entry-tag",
+            Path = "[]",
+            Kind = NeoEntryKind.String,
+            Text = new NeoTextSettings { Localizable = false },
+        },
+    };
+
+    [NeoMember("function-use-primary"), NeoScript]
+    public virtual partial Task<bool> UsePrimary(InventoryItem<TStack> target);
+}
+```
+
+Stable IDs are visible in `[NeoType]`, `[NeoInterface]`, `[NeoEnum]`,
+`[NeoEnumOption]`, `[NeoId]`, and `[NeoMember]`. Omit a nullable positional ID
+only when creating a record; a successful push assigns it and canonically
+rewrites the source. Once assigned, preserve it through renames.
+
+`[NeoMember]` owns identity/common options. Use narrow typed attributes for
+Neo behavior: `NeoText`, `NeoNumber`, `NeoDictionary`, `NeoList`, `NeoEntries`,
+`NeoIndex`, `NeoColumn`, `NeoLookup`, `NeoDialogue`, `NeoFile`, `NeoComputed`,
+`NeoScript`, `NeoFunction`, `NeoSystem`, and explicit schema/generic binding
+attributes. Use the typed settings classes for nested entries, template import
+options, localization, and system metadata. This is intentional: every valid
+option should appear in C# IntelliSense.
+
+A bodyless `[NeoComputed]` property needs no initializer or `#pragma`. The
+bundled analyzer suppresses only its sidecar-backed `CS8618`; ordinary nullable
+warnings remain enabled.
+
+Allowed values are statically analyzable literals, enum values, `nameof`,
+`typeof`, arrays/collections, object initializers, approved Neo value types,
+and `Neo.Ref<T>`, `Neo.Lookup<T>`, `Neo.Dialogue`, `Neo.Sprite`, `Neo.Audio`,
+or `Neo.Member` references. Authored code is never executed.
+
+Never introduce opaque carriers or identity escapes: `ExtraJson`, `DefaultJson`,
+`RetJson`, `ArgsJson`, `EntryChainJson`, `SchemaKeyOrderJson`,
+`GenericParamIds`, `ChainJson`, `SignatureJson`, `ExtendsId`, `isVirtual`, or
+`isAbstract`.
+
+Define each localization workflow status in
+`LocalizationStatuses/<Name>.cs` using `[NeoLocalizationStatus("stable-id")]`
+and a static `NeoLocalizationStatusSettings` object. The marker owns identity;
+typed properties cover slug, display metadata, archive state, transition
+rules, automatic transitions, and system restrictions. Keep the order in
+`NeoLocalizationSettings.StatusIds`.
+
+## NeoScript sidecars
+
+Scripted member bodies live at exactly
+`Scripts/<DeclaringType>/<Member>.neo`.
+
+A computed property uses one complete contextual file. The outer signature
+matches the linked C# declaration's semantic result (`Task<T>` functions use
+`T`) and adds the implicit `this` and `root` execution parameters:
+
+```neoscript
+string Description(InventoryItem this, Root root) {
+  get {
+    return $"{this.Name} ({this.Type})";
+  }
+
+  set(string value) {
+    this.Name = value;
+  }
+}
+```
+
+A concrete `[NeoScript]` method uses the same outer contextual signature and
+puts its declared arguments and executable body in a nested unit:
+
+```neoscript
+bool UsePrimary(InventoryItem this, Root root) {
+  (InventoryItem target) {
+    return target.IsStackable;
+  }
+}
 ```
+
+The complete wrapper is tracked on disk and displayed identically in editors;
+Monaco protects the signature/braces while leaving the getter, setter, or
+function body editable. Abstract scripted members have no file.
+
+Missing, duplicate, case-colliding, ambiguous, and orphaned sidecars are hard
+diagnostics. A sidecar for an abstract member is also invalid. The stable C#
+member ID lets canonical renames move the file safely; include C# and sidecar
+renames in the same reviewed change.
+
+Canonical C# places `// NeoScript: Scripts/<Type>/<Member>.neo` above the
+linked declaration. Go-to-definition, references, and rename use the Roslyn
+source identity plus stable member ID to navigate between C# and `.neo`.
+
+NeoScript is C#-flavored: use typed declarations (`string name = ...;`, not
+`var`); `this` is the containing instance; roots include `root.Assets`,
+`root.Save`, and `root.Session`.
+
+```sh
+neo script check --all
 neo script check --this Outpost --returns string 'return $"{this.Name}!";'
 neo script check --mode setter --attribute ComputedName 'root.Session.Name = value;'
 neo script check --mode nsfunction --attribute Outpost.RefreshUnlock 'return this.Level > 0;'
 neo script compile --mode nsfunction --attribute Outpost.RefreshUnlock 'return this.Level > 0;'
-neo script check --all              # recompile every stored NeoScript body
 neo script eval --returns string 'return root.Assets.Outposts[0].FullDisplayText;'
-neo script apply --mode action '...'  # prints write intents; commits nothing
 neo script eval --function Outpost.RefreshUnlock --this-value <id> --args '[3]'
-neo script apply --function Outpost.RefreshUnlock --this-value <id> --args '[3]'
+neo script apply --mode action '...'
 ```
 
-`eval` runs against authored values with the same evaluator the web UI uses.
-NSFunction `apply` is also preview-only: it reports the return value, write
-intents, and created Session rows but commits nothing. Purely NeoScript
-deferred paths may complete inline; native suspension reports unsupported.
-`--json` everywhere for machine-readable output.
+`eval` uses authored values and the same evaluator as the web app. `apply` is
+preview-only unless its command explicitly supports a commit; it reports
+return values and write intents. Prefer `--json` for automation.
 
-## Content (not in files)
+## Conflicts and version bumps
 
-Values, dialogue, and localized text are CLI verbs, not files:
+Overlapping concurrent schema edits produce explicit local/server conflict
+markers. They intentionally fail compilation. Edit source to the desired final
+state and push; that push is the resolution. `neo resolve --mine|--theirs` is
+whole-side convenience only.
 
-```
-neo records query [--kind <recordKind>]   # every record head in the version
+For `base-hash-conflict`, pull, resolve, and push again. Never seek a force
+bypass. For `version-bump-required`, inspect the classification and repeat
+with `neo push --accept-bump` only when intended.
+
+Script conflicts block validation in the same way and must be resolved in the
+tracked `.neo` file.
+
+## Content stays in commands
+
+Values, dialogue instances, localized text, and project files are records, not
+schema source files:
+
+```sh
+neo records query [--kind <recordKind>]
 neo records get <kind> <id>
-neo values list [attributeId] / get <valueId> / set <valueId> '<json>'
-neo loc locales / list / set <textId> <locale> "text"
+neo values list [attributeId]
+neo values get <valueId>
+neo values set <valueId> '<raw-json-value>'
+neo loc locales
+neo loc list
+neo loc set <textId> <locale> "text"
 ```
 
-Every `set` verb accepts a JSON-array batch on stdin or `--file` (e.g.
-`[{"textId":"...","locale":"de-DE","value":"..."}]`) — use batches when
-editing many records.
+Write verbs accept a JSON-array batch on stdin or `--file`; use one batch when
+edits must be atomic. A `values set` payload is the raw value, not
+`{"value": ...}`. For collection rows use `values add-entry` on the live
+container value; an attribute's default container ID may not be an instance's
+container.
 
-## Branches, merges, releases, migrations
+### Dialogue authoring
 
-```
-neo branch list / create <name> [--from <ref>] / switch <nameOrId>
-neo merge <branch> [--dry-run]     # field-level 3-way; conflicts reject with per-record+field payload
-neo release cut [--bump ...] [--dry-run]   # bump floor DERIVED from transaction history; raise-only
-neo migrate new <name> --target <Type>     # creates Migrations/NNNN-name.neo
-neo migrate list / check / run [--dry-run] [--skip-invalid]
-```
+Always run `neo dialogue dryrun [ref]` after editing dialogue. It traverses
+option paths from a fresh save and applies the runtime's mutation-ownership
+rules. Exit 1 means the authored graph would fail on device.
 
-Branches are copy-on-write forks (cheap; edits isolated until merged).
-Landing a branch into its fork parent auto-archives it (refreshes don't);
-archived versions hide under the picker's "Archived" submenu and behind
-`neo branch restore <name>`.
-Migrations are NeoScript actions in `.neo` files: `/// @migration <id>`,
-`/// @target <Type|project>` headers, then the action body; `this` = each
-instance of the target type. The v1 runner applies `this.<Field> = ...`
-assignments as one atomic CAS transaction and marks `appliedAt` per version
-(idempotent, per-branch). Sparse instances abort unless `--skip-invalid`.
+`neo dialogue export <ref>` and `neo dialogue apply <spec.json> [--dry-run]`
+round-trip a whole dialogue. `neo dialogue compile` compiles condition/action
+blocks with their dialogue/node context. Localized node fields hold text IDs;
+create/edit those records through `neo loc` with their links.
 
-## Setup (once per machine/repo)
+Lookup collection mutation is a common trap: mutating a collection through a
+lookup may resolve to an authored asset collection and be forbidden. The
+dialogue dry run exists to catch this and related save/session ownership bugs.
 
-```
-npm i -g @neocompose/cli   # or run from the web repo: node cli/bin/neo.mjs
-neo login [--api <url>] [--profile editor|release] [--save-project <id>]
-neo init --project <id> [--version <id>] [--dir neo]
-neo dev [--push]    # live: auto-pull on server change; 'p' push, 's' status
+## Branches, releases, and migrations
+
+```sh
+neo branch list
+neo branch create <name> [--from <ref>]
+neo branch switch <nameOrId>
+neo merge <branch> [--dry-run] [--migrate]
+neo release cut [--bump major|minor|patch] [--dry-run]
+
+neo migrate new <name> --target <Type>
+neo migrate list
+neo migrate check
+neo migrate run [--dry-run] [--skip-invalid]
 ```
 
-Agents run non-interactively: always pass explicit flags/ids. (In a human
-terminal the same commands prompt with pickers and confirms; with no TTY the
-CLI never blocks on a prompt — missing arguments raise an error that names
-the flag to pass, and confirms fall back to the pre-prompt behavior.)
-
-Tokens land in the macOS Keychain when available (0600 file elsewhere;
-`NEO_COMPOSE_TOKEN` / `--token-stdin` for CI). `--save-project` adds a
-narrow per-project save-read scope for `script eval --save`.
-
-## Dialogue validation & batch authoring
-
-- **ALWAYS run `neo dialogue dryrun [ref]` after authoring or editing
-  dialogues.** It walks every option path from a fresh save, executes every
-  action/condition through the real evaluator, and applies the Unity
-  runtime's mutation-ownership rules (save/session clone-on-write,
-  lookup-resolution). Exit 1 = the runtime would throw on device. Known
-  trap it catches: `root.Save.Inventory.Add(...)` — collection mutations
-  THROUGH Lookup attributes resolve into the referenced asset collection
-  and always fail at runtime.
-- `neo dialogue apply <spec.json> [--dry-run]` authors a whole dialogue
-  from one declarative file: nodes with `say`/`options`/`do` (NeoScript
-  `code` compiled server-side, `bind` overrides the action's `this`),
-  `group`/`start`/`linkedValueId`; strings minted in one transaction.
-  `neo dialogue export <ref>` round-trips an existing dialogue into the
-  same shape (actions surface compiled `ir`). Workflow: export → edit →
-  apply → dryrun.
-- Cross-outpost writes need authored OutpostSaveMap entries for every
-  outpost (fresh saves seed from authored values) — `values add-entry` on
-  the save-map dict with `key=<outpost value id>`.
-
-## Content authoring (dialogues, items, strings)
-
-- `neo dialogue create '<IDialogueBase json>'` writes a whole dialogue (node
-  graph + trigger) in one call; `edit`/`delete` manage the record. Node text
-  fields hold localized-text IDS — mint the strings afterwards with
-  `neo loc create '{"id":<textId>,"value":"...","links":[...]}'` using
-  `dialogue-node-text` / `dialogue-choice-text` links (recordKind
-  `dialogue-node`). `localizedTextEdits` on node create/edit only EDITS
-  existing texts.
-- `neo dialogue compile '{"code":...,"target":0|1|2,"dialogue":{},"node":{"primaryLinkedValueId":...}}'`
-  returns wire-ready compiled logic (0=condition, 1=action, 2=text variable).
-  Actions bind `this` to the NODE's primaryLinkedValueId — to unlock another
-  outpost, bind the action node to THAT outpost's value id. Lambdas don't
-  compile inside actions; lookup adds accept entry ids:
-  `root.Save.Inventory.Add("<entryValueId>")`.
-- Collection rows: `neo values add-entry <containerValueId>
-'{"entryAttributeId":...}'` (server mints the entry tree; find the LIVE
-  container by querying which list value contains existing entries — an
-  attribute's `valueId` may be its DEFAULT container, not the instance).
-  `neo values set <leafId> '<raw json value>'` — raw value, NOT wrapped in
-  `{"value":...}`.
-- `neo script eval --returns "string[]"` etc. accept `T[]`/`T?` suffixes;
-  `neo script compile` prints compiled getter/action IR.
-
-## Implementation notes agents should know
-
-- The CLI talks to **Convex directly** with typed `api.*` calls; pushes go
-  through the session-gated `commitFromSession` (same scope gates + CAS as
-  the web). `--json` is available on status/diff/branch list/migrate
-  list/script/records/values/loc.
-- The working copy also projects `Templates/*.cs`, `Localization.cs`, and
-  `Migrations/*.neo`. Migration pushes **pin compiled IR** on the record;
-  `migrate run` replays the pinned IR (rename-proof). `migrate run --server`
-  executes in the server runner; `neo merge --migrate` chains migrations at
-  merge, and `release cut` refuses while any migration is pending.
-- Pull short-circuits on the sync-signal head ("Already up to date") when
-  nothing changed server-side and the copy is clean.
-
-The editor profile cannot publish releases; that requires `--profile release`
-at login (server-enforced scopes — ZERO TRUST).
+Branches are copy-on-write forks. Releases are immutable snapshots; their bump
+floor is derived from transaction history and may only be raised. Release
+operations require the release login profile.
+
+Migrations remain NeoScript action files under `Migrations/`, with stable
+headers and pinned compiled IR. The server runner tracks per-branch applied
+state; merge may chain pending migrations before validation.
+
+## Editor and implementation contract
+
+The browser-safe `neoscript-language` service is shared by the compiler, CLI,
+web Monaco editor, and VS Code LSP. Do not add language intelligence directly
+to an environment adapter.
+
+Monaco's existing highlighting, comments/interpolation, bracket behavior,
+protected scaffolds, context-aware completion/hover, and accurate diagnostics
+are a release-blocking compatibility floor. V2 adds recovery completion,
+signature help, C# and script definitions, references, rename, document
+symbols, semantic tokens, quick fixes, formatting, richer diagnostics,
+contextual ranking, and incremental analysis. Project updates must refresh
+context without accumulating stale providers.
+
+The VS Code extension consumes the same service and grammar/token spec. Its
+LSP supports the same diagnostics, completion, hover, signature, navigation,
+rename, symbols, semantic tokens, and formatting. The VSIX is built in-repo;
+marketplace publication is separate.
+
+## Agent implementation notes
+
+- The Node CLI talks directly to Convex through typed `api.*` calls and uses
+  the same session-gated CAS commit path as the web app.
+- `SchemaManifestV2` is the only C# source/document boundary. The contract
+  registry classifies authored, derived, and volatile fields; derived server
+  fields come from the pulled base and absent/null equivalents normalize.
+- The npm package bundles the Roslyn app, dependencies, SDK, analyzer, and
+  generator under `dist/tooling`; it does not bundle a runtime.
+- The schema compiler does static analysis only. Never execute an authored
+  assembly to obtain settings.
+- A change is incomplete until typecheck/tests/builds, package-content and
+  contract-version checks, Monaco parity/browser-bundle suites, VSIX
+  packaging, Unity sample tests, live `neowyn` no-op verification, and final
+  `npm run doctor` succeed.
+
+Tokens use the macOS Keychain/OS credential store when available, a protected
+file only as fallback, and `NEO_COMPOSE_TOKEN` or `--token-stdin` in CI. The
+editor profile cannot publish releases; server-enforced scopes are the
+security boundary.