Skip to main content
The SDK should make the project boundary visible, not dissolve it into application objects. The root nika.yaml is the control plane. Each *.nika.yaml file is executable workflow intent.
PROJECT TREE · CONTROL PLANE + INTENT + PROOF
  • nika.yaml governs project-wide spend and the released reader profile this project uses.
  • workflows/ is reviewed as intent.
  • src/nika.ts owns binary resolution and the working directory, not a second copy of project policy.
  • .nika/ is runtime state. Ignore it in source control and mount it deliberately on a server.

​
Found the project

--project-file is the scripted door to the starter. It skips an existing file unless --force is explicit. Bare nika arm reads and validates the project and cadence grammar, reports what is armed, and schedules nothing. The starter is optional and comments every governing example. Start with the common rung that both released readers accept:
Add arm: when time or an event should start a workflow. Add traces: or registry: for direct-run policy. The current cadence path does not compose those two profiles yet, so the dedicated project file and arm registry pages show valid copy-paste forms for each lane.

​
Create one client

Binary resolution follows one ladder:
  1. bin passed to the constructor
  2. NIKA_BIN
  3. nika on PATH
Use an explicit application variable for packaged services. Keep PATH convenient for local development. cwd anchors relative workflow paths, project-file discovery and the .nika/ state directory.

​
Probe at startup

A missing binary is an environment failure. A dirty workflow is different: check() resolves to a report so the caller can show every finding.

​
Keep receipts governed

.gitignore
Traces may carry run metadata and outputs. Arm state carries firing claims, receipts and cadence watermarks. If a deployment retains them, choose the volume, retention window and access policy explicitly.

​
Connect the next systems

Security boundary

Keep permits, secrets, argv and spend ceilings explicit.

LocalNika client

Read every local method and its machine twin.

Workflow concepts

The file remains the language contract.

Traces

Understand the durable journal under the SDK receipt.

Resident server

Keep armed beats running on a container, VM or bare server.

Runtime state

Persist traces and arming ledgers without committing them.