#Vivarium recipes index (v1)

Machine-generated catalogue index of every reproduction this repository hosts. Consumed by the Vivarium MCP server and any other programmatic tool that wants to list, filter, or look up recipes.

#At a glance

URL: https://aletheia-works.github.io/vivarium/api/recipes.json

{
  "index": "v1",
  "contract": "v1",
  "recipes": [
    {
      "slug": "pandas-56679",
      "layer": 1,
      "project": "pandas",
      "issue": 56679,
      "title": "pandas-dev/pandas#56679",
      "page_url": "https://aletheia-works.github.io/vivarium/repro/pandas/56679/",
      "source_url": "https://github.com/aletheia-works/vivarium/tree/main/src/layer1_wasm/pandas-56679"
    },
    {
      "slug": "bash-local-shadows-exit",
      "layer": 2,
      "project": "bash",
      "issue": 0,
      "title": "bash `local` shadows command-substitution exit code",
      "page_url": "https://aletheia-works.github.io/vivarium/repro/bash/local-shadows-exit/",
      "verdict_url": "https://aletheia-works.github.io/vivarium/repro/bash/local-shadows-exit/verdict.json",
      "source_url": "https://github.com/aletheia-works/vivarium/tree/main/src/layer2_docker/bash-local-shadows-exit"
    }
  ]
}

#Top-level fields

#Recipe entry fields

#Versioning

The version is carried as index = "v1" on the top-level object.

• Optional additive fields ship as same-v1 revisions; consumers feature-detect them.
• Breaking changes (renamed fields, type changes, optional → required) require a v2 schema sibling.

There is no current v2.

#Revision history

#Generation

The index is built by docs/scripts/generate-recipes-index.ts, wired into the rspress dev and build scripts in docs/package.json. The script walks the recipe directories, parses each recipe README's first H1 for the title, and derives project / issue from the slug pattern (<project>-<digits> for slugs with a trailing issue number; first dash-segment otherwise, with a small override map for recipes whose slug shape diverges).

The output is tracked in git so PRs that add a recipe also show the index update in the diff. The optional facet fields (language, symptom, severity, tags) are merged in from docs/data/recipe-facets.json, a centralised overlay maintained by hand and reviewed in PR diff. The project field stays slug-derived in v1.

#Conformance

A recipes.json document conforms to v1 when:

1. It validates against recipes.schema.json.
2. index === "v1" and contract === "v1".
3. Every entry's slug matches ^[a-z0-9]+(-[a-z0-9]+)*$.
4. Every Layer 2 / 3 entry includes verdict_url; Layer 1 entries omit it.

Clauses 1–3 are mechanically enforceable via schema validation. Clause 4 is a derivation-rule constraint not encoded in the schema's oneOf (kept deliberately permissive: the MCP server treats a missing verdict_url on a Layer 2 / 3 entry the same as verdict_url pointing at a 404 — both are surfaced to the consumer as "no snapshot available").

#See also

• Contract v1 — the runtime verdict surface each recipe page publishes.
• Manifest v1 — the upstream-side manifest format an external repo ships at .vivarium/manifest.toml. Recipe entries in this index correspond to internal recipes; external repos publish their own per-repo manifest instead of being listed here.