Machine surfaces

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

Surface	Envelope	What it carries
`nika check <file> --json`	`report_version`	the full audit report: conformance findings (each with `code` · `severity` · `docs_url` · span), cost intervals per task, the derivation certificate, requirements (models · secrets · env), secret-flow findings, hints, pricing provenance (`pricing.snapshot`)
`nika doctor --json`	— (stable shape)	the environment diagnosis: per-finding status + the exact fix command, key PRESENCE (never values), local provider reachability
`nika catalog --json`	`catalog_version`	the provider/model vocabulary: models, capabilities, key env-var NAMES
`nika catalog --tools --json`	`tools_version`	the builtin tool catalog with model-facing JSON Schemas per tool
`nika inspect <file> --format json`	`graph_format` (`3`)	the ONE graph projection: nodes (id · `kind`: `task` · `finally` · verb · model/tool · when · fan-out · permits · cost interval) + typed edges (`kind`: `value` · `terminal-observation` · `failure-observation` · `control` + `predicate` · `recovery` · `finally` with `predicate: unwind` — `binding` on data edges) — mermaid and dot are derived from this, never parallel truths. Formats 1 and 2 are dead: a reader refuses a format it does not speak; a pinned golden is regenerated from the binary, never hand-edited; within format 3, evolution is additive-only
`nika run <file> --json`	NDJSON stream	the live event stream, one JSON object per line — the same events the trace records · the last line is `run_settled` with `status` ∈ `succeeded` · `failed` · `paused` · `cancelled` (0.118), the `error` cause on a failed run, `evidence` ∈ `sealed` · `unsealed` · `lost` · `none` (what the run left behind, said, never implied by an absent receipt) and the lanes that served
`nika trace ls --json`	— (stable shape)	the run inventory: every recorded trace with its state (`succeeded` · `failed` · `paused` · `cancelled` · `running` · `dead`) and its writer’s `liveness` (`alive` · `dead` · `unknown` — the lease beside the journal, never a guess), age, size, resume marker (0.118)
`nika trace outputs --json`	— (stable shape)	one run’s task projection: `state` and per task `status` · `error_code` · `recovered_from` · `integrity_source` (the upstream whose recovered fallback fed it) · a fan-out’s `items` rows (0.118)
`nika trace export`	OTLP	any recorded journal projected to OpenTelemetry (Jaeger · Grafana · Langfuse)
`nika spec --canon`	`schema_version`	the embedded canon SSOT (counts and names — cite it, never a remembered number)
`nika spec --schema`	JSON Schema `$id`	the embedded workflow schema — the same one editors validate against
`nika spec --schema --project`	JSON Schema `$id`	the project file’s schema (`nika.yaml` · `ceiling` · `traces` · `arm:` beats) — emitted from the parser, proven against its closed key sets (0.118)

nika check - reads the workflow from stdin — editors and agents audit keystroke-fresh buffers without touching the disk.

Prefer typed TypeScript over process glue? The published Nika client (@supernovae-st/nika@0.120.2) owns binary discovery, JSON decoding, cancellation, run.events() and typed errors. run() returns an admitted handle; run.result() settles. traceVerify reads existing evidence — it does not seal, rerun, or prove the job was correct. The SDK runtime guide maps these wires to code.

Canonical sources

The public documentation explains the contract. Machine consumers read the versioned CLI output or the owning repository, rather than a marketing build.

Surface	Owner and access
Workflow schema	`nika spec --schema` or spec schema
Diagnostics	`nika explain` or diagnostic registry
Tools and models	`nika catalog --tools --json` and `nika catalog --json`
Documentation for agents	Documentation index
Shared artifacts	Registry index

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:

Code	Meaning
`0`	success — clean check · completed run
`1`	the workflow ran and failed (a task settled failed)
`2`	findings / usage / refusal — check findings, bad flags, the `--max-cost-usd` floor refusal
`3`	environment — missing file, no golden to compare, binary-level trouble
`4`	paused — the run parked on a blocking `nika:prompt` (durable pause · ADR-099) · not a failure but non-zero on purpose · resume with `nika run --resume <trace> --answer <task>=<value>`
`130`	the runtime settled as cancelled after an operator request (0.118) — completed in-flight work is counted and unstarted tasks are cancelled; read the reported evidence state to determine whether a trace was sealed · a second Ctrl-C aborts mid-flight and can leave the trace incomplete · 128 + SIGINT, the code every shell already reads as interrupted

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 (stdio, read-only): 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). Same owning builders as the CLI payloads — the two lanes cannot drift apart by construction.

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.

nika welcome --deep --json ships on the released 0.120.1 binary — the whole workspace truth in one call (file map with per-file verdicts · run inventory · environment snapshot · wiring state). Caps are always reported; paths stay relative.

YAML

Language fields

CLI & errors

Data catalogs

Workspace

Documentation system

Tool contracts

Machine surfaces

The wires

Canonical sources

The exit-code contract

The MCP oracle

The evolution rules

​The wires

​Canonical sources

​The exit-code contract

​The MCP oracle

​The evolution rules

The wires

Canonical sources

The exit-code contract

The MCP oracle

The evolution rules