# nika.sh · llms.txt
# https://llmstxt.org/

> Nika is the checked workflow language for AI: an agent writes its plan as a
> readable file (steps, tools, permissions, outputs), nika check reads it back
> before a token is spent, the runtime enforces it, then it runs (traced and
> replayable). An open workflow language plus its reference engine in Rust.
> Apache-2.0 spec · AGPL-3.0-or-later engine. Paris. SuperNovae Studio.

## What

Nika reads `.nika.yaml` files and executes them as AI workflows.
Four verbs, locked forever: `infer` (LLM call), `exec` (subprocess),
`invoke` (builtin/tool; HTTP fetch is the `nika:fetch` builtin here),
`agent` (agent loop). Everything callable is a tool under `invoke`;
a verb is a distinct native execution model.

The envelope has nine top-level keys: `nika:` (the mark AND the file's
name, kebab-case · never a version marker) · model · inputs · const ·
secrets · permits · run · tasks · outputs. Values come from three
authorities: inputs (caller-supplied, with defaults), const (baked in),
secrets (vault-backed references). A file names no version; the binary
that runs it is the version. The engine versions on real semver toward
a 1.0 launch; currently v0.111.0.

Stdlib v0.1: 28 builtins · 17 providers (Ollama, LM Studio, llama.cpp,
LocalAI, vLLM, Mistral, Hugging Face, OpenAI, xAI, Anthropic, Gemini,
Groq, DeepSeek, OpenRouter, NVIDIA, Moonshot, mock) · 9 extract modes.
Bring your own keys. Every key stays yours. Local-first. Runs on your
laptop, no daemon.

## The contract

Every workflow declares its blast radius. The permits: block is a
default-deny allowlist by family: fs (read/write globs), net.http
(hosts), exec (argv-sound programs), tools. A step that reaches outside
it is refused before anything runs (NIKA-SEC-004); link-local and
metadata endpoints stay refused regardless (NIKA-SEC-005, the always-on
floor); secrets stay masked references with scoped egress. Every run
leaves a hash-chained NDJSON trace: `nika trace verify` walks the chain
and names the first broken link. `nika check` prices the plan's cost
floor before a token is spent; `--max-cost-usd` is a hard ceiling.
`nika check --infer-permits` writes the tightest boundary a file can
prove.

The boundary's laws were proposed as numbered public documents
(NEP-0002..0009: the lethal-trifecta human gate · absent permits declare
zero authority · untrusted values re-gate at the effect · the environment
permit · the data-as-code sink · the trace witness and differential oracle
· the egress proxy as the permit's exact projection · path grants
re-judged at dispatch) and folded into the specification chapters on
2026-08-13; the fold table names where each law lives now:
https://github.com/supernovae-st/nika-spec/tree/main/governance
Provenance: the public repos ship estate manifests (estate.yaml): every
tracked file declared authored or generated, hashed, checkable.

## Examples (canonical · conformance-gated)

Every spec version ships a versioned examples pack: foundation
workflows teaching the constructs plus tiered showcase real jobs
(T1 starter → T4 epic), each a complete validated file. The manifest
(pack_version · constructs · sha256 per file) makes the pack
verifiable end-to-end; docs and site render projections of the same
files.
Every served library file (e.g. https://nika.sh/library/daily-brief.nika.yaml) carries its SPDX line (Apache-2.0).

- Templates (instantiate, never invent: SLOT-marked skeletons): https://nika.sh/workflows/skeletons · machine catalog: https://nika.sh/templates/catalog.json · source: https://github.com/supernovae-st/nika-spec/tree/main/templates
- Agent authoring protocol: https://docs.nika.sh/guides/agent-authoring
- Pack manifest: https://github.com/supernovae-st/nika-spec/blob/main/examples/manifest.yaml
- Showcase source: https://github.com/supernovae-st/nika-spec/tree/main/examples/showcase
- Walkthroughs: https://docs.nika.sh/examples/overview
- Interactive explorer: https://nika.sh/#use-cases
- Blog (markdown source: content/blog in the site repo): https://nika.sh/blog · feed https://nika.sh/rss.xml · full text https://nika.sh/llms-full.txt · every post serves its markdown twin beside the page (append .md, e.g. https://nika.sh/blog/intent-as-code.md) · one citable register per tag (e.g. https://nika.sh/blog/tags/engine)

## Design system (machine-readable)

Every Nika verb, builtin, feature and run-state has a canonical icon,
color role and motion pattern, declared once in an ontology and served
as data. Verb hues (infer blue · exec orange · invoke cyan · agent
violet) appear ONLY on live-run surfaces; static UI keeps the text ink.

- Icon ontology (JSON · 79 entities · labels, semantics, hue tokens, links): https://nika.sh/brand/icons.json
- RDF projection (Turtle · SPARQL-ready · namespace https://nika.sh/ontology/design#): https://nika.sh/brand/icons.ttl
- Served icon catalog: https://nika.sh/brand/icons/<namespace>-<name>.svg (e.g. verb-infer, builtin-fetch, state-recovered)
- Brand kit + usage rules: https://nika.sh/brand · https://github.com/supernovae-st/nika.sh/blob/main/BRAND.md

## How to write Nika (the 12 patterns)

Deterministic core, model at the edges · parallelism is the default ·
type the boundaries · fan out with a leash · plan-then-execute · three
gates (when=skip, assert=fail, prompt=human) · sovereignty is a model:
line · agents get budgets · evidence always lands (a cleanup task on an
`unwind` edge) · one
data language (jq) · workflows are callable · mock-first.

- Patterns guide: https://docs.nika.sh/guides/patterns

## Links

- How the standard CHANGES (nobody amends it directly, the maintainers included): https://nika.sh/language/governance · the process is NEP-0000 (https://nika.sh/language/governance/nep-0000-the-nep-process); the numbered proposals folded INTO the language on 2026-08-13 (eighteen became chapters, two were buried) and their numbers stay doorways onto the chapter each law lives in · propose one: https://github.com/supernovae-st/nika-spec/tree/main/governance
- Language spec (Apache-2.0): https://github.com/supernovae-st/nika-spec · read it on the site, chapter by chapter, at the pin it was read at: https://nika.sh/language/spec (e.g. https://nika.sh/language/spec/verbs · /envelope · /dag · /variables · /errors · /conformance · /trace · each chapter whole, with its own sha256)
- Standard library register (every nika: builtin: args, required set, category): https://nika.sh/language/stdlib · one room per builtin (e.g. https://nika.sh/language/stdlib/fetch: the arg contract, the tool inside a real check-green file, the skeletons that ship it) · machine catalog: https://nika.sh/tools/catalog.json
- The four verbs (one room each: block contract, a complete file, the skeletons that speak it): https://nika.sh/language/verbs (e.g. https://nika.sh/language/verbs/invoke)
- The language register (every schema-declared key: scopes, types, required flags): https://nika.sh/language (e.g. https://nika.sh/language/words/with) · the contract: https://nika.sh/schema/workflow.json
- The truth system (how the site tells the truth: the pinned clocks, the truth words, the coverage score with its gaps named, the verify-yourself protocol): https://nika.sh/truth
- Error register (every NIKA-* code: category, transient flag, failure line): https://nika.sh/language/errors · one room per code (e.g. https://nika.sh/language/errors/NIKA-PARSE-001) · machine catalog: https://nika.sh/errors/catalog.json
- Provider register (local first, model pins, env vars): https://nika.sh/catalog/providers · one room per provider (angle, models, key ritual, an audited real file · e.g. https://nika.sh/catalog/providers/ollama) · the SPEC names 17 and the released catalog reaches 38: every one has a room, the other 21 carrying what the binary knows (wire dialect, key requirement, the seats a workflow can point at · e.g. https://nika.sh/catalog/providers/ai21) · machine catalog: https://nika.sh/providers/catalog.json
- Engine source (AGPL): https://github.com/supernovae-st/nika
- Why the engine is built this way (71 architecture decisions, read at the release pin): https://nika.sh/city/decisions · every decision with its status, the layers it binds and the decisions that cite it · the 59 settled ones open whole (e.g. https://nika.sh/city/decisions/adr-001) and the 12 still proposed keep their row · machine surfaces: https://nika.sh/engine/adr/index.json (every cross-reference edge) and https://nika.sh/engine/adr/bodies.json (the settled decisions, lexed)
- Where every piece lives (which repo ships what, and at which pin this site read it): https://nika.sh/city · two clocks govern the ecosystem, the spec pin for the language and the engine pin for what the released binary knows
- Agent lane (the MCP oracle · 9 read-only tools: nika_check · nika_explain · nika_schema · nika_examples · nika_template · nika_canon · nika_catalog · nika_tools · nika_inspect): https://github.com/supernovae-st/nika-plugins
- Editor lane (VS Code · Cursor · Windsurf: syntax, diagnostics, DAG view; files validate against https://nika.sh/spec/v1/workflow.schema.json via the yaml-language-server line): https://github.com/supernovae-st/nika-vscode
- Install: https://nika.sh/#install (or `brew install supernovae-st/tap/nika`)
- Docs: https://docs.nika.sh
- Registry (share workflows · every entry machine-re-proven: pinned sha256 + conformance oracle + engine cert before run): https://github.com/supernovae-st/nika-registry · machine index: https://raw.githubusercontent.com/supernovae-st/nika-registry/main/index.json · never install an LLM-suggested name without resolving it there first
- Releases (every published version: its assets and the sha256 digests recorded at upload · one room per version): https://nika.sh/releases · machine record: https://nika.sh/releases/catalog.json · the notes live at GitHub, one voice: https://github.com/supernovae-st/nika/releases
- The changelog (the exhaustive ship log: every release and public milestone, dated · the timeline below is its provenance record): https://nika.sh/changelog
- The map (every page, one graph): https://nika.sh/map · crawler twin: https://nika.sh/sitemap.xml · lens twin: https://nika.sh/ontology/language.json
- The anatomy hubs (one page per language layer; every member owns a room of its own, linked from its hub): https://nika.sh/how/flow (edges · gates) · https://nika.sh/how/boundary (permits · secrets) · https://nika.sh/how/proof (conformance · trace · machine surfaces)
- The register roots (every roomed family owns its root page listing its rooms, each member glossed): https://nika.sh/language/types · /language/namespaces · /language/edges · /language/predicates · /language/families · /language/modes · /language/permits · /language/secrets · /language/conformance · /language/error-namespaces · /language/error-categories · /how/oracle · /truth
- The timeline (the one verifiable record: eras · releases · forward gates · every provable claim re-proven in CI): https://nika.sh/timeline
- Integrations (get Nika into your stack · one room per client lane and per public repo, install commands verbatim from the READMEs): https://nika.sh/integrations · Claude Code: https://nika.sh/integrations/claude-code · Codex: https://nika.sh/integrations/codex · Cursor: https://nika.sh/integrations/cursor · VS Code: https://nika.sh/integrations/vscode · Hermes/skills.sh: https://nika.sh/integrations/hermes · the MCP server: https://nika.sh/integrations/mcp · the coverage matrix names all 31 clients the binary reaches and every one has a room saying what the RELEASED binary proves about it (status, class, the install line verbatim, what lands, what does not): e.g. https://nika.sh/integrations/opencode · /copilot-cli · /grok-build · /kimi-code · /zed · /goose
- Showcase rooms (one URL per conformance-gated real workflow, whole file + plan facts): https://nika.sh/workflows/jobs (the gallery lists all rooms; each room lives at its own slug under that path)
- The teaching path (13 numbered files, in order · each adds exactly ONE idea to the one before it; running them in order is how the language teaches itself): https://nika.sh/workflows · one room per step, whole file at the spec pin with its own sha256 (e.g. https://nika.sh/workflows/path/01-hello · /02-parallel-fanout · /12-failure-routing) · the corpus world holds all three shelves: the path, the jobs, the skeletons
- The catalog (what the RELEASED binary knows · vendored at the engine release pin, digest-verified · engine-release clock): https://nika.sh/catalog · models (one room each: serving seats, exact prices, measured energy): https://nika.sh/catalog/models · pricing (the rule table the audit reads · a local model is unpriced, never free): https://nika.sh/catalog/pricing · energy (measured Wh/Mtok with sources verbatim): https://nika.sh/catalog/energy · MCP servers (one room each: packages, env vars, the permit line): https://nika.sh/catalog/mcp · embeddings: https://nika.sh/catalog/embeddings · capability rules: https://nika.sh/catalog/capabilities · machine twin (the whole site as evidence-bearing JSON-LD triples): https://nika.sh/nika-graph.json

## Status

Shipping in the open (v0.111.0, real semver toward 1.0). The engine is admitted crate by crate (the repo README carries the live count). Each passes
a 12-gate admission (TDD, mutation testing ≥90%, zero `.unwrap()` in src).
Language v0.1 public spec is live; 1.0 is readiness-gated: the timeline carries the gates (conditions, never dates).
Building in public.

## License

Spec: Apache-2.0 (adopt freely, patent grant). Engine: AGPL-3.0-or-later.
Full copyleft. No SaaS loophole.