feat: publish the official catalog and StackConfig JSON Schema

[lloydrichards]

Publish the official catalog and the JSON Schema for stack.effect.json through the docs site. A compatible catalog update must reach users without a CLI release.

Parent: #275. Blocked by #271. Land the shared configuration declaration first so #273 and #274 can consume it while publication work continues.

Deliver the configuration schema

• Add optional $schema editor metadata to the canonical StackConfig declaration. Old configurations without it must remain valid.
• Define the canonical URL as https://stack-effect.lloydrichards.dev/schemas/v1/stack.effect.schema.json.
• Generate JSON Schema draft 2020-12 from StackConfig. Use the existing Schema.toStandardJSONSchemaV1 pattern in apps/cli/src/commands/schema.ts.
• Give the generated schema a $id for its hosted URL and a $schema for its JSON Schema dialect. These are separate from the optional $schema field in project configuration.
• Keep independently evolving catalog IDs out of exhaustive schema enums. Validate selections against the loaded catalog.

The CLI continues to validate with its installed domain schema. A hosted schema update must not make it fetch arbitrary schema URLs or claim support for new runtime behavior.

This issue owns the domain declaration and schema generator. #273 owns CLI configuration output and round trips. #274 owns the builder's generated configuration.

Deliver the public assets

Generate both assets from local authoring definitions during development and a clean docs build:

Public URL	Suggested source location
https://stack-effect.lloydrichards.dev/registry/v1/catalog.json	apps/docs/public/registry/v1/catalog.json
https://stack-effect.lloydrichards.dev/schemas/v1/stack.effect.schema.json	apps/docs/public/schemas/v1/stack.effect.schema.json

Build-emitted assets are also acceptable. Public URLs must not contain /public/. Asset generation must not fetch the production catalog.

Publish both files in one docs deployment. Return JSON content types and revalidation cache headers, not immutable. Support conditional requests. For cross-origin use, allow public GET requests and expose validators such as ETag. A missing registry path must return 404 rather than the app shell.

Reject exports outside #271's fixed v1 capability set. Keep an append-only fixture of published target and module IDs to catch removal or renaming. The fixture records identifiers, not historical catalog payloads. Template fixes may change generated bytes, but must pass representative generation tests.

The hosting provider is not identified in tracked config. Inspect the actual deployment setup, implement its header and route rules, and record a rollback procedure. Keep local and deployed evidence separate. Report missing deployment access if it prevents completion.

Done when

• A clean build and local development server expose both generated JSON assets at the agreed paths.
• Old configs decode, and example configs validate against the generated JSON Schema with and without $schema metadata.
• Tests reject removed published IDs and unsupported interpreter capabilities.
• Real deployed requests prove content types, conditional requests, CORS behavior, and a genuine 404.
• A catalog content update reaches the deployed endpoint without publishing the CLI.
• Deployment and rollback instructions identify the actual provider. Share this evidence with feat: deliver and qualify the official HTTP catalog registry #275.

Keep out of this issue

CLI and browser persistence adapters, configuration-source selection, immutable catalog archives, and content-version resolution. #275 owns the combined release decision.

Validate

Run bun format, bun lint, bun run type-check, affected scoped tests, and the docs build. Never use bun test. Use the catalog-workspace skill for template changes and bun run okf:check for knowledge changes. Do not claim deployed behavior from local tests alone.

[pullfrog]

No duplicate found: #109 delivered CLI catalog introspection, not hosted catalog/schema publication. #271 supplies the wire/export contract; #273 and #274 consume this issue's config contract, and #275 owns release qualification.

Implementation plan:

1. Add optional $schema and the canonical schema URL to StackConfig in packages/domain/src/Scaffold.ts first. Keep it metadata only: preserve it across Effect Schema decode/encode without fetching it, and leave tool selections as strings rather than catalog-derived enums. Hand the contract to feat: load the official registry in CLI commands #273/feat: load the official registry in Recipe Builder #274 for their config writers.
2. After feat: load the HTTP catalog with validated cache fallback #271 fixes the document schema/exporter, add a docs-owned generation script that imports only the local authoring catalog entrypoint, exports the full v1 document, and derives draft 2020-12 JSON Schema from StackConfig using the pattern in apps/cli/src/commands/schema.ts with $id and $schema. Wire it into both apps/docs/package.json dev and prebuild so a clean build emits /registry/v1/catalog.json and /schemas/v1/stack.effect.schema.json; do not use the CLI's lossy catalog-tree projection as the wire document.
3. Gate publication with v1 capability checks and a checked-in fixture of existing target/module IDs (not historical content). Test exporter round trip and identity rejection, template-change generation cases, old config decode, and generated CLI/builder configs against the emitted JSON Schema. Run scoped workspace tests, bun format, bun lint, and bun run type-check.
4. Identify the actual docs host configuration (none is tracked here), document deployment and rollback, then check the deployed endpoints for JSON bodies/MIME, revalidation headers and CORS/validators, genuine registry 404s, and a docs-only content update without a CLI release. Keep this issue open until those live checks pass; local Vite behavior is not deployment evidence.

  ^{｜ Implement plan ➔ ｜ View workflow run ｜ via Pullfrog ｜ Using GPT Sol ｜ 𝕏}

[lloydrichards]

Implementation: #281, stacked on #280. The canonical optional $schema declaration, generated catalog and Draft 2020-12 schema, published-ID fixture, Vercel routing/headers, and rollback instructions are in review.

Local evidence: format, lint, type checks, domain/docs tests, OKF validation, and docs build passed. The clean build emitted both JSON files; the local dev server returned 200 for each and 404 for a missing registry path. The Vercel preview build completed, and its deployment metadata confirms apps/docs as the project root.

Preview HTTP verification is blocked by Vercel SSO: unauthenticated requests to both assets and the missing path return 302 to Vercel sign-in before route handling. Production still returns 404 for the registry asset because #281 has not been deployed there. Content type, conditional requests, CORS, missing-path 404, and update propagation remain unverified on a public deployment. These are release evidence for #275, not claims from the local build.

[lloydrichards]

Production verification after the catalog deployment:

• Catalog and StackConfig schema return 200 with JSON content types, ETags, Cache-Control: public, max-age=0, must-revalidate, and Access-Control-Allow-Origin: *.
• If-None-Match returns 304 for both assets. An unknown registry path returns a genuine 404. Cross-origin OPTIONS preflight returns 204 and allows If-None-Match.
• The catalog GET transferred 64,901 bytes with gzip in one warm request (0.109 s to first byte, 0.131 s total). These are one-request measurements, not cold-cache or parse-time results.
• Remaining defect: neither cross-origin GET response includes Access-Control-Expose-Headers. Browsers therefore cannot read ETag or Last-Modified across origins, despite the rule in apps/docs/vercel.json. The Done when criterion for exposed validators is not yet met. Verify the effective Vercel routing/header configuration, deploy the correction, and repeat the public checks.

This deployed finding is separate from PR #284's code and CI qualification.

[lloydrichards]

The first production fix merged in PR #286. Both public 200 JSON responses now include Access-Control-Expose-Headers: ETag, Last-Modified, and Chromium can read those validators across origins.

A browser check exposed another failure: Chromium's next cross-origin request with If-None-Match fails with TypeError: Failed to fetch. The corresponding production 304 response has an ETag but no Access-Control-Allow-Origin. Public curl checks alone did not catch this. PR #287 adds an edge response-header transform; verify its behavior in Chromium after deployment before closing this issue.

[lloydrichards]

Publication qualification is complete.

• PRs fix(docs): expose registry validators across origins #286 and fix(docs): allow conditional registry requests across origins #287 corrected public CORS behavior. Both JSON assets return 200 with exposed ETag and Last-Modified; a cross-origin Chromium request reads the ETag and its next If-None-Match request returns a usable 304. OPTIONS preflight succeeds, and an unknown registry path returns 404.
• PR docs(catalog): clarify HTTP server target description #288 made a compatible catalog content edit without a CLI release. Before deployment, the public server target description was “A backend application, such as an API server” with ETag "a318762eccd35ec6d7261ad39485de69". After production deployed merge e4597a35, it was “An Effect HTTP API server” with ETag "13bcfc16bace41e74ac9740159846345". A JSON comparison found only that description changed; published target and module IDs match.
• The docs build generated both assets from local definitions. Catalog-workspace validation and diff passed for the metadata edit, as did catalog, CLI, and docs tests. PR docs(catalog): clarify HTTP server target description #288's CI, generated-project E2E jobs, and Pullfrog review passed.
• Vercel deployment and rollback steps are recorded in apps/docs/REGISTRY-DEPLOYMENT.md. Parent feat: deliver and qualify the official HTTP catalog registry #275 has the request, parse, transfer-size, and bundle measurements.

The deployed endpoint criteria and independent content-update criterion in this issue are now met.