Ship schema-driven VS Code and Zed editing for project YAML

[jeremi]

Tracked by #399.

Outcome

A Registry Stack project opened in VS Code or Zed gets useful YAML validation, completion, hover documentation, and outlining from the existing project-authoring JSON Schemas. This is the low-cost editor baseline for the 1.0 demo and does not require a custom language server.

The repository already owns strict Draft 2020-12 schemas for:

• registry-stack.yaml
• environments/*.yaml
• integrations/*/integration.yaml
• integrations/*/fixtures/*.yaml
• entities/*.yaml

registryctl authoring schema --kind <kind> already exposes the schema compiled into the installed CLI.

Requirements

• Provide a version-safe way for editors to resolve the schemas matching the installed or selected Registry Stack release.
• Do not bind editor configuration to a mutable main branch or an unrelated source checkout.
• Configure VS Code through the Red Hat YAML extension's schema association support, using a workspace setup, recommendation, or thin declarative extension as appropriate.
• Configure Zed through its native YAML language server using project settings or modelines.
• Associate all five authored file roles without applying Registry Stack schemas to unrelated YAML files.
• Add the setup to project starters or provide one deterministic, documented setup action for new and existing projects.
• Document the workflow in the public registryctl reference and a short demo path.
• Keep generated setup deterministic and free of credentials, secret values, deployment outputs, and machine-specific absolute paths.

Acceptance criteria

• A newly initialized project can enable the editor support without locating a Registry Stack source checkout or manually editing five schema paths.
• VS Code provides schema-driven key/value completion, field descriptions on hover, an outline, and inline validation for all five authored file roles.
• Zed provides the same schema-driven behavior for all five authored file roles.
• An unknown field, an invalid enum value, and an invalid value type are visibly diagnosed in both editors.
• Schema resolution is pinned to the matching Registry Stack release or installed registryctl version.
• Unrelated YAML files retain their normal editor behavior.
• Automated checks verify the generated editor configuration, file patterns, and referenced schema documents.
• The demo instructions are exercised from a clean initialized project.

Non-goals

• Cross-file symbol navigation
• Find references or rename
• Compiler-level semantic diagnostics
• Rhai or CEL expression intelligence
• A custom Language Server Protocol implementation

These belong to the shared language-server follow-up.

[jeremi]

Review notes before implementation, verified against the current tree and editor documentation (2026-07).

Cross-editor relative-path semantics differ. The Red Hat YAML extension resolves relative paths in yaml.schemas relative to the YAML file's own location; Zed resolves ./ paths in lsp.yaml-language-server.settings.yaml.schemas relative to the worktree root. One convention will not behave the same in both editors (long-standing vscode-yaml issues: redhat-developer/vscode-yaml#92, redhat-developer/vscode-yaml#1051). The generator has to emit per-editor path shapes; worth an explicit requirement bullet so this does not surface mid-implementation.

Suggested mechanism. A registryctl authoring editor-setup command (or an init flag) that writes .vscode/settings.json, .zed/settings.json, and a schema snapshot (for example .registry-stack/schemas/*.schema.json) emitted from the installed CLI. That satisfies pinning, determinism, no network, and no absolute paths in one move. Two refinements:

• a --check mode so CI catches snapshot drift after a CLI upgrade, which doubles as the documented upgrade path;
• recommend committing the snapshot so the whole team gets identical behavior, which requires the command to be idempotent and diff-stable.

Avoid modelines for the five roles. They cannot express patterns like integrations/*/integration.yaml, and vscode-yaml's modeline relative-path handling has a known bug (redhat-developer/vscode-yaml#587). Settings-based association is the right call.

Two small items to fold in:

• The schemas' $id still uses the placeholder host registrystack.example; set a real, versioned $id if the schemas are ever published at stable URLs.
• Decide explicitly on SchemaStore. Submitting the distinctive filenames (for example registry-stack.yaml) gives zero-config validation in unconfigured editors, but SchemaStore resolves to latest by default, which is in tension with the release-pinning requirement here. "Snapshot only, no SchemaStore" is a fine answer; record it either way. The fixture glob integrations/*/fixtures/*.yaml is too generic for SchemaStore regardless.