Skip to main content
Live project control plane. The released engine discovers nika.yaml from the working directory toward its ancestors. The file is optional when built-in defaults are enough. Its project-shape grammar is closed: nika · ceiling · arm · traces · registry. Direct runs and the cadence path (nika arm · nika serve) read the same file.
Source describes intent. .nika/ records what the machine did. A production deployment should choose storage and retention for that distinction before it runs its first armed beat.

State map

The unified tree below assumes the recommended setup: direct processes use the project root as cwd.
PROJECT STATE · TWO JOURNALS, TWO QUESTIONS

Verify a run trace through the SDK

The SDK returns the engine-issued receipt to the engine for verification. It does not accept a trace path or inspect the journal in TypeScript. nika arm reads the arming sidecar. They are related evidence, but they are not interchangeable.

Persist the clock on servers

A resident server or OS unit needs a durable project state path. If a container discards .nika/ on restart, it also discards recent traces and the watermark used to reason about missed slots.
The firing contract is at-least-once. A crash after a durable claim and before its receipt leaves an unmatched claim in history.ndjson. Keep external effects idempotent when a repeated fire must be harmless.

Source-control boundary

.gitignore
.nika/ also holds nika serve job state (.nika/serve/) and, when you serve over HTTP, the bearer token (.nika/serve.token): never commit it. Ignoring live state does not mean deleting it on deployment. Mount, back up or export it according to the workload’s evidence and retention policy.

Evidence lifecycle

Export evidence deliberately. Do not turn the entire state directory into a public application artifact.

Continue

Receipts and replay

Verify and replay the workflow journal.

Resident server

Operate the process that writes arming state.

Arm registry

Understand what the ledger is proving.

CWD and monorepos

See exactly which root owns each state lane.

Trace concepts

The durable run journal and its integrity chain.