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.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.yamlgoverns project-wide spend and the released reader profile this project uses.workflows/is reviewed as intent.src/nika.tsowns binary resolution and the working directory, not a second copy of project policy..nika/is runtime state: run records, firing ledgers, server job state and, when you serve over HTTP, the server’s bearer token. Ignore it in source control and mount it deliberately on a server.
Found the project
A project file is one line: the project’s kebab-case name. Create it and let the engine read it back:nika arm reads and validates the project file and its cadences, reports
what is armed, and schedules nothing. Add policy as you need it, for example a
default spending ceiling for every run of the project:
nika.yaml
nika init does much more than create nika.yaml: it writes about 30
agent, editor and hook files and a starter workflow
(the full list). Run it
only when you want that scaffold.arm: when time or an event should start a workflow, and traces: or
registry: for run policy: one file carries both. The
project file and arm registry
pages show copy-paste forms.
Create one client
fileURLToPath decodes percent-escapes and survives spaces in the path —
new URL(...).pathname does neither.
Binary resolution follows one ladder:
binpassed to the constructorNIKA_BIN- exact optional platform package
bin and
NIKA_BIN must be absolute paths: a bare name or a relative path throws
NikaConfigurationError, and a nika on your PATH is never used. cwd
anchors relative workflow paths, project-file discovery and the .nika/
state directory.
Probe at startup
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/ is machine state:
If a deployment retains this state, 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.