Project setup

The SDK should make the project boundary visible, not dissolve it into application objects. The root nika.yaml is the control plane — optional for a first workflow, required once the project arms beats or sets policy. Each *.nika file is executable workflow intent.

Recommended layout

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

nika init --project-file --recipe starter
nika arm

--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 the released reader accepts — the same identity nika init --project-file writes:

nika: my-project

ceiling: 0.50

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

// src/nika.ts
import { fileURLToPath } from 'node:url'
import { Nika } from '@supernovae-st/nika'

export const nika = new Nika({
  bin: process.env.APP_NIKA_BIN,
  cwd: fileURLToPath(new URL('..', import.meta.url)),
})

fileURLToPath decodes percent-escapes and survives spaces in the path — new URL(...).pathname does neither. Binary resolution follows one ladder:

bin passed to the constructor
NIKA_BIN
exact optional platform package

Use an explicit application variable for packaged services. Implicit PATH lookup is refused. cwd anchors relative workflow paths, project-file discovery and the .nika/ state directory.

Probe at startup

try {
  const report = await nika.check('workflows/daily-brief.nika', {
    nativeStrict: true,
  })
  if (!report.clean) {
    console.error('workflow refused at admission', report.findings)
    process.exit(2)
  }
  console.info('nika engine ready')
} catch (error) {
  console.error('cannot start workflow runtime', error)
  process.exit(3)
}

A missing binary is an environment failure (the promise rejects). A dirty workflow is different: check() resolves to a report so the caller can show every finding — branch on report.clean, never log readiness while it is false.

Keep receipts governed

.gitignore

.nika/traces/
.nika/arm/
.env

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.

Local 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.

Overview

Start

Project

Local API

Runtime

Remote API

Operations

Reference

Project setup

Recommended layout

Found the project

Create one client

Probe at startup

Keep receipts governed

Connect the next systems

Security boundary

Local client

Workflow concepts

Traces

Resident server

Runtime state

​Recommended layout

​Found the project

​Create one client

​Probe at startup

​Keep receipts governed

​Connect the next systems

Security boundary

Local client

Workflow concepts

Traces

Resident server

Runtime state

Recommended layout

Found the project

Create one client

Probe at startup

Keep receipts governed

Connect the next systems