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
`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 check - reads the workflow from stdin — editors and agents audit keystroke-fresh buffers without touching the disk.

Prefer typed TypeScript over process glue? The released LocalNika client owns binary discovery, JSON decoding, cancellation, run events and typed errors. The SDK runtime guide maps these wires to code.

The hosted twins

The same law reaches the web: the machine surfaces an agent can fetch without a binary, each probed and versioned like the CLI wires.

URL	What it carries
`nika.sh/spec/v1/workflow.schema.json`	the published workflow JSON Schema — the same one `nika spec --schema` embeds
`nika.sh/errors/catalog.json`	the error catalog, projected from the spec’s normative table
`nika.sh/brand/icons.json`	the design ontology: every verb, builtin, feature and run-state with glyph, hue and motion
`nika.sh/brand/icons.ttl`	the same graph in Turtle — SPARQL-ready, namespace `nkd:`
`nika.sh/llms.txt`	the agent-readable site summary (llmstxt.org shape)
registry `index.json`	every shared artifact with its pin, digest, cert summary and advisory state — resolve names here before installing anything an LLM suggests

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>`

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.

Next on this page once the next engine tag ships: nika welcome --deep --json (context_version) — the whole workspace truth in one call (file map with per-file verdicts · run inventory with actual cost · environment snapshot · wiring state · caps always reported, relative paths only). It is merged on main today and rides the next release.

YAML

CLI & errors

Data catalogs

Workspace

Machine surfaces

The wires

The hosted twins

The exit-code contract

The MCP oracle

The evolution rules

​The wires

​The hosted twins

​The exit-code contract

​The MCP oracle

​The evolution rules

The wires

The hosted twins

The exit-code contract

The MCP oracle

The evolution rules