PROJECT TREE · CONTROL PLANE + INTENT + PROOF
{`project/
├── nika.yaml # project profile + optional armed beats
├── workflows/
│ ├── daily-brief.nika.yaml # workflow intent
│ └── release.nika.yaml
├── src/
│ ├── nika.ts # LocalNika construction
│ └── release.ts # product code
├── .nika/
│ ├── traces/ # run journals
│ └── arm/ # firing ledgers + watermarks
├── package.json
└── .gitignore`}
* `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
```sh theme={"system"}
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 both released readers accept:
```yaml theme={"system"}
nika: v1
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](/sdk/project/nika-yaml)
and [arm registry](/sdk/project/arm-registry) pages show valid copy-paste forms
for each lane.
## Create one client
```ts theme={"system"}
// src/nika.ts
import { LocalNika } from '@supernovae-st/nika-client/local'
export const nika = new LocalNika({
bin: process.env.APP_NIKA_BIN,
cwd: new URL('..', import.meta.url).pathname,
})
```
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
```ts theme={"system"}
try {
console.info('nika engine', await nika.version())
} catch (error) {
console.error('cannot start workflow runtime', error)
process.exit(3)
}
```
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
```text .gitignore theme={"system"}
.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