The law: every human-facing surface has a --json twin, every
machine payload carries a version envelope, and evolution is
additive-only — a field is added, never renamed or removed within
a version. Agents and tooling parse the JSON; the pretty output is
free to improve without breaking anyone.
The wires
nika check - reads the workflow from stdin — editors and agents
audit keystroke-fresh buffers without touching the disk.
Canonical sources
The public documentation explains the contract. Machine consumers read the versioned CLI output or the owning repository, rather than a marketing build.
For a reproducible integration, replace
main with a reviewed commit and record
its content digest. The knowledge system explains
how to read source revisions and distinguish a contract from a released implementation. Historical schema identifiers are stable
identities; retiring a website does not rename a language namespace.
The exit-code contract
Scripts and agents branch on exit codes, so they are the engine CLI exit-code contract (locked · additive-only), not an accident:
Stream discipline: product output goes to stdout, only
environmental noise goes to stderr — and in
--json modes, progress
moves to stderr so stdout stays parseable.
The MCP oracle
nika mcp serves the same truths over the Model Context Protocol, read-only,
over stdio by default or Streamable HTTP with --transport http: validate
(nika_check: a dirty workflow returns isError: true, mirroring the CLI’s
exit 2) and learn (nika_schema · nika_examples · nika_template ·
nika_canon · nika_catalog · nika_tools · nika_explain ·
nika_inspect). The same builders produce the CLI payloads, so the two
cannot drift apart. MCP server describes each tool.
The evolution rules
- Versioned: breaking a payload shape means bumping its envelope field — consumers pin on it.
- Additive-only within a version: new fields appear, existing ones keep their meaning.
- Deterministic: stable key ordering, no timestamps injected into otherwise-stable payloads — machine output is cache- and diff-friendly.
- Presence, never values: no secret VALUE crosses any wire, human or machine. Requirements name the env var; doctor reports set/unset.
Every row above was read from
nika {STATUS.version}. An envelope you do
not recognize is a newer payload: refuse it rather than guess.