Contributing
yidam is a template and a toolchain, not an application. The thing being maintained is the model a derived repository inherits, the CLI that keeps it honest, and the harness that proves a bootstrap still works. That shapes what a good change looks like here.
Get set up
git clone https://github.com/goedelsoup/yidam
cd yidam
mise install # provisions rust, python, uv, node
mise run yidam-build # installs the full-feature binary into .local/bin
mise tasks # everything available
mise manages both toolchains and tasks. Rust is pinned in mise.toml
and rust-toolchain.toml, which are kept in sync.
yidam-build is --features full deliberately: working on the CLI means being able to run
index-build, the semantic retrieval path, and the sqlite/rdf exports. That is why mise install provisions what it does, and why it is the maintainer's setup rather than the
one Installation describes.
It installs to .local/bin, which mise.toml puts first on PATH, so every task below runs
the binary built from this tree. That is per-repository on purpose — a per-machine install
location meant building here clobbered every derived repo's pinned binary, and building in one
of those clobbered this.
Before you push
mise run ci
fmt --check, clippy -D warnings, and tests across both workspaces — the harness and the CLI.
Check it by exit code, not by reading the output: a task that fails mid-pipeline still
prints a lot of green.
mise run ci is the wrong size between two edits, though: it formats, lints and tests both
workspaces. For the CLI suite alone, with an optional filter:
mise run test-cli # the whole CLI suite
mise run test-cli rename_ # only the tests whose name contains this
Anything after the task name reaches cargo nextest. The command itself is ci-cli's own,
held to it by a gate, so a filtered run is the gate on a subset.
CI runs ci-cli-cov, not ci-cli: the same steps, with the test run measured for coverage
instead of run twice. A gate holds the two equal, so mise run ci is still the gate you get.
Two things mise run ci does not cover, and both have bitten:
mise run docs-build # the docs site — an unlisted page fails the build
mise run ci-vscode # the extension
CI runs the harness and the light CLI build as parallel jobs on every PR, plus the extension,
the parity suite, an aarch64 cross-compile and the scaling bench. A pull request also compiles
the feature-gated code: ci (cli · feature check) runs the three clippy lines ci-cli-full
runs: over the default set without vector-read, over --all-features and over
--no-default-features --features reports. What it does not do is run their
tests, or pass --all-targets — a #[cfg(test)] fixture behind a feature is still first
compiled after the merge. The full-feature test run is on main and weekly, not on PRs.
So mise run check-features before you push a change behind a feature, vector-read included —
its #[cfg(not(...))] arms compile only there now — and prefer taking gated facts as arguments
so the logic around them stays testable from every build.
What a change needs
Every behaviour change needs a test. Prefer testing library functions directly; use the integration tests only for end-to-end CLI behaviour.
Prefer discovering a set over listing one. A hardcoded file list in a guard test stops covering new files without ever going red. Where a test asserts something about "all the X", find the X's rather than naming them.
Break a new guard on purpose before trusting it green. A file-scanning test that looks at nothing passes.
Run what you cite. An RFC or a doc page that quotes code accurately can still contradict it; if a page contains an example, run the example.
Commit messages
This repository is bound by the same commit vocabulary a derived corpus is — the distinction
between an epistemic commit (what is known changed; the message is testimony) and an
operational one (the pipeline advanced) is enforced by yidam lint --commits.
yidam vocabulary # the closed list, with reasoning
yidam vocabulary --check "fix(cli): …" # check a subject before the commit exists
yidam lint --commits --range main..HEAD
The subject line convention here is a conventional-commit prefix followed by a clause naming the
actual defect or change, not a summary of the diff. git log is the best guide.
Repository layout
| Path | What it is |
|---|---|
yidam/prelude/ | The inherited model — the only directory a derived repo vendors |
yidam/cli/ | The yidam binary |
yidam/editors/ | LSP notes and the VS Code extension |
yidam/tests/ | Bootstrap harness, scenarios, rubric, judge |
yidam/web/docs/ | This site |
sadhana/ | The scaffold copied into derived repos |
samudaya/ | The seed layer, consumed at genesis |
docs/ | Documentation for yidam itself — the source of this site |
examples/ | Worked corpora, gated by CI |
Three layers meet in a derived repo with three different lifetimes: yidam/ is vendored and
re-vendored, sadhana/ becomes the repo's own content at genesis, samudaya/ is consumed and
deleted. Changing one is not the same kind of act as changing another.
Where a change goes
Changing the model — the node model, the graph invariants, conduct norms — is a change to
yidam/prelude/, and every derived repository inherits it at its next re-vendor. That is the
highest-consequence directory in the repository.
Changing behaviour belongs in yidam/cli/, and the SDK boundary matters: the CLI consumes
the Rust prelude implementation as yidam-core rather than re-implementing the
parse-and-classify surface, so drift between the tool and the model becomes a test failure
instead of a mystery.
A default is a claim about every corpus at once. The recurring lesson here is that a number
compiled into the binary is one repository's judgement arriving as a build failure in another
that never agreed to it. Where a threshold is genuinely a corpus's own business, it belongs in
.yidam/config.toml with the argument for it, absent-means-off.
The SDKs and parity
yidam/sdks/ implements the prelude model three times — Rust (the reference),
TypeScript, and Python — held to the same TOML fixtures.
mise run parity # cross-language parity for the SDK functions
mise run domain-parity # the domain calculators in yidam/domains/
mise run embed-parity # embedding reproducibility across runtimes
mise run verify # Dafny specs and Lean 4 proofs (dafny + lake installed separately)
A change to one implementation that is not made in the others is a parity failure, which is the point.
The editor extension
mise run ext-dev # compile, stage a fixture, open an Extension Development Host
mise run ext-fixture # rebuild the staged fixture
mise run ext-package -- dist/yidam-vscode.vsix
F5 from the repository root runs the same two steps as its preLaunchTask. The workspace it
opens is a staged copy of the reports fixture — the extension activates on .yidam.toml or
.yidam/**, and this repository is not a derived repository, so launching against the repo root
would activate nothing.
Tests need no editor:
cd yidam/editors/vscode && npm run test:unit
Hold the line from RFC-0016: TypeScript computes affordances, the CLI computes verdicts. A TypeScript re-implementation of a check is the drift the whole RFC set exists to close.
Proposing a design
Substantial changes get an RFC in docs/rfcs/ before they become behaviour —
a proposal held open for review, written in the same register as the rest of docs/: precise,
evidenced, and honest about what is not yet settled.
The set has a through-line worth reading before adding to it: yidam's parity surface used to certify that three SDKs parse Markdown identically while the products a consumer actually depends on drifted freely. The RFCs move the contract boundary to where integration happens.
Documentation
This site is built from docs/ at the repository root by an Astro/Starlight project in
yidam/web/docs/.
mise run docs-dev # http://localhost:4321/yidam/
mise run docs-build # what CI runs
A new page needs a sidebar entry in yidam/web/docs/astro.config.mjs or the build fails.
That is deliberate and runs in both directions: Starlight would otherwise render a page nobody
can reach, and a sidebar entry naming a page that no longer exists is a dead link. The check
names the file and tells you which side is wrong.
docs/README.md is deliberately not published — the sidebar is the site's contents table, and
publishing the file would ship a second copy that goes stale the first time the two disagree.
Reporting a problem
Issues. For anything about a specific repository's
behaviour, yidam doctor and yidam --version between them answer most of the first round of
questions — see Troubleshooting.