Skip to content
Lemma Lemma

Authoring a card

The corpus grows by contribution. Cards live in cards/<domain>/<id>.json — the domain field and the folder path must agree.

1. Pick a principle

Choose a principle with a clear formula and well-defined limits — a plasma frequency, a conservation law, a numerical-method stability bound. Start narrow.

2. Write the card

Copy an existing card in the closest domain as a template and follow schema/card.v0.1.json. A principle card requires kind, id, version, name, principles, formulaTeX, conventions, expectedLimits, and references.

{
  "kind": "principle",
  "id": "stefan-boltzmann",
  "version": "1.0.0",
  "name": "Stefan–Boltzmann law",
  "domain": "physics-thermodynamics",
  "principles": ["black-body radiation", "thermal equilibrium"],
  "formulaTeX": "j = \\sigma T^4",
  "conventions": ["j >= 0", "T in kelvin"],
  "expectedLimits": ["T -> 0 => j -> 0", "monotonic increasing in T"],
  "references": ["Reif, Statistical and Thermal Physics, §9"],
  "validationEnvelopes": { "sigma_W_per_m2K4": [5.669e-8, 5.671e-8] }
}

validationEnvelopes is optional but valuable — it’s the { key: [min, max] } numerical bounds the engine asserts at runtime.

3. Validate locally

The corpus is checked against the schema with ajv-cli — the same command CI runs on every PR:

Terminal window
npx ajv-cli@5 validate --spec=draft2020 -s schema/card.v0.1.json -d "cards/**/*.json"

4. Open a PR

Add the card under cards/<domain>/ and open a pull request against github.com/artano-ai/lemma. The corpus is CC-BY 4.0 — your name stays on the card.

What won’t be merged

  • Dimensionally inconsistent formulae.
  • references that are blog posts or non-attributable sources.
  • Cards that duplicate an existing one without explaining why.