Skip to content
Lemma Lemma

Authoring a card

The corpus grows by contribution. Cards live in cards/<domain>/<sub-domain>/<id>.json, and the domain field is the folder path joined with a hyphen — cards/physics/condensed-matter/ means "domain": "physics-condensed-matter". The two must agree. (cards/ops/ and cards/hypotheses/ are flat and carry no domain.)

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": "wien-displacement-law",
  "version": "1.0.0",
  "name": "Wien displacement law",
  "domain": "physics-statistical-mechanics",
  "principles": ["black-body radiation", "thermal equilibrium"],
  "formulaTeX": "\\lambda_{\\max} T = b",
  "conventions": ["lambda_max in metres", "T in kelvin"],
  "expectedLimits": [
    "T -> infinity => lambda_max -> 0 (peak shifts to shorter wavelengths)",
    "monotonic decreasing in T"
  ],
  "references": ["Reif, Statistical and Thermal Physics, §9"],
  "validationEnvelopes": { "b_m_K": [2.897e-3, 2.898e-3] }
}

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>/<sub-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.