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..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 ascwd.
PROJECT STATE · TWO JOURNALS, TWO QUESTIONS
Verify a run trace through the SDK
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.
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
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.