[Parked: gateway is transition surface] SchemaStore for gateway configs

Summary

Publish the catalog and gateway-config file formats as registered JSON Schemas (SchemaStore.org), so editors validate and autocomplete catalog.json/catalog.yaml and gateway_config.yaml files as users type.

Priority: P3 · Confidence: Medium

Why this matters

Hand-authored config/catalog files are a primary adoption surface (contextweaver init scaffolds one; the zero-Python mcp serve --config flow depends on one). Editor-integrated validation catches typos (descripton, wrong nesting) at authoring time instead of at load time, and SchemaStore registration makes that work in VS Code/JetBrains with zero user setup — a small polish that signals maturity.

Current evidence

• schemas/catalog.schema.json exists and is drift-gated (make schemas-check, issue #225 lineage) — but nothing associates it with file patterns in editors.
• examples/recipes/gateway_config.yaml (the mcp serve --config single-file format, issue #346) has no published schema at all — it would need to be authored (the config keys live in _mcp_cli.py's loader).
• docs/schemas/v0/ mirrors the schemas on the docs site, giving a stable public URL candidate.

External context

SchemaStore.org is the de-facto registry that YAML/JSON language servers (VS Code's built-ins, JetBrains) consult automatically; registration is a PR to the schemastore catalog mapping file patterns to a hosted schema URL. Schemas must be hosted at a stable URL (the GitHub Pages docs site qualifies).

Proposed implementation

1. Author schemas/gateway_config.schema.json from _mcp_cli.py's config loader (this is valuable on its own: it forces the config surface to be precisely specified); add it to the make schemas/schemas-check generation set if feasible, else commit + test against the example file.
2. Establish stable hosted URLs (e.g., https://dgenio.github.io/contextweaver/schemas/v0/<name>.schema.json) — verify the docs build already publishes docs/schemas/v0/.
3. Define filename conventions to map (e.g., *.cw-catalog.json|yaml, cw-gateway*.yaml — design decision: pick patterns specific enough not to collide with unrelated files, and document them).
4. Submit the SchemaStore registration PR; document inline # yaml-language-server: $schema=... usage as the no-registration fallback in the recipes.

AI-agent execution notes

• Inspect first: _mcp_cli.py config-loading code (every accepted key, type, default), schemas/ + _schema_gen.py, mkdocs.yml/docs.yml (does the published site serve the schema files verbatim?), examples/recipes/gateway_config.yaml.
• Run: jsonschema validation of all committed example configs/catalogs against the schemas (add as a test); make schemas-check.
• Edge cases: YAML 1.1 quirks (booleans), additionalProperties policy (recommend false for the config schema to catch typos — but verify no documented extension keys exist first).
• Do not change config semantics to fit the schema; the schema documents reality.

Acceptance criteria

• A gateway-config schema exists, validates the committed example, and is covered by tests.
• Both schemas are reachable at stable public URLs.
• SchemaStore PR submitted (link it here); recipes document the inline $schema fallback.

Test plan

Schema-vs-example validation tests in tests/test_recipes_configs.py; manual VS Code check with the inline directive; docs-site URL reachability check post-deploy.

Documentation plan

Recipes pages gain a "editor validation" note; CHANGELOG; AGENTS.md module map if a new generator lands.

Migration and compatibility notes

Not expected to require migration. The config schema effectively freezes key names — future config changes must update it (the drift gate makes that automatic if generated).

Risks and tradeoffs

SchemaStore review timelines are outside project control (the inline-directive fallback delivers most value immediately); filename-pattern collisions if chosen too broadly (be conservative). Authoring the config schema may surface undocumented/ambiguous keys — resolving those is a feature of doing this work.

Suggested labels

developer-experience, enhancement, area/docs, area/gateway

Start with _mcp_cli.py, schemas/, _schema_gen.py, mkdocs.yml or docs.yml, and examples/recipes/gateway_config.yaml. Run make schemas-check and inspect tests/test_recipes_configs.py to understand existing generation and validation coverage. Done means the gateway schema validates the example, both schemas have stable hosted URLs, recipes document the inline fallback, and the SchemaStore PR is submitted.