AGPL-3.0-or-later · forever.

{"id":"project/cwd-and-monorepos","slug":"cwd-and-monorepos","section":"project","label":"CWD and monorepos","summary":"Align project discovery and state roots.","status":"live","docsPath":"https://docs.nika.sh/sdk/project/cwd-and-monorepos","eyebrow":"project roots · live","title":"CWD is an operational decision.","description":"Align the process room, discovered project file, workflow paths and runtime state before a monorepo creates two invisible roots.","promise":"Project policy discovery walks upward. Direct-run trace storage does not. Set LocalNika cwd to the intended project root when one control plane and one evidence well are the goal.","facts":[{"label":"project lookup","value":"cwd → first ancestor"},{"label":"direct traces","value":"cwd/.nika/traces"},{"label":"arm state","value":"project/.nika/arm"},{"label":"armed run traces","value":"project/.nika/traces"}],"sections":[{"label":"01 · separate the roots","title":"Discovery and storage answer different questions.","body":"The engine can discover an ancestor nika.yaml while a direct run still writes its trace under the process working directory. The arm and serve paths deliberately enter the discovered project root before firing, so their ledger and triggered-run traces live together there.","ascii":"/repo/apps/api/                 LocalNika cwd\n├── .nika/traces/              direct-run receipts\n└── ↑ discover\n    /repo/nika.yaml             governing project\n    /repo/.nika/arm/            firing ledger\n    /repo/.nika/traces/         arm / serve run receipts"},{"label":"02 · align","title":"Use the project root as the process room.","body":"A root-aligned cwd gives relative workflow paths, project discovery, direct traces and armed state one explainable home. Resolve the absolute directory once at application startup.","code":"import { fileURLToPath } from 'node:url'\nimport { LocalNika } from '@supernovae-st/nika-client/local'\n\nconst projectRoot = fileURLToPath(new URL('../../', import.meta.url))\n\nexport const nika = new LocalNika({ cwd: projectRoot })\n\nawait nika.runToEnd('workflows/release.nika.yaml')","language":"typescript","filename":"src/runtime/nika.ts"},{"label":"03 · nest deliberately","title":"A nested nika.yaml is a real boundary.","body":"The first file found wins. Put a second nika.yaml under apps/api only when that service must have its own ceiling or project profile. Do not add one merely to shorten a path because it also changes which policy the engine applies.","ascii":"/repo/nika.yaml                  platform project\n└── apps/\n    ├── api/nika.yaml           API project boundary\n    │   └── workflows/\n    └── worker/                 inherits /repo/nika.yaml","note":"Review nested project files like package boundaries. A new file changes discovery for every process started below it."},{"label":"04 · inspect","title":"Probe from the same room as production.","body":"Run the report and trace listing with the exact working directory the service will use. A clean command from the repository root does not prove a nested deployment uses the same project or evidence store.","code":"cd /srv/nika/project\nnika arm\nnika trace ls\nnika serve --dry","language":"bash","filename":"terminal"}],"related":[{"label":"Project setup","to":"/sdk/start/project-setup"},{"label":"Project runtime state","to":"/sdk/project/runtime-state"},{"label":"LocalNika configuration","to":"/sdk/reference/configuration"},{"label":"Resident server","to":"/sdk/operations/resident-server"}]}

project roots · live

CWD is an operational decision.

Align the process room, discovered project file, workflow paths and runtime state before a monorepo creates two invisible roots.

Project policy discovery walks upward. Direct-run trace storage does not. Set LocalNika cwd to the intended project root when one control plane and one evidence well are the goal.

Discovery and storage answer different questions.

The engine can discover an ancestor nika.yaml while a direct run still writes its trace under the process working directory. The arm and serve paths deliberately enter the discovered project root before firing, so their ledger and triggered-run traces live together there.

/repo/apps/api/                 LocalNika cwd
├── .nika/traces/              direct-run receipts
└── ↑ discover
    /repo/nika.yaml             governing project
    /repo/.nika/arm/            firing ledger
    /repo/.nika/traces/         arm / serve run receipts

Use the project root as the process room.

A root-aligned cwd gives relative workflow paths, project discovery, direct traces and armed state one explainable home. Resolve the absolute directory once at application startup.

import { fileURLToPath } from 'node:url'
import { LocalNika } from '@supernovae-st/nika-client/local'

const projectRoot = fileURLToPath(new URL('../../', import.meta.url))

export const nika = new LocalNika({ cwd: projectRoot })

await nika.runToEnd('workflows/release.nika.yaml')

A nested nika.yaml is a real boundary.

The first file found wins. Put a second nika.yaml under apps/api only when that service must have its own ceiling or project profile. Do not add one merely to shorten a path because it also changes which policy the engine applies.

/repo/nika.yaml                  platform project
└── apps/
    ├── api/nika.yaml           API project boundary
    │   └── workflows/
    └── worker/                 inherits /repo/nika.yaml

Probe from the same room as production.

Run the report and trace listing with the exact working directory the service will use. A clean command from the repository root does not prove a nested deployment uses the same project or evidence store.

cd /srv/nika/project
nika arm
nika trace ls
nika serve --dry