# 12-gate admission
Source: https://docs.nika.sh/architecture/admission

Twelve gates every crate must pass before joining the Nika workspace. No exceptions, no late fixes.

A crate does not join the Nika workspace by being merged. It joins by
**passing all twelve gates in the same commit**. No "we'll fix Gate 5
later." No "the spec is obvious." A crate admission is one atomic commit.

<Info>
  **Canonical source:** [`RUST_ENFORCEMENT.md`](https://github.com/supernovae-st/nika/blob/main/RUST_ENFORCEMENT.md) §12 Gates · checker `scripts/ci/check-crate-gates.sh` (machine-readable JSON output).

  **Live progress:**  crates admitted ·  WIP () · projected horizon  (cap ).
</Info>

## The 12 gates

<Steps>
  <Step title="Gate 1: SPEC">
    A crate spec exists at `docs/crate-specs/<crate>.md`. It declares:
    purpose, layer (L0/L0.5/L1/L2/L3/L4), LOC budget, public API surface,
    security axes, tracked ADRs. No code before spec.
  </Step>

  <Step title="Gate 2: TDD">
    Tests written before implementation. The commit history shows
    **RED before GREEN**: failing tests on one commit, minimal
    implementation on the next. Reviewed in gate 11.
  </Step>

  <Step title="Gate 3: IMPL">
    Minimal implementation. Compiles with `cargo build --workspace`.
    Every test green with `cargo test --workspace --lib`. No `# TEMP`
    without a removal plan. No `#[allow(dead_code)]`. No files >1500 LOC.
  </Step>

  <Step title="Gate 4: CLIPPY 0">
    `cargo clippy --workspace --all-targets -- -D warnings`: zero warnings.
    `unwrap_used = "deny"` enforced workspace-wide. Zero `.unwrap()` /
    `.expect(` in `src/` outside `#[cfg(test)]`.
  </Step>

  <Step title="Gate 5: MUTATION ≥ 90%">
    `cargo mutants -p <crate>`: at least 90% of mutants killed. Catches
    untested branches, "happy path only" tests, dead clauses. Data-heavy
    crates (e.g., `nika-catalog`) may use 85% with justification in spec.
  </Step>

  <Step title="Gate 6: PROPERTY">
    Property tests via `proptest` for any crate touching: security,
    parsers, encoding, taint propagation, capability resolution. Regression
    seeds checked into `proptest-regressions/`.
  </Step>

  <Step title="Gate 7: BENCHMARKS">
    `benches/` directory with `criterion` if the crate is on a hot path
    (parsers, catalog lookup, template resolution). Waivable for pure-types
    crates with justification in spec.
  </Step>

  <Step title="Gate 8: DOCS">
    `cargo doc --no-deps --document-private-items`: zero warnings. All
    public items documented. `#[doc(hidden)]` used sparingly and with reason.
  </Step>

  <Step title="Gate 9: CANARY E2E">
    A `.nika.yaml` canary workflow under `tests/canary-<crate>.nika.yaml`
    exercises the crate end-to-end against the rest of the workspace.
    Waivable for L0 foundation crates with no runtime surface.
  </Step>

  <Step title="Gate 10: PARITY LEGACY">
    Golden test comparing output against the legacy v0.79 implementation
    (read via `git show main:path/to/file.rs`). Flags behavior drift from
    v0.79 for conscious review. Landing from Phase 5+.
  </Step>

  <Step title="Gate 11: REVIEW SWARM">
    Three parallel agents review the PR: `spn-nika:code-reviewer` +
    `spn-rust:rust-pro` + `feature-dev:code-reviewer`. Every P0 and P1
    finding must be fixed in the same session before merge.
  </Step>

  <Step title="Gate 12: ATOMIC COMMIT">
    Single commit. Message:

    ```
    feat(<crate>): admit to workspace — all 12 gates passed

    Gate 1  SPEC     ✅  docs/crate-specs/<crate>.md
    Gate 2  TDD      ✅  RED before GREEN confirmed
    Gate 3  IMPL     ✅  <N> LOC, compiles, tests pass
    ...
    Co-Authored-By: Nika 🦋 <nika@supernovae.studio>
    ```
  </Step>
</Steps>

## Why twelve

<Check>
  Each gate catches a failure mode seen in production Rust codebases at
  scale. Dropping any one means accepting a known regression vector.
</Check>

| Gate       | Failure mode caught                                                  |
| ---------- | -------------------------------------------------------------------- |
| SPEC       | Scope creep, missing layer contract, undeclared axes                 |
| TDD        | Tests that retrofit the implementation (always green from commit 1)  |
| IMPL       | Oversized files, dead code, TEMP debt                                |
| CLIPPY     | Panic-prone patterns, hidden bugs flagged by lints                   |
| MUTATION   | "100% test coverage" with zero real assertions                       |
| PROPERTY   | Edge cases in parsers / taint / crypto that example-based tests miss |
| BENCHMARKS | Silent perf regression on hot paths                                  |
| DOCS       | Undocumented public API, broken intra-doc links                      |
| CANARY     | Integration breaks hidden by unit-test success                       |
| PARITY     | Silent behavior drift from the v0.79 baseline                        |
| REVIEW     | Single-reviewer blind spots                                          |
| ATOMIC     | Merge-commit noise, non-bisectable history                           |

## Exemptions

A gate is **genuinely not applicable** for some crate types:

* `benches/` for a pure-types crate with no hot path.
* Canary E2E for L0 foundation (nothing to execute end-to-end).
* PARITY for crates with no v0.79 counterpart (Diamond-original code).

**Exemptions are documented in `docs/crate-specs/<crate>.md` with a
1-paragraph justification.** They are not defaults. They are deliberate.

## Admission cadence

<Warning>
  One crate at a time. No parallel admission. No "let's admit these 3
  together." Each crate commit is atomic, bisectable, and reviewable in
  isolation.
</Warning>

The rhythm: **1 crate admission = 1 commit = 1 tag increment**
a per-admission alpha tag (`v0.8x.0-alpha.N`). Every 4 weeks, a blog post or dev log entry. Public
accountability.

## See also

<CardGroup>
  <Card title="Layer registry" icon="layer-group" href="/architecture/layers">
    Six layers. Mechanical sort test to pick the right layer for a new crate.
  </Card>

  <Card title="Forward-compat invariants" icon="shield-halved" href="/architecture/forward-compat-invariants">
    Eight patterns. The public-API contract every admitted crate honors.
  </Card>

  <Card title="L0 foundation decisions" icon="list-check" href="/architecture/l0-decisions">
    Q1-Q13 locked: the per-crate decisions that shaped today's L0.
  </Card>

  <Card title="Constellation" icon="diagram-project" href="/reference/constellation">
    Live progress: admitted, WIP, planned.
  </Card>
</CardGroup>


# ADR index
Source: https://docs.nika.sh/architecture/adrs

The Architecture Decision Record index — every significant engineering decision in Nika Diamond, versioned + auditable. Live counts derive from the status snapshot.

Every significant engineering decision in Nika Diamond lives as an ADR,
a short markdown file in [`docs/adr/`](https://github.com/supernovae-st/nika/tree/main/docs/adr)
with status, date, context, decision, consequences.&#x20;**&#x20;total**:
&#x20;Accepted,  Proposed.

<Info>
  **Canonical source:** [`docs/adr/index.json`](https://github.com/supernovae-st/nika/blob/main/docs/adr/index.json)
  (machine-readable) + [`docs/adr/README.md`](https://github.com/supernovae-st/nika/blob/main/docs/adr/README.md)
  (human index). One file per ADR, immutable once Accepted (superseded
  rather than edited).
</Info>

## At a glance

<CardGroup>
  <Card title="Total" icon="scroll">
    &#x20;decision records
  </Card>

  <Card title="Accepted" icon="check">
    &#x20;locked
  </Card>

  <Card title="Proposed" icon="clock">
    &#x20;in review
  </Card>
</CardGroup>

## By theme

<AccordionGroup>
  <Accordion title="Meta / Process (5)" icon="gavel">
    How Nika runs itself as a project: version cadence, admission, ADRs-on-ADRs.

    | ID                                                                                                   | Title                                                                                      | Status                       |
    | ---------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ | ---------------------------- |
    | [ADR-001](https://github.com/supernovae-st/nika/blob/main/docs/adr/adr-001-diamond-orphan-branch.md) | Diamond orphan branch rewrite instead of iterative refactor                                | ✅ Accepted                   |
    | [ADR-002](https://github.com/supernovae-st/nika/blob/main/docs/adr/adr-002-forever-v0x.md)           | Real semver toward 1.0: 0.91.0 release-candidate, 1.0 public API lock when gates are green | 🔄 amended (D-2026-06-20-N1) |
    | [ADR-003](https://github.com/supernovae-st/nika/blob/main/docs/adr/adr-003-12-gate-admission.md)     | 12-gate crate admission protocol                                                           | ✅ Accepted                   |
    | [ADR-009](https://github.com/supernovae-st/nika/blob/main/docs/adr/adr-009-adr-process.md)           | ADR process and hook discipline                                                            | ✅ Accepted                   |
    | [ADR-011](https://github.com/supernovae-st/nika/blob/main/docs/adr/adr-011-cargo-xtask.md)           | cargo xtask as canonical automation surface                                                | ✅ Accepted                   |
  </Accordion>

  <Accordion title="Architecture / Layering (6)" icon="layer-group">
    The six-layer crate discipline + physical workspace layout.

    | ID                                                                                                           | Title                                                                | Status     |
    | ------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------- | ---------- |
    | [ADR-004](https://github.com/supernovae-st/nika/blob/main/docs/adr/adr-004-context-window-sized-crates.md)   | Context-window-sized crate architecture                              | ✅ Accepted |
    | [ADR-006](https://github.com/supernovae-st/nika/blob/main/docs/adr/adr-006-layered-kernel-isp-traits.md)     | Layered architecture with kernel ISP atomic traits + `trait_variant` | ✅ Accepted |
    | [ADR-022](https://github.com/supernovae-st/nika/blob/main/docs/adr/adr-022-foundation-crate-layout-v081.md)  | Foundation crate layout v0.81: 14 crates, `publish = false`          | ✅ Accepted |
    | [ADR-023](https://github.com/supernovae-st/nika/blob/main/docs/adr/adr-023-file-modularity-discipline.md)    | File modularity: 800 LOC warn / 1500 fail / 3000 fail-with-ADR       | ✅ Accepted |
    | [ADR-026](https://github.com/supernovae-st/nika/blob/main/docs/adr/adr-026-workspace-toml-ssot.md)           | `workspace.toml` single source of truth + auto-generated `crate.md`  | ✅ Accepted |
    | [ADR-027](https://github.com/supernovae-st/nika/blob/main/docs/adr/adr-027-strict-l0-tiers-cargo-timings.md) | Strict L0 sublayer tiers + max 3 sibling deps                        | ✅ Accepted |
  </Accordion>

  <Accordion title="Forward-compat (4)" icon="shield-halved">
    How Nika stays additive across decades without breaking changes.

    | ID                                                                                                               | Title                                                                                 | Status     |
    | ---------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- | ---------- |
    | [ADR-007](https://github.com/supernovae-st/nika/blob/main/docs/adr/adr-007-forward-compat-invariants.md)         | Forward-compat invariants with `#[non_exhaustive]`, `new()`, pre-planted reservations | ✅ Accepted |
    | [ADR-014](https://github.com/supernovae-st/nika/blob/main/docs/adr/adr-014-sealed-kernel-traits.md)              | Sealed kernel traits with explicit adapter registration                               | ✅ Accepted |
    | [ADR-025](https://github.com/supernovae-st/nika/blob/main/docs/adr/adr-025-per-crate-semver-release-plz.md)      | Per-crate semver via `release-plz` (publishable crates only)                          | ✅ Accepted |
    | [ADR-028](https://github.com/supernovae-st/nika/blob/main/docs/adr/adr-028-forward-compat-reservation-policy.md) | Forward-compat reservation policy: seams now, crates later                            | ✅ Accepted |
  </Accordion>

  <Accordion title="Error handling + diagnostics (2)" icon="triangle-exclamation">
    How `NikaError` is shaped + how failures surface to users.

    | ID                                                                                                     | Title                                                         | Status     |
    | ------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------- | ---------- |
    | [ADR-005](https://github.com/supernovae-st/nika/blob/main/docs/adr/adr-005-error-hierarchy.md)         | Trait-based error hierarchy with `NikaErrorCode` + `Box<dyn>` | ✅ Accepted |
    | [ADR-010](https://github.com/supernovae-st/nika/blob/main/docs/adr/adr-010-miette-diagnostic-layer.md) | `miette` as the L4 diagnostic presentation layer              | ✅ Accepted |
  </Accordion>

  <Accordion title="Runtime + concurrency (5)" icon="rotate">
    Cancellation, streaming, sync primitives, retry / timeout ownership.

    | ID                                                                                                     | Title                                                                    | Status     |
    | ------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------ | ---------- |
    | [ADR-012](https://github.com/supernovae-st/nika/blob/main/docs/adr/adr-012-typestate-runtime.md)       | Typestate for `nika-runtime` workflow lifecycle                          | ✅ Accepted |
    | [ADR-016](https://github.com/supernovae-st/nika/blob/main/docs/adr/adr-016-cancellation-model.md)      | Cancellation model: future-drop primary + `CancelCtx` cooperative module | ✅ Accepted |
    | [ADR-017](https://github.com/supernovae-st/nika/blob/main/docs/adr/adr-017-streaming-policy.md)        | Streaming policy: bounded mpsc(32), `ReceiverStream` at kernel boundary  | ✅ Accepted |
    | [ADR-018](https://github.com/supernovae-st/nika/blob/main/docs/adr/adr-018-runtime-sync-primitives.md) | Runtime + sync primitives: single Tokio rt, `parking_lot` default        | ✅ Accepted |
    | [ADR-019](https://github.com/supernovae-st/nika/blob/main/docs/adr/adr-019-retry-timeout-ownership.md) | Retry + timeout ownership: stratified by layer                           | ✅ Accepted |
  </Accordion>

  <Accordion title="Testing (2)" icon="flask">
    How the engine verifies itself beyond unit tests.

    | ID                                                                                                           | Title                                                           | Status     |
    | ------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------- | ---------- |
    | [ADR-013](https://github.com/supernovae-st/nika/blob/main/docs/adr/adr-013-loom-concurrency-verification.md) | Loom-based concurrency verification for L0.5 + L3               | ✅ Accepted |
    | [ADR-015](https://github.com/supernovae-st/nika/blob/main/docs/adr/adr-015-expect-test-inline-snapshots.md)  | `expect-test` for inline snapshot assertions on rendered output | ✅ Accepted |
  </Accordion>

  <Accordion title="Catalog + YAML (2)" icon="book">
    The data-driven provider catalog and the workflow envelope convention.

    | ID                                                                                                      | Title                                                             | Status     |
    | ------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------- | ---------- |
    | [ADR-008](https://github.com/supernovae-st/nika/blob/main/docs/adr/adr-008-toml-driven-catalog.md)      | TOML-driven catalog with build-time codegen + perfect-hash lookup | ✅ Accepted |
    | [ADR-021](https://github.com/supernovae-st/nika/blob/main/docs/adr/adr-021-yaml-envelope-convention.md) | YAML envelope: `apiVersion + kind + metadata + spec`              | ✅ Accepted |
  </Accordion>

  <Accordion title="WASM + sandbox (1)" icon="box">
    The v0.100 plugin boundary, pre-planted at v0.80.

    | ID                                                                                                  | Title                                                               | Status     |
    | --------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------- | ---------- |
    | [ADR-020](https://github.com/supernovae-st/nika/blob/main/docs/adr/adr-020-wasm-plugin-boundary.md) | WASM plugin boundary + Sandbox: trait stubs now, dual timeout later | ✅ Accepted |
  </Accordion>

  <Accordion title="SOTA Rust patterns (1)" icon="crab">
    Cross-cutting idiom adoption.

    | ID                                                                                                | Title                                                                         | Status     |
    | ------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- | ---------- |
    | [ADR-024](https://github.com/supernovae-st/nika/blob/main/docs/adr/adr-024-sota-rust-patterns.md) | Adopt SOTA Rust patterns: `bon` Builder, `Arc<str>`, `camino`, sealed modules | ✅ Accepted |
  </Accordion>

  <Accordion title="L0 foundational additions (2)" icon="cube">
    Late-added Accepted ADRs covering foundational types + kernel expansion.

    | ID                                                                                                         | Title                                                                 | Status     |
    | ---------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------- | ---------- |
    | [ADR-033](https://github.com/supernovae-st/nika/blob/main/docs/adr/adr-033-l0-foundational-types.md)       | L0 foundational types: Cost, UUIDv7, TrustLevel, TokenUsage evolution | ✅ Accepted |
    | [ADR-034](https://github.com/supernovae-st/nika/blob/main/docs/adr/adr-034-l05-kernel-traits-expansion.md) | L0.5 kernel traits expansion: 6 new traits scoped to v0.81+           | ✅ Accepted |
  </Accordion>

  <Accordion title="Proposed: under review (5)" icon="clock">
    Seed-level reservations ahead of their implementing crates.

    | ID                                                                                                          | Title                                                                   | Status      |
    | ----------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- | ----------- |
    | [ADR-029](https://github.com/supernovae-st/nika/blob/main/docs/adr/adr-029-embedding-spec-reservation.md)   | EmbeddingSpec value-type reservation (memory subsystem seed)            | 🕒 Proposed |
    | [ADR-030](https://github.com/supernovae-st/nika/blob/main/docs/adr/adr-030-memory-frame-trust.md)           | `MemoryFrameRef.trust` reservation (Shield gate seed)                   | 🕒 Proposed |
    | [ADR-031](https://github.com/supernovae-st/nika/blob/main/docs/adr/adr-031-recall-query-tenant-keyspace.md) | `RecallQuery.tenant` reservation (multi-tenant keyspace seed)           | 🕒 Proposed |
    | [ADR-032](https://github.com/supernovae-st/nika/blob/main/docs/adr/adr-032-wasm-plugin-context.md)          | `WasmPluginError::OutOfFuel` + `Trap` + `PluginCallContext` reservation | 🕒 Proposed |
    | [ADR-035](https://github.com/supernovae-st/nika/blob/main/docs/adr/adr-035-telemetry-seams.md)              | Telemetry seams: `SpanGuard.parent_span_id` + `SpanRef` (OTel-ready)    | 🕒 Proposed |
  </Accordion>
</AccordionGroup>

## How ADRs work

<Steps>
  <Step title="Propose">
    Any significant engineering decision starts as a Proposed ADR: a
    short markdown file in `docs/adr/adr-NNN-<slug>.md` with
    frontmatter: `id`, `title`, `status: Proposed`, `date`, `tags`,
    `related`. Writer describes the context, options considered, and
    recommended decision.
  </Step>

  <Step title="Review">
    Proposed ADRs are discussed in PRs. Others get `related:` /
    `supersedes:` / `requires:` links. Status can flip to Accepted or
    Rejected. The ADR index (`docs/adr/index.json`) is auto-regenerated.
  </Step>

  <Step title="Accept">
    Once Accepted, the ADR is **immutable**. Any revision happens via a
    new ADR that `supersedes:` the old one. This keeps decision history
    auditable: `git log` tells you when and why a given rule came in.
  </Step>

  <Step title="Supersede">
    Rare, but when a decision proves wrong, a new Accepted ADR
    supersedes it. The superseded ADR stays in the tree with
    `status: superseded` and `superseded_by:`. It has happened once so
    far: **ADR-021** (the K8s-style `apiVersion` envelope) was superseded
    by **ADR-082**, which locked the single `nika: v1` version marker.
    One ADR is also Rejected outright (**ADR-089**) and kept in the tree
    as the record of a road not taken.
  </Step>
</Steps>

## Metadata fields

Every ADR carries rich metadata in both its frontmatter and `index.json`:

| Field            | Purpose                                                                                                                                                                                  |
| ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`             | `ADR-NNN` · assigned in ascending order, never reused. Not gap-free: ranges are reserved in blocks, so the tree currently runs `ADR-001`..`ADR-106` with 043-077 and 101-104 unallocated |
| `title`          | One-line decision summary                                                                                                                                                                |
| `status`         | `Proposed` / `Accepted` / `Rejected` / `Superseded`                                                                                                                                      |
| `date`           | ISO date of last status change                                                                                                                                                           |
| `tags`           | Free-form (e.g., `architecture`, `runtime`, `forward-compat`)                                                                                                                            |
| `affects_crates` | List of crate names the decision constrains                                                                                                                                              |
| `affects_layers` | `L0`..`L5` · which layers feel the effect                                                                                                                                                |
| `supersedes`     | IDs this ADR replaces                                                                                                                                                                    |
| `superseded_by`  | ID that replaces this ADR                                                                                                                                                                |
| `related`        | Sibling ADRs in the same design arc                                                                                                                                                      |
| `requires`       | Prerequisite ADRs (this one makes no sense without them)                                                                                                                                 |
| `enables`        | Downstream ADRs this one unlocks                                                                                                                                                         |

## Gate 12 integration

<Check>
  Admission Gate 12 fails when a crate's commit changes a public API
  surface without either (a) being purely additive under
  `#[non_exhaustive]` rules, or (b) referencing an Accepted ADR that
  authorizes the break. The ADR trail is how breaking changes earn the
  right to exist.
</Check>

## See also

<CardGroup>
  <Card title="Forward-compat invariants" icon="shield-halved" href="/architecture/forward-compat-invariants">
    The 8 patterns that keep most ADRs additive.
  </Card>

  <Card title="L0 decisions" icon="list-check" href="/architecture/l0-decisions">
    Q1-Q13: the foundation decisions that became ADRs 033, 034 + others.
  </Card>

  <Card title="12-gate admission" icon="check-double" href="/architecture/admission">
    Gate 12 requires ADR alignment for breaking change.
  </Card>

  <Card title="ADR directory on GitHub" icon="github" href="https://github.com/supernovae-st/nika/tree/main/docs/adr">
    Browse the full ADR tree, index.json, and README.
  </Card>
</CardGroup>


# Forward-compat invariants
Source: https://docs.nika.sh/architecture/forward-compat-invariants

Eight patterns + five decisions that protect Nika's public API against breaking change. LOCKED at v0.80.

Nika follows **real semver toward 1.0**. Features ship incrementally across 1.x minors over years.
The 1.0 architecture must accommodate later minors (memory subsystem, agent-v2; WASM plugins, observability),
and features we haven't imagined **without breaking changes to the public API**.

<Info>
  **Status: LOCKED at v0.80.** Every crate admitted to the Diamond workspace must
  comply before passing Gate 12. Patterns distilled from Rust (2015→), Tokio
  (0.1→1.x), Deno, Cargo, Serde (9+ years stable), Axum/Tower, Bevy.

  **Canonical source:** [`docs/architecture/forward-compat-invariants.md`](https://github.com/supernovae-st/nika/blob/main/docs/architecture/forward-compat-invariants.md).
</Info>

## The 8 patterns

<AccordionGroup>
  <Accordion title="FCI-001: Kernel traits upfront, implementations deferred" icon="key">
    Define traits in `nika-kernel` at v0.90 for subsystems that ship later.
    Default methods return `Err(Unsupported)` until real implementations land.

    ```rust theme={"system"}
    #[trait_variant::make(MemoryStoreDyn: Send)]
    pub trait MemoryStore: Send + Sync + 'static {
        async fn put(&self, frame: MemoryFrame) -> Result<MemoryFrameRef>;
        async fn query(&self, q: &MemoryQuery) -> Result<Vec<MemoryFrame>>;
        async fn forget(&self, _r: &MemoryFrameRef) -> Result<()> {
            Err(NikaError::Unsupported("forget"))
        }
    }
    ```

    **Locked traits (v0.90):** `MemoryStore`, `EmbeddingProvider`, `ToolExecutor`,
    `WasmPluginHost`, `MetricsExporter` + `TracerProvider` + `AuditSink` +
    `EventSink` + `BillingSink`, `Sandbox`. Stubs in `src/plugin/`, `src/infra/`.

    **Impact:** v0.95 lights up the memory subsystem by adding `nika-memory-oxigraph` that implements
    `MemoryStore`. **Zero v0.90 code modification.**
  </Accordion>

  <Accordion title="FCI-002: `#[non_exhaustive]` on every public struct, enum, error variant" icon="lock">
    Every public type carries `#[non_exhaustive]` so adding a field or variant
    is always additive. `new()` constructors provide ergonomic construction
    without exposing struct literal syntax.

    ```rust theme={"system"}
    #[non_exhaustive]
    pub struct InferRequest {
        pub provider: ProviderId,
        pub model: ModelId,
        pub messages: Vec<Message>,
        // adding fields here never breaks downstream
    }

    impl InferRequest {
        pub fn new(provider: ProviderId, model: ModelId) -> Self { /* ... */ }
    }
    ```

    Invariant #19: every `#[non_exhaustive]` struct ships a `new()` constructor.
  </Accordion>

  <Accordion title="FCI-003: Single version marker per on-disk artifact" icon="file-code">
    A workflow pins its contract with **one header line** · `nika: v1` (a
    single version marker · the language name as key, the contract version
    as value · supersedes the older K8s `apiVersion:` and `schema:
            nika/workflow@X` forms). Parsers reject any other value (`v1.0` · `v2` …)
    with a clear error.

    ```yaml illustration · the envelope pin theme={"system"}
    nika: v1
    workflow:
      id: my-flow
    tasks: { ... }
    ```

    `v1` is the only value for the lifetime of the v1 contract: minor
    additions are **additive** and never change it. There is no `nika: v2` —
    ever: pre-1.0 grammar changes happen inside `v1` (the pre-1.0 stability
    contract) · after engine 1.0.0 the grammar is additive only.
    Non-workflow artifacts (package manifests, events) carry their own
    schema version field.
  </Accordion>

  <Accordion title="FCI-004: Extension namespaces (`nika.*` core + `x-*` community)" icon="plug">
    Public schemas reserve two namespaces: **`nika.*`** for core additions
    (authoritative, versioned) and **`x-*`** for community overlays (no
    stability guarantee, no collision with core). **Scope note** · in the
    workflow language both are RESERVED, not current: unknown top-level
    fields are rejected at v0.1, and the tool namespace set is closed at
    `nika:` / `mcp:` (engine-specific tools route through `mcp:`). The
    live `x-*` surface today is the pck registry.

    ```yaml illustration · RESERVED future extension fields (rejected today) theme={"system"}
    nika: v1
    workflow:
      id: my-flow
    nika.cache: { ttl: 3600 }      # nika.* core extension · a future additive minor
    x-my-org-metric: 42             # x-* community overlay · reserved · NOT valid v0.1
    ```
  </Accordion>

  <Accordion title="FCI-005: Reserved error code ranges" icon="triangle-exclamation">
    Two error surfaces, one rule each. The WORKFLOW-VISIBLE surface is the
    spec's `NIKA-<NAMESPACE>-<NNN>` taxonomy ( registered
    codes across  namespaces ·
    [`reference/error-codes`](/reference/error-codes)). Namespaces own
    `001-099` ranges, codes are never repurposed. The ENGINE-INTERNAL
    registry (`nika_error::codes` · `NIKA-1000+` blocks per L1 effect
    crate) is diagnostics machinery: reserved per crate, never
    reassigned, and never leaked into workflow-visible errors.
  </Accordion>

  <Accordion title="FCI-006: Sealed traits for core, open traits for extension" icon="seal">
    Core kernel traits (e.g., `Provider`, `EventSink`, `Sandbox`) are
    **sealed** via a private supertrait: only Nika-owned crates can
    implement them. Extension traits (e.g., `MemoryStore`) are open for
    community crates to implement.

    ```rust theme={"system"}
    mod sealed { pub trait Sealed {} }
    pub trait Provider: sealed::Sealed + Send + Sync { /* ... */ }
    ```

    Enforced by ADR-014.
  </Accordion>

  <Accordion title="FCI-007: Feature flags with stable defaults" icon="flag">
    New capability = new `feature` flag, OFF by default. After 1-2 minor
    cycles of stability, flips to default-ON. Never remove a default feature
    (breaking change): deprecate and redirect.

    ```toml theme={"system"}
    [features]
    default = ["rustls-tls"]
    rustls-tls = ["dep:rustls"]
    native-tls = ["dep:native-tls"]   # alternative, off by default
    ```
  </Accordion>

  <Accordion title="FCI-008: Public API discipline via CI" icon="robot">
    Three tools on every CI run:

    * **`cargo public-api`**: detects API surface changes per crate.
    * **`cargo semver-checks`**: verifies SemVer compatibility.
    * **`cargo deny`**: enforces license + advisories + layer bans.

    Gate 12 fails on any unintentional public API drift. `.public-api.json`
    snapshots are checked into the repo per crate.
  </Accordion>
</AccordionGroup>

## The 5 locked decisions (v0.80)

| ID          | Decision                                                                                                   | Impact                                                            |
| ----------- | ---------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------- |
| **FCI-009** | `EventKind` = scoped sub-enums (Pattern B), \~22 categories                                                | Emit site is compile-time checked; sub-enums evolve independently |
| **FCI-010** | `InferRequest` / `InferResponse` fields reserved: `memory`, `budget`, `baggage`, `trust_level`, `trace_id` | v0.95 adds memory without touching kernel                         |
| **FCI-011** | `schema:` field mandatory day-1                                                                            | Every on-disk artifact versioned from v0.90 forward               |
| **FCI-012** | `Provider` trait shape frozen (4 methods, 1 sealed supertrait)                                             | Cross-provider parity testable (shadow zone 2 + 7)                |
| **FCI-013** | Telemetry = 5 sibling sinks (Event, Metrics, Trace, Audit, Billing)                                        | OTel GenAI semconv bridged via typed `GenAiAttrs` (Q13 rev.3)     |

## The 10 rules

<Check>
  Every crate admission answers "yes" to each. `cargo public-api` +
  `cargo semver-checks` catch violations before merge.
</Check>

1. All public types carry `#[non_exhaustive]`.
2. All public structs with `#[non_exhaustive]` ship a `new()` constructor.
3. All `async` trait methods use `trait_variant::make` for dynamic dispatch.
4. All core traits seal via private supertrait.
5. All error types expose a `NIKA-XXX` code via `NikaError::code()`.
6. All on-disk schemas carry `schema: "nika/<kind>@<major>"`.
7. All DTO fields reserve forward-compat extension slots (see FCI-010).
8. All feature flags default to a stable subset: new caps ship OFF.
9. All public API changes emit a `cargo public-api` diff in the PR.
10. All breaking changes require ADR Accepted before merge.

## See also

<CardGroup>
  <Card title="Layer registry" icon="layer-group" href="/architecture/layers">
    Six layers + L0.5, mechanical sort test, security axes.
  </Card>

  <Card title="L0 foundation decisions" icon="list-check" href="/architecture/l0-decisions">
    Q1-Q13 locked 2026-04-16: proc macros, kernel prelude, transform crate, memory sinks.
  </Card>

  <Card title="12-gate admission" icon="check-double" href="/architecture/admission">
    How a crate earns a seat at the workspace: SPEC through ATOMIC commit.
  </Card>

  <Card title="ADR index" icon="scroll" href="https://github.com/supernovae-st/nika/tree/main/docs/adr">
    35 decision records (30 Accepted + 5 Proposed).
  </Card>
</CardGroup>


# L0 foundation decisions
Source: https://docs.nika.sh/architecture/l0-decisions

Q1-Q13: the 13 architectural decisions that lock the L0 + L0.5 layer shape.

Thirteen questions, thirteen locks. These decisions shape the **L0 foundation**
( admitted + remaining through Round 4) and the
**L0.5 kernel contract**. Revised twice by swarm audit: current state is
rev. 3.

<Info>
  **Canonical source:** [`docs/architecture/l0-l05-architecture-decisions.md`](https://github.com/supernovae-st/nika/blob/main/docs/architecture/l0-l05-architecture-decisions.md).
  Full rationale (3-4 agents per question) lives in the engine repo.
</Info>

## Decision index

| Q       | Decision                                                            | Status                  |
| ------- | ------------------------------------------------------------------- | ----------------------- |
| **Q1**  | No proc macros in L0 · manual impl + `macro_rules!`                 | LOCKED                  |
| **Q2**  | No `nika-stdx`; split `nika-error` → `nika-types` + `nika-error`    | LOCKED · executed       |
| **Q3**  | Extract `nika-catalog-codegen` NOW (testable + reusable)            | LOCKED                  |
| **Q4**  | `nika-event`: 3-layer split (L0 types + L1 store + L2 export)       | LOCKED                  |
| **Q5**  | Admission order: schema → codegen → event → binding → pck-manifest  | LOCKED                  |
| **Q6**  | `EventKind` = scoped sub-enums (Pattern B, \~22 categories)         | LOCKED                  |
| **Q7**  | `nika-kernel` prelude re-export hub (4 lines, 0 new deps)           | LOCKED                  |
| **Q8**  | `nika-transform` = standalone L0 crate (rev.2: 2 consumers found)   | LOCKED rev.2            |
| **Q9**  | `Timestamp` + `WallDuration` = module in `nika-types`               | LOCKED rev.2            |
| **Q10** | Canonical-JSON (RFC 8785) = module in `nika-types`                  | LOCKED rev.2            |
| **Q11** | Token-streaming cardinality = delta-batching, not 1-event-per-token | LOCKED rev.3            |
| **Q12** | Drop `ObservabilitySink` + add `AuditSink` (5 sibling channels)     | LOCKED rev.3 · executed |
| **Q13** | Bridge OTel GenAI semconv via typed `GenAiAttrs` on Infer           | LOCKED rev.3 · executed |

## Why these decisions exist

<Warning>
  L0 is the foundation. A wrong choice at L0 propagates through 40+ crates.
  These decisions were made BEFORE any L1 / L2 admission to avoid costly
  migrations. Each was validated by ≥3 Rust council agents + cross-checked
  against 17 Phase-C research agents.
</Warning>

## Deep dives

<AccordionGroup>
  <Accordion title="Q1: No proc macros in L0" icon="ban">
    **Rationale.** Proc macros add compile-time dependency on `syn` + `quote`

    * `proc-macro2` (\~50 MLOC compile graph). L0 crates must compile in
      seconds for CI parity testing. Manual `impl Trait for Struct` +
      `macro_rules!` covers every pattern we've needed at L0.

    **Escape hatch.** Proc macros allowed at L2+ (e.g., `#[builtin_tool]`
    attribute macro in `nika-verb-invoke`). L0 stays procmacro-free forever.

    **Impact.** `nika-types` compile time stays \< 2s; downstream crates
    don't pay proc-macro cost transitively.
  </Accordion>

  <Accordion title="Q2: nika-types is the foundation, not nika-stdx" icon="cube">
    **Rationale.** A generic `nika-stdx` crate devolves into a kitchen-sink
    (anti-pattern #1 from layer-registry). Instead, foundation types live in
    `nika-types` (splitable when cohesion demands), error infra in
    `nika-error`, lookup tables in `nika-catalog`. Purpose-named, not
    kitchen-sink.

    **Executed.** `nika-types` admitted as L0 foundation (no I/O, no async,
    Cow-heavy). `nika-error` re-exports the subset it needs.
  </Accordion>

  <Accordion title="Q3: Extract nika-catalog-codegen as standalone L0" icon="hammer">
    **Rationale.** TOML → Rust codegen is testable logic that today lives
    in `build.rs`. Extract it so:

    * `build.rs` remains \<50 LOC (delegates).
    * Codegen gets its own unit tests + snapshot tests.
    * Community overlays (`nika-catalog-cn`) reuse the same codegen.

    Targets admission Round 3 post-nika-schema.
  </Accordion>

  <Accordion title="Q4: nika-event 3-layer split" icon="bell">
    **Rationale.** Event emission (L0 types + scoped sub-enums) is concept
    separate from storage (L1 `nika-event-store` writes NDJSON / SQLite)
    which is separate from export (L2 `nika-event-export` pushes OTel /
    Datadog / Honeycomb). Each layer tested in isolation.

    **Mapping**: L0 `nika-event` (\~2.5k LOC) types + sub-enums ·
    L1 `nika-event-store` (\~3k LOC, future) · L2 `nika-event-export` (\~2k LOC, future).
  </Accordion>

  <Accordion title="Q5: Admission order for L0" icon="arrow-right">
    **Order.** schema → catalog-codegen → event → binding → pck-manifest.

    **Why this order.**

    * `nika-schema` unblocks the rest (it defines the AST).
    * `catalog-codegen` independent (purely build-time).
    * `nika-event` needs types (done) and schema (for correlation IDs).
    * `nika-binding` needs event + transform.
    * `nika-pck-manifest` is standalone and can run in parallel with any of the above.
  </Accordion>

  <Accordion title="Q6: EventKind scoped sub-enums (not mega-enum)" icon="tags">
    **Rationale.** A single `EventKind` enum with 22 variants becomes a
    merge-conflict magnet and bloats every consumer's match arm. Instead,
    \~22 sub-enums grouped by emission site (`ExecEvent`, `InferEvent`,
    `ProviderEvent`, etc.), unified under an `Event` sum type via the
    `event_categories!` macro.

    **Impact.** Each verb crate emits its own sub-enum variants; consumers
    match on the category they care about; rest are transparent.
  </Accordion>

  <Accordion title="Q7: nika-kernel prelude re-export hub" icon="star">
    **Rationale.** L2+ verb crates today `use nika_types::*; use nika_error::*;
            use nika_kernel::traits::*;` (3 imports every file). Instead,
    `nika-kernel` ships `pub mod prelude` that re-exports from `nika-types`

    * `nika-error` + its own traits. Verb crates: `use nika_kernel::prelude::*;`.

    **Cost.** 4 lines of code. Zero new deps (already transitive).
  </Accordion>

  <Accordion title="Q8: nika-transform = standalone L0 crate (REVERTED rev.2)" icon="rotate-left">
    **Original decision.** Inline `nika-transform` into `nika-binding` (single
    consumer).

    **Reversion rationale.** Swarm audit found a **second consumer**:
    `nika-builtin-*` crates need `nika-transform` filters (json, base64,
    shell\_quote) for `invoke:builtin:` parameter processing. Inlining would
    force `nika-binding` dependency on every builtin crate (wrong coupling).

    **Final.** `nika-transform` stays L0, 65 transforms in 7 sub-modules,
    two consumers (binding + builtin-\*).
  </Accordion>

  <Accordion title="Q9-Q10: Timestamp + canonical-JSON = modules in nika-types" icon="clock">
    **Rationale rev.2.** Both were initially planned as standalone L0 crates
    (`nika-time`, `nika-canonical`). Audit found each has zero
    non-foundation dependencies and tight coupling to core types. They
    become modules inside `nika-types`:

    * `nika_types::timestamp`: `Timestamp` + `WallDuration` (monotonic + RFC3339)
    * `nika_types::hash::canonical`: RFC 8785 canonical-JSON for hash stability

    **Impact.** `nika-types` gains \~300 LOC, stays well under 15k crate cap.
  </Accordion>

  <Accordion title="Q11: Token-streaming delta-batching" icon="wave-square">
    **Rationale.** Emitting 1 `InferEvent::Token` per LLM token would flood
    the event bus (2k tokens/s on fast providers). Instead, batch into
    deltas: emit `InferEvent::Delta { text, token_count, duration }` every
    50ms or 32 tokens, whichever first.

    **Impact.** Event rate capped at \~20 Hz regardless of provider speed.
  </Accordion>

  <Accordion title="Q12: 5 sibling sinks (not 1 ObservabilitySink)" icon="diagram-project">
    **Rationale rev.3.** The original `ObservabilitySink` god-trait would have
    forced every sink implementation to handle 5 concerns at once. Instead,
    5 sibling traits live alongside each other:

    * `EventSink`: structured events (NDJSON, OpenTelemetry)
    * `MetricsExporter`: Prometheus / StatsD / OTel metrics
    * `TracerProvider`: OTel traces (W3C TraceContext)
    * `AuditSink`: compliance audit log (tamper-evident, separate from EventSink)
    * `BillingSink`: cost accounting (\$ per provider call)

    **Impact.** Each sink tested independently. Implementations can mix-and-match
    (e.g., Honeycomb for trace, Prometheus for metrics, local NDJSON for audit).
  </Accordion>

  <Accordion title="Q13: OTel GenAI semconv via typed GenAiAttrs" icon="link">
    **Rationale rev.3.** OpenTelemetry defines [GenAI semantic conventions](https://opentelemetry.io/docs/specs/semconv/gen-ai/)
    for LLM attributes (`gen_ai.system`, `gen_ai.request.model`, etc.).
    Rather than stuff strings into a `HashMap<String, String>`, expose a
    typed `GenAiAttrs` struct on `InferRequest` / `InferResponse`.

    **Impact.** Consumers get IDE completion + compile-time safety.
    Non-breaking: `GenAiAttrs` is `#[non_exhaustive]`. New attrs are additive.
  </Accordion>
</AccordionGroup>

## See also

<CardGroup>
  <Card title="Layer registry" icon="layer-group" href="/architecture/layers">
    How these L0 crates fit into the 6-layer pyramid.
  </Card>

  <Card title="Forward-compat invariants" icon="shield-halved" href="/architecture/forward-compat-invariants">
    The 8 patterns that make these decisions safe to evolve.
  </Card>

  <Card title="12-gate admission" icon="check-double" href="/architecture/admission">
    How each L0 crate earns its seat.
  </Card>

  <Card title="Constellation" icon="diagram-project" href="/reference/constellation">
    Live state: which L0 crates are admitted today.
  </Card>
</CardGroup>


# Layer registry
Source: https://docs.nika.sh/architecture/layers

Six layers (L0 → L5) + L0.5 for trait-only crates. Upward dependencies are a CI hard failure.

Nika Diamond is  admitted crates organized into **six layers**,
with a half-layer (**L0.5**) for trait-only crates. Every workspace-local
dependency points strictly downward. A CI script (`check-layering.sh`)
fails the build on any upward import.

<Note>
  **Canonical source:** [`docs/architecture/crate-layer-registry.md`](https://github.com/supernovae-st/nika/blob/main/docs/architecture/crate-layer-registry.md).
  This page curates the layer model for readers; the authoritative manifest
  lives in the engine repo next to the enforcement script.
</Note>

## Mechanical sort test

Every new crate answers these questions in order. First hit wins.

<Steps>
  <Step title="Does it produce the `nika` binary?">
    → **L5** (the binary)
  </Step>

  <Step title="Does it expose a transport / UI surface (CLI, HTTP, MCP, LSP, SDK)?">
    → **L4** (interfaces)
  </Step>

  <Step title="Does it enforce runtime policy, sandboxing, or orchestration?">
    → **L3** (runtime + policy + sandbox)
  </Step>

  <Step title="Does it implement a verb or a domain service?">
    → **L2** (verbs + services)
  </Step>

  <Step title="Is it a primitive with I/O (fs, net, exec, env)?">
    → **L1** (effect impls)
  </Step>

  <Step title="None of the above?">
    → **L0** (pure, sync, zero I/O). If it's trait-only but async is OK, → **L0.5**.
  </Step>
</Steps>

## The pyramid

```mermaid theme={"system"}
%%{init: {'theme':'dark','themeVariables':{'background':'transparent','mainBkg':'transparent'}}}%%
flowchart TB
  classDef layer0 fill:#1e3a8a,color:#fff,stroke:#3b82f6
  classDef layer05 fill:#6d28d9,color:#fff,stroke:#8b5cf6
  classDef layer1 fill:#065f46,color:#fff,stroke:#10b981
  classDef layer2 fill:#92400e,color:#fff,stroke:#f59e0b
  classDef layer3 fill:#9a3412,color:#fff,stroke:#f97316
  classDef layer4 fill:#991b1b,color:#fff,stroke:#ef4444
  classDef layer5 fill:#4c1d95,color:#fff,stroke:#a78bfa,font-weight:bold

  L5["L5 — `nika` binary (&lt;500 LOC)"]:::layer5
  L4["L4 — interfaces · cli · serve · mcp · lsp · sdk"]:::layer4
  L3["L3 — runtime · policy · shield · sandbox"]:::layer3
  L2["L2 — verbs · builtins · pck · memory · observability"]:::layer2
  L1["L1 — effects · fs · http · process · keys · provider impls"]:::layer1
  L05["L0.5 — kernel traits + mock (async OK, zero I/O)"]:::layer05
  L0["L0 — pure types · sync · zero I/O · zero deps on runtimes"]:::layer0

  L5 --> L4 --> L3 --> L2 --> L1 --> L05 --> L0
```

<sub>Arrows read "depends on". Upward arrows are forbidden: `check-layering.sh` fails on any workspace-local dep that points up.</sub>

## Layer table

| Layer    | Role                                                                 | Allowed I/O                                | Allowed deps | Example crates                                                                                                                                         |
| -------- | -------------------------------------------------------------------- | ------------------------------------------ | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **L0**   | Pure types, lookup tables, sync-only APIs                            | none                                       | (leaf)       | `nika-types`, `nika-error`, `nika-catalog`, `nika-schema`, `nika-event`, `nika-binding`, `nika-transform`, `nika-pck-manifest`, `nika-catalog-codegen` |
| **L0.5** | Kernel trait definitions + companions (mock) · async OK              | none (traits only)                         | L0           | `nika-kernel` (facade hub), `nika-kernel-core`, `nika-kernel-ai`, `nika-kernel-runtime`, `nika-kernel-plugin`, `nika-kernel-mock`                      |
| **L1**   | Effect implementations · async, per-crate capability axis            | declared axes only (fs / net / exec / env) | L0, L0.5     | `nika-fs`, `nika-http`, `nika-process`, `nika-git`, `nika-keys-*`, `nika-pck-registry`, `nika-pck-store`, `nika-<provider>-*`                          |
| **L2**   | Verbs + domain services · orchestrates L1 impls behind kernel traits | via L1 traits only                         | L0, L0.5, L1 | `nika-pck`, `nika-verb-*`, `nika-policy`, `nika-connectome`, `nika-observability`, `nika-builtin-{github,cloud,workspace}`                             |
| **L3**   | Runtime + policy + sandbox · enforces execution contracts            | via L2                                     | L0..L2       | `nika-runtime`, `nika-shield`, `nika-wasm-host` (v0.100), `nika-sandbox` (v0.100)                                                                      |
| **L4**   | Interfaces · transport / UI surfaces (libraries)                     | via L3                                     | L0..L3       | `nika-cli`, `nika-serve`, `nika-mcp`, `nika-lsp`, `nika-sdk`, `nika-catalog-verify`                                                                    |
| **L5**   | The binary · sole `[[bin]]` composition root                         | via L4                                     | L0..L4       | `nika` (\<500 LOC)                                                                                                                                     |

<Tip>
  `nika-http` is the **L1 HTTP client** (used by `fetch` / catalog sync).
  The HTTP server surface of `nika serve` lives **inline inside
  `nika-serve` L4**: no separate server crate.
</Tip>

## Admitted today (v)

<CardGroup>
  <Card title="nika-types" icon="cube" href="https://github.com/supernovae-st/nika/tree/main/crates/nika-types">
    **L0** · Foundation value types. Leaf of the DAG.
  </Card>

  <Card title="nika-error" icon="triangle-exclamation" href="https://github.com/supernovae-st/nika/tree/main/crates/nika-error">
    **L0** · NIKA-XXX error hierarchy + `miette` integration.
  </Card>

  <Card title="nika-catalog" icon="book" href="https://github.com/supernovae-st/nika/tree/main/crates/nika-catalog">
    **L0** · Provider / capability TOML catalog, phf lookup.
  </Card>

  <Card title="nika-kernel" icon="circuit-board" href="https://github.com/supernovae-st/nika/tree/main/crates/nika-kernel">
    **L0.5** · 40 ISP traits, sealed supertrait, prelude re-export hub.
  </Card>

  <Card title="nika-kernel-mock" icon="circuit-board" href="https://github.com/supernovae-st/nika/tree/main/crates/nika-kernel-mock">
    **L0.5** · Pure-memory trait mocks for testing.
  </Card>

  <Card title="nika-catalog-verify" icon="check" href="https://github.com/supernovae-st/nika/tree/main/crates/nika-catalog-verify">
    **L4** · Build-only catalog validation tool.
  </Card>
</CardGroup>

<sub>**WIP:** `nika-schema` (parser scaffolding, Round 4 admission gate).</sub>

## Security axes

Every L1 crate declares the capabilities it exercises in
`docs/architecture/security-axes.toml`. Reserving an axis costs nothing
today and forbids its silent later use.

<AccordionGroup>
  <Accordion title="The 12 capability axes" icon="shield">
    | Axis                  | Meaning                                                          |
    | --------------------- | ---------------------------------------------------------------- |
    | `reads-env`           | Reads process environment variables                              |
    | `reads-fs`            | Reads filesystem (read-only)                                     |
    | `rw-fs`               | Reads and writes filesystem                                      |
    | `exec-shell`          | Spawns subprocesses                                              |
    | `net-egress`          | Initiates outbound network connections                           |
    | `net-ingress`         | Accepts inbound connections                                      |
    | `spawns-thread`       | Uses `std::thread::spawn` or `tokio::task::spawn_blocking`       |
    | `mutates-global`      | Mutates process-global state (env, CWD, signals)                 |
    | `panics-allowed`      | Explicit opt-out from zero-panic discipline (rare)               |
    | `reads-secrets`       | Reads `Secret<T>` / `SecretRef` material                         |
    | `time-mutation`       | Manipulates clocks (`MockClock`, `tokio::time::pause`)           |
    | `allocator-sensitive` | Imposes allocator constraints (pre-flight for WASM v0.100)       |
    | `thread-local-state`  | Uses `thread_local!` / static `RefCell` (incompatible with WASM) |
  </Accordion>

  <Accordion title="How enforcement works" icon="gavel">
    Three CI vectors enforce layer discipline:

    * **`check-layering.sh`** (hygiene vector 11, P0, fail on violation): reads layer membership from `[workspace.metadata.diamond.layers]` and verifies every workspace-local dependency is equal or lower layer.
    * **`check-security-axes.sh`** (vector 12, P1): cross-checks declared axes against static analysis of the source tree.
    * **`check-no-async-in-l0.sh`** (vector 16, P1): greps `async fn` / `async {` in L0 source trees; fails on any match.
  </Accordion>
</AccordionGroup>

## Forward compatibility

* **The Connectome**: 1 L2 orchestrator (`nika-connectome`) + 10 L1 satellites (hnsw, bm25, rrf, rerank, fsrs, rdfs-reasoner, temporal, graph-algos, autodesc-minimal, autodesc-full). No renumber: they slot into L1 / L2 naturally.
* **v0.100 WASM** plugin host + sandbox: L3 crates alongside `nika-runtime`. No renumber.

## Anti-patterns

<Warning>
  Seven patterns that tank the layer contract. If you catch yourself writing one, stop and re-ask the mechanical sort test.
</Warning>

1. **Kitchen-sink crate**: "I'll just add this utility to `nika-error`" leads to a 10k-LOC bag-of-tricks every crate transitively pulls in. One caller = stays in the caller.
2. **Facade mega-crate**: "Re-export everything from `nika` for convenience" collapses the layer contract and tanks compile time.
3. **Upward re-exports**: an L1 crate `pub use nika_pck::...` turns its API into an L2 consumer and breaks mechanical sorting.
4. **`async` in L0**: forces a runtime choice on every L1 / L2 consumer; makes the crate unusable in build scripts.
5. **`anyhow::Error` in library code**: L5 binary only. L0..L4 uses the typed error hierarchy.
6. **`Box<dyn Error>` in public API**: hygiene vector 19 bans it. Swap to the typed error hierarchy.
7. **Runtime imports in L0**: `tokio::spawn` in `nika-error` is a layer violation even if it compiles.

## See also

* [Forward-compat invariants](/architecture/forward-compat-invariants), the 8 patterns + 5 decisions that protect the public API
* [L0 foundation decisions](/architecture/l0-decisions): Q1 through Q13, locked
* [12-gate admission](/architecture/admission), how a crate earns a seat at the workspace
* [Constellation](/reference/constellation), live map of admitted / WIP / planned crates


# Releases
Source: https://docs.nika.sh/changelog/releases

The full arc — the exploration (summer 2025), the brouillon era (v0.1 → v0.79), the Diamond rewrite, and every public release since v0.90.0. One source of truth: `CHANGELOG.md` on the `main` branch.

Nika follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and
[real semver toward 1.0](/changelog/roadmap). The history below spans three
eras, and every entry is dated from the git record:

1. **✧ Exploration** (summer 2025 → end 2025) — private prototypes before
   the repo existed: the idea, tested in code that was never meant to
   survive.
2. **✎ Brouillon** (January 1 → April 13, 2026) — the named draft: v0.1 →
   v0.79.3, a 14-week private sprint that grew to a 322k-LOC engine and
   taught the lesson Diamond is built on. The era is called what its git
   branch is called: `brouillon`.
3. **◆ Diamond** (April 13, 2026 →) — a ground-up rewrite, one crate at a
   time, 12 gates each; tagged binaries and real semver since v0.90.0
   (June 21, 2026).

<Info>
  **Canonical source:** [`CHANGELOG.md`](https://github.com/supernovae-st/nika/blob/main/CHANGELOG.md)
  on the `main` branch. This page curates the milestones; the full history
  lives in the repo. Current HEAD `{STATUS.head}`. Filter entries with the
  tags, or subscribe via [RSS](https://docs.nika.sh/changelog/releases/rss.xml).
  The era model itself is machine-verified: [nika.sh/timeline](https://nika.sh/timeline)
  renders the spec's [`timeline/timeline.yaml`](https://github.com/supernovae-st/nika-spec/blob/main/timeline/timeline.yaml),
  and every provable claim in it is re-proven in CI against crates.io and GitHub.
</Info>

## Cadence

<Check>
  **Since v0.90.0 (June 21, 2026 · the first public release), every release
  is a real-semver tag with binaries**: Homebrew, the install script, a
  GitHub Release, and a curated `CHANGELOG.md` section. Public
  accountability, no hidden work.
</Check>

Between release tags, progress lands on `main` as:

1. **Crate admission commits** (e.g., `feat(nika-X): admit to workspace — all 12 gates passed`).
2. **Hygiene vector deployments** ( active vectors guard the workspace on every push).
3. **ADR promotions** ( total:  Accepted,  Proposed).

## History

<Update label="v0.107.0" description="2026-08-01 · the trust release — three doors, one honest machine">
  An outside audit measured the **experience** instead of the feature list
  — five waves, seventy-two receipts, twenty-two P0s — and the arc closed
  every one. Consent means consent: a non-affirmative answer fires **zero
  effects** (`NIKA-SEC-014`, minted spec-first with its conformance
  fixtures). The hooks' judge moved into the binary (`nika guard`,
  fail-visible). Autonomy is graded before it is colored — the risk rung
  never renders green past Supervised. The data journey names sources,
  destinations and secrets **before** the run, and redaction works by
  provenance: a one-byte secret dies the same death as a long one.

  **The teaching grammar collapses to three doors.** `nika try [slug]` is
  the showroom — offline by default (the mock rehearsal · zero keys · zero
  flags), nothing written, nothing owned; bare `nika try` lists what there
  is to see. `nika new` takes ONE positional gesture: plain words route
  across the whole catalog, an example slug lands verbatim WITH its
  ingredients, a skeleton name instantiates (`nika new '?'` lists the
  set). `nika init` founds. The old doors die loudly:

  | Dead door                           | The 0.107 door                                |
  | ----------------------------------- | --------------------------------------------- |
  | `nika examples` (the verb tree)     | `nika try` to see · `nika new <slug>` to take |
  | `nika new --from <template> <dest>` | `nika new <slug-or-plain-words> [dest]`       |
  | `nika evidence <trace>`             | `nika trace evidence <trace>`                 |
  | `nika receipt explain <file>`       | `nika trace receipt explain <file>`           |

  **A human gate can no longer kill a first run.** A `nika:prompt` with no
  `default:` used to die in milliseconds on every text-mode run. The rider
  is now armed on every lane: unattended runs **pause durably** (exit 4,
  the pause journaled, never a failure frame), and at a terminal the gate
  asks you directly — confirm `[y/N]`, choice, or input — leaving a
  paste-able resume line that carries the run's own `--var`/`--model`.

  Around the core, the doors multiplied honestly: `nika wire` previews and
  never rewrites unasked, six clients join the targets (grok · antigravity
  · kimi · kiro · copilot · amp — `wire all` covers twenty-one), and
  `nika init` writes the two project MCP doors (`.mcp.json` +
  `.agents/mcp_config.json`), handing the read-only oracle to agent
  surfaces with zero machine wiring. `nika doctor` gives every probed host
  a capability receipt and names kit↔binary train drift with the exact
  align command. Cost honesty grows an **energy rung** (NEP-0018 —
  watt-hours beside dollars), and a priced backend that omits token usage
  now fails closed.

  These docs teach 0.107 and only 0.107. The 0.106 value/permits grammar
  is unchanged — what moved is the CLI's teaching surface. Pin the tag
  you run.
</Update>

<Update label="v0.106.0" description="2026-07-27 · the values get names, the boundary gets teeth">
  Two flag-days land in one window, and both are the same idea: **a thing
  the file left implicit becomes a thing the file declares.**

  **① The E-split — `vars:` and `env:` die into four named authorities.**
  One block for everything a workflow knew was a block that told you
  nothing: whether a value came from the caller, from the deployment, or
  from the file itself was invisible, and so was whether it could be
  trusted. The family is now closed at four, one role each — `inputs:`
  (the caller supplies it at launch) · `config:` (the deployment supplies
  it, and it may appear in logs) · `const:` (the file owns it, immutable)
  · `secrets:` (a governed store, masked). `inputs.*` and `config.*` are
  **untrusted** (they come from outside the file); literals, `const.*` and
  `secrets.*` are **trusted** — which is why a destination a `permits:`
  entry pins belongs in `const:`, where no caller can move it out from
  under the boundary.

  The old spellings refuse loudly, and they refuse with a *classification*,
  not a rename: there is no mechanical `vars:` → `inputs:` (that is how you
  end up with a caller-overridable output path). Each use is classified
  into the authority its role commands; `nika check --fix` migrates the
  provable cases and stops on the rest rather than guessing.

  **② An absent `permits:` block declares ZERO authority.** It used to mean
  "engine floor only" — a hint, and a green check. It now means what its
  absence always should have: no filesystem, no network, no shell, no
  tools. Every effect the body requires is refused at check with
  `NIKA-AUTH-006` before a single token is spent, and any effect that
  reaches run time fails the task with `NIKA-SEC-004`. A pure-compute
  workflow still passes; `permits: {}` is the authored spelling of "I
  touch nothing"; and under composition the absence is a wall — a parent's
  grants never flow down implicitly (`NIKA-COMP-002`). The repair is one
  command: `nika check --infer-permits` walks the DAG and prints the
  tightest boundary the body actually needs, ready to paste.

  | Dead form                             | Refusal                    | The 0.106 form                                                                                                                                             |
  | ------------------------------------- | -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
  | `vars:` block                         | `NIKA-VALUES-001`          | classify each entry → `inputs:` · `config:` · `const:` · `secrets:`                                                                                        |
  | `env:` block (envelope)               | `NIKA-VALUES-002`          | `config:` for a non-sensitive dial · `secrets:` for a governed reference (`exec.env:` is a different field and is untouched)                               |
  | `${{ vars.X }}` · `${{ env.X }}`      | `NIKA-VALUES-001` / `-002` | the read follows the declaration                                                                                                                           |
  | any other value namespace             | `NIKA-VALUES-003`          | the family is exactly four                                                                                                                                 |
  | no `permits:` block, body has effects | `NIKA-AUTH-006`            | the block `--infer-permits` writes                                                                                                                         |
  | `after: { x: succeeded }` · `failed`  | `NIKA-DAG-005`             | `success` · `failure` (`skipped` · `terminal` unchanged)                                                                                                   |
  | `type: boolean` in a declaration      | `NIKA-TYPE-001`            | `bool` — and the flat 6-enum gives way to the type grammar (`{ array: string }`, `{ object: { … } }`). Raw JSON Schema under `infer.schema:` is untouched. |

  Also in the window: an envelope `run:` block declares the run's
  **entropy** and **clock** (`{ entropy, clock }`, closed) — randomness and
  time stop being ambient, and `entropy: { seeded: N }` + `clock: virtual`
  make two runs of the same file byte-identical. The dimensions couple, so
  a declared contradiction refuses at parse (`NIKA-PARSE-026` /
  `NIKA-PARSE-027`).

  These docs teach 0.106 and only 0.106 — no dual grammar, no "if you are
  on 0.105" branch. Pin the tag you run.
</Update>

<Update label="v0.105.0" description="2026-07-20 · the map comes home">
  The refonte reaches users — **the file becomes a map**. `workflow:` is
  an object (`id:` + `description:`), `tasks:` is a map keyed by id, and
  precedence reads the way you think: **the binding IS the edge**
  (`with: x: ${{ tasks.a.output }}` declares the data edge) · control-only
  ordering is `after: {producer: succeeded}` against a closed predicate
  set (succeeded · failed · skipped · terminal). The old forms die loudly
  — a scalar `workflow:` is NIKA-PARSE-020, `depends_on:` is
  NIKA-PARSE-024 — and `nika check --fix` machine-migrates the provable
  cases. The proof layer opens: semantic hash + `nika.lock` +
  `receipt_format: 1`, workflow composition (`invoke: workflow:`), and
  `nika:decide`, the deterministic decision kernel. One security seat
  ships in this tag: the **lethal-trifecta judge** (NIKA-SEC-009) refuses
  private-read + untrusted-ingress + external-egress with no blocking
  human gate on the path. The LSP learns the map end-to-end (server-side
  rename · per-block keysets · `semantic_document_format: 1`). Every
  surface you copy from re-baked the same day — the site, these docs, the
  templates and the kit speak the released grammar (the serve-time door
  law: what you copy runs on YOUR installed binary). Thinking-model note,
  same honesty as the K3 seat: reasoning spends `max_tokens` — budget
  generously or declare `thinking:`; an empty answer says why.
</Update>

<Update label="v0.104.0" description="2026-07-17 · the seventeenth seat">
  **Moonshot (Kimi) joins the canonical catalog** — 17 providers (11 cloud
  · 5 local · 1 test). `model: moonshot/kimi-k3` runs Kimi K3 first-class:
  1M context, `MOONSHOT_API_KEY`, and the pricing snapshot makes
  `--max-cost-usd` a **hard ceiling** on kimi spend (the promotion run
  metered $0.002787 against a $0.0077 printed worst-case). K3 is a
  thinking model — reasoning spends output tokens, so budget `max_tokens`
  generously (512+; at 64 the answer comes back empty and the engine says
  why). Weights are announced open on July 27; until then the hosted API
  routes through Moonshot's servers with training-by-default — read the
  permits section of your workflow as the data-residency contract it is:
  no declared egress, no call. Also in this wave: the lsp/graph/mcp test
  fixtures that shipped red at the v0.103.0 tag now speak the argv form
  (a CI-coverage gap banked as a finding), and the tag's rustfmt drift is
  cleared. Release branch cut from v0.103.0 — `main` is mid-refonte and
  users never ship a transitional grammar. Spec side: ADR-105 + stdlib
  16→17 + the escape-hatch doc now names the real variable
  (`NIKA_OPENAI_BASE_URL`, complete endpoint, verbatim).
</Update>

<Update label="v0.103.0" description="2026-07-13 · the language tightens">
  The pre-1.0 window pays for itself — three breaking cuts in one wave,
  spec and engine merged in the same window. `command:` is **argv-only**
  (`["cargo", "test"]` — execve, no shell: an interpolated value can
  never break out of its argument) and the string form moves to
  **`shell:`**, the explicit door — semantics ride the *field*, never
  the YAML type. A bare `${{ tasks.X }}` is now an error (NIKA-VAR-020):
  name the projection — `.output` / `.status` / `.error` /
  `.duration_ms`. And the gate algebra (upstream terminal × gate form →
  downstream status) becomes a normative spec table — the when-status
  pattern is a propagation *choice*, not redundancy. \~530 corpus sites
  migrated; docs, site, editor, kit and registry re-taught in lockstep.

  [Engine release](https://github.com/supernovae-st/nika/releases/tag/v0.103.0)
</Update>

<Update label="v0.102.0" description="2026-07-13 · the editor speaks the language">
  The LSP arc lands server-side: the pause after a colon answers
  itself (space joins the triggers), `args:` keys complete from the
  tool's own schema, `mode:` enums scope to the enclosing tool,
  `${{ vars./secrets./env. }}` complete from the FILE's declarations,
  hover cards read the graph (wave k/N · transitive reach · model
  fallback tiers), and references resolve closure-aware. Plus:
  `wave-sweep.sh` (the one-command release sweep) and three new
  coherence-bot probes born from drifts caught by hand.

  [Engine release](https://github.com/supernovae-st/nika/releases/tag/v0.102.0)
</Update>

<Update label="v0.101.0" description="2026-07-13 · the sovereign lane ships whole">
  Every release binary now carries `local-infer` — `nika model pull` →
  `nika model serve` → workflow `infer` against your own machine: no
  cloud, no external daemon, no build-from-source wall (#518, the
  release ruling, executed). CPU on every target on purpose (darwin
  included) until candle's quantized rms-norm Metal kernel is fixed.
  The release funnel now pins the teaching both ways: a shipped binary
  must never utter « built without local inference ».

  [Engine release](https://github.com/supernovae-st/nika/releases/tag/v0.101.0)
</Update>

<Update label="v0.100.0" description="2026-07-12 · the terminal sings · the models come home · the kit rides three surfaces">
  The terminal learns to sing: a **verb band** colors every task by its
  verb, the spinner is a real live probe, and `nika run` paints the DAG
  as **living wire-art in-frame** — states, in-node spinners, edge
  pulses — while `nika inspect --format json|mermaid|dot` becomes the
  ONE graph projector (now projecting declared policy too: `retry` ·
  `timeout` · `on_error` · `outputs`). `nika init` becomes a **founding
  wizard** (recipes, themes, wiring — everything asked before the first
  write) and equips a repo for **15 agent surfaces** project-side,
  Cursor subagents + seatbelt hooks included. The **models come home**:
  `nika model pull/list/rm` (one models dir by construction, resumable
  verified downloads) and `nika model serve` (the sovereign sidecar,
  OpenAI-compatible on loopback) close the local loop — pull → serve →
  workflow infer, trace-chained. `nika check --fix` is an in-binary
  repair loop that converges; the machine dry-run ships one versioned
  plan object; a paused run teaches its exact resume command; registry
  refs run verified (`nika run @org/flow`). The **agents kit becomes a
  suite** — 4 skills · 3 subagents · 5 commands · 3 seatbelt hooks in
  ONE dialect across Claude Code, Cursor and Codex (probe-proven) —
  and the LSP ships **code actions**: every `check --fix` rename lands
  as a quickfix in any editor. Wire waves add claude-desktop, cline,
  continue and qwen (12+ targets).
</Update>

<Update label="v0.99.0" description="2026-07-10 · the MODELS rung · two media builtins graduate · the boundary earns its valve">
  The check ladder earns its **MODELS rung**: every `model:` must resolve
  in THIS binary — a bare id (`gpt-5-turbo`) or a provider the resolver
  cannot drive is a finding with the fix taught in-line, pricing refuses
  to price what cannot resolve (*unpriced beats conjured*), and the MCP
  `nika_check` lane obeys the same law. Two **media builtins graduate**:
  `nika:image_fx` (15 deterministic op families — dither · duotone ·
  halftone · glitch · ascii — over a hand-rolled zero-dep PNG codec, the
  recipe riding the `tEXt` chunk) and `nika:chart` (five chart types
  compiled to byte-identical SVG, parity proven across architectures);
  both artifacts sha256-chain into the trace. **Egress to `outputs`**
  closes the one documented information-flow gap: a sink-only,
  secret-specific declassification of the workflow boundary itself —
  every embedded template now passes its own audit, zero exceptions.
  `nika explain --forecast` computes duration/cost/risk priors from YOUR
  local traces (p50/p90 earned at n ≥ 5 — deterministic stats, never a
  model call). `nika wire` covers **opencode** and **hermes** (8
  targets), the missing-input trap teaches at check time, and the
  release tarball is **funnel-gated** — a stranger's broken first run
  never uploads.
</Update>

<Update label="v0.98.0" description="2026-07-08 · native answers · the checker closes run-fail gaps · one lexer">
  Structured output goes **native per provider** — Anthropic's
  `output_config.format`, Gemini's `responseJsonSchema` (the lossy
  converter dies), OpenAI strict-mode honesty (`not`/`allOf` stripped at
  the wire instead of 400ing) — with a **coercion ladder** that repairs
  case-folded enums, string numbers and singleton arrays before any PAID
  retry. The checker closes gaps that used to fail at run: the compact
  block-sequence **bomb** that aborted every check/run is caught as
  NIKA-PARSE-001, `max_turns` bounds and `for_each` over a typed
  non-array are check-time findings, and `env:` **binds at run** exactly
  as checked. The `${{ }}` scanner becomes its own crate (`nika-tmpl`),
  shared by checker AND runtime — parity by construction. And the first
  30 seconds learn to speak: `nika welcome` mirrors your machine,
  `nika explain <file>` narrates a workflow (cost honesty included),
  `nika init` briefs six agent surfaces, `--max-cost-usd` refuses to
  start when the static floor already exceeds the budget.
</Update>

<Update label="v0.97.0" description="2026-07-07 · the run becomes evidence">
  Every journal line carries a **hash chain** — `nika trace verify` walks
  it and names the first broken link; export and replay check the chain
  before trusting the data. `nika trace reproduce` compares a recorded
  run against a fresh one and classifies every task (reproduced ·
  nondeterministic · authored · environment). The journal **attests its
  engine** (`engine_version` + platform on `workflow_started`). Models
  are **priced before the first run** — 602 rules refreshed from
  models.dev, per-model rates in `check --json` (the VS Code preflight
  shows `$in/$out per 1M` on this tag). `check` IS the dry-run — the
  plan names what dispatches in which wave. `doctor --json` speaks
  machine; bare `nika init`/`new` converse on a terminal; and the dap
  drift warn tells a re-encode from an edit (`workflow_sha256_lf`).
</Update>

<Update label="v0.96.0" description="2026-07-06 · the run becomes a place">
  `nika dap` brings time-travel replay debugging over the run journal —
  breakpoints in your `.nika.yaml`, step forward AND backward, recorded
  outputs in the Variables pane; the VS Code extension's F5 integration
  lights up on this tag. `nika trace export` projects any journal to
  OTLP/JSON lines (Jaeger · Grafana · Langfuse — cost rides
  `gen_ai.usage.cost`). `nika check --json` gains the `requirements`
  section (models · keys · secrets · env) so editors and CI state
  blockers before any token. A typo'd field now teaches: « unknown
  field `infr` — did you mean `infer`? ». Runs record their source
  (workflow\_sha256) and skips say why (when · blocked\_by). Plus:
  doctor --ping v2, strict boolean args, the opt-in CSV
  formula-injection guard.
</Update>

<Update label="v0.95.0" description="2026-07-06 · the catalog practices local-first">
  The 5 local servers (Ollama · LM Studio · llama.cpp · LocalAI · vLLM)
  join `nika catalog` with descriptions, tags and seed models — keyless
  by construction, and sovereign models stay unpriced, never « free ».
  38 providers in the engine's catalog inventory (the canonical spec
  set stays 16). A bare `nika` now suggests the next command
  instead of a wall of help text. Fixes: `nika:write` honors
  `create_dirs: false` loudly, `nika:date` resolves named timezones
  from the bundled db, `nika:log` neutralizes terminal control
  sequences, and the MCP stdio transport bounds its line reads.
</Update>

<Update label="v0.94.0" description="2026-07-06 · the media suite · every run leaves a journal">
  Two media builtins take the stdlib to 25: `nika:image_generate`
  (generation and editing, local-first providers, provenance manifests,
  content credentials preserved) and `nika:tts_generate` (one sovereign
  `/v1/audio/speech` wire · a real deterministic WAV under mock). Every
  run now writes `.nika/traces/` by default and `--task` scopes execution
  to one upstream cone. The catalog rides the wire (`catalog`/`tools   --json` plus their MCP twins — the read-only tool set on protocol
  `2026-07-28`), `cost_usd` rides `task_completed` without ever faking a
  zero, Hugging Face and NVIDIA join the 16-provider canonical catalog,
  and `nika doctor --ping` actually probes the local ports.
</Update>

<Update label="v0.93.1" description="2026-07-05 · the embedded pack teaches 2026 models">
  The pack vendored into the binary carries the qwen3.5 teach-cascade:
  the first `nika examples run 01-hello` of a fresh install works against
  the local models people actually pull in July 2026. Plus the README
  daily-commands block — the full 0.93 user loop in one place.
</Update>

<Update label="v0.93.0" description="2026-07-05 · resume · test harness · local thinking models unbricked">
  Provider-plane HTTP timeout rises to 180s: 2026 open-weight thinking
  models (qwen3.5 · gemma4) no longer die at the cloud-calibrated 30s
  ceiling. `nika run --resume` lands durable-lite resume — the trace IS
  the checkpoint, completed tasks replay as visible cache hits (ADR-099).
  `nika test` golden harness + ADR-098 schema wire selection + the CLI
  verdict card. `nika-cap` admitted (all 12 gates) — 40 of 42 crates.
</Update>

<Update label="v0.92.0" description="2026-07-03 · MCP learning tools · codex wire · exec hardening">
  The MCP oracle grows the learning tools (`nika_schema` ·
  `nika_examples` · `nika_template` · `nika_canon`). `nika wire codex`
  patches `~/.codex/config.toml`; the Claude Code marketplace ships one
  plugin dir for two ecosystems. Exec hardening: provider API keys
  scrubbed from exec children · env keys restricted to POSIX names ·
  browser navigation guarded against private/loopback SSRF.
</Update>

<Update label="v0.91.0" description="2026-06-25 · onboarding wiring · headless builds">
  Explicit onboarding wiring in the CLI · `nika examples run` takes a
  `--model` override with an offline mock hint · headless build fixes
  (xcap backend default-off · atspi 0.29) · doctor recognizes the
  workspace Cursor MCP config · release pipeline separates the dev
  version from brew assets.
</Update>

<Update label="v0.90.0" description="2026-06-21 · the first public release">
  **Diamond's first tagged public release.** CLI binaries for four
  platforms (macOS arm64/x64 · Linux arm64/x64) via Homebrew and the
  install script, cut by the release pipeline on the tag. `nika-cli` and
  `nika-extract` admitted the same morning — the operator surface and the
  9 fetch extract modes. Real semver toward a 1.0.0 public launch —
  quality over speed. Everything before this tag is rewrite history.
</Update>

<Update label="The vertical slice" description="2026-06-10 → 2026-06-21 · 23 crates in twelve days">
  The sprint that turned a foundation into a runnable engine. June 10:
  the kernel splits into four siblings (`core` · `ai` · `runtime` ·
  `plugin`) and the effect crates land — `nika-fs`, `nika-http`,
  `nika-blob`, `nika-exec-runner`, `nika-input`. June 11: `nika-pack`,
  `nika-providers`, `nika-browser`, and **all four verb crates admitted
  the same day** — `infer` · `exec` · `invoke` · `agent`. June 12:
  `nika-runtime` (the DAG scheduler). June 15-18: `nika-lsp`,
  `nika-mcp`, `nika-builtin`, `nika-schema`. June 21: `nika-cli` +
  `nika-extract` — and the v0.90.0 tag ships that evening.
</Update>

<Update label="The language locks" description="May 2026 · the spec goes public · 7 crates climb">
  The month the language reached its final shape, in the open
  [`nika-spec`](https://github.com/supernovae-st/nika-spec) repo
  (Apache-2.0): the `nika: v1` envelope (one field, forever), the four
  verbs locked (`infer` · `exec` · `invoke` · `agent` — everything else
  is a tool under `invoke`), CEL + jq as the only two expression layers,
  agent tools default-deny, and the stdlib curated down to 22 builtins
  with zero capability loss. Meanwhile the climb continued:
  `nika-catalog-codegen` (May 10), `nika-bm25` (May 12), `nika-event` +
  `nika-clock` (May 24), `nika-screen` + `nika-ocr` + `nika-a11y`
  (May 25).
</Update>

<Update label="The foundation hardens" description="2026-04-17 · hygiene vectors · forward-compat seams · telemetry seeds">
  ### Added

  * **4 new hygiene vectors** (30-33): `check-cancel-safety.sh`,
    `check-owned-strings.sh`, `check-unsafe-count.sh`, `check-layer-deps.sh` —
    the suite reaches 33 active vectors.
  * **Forward-compat reservations**: 5 seams pre-planted for the memory
    subsystem + WASM eras: `EmbeddingSpec`, `MemoryFrameRef.trust`,
    `RecallQuery.tenant`, `WasmPluginError::OutOfFuel` +
    `PluginCallContext`, `MemoryLifecycle` trait.
  * **Telemetry seeds**: `SpanGuard.parent_span_id` + W3C Trace Context
    linkage; `Timestamp(i64 unix_ns)` + `WallDuration` in
    `nika-types::timestamp` with RFC 3339 Display.
  * **Test depth**: 14 new proptest properties (TrustLevel lattice
    invariants, ID serde roundtrip); Loom interleaving tests for
    `CancelCtx`; a mutation baseline for `nika-error`.
  * **5 new ADRs**: ADR-029 → ADR-032 + ADR-035 (telemetry seams).

  ### Changed

  * `ObservabilitySink` dropped → 5 sibling channels (Event · Metrics ·
    Trace · Audit · Billing).
  * Engine hygiene enforces RED as fail / YELLOW as suggestion for
    routine pushes.
</Update>

<Update label="v0.80.0-alpha.4" description="2026-04-14 · nika-catalog-verify admitted">
  **Crate admitted:** `nika-catalog-verify` (L4, 600 LOC, 9 tests, all 12
  gates green). The first L4 interface crate: validates all catalog
  TOMLs at build time via `cargo run -p nika-catalog-verify`.
</Update>

<Update label="v0.80.0-alpha.3" description="2026-04-13 · nika-kernel + nika-kernel-mock admitted">
  **Crates admitted:** `nika-kernel` (L0.5) + `nika-kernel-mock` (L0.5).
  40 ISP traits with sealed supertrait discipline. `trait_variant::make`
  for async dynamic dispatch. Pure-memory mocks for hermetic test
  environments. Preludes re-export `nika-types` + `nika-error` types
  for ergonomic downstream imports.
</Update>

<Update label="v0.80.0-alpha.2" description="2026-04-13 · nika-catalog admitted">
  **Crate admitted:** `nika-catalog` (L0). TOML-driven provider + model +
  capability catalog with build-time codegen, perfect-hash lookup, Cow-
  heavy zero-copy types. At admission: 105 MCP servers, 32 LLM providers,
  13 embedding models in the inventory. Schema FK-check enforced in
  `build.rs`.
</Update>

<Update label="v0.80.0-alpha.1" description="2026-04-13 · nika-error admitted">
  **Crate admitted:** `nika-error` (L0). Typed NIKA-XXX error hierarchy,
  miette integration for L4 diagnostics, per-crate error range
  allocation, proptest-backed roundtrip invariants.
</Update>

<Update label="Diamond begins" description="2026-04-13 · the orphan branch · v0.80.0-alpha.0">
  **The rewrite starts.** An orphan branch created from scratch (as
  `nika-diamond`, renamed `main` in May 2026) — zero shared history with
  the brouillon. The constraint that defines everything after:
  every crate must fit in an AI context window. ≤15k LOC per crate,
  ≤1,500 per file, ≤100 lines per function, zero `.unwrap()` in `src/`,
  and 12 admission gates before a crate joins the workspace. First
  admitted crate: `nika-types` (L0 foundation). The versioning policy
  said « forever v0.x » at the time; it was later amended to real semver
  toward 1.0.
</Update>

<Update label="v0.79.3 — the brouillon closes" description="2026-04-09 · 322k LOC · 31 crates · the context lesson">
  The final sprint says everything about the pace: v0.73 → v0.79 in
  three days (April 6-8), v0.79.3 on April 9. Fourteen weeks after the
  first commit, the brouillon engine is a working 322k-LOC, 31-crate
  system — and it has surfaced the lesson Diamond is built on: at that
  scale the biggest correctness risk stops being algorithmic and
  becomes **context**. No human or AI assistant could hold the system
  in working memory, so refactors happened by pattern-match, and
  pattern-match hallucinates. Four days later the rewrite began. The
  era is preserved read-only on the branch that named it —
  `brouillon`, a private archive; nothing ships from it. Diamond
  reads it, then rewrites from scratch.
</Update>

<Update label="The version storm" description="2026-02 → 2026-03 · v0.3 → v0.21 in fifteen days">
  February 18 is the day the language grows teeth: `invoke:` and
  `agent:` land in the AST and the runtime, the MCP client appears,
  and the provider layer learns tool calling — all in one day. Then
  the storm: v0.3 (February 19) → v0.10 (February 25) → v0.17
  (March 2) → v0.21 with a first language server (March 5). March
  alone counts 2,900+ commits — the month the brouillon engine
  became an ecosystem: LSP, security releases, CI/CD, release
  automation. The era even has a public spine: seven crates.io
  releases, 0.20.0 (March 4) → 0.47.1 (March 26) — later yanked,
  listed forever.
</Update>

<Update label="The brouillon era begins" description="2026-01-01 · the first commit">
  **The first commit lands on New Year's Day 2026**: `initial nika v0.1
      with strict templating system` — followed the same week by DAG
  validation, event sourcing for the workflow audit trail, and
  fine-grained executor events. The shape of everything that followed —
  declarative workflows, a DAG, an audit trail — is visible in week
  one. \~4,600 commits follow in fourteen weeks. The era carries the
  name its git branch carries: `brouillon` — the draft.
</Update>

<Update label="The exploration" description="summer 2025 → end 2025 · prototypes before the repo">
  Nika started as a frustration in 2025: useful AI work kept
  disappearing into chat histories. A great run — a research brief, a
  review procedure, a data pipeline — lived and died inside one
  conversation, unrepeatable and unownable. The bet: **durable agent
  work should be source code** — one file you can run, diff, review,
  and keep; local-first; any model; sovereign by default. The idea was
  tested in code from the start — private prototypes through the
  summer and fall of 2025, pre-git and testimony-grade, and the
  [timeline](https://nika.sh/timeline) labels them exactly that. The
  first repo commit followed on January 1, 2026.
</Update>

## Full history

<CardGroup>
  <Card title="CHANGELOG.md" icon="github" href="https://github.com/supernovae-st/nika/blob/main/CHANGELOG.md">
    Every crate admission, every hygiene vector deploy, every ADR
    promotion. Source of truth on the `main` branch.
  </Card>

  <Card title="Commit history" icon="code-commit" href="https://github.com/supernovae-st/nika/commits/main">
    Every commit on the `main` branch: atomic, bisectable,
    Co-Authored-By Nika 🦋.
  </Card>

  <Card title="GitHub Releases" icon="tag" href="https://github.com/supernovae-st/nika/releases">
    Binaries for every tag: macOS arm64/x64 · Linux arm64/x64 ·
    checksums + per-release notes.
  </Card>

  <Card title="Live state" icon="gauge" href="/reference/status">
    Current test counts, clippy, hygiene, admitted crate inventory.
  </Card>

  <Card title="Roadmap" icon="map" href="/changelog/roadmap">
    What's next: the 0.9x hardening train, the contract system and the
    whole Connectome landing before 1.0, the 1.0.0 culmination, 1.x
    minors completing the layered foundation, then the ecosystem tier.
  </Card>
</CardGroup>


# Roadmap
Source: https://docs.nika.sh/changelog/roadmap

Real semver toward 1.0. Quality over speed. The 0.9x train hardens the engine; 1.0 tags when the gates are green.

Nika follows **real semver toward 1.0**. The latest tagged public release is
**v**. 1.0 tags when the release gates are green — never on a
calendar. Features arrive in 1.x minors. Each version is a quality milestone
earned by crate admissions + hygiene vector deploys + ADR promotions.

<Info>
  **Canonical source:** [`ROADMAP.md`](https://github.com/supernovae-st/nika/blob/main/ROADMAP.md)
  on the `main` branch. This page summarises the milestones;
  the full roadmap lives in the repo alongside ADRs. The forward **gates**
  themselves are machine-carried by the spec's
  [timeline](https://nika.sh/timeline) (conditions, never dates) — when a
  gate flips, the record gains a dated, proven entry.
</Info>

## The road so far

| When              | What                                                                                                                                                                                                                                                                                                                                                                 |
| ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Summer → end 2025 | ✧ The exploration — private prototypes before the repo; the idea: durable agent work should be source code — one file, any model, sovereign by default.                                                                                                                                                                                                              |
| 2026-01-01        | ✎ The brouillon era begins — first commit `initial nika v0.1`. Fourteen weeks and \~4,600 commits of private drafting, on the branch literally named `brouillon`.                                                                                                                                                                                                    |
| Feb–Mar 2026      | The version storm: verbs, an MCP client, then a first LSP appear in the brouillon codebase — v0.3 → v0.21 in fifteen days, plus a public crates.io spine (0.20.0 → 0.47.1).                                                                                                                                                                                          |
| 2026-04-09        | v0.79.3 — the brouillon engine peaks at 322k LOC / 31 crates, and teaches the context lesson that motivates Diamond.                                                                                                                                                                                                                                                 |
| 2026-04-13        | **Diamond begins**: ground-up rewrite on an orphan branch. 12 gates per crate, hard caps, zero `.unwrap()`.                                                                                                                                                                                                                                                          |
| May 2026          | The language locks in the open spec: `nika: v1` envelope · 4 verbs · CEL + jq · 22-builtin stdlib.                                                                                                                                                                                                                                                                   |
| 2026-06-10 → 21   | The vertical slice: 23 crates admitted in twelve days — verbs, runtime, LSP, MCP, schema, CLI.                                                                                                                                                                                                                                                                       |
| 2026-06-21        | **v0.90.0 — first public release** (Homebrew + install script, 4 platforms).                                                                                                                                                                                                                                                                                         |
| Since             | The 0.9x train: agent wiring (0.92) · resume + test harness (0.93) · media suite (0.94) · local-first catalog (0.95) · time-travel debugging (0.96) · hash-chained evidence (0.97) · native structured output + the shared `${{ }}` lexer (0.98) · deterministic media artifacts (`image_fx` + `chart`) + the models-resolve audit rung + the `egress` valve (0.99). |

The dated, tagged detail lives on the [Releases](/changelog/releases) page.

## Why real semver toward 1.0

<CardGroup>
  <Card title="1.0 means we stand behind it" icon="circle-check">
    v0.90.0 was the first public release; the 0.9x line is
    release-candidate grade. 1.0 is the usable engine we commit to as a
    stable public API, not a marketing tick. Pre-1.0 the surface is still
    hardening; 1.0 is the line where the public API is stable and
    additive from there.
  </Card>

  <Card title="Quality bar stays high" icon="medal">
    Every crate admits with 12 gates.  crates meet
    that bar today. Admission cadence is set by the quality bar, not a
    calendar — and not by a crate count.
  </Card>

  <Card title="Forward-compat = additive" icon="shield-halved">
    `#[non_exhaustive]` on every public type + pre-planted reservations
    means new features are additive. No breaking change without an
    Accepted ADR. See [forward-compat invariants](/architecture/forward-compat-invariants).
  </Card>

  <Card title="Public accountability" icon="eye">
    All work happens on the `main` branch. Every commit is
    Co-Authored-By Nika 🦋, atomic, bisectable. The engine is the
    changelog.
  </Card>
</CardGroup>

## Current state: v

**&#x20;crates admitted** ·&#x20;**&#x20;lib tests** ·  hygiene vectors ·  ADRs ( Accepted).

Already live today: the four verbs (`infer` · `exec` · `invoke` · `agent`),
`nika run` / `check` / `test` / `trace` / `dap`, the LSP, the MCP oracle,
&#x20;catalog providers, and the embedded language pack.
See [live state](/reference/status) for the authoritative snapshot.

## Milestones

<AccordionGroup>
  <Accordion title="0.9x: the hardening train (now)" icon="train">
    **The current work.** Each 0.9x minor is a complete, diamond-grade
    release; together they close the distance to 1.0:

    * **The remaining L0 slices**: `nika-binding` (types-first slice) and
      `nika-transform`. There is no "last crate": ADR-037 made the count a
      projection (, cap ), so the
      train ends when the gates close, not when a counter fills.
    * **The 7 shadow zones close** (the 1.0 gates): `nika serve` input
      trust · cross-provider structured-output parity · binding taint
      runtime · `for_each` per-element spotlight · L1 taint runtime ·
      NikaError Display parity · the provider parity matrix.
    * **The registry story**: shared workflows re-proven by CI (hash +
      oracle + engine cert) and a client verb to consume them
      (`nika add` — ADR-106, Proposed).
    * **Design-partner hardening**: `1.0.0-rc.N` pre-releases once the
      gates are green, exercised on real workloads before the lock.

    **No date.** The train ships when each release earns its tag.
  </Accordion>

  <Accordion title="The Connectome: sovereign memory, whole, before 1.0" icon="brain">
    **The whole Connectome is a declared pre-condition of the official
    launch** (the timeline's [connectome gate](https://nika.sh/timeline#gates)
    · « lands whole before 1.0 »):

    * `nika-connectome` L2 orchestrator + the L1 memory satellites
      (`nika-hnsw`, `nika-bm25`, `nika-rrf`, `nika-fsrs`,
      `nika-rdfs-reasoner`, `nika-temporal`, `nika-graph-algos`,
      `nika-autodesc-minimal`, `nika-autodesc-full`), admitted through
      the same 12 gates as every crate.
    * Recall and ingest as builtin tools under `invoke:` — never a new
      verb (the 4 verbs are absolute).
    * The zero-LLM write path: memory is written by deterministic code,
      never by a model's output.
    * A sovereign, exportable store on open standards (RDF/SPARQL ·
      ADR-004): yours to query, export, delete.
    * Store digests pinned in receipts, so recall is replayable.

    **Separate count** from the  Diamond horizon: the
    11 memory crates (1 orchestrator + 10 satellites) add on top. No date: gates, not calendars. The
    un-numbered next major stays reserved, its content the operator's
    to declare.
  </Accordion>

  <Accordion title="Built for a hundred years: the standard's machinery, before 1.0" icon="landmark">
    **A standard is judged by what outlives its author.** The
    [hundred-year gate](https://nika.sh/timeline#gates) lands before the
    launch:

    * The NEP door exercised end to end: proposals ratified through it,
      laws and fixtures landing together.
    * The conformance suite in tiers (T0/T1/T2), any engine proving
      itself with the public runner.
    * Every release archived beyond us: Software Heritage, a citable
      DOI, the SWHID cited in the spec.
    * The compatibility promise, published: what a workflow written
      today is guaranteed tomorrow.
    * The deterministic checker, proven in CI: same input, same
      diagnostics, same order.
    * Succession written down: the project survives its maintainer.
  </Accordion>

  <Accordion title="1.0.0: Public API lock" icon="rocket">
    **1.0.0 ships when the gates are green — the culmination, not the
    start.** The contract system, the whole Connectome and the
    hundred-year machinery land first
    (the timeline's gates carry the conditions); the language spec
    (`nika: v1` envelope, Apache-2.0) is already public and stable. 1.0
    is the point where the public API is locked and additive from there,
    enforced by `cargo public-api` + `cargo semver-checks` on every PR.
  </Accordion>

  <Accordion title="1.x minors: the foundation completes, additively" icon="diamond">
    **Arrives across 1.x minors, no breaking changes:**

    * `nika-catalog-sync` shipping catalog freshness (triple-source
      cross-check: LiteLLM + models.dev + OpenRouter corroboration).
    * Sigstore keyless signing on release artifacts.
    * `cargo install nika` — crates.io joins the install matrix.
    * Deeper LSP analysis: full cross-task binding analysis + taint
      propagation warnings + DAG preview.
    * Cross-provider parity expansion as models evolve.

    **No date.** The layered architecture, complete and then extended
    across 1.x minors.
  </Accordion>

  <Accordion title="Ecosystem tier: plugins + observability" icon="box">
    **Target state when shipped:**

    * `nika-wasm-host` (L3) + `nika-sandbox` (L3) admitted.
    * WASM plugin boundary live: community plugins run with fuel
      metering, Trap taxonomy, capability-scoped syscalls.
    * `nika-observability` suite: OTel GenAI semconv bridge (ADR-035),
      Prometheus / StatsD exporters, audit log with tamper-evidence.
    * `nika-policy` L2 shipping Shield policy engine (prompt injection
      classification, taint enforcement).
    * `pck` registry fully live: community workflow packages,
      signature verification, overlay precedence (User > Pck > Core).

    **No date.** Versions stay honest real-semver tags: there is no
    marketing version axis.
  </Accordion>

  <Accordion title="Ongoing" icon="infinity">
    Beyond the ecosystem tier, Nika continues incrementally:

    * Language bindings (`nika-napi`, `nika-py`): rebuild if demand
      materializes (currently deferred per POST\_AUDIT).
    * TUI (`nika-tui`): rebuild in the "Act 3" timeframe if needed.
    * Cross-provider parity expansion as models evolve (GPT-5 family,
      Claude 5, Gemini 3, etc.).
    * Community catalogs (`nika-catalog-cn`, `nika-catalog-eu`) via
      pck admission gates.

    **Real semver.** Additive across minors; the next major stays un-numbered until declared.
  </Accordion>
</AccordionGroup>

## How a release ships

<Steps>
  <Step title="The work earns the tag">
    Crate admissions (12 gates), shadow-zone closures, and field fixes
    accumulate on `main` — every commit atomic and bisectable.
  </Step>

  <Step title="The tag cuts the binaries">
    A `vX.Y.Z` tag triggers the release pipeline: four `nika` binaries
    (macOS arm64/x64 · Linux arm64/x64) + checksums.
  </Step>

  <Step title="The release lands everywhere">
    GitHub Release with curated notes, the Homebrew tap bumps, the
    install script serves the new version.
  </Step>

  <Step title="The changelog tells the story">
    A curated `CHANGELOG.md` section + an entry on
    [Releases](/changelog/releases) (subscribable via RSS).
  </Step>
</Steps>

## Deliberately excluded

<Warning>
  These are not "someday maybe": they are architectural non-goals.
  Re-opening requires a new ADR that supersedes POST\_AUDIT.
</Warning>

* **`nika-sdk`**: 0 consumers, speculative (POST\_AUDIT 2026-04-14).
* **`nika-tui`**: W1 speculative. Maybe Act 3, never before.
* **Proc macros in L0**: Q1 LOCKED. Manual impl + `macro_rules!` forever.
* **`Box<dyn Error>` in public API**: hygiene vector 19 bans.
* **`anyhow::Error` in library code**: ADR-005. Binary only.
* **Plugins as proc macros**: the WASM boundary (ecosystem tier) is the plugin story.

## Governance

<Steps>
  <Step title="Every change has an ADR">
    Significant engineering decisions start as Proposed ADRs, discussed
    in PRs, Accepted or Rejected. See [ADR index](/architecture/adrs).
  </Step>

  <Step title="Every commit is atomic + Co-Authored">
    1 logical change = 1 commit. Co-Authored-By Nika 🦋 always
    (never Claude). Bisectable history is non-negotiable.
  </Step>

  <Step title="Every crate passes 12 gates">
    No late fixes. No partial admissions. See [admission](/architecture/admission).
  </Step>

  <Step title="Forward-compat = additive">
    No breaking change without Accepted ADR. `cargo public-api` +
    `cargo semver-checks` on every PR. See [FCI](/architecture/forward-compat-invariants).
  </Step>
</Steps>

## See also

<CardGroup>
  <Card title="Releases" icon="clock-rotate-left" href="/changelog/releases">
    The full arc, dated and tagged: exploration → brouillon → Diamond.
  </Card>

  <Card title="Timeline" icon="timeline" href="https://nika.sh/timeline">
    The one verifiable record — eras, releases, forward gates; every
    provable claim re-proven in CI.
  </Card>

  <Card title="Live state" icon="gauge" href="/reference/status">
    Where the engine is today.
  </Card>

  <Card title="Constellation" icon="diagram-project" href="/reference/constellation">
    Visual map of every crate across six layers — live admission status.
  </Card>

  <Card title="ADR index" icon="scroll" href="/architecture/adrs">
    Every decision that shapes the roadmap.
  </Card>
</CardGroup>


# Architecture
Source: https://docs.nika.sh/concepts/architecture

Nika is a single Rust binary composed of layered crates, six layers deep plus the L0.5 trait half-layer. Strict downward dependencies, enforced by cargo-deny.

Nika is a single Rust binary (`nika` at **L5**) composed of&#xA;**&#x20;admitted crates** across six layers
(L0 → L5) plus the **L0.5** trait half-layer. Each crate has one job.
Together they parse `.nika.yaml`, resolve templates, route to providers,
execute verbs, and emit a structured event stream.

<Tip>
  **Looking for the authoritative contract?** The [Architecture tab](/architecture/layers)
  holds the curated specs:
  [Layer registry](/architecture/layers) · [Forward-compat invariants](/architecture/forward-compat-invariants)
  · [L0 decisions](/architecture/l0-decisions) · [12-gate admission](/architecture/admission).
  This page orients the concept; those pages are the contract.
</Tip>

## One binary, six layers

```mermaid theme={"system"}
%%{init: {'theme':'dark','themeVariables':{'background':'transparent','mainBkg':'transparent'}}}%%
flowchart BT
  L0["L0 · pure types · zero I/O · sync"]:::z
  L05["L0.5 · kernel traits (async OK)"]:::a
  L1["L1 · effects (fs · http · process · provider impls)"]:::b
  L2["L2 · verbs · services · builtins"]:::c
  L3["L3 · runtime · policy · sandbox"]:::d
  L4["L4 · interfaces · cli · serve · mcp · lsp · sdk"]:::e
  L5["L5 · nika binary (&lt;500 LOC)"]:::f

  L0 --> L05 --> L1 --> L2 --> L3 --> L4 --> L5

  classDef z fill:#1e3a8a,color:#fff,stroke:#3b82f6
  classDef a fill:#6d28d9,color:#fff,stroke:#8b5cf6
  classDef b fill:#065f46,color:#fff,stroke:#10b981
  classDef c fill:#92400e,color:#fff,stroke:#f59e0b
  classDef d fill:#9a3412,color:#fff,stroke:#f97316
  classDef e fill:#991b1b,color:#fff,stroke:#ef4444
  classDef f fill:#4c1d95,color:#fff,stroke:#a78bfa,font-weight:bold
```

Arrows read "built on". The `nika` binary at L5 composes L4 interface
crates, which consume L3 runtime + policy, which orchestrate L2 verbs,
which call L1 effects through L0.5 kernel traits, which use L0
foundation types. **Upward imports are a CI hard failure.**

## Each layer answers one question

| Layer    | Question                                                              | Examples                                                       |
| -------- | --------------------------------------------------------------------- | -------------------------------------------------------------- |
| **L0**   | What shapes does the engine use to talk about itself?                 | `WorkflowId`, `NikaError`, `ModelCapabilities`, `Timestamp`    |
| **L0.5** | What contract does a provider / fs / clock / tool executor implement? | `Provider`, `Fs`, `Clock`, `ToolExecutor`, `MemoryStore`       |
| **L1**   | How do I actually call OpenAI / read a file / run a process?          | `nika-provider-openai`, `nika-fs`, `nika-process`, `nika-http` |
| **L2**   | How do I execute a Nika verb end-to-end?                              | `nika-verb-exec`, `nika-verb-infer`, `nika-verb-agent`         |
| **L3**   | How do I orchestrate a full workflow safely?                          | `nika-runtime`, `nika-shield`, `nika-sandbox` (future minors)  |
| **L4**   | How does a human / tool / IDE talk to Nika?                           | `nika-cli`, `nika-serve`, `nika-mcp`, `nika-lsp`               |
| **L5**   | What's the single entrypoint that wires it all?                       | `nika` binary (\<500 LOC)                                      |

## Why layers matter

<AccordionGroup>
  <Accordion title="Mechanical sorting · no debate" icon="layer-group">
    New crate? Answer the [mechanical sort test](/architecture/layers#mechanical-sort-test)
    in under 10 seconds. No meetings, no "where should this live", no
    spiral into abstraction-first design.
  </Accordion>

  <Accordion title="Trustable L0 · no hidden I/O" icon="shield">
    L0 has **zero I/O, zero async, zero runtime deps**. Your build script
    can safely `use nika_types::*` without pulling in tokio. Property tests
    against L0 types run in milliseconds.
  </Accordion>

  <Accordion title="Swappable effects · test hermetically" icon="rotate">
    Every I/O crate implements a kernel trait with a mock twin. Unit tests
    use `nika-kernel-mock::MockClock`, `MockFs`, `MockProvider`: no
    network, no disk, no wall-clock flakiness. Invariant #27.
  </Accordion>

  <Accordion title="Capped blast radius · per-axis capabilities" icon="explosion">
    Every L1 crate declares its capability axes in
    `docs/architecture/security-axes.toml` (e.g., `net-egress` for HTTP,
    `rw-fs` for filesystem). Silent axis escalation fails CI.
    [12 axes total](/architecture/layers#security-axes).
  </Accordion>
</AccordionGroup>

## What ships at v

**&#x20;crates admitted** past 12 gates:

<CardGroup>
  <Card title="nika-types" icon="cube">**L0** · Foundation value types</Card>
  <Card title="nika-error" icon="triangle-exclamation">**L0** · NIKA-XXX error infra</Card>
  <Card title="nika-catalog" icon="book">**L0** ·  providers ·  rules</Card>
  <Card title="nika-kernel" icon="circuit-board">**L0.5** · 40 ISP traits</Card>
  <Card title="nika-kernel-mock" icon="circuit-board">**L0.5** · Pure-memory mocks</Card>
  <Card title="nika-catalog-verify" icon="check">**L4** · Catalog validation tool</Card>
</CardGroup>

`nika-schema` (parser · analyzer · static check) is admitted and live: it is what `nika check` runs.

[Live constellation →](/reference/constellation) · [12-gate admission →](/architecture/admission)

## The build model

Every crate earns its seat through twelve gates. No exceptions, no late
fixes. One crate = one atomic commit.

<Steps>
  <Step title="SPEC → TDD → IMPL">
    Spec at `docs/crate-specs/<crate>.md` first. Tests red before
    implementation. Minimal code to green.
  </Step>

  <Step title="CLIPPY 0 → MUTATION ≥ 90%">
    Zero clippy warnings. `cargo mutants -p <crate>` kills ≥ 90% of
    generated mutants.
  </Step>

  <Step title="PROPERTY → BENCHMARKS → DOCS">
    Property tests via `proptest` where it matters (parsers, taint,
    crypto). Criterion benchmarks on hot paths. `cargo doc` clean.
  </Step>

  <Step title="CANARY → PARITY → REVIEW → COMMIT">
    End-to-end `.nika.yaml` canary. Golden diff vs legacy (Phase 5+).
    3-agent swarm review. One atomic commit with a gate checklist in the body.
  </Step>
</Steps>

[Full 12-gate spec →](/architecture/admission)

## See also

<CardGroup>
  <Card title="Layers" icon="layer-group" href="/architecture/layers">
    Authoritative layer registry with mechanical sort test.
  </Card>

  <Card title="Forward-compat invariants" icon="shield-halved" href="/architecture/forward-compat-invariants">
    The 8 patterns that keep the public API stable across years.
  </Card>

  <Card title="L0 decisions" icon="list-check" href="/architecture/l0-decisions">
    Q1-Q13: why no proc macros in L0, why sibling sinks not god-trait.
  </Card>

  <Card title="Admission" icon="check-double" href="/architecture/admission">
    The 12 gates with rationale per gate.
  </Card>
</CardGroup>


# Bindings
Source: https://docs.nika.sh/concepts/bindings

Template expressions that move values between tasks. Scoped, typed, taint-tracked, evaluated at runtime.

A **binding** is a template expression wrapped in `${{ … }}`. It resolves
at runtime against a typed scope (the four value authorities, task-scope
bindings, task records) and substitutes into the field. What's inside
`${{ }}` is [CEL](https://cel.dev) (Common Expression Language), the
same expression language GitHub Actions and Kubernetes admission
policies use. Nika does not invent a DSL.

The parser preserves both forms of every templatable field through the
AST: either a literal value or a `Templatable::Template(String)` holding
the unresolved expression. See
`crates/nika-schema/src/types/templatable.rs` for the exact types.

<Info>
  **Two expression layers, locked by the spec:** [CEL](https://cel.dev)
  inside `${{ }}` (conditions + value substitution) and **jq** inside
  `output:` bindings + the `nika:jq` builtin (extraction + transform).
  There are no template filters: anything beyond a reference or a
  boolean is a jq expression or a task. Engine-side, taint propagation
  and typed scope lookup mature across admission rounds; the syntax
  below is the frozen `nika: v1` contract.
</Info>

## Shape

```
${{ <expression> }}
```

Four examples, each a valid `Templatable::Template`:

```yaml theme={"system"}
prompt: "${{ inputs.target }}"
prompt: "${{ with.model_family }}"
command: ["echo", "${{ const.output_dir }}/report.txt"]
with:
  title: ${{ tasks.fetch_issue.output.title }}   # tasks.* lives at the boundary
```

Whitespace inside `${{ }}` is ignored. Nested `${{ }}` is rejected at
parse time.

## The six namespaces

Every binding resolves against one of six named namespaces. The resolver
refuses unknown top-level names at validation time, so `${{ tsaks.foo }}`
is caught before the run starts — and a value-namespace read outside the
closed family (`${{ params.X }}` and friends) refuses `NIKA-VALUES-003`.

| Namespace             | Source                                                                                                                                              | Example              |
| --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------- |
| `inputs.*`            | Typed workflow inputs, declared in the envelope `inputs:` block — supplied by the caller at launch                                                  | `inputs.target`      |
| `config.*`            | Typed non-sensitive runtime config, declared in `config:` — supplied by the deployment, may appear in logs                                          | `config.log_level`   |
| `const.*`             | Named constants declared in `const:` — a fixed value baked into the file                                                                            | `const.output_dir`   |
| `secrets.*`           | Vault/env/file-backed secret references (masked in logs)                                                                                            | `secrets.api_key`    |
| `with.*`              | The task's **data boundary** — per-task `with:` block; each `tasks.*` reference in a value declares a typed edge, the body reads the binding        | `with.model_family`  |
| `tasks.<name>.output` | The result record of a completed task (`.output` · `.status` · `.error` · `.duration_ms` · named bindings) — **boundary surfaces only** (see below) | `tasks.greet.output` |

The first four are the **value authorities** — the closed family every
workflow value is declared under, one role each, no alias. `with` and
`tasks` are the **runtime namespaces**: legal in `${{ }}`, never value
authorities.

`${{ vars.X }}` and `${{ env.X }}` are dead reads (`NIKA-VALUES-001` /
`NIKA-VALUES-002`). Each old use classifies into the authority its role
commands — a typed parameter into `inputs:`, a fixed value into `const:`,
non-sensitive runtime configuration into `config:`, a governed store
reference into `secrets:`. Classification, never a bulk rename: the
question is what the value *plays*, not what it was spelled.

Task names are validated at parse time (`snake_case`, unique). A
binding that references a task not present in the file fails with a
miette diagnostic pointing at the exact byte range.

## The reference boundary: where `tasks.*` may appear

The `tasks` namespace is **boundary-only**. A `${{ tasks.X.* }}` reference
is legal in exactly five places: `with:` values (the binding IS the edge) ·
`after:` keys (the entry names the producer) · `on_error.recover:` (a
fallback reads a settled record) · `on_finally:` blocks (the **parent**
task only) · workflow `outputs:` (the run's exports read the settled
world).

Everywhere else — verb fields (`prompt:` · `command:` · `args:` · …),
`when:`, `for_each:` — a `tasks.*` reference is refused at parse time
(`NIKA-VAR-021`) with a machine-applicable fix: **hoist it into `with:`**
and read the binding.

```yaml theme={"system"}
# ❌ NIKA-VAR-021 — the body reads the global namespace
summarize:
  infer:
    prompt: "Summarize · ${{ tasks.fetch.output }}"

# ✅ the fix `nika check --fix` applies
summarize:
  with:
    article: ${{ tasks.fetch.output }}
  infer:
    prompt: "Summarize · ${{ with.article }}"
```

The task body is a **pure function of its declared inputs** (`with` · the
four value authorities `inputs` · `config` · `const` · `secrets` · the loop
locals): every cross-task dependency is visible at the boundary, named, and
typed by its edge role.

## Typed resolution

Nika knows the expected type of every binding target. If `inputs.count`
is declared `integer` and you drop it into a field typed as a list,
validation fails *before* the run starts.

```yaml theme={"system"}
inputs:
  count:
    type: integer

tasks:
  loop:
    for_each: "${{ inputs.count }}"      # fails — for_each needs a list
    infer:
      model: ollama/<model>     # <provider>/<name>
      prompt: "Iteration ${{ item }}"
```

Type-checking is the analyzer's job, live today in `nika check`
(every deep output reference is validated against its declared shape). The parser's
`Templatable<T>` carries `T` as a phantom type so downstream stages
can't conflate `Templatable<u32>` with `Templatable<bool>`.

## Taint tracking (target design · Phase D)

External data is tainted by default. The taint set is maintained by
the analyzer and propagates through bindings:

* `fetch` output → tainted (HTTP body, third-party controlled).
* `exec` stdout → tainted (subshell could have been influenced).
* `infer` / `agent` output → tainted (prompt injection vector).
* `invoke` output → tainted (MCP servers are third-party).
* `inputs.*` → tainted (caller-supplied at launch).
* `config.*` → tainted (deployment-supplied, from outside the file).
* literals, `const.*`, `secrets.*` → **trusted** (the file owns them).

Integrity is orthogonal to confidentiality: a secret is *trusted* (the
author put it there) and *confidential* (it must not leak). One untrusted
operand taints the whole interpolation.

Passing tainted data to a *privileged sink* (notably `exec.command`)
without an explicit sanitizer raises a `NIKA-SEC`-family error (the
runtime taint layer · [security model](/concepts/security)):

```yaml theme={"system"}
pull_user_input:
  invoke:
    tool: nika:fetch
    args:
      url: https://api.example.com/comment

run_it:
  with:
    comment: ${{ tasks.pull_user_input.output }}
  exec:
    command: ["${{ with.comment }}"]   # NIKA-SEC taint violation · tainted data as the program
```

Fix: never interpolate tainted data into the command position; pass it
as data instead:

```yaml theme={"system"}
run_it:
  with:
    comment: ${{ tasks.pull_user_input.output }}
  exec:
    command: ["tee", "/tmp/comment.txt"]
    stdin: "${{ with.comment }}"   # data channel, not code channel
```

Taint is a property of **data**, not of a principal (T3:A design from
`InferResponse.trust_level`). Cross-link: ADR-014 (sealed kernel
traits), `nika-error::trust::TrustLevel`.

## The expression language: CEL, one small subset

What's inside `${{ }}` is the **v0.1 CEL subset**
([normative grammar](https://github.com/supernovae-st/nika-spec/blob/main/spec/03-dag.md)):

| Form         | Example                                                          |
| ------------ | ---------------------------------------------------------------- |
| Field access | `inputs.topic` · `tasks.build.status`                            |
| Index access | `tasks.list.output[0]` · `obj['key-with-dash']`                  |
| Comparison   | `==` `!=` `<` `<=` `>` `>=`                                      |
| Boolean      | `&&` `\|\|` `!`                                                  |
| Membership   | `status in ['success', 'skipped']`                               |
| Size         | `size(items) > 0` · the one v0.1 function, the empty-check idiom |
| Literals     | `true` · `42` · `3.14` · `'str'` · `null`                        |
| Grouping     | `( … )`                                                          |

There are **no template filters** (`\| upper`, `\| truncate`, …). Anything
that transforms data is a **jq expression**, in an `output:` binding or
through the `nika:jq` builtin. Two layers, one job each:

```yaml theme={"system"}
# CEL decides · jq transforms
digest:
  with:
    items: ${{ tasks.fetch.output }}             # the binding IS the edge
  when: ${{ size(with.items) > 0 }}              # CEL · condition (local read)
  invoke:
    tool: "nika:jq"
    args:
      input: "${{ with.items }}"                 # CEL · reference
      expression: ".items | map(.title) | join(\"\\n\")"   # jq · transform
```

CEL macros and string functions are reserved for later minors: growth
is additive, never breaking.

## Multi-line

YAML block scalars compose cleanly with bindings (the pull-request fields
crossed the boundary in `with:`; the prompt reads the bindings):

```yaml theme={"system"}
review:
  with:
    title: ${{ tasks.fetch_pr.output.title }}
    body: ${{ tasks.fetch_pr.output.body }}
  infer:
    prompt: |
      You are reviewing the following pull request.

      Title: ${{ with.title }}
      Body:  ${{ with.body }}

      Provide three concrete improvements.
```

The parser preserves indentation and line breaks: the prompt reaches
the provider exactly as you typed it, minus the leading YAML block
indentation.

## Null handling

Defaults live in declarations, not in expressions. Which declaration
depends on who owns the value:

```yaml theme={"system"}
inputs:
  topic:
    type: string
    required: true         # the caller MUST supply it · validated before anything runs
  tone:
    type: string
    default: "neutral"     # the caller MAY override it from the CLI
const:
  house_style: "sober"     # nobody overrides it · the file owns it
```

If `inputs.optional_field` is required and the caller supplies nothing,
the run is refused before it starts: a miette diagnostic points at the
declaration site and the usage site.

## What bindings are **not**

* ❌ Not a scripting language. No loops, no conditionals inside `${{ }}`.
* ❌ Not arbitrary JavaScript / Python eval. No dynamic code.
* ❌ Not Jinja2 / Liquid in full: `for` and `if` blocks are **not**
  supported inside expressions.
* ✅ Scope lookup + CEL evaluation + type check + taint propagation.

Workflow-level control flow (`for_each:`, `when:`, the `with:` /
`after:` edges) lives on the **task envelope**, not inside bindings.
This is deliberate: the DAG is a static artifact, inspectable by the
analyzer and renderable by any graph surface — `nika inspect <file> --format mermaid|dot|json`; bindings are local decorations.

## Related ADRs

* **ADR-010**: miette as the L4 diagnostic presentation layer. Every
  binding error points at the exact byte range in the source file.
* **ADR-014**: sealed kernel traits. The resolver runs at L3 and never
  crosses into arbitrary user-provided evaluator code.
* **ADR-021**: YAML envelope convention. `${{ }}` bindings appear
  inside `spec:` (workflow) or inside reusable skill / agent documents,
  and resolve against the same scope shape.

## Read next

<CardGroup>
  <Card title="Events" icon="signal" href="/concepts/events">
    What gets emitted, when.
  </Card>

  <Card title="Workflows" icon="diagram-project" href="/concepts/workflows">
    The envelope that holds the `tasks:` bindings operate on.
  </Card>

  <Card title="Verbs" icon="play" href="/concepts/verbs">
    Each verb's taint classification and sanitizer expectations.
  </Card>

  <Card title="YAML reference" icon="file-code" href="/reference/yaml-syntax">
    Full binding grammar and filter catalog.
  </Card>
</CardGroup>


# Events
Source: https://docs.nika.sh/concepts/events

Five observability channels. Every run emits typed events, metrics, traces, billing records, and append-only audit entries.

Every Nika run emits a structured stream of **events**. One event is one
`Event` struct from `nika-kernel::infra::event_sink`, carried as one
line of NDJSON on stdout (or any other sink you wire in). Events are
deterministic, typed, and carry source IDs that correlate to the trace
stack.

The observability surface has **five sibling channels**, each a separate
kernel trait, so impls can be swapped, sampled, or persisted
independently:

| Channel | Trait             | Semantics                                                           |
| ------- | ----------------- | ------------------------------------------------------------------- |
| Events  | `EventSink`       | Structured telemetry. **May be sampled or dropped** under load.     |
| Metrics | `MetricsExporter` | Counters / histograms. Aggregated, low-cardinality.                 |
| Traces  | `TracerProvider`  | W3C-compatible spans. Sampled per-head.                             |
| Billing | `BillingSink`     | Token + cost ledger. **Never dropped, never sampled.**              |
| Audit   | `AuditSink`       | Append-only, persist-or-fail. Compliance (GDPR, EU AI Act, Shield). |

<Info>
  `nika run --json` streams the local event lane today. The kernel traits
  (`EventSink`, `AuditSink`, `BillingSink`, `MetricsExporter`, and
  `TracerProvider`) keep the interface stable while HTTP/SSE/OTLP exporters
  remain future interface work.
</Info>

## `Event` shape

```rust theme={"system"}
#[non_exhaustive]
pub struct Event {
    pub id: EventId,                    // ULID
    pub run_id: RunId,                  // ULID of the current run
    pub trace_id: Option<TraceId>,      // W3C trace context
    pub kind: String,                   // e.g. "task.started"
    pub timestamp_ms: u64,              // Unix epoch milliseconds
    pub payload: serde_json::Value,     // kind-specific fields
}
```

Source: `crates/nika-kernel/src/infra/event_sink.rs`. Every event shares
`id`, `run_id`, `kind`, and `timestamp_ms`; `payload` shape depends on
the `kind` discriminator.

## `EventSink` trait (L0.5)

```rust theme={"system"}
#[trait_variant::make(EventSinkDyn: Send)]
pub trait EventSink: Send + Sync + crate::sealed::Sealed {
    async fn emit(&self, event: Event) -> Result<(), NikaError>;
}
```

**Cancel-safety contract** (from the source): impls MUST NOT maintain
cross-emission state. Dropping a future mid-emit is semantically
identical to a sampled-away event. Batched sinks flush on a separate
task that owns the batch: the `emit` call itself is atomic or
all-nothing.

The trait is `Sealed` (ADR-014): external crates cannot implement it
directly; they route through the workspace-controlled adapter path.

## Event kinds

Every kind is emitted from **exactly one call site** in the codebase
(INV-024). No ambiguous duplicates: if you see `infer.chunk` on the
wire, you know exactly which crate produced it.

### Workflow-level

* `workflow.started`: a run begins.
* `workflow.completed`: run ends, with status.
* `workflow.skipped`: the run was gated off before any task started.

### Task-level

* `task.started`: a task begins executing.
* `task.completed`: a task ends successfully.
* `task.failed`: a task errored out; payload carries the typed error (`code` · `category` · `transient` · the spec error shape). On the wire the engine's event slugs are snake\_case (`task_failed`). The dot-form here is the documentation vocabulary.
* `task.skipped`: the task's `when:` evaluated to false (or its empty
  `for_each` collection skipped it).
* `task.cancelled`: the task never ran because its default gate became
  unsatisfiable (an upstream failed) or the run was cancelled (a normal
  terminal state under gate-based propagation).
* `task.retry`: a retry attempt begins (emitted before `task.started` of the retry).

### Verb-level

From `nika-kernel::provider::InferEvent`:

* `infer.delta`: streaming text chunk (`Delta { text }`).
* `infer.tool_use_start`: agent called a tool (`ToolUseStart { id, name }`).
* `infer.tool_use_delta`: streaming partial JSON input (`ToolUseDelta { id, partial_json }`).
* `infer.thinking`: extended thinking chunk (`Thinking { text }`).
* `infer.usage`: token usage update (`Usage(TokenUsage)`).
* `infer.done`: stream completed (`Done { stop_reason, request_id, finish_reason_raw }`).

From the other verbs:

* `fetch.request`: HTTP request sent.
* `fetch.response`: HTTP response received.
* `exec.output`: a line of stdout/stderr.
* `invoke.call`: tool invoked.
* `invoke.result`: tool returned.
* `agent.iteration`: one loop turn completed.

### Meta

* `checkpoint`: serializable snapshot (`AgentCheckpoint`, used for resume).
* `taint.violation`: binding crossed a taint boundary (mirrors `AuditRecord::TaintViolation`).
* `budget.warning`: nearing a `BudgetDirective` ceiling.
* `budget.exceeded`: budget hard-stop triggered.

## OTel `GenAI` semconv bridge (Q13)

Every `InferRequest` and `InferResponse` carries a `GenAiAttrs` struct
that maps directly to the OpenTelemetry `gen_ai.*` semantic conventions:

```rust theme={"system"}
#[non_exhaustive]
pub struct GenAiAttrs {
    pub system: GenAiSystem,             // anthropic | open_ai | google | …
    pub operation: GenAiOperation,       // chat | embedding | image_generation | …
    pub response_id: Option<String>,     // gen_ai.response.id
    pub response_model: Option<String>,  // gen_ai.response.model
    pub encoding_formats: Vec<String>,   // gen_ai.request.encoding_formats
    pub conversation_id: Option<String>, // gen_ai.conversation.id
    pub agent_id: Option<String>,        // gen_ai.agent.id
    pub agent_name: Option<String>,      // gen_ai.agent.name
}
```

Source: `crates/nika-kernel/src/ai/genai.rs`. This enforces
**cross-provider parity** (Pre-launch Gate 2): no provider can silently
drop an attribute the kernel exports. When Nika emits an `infer.done`
event, the `payload.gen_ai` block is identical in shape across all
&#x20;providers.

Cross-link: [OTel GenAI spec](https://opentelemetry.io/docs/specs/semconv/gen-ai/).

## `AuditSink`: the fifth channel (Q12)

`AuditSink` is **separate** from `EventSink`. Audit records are
**append-only, persist-or-fail**: they MUST persist durably (fsync on a
local log, synchronous HTTP POST to an append-only endpoint) before the
trait method returns `Ok`. Buffering in memory is forbidden by contract.

```rust theme={"system"}
#[non_exhaustive]
pub enum AuditRecord {
    CapabilityOverride { tenant_id, capability, reason },
    TaintViolation    { tenant_id, path, severity },
    CanaryLeaked      { tenant_id, canary_id },
    BudgetExhausted   { tenant_id, dimension, cap, observed },
    PolicyDenied      { tenant_id, rule_id, target },
    KeyUsed           { tenant_id, key_id },
    SecretRedacted    { tenant_id, location },
    Extension         { ns, name, payload },   // forward-compat escape hatch
}
```

Every variant carries a `TenantId` for multi-tenant routing. `Extension`
is the forward-compat path (ADR-028): new categories land there first
and get promoted to a first-class variant once the namespace stabilises.

Severity is separate: `Info`, `Warn`, `Critical`. A `TaintViolation`
with `Severity::Critical` should kill the run; a `CapabilityOverride`
with `Severity::Info` is an operator trail, not a failure.

<Note>
  `AuditSink` replaced an earlier `ObservabilitySink` design during the
  Q12 L0.5 architecture sweep (locked 2026-04-16, see
  `docs/architecture/l0-l05-architecture-decisions.md`). The separation
  matters: telemetry is best-effort; audit is compliance. Different
  persistence guarantees, different failure modes, different sinks.
</Note>

## `BillingSink`: the ledger (separate trait)

Token + cost accounting uses its own trait because it has different
dropping semantics than `EventSink`. Billing records are **never
dropped**. Implementations persist on every call and surface failures
to the caller, who kills the run if persistence fails (revenue
integrity > workflow liveness).

See `nika-kernel::infra::billing::BillingSink` + ADR-028 §4.

## Telemetry seams (ADR-035)

Two reservations on the trace layer make the kernel OTel-ready without
breaking any v0.8x caller:

1. `SpanGuard.parent_span_id: Option<SpanId>`, an explicit parent link so
   nested spans can be stitched into a tree without a thread-local
   stack (which tokio's multi-thread runtime breaks).
2. `SpanRef { trace_id, span_id }`, a copyable handle that propagates
   span identity across `tokio::mpsc` boundaries and spawned tasks
   without cloning the full `SpanGuard`.

Both land as additive, `#[non_exhaustive]` extensions. In a future minor they
bridge zero-copy into OTel's `SpanContext` when
`nika-observability-otel` admits.

## Enable the stream (target CLI)

```bash theme={"system"}
nika run workflow.nika.yaml --json             # stdout NDJSON
nika run workflow.nika.yaml --json > run.log   # file
```

The CLI JSON lane is live. HTTP/SSE/OTLP export belongs to the future
`nika-serve` interface; today the local binary owns the run stream.

## Why five channels, not one

Because they have incompatible guarantees:

* **Events** want volume + sampling. Dropping is fine.
* **Metrics** want aggregation + low cardinality. Pre-aggregated.
* **Traces** want causal structure + head sampling.
* **Billing** wants durability + no drops. Every token metered.
* **Audit** wants persist-or-fail + append-only. Compliance contract.

Forcing them through one sink loses either the sampling headroom (makes
the hot path slow) or the compliance contract (drops records under
load, fails the audit).

## Related ADRs

* **ADR-021**: YAML envelope. `EventSink` emits events that correlate
  to tasks inside `spec.tasks`, tagged with the workflow's `metadata.name`.
* **ADR-028**: forward-compat reservation policy. `Extension` variants
  in `AuditRecord` + `StopReason::Unknown(String)` in `InferResponse`.
* **ADR-035**: telemetry seams (SpanGuard parent + SpanRef).

## Read next

<CardGroup>
  <Card title="Event source" icon="file-code" href="https://github.com/supernovae-st/nika/blob/main/crates/nika-event">
    The `nika-event` crate: every kind + payload schema in source.
  </Card>

  <Card title="Providers" icon="server" href="/concepts/providers">
    How the unified `InferEvent` stream maps to  providers.
  </Card>

  <Card title="Bindings" icon="link" href="/concepts/bindings">
    Reading `tasks.<id>.events` from other tasks.
  </Card>

  <Card title="Architecture" icon="layer-group" href="/concepts/architecture">
    L0.5 kernel traits the observability channels live in.
  </Card>
</CardGroup>


# How Nika compares
Source: https://docs.nika.sh/concepts/how-nika-compares

An honest map of where Nika fits next to LangGraph, Temporal, GitHub Actions and the agent frameworks: what it does that they do not, and what they do that it does not.

Most orchestrators plan. Nika sits under them: a plain-text file your agent, cron or CI can hand the repeatable slice of the work to, checked before a single token is spent and verifiable after it runs. This page is an honest map, including the places where the other tools win.

## The one thing that is different

Nika is the only one where you can **audit a workflow before you run it**. `nika check` reads the file statically and tells you the plan, an honest cost floor, which secrets flow into which step, and the permits boundary, before anything executes. Every run then leaves a hash-chained trace that `nika trace verify` confirms or breaks. The receipt comes from the runtime, never from a model's prose.

That is a property of the whole design (one static Rust binary, a frozen language, local-first), not a feature bolted on. It is what the rest of this page is measured against.

## Where Nika fits

<table>
  <thead>
    <tr><th>You want to...</th><th>Reach for</th></tr>
  </thead>

  <tbody>
    <tr><td>Turn a repeated AI job into a reviewable, diffable file</td><td><strong>Nika</strong></td></tr>
    <tr><td>Know what a workflow will cost and touch before it runs</td><td><strong>Nika</strong> (no other tool checks cost and secret flows statically)</td></tr>
    <tr><td>Run AI work locally, offline, with no keys</td><td><strong>Nika</strong> (mock and Ollama paths), or a local framework</td></tr>
    <tr><td>Build a long-lived, distributed, durable-execution system</td><td><strong>Temporal</strong>, DBOS, Restate</td></tr>
    <tr><td>Write agent logic as code with a visual graph</td><td><strong>LangGraph</strong>, Mastra</td></tr>
    <tr><td>Orchestrate repos, runners and services in CI</td><td><strong>GitHub Actions</strong>, Argo</td></tr>
    <tr><td>An autonomous coding agent in your editor</td><td><strong>Cursor</strong>, Claude Code, Continue.dev</td></tr>
  </tbody>
</table>

They orchestrate infra, services and code. Nika is the file for the AI-native slice, and it runs happily **inside** any of them: there is a [GitHub Action](https://github.com/supernovae-st/nika-action) that posts the check verdict on your PRs.

## Where Nika is honestly weaker

We publish this because a comparison that only lists wins is marketing, not a map.

* **No IDE chrome.** Cursor and Continue.dev win for in-editor UX. Nika ships a VS Code extension for `.nika.yaml` (syntax, a DAG view, diagnostics), but it is not an agentic editor.
* **No visual workflow builder.** LangGraph has a graph UI. Nika draws the DAG (`nika graph`) but you author in YAML and CLI.
* **No enterprise durable-execution track record.** Temporal has a decade of battle-testing for long-lived distributed state. Nika is a finite single-run DAG, one file in, one run out. Different problem.
* **Younger, smaller community.** LangGraph and Cursor have far larger ecosystems today.
* **Non-interactive by design.** A Nika run does not stop to ask questions mid-flight. That is the contract that makes it repeatable; it also means it is not a chat.

## Where Nika is honestly stronger

* **Check before run.** The static audit (plan, types, cost floor, secret flows, permits) exists in no other tool in this list. You spend zero tokens to learn a workflow is broken or expensive.
* **Receipts, not vibes.** The hash-chained trace is tamper-evident: verify exits clean or names the first altered link. Editable, lossy chat logs cannot make that claim. The underlying pattern is tool-neutral — [run receipts](/patterns/run-receipts) — and worth adopting even without Nika.
* **One static binary.** The same file is a runner, a checker, a golden-test harness, an MCP server, an LSP, and a time-travel DAP debugger. No runtime to stand up, no cluster.
* **The file is portable.** A Nika workflow is text bound to no framework: any conformant engine runs it. Your logic is not locked to one vendor's Python graph.
* **Sovereign by construction.** AGPL engine, Apache-2.0 spec, local-first, no mandatory cloud, sixteen providers you pick from.

## The honest bottom line

If you need durable distributed execution, use Temporal. If you want an agentic IDE, use Cursor. If your agent logic is genuinely code, use LangGraph. If you want the repeatable, budgeted, auditable slice of AI work to live in a file you can review before it spends and verify after it runs, that is Nika, and it composes with all of the above rather than replacing them.

<Note>
  Try the difference in two commands, offline, no keys:

  ```bash theme={"system"}
  brew install supernovae-st/tap/nika
  nika try 01-hello
  ```
</Note>


# Providers
Source: https://docs.nika.sh/concepts/providers

The canonical provider catalog — local-first (plus a wider engine catalog) behind one unified InferRequest. Switch provider = change one field.

Two provider numbers exist, on purpose: the **language spec** locks&#xA;**&#x20;canonical providers** (what a conformant engine MUST
ship · see the [spec catalog](https://github.com/supernovae-st/nika-spec/blob/main/stdlib/providers-v0.1.md));
the **reference engine's catalog** goes wider. Nika ships with&#xA;**&#x20;LLM providers** in its catalog,
orchestrated behind one unified `InferRequest`. The `infer:` verb takes a
`model: <provider>/<name>` string, looks up capability rules
([ rules](/reference/capabilities)), and dispatches
through the right API dialect.

<Tip>
  **Full inventory with env vars and default models:** [Providers catalog](/reference/providers-catalog).
  This page explains the design: why a single `InferRequest` works across
  &#x20;providers.
</Tip>

## One `InferRequest` for all providers

```rust theme={"system"}
#[non_exhaustive]
pub struct InferRequest {
    pub provider: ProviderId,          // e.g., "anthropic", "openai", "moonshot"
    pub model: ModelId,                // e.g., "claude-sonnet-4-6"
    pub messages: Vec<Message>,
    pub response_format: Option<ResponseFormat>,
    pub tools: Vec<ToolSpec>,
    pub temperature: Option<f32>,
    pub top_p: Option<f32>,
    pub max_tokens: Option<u32>,
    pub stream: bool,
    // reserved for future minors: memory, budget, baggage, trust_level, trace_id
}
```

Every L1 provider crate (`nika-provider-anthropic`, `nika-provider-openai`,
`nika-provider-gemini`, …) implements the single `Provider` trait from
`nika-kernel`:

```rust theme={"system"}
#[trait_variant::make(ProviderDyn: Send)]
pub trait Provider: sealed::Sealed + Send + Sync + 'static {
    async fn infer(&self, req: &InferRequest) -> Result<InferResponse>;
    async fn stream(&self, req: &InferRequest) -> Result<InferStream>;
    fn capabilities(&self, model: &str) -> ModelCapabilities;
    fn provider_id(&self) -> &'static ProviderId;
}
```

Switching provider is **one line** in YAML:

```yaml theme={"system"}
tasks:
  first:
    infer:
      model: ollama/llama3.2:3b            # <provider>/<name> · swap to mistral/… · anthropic/… · gemini/…
      prompt: "Hello."
```

## API dialects (7)

Providers speak 7 distinct dialects. One provider crate per dialect + an
OpenAI-compatible family that covers 23 providers.

| Dialect       | Providers                                                                                                                                                                                                                   | Notes                                                                                             |
| ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
| `openai-chat` | openai, mistral, groq, deepseek, xai, openrouter, together, fireworks, cerebras, sambanova, perplexity, moonshot, qwen, minimax, zhipu, nvidia-nim, deepinfra, replicate, hyperbolic, writer, databricks, azure, cloudflare | 23 providers share OpenAI's `/v1/chat/completions` shape with per-provider base URL + auth header |
| `anthropic`   | anthropic                                                                                                                                                                                                                   | Native Messages API, tool use as schema, extended thinking                                        |
| `gemini`      | gemini, vertex                                                                                                                                                                                                              | Native `generateContent` API, safety settings, structured output via `response_schema`            |
| `cohere`      | cohere                                                                                                                                                                                                                      | Native Command API                                                                                |
| `ai21`        | ai21                                                                                                                                                                                                                        | Native Jamba API                                                                                  |
| `bedrock`     | bedrock                                                                                                                                                                                                                     | AWS SigV4, model-prefix routing (`anthropic.claude-...`)                                          |
| `voyage`      | voyage                                                                                                                                                                                                                      | Embeddings-only                                                                                   |

<Note>
  **In-process runner:** `nika-infer-local` is the sovereign local
  sidecar (candle-based, per ADR-091): quantized generation without an
  external server. Most users take the simpler path first: a local server
  (Ollama, LM Studio, llama.cpp, vLLM) per the [local models
  guide](/guides/local-models).
</Note>

## Capability-aware routing

Every `InferRequest` is routed through **capability rules** before
dispatch. The rules decide:

* What **modalities** the model accepts (text / image / audio / pdf / …).
* Whether **tool calling** + **parallel tool calls** are supported.
* Whether **JSON mode** is `unavailable` / `object` / `schema`.
* Whether **streaming** is native or emulated.
* Whether **prompt caching** / **context caching** reduces cost.
* Which **supported parameters** are legal (reasoning-effort, thinking-
  budget, computer-use, citations, …).

<Check>
  If you send `tools: [...]` to a model whose capability rule says
  `tool_calling = false`, Nika fails fast with `NIKA-13x` before hitting
  the network: no silent provider-side error.
</Check>

See [Capability rules](/reference/capabilities) for the full resolution
algorithm (defaults → scan rules in file order → apply matches).

## Structured output · the engine picks the wire (ADR-098)

A task's `schema:` is the single authored contract — there is no `json:
true` sugar and no per-provider knob. The engine decides, per run, how to
honor it on the wire the model speaks:

* **Fully-specified schema** (every `object` has `properties`, every
  `array` has `items`): forwarded verbatim to the provider's strict
  structured mode where the wire has one.
* **Underspecified schema** (any node typed `object` without `properties`,
  or `array` without `items` — the honest shape for "return the same
  free-form JSON, transformed"): strict mode would reject it with an
  HTTP 400, so the engine requests the provider's **native JSON mode**
  instead, steers the shape through the prompt instruction, and validates
  the reply **locally** against your schema, with bounded retry.
* **Wire with no native JSON mode** (the anthropic dialect): the prompt
  instruction carries the shape; the same local validation applies.
* **The mock wire** receives the schema verbatim and *synthesizes* a
  conformant instance — this is what lets every schema workflow run
  offline under [`nika test`](/guides/testing).

Local validation is the constant enforcement floor across **all** wires:
the provider's strict mode is an optimization, never the guarantee. You
write the schema you mean; the engine picks the wire that can honor it.

## Fallback chains (target design)

When a provider fails, Nika can route to a fallback:

```yaml target design · a future minor theme={"system"}
tasks:
  primary:
    infer:
      model: ollama/llama3.2:3b            # <provider>/<name> · local first
      prompt: "..."
    fallback:
      - { model: mistral/mistral-large }
      - { model: anthropic/claude-sonnet-4-6 }
```

<Warning>
  `fallback:` is reserved in the kernel DTO but not yet parsed at v.
  Model fallback chains need a separate runtime policy gate before they become
  user-facing syntax.
</Warning>

## Why  and not 9

<Info>
  Earlier drafts of this page listed 9 providers. That was a snapshot from
  mid-2025. Today's catalog is -deep, covering frontier
  cloud labs, fast-inference shops (Groq, Cerebras, SambaNova), Chinese
  labs (Moonshot, Qwen, MiniMax, Zhipu), enterprise platforms (Bedrock,
  Azure, Vertex), and niche (Voyage embeddings, Writer enterprise).
  Source of truth lives in the TOML and is build-time validated.
</Info>

## Adding a new provider

<Steps>
  <Step title="Add a `[[providers]]` block to `llm-providers.toml`">
    Declare `id`, `name`, `aliases`, `env_var`, `key_prefixes`,
    `default_model`, `cheap_model`, `api_dialect`, `tags`, and at least
    one `[[providers.models]]` sub-block.
  </Step>

  <Step title="Add capability rules if the provider has unique features">
    Put rules in `model-capabilities.toml` scoped via `scope.providers`.
    Inherit defaults if the provider is standard (most openai-chat
    providers need no rules).
  </Step>

  <Step title="Implement the L1 provider crate">
    If the `api_dialect` already exists, wire a new provider instance
    with the correct base URL + auth. If new dialect, new L1 crate
    `nika-provider-<name>`.
  </Step>

  <Step title="Pass the engine's admission checklist">
    Property test against the provider's API contract. Criterion bench for
    token throughput. Capability parity test. [How admission works →](/architecture/admission).
  </Step>
</Steps>

## See also

<CardGroup>
  <Card title="Providers catalog" icon="list" href="/reference/providers-catalog">
    All  providers with env vars, default / cheap models, dialects.
  </Card>

  <Card title="Capability rules" icon="grid" href="/reference/capabilities">
    Resolution algorithm and -rule contract.
  </Card>

  <Card title="Concepts · Verbs" icon="play" href="/concepts/verbs">
    The `infer:` verb and its three siblings (exec / invoke / agent) · fetch is the `nika:fetch` builtin under `invoke:`.
  </Card>

  <Card title="L0 decisions" icon="list-check" href="/architecture/l0-decisions">
    Why capability rules use prefix matching, not regex (Q1).
  </Card>
</CardGroup>


# Security model
Source: https://docs.nika.sh/concepts/security

What protects a Nika workflow: SSRF defense on by default, a shell blocklist, taint-tracked trust levels, typed security errors, and a hardened Rust supply chain.

Workflows run attacker-influenced inputs by nature: they fetch URLs,
shell out, and feed model output into tools. Nika's position is that the
**mechanism must be safe before policy makes it configurable**: the
dangerous primitives ship hardened by default, and a violation is a
typed `NIKA-SEC-*` error your workflow can read, not a stack trace.

## The threat model in one table

| You write            | The attacker controls                       | The defense                                   |
| -------------------- | ------------------------------------------- | --------------------------------------------- |
| `invoke: nika:fetch` | the URL (or a page that redirects)          | 3-layer SSRF defense, on by default           |
| `exec:`              | argument values flowing from upstream tasks | shell blocklist + data-channel pattern        |
| `infer:` → tool use  | the fetched content the model reads         | trust levels + spotlight + injection scanning |
| `secrets.*` bindings | log access                                  | masked at the binding layer, never logged     |

## Permits — declare the blast radius

On top of the hardened mechanisms, a `permits:` block makes the file
itself declare its blast radius. Four families, one shape:

```yaml theme={"system"}
permits:
  fs:
    read: ["./data/**"]        # paths tasks may read
    write: ["./out/**"]        # paths tasks may write
  net:
    http: ["api.github.com"]   # hosts nika:fetch may reach
  exec: ["git", "wc"]          # programs exec: may run (false · true · allowlist)
  tools: ["nika:*"]            # tool ids invoke:/agents may call
```

Two laws govern it:

1. **No `permits:` block → the engine floor only.** The hardened
   defaults below (SSRF defense, shell blocklist, secret masking)
   apply — nothing else is restricted.
2. **Any `permits:` block → default-deny for the whole file.** Anything
   not listed is refused. A task reaching beyond the boundary is caught
   by `nika check`, statically — `NIKA-SEC-004`, with the exact fix —
   and the same boundary is enforced again at run time.

You never have to write it by hand: `nika check --infer-permits`
computes the tightest boundary the file actually needs and prints it,
ready to paste. The SSRF floor below stays on **regardless** of
permits — a permitted host still cannot bounce into private space.

<video>
  <source type="video/webm" />

  <source type="video/mp4" />
</video>

## SSRF defense (on by default)

`nika:fetch` refuses to be bounced into private space. Three layers,
verbatim from the engine (`nika-http`):

<Steps>
  <Step title="Static checks (pure)">
    Scheme allow-list (`http`/`https` only), blocked hostnames
    (`localhost`, cloud metadata), literal-IP range checks: loopback,
    RFC 1918, link-local/metadata (`169.254.169.254`), CGN, IPv6 local
    ranges, v4-mapped v6.
  </Step>

  <Step title="DNS resolution check">
    Non-literal hosts are resolved and **every address** is
    range-checked: this kills decimal-IP tricks (`http://2130706433/`)
    and public names that resolve to private addresses.
  </Step>

  <Step title="Per-hop redirect re-check">
    Client-level redirects are disabled; the engine follows redirects
    itself and re-runs layers 1+2 on **every hop**. A public host
    cannot 302 the client into your VPC.
  </Step>
</Steps>

Response sizes are capped (64 MiB default) and self-signed TLS is
rejected by default. Private-network access is opt-in configuration,
never the default.

## exec: the data-channel rule

`exec` in shell mode runs every command against a blocklist before
spawn. But the structural defense is in how you write workflows:
**tainted data goes through data channels, never code channels**.

```yaml theme={"system"}
# ❌ tainted output interpolated into the argv
bad:
  with:
    comment: ${{ tasks.fetch_comment.output }}
  exec:
    command: ["echo", "${{ with.comment }}"]

# ✅ tainted output passed as data
good:
  with:
    comment: ${{ tasks.fetch_comment.output }}
  exec:
    command: ["tee", "/tmp/comment.txt"]
    stdin: "${{ with.comment }}"
```

Passing tainted data to a privileged sink without going through a data
channel raises a typed taint violation: taint is a property of the
**data**, not of who runs the workflow.

## The two authored doors

Some legitimate workflows do need to cross one of these lines. Nika refuses
to let that happen silently: there are exactly two doors, both authored, both
requiring a written justification, both recorded in the run receipt.

| Door          | Lifts                                                                                                     | Shape                                                                                            |
| ------------- | --------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
| `declassify:` | the **permit-parameterization taint** — an untrusted binding used where a permit is matched               | a list; each entry names `from:` (one dotted binding), `to: trusted`, and a non-empty `because:` |
| `inert:`      | the **data-as-code sink** — a `nika:fetch` whose resolved URL names a code-bearing class (`NIKA-SEC-008`) | a non-empty string; the string IS the justification                                              |

```yaml theme={"system"}
load_inventory:
  invoke:
    tool: "nika:read"
    args: { path: "${{ inputs.p }}" }
  declassify:
    - from: inputs.p
      to: trusted
      because: "deployment-controlled inventory path, reviewed at release"
```

Each door lifts **one** law and nothing else. `declassify:` does not widen
`permits:` — the value is still matched against the declared boundary, so it
can never become a permit bypass, and there is no implicit declassification.
`inert:` does not touch the `net.http` boundary or the SSRF floor.

Because both are plain YAML keys, `grep -rn 'declassify:\|inert:'` over a
repo returns every place a law was waived, with the reason attached. That is
the point: the escape hatch is auditable by construction.

## Trust levels + prompt injection

Content entering a workflow carries a trust level. Untrusted content
(fetched pages, user comments) is tracked as it flows into prompts and
tools:

| Defense layer                                              | Error surface                        |
| ---------------------------------------------------------- | ------------------------------------ |
| dangerous tool invoked on untrusted data → blocked         | `NIKA-SEC` family (`security_error`) |
| strict-mode trust-level violation                          | `NIKA-SEC` family                    |
| exfiltration canary token found in output                  | `NIKA-SEC` family                    |
| prompt-injection scanner (+ ML detection)                  | `NIKA-SEC` family                    |
| untrusted data reached a prompt without spotlight wrapping | `NIKA-SEC` family                    |
| workflow recursion depth / self-launch blocked             | `NIKA-SEC-003` (registered)          |

The three codes the spec REGISTERS today: `NIKA-SEC-001` (exec blocklist
hit), `NIKA-SEC-002` (agent tool outside the whitelist), `NIKA-SEC-003`
(run-recursion bound). The runtime trust layers above are engine-side
(the Shield): they emit within the `NIKA-SEC` namespace as they land.

Every failure is a [typed error](/reference/error-codes) with a stable
code and a `transient` flag. Your `on_error:` can act on it.

## Secrets

`${{ secrets.* }}` is a first-class namespace (vault/env/file-backed).
Secret values are **masked in logs and traces** at the binding layer:
they never appear in the event stream, and they are not readable back
from a task's recorded output.

## Supply-chain hardening (the engine itself)

* `unsafe_code = "forbid"` workspace-wide · zero `.unwrap()` in `src/` (CI-enforced)
* `cargo deny` on every PR · `cargo audit` on every dependency change
* Sealed kernel traits · external code cannot impersonate engine I/O
* &#x20;lib tests ·  clippy warnings · every crate passes 12 admission gates
* AGPL-3.0-or-later · the source travels with the binary, always auditable

## Reporting a vulnerability

**[security@supernovae.studio](mailto:security@supernovae.studio)** (please not via public issues).
Acknowledgement ≤72h, triage ≤7 days, disclosure ≤90 days. Full policy,
disclosure process and the out-of-scope list:
[SECURITY.md](https://github.com/supernovae-st/nika/blob/main/SECURITY.md).

## See also

<CardGroup>
  <Card title="Error codes" icon="triangle-exclamation" href="/reference/error-codes">
    The `NIKA-SEC` namespace + every typed failure.
  </Card>

  <Card title="Bindings" icon="link" href="/concepts/bindings">
    Taint, scopes, and the `secrets.*` namespace.
  </Card>

  <Card title="Builtins · fetch" icon="globe" href="/reference/builtins">
    The `nika:fetch` contract (engines MUST ship SSRF defense).
  </Card>

  <Card title="SECURITY.md" icon="shield" href="https://github.com/supernovae-st/nika/blob/main/SECURITY.md">
    Reporting, disclosure timeline, hall of fame.
  </Card>
</CardGroup>


# Traces & replay
Source: https://docs.nika.sh/concepts/traces

Every run can leave a replayable record: one NDJSON file that proves what ran, in what order, at what cost.

You ran a workflow an hour ago. It worked (or it didn't), and now someone
asks: *what exactly happened?* With most AI tooling the answer scrolled
away. With Nika the run itself is a file: every event the engine emitted,
one JSON line each, in order, with timestamps. Save it, share it, replay
it. The run is evidence, not a memory.

<video>
  <source type="video/webm" />

  <source type="video/mp4" />
</video>

*A real run, replayed: the plan lights task by task exactly as the
recorded event stream says it happened.*

## Record a run

`nika run` renders a live storyboard for humans. Add `--json` and the
same run streams machine events instead, one NDJSON line per event:

```bash theme={"system"}
nika run review.nika.yaml --json > .nika/traces/review.ndjson
```

That single redirect is the whole recorder. The stream is designed for
CI and agents (stdout stays pure NDJSON; nothing else is printed there),
so capturing it live costs nothing. By convention, project traces live
under `.nika/traces/` next to the workflows they record; the CLI reads a
trace from any path you give it.

Since 0.94 the redirect is optional: **every run writes its own journal**
to `.nika/traces/<timestamp>-<id>.ndjson` by default, and the verdict
line prints the path. `--resume`, `nika trace show|replay` and the editor
read it directly. Opt out per run with `--no-trace-file`, or globally
with `NIKA_NO_TRACE_FILE` (`nika try` never journals — the mock
rehearsal is not a workspace run).

## The event stream

A trace is the run's lifecycle spine. Each line is one event with a
unique id, a nanosecond timestamp, a `kind`, and typed fields:

* `workflow_started`, then one `task_scheduled` per task
* `task_started` when a task's dependencies clear
* `task_completed` (with `duration_ms`), or `task_failed`, or
  `task_skipped` (a `when:` gate said no), or `task_cache_hit`
  (a [resumed run](/guides/resume) reused this task's recorded work)
* `workflow_completed`, or `workflow_failed`, or `workflow_paused`
  (a human gate is waiting — the trace carries the prompt payload)

Here is a real capture, verbatim, from a two-task exec workflow:

```json theme={"system"}
{"id":{"uuid":"019f23fb-af22-76b0-a124-4fc91d3166e9"},"timestamp":1783015124770000000,"kind":"workflow_started","run":null,"correlation":null,"fields":[{"key":"workflow","value":"version-stamp"},{"key":"permits","value":"engine floor (no boundary declared)"}]}
{"id":{"uuid":"019f23fb-af22-76b0-a124-4fd5aa792ff9"},"timestamp":1783015124770000000,"kind":"task_scheduled","run":null,"correlation":null,"fields":[{"key":"task","value":"stamp"}]}
{"id":{"uuid":"019f23fb-af3d-7331-807d-3ec787e872c3"},"timestamp":1783015124797000000,"kind":"task_started","run":null,"correlation":null,"fields":[{"key":"task","value":"stamp"},{"key":"note","value":"exec · date"}]}
{"id":{"uuid":"019f23fb-af3d-7331-807d-3ed6051694b4"},"timestamp":1783015124797000000,"kind":"task_completed","run":null,"correlation":null,"fields":[{"key":"task","value":"stamp"},{"key":"note","value":"exec · date"},{"key":"duration_ms","value":26}]}
{"id":{"uuid":"019f23fb-af5a-70d3-a7e2-1cfd58fbaed3"},"timestamp":1783015124826000000,"kind":"workflow_completed","run":null,"correlation":null,"fields":[{"key":"workflow","value":"version-stamp"}]}
```

The spine is not the whole vocabulary. Deeper kinds record retries
(`task_retrying`), cancellation (`task_cancelled`,
`workflow_cancelled`), money (`cost_incurred`), security checks
(`permit_checked`), streaming (`infer_chunk`) and the agent loop
(`agent_tools_selected`, `agent_budget_checkpoint`, and friends). The
full event system, including the durability checkpoints that make runs
resumable, is documented in [Concepts · Events](/concepts/events).

Real spend also rides the spine: a priced `task_completed` carries a
`cost_usd` field next to its `tokens` — **absent** for mock and local
runs (unpriced is honestly absent, never a fake `0`). Agent loops
report the loop's accumulated tool spend as `tools_cost_usd`.

## Replay, never re-execute

Two commands read a trace back:

```bash theme={"system"}
nika trace replay .nika/traces/review.ndjson   # re-render the run, live
nika trace show   .nika/traces/review.ndjson   # print the final card only
```

`replay` plays the recorded events through the same renderer that drew
the original run: same storyboard, same timing, same verdict card.
`show` skips the animation and prints the summary.

<Warning>
  **Replay = re-render, never re-execute.** Replaying a trace calls no
  model, runs no command, touches no file. Zero tokens, zero effects.
  It is a projection of what already happened, safe to run on any
  machine, any number of times.
</Warning>

## Why this matters

* **The run is auditable.** Which tasks ran, in what order, how long
  each took, what it cost, which permits were checked: it is all in the
  file, not in someone's scrollback.
* **The run is shareable.** Attach the `.ndjson` to a PR or an issue.
  A reviewer replays it locally and sees exactly what you saw, without
  credentials and without re-running anything.
* **The demos are honest.** The replays on [nika.sh](https://nika.sh)
  ("Press play. It really ran.") are exactly these files: recorded runs
  played back through the same renderer, not screenshots and not
  mockups.
* **The run is resumable.** The same file doubles as the checkpoint:
  `nika run --resume <trace>` skips completed work with visible cache
  hits and re-arms a paused human gate. See [Resume a run](/guides/resume).

## Related

* [Reference · CLI](/reference/cli): every `nika run` and `nika trace`
  flag, including `--json` and `--output json` (the typed `outputs:`
  export, a different surface from the event stream).
* [Concepts · Events](/concepts/events): the full event vocabulary and
  the durability model behind it.
* [Concepts · Workflows](/concepts/workflows): how a file becomes the
  executed graph the trace records.


# The 4 verbs
Source: https://docs.nika.sh/concepts/verbs

infer · exec · invoke · agent. Four verbs, closed set, typed contracts. Everything else is data.

A Nika workflow is a list of **tasks**. Each task picks exactly one of
**four verbs** (`infer`, `exec`, `invoke`, `agent`) and
supplies its required fields. The set is closed: the parser's verb
dispatcher is exhaustive at compile time, so adding a fifth verb is a
schema-version bump, not a patch release.

<Info>
  All four verbs execute end-to-end today: every snippet on this page is
  runnable with `nika run` at v. Verb grammar is frozen by
  the `nika: v1` language envelope: these four, forever.
</Info>

## Why four?

A verb is a **distinct native execution model** the engine itself
implements. Every workflow decomposes into one of these moves:

| Verb     | One-line intent                                             |
| -------- | ----------------------------------------------------------- |
| `infer`  | Ask an LLM.                                                 |
| `exec`   | Run a local command.                                        |
| `invoke` | Call a builtin tool OR an MCP tool.                         |
| `agent`  | Delegate to an agent loop (LLM + tools + iteration budget). |

Anything else we considered ("transform", "map", "branch", "retry")
was a special case of one of these four, or workflow-level machinery
(dependencies, `for_each`, `when`) that lives on the task envelope,
not as a new verb.

The vNext families stay on the same tool — uploads are `multipart:`, forms are
`form:`, and a bounded site crawl is `traverse:` (crawl is an *intention*, fetch
is the primitive):

```yaml theme={"system"}
crawl_site:
  invoke:
    tool: "nika:fetch"
    args:
      url: "${{ inputs.site_url }}"
      traverse: { max_pages: 5 }   # same-origin BFS · robots honored · page digests out
```

```mermaid theme={"system"}
%%{init: {'theme':'dark','themeVariables':{'background':'transparent','mainBkg':'transparent'}}}%%
flowchart LR
    classDef verb fill:#3F7DFF,color:#fff,stroke:#7FE9FF,font-weight:bold
    classDef tool fill:#1f2937,color:#94a3b8,stroke:#475569
    classDef out fill:#0b1530,color:#7FE9FF,stroke:#3F7DFF

    Y["📄 .nika.yaml<br/>intent"]:::out --> D{verb?}
    D -->|"think"| I["infer<br/>LLM call"]:::verb
    D -->|"run"| E["exec<br/>subprocess"]:::verb
    D -->|"use"| V["invoke<br/>tool dispatch"]:::verb
    D -->|"delegate"| A["agent<br/>loop + budget"]:::verb
    V --> B["nika:* builtins"]:::tool
    V --> M["MCP servers"]:::tool
    A -.->|"each turn may"| V
    I & E & V & A --> R["typed output<br/>tasks.X.output"]:::out
```

<sub>The set is closed at four. Everything *callable* is a tool under `invoke`; everything about *ordering* is a DAG construct on the task envelope.</sub>

> **Where did `fetch` go?** Fetching a URL is *calling a tool*, not a
> distinct execution model, so it is the `nika:fetch` builtin, reached
> through `invoke:` (the extract modes become its `mode` argument). Same
> reason a DB query (`invoke: mcp:postgres/query`) or a file write
> (`invoke: nika:write`) is not its own verb.

## `exec`: run a local command

Spawns a subprocess, captures stdout/stderr, returns exit code + output.

**Required**: exactly one of `command` (array · argv through `execve`, no
shell) | `shell` (string · the explicit shell door: pipes · redirects ·
globs). A string `command:` is rejected at parse.
**Optional**: `cwd` (path), `env` (map · OS env for this subprocess), `stdin` (string), `capture` (`stdout` default · `stderr` · `combined` · `structured`). Task-level `timeout:` applies (not a verb field).

```yaml theme={"system"}
build:
  timeout: "300s"                  # task-level (applies to any verb)
  exec:
    command: ["cargo", "build", "--release"]
    cwd: ./crates/engine
    capture: structured            # { stdout, stderr, exit_code }
    env:
      RUSTFLAGS: "-C target-cpu=native"
```

**Invariants** (from `nika-kernel::process::ShellExecutor`):

* `Command::new` MUST set `kill_on_drop(true)`: no leaked child processes (INV-011).
* Concurrent pipe reading uses `tokio::try_join!` (INV-012).
* Non-zero exit is a task failure (`NIKA-EXEC-001`) in the default
  capture modes, **except `capture: structured`**, where the exit code
  is data (`output.exit_code` · the task succeeds and the workflow
  branches on it). Untrusted values ride argv elements (each substituted
  independently, no shell to break out of) or `stdin:` — never a
  `shell:` string.

Cross-link: [`ShellExecutor` trait](/architecture/layers#layer-table) (L0.5 kernel contract).

## HTTP fetch: `invoke: nika:fetch` (a builtin, not a verb)

Fetching a URL is *calling a tool*, so it is the **`nika:fetch` builtin**
reached through `invoke:`, not its own verb. Issues an HTTP request
(GET/POST/etc.), returns bytes or parsed/extracted data; the old extract
modes become the builtin's `mode` argument.

```yaml theme={"system"}
secrets:
  github_token:
    source: env                        # a token is a governed reference, never a literal
    key: GITHUB_TOKEN
    egress:
      - to: "nika:fetch"               # the author declassifies THIS sink, in-file
        host: "api.github.com"         # and only this host

permits:
  net: { http: ["api.github.com"] }
  tools: ["nika:fetch"]

tasks:
  pull_readme:
    timeout: "30s"                     # task-level (applies to any verb)
    invoke:
      tool: nika:fetch
      args:
        url: https://api.github.com/repos/supernovae-st/nika/readme
        method: GET
        mode: text                     # extraction mode · see extract-modes
        headers:
          Accept: application/vnd.github.raw
          Authorization: "Bearer ${{ secrets.github_token }}"
```

A credential is a `secrets:` reference — never a `config:` value, never a
literal. And a secret reaching any sink is a blocking leak by default
(`NIKA-SEC-006`): the `egress:` entry is the author sanctioning one
specific destination, statically checkable, and it never widens
`permits.net.http` — it narrows inside it.

**Pick the `mode` for the content** — the default is `markdown`, built
for *pages*: fetching a JSON API without a mode markdown-escapes the
body (`\[`, `assets\_url`) and every downstream `jq`/`fromjson` fails
on byte 0. APIs take `mode: raw` (the exact bytes) or `mode: jq` + a
`jq:` expression — the shape step rides the fetch itself, one task
instead of two.

**Invariants** (from `nika-kernel::http::HttpClient`):

* Output is **tainted** by default (external input is untrusted, T3:A).
* Transient statuses (429, 5xx) are retried per `retry:` on the task.
* Authentication headers never appear in events: they pass through
  `SecretResolver` + `AuditSink::SecretRedacted`.

See the [builtins catalog](/reference/constellation) for `nika:fetch`'s
full argument schema (extract modes, session, cache).

## `invoke`: call a builtin or MCP tool

Calls a builtin (`nika:` namespace) or a tool/resource exposed by a
connected **Model Context Protocol** server. MCP server aliases are
declared in the workflow's `mcp:` block.

**Required**: `tool` (string · `nika:<path>` for a builtin OR `mcp:<server>/<tool>` for an MCP tool).
**Optional**: `args` (object · tool-specific schema). Task-level `timeout:` applies (not a verb field).

```yaml theme={"system"}
search_vectordb:
  with:
    summary: ${{ tasks.summarize.output }}
  invoke:
    tool: "mcp:chroma/query"          # mcp:<server>/<tool> · one colon, then a slash
    args:
      query: "${{ with.summary }}"
      top_k: 5
```

The MCP server `chroma` is configured in the engine's MCP server registry
(engine config · out of scope of the workflow file). Builtins use the
`nika:` namespace, e.g. `tool: "nika:read"`.

Routing goes through `ToolExecutor` + `ToolExecute::execute(ToolCall)`
at L0.5, the same trait the `agent` verb uses to dispatch in-loop
tool calls (`crates/nika-kernel/src/runtime/tool_executor.rs`).

## `infer`: LLM inference

Single-shot call to a language model. One `InferRequest` shape covers
all  providers in the catalog.

**Required**: `prompt` (string).
**Optional**: `system` (string), `model` (`<provider>/<name>` · overrides the
workflow default), `temperature` (0.0–2.0), `max_tokens` (u32), `schema`
(JSON Schema · structured output), `thinking` (`{ enabled, budget_tokens }`),
`vision` (image inputs).

```yaml theme={"system"}
summarize:
  with:
    readme: ${{ tasks.pull_readme.output }}
  infer:
    model: mistral/<model>          # <provider>/<name> · see /reference/providers-catalog
    system: "You are a technical writer."
    prompt: |
      Summarize this in one sentence:
      ${{ with.readme }}
    temperature: 0.3
    max_tokens: 500
```

<Note>
  Model identifiers are catalog-validated at parse time. See the
  [Providers catalog](/reference/providers-catalog) for live IDs. We
  never hard-code them in concept docs because model names drift faster
  than the docs refresh cycle.
</Note>

**Invariants** (from `nika-kernel::provider::Provider`):

* Unified `InferRequest` (INV-017): one DTO · per-provider wire dialects below (3 implemented today: anthropic · gemini · openai-compat, the dialect that carries most of the 16-provider catalog · plus mock).
* Capability rules ([ rules](/reference/capabilities))
  run **before** dispatch. Sending `tools` to a model whose capability
  rule says `tool_calling = false` fails with a typed validation error
  before the network round-trip.
* Every provider emits the same `InferEvent` stream: `Delta`,
  `ToolUseStart`, `ToolUseDelta`, `Thinking`, `Usage`, `Done`.

Cross-link: [Providers](/concepts/providers) · [`Provider` trait](/architecture/layers#layer-table) · ADR-035 (telemetry seams).

## `agent`: multi-turn loop with tools

A model-driven loop: the agent calls tools, observes results, iterates
until a completion signal fires or a budget exhausts.

**Required**: `prompt` (string · initial user message).
**Optional**: `system` (string), `model` (`<provider>/<name>`), `tools`
(whitelist · glob patterns · **default-deny**), `max_turns` (u32 · default 10),
`max_tokens_total` (u32 · cumulative token budget), `temperature` (0.0–2.0),
`schema` (JSON Schema · validates the final message).

```yaml theme={"system"}
investigate:
  agent:
    model: mistral/<model>          # <provider>/<name>
    system: |
      You are investigating a GitHub issue. Use tools to gather
      context before answering.
    tools:                               # default-deny · grant explicitly
      - nika:fetch
      - mcp:browser/*
    max_turns: 10
    max_tokens_total: 100000
    prompt: |
      Investigate issue #${{ inputs.issue_number }} and summarise
      the root cause in under 200 words.
```

**Invariants** (from `nika-kernel::runtime::agent`):

* The loop is budget-bounded. The LANGUAGE contract (`max_turns` ·
  `max_tokens_total` · spec 02-verbs) is what workflows declare; the
  engine's `AgentLoopConfig` carries `max_turns` today plus its
  planning/reflection/compression knobs. `max_tokens_total` wires in
  with the runtime milestone.
  A ceiling hit is a **typed failure** (`NIKA-AGENT-001` /
  `NIKA-AGENT-002` · `budget_error`) with the last assistant message
  preserved in `error.details.partial_output`. Recover it explicitly
  via `on_error:` if a partial is acceptable. Natural completion (or
  `nika:done`, optionally with `result:`) is success.
* A failing tool call feeds its typed error back to the model (the
  loop continues against its budgets), EXCEPT `security_error`, which
  fails the task immediately.
* Every tool call is **taint-checked**: untrusted data cannot reach
  dangerous verbs without an explicit sanitizer.
* The iteration trace (`ToolCallRecord` + `CheckpointMessage`) is
  emitted as events for audit and, optionally, checkpoint resume.

Cross-link: [`AgentLoopConfig`](/architecture/layers#layer-table) · ADR-016 (cancellation model).

## Verb selection is exhaustive

The `nika-schema` parser enforces "exactly one verb key per task" at
compile time: the `Verb` enum in
`crates/nika-schema/src/parser/tasks.rs` has four variants, and the
action builder has exactly four match arms. Adding a fifth verb
requires:

1. Extending `RawAction` + the `Verb` enum.
2. Wiring a new action builder arm.
3. Bumping `SchemaVersion` (currently `v1`).
4. Running all 12 admission gates on the consuming L2 verb crate.

This is the single hardest number in the Nika grammar to change. We'd
rather say no.

<Info>
  **Implementation status.** Current verb executors ship as design-only
  kernel traits; the four L2 verb crates (`nika-verb-infer`,
  `nika-verb-exec`, `nika-verb-invoke`, `nika-verb-agent`) are all
  admitted and execute end-to-end (see
  [Constellation](/reference/constellation)). `fetch` is not a verb
  crate: it is the `nika:fetch` builtin reached through `invoke`. The verb
  grammar is locked and shipped (`nika-schema`).
</Info>

## Read next

<CardGroup>
  <Card title="Workflows" icon="diagram-project" href="/concepts/workflows">
    How verbs compose into a DAG.
  </Card>

  <Card title="Bindings" icon="link" href="/concepts/bindings">
    How values flow between tasks.
  </Card>

  <Card title="Providers" icon="server" href="/concepts/providers">
    The -provider catalog behind `infer` and `agent`.
  </Card>

  <Card title="Events" icon="signal" href="/concepts/events">
    Every verb emits typed events.
  </Card>
</CardGroup>


# Workflows
Source: https://docs.nika.sh/concepts/workflows

A .nika.yaml file: schema · metadata · tasks. Parsed into a DAG, executed with structured concurrency.

A **workflow** is a YAML document that names a goal, lists one or more
tasks, and declares how values flow between them. Nika parses the file
with source spans, validates it against the catalog, compiles it to a
DAG, and executes tasks in topological order, parallelizing whatever
the dependency graph allows.

<Info>
  **Implementation status.** The envelope below is the canonical spec
  contract (`nika-spec` · [01-envelope](https://github.com/supernovae-st/nika-spec/blob/main/spec/01-envelope.md)).
  The engine implements it end-to-end today: `nika check` parses and
  audits it, `nika run` executes it. [Live state →](/reference/status)
</Info>

## Minimal workflow

```yaml theme={"system"}
nika: v1
workflow:
  id: hello
  description: "A minimal workflow."

tasks:
  greet:
    infer:
      prompt: "Say hi in one line."
      model: ollama/<model>      # <provider>/<name>
```

Two required lines (`nika:` + `workflow:`) and a non-empty `tasks:`, the
whole minimum to be a valid workflow. Fields carry source spans through
`Spanned<T>` so diagnostics point at the exact byte range.

## Why one version marker (not a K8s envelope)

The envelope is **one header line** · `nika: v1`. Earlier drafts explored a
Kubernetes-style `apiVersion` + `kind` + `metadata` + `spec` envelope, but
the spec rejected it: that is two version-ish fields and ceremony a workflow
file does not need. Modern specs converge on a single version marker:
OpenAPI writes `openapi: 3.1.0`, Docker Compose dropped its `version:` field
entirely. Nika takes the proven path: **the language name as the key, the
contract version as the value.**

* No separate `kind:` field: the presence of `workflow:` is itself the
  document-type discriminator. Future document types (if any ever ship) use
  their own top-level key.
* The engine's internal canonical URI stays `https://nika.sh/spec/v1` for
  RDF / conformance tooling, but the author never types a URL.

Multi-document YAML is supported: one file may declare multiple documents
separated by `---`, parsed into `Vec<RawDocument>`.

## Anatomy of a workflow

The workflow AST (`nika-schema::raw::RawWorkflow`) models exactly the
envelope's fields — nothing hidden, nothing extra:

| Field      | Purpose                                                                                                       |
| ---------- | ------------------------------------------------------------------------------------------------------------- |
| `nika`     | The language contract version (exactly `v1`).                                                                 |
| `workflow` | The identity object — kebab-case `id:` (the document-type discriminator) + optional `description:`.           |
| `model`    | Workflow-level default `<provider>/<name>` for `infer` / `agent` tasks.                                       |
| `inputs`   | **Value authority** · typed parameters the caller supplies at launch (`--var key=value`) · `${{ inputs.X }}`. |
| `config`   | **Value authority** · typed non-sensitive runtime config the deployment supplies · `${{ config.X }}`.         |
| `const`    | **Value authority** · named constants fixed in the file, never caller-supplied · `${{ const.X }}`.            |
| `secrets`  | **Value authority** · masked store references · `${{ secrets.X }}`.                                           |
| `permits`  | The declared capability boundary. Absent = **zero** authority; present = default-deny per category.           |
| `policy`   | The run's declared limits.                                                                                    |
| `types`    | Named PascalCase type declarations, referenced by `returns:` and typed `outputs:`.                            |
| `run`      | The run's entropy + clock declaration — randomness and time are declared, never ambient.                      |
| `tasks`    | The DAG payload — a non-empty map, the key IS the task id.                                                    |
| `outputs`  | The workflow's return contract.                                                                               |
| `assert`   | The author's obligations, judged by the engine.                                                               |

The four value authorities are a **closed family**: `inputs` · `config` ·
`const` · `secrets`. The pre-flip `vars:` and `env:` blocks are dead
(`NIKA-VALUES-001` / `NIKA-VALUES-002`) and no alias survives — each old
use classifies into the authority its role commands. (The `env:` field
*inside* an `exec:` block is a different thing and is alive: it is the
child process's environment map.)

Every field is span-carrying (`Spanned<T>`): source spans survive
all the way into the diagnostic layer (ADR-010 miette bridge).

## Execution pipeline

```
         ┌───────────────┐
 .yaml   │  nika-schema  │   RawWorkflow
  ─────► │     parser    │ ──────────────┐
         │ (marked-yaml) │               │
         └───────────────┘               ▼
                                 ┌────────────────┐
                                 │ nika-schema    │   DAG · typed
                                 │    analyzer    │   scope · taint
                                 │   (admitted)   │
                                 └────────────────┘
                                          │
                                          ▼
                                 ┌────────────────┐
                                 │  nika-runtime  │
                                 │  (L3 · live)   │
                                 │                │
                                 │ topo-sort ──►  │   ┌─ exec   L2
                                 │ dispatch  ──►  │   ├─ fetch  L2
                                 │ events    ──►  │   ├─ invoke L2
                                 │ checkpoint ──► │   ├─ infer  L2
                                 │                │   └─ agent  L2
                                 └────────────────┘
                                          │
                                          ▼
                                  EventSink · BillingSink · AuditSink
```

ASCII by intent: Mintlify renders fine, but the diagram above is plain
text and pastes into terminals and issue trackers without a renderer.

## Tasks, edges, fan-out

`tasks.*` crosses a task boundary through exactly **two doors** — `with:`
(data) and `after:` (control) — and the engine computes the graph FROM
those doors: a `with:` binding referencing `${{ tasks.X.* }}` both names
the data the task consumes and declares a typed edge; an `after:` entry
(`{producer: predicate}`) orders on state and carries no data. There is no
third way to connect two tasks — `depends_on` is dead (`NIKA-PARSE-024` ·
`nika check --fix` migrates it). Nika builds the DAG, topologically sorts,
and runs tasks in parallel where the graph allows.

```yaml theme={"system"}
tasks:
  fetch_data:
    invoke:
      tool: nika:fetch
      args:
        url: https://example.com/data.json

  analyze:
    with:
      data: ${{ tasks.fetch_data.output }}    # the binding IS the edge
    infer:
      model: ollama/<model>      # <provider>/<name>
      prompt: "${{ with.data }}"

  notify:
    with:
      analysis: ${{ tasks.analyze.output }}
    exec:
      command: ["echo", "${{ with.analysis }}"]
```

The task's **body consumes its bindings** (`${{ with.data }}`), never the
global `tasks.*` namespace: a reference outside the boundary is
`NIKA-VAR-021`, and `nika check --fix` hoists it into `with:` for you.

For an ordering with **no data** (run the deploy after the tests, consume
nothing), use `after:` — a map `{producer: predicate}` whose predicate
names the producer states that admit this task:

```yaml theme={"system"}
deploy:
  after:
    tests: success      # control edge · state, never data
  exec:
    command: ["./deploy.sh"]
```

The predicate set is **closed** (`NIKA-DAG-005` otherwise): `success` ·
`failed` · `skipped` · `terminal` — where `terminal` admits any terminal
state, `cancelled` included (the always-pattern: « run once X is settled,
whatever happened »).

Fan-out over a collection (`files` here is a jq
[output binding](/concepts/bindings) on `list_files`, e.g.
`output: { files: 'split("\n")' }` — the collection crosses the boundary
through `with:`, then `for_each:` reads the binding):

```yaml theme={"system"}
analyze_each:
  with:
    files: ${{ tasks.list_files.files }}
  for_each: "${{ with.files }}"
  infer:
    model: ollama/<model>        # <provider>/<name>
    prompt: "Review this file: ${{ item }}"
```

Conditional execution: `when:` is a **local business condition**, evaluated
*after* the gate admits the task. It reads local namespaces only (`vars` ·
`env` · `with` · the `for_each` locals) — a `tasks.*` reference inside
`when:` is refused at parse time (`NIKA-VAR-021`): the binding creates the
edge, `when:` reads the binding.

```yaml theme={"system"}
deploy:
  with:
    passed: ${{ tasks.tests.output.passed }}
  when: "${{ with.passed == true }}"
  exec:
    command: ["./deploy.sh"]
```

`when:` evaluating `false` settles the task **`skipped`** (a decision —
downstream value edges pass, reading `null`), and the gate always applies:
`when:` refines it, never replaces it. To run a task *whatever happened*
upstream (the report / cleanup class), say it in the graph —
`after: { pipeline: terminal }` — and observe the outcome through
`with: { outcome: ${{ tasks.pipeline.status }} }` when the body branches
on it.

Retry on failure: `retry:` is the one shape (and `on_error:` catches
what retries can't fix):

```yaml theme={"system"}
flaky_api:
  invoke:
    tool: nika:fetch
    args:
      url: https://example.com/api
  retry:
    max_attempts: 5
    backoff_strategy: exponential
    jitter: true
```

<Note>
  Field names are the spec's: the map key is the task's identity (no
  `id:`/`name:` field), `when:` (not `condition:`), `with:`/`after:`
  (not `depends_on:`), `retry.max_attempts` (not `max_retries:`). The
  [JSON Schema](https://nika.sh/spec/v1/workflow.schema.json) rejects the wrong
  names at check time.
</Note>

## Inputs · `inputs`

Workflow inputs live in `inputs:`, available in every task via
`${{ inputs.<name> }}`. Every entry is a **typed declaration** (`type:` is
required, and speaks the full type grammar): that is what lets the engine
validate what a caller passes and generate a callable schema for
`nika.run_workflow` over MCP.

A value the caller may override belongs here. A value the file owns and
nobody overrides is a `const:` entry; a deployment dial is a `config:`
declaration; a credential is a `secrets:` reference. Four authorities, one
role each — pick by the role the value plays.

```yaml research-brief.nika.yaml theme={"system"}
nika: v1
workflow:
  id: research-brief
  description: "Bullet-point brief on a topic supplied at launch."

model: mock/echo                       # swap for ollama/qwen3.5:4b or any provider

inputs:
  topic:
    type: string                       # typed · validated + schema-gen
    required: true
    description: "Subject to research"
  bullets:
    type: integer
    default: 3

tasks:
  brief:
    infer:
      prompt: "Write ${{ inputs.bullets }} bullet points on ${{ inputs.topic }}."

outputs:
  brief: "${{ tasks.brief.output }}"
```

This file declares no `permits:` block and needs none: it runs zero shells,
touches no file, reaches no host. Every effect-bearing workflow carries one —
absent means **zero** authority, and the check refuses the body with
`NIKA-AUTH-006` before a single token is spent.

<Note>
  There is no `include:` / `import:` — a workflow never splices another
  file's text into its own. Reuse happens through **composition**: one
  workflow *calls* another as a typed, bounded step. See below.
</Note>

## Composition · one workflow calls another

`invoke:` is a **tagged union**: exactly one of `tool:` (a builtin or an MCP
tool) or `workflow:` (another workflow). Same verb, same call site — the
field IS the semantics. There is no fifth verb and no `nika:*` builtin that
launches a workflow.

The child is an ordinary workflow. Nothing marks it as "a child":

```yaml word-count.nika.yaml theme={"system"}
nika: v1
workflow:
  id: word-count
  description: "Count the words in a piece of text · the reusable child."

inputs:
  text: { type: string, required: true }

permits:
  tools: ["nika:jq"]

tasks:
  count:
    invoke:
      tool: "nika:jq"
      args:
        input: { text: "${{ inputs.text }}" }
        expression: '{ words: (.text | split(" ") | length) }'
    returns:
      object:
        words: integer

outputs:
  words: "${{ tasks.count.output.words }}"
```

The parent calls it by **static path**, passes `args:` that fit the child's
`inputs:`, and reads the child's `outputs:` back as that task's output:

```yaml brief-with-stats.nika.yaml theme={"system"}
nika: v1
workflow:
  id: brief-with-stats
  description: "Write a brief, then measure it by calling a child workflow."

model: mock/echo

inputs:
  topic: { type: string, required: true }

permits:
  tools: ["nika:jq"]           # the child's tools, hoisted · see the boundary note

tasks:
  brief:
    infer:
      prompt: "Write three bullet points on ${{ inputs.topic }}."

  measure:
    with:
      body: "${{ tasks.brief.output }}"
    invoke:
      workflow: "./word-count.nika.yaml"
      args:
        text: "${{ with.body }}"
    returns:
      object:
        words: integer

outputs:
  brief: "${{ tasks.brief.output }}"
  words: "${{ tasks.measure.output.words }}"
```

```bash theme={"system"}
nika run brief-with-stats.nika.yaml --var topic="local-first AI"
```

### The rules the checker enforces

* **Static target** — `workflow:` is a filesystem path or a pinned
  `registry:owner/name@version`. A `${{ }}`-templated target is refused
  (`NIKA-COMP-001`): a call graph you cannot draw before the run is a call
  graph you cannot bound.
* **Typed call** — the parent's `args:` must fit the child's `inputs:`, and
  what the parent declares in `returns:` must fit the child's `outputs:`
  (`NIKA-COMP-004`). The child's contract is *derived from its body*, never
  annotated twice.
* **Zero implicit authority** — a child never gains a capability its parent
  lacks (`NIKA-COMP-002`).
* **Acyclic** — a static cycle or self-launch is refused (`NIKA-COMP-003`).

<Warning>
  **The parent's `permits:` must cover the child's effects.** Authority flows
  down, never up: the child above invokes `nika:jq`, so the parent declares
  `nika:jq` too — drop it and the check fails `NIKA-COMP-002`. On that parent
  `nika check` also prints an advisory `NIKA-DRIFT-001` hint saying the entry
  "admits no tool the body invokes" — it is counting only the parent's *own*
  tasks. Under composition the entry is load-bearing: keep it. The hint is
  advisory and does not fail the check.
</Warning>

Each child keeps its **own** hash-chained trace; the parent's trace records
the child's outcome, so a run is a forest of chains rather than one flattened
stream. Full contract: [spec 14 · Composition](https://github.com/supernovae-st/nika-spec/blob/main/spec/14-composition.md).

### Supply values at launch · `--var`

`nika run` takes one `--var key=value` per input (repeatable):

```bash theme={"system"}
nika run research-brief.nika.yaml --var topic="local-first AI" --var bullets=5
```

Four rules govern the flag, and the file stays the contract — every input a
caller can pass is declared in `inputs:`:

* **A supplied value overrides a declared `default:`.** `--var bullets=5`
  wins over `default: 3` for this run.
* **It satisfies `required: true`.** A required input with no default must be
  supplied at launch; without it the task that reads it fails loud
  (`NIKA-VAR-001`, naming the exact flag to pass). `nika check` flags it
  earlier, statically: `HINT [inputs] required input(s) with no default ·
  pass at run time: --var topic=…`.
* **The value parses as JSON when it parses.** `--var bullets=5` arrives as
  a number, `--var deep=true` as a boolean, `--var tags='["a","b"]'` as an
  array. Anything that does not parse as JSON rides as a string — no
  quoting gymnastics for the common case.
* **An unknown key is refused before the run**, with the declared set
  listed — a typo that silently did nothing would be the worst outcome:

```text theme={"system"}
$ nika run research-brief.nika.yaml --var topic=x --var oops=1
nika run: --var oops: unknown input — the workflow declares: topic · bullets
```

`--var` reaches `inputs:` and nothing else. A `const:` entry is immutable
across the run by construction, and a `config:` value comes from the
deployment — neither is a launch flag.

## Outputs and events

Every task emits a structured `Event` stream during execution
(`nika-kernel::infra::event_sink::Event`). Consumers subscribe via
`EventSink` and receive one JSON object per line (NDJSON on stdout by
default). See [Events](/concepts/events) for the event model and
[Bindings](/concepts/bindings) for how the DAG propagates values.

<Info>
  The workflow grammar is locked and implemented: the `nika-schema`
  crate ships the envelope, the analyzer and semantic validation
  (type-checked bindings, secret-flow audit, cycle detection). That is
  exactly what `nika check` runs on your file today.
</Info>

## Read next

<CardGroup>
  <Card title="Bindings" icon="link" href="/concepts/bindings">
    Template expressions: `${{ }}` syntax, scopes, filters, taint.
  </Card>

  <Card title="Events" icon="signal" href="/concepts/events">
    The typed event stream every run emits.
  </Card>

  <Card title="Verbs" icon="play" href="/concepts/verbs">
    The 4 verbs each task picks from.
  </Card>

  <Card title="YAML reference" icon="file-code" href="/reference/yaml-syntax">
    Full schema specification (generated from AST).
  </Card>
</CardGroup>


# Bookmark triage
Source: https://docs.nika.sh/examples/bookmark-triage

T2 fan-out · personal / research: the bookmark pile triaged into one table — dead links survive the batch instead of killing it.

> **T2 fan-out · personal / research**: `for_each` fans one
> `nika:fetch` with `mode: metadata` per URL — the page's OG/meta head
> as typed data, not a scrape — with `retry:` for transient blips and
> `on_error: recover:` so a dead link degrades to a `{ dead: true }`
> row instead of failing the batch. `nika:jq` renders the triage
> table; `nika:write` persists it.

## The job

Every bookmark pile has the same two questions: *what is this, and is
it even alive?* Answering them by hand means opening every tab. This
workflow answers both in one run — title/description/site from each
page's own metadata, dead links marked as dead — and leaves a table
you can sort, grep, and prune from.

## The shape

```mermaid theme={"system"}
flowchart LR
  pages["pages · ∥ for_each · nika:fetch"]:::invoke
  table["table · nika:jq"]:::invoke
  report["report · nika:write"]:::invoke
  pages --> table
  table --> report
  classDef invoke fill:#22d3ee22,stroke:#22d3ee,color:#22d3ee
```

## The file

```yaml bookmark-triage.nika.yaml theme={"system"}
nika: v1
workflow:
  id: bookmark-triage
  description: "URL list → per-page metadata fan-out (dead links survive) → one markdown triage table"

const:
  bookmarks:
    # The saved-links pile to triage.
    #
    # A TYPED constant is `{ type, value }` — both keys, exactly those two
    # (`description:` here is NIKA-PARSE-005 · unknown field). The
    # discriminator is normative (01-envelope.md §const): an object missing
    # either key is a bare literal object constant. So `{ type, default }` is
    # not a declaration at all — `${{ const.bookmarks }}` would yield the whole
    # `{type, default}` map and `for_each` would die NIKA-VAR-006 ·
    # « for_each collection must be an array · got object ».
    type: { array: string }
    value:
      - "https://example.com"
      - "https://github.com/supernovae-st/nika"
      - "https://this-domain-does-not-exist-0000.invalid" # the dead one · the recover path IS the demo

permits:
  exec: false
  net:
    http: ["example.com", "github.com", "this-domain-does-not-exist-0000.invalid"]
  fs:
    write: ["out/**"]
  tools: ["nika:fetch", "nika:jq", "nika:write"]

tasks:
  # The fan-out · one metadata fetch per URL · a dead link recovers to a
  # marker object (the batch NEVER dies at bookmark 14).
  pages:
    for_each: ${{ const.bookmarks }}
    max_parallel: 3
    fail_fast: false
    retry: { max_attempts: 2, backoff_ms: 500 } # a transient blip retries BEFORE the dead verdict
    on_error:
      recover: { dead: true } # a YAML value, not a JSON string — the marker row
    invoke:
      tool: "nika:fetch"
      args:
        url: "${{ item }}"
        mode: metadata

  # The fan-in · zip results back to their URLs · split live from dead.
  table:
    with:
      pages: ${{ tasks.pages.output }}
    invoke:
      tool: "nika:jq"
      args:
        input:
          urls: ${{ const.bookmarks }}
          pages: ${{ with.pages }}
        expression: >-
          def esc: tostring | gsub("\\|"; "\\|") | gsub("\n"; " ");
          ([.urls, .pages] | transpose | map({ url: .[0], page: .[1] })) as $rows |
          {
            live: ([$rows[] | select(.page.dead != true) |
              "| \(.url) | \(.page.title // "—" | esc) | \((.page.description // "—" | esc) | .[0:80]) |"] | join("\n")),
            dead: ([$rows[] | select(.page.dead == true) | "| \(.url) | DEAD | link rot |"] | join("\n"))
          }

  report:
    with:
      table_live: ${{ tasks.table.output.live }}
      table_dead: ${{ tasks.table.output.dead }}
    invoke:
      tool: "nika:write"
      args:
        path: out/bookmarks.md
        create_dirs: true
        content: |
          # Bookmark triage

          | url | title | description |
          | --- | --- | --- |
          ${{ with.table_live }}
          ${{ with.table_dead }}

          *Generated by [nika](https://nika.sh) — dead links survived the batch (`on_error: recover:`).*

outputs:
  table:
    value: ${{ tasks.table.output }}
    description: "Live rows + dead rows · the triage split"
```

## The resilience ladder, in order

1. **`retry: { max_attempts: 2, backoff_ms: 500 }`** — a transient
   blip gets a second chance BEFORE any verdict.
2. **`on_error: recover:`** — a link that still fails becomes
   `{ dead: true }` and the batch keeps walking. `recover:` takes a
   YAML *value*, not a JSON string: quote it and jq downstream sees an
   unindexable string instead of an object.
3. **The table renders both worlds** — the jq step escapes pipes and
   newlines from page-controlled metadata (a `|` in someone's OG title
   must not break your markdown table), and dead rows print as `DEAD`
   instead of vanishing.

The quiet lesson: `mode: metadata` fetches the page's *head*, typed —
when all you need is identity, don't ask for the body.

## Run it

```bash theme={"system"}
git clone https://github.com/supernovae-st/nika-spec && cd nika-spec
nika run examples/showcase/t2-bookmark-triage.nika.yaml
open out/bookmarks.md
```

<Note>
  This workflow is newer than the currently shipped engine pack:
  `nika examples run showcase/t2-bookmark-triage` says
  `unknown example` until the next engine tag re-vendors the pack.
  Until then, run it from the spec checkout as above — the file is the
  same one the pack will embed, sha-pinned in the spec manifest.
</Note>

Replace `inputs.bookmarks` with your own export (most browsers dump
bookmarks to HTML — one jq pass turns that into the URL list this file
expects).


# CEO Monday brief
Source: https://docs.nika.sh/examples/ceo-monday-brief

T4 epic · founders: market + engineering + KPIs synthesized, and the ping tells you what the run cost.

> **T4 epic · founders / executives**: the flagship. Three branches
> gather in parallel (web signal, repo pulse, the KPI sheet), jq does
> the revenue arithmetic, a thinking model writes the brief, and
> `nika:inspect view: cost` puts the run's own bill in the ping.
> A workflow that reports what it cost you is a workflow you trust on
> a schedule.

## The job

Monday needs one page: market, product, numbers, risks, the ONE
decision. Assembling it eats an hour of founder time. This file
assembles it before you wake: dated filename, summed revenue, and a
webhook ping ending in `run cost $0.14`.

## The shape

```mermaid theme={"system"}
flowchart TD
  approve["approve · nika:prompt"]:::invoke
  news["news · nika:fetch"]:::invoke
  pulse["pulse · git"]:::exec
  sheet["sheet · nika:read"]:::invoke
  rows["rows · nika:convert"]:::invoke
  revenue["revenue · nika:jq"]:::invoke
  brief["brief · thinking"]:::infer
  stamp["stamp · nika:date"]:::invoke
  save["save · nika:write"]:::invoke
  alert["alert · nika:notify"]:::invoke
  approve --> news
  approve --> pulse
  approve --> sheet
  sheet --> rows
  rows --> revenue
  approve --> brief
  news --> brief
  pulse --> brief
  rows --> brief
  revenue --> brief
  approve --> stamp
  approve --> save
  stamp --> save
  brief --> save
  save --> alert
  stamp --> alert
  save -.->|terminal| alert
  classDef infer fill:#5b8cff22,stroke:#5b8cff,color:#5b8cff
  classDef exec fill:#ff7a3c22,stroke:#ff7a3c,color:#ff7a3c
  classDef invoke fill:#22d3ee22,stroke:#22d3ee,color:#22d3ee
```

## The file

```yaml ceo-monday-brief.nika.yaml theme={"system"}
nika: v1
workflow:
  id: ceo-monday-brief
  description: "news + repo pulse + KPIs → one synthesis → dated brief → a ping on every outcome"

model: ollama/qwen3.5:4b   # local · zero key · `--model mock/echo` rehearses the whole file

inputs:
  alert:
    type: bool
    default: false
    description: "Send the founders ping. OFF by default so a rehearsal touches no webhook."
  kpi_sheet:
    type: string
    default: "./examples/fixtures/ceo-kpis.csv"
    description: "The weekly numbers · columns incl. weekly_revenue"

const:
  watch_query: "AI workflow engines"

secrets:
  founders_webhook:
    source: env
    key: FOUNDERS_WEBHOOK_URL
    egress:                       # sanction the one send · the secret IS the URL
      - to: "nika:notify"
        host_from_self: true
permits:
  exec: ["git"]
  tools: ["nika:convert", "nika:date", "nika:fetch", "nika:jq", "nika:notify", "nika:prompt", "nika:read", "nika:write"]
  net:
    http:
      - "hn.algolia.com"          # the market-signal search · the only host this brief READS
      # `host_from_self:` above sanctions the FLOW (the secret may be the URL) —
      # it does not grant the capability. The host stays unknown at check, so it
      # is judged at RUN against this bound: name the escalation host here or the
      # send is refused mid-run, after the tokens are already spent.
      - "hooks.slack.com"         # swap for wherever FOUNDERS_WEBHOOK_URL points
  fs:
    # The sheet arrives as an INPUT, so `check` reads past it — and the wall does
    # not move when the input does: point --var kpi_sheet at anything else and the
    # run refuses it NIKA-SEC-004. That asymmetry is the point of a permits block.
    read: ["./examples/fixtures/ceo-kpis.csv"]
    # One dated brief per run, written DIRECTLY in ./briefs/. `*` matches a single
    # segment and never crosses `/`, so nothing here can steer the write into a
    # subtree — which is why this is not `./briefs/**`.
    write: ["./briefs/*-monday.md"]

tasks:
  # ── the human gate · FIRST, before anything untrusted enters ──
  #
  # This run holds all three legs of the lethal trifecta: a private read (the
  # numbers), untrusted ingress (a public news API), and external egress (a
  # write and a webhook). NEP-0002 asks for one blocking human decision that
  # DOMINATES every path to every egress-capable task — which forces it here,
  # at the root, not in front of the save.
  #
  # A gate placed after the fetch could never dominate: the brief still reaches
  # `save` along its own data edge, a path the human is not standing on. And a
  # human skimming a model's summary of an attacker's page is a weak check
  # anyway — by then the payload is already inside the run. So the decision
  # taken here is the honest one: authorize the CAPABILITY ENVELOPE up front.
  approve:
    invoke:
      # blocking · no `default:` · a gate with a default is not a gate, and the
      # checker enforces both directions: add `default: false` here and this
      # file turns RED with NIKA-SEC-009, because a defaulted prompt dominates
      # nothing. Leaving it blocking costs one [headless-prompt] hint instead —
      # that hint is the price of a real gate, not a defect to paper over.
      # The run pauses (exit 4, not a failure) — answer and resume with
      #   nika run <file> --resume <trace> --answer approve=true
      tool: "nika:prompt"
      args:
        message: |
          This Monday brief will:
            · fetch public news from hn.algolia.com
            · run git in this repo
            · read ${{ inputs.kpi_sheet }}
            · write ./briefs/<date>-monday.md
            · ping the founders webhook (armed: ${{ inputs.alert }})

          Proceed? [yes/no]

  # ── branch 1 · market signal · the untrusted leg ──
  news:
    with:
      go: ${{ tasks.approve.output }}
    when: ${{ with.go == true }}
    invoke:
      tool: "nika:fetch"
      args:
        url: "https://hn.algolia.com/api/v1/search?query=${{ const.watch_query }}"
        mode: jq
        jq: ".hits[:10] | map(.title)"
    on_error:
      # The honest dry run · offline the host resolves nowhere and this literal
      # takes over, so the join below is exercised on both paths with the same
      # binding. It is labelled in the brief so nobody mistakes it for signal.
      recover: ["(offline rehearsal · no market signal was fetched)"]

  # ── branch 2 · engineering pulse ──
  pulse:
    with:
      go: ${{ tasks.approve.output }}
    when: ${{ with.go == true }}
    exec:
      # Default capture (stdout), so a non-zero exit FAILS the task and the
      # recovery below is what handles it. The tempting alternative — `capture:
      # structured` — turns the exit code into data and the task reports success
      # whatever happened; that is only honest when something downstream reads
      # `exit_code`, and the checker flags the case where nothing does
      # ([swallowed-exit]). Here the failure is visible in the run (« 1
      # recovered ») and labelled in the brief, which is the same information
      # with none of the silence.
      command: ["git", "--no-pager", "shortlog", "-sn", "--since=1 week ago", "HEAD"]
    on_error:
      recover: "(no engineering pulse · git could not be read here)"

  # ── branch 3 · the numbers · the private leg ──
  sheet:
    with:
      go: ${{ tasks.approve.output }}
    when: ${{ with.go == true }}
    invoke:
      tool: "nika:read"
      args: { path: "${{ inputs.kpi_sheet }}" }

  rows:
    with:
      csv: ${{ tasks.sheet.output }}
    # A SKIPPED producer hands its consumer `null`, and the consumer runs anyway.
    # Measured: without this line a « no » at the gate reaches nika:convert with
    # nothing and the run FAILS (NIKA-BUILTIN-CONVERT-002) instead of landing
    # nothing — a refusal must be a quiet no-op, never an error. Every task
    # downstream of a gated one carries its own admission test.
    when: ${{ with.csv != null }}
    invoke:
      tool: "nika:convert"
      args:
        input: "${{ with.csv }}"
        from: csv
        to: json
        has_header: true

  revenue:
    with:
      rows: ${{ tasks.rows.output }}
    when: ${{ with.rows != null }}
    invoke:
      tool: "nika:jq"
      args:
        # CSV cells arrive as STRINGS whatever they look like, so `tonumber`
        # before `add`. Money is arithmetic, never a model's opinion of it.
        input: "${{ with.rows }}"
        expression: "map(.weekly_revenue | tonumber) | add"

  # ── the join · three branches land here, one call ──
  brief:
    with:
      go: ${{ tasks.approve.output }}
      # Every binding is SHALLOW (`.output`, never `.output.field`). Measured:
      # a skipped producer's `.output` reads as `null` and the join survives it,
      # while a deep field of the same skipped producer is NIKA-VAR-001 ·
      # unresolved template reference — bindings resolve before `when:` decides,
      # so a deep read into a « no » path kills the run the gate was meant to
      # spare. Reach one level, gate, then reach deeper downstream.
      news: ${{ tasks.news.output }}
      pulse: ${{ tasks.pulse.output }}
      rows: ${{ tasks.rows.output }}
      revenue: ${{ tasks.revenue.output }}
    when: ${{ with.go == true }}
    infer:
      max_tokens: 1200               # the cost report becomes a ceiling, not UNBOUNDED
      prompt: |
        Market signal · ${{ with.news }}
        Engineering pulse · ${{ with.pulse }}
        Weekly rows · ${{ with.rows }}
        Revenue, summed by the engine · ${{ with.revenue }}

        Write my Monday brief · 5 sections · market · product · numbers ·
        risks · the ONE decision this week needs.
      thinking:
        # A reasoning budget, honoured by seats that support extended thinking
        # and ignored by the ones that do not — declaring it never fails a run.
        enabled: true
        budget_tokens: 4000

  stamp:
    with:
      go: ${{ tasks.approve.output }}
    when: ${{ with.go == true }}
    invoke:
      tool: "nika:date"
      args: { op: now }
    output:
      day: ".[:10]"                  # nika:date returns the ISO string itself · slice YYYY-MM-DD

  save:
    with:
      go: ${{ tasks.approve.output }}   # every effect re-reads the decision · a « no » lands nothing
      day: ${{ tasks.stamp.day }}
      brief: ${{ tasks.brief.output }}
    when: ${{ with.go == true }}
    invoke:
      tool: "nika:write"
      args:
        path: "./briefs/${{ with.day }}-monday.md"
        content: "${{ with.brief }}"
        create_dirs: true

  # ── the ping · a TASK, not a cleanup hook ──
  #
  # `after: {save: terminal}` admits all four settled states, so this fires
  # whether the brief landed, failed, or was skipped by a « no » at the gate.
  # It is deliberately not an `on_finally:` hook: cleanup errors are LOGGED and
  # DO NOT PROPAGATE (03 §on_finally · best-effort lane), so a webhook that
  # dies there dies in silence — measured: an unresolved secret in a cleanup
  # hook leaves the run green with nothing sent. An alert you cannot trust to
  # fail loudly is not an alert.
  alert:
    after:
      save: terminal
    with:
      armed: ${{ inputs.alert }}
      outcome: ${{ tasks.save.status }}   # observe WHAT happened · same pass-set as the after edge
      day: ${{ tasks.stamp.day }}
    when: ${{ with.armed == true }}       # OFF by default · a rehearsal touches no webhook
    invoke:
      tool: "nika:notify"
      args:
        channel: webhook
        target: "${{ secrets.founders_webhook }}"
        message: "Monday brief · ${{ with.outcome }} · briefs/${{ with.day }}-monday.md"
        severity: info

outputs:
  brief: ${{ tasks.brief.output }}
  revenue:
    value: ${{ tasks.revenue.output }}
    description: "Total weekly revenue, summed by jq — the number nobody guessed"
```

## How it works

<Steps>
  <Step title="Three branches, zero coordination code">
    News (HN API through `mode: jq`), engineering pulse (`git shortlog`)
    and the KPI sheet (read → convert → jq `add`) run concurrently. The
    revenue sum is jq arithmetic: deterministic, not model-guessed.
  </Step>

  <Step title="Dates come from a builtin">
    `nika:date` + the `.iso[:10]` binding stamp the filename
    `briefs/2026-06-15-monday.md`. Never let a model guess the date.
  </Step>

  <Step title="The run reports its own bill">
    `nika:inspect view: cost` returns `{total_usd, by_task, by_provider}`.
    The ping interpolates it. Cost-aware automation is automation you
    can leave running.
  </Step>
</Steps>

## Constructs you just used

| Construct                      | Where                        | Reference                        |
| ------------------------------ | ---------------------------- | -------------------------------- |
| 3-branch parallel gather       | `news` · `pulse` · `kpi_raw` | [Workflows](/concepts/workflows) |
| jq arithmetic (`add`)          | `revenue`                    | [Builtins](/reference/builtins)  |
| `nika:inspect view: cost`      | `bill`                       | [Builtins](/reference/builtins)  |
| `output:` binding on a builtin | `stamp`                      | [Bindings](/concepts/bindings)   |

## Make it yours

* Add a fourth branch: support sentiment from [Support triage](/examples/support-triage)'s board file.
* Keep a budget: follow `bill` with `nika:assert` on `total_usd < 1`. The brief refuses to overspend.
* Archive the history: the dated files under `briefs/` are already your decision journal.

<Card title="Back to all examples" icon="rocket" href="/examples/overview">
  You've climbed the whole ladder, starter to epic. Time to write
  yours.
</Card>


# Competitor radar
Source: https://docs.nika.sh/examples/competitor-radar

T3 fan-out · strategy: everything they shipped last week, read in parallel, one Monday brief.

> **T3 fan-out · strategy / product marketing**: the flagship
> `for_each`. The number of pages is decided at RUNTIME by the
> competitor's sitemap; `max_parallel` keeps the crawl polite,
> `fail_fast: false` keeps one dead page from killing the radar,
> `retry:` absorbs the flaky web.

## The job

Monday 8am: what did they ship? Instead of 40 tabs, the sitemap is
mapped, the 8 freshest pages are read concurrently, and one brief tells
you what it signals. Every page that survives lands in the fan-in; every
page that doesn't is reported, not fatal.

## The shape

```mermaid theme={"system"}
flowchart TD
  now["now · nika:date"]:::invoke
  cutoff["cutoff · nika:date"]:::invoke
  cutoff_day["cutoff_day · nika:date"]:::invoke
  map["map · nika:fetch"]:::invoke
  recent["recent · nika:jq"]:::invoke
  pages["pages · ∥ for_each · nika:fetch"]:::invoke
  readable["readable · nika:jq"]:::invoke
  digest["digest"]:::infer
  save["save · nika:write"]:::invoke
  record["record · nika:emit"]:::invoke
  now --> cutoff
  cutoff --> cutoff_day
  map --> recent
  cutoff_day --> recent
  recent --> pages
  recent --> readable
  pages --> readable
  readable --> digest
  cutoff_day --> digest
  digest --> save
  recent --> record
  readable --> record
  cutoff_day --> record
  classDef infer fill:#5b8cff22,stroke:#5b8cff,color:#5b8cff
  classDef invoke fill:#22d3ee22,stroke:#22d3ee,color:#22d3ee
```

## The file

```yaml competitor-radar.nika.yaml theme={"system"}
nika: v1
workflow:
  id: competitor-radar
  description: "sitemap → what changed this window → parallel page reads → one brief"

model: ollama/qwen3.5:4b   # local · zero key · swap for anthropic/claude-sonnet-4-6 for a sharper read

run:
  clock: system            # `pages` declares a `timeout:` · name the clock it rides

inputs:
  sitemap_url:
    type: string
    default: "https://nika.sh/sitemap.xml"
    description: "Whose sitemap to read · must agree with the host in permits.net.http"
  window_days:
    type: integer
    default: 7
    description: "How far back « recently » reaches"
  max_pages:
    type: integer
    default: 6
    description: "Politeness cap · the fan-out never exceeds this many fetches"

permits:
  tools: ["nika:date", "nika:emit", "nika:fetch", "nika:jq", "nika:write"]
  net:
    # ONE host covers BOTH fetches, and that is a claim worth being explicit
    # about: `map` reads the sitemap, then `pages` fetches whatever `.loc`
    # values came back — runtime URLs this file never sees. A sitemap is
    # single-host by protocol, so the site's own host is the honest wall: if
    # their sitemap ever points somewhere else, that fetch is refused instead
    # of followed. Change `inputs.sitemap_url` and this line changes with it.
    http: ["nika.sh"]
  fs:
    # ONE file, named exactly, because the path IS a literal — there is no
    # uuid or date in it, so there is nothing for a wildcard to stand in for.
    # A bound is only as wide as the uncertainty it has to cover.
    #
    # `create_dirs: true` below makes the missing `./radar/` without needing
    # a grant of its own: measured, with only this line, the directory is
    # created and the brief lands. (Builtins that take an `output_dir:`
    # instead — `nika:image_generate` and family — are the opposite case:
    # `check` judges the directory ARGUMENT while the run gates each final
    # file path, so those need the directory AND its children. The bound
    # follows what the builtin names.)
    write: ["./radar/competitor-brief.md"]

tasks:
  # ── how far back does « recently » reach ───────────────────────────
  # Three date ops rather than a hardcoded string, because a radar that ships
  # with a date baked in is wrong the day after you write it. `format` to
  # %Y-%m-%d puts the cutoff in the same shape sitemaps use for `lastmod`,
  # which is what makes the string comparison below sound.
  now:
    invoke:
      tool: "nika:date"
      args: { op: now }

  cutoff:
    with:
      now: ${{ tasks.now.output }}
    invoke:
      tool: "nika:date"
      args:
        op: subtract
        base: "${{ with.now }}"
        duration: "${{ inputs.window_days }}d"

  cutoff_day:
    with:
      cutoff: ${{ tasks.cutoff.output }}
    invoke:
      tool: "nika:date"
      args:
        op: format
        input: "${{ with.cutoff }}"
        format: "%Y-%m-%d"

  # ── what they publish, and when it last moved ──────────────────────
  map:
    invoke:
      tool: "nika:fetch"
      args:
        url: "${{ inputs.sitemap_url }}"
        mode: sitemap                  # → [{loc, lastmod, changefreq, priority}, …]

  # `lastmod` is optional in the sitemap protocol, so `// ""` sends an entry
  # without one outside the window instead of crashing the filter. Newest
  # first, then the politeness cap — the fan-out width is decided here and
  # nowhere else.
  recent:
    with:
      entries: ${{ tasks.map.output }}
      cutoff: ${{ tasks.cutoff_day.output }}
    invoke:
      tool: "nika:jq"
      args:
        input: { entries: "${{ with.entries }}", cutoff: "${{ with.cutoff }}" }
        expression: >-
          .cutoff as $c
          | .entries
          | map(select((.lastmod // "") >= $c))
          | sort_by(.lastmod) | reverse
          | .[:${{ inputs.max_pages }}]
          | map(.loc)

  # ── read them all at once ──────────────────────────────────────────
  pages:
    with:
      urls: ${{ tasks.recent.output }}
    for_each: ${{ with.urls }}
    max_parallel: 4                    # be a good guest · four in flight, no more
    fail_fast: false                   # one dead page must not kill the radar
    on_error:
      recover: null                    # that page yields null at its index · the batch lives
    timeout: "30s"                     # somebody else's server, somebody else's bad day
    retry:
      max_attempts: 3
      backoff_strategy: exponential
      jitter: true                     # a swarm that retries in lockstep is a small DDoS
    invoke:
      tool: "nika:fetch"
      args:
        url: "${{ item }}"
        mode: article                  # readability extraction · the prose, not the chrome

  # ── the fan-in · a for_each output is an array in ITEM ORDER ───────
  # which is what lets `transpose` put each page's text back beside its own
  # URL. The `select` is where the pages that never answered leave.
  readable:
    with:
      urls: ${{ tasks.recent.output }}
      pages: ${{ tasks.pages.output }}
    invoke:
      tool: "nika:jq"
      args:
        input: ["${{ with.urls }}", "${{ with.pages }}"]
        expression: >-
          transpose
          | map(select(.[1] != null))
          | map({ url: .[0], text: .[1] })

  digest:
    with:
      readable: ${{ tasks.readable.output }}
      cutoff: ${{ tasks.cutoff_day.output }}
    when: ${{ size(with.readable) > 0 }}   # a quiet week costs nothing
    infer:
      max_tokens: 1500                     # one page · a ceiling, not a hope
      prompt: |
        These are the pages a competitor published or changed since
        ${{ with.cutoff }} ·
        ${{ with.readable }}
        Write the Monday brief · what they shipped · what it signals · what
        we should watch. One page, plain words, no filler.

  save:
    with:
      digest: ${{ tasks.digest.output }}
    when: ${{ with.digest != null }}   # a skipped task reads null downstream · gate on the VALUE
    invoke:
      tool: "nika:write"
      args:
        path: "./radar/competitor-brief.md"
        content: "${{ with.digest }}"
        create_dirs: true

  # The « it is ready » signal, as a LOCAL journal event. No webhook, no
  # secret, no host: the brief is on disk and the event says so. A radar that
  # needed an outbound credential to tell you it had finished would be a
  # strictly larger blast radius for no extra information.
  record:
    with:
      urls: ${{ tasks.recent.output }}
      readable: ${{ tasks.readable.output }}
      cutoff: ${{ tasks.cutoff_day.output }}
    invoke:
      tool: "nika:emit"
      args:
        event_type: "competitor.radar.scan"
        payload:
          since: ${{ with.cutoff }}
          selected: ${{ with.urls }}
          read_ok: ${{ with.readable }}

outputs:
  since:
    value: ${{ tasks.cutoff_day.output }}
    description: "The computed window start · what « recently » meant on this run"
  pages:
    value: ${{ tasks.recent.output }}
    description: "The URLs the sitemap said had changed inside that window"
  brief:
    value: ${{ tasks.digest.output }}
    description: "The Monday brief · null when the week was quiet"
```

## How it works

<Steps>
  <Step title="The collection is computed, not hardcoded">
    The URL list crosses the boundary
    (`map_recent: ${{ tasks.map.recent }}` in `with:`), then
    `for_each: ${{ with.map_recent }}` fans out: eight URLs this week,
    three next week. The DAG doesn't change.
  </Step>

  <Step title="Resilience is per-iteration">
    `retry:` (exponential + jitter) and `timeout: "30s"` apply to EACH
    page fetch. `fail_fast: false` collects errors instead of aborting
    the batch.
  </Step>

  <Step title="The fan-in is just a reference">
    `${{ tasks.pages.output }}` is the ARRAY of per-page outputs, in
    input order. One prompt consumes the whole crawl.
  </Step>
</Steps>

## Constructs you just used

| Construct                           | Where            | Reference                             |
| ----------------------------------- | ---------------- | ------------------------------------- |
| `for_each` over a binding           | `pages`          | [Workflows](/concepts/workflows)      |
| `max_parallel` + `fail_fast`        | `pages`          | [Workflows](/concepts/workflows)      |
| per-iteration `retry:` + `timeout:` | `pages`          | [Error model](/reference/error-codes) |
| `${{ item }}` loop-local            | `pages.args.url` | [Bindings](/concepts/bindings)        |

## Make it yours

* Track THREE competitors: lift the sitemap URL into a list and nest the pattern, or run the workflow per competitor and merge the briefs.
* Filter the sitemap by date with a sharper jq binding before fanning out.
* Schedule it for Monday 07:30 from your host's cron. The brief is on your desk before standup.

<Card title="Next · Localization factory" icon="language" href="/examples/localization-factory">
  Chained fan-outs and the jq `transpose` zip: the whole docs tree,
  translated.
</Card>


# Config drift sentinel
Source: https://docs.nika.sh/examples/config-drift-sentinel

T3 · SRE: only unsanctioned prod drift wakes anyone. jq decides; the model explains.

> **T3 · SRE / platform**: the deterministic-core pattern at its
> sharpest. Approved overrides merge into the baseline (RFC 7396), the
> live config diffs against THAT (RFC 6902), blake3 fingerprints the
> evidence, and the LLM's only job is explaining the patch to a human
> at 3am.

## The job

« Did anyone change prod config without telling us? » Pure-diff
monitors page you for every sanctioned change too: alert fatigue. This
sentinel knows what was approved: it reconstructs the EXPECTED state
first, so the diff contains only the drift nobody signed off on.

## The shape

```mermaid theme={"system"}
flowchart TD
  live_raw["live_raw · nika:fetch"]:::invoke
  baseline_raw["baseline_raw · nika:read"]:::invoke
  fingerprint["fingerprint · nika:hash"]:::invoke
  parsed["parsed · nika:jq"]:::invoke
  expected["expected · nika:json_merge_patch"]:::invoke
  drift["drift · nika:json_diff"]:::invoke
  paging["paging · nika:jq"]:::invoke
  explain["explain"]:::infer
  alert["alert · nika:notify"]:::invoke
  record["record · nika:emit"]:::invoke
  live_raw --> fingerprint
  live_raw --> parsed
  baseline_raw --> parsed
  parsed --> expected
  expected --> drift
  parsed --> drift
  drift --> paging
  drift --> explain
  paging --> alert
  drift --> record
  paging --> record
  fingerprint --> record
  explain --> record
  classDef infer fill:#5b8cff22,stroke:#5b8cff,color:#5b8cff
  classDef invoke fill:#22d3ee22,stroke:#22d3ee,color:#22d3ee
```

## The file

```yaml config-drift-sentinel.nika.yaml theme={"system"}
nika: v1
workflow:
  id: config-drift-sentinel
  description: "live config vs sanctioned baseline → typed drift → triaged, explained alert"

model: ollama/qwen3.5:4b   # local · zero key · swap for anthropic/claude-haiku-4-5 (explain is cheap)

inputs:
  config_url:
    type: string
    default: "https://api.internal.example.com/v1/config"
    description: "The live-config endpoint · the placeholder resolves nowhere, which is what makes the default run a rehearsal"

const:
  # The committed rehearsal baseline. Point this at your real intended state
  # and change `permits.fs.read` in the same edit — a permit is a literal you
  # can read, it cannot interpolate a const (`NIKA-AUTH-007`).
  baseline_path: "./examples/fixtures/config-baseline.json"

  # Sanctioned drift · an RFC 7396 merge patch applied to the baseline before
  # the diff. `{}` means « nothing is pre-approved ».
  #
  # This is a BARE LITERAL, deliberately. A typed constant is `{ type, value }`
  # and nothing else: an object missing either key is read as a literal object
  # (`01-envelope.md:273`). Writing `{ type: object, default: {} }` here would
  # declare nothing — `${{ const.approved_overrides }}` would resolve to that
  # whole three-key map. Measured, with `{ replicas: 6 }` as the baseline:
  #   {"default":{},"description":"…","replicas":6,"type":"object"}
  # No error, no warning. The sentinel would just spend every morning diffing
  # prod against a config nobody ever intended.
  approved_overrides: {}

  # An RFC 6902 patch path starting with one of these can take the service
  # down. Everything else is recorded and read in the morning. The list lives
  # here, in the file, instead of inside a prompt: paging policy is reviewable.
  paging_prefixes: ["/replicas", "/feature_flags", "/upstreams", "/limits"]

secrets:
  oncall_webhook:
    source: env
    key: ONCALL_WEBHOOK_URL
    egress:                       # sanction the one send · the secret IS the URL
      - to: "nika:notify"
        host_from_self: true

permits:
  tools: ["nika:emit", "nika:fetch", "nika:hash", "nika:jq", "nika:json_diff", "nika:json_merge_patch", "nika:notify", "nika:read"]
  net:
    # TWO hosts, two different jobs.
    #
    # `host_from_self:` above sanctions the FLOW (this secret may be the URL)
    # — it does not grant the capability. The webhook host stays unknown at
    # check time, so it is judged at RUN against this list: name the
    # escalation host here or the page is refused mid-run, after the drift
    # has already been found. Measured, all three cases · with the host
    # absent, or with some other host named, `check` is green and the run
    # dies `NIKA-SEC-004 · <host> resolves outside the declared net.http
    # boundary`; with it named, the permit clears and the send goes out.
    http:
      - "api.internal.example.com"   # the config endpoint this sentinel polls
      - "hooks.slack.com"            # where the page goes · swap for your own
  fs:
    # Read-only by design: a drift sentinel OBSERVES prod, it never edits it.
    # There is no `write:` key at all, so every path on this machine is denied
    # for writes — the baseline is the one file this workflow may open.
    read: ["./examples/fixtures/config-baseline.json"]

tasks:
  # ── what prod says it is · as BYTES ────────────────────────────────
  # `mode: raw` keeps the response as the string the server sent, which is
  # what `fingerprint` hashes below. The recovery value is that same string:
  # a real HTTP body, one benign step off the baseline (log_level info →
  # debug), so the triage downstream has something honest to triage. Point
  # `--var config_url=` at a live endpoint and this branch never runs.
  live_raw:
    on_error:
      recover: '{"service":"checkout-api","replicas":6,"log_level":"debug","feature_flags":{"beta_ui":false,"instant_refunds":true,"queue_v2":false},"limits":{"request_timeout_ms":2500,"max_body_bytes":1048576},"upstreams":{"ledger":"https://ledger.internal.example.com","risk":"https://risk.internal.example.com"}}'
    retry:
      max_attempts: 3
      backoff_strategy: exponential
    invoke:
      tool: "nika:fetch"
      args:
        url: "${{ inputs.config_url }}"
        mode: raw

  # ── what prod is supposed to be · also bytes ───────────────────────
  baseline_raw:
    invoke:
      tool: "nika:read"              # returns a STRING · a file is text until you parse it
      args: { path: "${{ const.baseline_path }}" }

  # Provenance over the exact response bytes, taken BEFORE the parse: two
  # different JSON texts that mean the same thing hash differently, and that
  # is the point — this attests the artifact, not the interpretation.
  # `nika:hash` requires `content:` to be a string; handing it the parsed
  # object fails `NIKA-BUILTIN-HASH-001` at run while `check` stays green.
  fingerprint:
    with:
      raw: ${{ tasks.live_raw.output }}
    invoke:
      tool: "nika:hash"
      args:
        algo: blake3
        content: "${{ with.raw }}"
        encoding: hex

  # ── text becomes data, in one place ────────────────────────────────
  # Both sides are parsed together so the « where did this stop being a
  # string » question has exactly one answer in this file. `json_merge_patch`
  # and `json_diff` take OBJECTS: feeding either one the raw string fails
  # `NIKA-BUILTIN-JSON_MERGE_PATCH-001` at run, and `check` cannot see it
  # coming — the type only exists once the tool has run.
  parsed:
    with:
      live: ${{ tasks.live_raw.output }}
      baseline: ${{ tasks.baseline_raw.output }}
    invoke:
      tool: "nika:jq"
      args:
        input: { live: "${{ with.live }}", baseline: "${{ with.baseline }}" }
        expression: "{ live: (.live | fromjson), baseline: (.baseline | fromjson) }"

  expected:
    with:
      baseline: ${{ tasks.parsed.output.baseline }}
    invoke:
      tool: "nika:json_merge_patch"     # RFC 7396 · objects merge, null deletes
      args:
        target: "${{ with.baseline }}"
        patch: "${{ const.approved_overrides }}"

  # ── the difference, as data ────────────────────────────────────────
  drift:
    with:
      expected: ${{ tasks.expected.output }}
      live: ${{ tasks.parsed.output.live }}
    invoke:
      tool: "nika:json_diff"            # RFC 6902 · [{op, path, value}, …]
      args:
        before: "${{ with.expected }}"
        after: "${{ with.live }}"

  # ── triage · which of those operations is worth a phone call ───────
  # `any($p[]; …)` is true when the operation's path starts with any prefix.
  # A log_level change survives the diff and dies right here, which is the
  # difference between a sentinel people keep and one they mute.
  paging:
    with:
      patch: ${{ tasks.drift.output }}
    invoke:
      tool: "nika:jq"
      args:
        input: { patch: "${{ with.patch }}", prefixes: "${{ const.paging_prefixes }}" }
        expression: >-
          .prefixes as $p
          | .patch
          | map(select(.path as $path | any($p[]; . as $pre | $path | startswith($pre))))

  explain:
    with:
      patch: ${{ tasks.drift.output }}
    when: ${{ size(with.patch) > 0 }}   # a clean scan spends nothing
    on_error:
      recover: "(explanation unavailable · the model call failed · the raw patch is attached)"
    infer:
      max_tokens: 600                   # three bullets · a ceiling, not a hope
      prompt: |
        This RFC 6902 patch is UNSANCTIONED config drift in production ·
        ${{ with.patch }}
        Explain in 3 bullets · what changed · likely blast radius · first check.

  # ── the page carries the FACT · never the payload ──────────────────
  #
  # All three trifecta legs are structural here: the baseline is a private
  # read, the live config is untrusted ingress, and the webhook is external
  # egress. Interpolating the diff — or the explanation derived from it —
  # into this message would be a realized flow: someone who can move prod
  # config could shape the diff until it echoes baseline values out through
  # the webhook. So the page says THAT drift happened and where to look; the
  # drift itself goes to the journal below, which never leaves the machine.
  # `when:` may still read the patch — a gate decides, it does not transmit.
  alert:
    with:
      paging: ${{ tasks.paging.output }}
    when: ${{ size(with.paging) > 0 }}
    invoke:
      tool: "nika:notify"
      args:
        channel: webhook
        target: "${{ secrets.oncall_webhook }}"
        message: "Unsanctioned config drift on a paging path · details in the config.drift.scan journal event"
        severity: critical

  # `nika:emit` is a LOCAL event · it needs no `net:` grant because nothing
  # leaves the machine. The full patch, the provenance fingerprint and the
  # explanation land here, where whoever answers the page reads them. On a
  # clean scan `explain` is gated off and resolves null — the scan is still
  # recorded, which is how you prove the sentinel ran at all.
  record:
    with:
      patch: ${{ tasks.drift.output }}
      paging: ${{ tasks.paging.output }}
      live_hash: ${{ tasks.fingerprint.output }}
      explanation: ${{ tasks.explain.output }}
    invoke:
      tool: "nika:emit"
      args:
        event_type: "config.drift.scan"
        payload:
          patch: ${{ with.patch }}
          paging: ${{ with.paging }}
          live_hash: ${{ with.live_hash }}
          explanation: ${{ with.explanation }}

outputs:
  drift:
    value: ${{ tasks.drift.output }}
    description: "RFC 6902 operations · empty when prod matches the sanctioned state"
  paging:
    value: ${{ tasks.paging.output }}
    description: "The subset of those operations that is worth a phone call"
  live_hash:
    value: ${{ tasks.fingerprint.output }}
    description: "blake3 of the exact response bytes · the provenance receipt"
```

## How it works

<Steps>
  <Step title="RFC 7396 reconstructs the sanctioned state">
    `nika:json_merge_patch` applies the approved overrides to the
    baseline: `null` deletes a key, exactly per the RFC. This is the
    builtin jq's recursive merge can't replace.
  </Step>

  <Step title="RFC 6902 names what actually changed">
    `nika:json_diff` returns a standard JSON Patch: machine-readable
    operations, not a text diff. Empty patch = healthy prod = total
    silence.
  </Step>

  <Step title="Evidence travels with the alert">
    The blake3 fingerprint of the live config rides in the alert AND in
    the `nika:emit` journal event. When you investigate later, you know
    exactly which state fired.
  </Step>
</Steps>

## Constructs you just used

| Construct                          | Where         | Reference                       |
| ---------------------------------- | ------------- | ------------------------------- |
| `nika:json_merge_patch` (RFC 7396) | `expected`    | [Builtins](/reference/builtins) |
| `nika:json_diff` (RFC 6902)        | `drift`       | [Builtins](/reference/builtins) |
| `nika:hash` blake3                 | `fingerprint` | [Builtins](/reference/builtins) |
| `nika:emit` machine events         | `record`      | [Events](/concepts/events)      |

## Make it yours

* Run it every 15 minutes from your scheduler; the `record` event stream becomes your drift history.
* Watch N services: lift the URL + baseline into a list and `for_each` the whole sentinel body.
* Auto-remediate the SAFE class: a `when:` branch that opens a revert PR via your MCP git server.

<Card title="Next · PR review fan-out" icon="code-pull-request" href="/examples/pr-review-fanout">
  One read-only agent per changed file: the swarm pattern, with a
  deterministic grep sweep beside it.
</Card>


# Contract guard
Source: https://docs.nika.sh/examples/contract-guard

T2 chain · legal: clause extraction on a LOCAL model. The contract never leaves the machine.

> **T2 chain · legal / compliance**: `model: ollama/llama3.2:3b` at the
> envelope means **every** model call in this file runs on your own
> hardware. For a contract, that's not a preference. It's the
> requirement. Belt-and-braces: `schema:` at infer time, `nika:validate`
> after, `nika:assert` as the hard gate.

## The job

Outside counsel takes a week. Pasting the contract into a cloud chatbot
takes your confidentiality with it. This workflow extracts every
risk-bearing clause (verbatim quotes, typed risk levels) locally,
re-validates the extraction, and refuses to write the memo if the data
doesn't hold.

## The shape

```mermaid theme={"system"}
flowchart LR
  contract["contract · nika:read"]:::invoke
  clauses["clauses · typed"]:::infer
  check["check · nika:validate"]:::invoke
  gate["gate · nika:assert"]:::invoke
  memo["memo"]:::infer
  save["save · nika:write"]:::invoke
  contract --> clauses
  clauses --> check
  check --> gate
  clauses --> memo
  gate -.->|success| memo
  memo --> save
  classDef infer fill:#5b8cff22,stroke:#5b8cff,color:#5b8cff
  classDef invoke fill:#22d3ee22,stroke:#22d3ee,color:#22d3ee
```

## The file

```yaml contract-guard.nika.yaml theme={"system"}
nika: v1
workflow:
  id: contract-guard
  description: "Local-model clause extraction → schema gate → risk memo"

# Local · the whole review runs offline, zero cloud. Also a NON-thinking
# model on purpose: a thinking model can spend the whole `max_tokens` budget
# in its think block and return before the JSON (engine#428).
model: ollama/llama3.2:3b

inputs:
  contract_path:
    type: string
    default: "examples/fixtures/contract.md"
    description: "Path to the contract (markdown or plain text)"
permits:
  tools: ["nika:assert", "nika:read", "nika:validate", "nika:write"]
  fs:
    # `permits:` cannot interpolate (NIKA-AUTH-007), so this literal does not
    # follow `inputs.contract_path` around: passing --var without editing this
    # line is refused at run with NIKA-SEC-004. Deliberate — a reviewer can
    # see every file this workflow may open by reading four words.
    read: ["examples/fixtures/contract.md"]
    write: ["out/risk-memo.md"]

tasks:
  contract:
    invoke:
      tool: "nika:read"
      args: { path: "${{ inputs.contract_path }}" }

  clauses:
    with:
      contract: ${{ tasks.contract.output }}
    infer:
      max_tokens: 1600
      prompt: |
        Extract every risk-bearing clause from this contract ·
        ${{ with.contract }}
        Quote each clause verbatim · classify its risk.
      schema:
        type: object
        additionalProperties: false
        required: [clauses]
        properties:
          clauses:
            type: array
            items:
              type: object
              additionalProperties: false
              required: [quote, type, risk]
              properties:
                quote: { type: string }
                type: { type: string, enum: [liability, termination, ip, payment, data, other] }
                risk: { type: string, enum: [low, medium, high] }

  check:
    with:
      clauses: ${{ tasks.clauses.output }}
    invoke:
      tool: "nika:validate"
      args:
        data: "${{ with.clauses }}"
        format: json
        schema:
          type: object
          required: [clauses]
          properties:
            clauses:
              type: array
              minItems: 1        # an empty extraction is a FAILED extraction

  gate:
    with:
      extraction_ok: ${{ tasks.check.output.valid == true }}   # the whole condition crosses as ONE boundary expression
    invoke:
      tool: "nika:assert"
      args:
        condition: "${{ with.extraction_ok }}"
        message: "Clause extraction failed the schema gate: refusing to write the memo"

  memo:
    with:
      clauses: ${{ tasks.clauses.output.clauses }}
    after:
      gate: success              # state, no data · the assert passed or the memo is cancelled
    infer:
      max_tokens: 1200
      prompt: |
        Write a one-page risk memo from these clauses ·
        ${{ with.clauses }}
        Order by risk · high first · cite the quoted text.

  save:
    with:
      memo: ${{ tasks.memo.output }}
    invoke:
      tool: "nika:write"
      args:
        path: out/risk-memo.md
        content: "${{ with.memo }}"
        create_dirs: true

outputs:
  clauses:
    value: ${{ tasks.clauses.output.clauses }}
    description: "Typed risk-bearing clauses, verbatim quotes"
  memo: ${{ tasks.memo.output }}
```

## How it works

<Steps>
  <Step title="Sovereignty is one line">
    The envelope `model:` points at Ollama. Same file, same schema, same
    everything, just no cloud. Swap back to a cloud provider for
    non-sensitive documents; the workflow doesn't change shape.
  </Step>

  <Step title="validate re-checks what schema promised">
    `nika:validate` runs the extraction against a second, stricter
    schema (`minItems: 1`) and returns `{valid, errors}`: belt and
    braces for legal-grade output.
  </Step>

  <Step title="assert is the fail-fast guard">
    `when:` skips; `nika:assert` FAILS. A memo built on a bad extraction
    is worse than no memo, so the gate throws, loudly.
  </Step>
</Steps>

## Constructs you just used

| Construct                   | Where             | Reference                        |
| --------------------------- | ----------------- | -------------------------------- |
| local provider (`ollama/…`) | envelope `model:` | [Providers](/concepts/providers) |
| `nika:validate`             | `check`           | [Builtins](/reference/builtins)  |
| `nika:assert` vs `when:`    | `gate`            | [Builtins](/reference/builtins)  |
| verbatim-quote schema       | `clauses`         | [The 4 verbs](/concepts/verbs)   |

## Make it yours

* Compare against your clause playbook: `nika:read` the playbook + a second `infer` that flags deviations.
* Batch a folder of NDAs: `nika:glob` + `for_each` ([Localization factory](/examples/localization-factory) shows the chained fan-out).
* HR version: same shape over candidate agreements or policy docs. Sensitive data, local model, typed findings.

<Card title="Level up · T3 fan-out" icon="satellite-dish" href="/examples/competitor-radar">
  Next tier: collections the workflow discovers at runtime, processed in
  parallel with retry and a leash.
</Card>


# CSV chart report
Source: https://docs.nika.sh/examples/csv-chart-report

T2 chain · data → picture: paste the spreadsheet, get the slide. Offline, deterministic, zero model calls.

> **T2 chain · data → picture**: `nika:read` loads the CSV,
> `nika:convert` types it into rows, `nika:jq` aggregates by region,
> `nika:chart` renders the bar chart as a real image, and `nika:write`
> assembles the markdown report around it. Five tasks, zero model
> calls — the whole pipeline is deterministic data plumbing.

## The job

The Monday deck needs one chart and one table, and the ritual is
always the same: open the sheet, pivot, screenshot, paste. This
workflow replaces the ritual with a file — drop the CSV, run once,
and the report (chart image + aggregate table) is on disk, identical
every time the data is identical.

## The shape

```mermaid theme={"system"}
flowchart LR
  raw["raw · nika:read"]:::invoke
  rows["rows · nika:convert"]:::invoke
  by_region["by_region · nika:jq"]:::invoke
  chart["chart · nika:chart"]:::invoke
  rows_md["rows_md · nika:jq"]:::invoke
  report["report · nika:write"]:::invoke
  raw --> rows
  rows --> by_region
  by_region --> chart
  by_region --> rows_md
  rows_md --> report
  chart -.->|success| report
  classDef invoke fill:#22d3ee22,stroke:#22d3ee,color:#22d3ee
```

## The file

```yaml csv-chart-report.nika.yaml theme={"system"}
nika: v1
workflow:
  id: csv-chart-report
  description: "CSV → aggregate → rendered bar chart + markdown report · offline · deterministic"

const:
  sales_csv: "examples/fixtures/sales.csv" # columns · region,revenue (revenue a plain number)

permits:
  exec: false
  tools: ["nika:chart", "nika:convert", "nika:jq", "nika:read", "nika:write"]
  fs:
    # The one CSV this reads, named exactly. `data/**` would have granted a
    # whole tree to a workflow that opens a single file.
    read: ["examples/fixtures/sales.csv"]
    # Two artifacts land here — the SVG and the report page. `**` because the
    # chart and the report are written by two different builtins into the
    # same tree, and both are covered by one honest entry.
    write: ["out/**"]

tasks:
  raw:
    invoke:
      tool: "nika:read"
      args: { path: "${{ const.sales_csv }}" }

  rows:
    with:
      raw: ${{ tasks.raw.output }}
    invoke:
      tool: "nika:convert"
      args:
        input: "${{ with.raw }}"
        from: csv
        to: json
        has_header: true

  # Sum revenue per region · a deterministic reduce, no model.
  by_region:
    with:
      rows: ${{ tasks.rows.output }}
    invoke:
      tool: "nika:jq"
      args:
        input: "${{ with.rows }}"
        expression: 'group_by(.region) | map({ region: .[0].region, revenue: (map(.revenue | tonumber) | add) })'

  # The picture · one SVG, its sha lands in the trace.
  chart:
    with:
      by_region: ${{ tasks.by_region.output }}
    invoke:
      tool: "nika:chart"
      args:
        data: "${{ with.by_region }}"
        semantics: { region: category, revenue: usd }
        chart: { type: bar, x: region, y: revenue, title: "Revenue by region" }
        out: out/revenue-by-region.svg

  # The rows as MARKDOWN · a report renders lines, never a JSON blob
  # (region names are user data — the esc guards a `|` in them).
  rows_md:
    with:
      by_region: ${{ tasks.by_region.output }}
    invoke:
      tool: "nika:jq"
      args:
        input: "${{ with.by_region }}"
        expression: >-
          def esc: tostring | gsub("\\|"; "\\|") | gsub("\n"; " ");
          map("| \(.region | esc) | \(.revenue) |") | join("\n")

  # The page · the report references the picture beside it.
  report:
    with:
      rows_md: ${{ tasks.rows_md.output }}
    after:
      chart: success
    invoke:
      tool: "nika:write"
      args:
        path: out/revenue-report.md
        content: |
          # Revenue by region

          ![Revenue by region](revenue-by-region.svg)

          | region | revenue |
          | --- | --- |
          ${{ with.rows_md }}

          *Generated offline by [nika](https://nika.sh) · the chart's sha is in the run trace (`nika trace verify`).*

outputs:
  by_region:
    value: ${{ tasks.by_region.output }}
    description: "Per-region revenue totals · the chart + report render from this"
```

## What this file teaches

* **`nika:convert` is the typed seam** — CSV text becomes structured
  rows once, at one task, and everything downstream works on data,
  not strings. The jq aggregation reads fields, never re-parses.
* **A chart is an artifact, not a side effect** — `nika:chart` returns
  a rendered image the report links by path. Re-running with the same
  CSV produces the same bytes: the chart can live in git, and a diff
  on it means the *data* moved.
* **No model, no bill, no network** — `nika check` shows an empty cost
  interval, and the run works on a plane. Determinism is the feature:
  this is the workflow you trust in a cron.

## Run it

```bash theme={"system"}
git clone https://github.com/supernovae-st/nika-spec && cd nika-spec
nika run examples/showcase/t2-csv-chart-report.nika.yaml
open out/revenue-report.md
```

<Note>
  This workflow is newer than the currently shipped engine pack:
  `nika examples run showcase/t2-csv-chart-report` says
  `unknown example` until the next engine tag re-vendors the pack.
  Until then, run it from the spec checkout as above — the file is the
  same one the pack will embed, sha-pinned in the spec manifest.
</Note>

Swap the bundled sample for your own export by pointing
`const.sales_csv` at it — the aggregation key and the chart spec are
the only two lines to adapt.


# Deep research brief
Source: https://docs.nika.sh/examples/deep-research-brief

T4 epic · research: plan → budgeted research agent → thinking-model synthesis. Auditable end to end.

> **T4 epic · research / consulting / VC**: plan-then-execute. A fast
> model writes the plan, an agent works the web **under explicit
> budgets**, a thinking model synthesizes. Three stages, three different
> cost profiles, every intermediate on disk.

## The job

« Get me up to speed on X by Thursday » is two days of tabs, or it's
this pipeline: four sharp queries planned, researched with verbatim
quotes and source tracking, synthesized into an executive brief that
separates what's true from what's contested.

## The shape

```mermaid theme={"system"}
flowchart LR
  slug["slug · nika:jq"]:::invoke
  plan["plan · typed"]:::infer
  investigate["investigate · 2 tools"]:::agent
  brief["brief · thinking"]:::infer
  save["save · nika:write"]:::invoke
  plan --> investigate
  investigate --> brief
  slug --> save
  brief --> save
  classDef infer fill:#5b8cff22,stroke:#5b8cff,color:#5b8cff
  classDef invoke fill:#22d3ee22,stroke:#22d3ee,color:#22d3ee
  classDef agent fill:#b07bff22,stroke:#b07bff,color:#b07bff
```

## The file

```yaml deep-research-brief.nika.yaml theme={"system"}
nika: v1
workflow:
  id: deep-research-brief
  description: "plan → budgeted research agent → thinking synthesis → brief on disk"

model: ollama/qwen3.5:4b   # local · zero key · `--model mock/echo` rehearses the whole file

inputs:
  topic:
    type: string
    default: "local-first AI runtimes"
    description: "What to research · free text (--var topic=…), and it never touches a path directly"

permits:
  tools: ["nika:done", "nika:fetch", "nika:jq", "nika:write"]
  net:
    # There is no `*` here and there never will be: `net.http` entries are exact
    # host names. An agent told to « research the web » therefore cannot — the
    # corpus it may reach is a decision taken HERE, before the loop starts,
    # rather than discovered afterwards in a trace. Add the sources you actually
    # trust; the agent's fetch is judged against this list at RUN, and `check`
    # cannot see it coming because the agent chooses its own URLs.
    http:
      - "arxiv.org"
      - "export.arxiv.org"
      - "en.wikipedia.org"
      - "hn.algolia.com"
  fs:
    # One brief per topic, written DIRECTLY in ./research/. `*` matches a single
    # segment and never crosses `/`, so even a slug that somehow kept a slash is
    # refused rather than steered into a subtree — `./research/**` would let it
    # through. The slug task below makes that doubly hard; the wall makes it
    # impossible, and only one of the two is a guarantee.
    write: ["./research/*.md"]

tasks:
  # The topic is free text — « Local-First AI Runtimes: a survey/2026 » — and it
  # ends up in a filename. Deriving the slug in jq keeps that arithmetic out of
  # the model AND out of the path: the expression is total, so there is no input
  # for which it returns something containing a separator.
  slug:
    invoke:
      tool: "nika:jq"
      args:
        input: "${{ inputs.topic }}"
        expression: 'ascii_downcase | gsub("[^a-z0-9]+"; "-") | gsub("^-|-$"; "")'

  plan:
    infer:
      max_tokens: 400              # planning is short · cap it and the cost report is a ceiling
      prompt: "Break '${{ inputs.topic }}' into 4 sharp research queries · no overlap."
      schema:
        # `additionalProperties: false` on every object node — without it the
        # shape is a suggestion and each provider answers with a slightly
        # different object. `plan.output.queries` is read below, so it has to be
        # a promise, not a hope.
        type: object
        additionalProperties: false
        required: [queries]
        properties:
          queries:
            type: array
            items: { type: string }

  investigate:
    with:
      queries: ${{ tasks.plan.output.queries }}
    agent:
      system: |
        You are a rigorous researcher. Work the queries one by one · fetch
        sources · keep verbatim quotes · note what each source actually
        supports, and what it does not. If a fetch is refused, record that the
        source was out of bounds rather than substituting another.
        Call nika:done when the plan is exhausted.
      prompt: "Research plan · ${{ with.queries }}"
      tools:
        # Every id here must also appear in `permits.tools` above — `check`
        # refuses the mismatch statically (NIKA-SEC-004 · agent tool … is
        # outside permits.tools). Note what is NOT granted: `nika:write`. The
        # agent's product is the typed object it returns, so it never needs a
        # file of its own, and the workflow keeps the only pen in the room.
        - "nika:fetch"                 # the corpus named in permits.net.http
        - "nika:done"                  # the loop-completion sentinel
      max_turns: 25                    # the leash · a loop that cannot end is a bill
      max_tokens_total: 150000         # and the second leash, in tokens
      schema:
        type: object
        additionalProperties: false
        required: [findings, sources]
        properties:
          findings:
            type: array
            items: { type: string }
          sources:
            type: array
            items: { type: string }

  brief:
    with:
      findings: ${{ tasks.investigate.output.findings }}
      sources: ${{ tasks.investigate.output.sources }}
    infer:
      max_tokens: 2000
      prompt: |
        Findings · ${{ with.findings }}
        Sources · ${{ with.sources }}
        Write the executive brief · what's true · what's contested · what it
        means · what to do. Two pages max. Anything the sources do not support
        goes in « contested », never in « true ».
      thinking:
        # A reasoning budget, honoured by seats that support extended thinking
        # and ignored by the ones that do not — declaring it never fails a run.
        enabled: true
        budget_tokens: 8000

  save:
    with:
      slug: ${{ tasks.slug.output }}
      brief: ${{ tasks.brief.output }}
    invoke:
      tool: "nika:write"
      args:
        path: "./research/${{ with.slug }}.md"
        content: "${{ with.brief }}"
        create_dirs: true

outputs:
  brief: ${{ tasks.brief.output }}
  sources:
    value: ${{ tasks.investigate.output.sources }}
    description: "Every source the agent actually used"
  slug:
    value: ${{ tasks.slug.output }}
    description: "The filename stem the brief landed under · ./research/<slug>.md"
```

## How it works

<Steps>
  <Step title="Right model, right stage">
    Planning is a haiku-class job (`model:` override on the task);
    synthesis gets a `thinking:` budget. The envelope default covers the
    middle. One file, three cost profiles.
  </Step>

  <Step title="The agent has a leash">
    `max_turns: 25` + `max_tokens_total: 150000` bound the loop;
    `nika:done` lets it exit cleanly when the plan is exhausted. The
    final message must match the schema: findings AND sources.
  </Step>

  <Step title="Callable by other workflows">
    The typed `outputs:` (`brief`, `sources`) make this a building
    block: a parent workflow can consume the contract without parsing
    prose.
  </Step>
</Steps>

## Constructs you just used

| Construct                   | Where         | Reference                             |
| --------------------------- | ------------- | ------------------------------------- |
| per-task `model:` override  | `plan`        | [Providers](/concepts/providers)      |
| agent budgets + `nika:done` | `investigate` | [The 4 verbs](/concepts/verbs)        |
| `thinking:`                 | `brief`       | [The 4 verbs](/concepts/verbs)        |
| typed `outputs:`            | envelope tail | [YAML syntax](/reference/yaml-syntax) |

## Make it yours

* Force source-grounding harder: have `brief` cite `${{ tasks.investigate.output.sources }}` inline per claim.
* Competitive variant: seed `plan` with [Competitor radar](/examples/competitor-radar)'s digest instead of a bare topic.
* Weekly cadence: pair with your scheduler and diff this week's brief against last week's with `nika:json_diff`.

<Card title="Next · Incident war room" icon="fire-extinguisher" href="/examples/incident-war-room">
  Parallel evidence gathering, a settle-and-recheck loop, and a
  postmortem that refuses to claim recovery it can't prove.
</Card>


# ETL quarantine
Source: https://docs.nika.sh/examples/etl-quarantine

T2 chain · data engineering: bad batches degrade to a quarantine file instead of killing the pipeline.

> **T2 chain · data engineering**: the `on_error: recover:` example.
> The difference between « re-run the whole night » and « fix three
> rows tomorrow morning » is one block: bad data is **data**, not an
> exception.

## The job

The nightly batch dies at row 14,203 and the whole pipeline dies with
it. Here the malformed-CSV case recovers to an empty batch, the schema
gate splits good from bad, rejects land in a quarantine file with
their validation errors, and the good rows aggregate per currency,
in jq, deterministically.

## The shape

```mermaid theme={"system"}
flowchart LR
  empty_batch["empty_batch · nika:jq"]:::invoke
  raw["raw · nika:read"]:::invoke
  rows["rows · nika:convert"]:::invoke
  check["check · nika:validate"]:::invoke
  good["good · nika:jq"]:::invoke
  quarantine["quarantine · nika:write"]:::invoke
  report["report · nika:write"]:::invoke
  raw --> rows
  rows --> check
  rows --> good
  check --> good
  check --> quarantine
  good --> report
  classDef invoke fill:#22d3ee22,stroke:#22d3ee,color:#22d3ee
```

## The file

```yaml etl-quarantine.nika.yaml theme={"system"}
nika: v1
workflow:
  id: etl-quarantine
  description: "CSV batch → schema gate → quarantine the bad · aggregate the good"

const:
  batch_csv: "examples/fixtures/orders.csv"
permits:
  tools: ["nika:convert", "nika:jq", "nika:read", "nika:validate", "nika:write"]
  # The batch comes in at ONE path and leaves at TWO · each named exactly.
  # Note what is NOT granted: `out/**` would have handed the whole artifact
  # tree to a pipeline that only ever writes these two files.
  fs:
    read: ["examples/fixtures/orders.csv"]
    write: ["out/quarantine/orders-rejected.json", "out/reports/daily-totals.json"]

tasks:
  # A deterministic empty fallback · the recover target when parsing dies.
  empty_batch:
    invoke:
      tool: "nika:jq"
      args: { input: [], expression: "." }

  raw:
    invoke:
      tool: "nika:read"
      args: { path: "${{ const.batch_csv }}" }

  rows:
    with:
      csv: ${{ tasks.raw.output }}
    invoke:
      tool: "nika:convert"
      args:
        input: "${{ with.csv }}"
        from: csv
        to: json
        has_header: true
    on_error:
      recover: ${{ tasks.empty_batch.output }}    # malformed CSV → empty batch · pipeline lives

  check:
    with:
      rows: ${{ tasks.rows.output }}
    invoke:
      tool: "nika:validate"
      args:
        data: "${{ with.rows }}"
        format: json
        schema:
          type: array
          items:
            type: object
            required: [order_id, amount, currency]
            properties:
              order_id: { type: string }
              amount: { type: string }
              currency: { type: string, enum: [EUR, USD, GBP] }

  good:
    with:
      rows: ${{ tasks.rows.output }}
      valid: ${{ tasks.check.output.valid }}
    when: ${{ with.valid == true }}
    invoke:
      tool: "nika:jq"
      args:
        input: "${{ with.rows }}"
        expression: 'group_by(.currency) | map({currency: .[0].currency, orders: length, total: (map(.amount | tonumber) | add)})'

  quarantine:
    with:
      valid: ${{ tasks.check.output.valid }}
      errors: ${{ tasks.check.output.errors }}
    when: ${{ with.valid == false }}
    invoke:
      tool: "nika:write"
      args:
        path: out/quarantine/orders-rejected.json
        content: "${{ with.errors }}"
        create_dirs: true

  report:
    with:
      totals: ${{ tasks.good.output }}
    when: ${{ with.totals != null && size(with.totals) > 0 }}   # good is SKIPPED (null) on the quarantine path · guard before size()
    invoke:
      tool: "nika:write"
      args:
        path: out/reports/daily-totals.json
        content: "${{ with.totals }}"
        create_dirs: true

outputs:
  # Deliberately untyped · on the quarantine path `good` is SKIPPED and
  # this is null — a declared `type: array` would refuse the branch the
  # file exists to demonstrate.
  totals: ${{ tasks.good.output }}
```

## How it works

<Steps>
  <Step title="recover: is the safety net">
    `on_error: recover: ${{ tasks.empty_batch.output }}`: when the
    CSV won't parse, the task yields the fallback instead of failing.
    Downstream sees an empty batch, not a dead pipeline.
  </Step>

  <Step title="The gate splits, when: routes">
    `nika:validate` returns `{valid, errors}` · two `when:` branches
    route the run: good rows aggregate, bad batches quarantine WITH
    their error report.
  </Step>

  <Step title="jq does the accounting">
    `group_by(.currency)` + `add`: totals are arithmetic, not model
    output. No LLM call anywhere in this workflow.
  </Step>
</Steps>

## Constructs you just used

| Construct              | Where                 | Reference                             |
| ---------------------- | --------------------- | ------------------------------------- |
| `on_error: recover:`   | `rows`                | [Error model](/reference/error-codes) |
| `nika:validate` gate   | `check`               | [Builtins](/reference/builtins)       |
| `when:` branch routing | `good` · `quarantine` | [Workflows](/concepts/workflows)      |
| jq aggregation         | `good`                | [Builtins](/reference/builtins)       |

## Make it yours

* Add a `nika:notify` task on the quarantine branch: data-quality alerts only when something was actually rejected.
* Chain [Release notes](/examples/release-notes)' pattern to post the daily totals to your team channel.
* Validate against your real row schema: the gate is just JSON Schema.

<Card title="Next · Release radar" icon="signal" href="/examples/release-radar">
  The feed-mode example: RSS/Atom parsed natively, diffed against
  last run's state.
</Card>


# Image FX batch
Source: https://docs.nika.sh/examples/image-fx-batch

T1 fan-out · creators / media: a folder of photos → deterministic art, byte-identical forever. Zero model, zero network.

> **T1 fan-out · creators / media**: `nika:glob` lists the folder,
> `for_each` fans one `nika:image_fx` task per photo, and a fixed ops
> chain (grayscale → dither → pixelate) renders each one. No model in
> the loop — the pipeline is pure pixels, so the same input produces
> the same bytes on every run, on every machine.

## The job

Batch-stylizing a shoot means opening an editor, replaying the same
five clicks per photo, and hoping you replayed them identically. This
workflow IS the preset: the ops chain is written once in YAML, the
batch fans out in parallel, and re-running it a year from now yields
byte-identical output — the style is version-controlled with your
repo.

## The shape

```mermaid theme={"system"}
flowchart LR
  shots["shots · nika:glob"]:::invoke
  jobs["jobs · nika:jq"]:::invoke
  stylize["stylize · ∥ for_each · nika:image_fx"]:::invoke
  shots --> jobs
  jobs --> stylize
  classDef invoke fill:#22d3ee22,stroke:#22d3ee,color:#22d3ee
```

## The file

```yaml image-fx-batch.nika.yaml theme={"system"}
nika: v1
workflow:
  id: image-fx-batch
  description: "Folder of PNG files → deterministic art (grayscale · dither · pixelate) · offline batch"

const:
  # Two sample photos ship with the repo. Point this at your own folder and
  # move `permits.fs.read` with it — a const is baked in, never caller-supplied,
  # so the two lines stay in step by editing, not by magic.
  photos: "examples/fixtures/photos"

permits:
  exec: false
  tools: ["nika:glob", "nika:image_fx", "nika:jq"]
  fs:
    # ONE entry that has to cover TWO different reads, and this is the trap:
    #   · `nika:glob` gates its WALK ROOT — the directory itself
    #   · `nika:image_fx` gates each MATCHED FILE underneath it
    # Measured against 0.106.0: granting only `…/photos` passes `check` with
    # zero hints and then dies at run — NIKA-SEC-004 on the first photo.
    # Granting only `…/photos/*.png` is worse: `check` calls the entry drift
    # (it matches no literal the body names) and the glob is refused at run.
    # `**` covers the directory AND every descendant, so one entry is honest
    # here; `["…/photos", "…/photos/*.png"]` is the two-entry equivalent.
    read: ["examples/fixtures/photos/**"]
    # The renders land FLAT in one directory, so `*` is enough: it matches a
    # single path segment and never crosses `/`, which means a photo whose
    # name contained a slash could not steer a write into a subtree.
    write: ["out/darkroom/*"]

tasks:
  # The folder is the work list — no hand-maintained array to drift.
  shots:
    invoke:
      tool: "nika:glob"
      args: { pattern: "${{ const.photos }}/*.png" }

  # Derive {src, out} pairs · jq does the string work, natively.
  jobs:
    with:
      shots: ${{ tasks.shots.output }}
    invoke:
      tool: "nika:jq"
      args:
        input: "${{ with.shots }}"
        expression: 'map({ src: ., out: ("out/darkroom/" + (split("/") | last)) })'

  # One deterministic darkroom pass per photo · the ops run IN ORDER.
  stylize:
    with:
      jobs: ${{ tasks.jobs.output }}
    for_each: ${{ with.jobs }}
    max_parallel: 4
    invoke:
      tool: "nika:image_fx"
      args:
        input: "${{ item.src }}"
        out: "${{ item.out }}"
        seed: 0                       # explicit · the render is a function of (bytes · ops · seed)
        ops:
          - grayscale: {}
          - dither: { mode: bayer4 }
          - pixelate: { block: 4 }

outputs:
  rendered:
    # an empty folder skips the fan-out (its output is null) — the guard keeps
    # the typed contract honest on the very first exploratory run
    value: "${{ tasks.stylize.output != null ? tasks.stylize.output : [] }}"
    description: "The stylized artifact receipts · one per input photo · path + sha256"
```

## Two things this file teaches

1. **The ops vocabulary is a closed set** — `dither: { mode: bayer4 }`
   is one of the engine's named modes; misspell it (`bayer`) and
   `nika check` answers with the whole legal set instead of guessing.
   The checker teaches the vocabulary before the run spends a cycle.
2. **A fan-out that can produce nothing still binds** — the collect
   step guards with `${{ tasks.stylize.output != null ? … : [] }}`
   (quoted, because a bare CEL ternary contains `:` and YAML would
   claim it). An empty folder degrades to an empty manifest, not a
   crash.

## Run it

```bash theme={"system"}
nika new image-fx-batch fx.nika.yaml   # the file + its two sample photos land beside you
nika run fx.nika.yaml                  # offline · $0.00 · deterministic renders
ls out/darkroom/
```

<Note>
  The 0.107 pack embeds this workflow: `nika new image-fx-batch <dest>`
  lands the file verbatim **with its ingredients** (the two sample
  photos, at the exact relative path the yaml names). Proven against the
  released `0.107.0`: the taken copy runs offline end-to-end — `3/3 done
      · $0.00`, two renders in `out/darkroom/`.
</Note>

Point `const.photos` at any directory of PNG files. Because every op is
deterministic, the diff of `out/darkroom/` across two runs is empty —
which makes the output safe to commit, and the workflow safe to put in CI.


# Incident war room
Source: https://docs.nika.sh/examples/incident-war-room

T4 epic · SRE: evidence gathered in parallel, a typed timeline, and a recovery check before any postmortem draft.

> **T4 epic · SRE / on-call**: three evidence sources gathered in
> parallel, a typed timeline, then the honest part: `nika:wait` a settle
> window, re-poll the status API, and `nika:assert` refuses to draft a
> « resolved » postmortem while prod still burns. `on_finally:` files
> the journal event and the ping NO MATTER WHAT.

## The job

The hour after an incident is logs, Slack archaeology and a postmortem
nobody wants to start. This pipeline assembles the evidence, rebuilds
the timeline as typed events, proves recovery, and leaves a draft
(summary, impact, hypotheses, actions) in the incidents folder before
the retro is scheduled.

## The shape

```mermaid theme={"system"}
flowchart TD
  approve["approve · nika:prompt"]:::invoke
  deploys["deploys · git"]:::exec
  status_history["status_history · nika:fetch"]:::invoke
  runbook["runbook · nika:read"]:::invoke
  timeline["timeline · typed"]:::infer
  settle["settle · nika:wait"]:::invoke
  recheck["recheck · nika:fetch"]:::invoke
  confirmed["confirmed · nika:assert"]:::invoke
  postmortem["postmortem · thinking"]:::infer
  save["save · nika:write"]:::invoke
  alert["alert · nika:notify"]:::invoke
  approve --> deploys
  approve --> status_history
  approve --> runbook
  deploys --> timeline
  status_history --> timeline
  runbook --> timeline
  timeline -.->|success| settle
  approve --> recheck
  settle -.->|success| recheck
  recheck --> confirmed
  timeline --> postmortem
  confirmed -.->|success| postmortem
  postmortem --> save
  save --> alert
  save -.->|terminal| alert
  classDef infer fill:#5b8cff22,stroke:#5b8cff,color:#5b8cff
  classDef exec fill:#ff7a3c22,stroke:#ff7a3c,color:#ff7a3c
  classDef invoke fill:#22d3ee22,stroke:#22d3ee,color:#22d3ee
```

## The file

```yaml incident-war-room.nika.yaml theme={"system"}
nika: v1
workflow:
  id: incident-war-room
  description: "parallel evidence → typed timeline → settle + recheck → refuse or draft → record"

model: ollama/qwen3.5:4b   # local · zero key · `--model mock/echo` rehearses the whole file

inputs:
  alert:
    type: bool
    default: false
    description: "Ping on-call when the run settles. OFF by default so a rehearsal touches no webhook."
  settle:
    type: string
    default: "30s"
    description: "How long to let the fix propagate before the confirming re-poll"
  status_url:
    type: string
    default: "https://status.internal.example.com/v1/services/checkout-api"
    description: "The service status endpoint · polled twice"

const:
  service: "checkout-api"
  log_window: "90 minutes ago"
  runbook: "./examples/fixtures/checkout-api-runbook.md"

secrets:
  oncall_webhook:
    source: env
    key: ONCALL_WEBHOOK_URL
    egress:                       # sanction the one send · the secret IS the URL
      - to: "nika:notify"
        host_from_self: true
permits:
  exec: ["git"]
  tools: ["nika:assert", "nika:fetch", "nika:notify", "nika:prompt", "nika:read", "nika:wait", "nika:write"]
  net:
    http:
      # The status host is judged here even though the URL arrives as an input:
      # an input moves the ARGUMENT, never the wall. Point --var status_url at
      # another host and the poll is refused NIKA-SEC-004 until you name it here.
      - "status.internal.example.com"
      # `host_from_self:` above sanctions the FLOW (the secret may be the URL) —
      # it does not grant the capability. The host stays unknown at check, so it
      # is judged at RUN against this bound: name the escalation host here or the
      # send is refused mid-run, after the tokens are already spent.
      - "hooks.slack.com"         # swap for wherever ONCALL_WEBHOOK_URL points
  fs:
    # The write path is built from `const.service`, so it is pinned before the
    # run starts — but `check` reads straight past a const embedded in a longer
    # string, so it is not declared for you. Written out literally, because a
    # permit bound IS the wall and cannot interpolate (NIKA-AUTH-007).
    read: ["./examples/fixtures/checkout-api-runbook.md"]
    write: ["./incidents/checkout-api-postmortem.md"]

tasks:
  # ── the human gate · FIRST, before any evidence is gathered ──
  #
  # All three trifecta legs are live here: a private read (the runbook),
  # untrusted ingress (the status endpoint), and external egress (git, the
  # status host, the write, the webhook). NEP-0002 requires a blocking human
  # gate that DOMINATES every path to every egress-capable task, so it belongs
  # at the root — a gate placed later cannot dominate, because the gathered
  # evidence reaches the postmortem along its own data edge.
  #
  # On-call is already at the keyboard during an incident, so one confirmation
  # up front costs nothing and authorizes the whole envelope at once.
  approve:
    invoke:
      # blocking · no `default:` · a gate with a default is not a gate, and the
      # checker agrees in both directions: add `default:` here and NIKA-SEC-009
      # fires instead, because a defaulted prompt no longer dominates anything.
      # The [headless-prompt] hint is the price of a real gate — pay it here.
      # Pauses the run (exit 4) — resume with
      #   nika run <file> --resume <trace> --answer approve=true
      tool: "nika:prompt"
      args:
        message: |
          Incident war-room for ${{ const.service }} will:
            · read git history for the last ${{ const.log_window }}
            · poll ${{ inputs.status_url }} (twice, ${{ inputs.settle }} apart)
            · read ${{ const.runbook }}
            · write ./incidents/${{ const.service }}-postmortem.md
            · ping the on-call webhook (armed: ${{ inputs.alert }})

          Proceed? [yes/no]

  # ── the gather wave · all three run in parallel, one per verb ──

  # « What shipped just before it broke? » is the first question of every
  # incident, and the runbook says so out loud.
  deploys:
    with:
      go: ${{ tasks.approve.output }}
    when: ${{ with.go == true }}
    exec:
      command: ["git", "--no-pager", "log", "--oneline", "--since=${{ const.log_window }}"]
    on_error:
      # Missing evidence is EVIDENCE. The stand-in is labelled so the timeline
      # below is told the deploy log was unreadable and cannot quietly invent a
      # release that never happened.
      recover: "(deploy log unavailable · git could not be read here)"

  status_history:
    with:
      go: ${{ tasks.approve.output }}
    when: ${{ with.go == true }}
    invoke:
      tool: "nika:fetch"
      args:
        url: "${{ inputs.status_url }}"
        mode: jq
        jq: ".history"
    retry:
      # A status page mid-incident is exactly the endpoint that flaps. Retry is
      # safe here because a GET is idempotent — the checker warns [retry-effects]
      # when you retry something that is not.
      max_attempts: 3
      backoff_strategy: exponential
      jitter: true
    on_error:
      recover: []                 # offline · no history to reconstruct from

  runbook:
    with:
      go: ${{ tasks.approve.output }}
    when: ${{ with.go == true }}
    invoke:
      tool: "nika:read"
      args: { path: "${{ const.runbook }}" }

  # ── reconstruct · a TYPED timeline, not a paragraph ──
  timeline:
    with:                               # three value edges · the wave joins here
      deploys: ${{ tasks.deploys.output }}
      history: ${{ tasks.status_history.output }}
      runbook: ${{ tasks.runbook.output }}
    when: ${{ with.runbook != null }}   # « no » at the gate → nothing to reconstruct
    infer:
      max_tokens: 1500
      prompt: |
        Deploys in the window ·
        ${{ with.deploys }}
        Status history · ${{ with.history }}
        Runbook · ${{ with.runbook }}

        Reconstruct the incident timeline as events. Every event cites the
        evidence it came from; if a source says it is unavailable, say the
        timeline is incomplete rather than filling the gap.
      schema:
        # `additionalProperties: false` on EVERY object node — without it the
        # shape is a suggestion and each provider returns a slightly different
        # object. A typed timeline is the whole point of this task.
        type: object
        additionalProperties: false
        required: [events]
        properties:
          events:
            type: array
            items:
              type: object
              additionalProperties: false
              required: [at, what, evidence]
              properties:
                at: { type: string }
                what: { type: string }
                evidence: { type: string }

  # ── settle, then confirm recovery before claiming it ──
  settle:
    after:
      timeline: success              # state, no data · wait only once there is something to confirm
    invoke:
      tool: "nika:wait"
      args: { duration: "${{ inputs.settle }}" }

  recheck:
    after:
      settle: success
    with:
      go: ${{ tasks.approve.output }}   # the second network touch re-reads the decision too
    when: ${{ with.go == true }}
    invoke:
      tool: "nika:fetch"
      args:
        url: "${{ inputs.status_url }}"
        mode: jq
        jq: ".current.state"
    on_error:
      # The rehearsal's stand-in says the service came back, so the green path
      # is the one you see offline. Point --var status_url at a real endpoint
      # and anything other than « operational » blocks the draft below — that
      # refusal is the designed path, not a bug in the file.
      recover: "operational"

  confirmed:
    with:
      recovered: ${{ tasks.recheck.output == 'operational' }}   # the whole check crosses as ONE boundary expression
    invoke:
      tool: "nika:assert"
      args:
        condition: "${{ with.recovered }}"
        message: "Service is NOT back to operational: postmortem draft blocked"

  # ── the draft · only after recovery is proven ──
  postmortem:
    with:
      events: ${{ tasks.timeline.output }}
    after:
      confirmed: success             # state, no data · recovery proven or no draft
    infer:
      max_tokens: 2000
      prompt: |
        Timeline · ${{ with.events }}
        Write the postmortem draft · summary · impact · root-cause
        hypotheses · 3 follow-up actions with owners left blank.
      thinking:
        # A reasoning budget, honoured by seats that support extended thinking
        # and ignored by the ones that do not — declaring it never fails a run.
        enabled: true
        budget_tokens: 4000

  save:
    with:
      postmortem: ${{ tasks.postmortem.output }}
    invoke:
      tool: "nika:write"
      args:
        path: "./incidents/${{ const.service }}-postmortem.md"
        content: "${{ with.postmortem }}"
        create_dirs: true

  # ── the record · lands on EVERY outcome, including the refused one ──
  #
  # `after: {save: terminal}` admits all four settled states, so this task runs
  # when the draft lands AND when `confirmed` refused it and `save` was
  # cancelled — which is precisely the outcome on-call needs to hear about.
  # It is a TASK, not an `on_finally:` hook: cleanup errors are LOGGED and DO
  # NOT PROPAGATE (03 §on_finally · best-effort lane), so a webhook that dies
  # in a hook dies in silence — measured, the run stays green with nothing
  # sent. An alert you cannot trust to fail loudly is not an alert.
  alert:
    after:
      save: terminal
    with:
      armed: ${{ inputs.alert }}
      outcome: ${{ tasks.save.status }}   # observe WHAT happened · same pass-set as the after edge
    when: ${{ with.armed == true }}       # OFF by default · a rehearsal touches no webhook
    invoke:
      tool: "nika:notify"
      args:
        channel: webhook
        target: "${{ secrets.oncall_webhook }}"
        message: "${{ const.service }} war-room settled · postmortem draft ${{ with.outcome }}"
        severity: warning

outputs:
  timeline:
    value: ${{ tasks.timeline.output }}
    description: "The reconstructed, typed incident timeline"
  postmortem: ${{ tasks.postmortem.output }}
```

## How it works

<Steps>
  <Step title="Evidence gathers in one wave">
    `logs` (structured capture), `status_history` (with retry: status
    pages flap during incidents) and `runbook` share no deps: one
    parallel wave, three sources.
  </Step>

  <Step title="Settle, recheck, PROVE">
    `nika:wait duration: 60s` gives the system a settle window, the
    re-poll reads `.current.state`, and the assert fails the run,
    loudly, if it isn't `operational`. No optimistic postmortems.
  </Step>

  <Step title="on_finally always reports">
    Whether `save` success, failed or timed out, the `nika:emit`
    journal event and the on-call ping fire. Cleanup hooks are
    best-effort and never mask the main outcome.
  </Step>
</Steps>

## Constructs you just used

| Construct                   | Where       | Reference                        |
| --------------------------- | ----------- | -------------------------------- |
| `capture: structured`       | `logs`      | [The 4 verbs](/concepts/verbs)   |
| `nika:wait`                 | `settle`    | [Builtins](/reference/builtins)  |
| `nika:assert` recovery gate | `confirmed` | [Builtins](/reference/builtins)  |
| `on_finally:`               | `save`      | [Workflows](/concepts/workflows) |

## Make it yours

* Pull the incident channel export as a fourth evidence source and let the timeline cite humans, not just machines.
* Auto-file the retro: `nika:fetch method: POST` to your calendar/issue API with `${{ tasks.timeline.output.events[0].at }}` as the anchor.
* Track MTTR over time: the `on_finally` event stream is already your dataset.

<Card title="Next · CEO Monday brief" icon="briefcase" href="/examples/ceo-monday-brief">
  The closer: a three-branch gather, jq arithmetic, a thinking
  synthesis, and a run that reports its own bill.
</Card>


# Invoice chaser
Source: https://docs.nika.sh/examples/invoice-chaser

T2 chain · finance: overdue reminders drafted, and nothing goes out until a human says yes.

> **T2 chain · finance / freelance**: the human-in-the-loop example.
> `nika:prompt` blocks the workflow until someone answers; the
> drafting is automated, the **sending decision never is**.

## The job

Friday: open the ledger, find who's late, write polite-but-firm
reminders, don't send the awkward one to the client who paid this
morning. This file filters the CSV deterministically (jq, not an LLM
guessing at numbers), drafts every reminder, then stops and asks you.

## The shape

```mermaid theme={"system"}
flowchart LR
  ledger["ledger · nika:read"]:::invoke
  rows["rows · nika:convert"]:::invoke
  overdue["overdue · nika:jq"]:::invoke
  drafts["drafts"]:::infer
  approve["approve · nika:prompt"]:::invoke
  save["save · nika:write"]:::invoke
  ledger --> rows
  rows --> overdue
  overdue --> drafts
  drafts --> approve
  drafts --> save
  approve --> save
  classDef infer fill:#5b8cff22,stroke:#5b8cff,color:#5b8cff
  classDef invoke fill:#22d3ee22,stroke:#22d3ee,color:#22d3ee
```

## The file

```yaml invoice-chaser.nika.yaml theme={"system"}
nika: v1
workflow:
  id: invoice-chaser
  description: "Ledger CSV → overdue filter → drafted reminders → human gate → drafts file"

model: ollama/qwen3.5:4b   # local · zero key · swap for groq/llama-3.3-70b (drafting is a fast-model job)

const:
  ledger_csv: "examples/fixtures/invoices.csv"
permits:
  tools: ["nika:convert", "nika:jq", "nika:prompt", "nika:read", "nika:write"]
  fs:
    # Two files, both spelled out — `const.ledger_csv` in, the drafts file
    # out. A const is baked in and a run cannot move it, so the boundary is
    # exact: no glob, and nothing else on disk is reachable either way.
    read: ["examples/fixtures/invoices.csv"]
    write: ["out/reminders-to-send.md"]

tasks:
  ledger:
    invoke:
      tool: "nika:read"
      args: { path: "${{ const.ledger_csv }}" }

  rows:
    with:
      csv: ${{ tasks.ledger.output }}
    invoke:
      tool: "nika:convert"
      args:
        input: "${{ with.csv }}"
        from: csv
        to: json
        has_header: true

  overdue:
    with:
      rows: ${{ tasks.rows.output }}
    invoke:
      tool: "nika:jq"
      args:
        input: "${{ with.rows }}"
        expression: 'map(select(.status == "overdue"))'

  drafts:
    with:
      overdue: ${{ tasks.overdue.output }}
    when: ${{ size(with.overdue) > 0 }}
    infer:
      max_tokens: 900       # a ceiling makes the cost report a number, not UNBOUNDED
      prompt: |
        Draft one short, polite payment reminder per overdue invoice ·
        ${{ with.overdue }}
        Markdown · one section per client · firm but warm.

  approve:
    with:
      drafts: ${{ tasks.drafts.output }}
    when: ${{ with.drafts != null }}   # nothing drafted · nothing to approve
    invoke:
      tool: "nika:prompt"
      args:
        message: "Save the reminder drafts for sending?"
        default: false

  save:
    with:
      drafts: ${{ tasks.drafts.output }}
      approved: ${{ tasks.approve.output }}
    when: ${{ with.drafts != null && with.approved == true }}   # zero overdue → drafts skipped (null) · don't write nothing
    invoke:
      tool: "nika:write"
      args:
        path: out/reminders-to-send.md
        create_dirs: true
        content: "${{ with.drafts }}"

outputs:
  overdue:
    value: ${{ tasks.overdue.output }}
    description: "The overdue rows the reminders were drafted for"
```

## How it works

<Steps>
  <Step title="Data work is jq work">
    CSV → JSON via `nika:convert`, then `map(select(.status == "overdue"))`
    in `nika:jq`. No model touches the numbers: deterministic, free,
    auditable.
  </Step>

  <Step title="size() gates the whole tail">
    The list crosses the boundary (`overdue: ${{ tasks.overdue.output }}`
    in `with:`), then `when: ${{ size(with.overdue) > 0 }}` is the
    canonical empty-check. No overdue invoices → the rest of the file
    skips (and value edges pass the skip along as `null`).
  </Step>

  <Step title="The approval gate">
    `nika:prompt` blocks until answered (CI can use `default:`). The
    save binds the verdict (`approved: ${{ tasks.approve.output }}`)
    and runs only `when: ${{ with.drafts != null && with.approved == true }}`.
  </Step>
</Steps>

## Constructs you just used

| Construct                | Where         | Reference                        |
| ------------------------ | ------------- | -------------------------------- |
| `nika:convert` from/to   | `rows`        | [Builtins](/reference/builtins)  |
| `nika:jq` filtering      | `overdue`     | [Builtins](/reference/builtins)  |
| CEL `size()`             | `drafts.when` | [Workflows](/concepts/workflows) |
| `nika:prompt` human gate | `approve`     | [Builtins](/reference/builtins)  |

## Make it yours

* Per-client emails instead of one file: `for_each` over the overdue rows ([fan-out tier](/examples/competitor-radar)).
* Escalate 60-days-late differently: a second jq filter + a sterner prompt.
* Wire the approved drafts to your mail API with `nika:fetch method: POST`.

<Card title="Next · Support triage" icon="headset" href="/examples/support-triage">
  Classify a whole queue in one schema-typed call, then let jq slice the
  urgent ones out.
</Card>


# Local-first daily brief
Source: https://docs.nika.sh/examples/local-first-daily-brief

T1 starter · zero keys, zero cloud: fetch real data, brief it with a local Ollama model, keep a tamper-evident trace.

> **T1 starter · local-first**: the whole loop on your machine — a real
> HTTP fetch, a local model, a verifiable trace. No API key exists in
> this tutorial, so there is nothing to leak and nothing to meter.

## The job

A morning brief from a live source, every day, the same way. One file
captures it; your laptop runs it; the trace proves what happened.

## Prerequisites

* `nika` installed: `brew install supernovae-st/tap/nika` ([other paths](/getting-started/installation))
* [Ollama](https://ollama.com) running with a small model:
  `ollama pull qwen3.5:4b` (any local model works — swap the `model:` line)

## The file

Save as `daily-brief.nika.yaml`:

```yaml theme={"system"}
nika: v1
workflow:
  id: daily-brief
model: ollama/qwen3.5:4b

permits:
  exec: false                          # nothing shells out
  net:
    http: ["hn.algolia.com"]           # the one host this file reaches
  tools: ["nika:fetch"]

tasks:
  fetch:
    invoke:
      tool: "nika:fetch"
      args: { url: "https://hn.algolia.com/api/v1/search?tags=front_page" }

  brief:
    with:
      stories: ${{ tasks.fetch.output }}
    infer:
      max_tokens: 300
      prompt: |
        Five bullet points, most signal first: ${{ with.stories }}

outputs:
  brief: ${{ tasks.brief.output }}
```

Swap the URL for any JSON source — an RSS-to-JSON bridge, your issue
tracker's API, a status page.

## Check, then run

```sh theme={"system"}
nika check daily-brief.nika.yaml
```

The static audit passes before a single token is spent — plan, types,
tools, args, secret flows. One honest wrinkle to read, not fear:

```text theme={"system"}
⚠  COST   $0.0000 – $0.0000 FLOOR (unbounded tasks present)
   brief  ollama/qwen3.5:4b  UNBOUNDED — no catalog price (local/unknown model)
```

A local model has no list rate, so the engine says **unbounded** instead
of pretending `$0.00` is a promise. Local work is never blocked and never
metered — the flag exists so a *paid* uncataloged model can't hide behind
a fake zero ([cost honesty](/guides/cost-honesty)).

Then:

```sh theme={"system"}
nika run daily-brief.nika.yaml
```

A real run of this exact file (Apple Silicon, qwen3.5:4b):

```text theme={"system"}
✔  fetch  invoke · nika:fetch        762ms
✔  brief  infer · ollama/qwen3.5:4b  48.0s
── 2/2 done · ≥ $0.00 (1 unpriced) · elapsed 48.7s ─────────────
  trace: .nika/traces/2026-07-09T22-54-50Z-e843.ndjson · 8 events · chain 394719d2…
```

## The receipt

```sh theme={"system"}
nika trace verify .nika/traces/<run>.ndjson   # path from the run card's trace: line
```

```text theme={"system"}
OK — 8 events · chain intact · head 394719d24361e1a6…
```

The trace is a hash chain: edit any event after the fact and `verify`
exits non-zero. Your brief comes with proof of what ran, in what order,
against which inputs — even offline.

## Make it daily

Cron it, or wire [the GitHub Action](/integrations/github-actions) if the
file lives in a repo — every edit to the workflow gets a static check
before it lands. When you want the run itself in CI, that stays a
deliberate step in your own job, with your own budget flags.

## Where to go next

* Read the `permits:` block as the contract: absent is zero authority,
  present is default-deny. `nika check --infer-permits` writes the
  tightest one for the next file you author
  ([security](/concepts/security)).
* Persist the brief: a third task with `nika:write` and a
  `content:` binding ([starters](/examples/standup-digest) show the shape).
* Mix providers: keep `fetch` local, point `brief` at a cloud model with
  `--max-cost-usd` — the budget gate prices the file's own model before
  anything starts ([cost honesty](/guides/cost-honesty)).


# Localization factory
Source: https://docs.nika.sh/examples/localization-factory

T3 fan-out · product / i18n: the whole docs tree translated, voice intact, zero copy-paste.

> **T3 fan-out · product / content / i18n**: three chained fan-outs
> (read-all → translate-all → write-all) with jq `transpose` zipping
> paths back to texts between stages. The masterclass file for
> collections.

## The job

« Can we have the docs in French? » is weeks of copy-paste, or it's this
file: glob finds every markdown file, the texts are read and translated
in parallel (rate-limited so the provider doesn't choke), and the mirror
tree appears under `i18n/fr/` with the original paths preserved.

## The shape

```mermaid theme={"system"}
flowchart LR
  files["files · nika:glob"]:::invoke
  texts["texts · ∥ for_each · nika:read"]:::invoke
  pairs["pairs · nika:jq"]:::invoke
  translated["translated · ∥ for_each"]:::infer
  bundle["bundle · nika:jq"]:::invoke
  mirror["mirror · ∥ for_each · nika:write"]:::invoke
  files --> texts
  files --> pairs
  texts --> pairs
  pairs --> translated
  pairs --> bundle
  translated --> bundle
  bundle --> mirror
  classDef infer fill:#5b8cff22,stroke:#5b8cff,color:#5b8cff
  classDef invoke fill:#22d3ee22,stroke:#22d3ee,color:#22d3ee
```

## The file

```yaml localization-factory.nika.yaml theme={"system"}
nika: v1
workflow:
  id: localization-factory
  description: "glob docs → parallel read → parallel translate → mirror tree"

model: ollama/qwen3.5:4b   # local default · swap for mistral/mistral-large (EU model for EU locales)

const:
  lang: "fr"
  # The committed rehearsal tree. Point this at ./docs (or wherever yours
  # lives) and change `permits.fs.read` to match, in the same edit.
  source_root: "./examples/fixtures/docs"

permits:
  tools: ["nika:glob", "nika:jq", "nika:read", "nika:write"]
  fs:
    # `nika:glob` opens the ROOT of its pattern, so the bound has to cover
    # the directory AND everything under it — `**` does both (it matches the
    # dir itself and any descendant at any depth). A bound naming only the
    # `.md` files refuses the glob before it lists anything:
    # `NIKA-SEC-004 · ./examples/…/docs resolves outside permits.fs.read`.
    read: ["./examples/fixtures/docs/**"]
    # The mirror is as deep as the source tree, so this one earns its `**`:
    # every locale lands under ./i18n/ and nothing lands outside it. Naming
    # the locale (`./i18n/fr/**`) would be tighter but would have to be
    # re-edited for every value of `const.lang` — the bound is the tree the
    # factory owns.
    write: ["./i18n/**"]

tasks:
  # ── the collection is discovered, never declared ────────────────────
  files:
    invoke:
      tool: "nika:glob"
      args:
        pattern: "${{ const.source_root }}/**/*.md"
        exclude: ["**/node_modules/**"]

  # ── stage 1 · read every file, 8 at a time ─────────────────────────
  texts:
    with:
      files: ${{ tasks.files.output }}
    for_each: ${{ with.files }}
    max_parallel: 8                    # local disk · the only cost is file handles
    invoke:
      tool: "nika:read"
      args: { path: "${{ item }}" }

  # ── the zip · path + text, and the source root comes off ───────────
  # `texts` is an array in the SAME ORDER as `files`, so transpose pairs
  # them index-for-index. `ltrimstr` makes each path relative to the source
  # root — that stripped path is what the mirror tree is built from.
  pairs:
    with:
      files: ${{ tasks.files.output }}
      texts: ${{ tasks.texts.output }}
    invoke:
      tool: "nika:jq"
      args:
        input: ["${{ with.files }}", "${{ with.texts }}"]
        expression: >-
          transpose
          | map({ path: (.[0] | ltrimstr("${{ const.source_root }}/")), text: .[1] })

  # ── stage 2 · translate every file, 3 at a time ────────────────────
  translated:
    with:
      pairs: ${{ tasks.pairs.output }}
    for_each: ${{ with.pairs }}
    max_parallel: 3                    # rate-limit the provider, not the disk
    fail_fast: false                   # finish the batch · one bad file is not a batch failure
    on_error:
      recover: null                    # null holds the index open so the zip below stays aligned
    infer:
      max_tokens: 4000                 # a doc page, not a book · the cost ceiling is a real number
      prompt: |
        Translate to ${{ const.lang }} · keep the markdown structure, leave
        code blocks untouched, and keep the original tone ·
        ${{ item.text }}

  # ── the fan-in · drop the files that failed, keep their paths ──────
  # Second transpose, same law: `translated` is index-aligned with `pairs`
  # because `recover: null` filled the failures in place. `select(.[1] !=
  # null)` is where a failed translation leaves the batch — by VALUE, after
  # the fact, not by aborting the fan-out.
  bundle:
    with:
      pairs: ${{ tasks.pairs.output }}
      translated: ${{ tasks.translated.output }}
    invoke:
      tool: "nika:jq"
      args:
        input: ["${{ with.pairs }}", "${{ with.translated }}"]
        expression: >-
          transpose
          | map(select(.[1] != null))
          | map({ path: .[0].path, text: .[1] })

  # ── stage 3 · write the mirror ─────────────────────────────────────
  mirror:
    with:
      bundle: ${{ tasks.bundle.output }}
    for_each: ${{ with.bundle }}
    max_parallel: 8
    invoke:
      tool: "nika:write"
      args:
        path: "./i18n/${{ const.lang }}/${{ item.path }}"
        content: "${{ item.text }}"
        create_dirs: true              # the mirror's subdirectories do not exist yet

outputs:
  translated:
    value: ${{ tasks.bundle.output }}
    description: "Every file that made it through, as {path, text} · the mirror's manifest"
```

## How it works

<Steps>
  <Step title="The filesystem is the collection">
    `nika:glob` returns the file list at runtime: add a doc tomorrow,
    it's in the next run. `exclude:` keeps `node_modules` out.
  </Step>

  <Step title="transpose zips parallel arrays">
    Two fan-outs produce two aligned arrays (paths, texts). The jq
    `transpose | map({path: .[0], text: .[1]})` zip turns them into
    `[{path, text}]`, and `${{ item.path }}` works, because loop-locals
    are full objects.
  </Step>

  <Step title="The mirror tree comes out the other end">
    The final fan-out writes `./i18n/fr/<original path>` with
    `create_dirs: true`. Path templating is plain `${{ }}` interpolation
    inside a string.
  </Step>
</Steps>

## Constructs you just used

| Construct                        | Where                             | Reference                        |
| -------------------------------- | --------------------------------- | -------------------------------- |
| `nika:glob` + `exclude`          | `files`                           | [Builtins](/reference/builtins)  |
| chained `for_each` stages        | `texts` → `translated` → `mirror` | [Workflows](/concepts/workflows) |
| jq `transpose` zip               | `pairs` · `bundle`                | [Builtins](/reference/builtins)  |
| `${{ item.path }}` object locals | `mirror`                          | [Bindings](/concepts/bindings)   |

## Make it yours

* All your locales: wrap the lang in a list and run per locale, or lift `const.lang` to a typed required input and call the workflow per language.
* Glossary discipline: interpolate your terminology table into the translate prompt so product names never drift.
* Only what changed: replace `glob` with `exec: git diff --name-only` and translate the delta ([PR review fan-out](/examples/pr-review-fanout) starts the same way).

<Card title="Next · Config drift sentinel" icon="shield-halved" href="/examples/config-drift-sentinel">
  RFC 7396 merge-patch + RFC 6902 diff: jq decides, the model only
  explains.
</Card>


# Meeting actions
Source: https://docs.nika.sh/examples/meeting-actions

T1 starter · every office job: transcript in, tracker-ready typed action items out.

> **T1 starter · every office job**: the first example with
> `infer.schema:`. The model doesn't get to answer in prose. It returns
> the JSON shape you declared, or the engine rejects it.

## The job

The meeting ended an hour ago and nobody remembers who owns what. The
transcript is sitting in a file. This workflow extracts every action
item as `{owner, task, due}`: typed, validated, importable by whatever
tracker you use.

## The shape

```mermaid theme={"system"}
flowchart LR
  transcript["transcript · nika:read"]:::invoke
  extract["extract · typed"]:::infer
  save["save · nika:write"]:::invoke
  trace["trace · nika:log"]:::invoke
  transcript --> extract
  extract --> save
  extract -.->|success| trace
  classDef infer fill:#5b8cff22,stroke:#5b8cff,color:#5b8cff
  classDef invoke fill:#22d3ee22,stroke:#22d3ee,color:#22d3ee
```

## The file

```yaml meeting-actions.nika.yaml theme={"system"}
nika: v1
workflow:
  id: meeting-actions
  description: "Transcript → typed action items {owner, task, due}"

# A NON-thinking local model, deliberately: a thinking model can spend the
# whole `max_tokens` budget in its think block and return before the JSON
# (engine#428). Schema showcases pick a model that answers directly.
model: ollama/llama3.2:3b

inputs:
  transcript_path:
    type: string
    default: "examples/fixtures/meeting-transcript.txt"
    description: "Path to the raw meeting transcript"
permits:
  tools: ["nika:log", "nika:read", "nika:write"]
  fs:
    # The sample transcript, named as a LITERAL. `permits:` cannot interpolate
    # (NIKA-AUTH-007), so this line does not follow `inputs.transcript_path`
    # around: pointing the var at your own file means editing this entry too,
    # or the read is refused at run with NIKA-SEC-004. That is the wall doing
    # its job — a boundary you can read is a boundary a reviewer can check.
    read: ["examples/fixtures/meeting-transcript.txt"]
    write: ["out/action-items.json"]

tasks:
  transcript:
    invoke:
      tool: "nika:read"
      args: { path: "${{ inputs.transcript_path }}" }

  extract:
    with:
      transcript: ${{ tasks.transcript.output }}
    infer:
      max_tokens: 900                  # a ceiling makes the cost report a number, not UNBOUNDED
      prompt: |
        Extract every action item from this meeting transcript ·
        ${{ with.transcript }}
        One entry per commitment somebody actually made. `due` only when a
        date or deadline was stated — never invent one.
      schema:                          # the contract the model must satisfy
        type: object
        additionalProperties: false
        required: [actions]
        properties:
          actions:
            type: array
            items:
              type: object
              additionalProperties: false
              required: [owner, task]
              properties:
                owner: { type: string }
                task: { type: string }
                due: { type: string }

  save:
    with:
      extract_actions: ${{ tasks.extract.output.actions }}
    invoke:
      tool: "nika:write"
      args:
        # `.json` content is ONE interpolation of a real value — the engine
        # serializes it. Typing `{ "actions": ${{ … }} }` by hand emits
        # unquoted fields and the artifact stops being JSON.
        path: out/action-items.json
        content: "${{ with.extract_actions }}"
        create_dirs: true

  trace:
    after:
      extract: success
    invoke:
      tool: "nika:log"
      args:
        level: info
        message: "Action items extracted to out/action-items.json"

outputs:
  actions:
    value: ${{ tasks.extract.output.actions }}
    description: "Typed action items, tracker-ready"
```

## How it works

<Steps>
  <Step title="A required, typed input">
    `transcript_path` is declared with `type: string · required: true`:
    the engine validates inputs before any task runs, and the workflow
    becomes callable with a real contract.
  </Step>

  <Step title="The schema IS the contract">
    `infer.schema:` is standard JSON Schema. The model must return a
    matching object. On violation the engine rejects (and may retry).
    Downstream tasks index into it directly: `${{ tasks.extract.output.actions }}`.
  </Step>

  <Step title="Two consumers, no extra ceremony">
    `save` writes the JSON, `trace` logs a human-readable line. Both
    depend on `extract`, both run in parallel.
  </Step>
</Steps>

## Constructs you just used

| Construct            | Where               | Reference                             |
| -------------------- | ------------------- | ------------------------------------- |
| typed `inputs:`      | `transcript_path`   | [YAML syntax](/reference/yaml-syntax) |
| `infer.schema:`      | `extract`           | [The 4 verbs](/concepts/verbs)        |
| schema-path indexing | `save.args.content` | [Bindings](/concepts/bindings)        |
| `nika:log`           | `trace`             | [Builtins](/reference/builtins)       |

## Make it yours

* Add `due` to the `required:` list if your team always sets deadlines.
* Chain a `nika:notify` task that posts each owner their items.
* Swap the transcript file for a `nika:fetch` of your meeting tool's export API. The schema doesn't change.

<Card title="Next · Price watch" icon="tag" href="/examples/price-watch">
  The next starter has zero model calls: pure tools, bindings and one
  CEL comparison.
</Card>


# Model bench
Source: https://docs.nika.sh/examples/model-bench

T2 diamond · engineering: the same question, three local models, one MEASURED table. Zero keys, zero cloud, zero spend.

> **T2 diamond · engineering / model selection**: three `infer.model:`
> seats fan out the SAME question in parallel; a `nika:jq` fan-in builds
> a markdown table from measured facts — each answer's latency comes
> from `tasks.X.duration_ms`, the run's own clock. No judge model, no
> scores: the table states facts, the quality call stays yours.

## The job

Picking a default model by vibes is how you end up paying for quality
you don't need — or shipping answers a smaller model would have matched.
This workflow is the bench you run BEFORE deciding: same prompt, three
seats, one report on disk that you can diff run over run.

## The shape

```mermaid theme={"system"}
flowchart LR
  ask_incumbent["ask_incumbent"]:::infer
  ask_challenger["ask_challenger"]:::infer
  ask_tiny["ask_tiny"]:::infer
  tabulate["tabulate · nika:jq"]:::invoke
  persist["persist · nika:write"]:::invoke
  ask_incumbent --> tabulate
  ask_challenger --> tabulate
  ask_tiny --> tabulate
  tabulate --> persist
  classDef infer fill:#5b8cff22,stroke:#5b8cff,color:#5b8cff
  classDef invoke fill:#22d3ee22,stroke:#22d3ee,color:#22d3ee
```

## The file

```yaml model-bench.nika.yaml theme={"system"}
nika: v1
workflow:
  id: model-bench
  description: "One question → three local models → a measured comparison table"

model: ollama/qwen3.5:4b # the house default · contenders below pick their own seats

const:
  question:
    # A TYPED constant is `{ type, value }` — both keys, exactly those two.
    # `{ type, default }` is not a declaration at all (01-envelope.md §const:
    # an object missing either key is a bare literal object), so the prompt
    # below would receive the whole `{type, default}` map instead of the
    # question. Measured: the model gets a JSON blob and the bench is junk.
    type: string
    value: "Explain, in five lines, why a workflow should be audited before it runs."
permits:
  tools: ["nika:jq", "nika:write"]
  fs: { write: ["out/model-bench.md"] }

tasks:
  ask_incumbent:
    infer:
      model: ollama/qwen2.5:14b # the quality bar · the seat to beat
      prompt: "${{ const.question }}"
      max_tokens: 600

  ask_challenger:
    infer:
      model: ollama/llama3.2:3b # another family · same size class
      prompt: "${{ const.question }}"
      max_tokens: 600

  ask_tiny:
    infer:
      model: ollama/qwen2.5:0.5b # the "is small enough?" probe
      prompt: "${{ const.question }}"
      max_tokens: 600

  tabulate:
    with:
      ask_incumbent_duration_ms: ${{ tasks.ask_incumbent.duration_ms }}
      ask_incumbent: ${{ tasks.ask_incumbent.output }}
      ask_challenger_duration_ms: ${{ tasks.ask_challenger.duration_ms }}
      ask_challenger: ${{ tasks.ask_challenger.output }}
      ask_tiny_duration_ms: ${{ tasks.ask_tiny.duration_ms }}
      ask_tiny: ${{ tasks.ask_tiny.output }}
    invoke:
      tool: "nika:jq"
      args:
        input:
          - model: "ollama/qwen2.5:14b"
            ms: "${{ with.ask_incumbent_duration_ms }}"
            answer: "${{ with.ask_incumbent }}"
          - model: "ollama/llama3.2:3b"
            ms: "${{ with.ask_challenger_duration_ms }}"
            answer: "${{ with.ask_challenger }}"
          - model: "ollama/qwen2.5:0.5b"
            ms: "${{ with.ask_tiny_duration_ms }}"
            answer: "${{ with.ask_tiny }}"
        expression: >-
          "| model | latency | chars | answer (first 160) |\n|---|---|---|---|\n"
          + (map("| " + .model + " | "
               + (if .ms == null then "cached" else (.ms | tostring) + "ms" end) + " | "
               + (.answer | length | tostring) + " | "
               + (.answer | gsub("\n"; " ") | .[0:160]) + " |")
             | join("\n"))

  persist:
    with:
      tabulate: ${{ tasks.tabulate.output }}
    invoke:
      tool: "nika:write"
      args:
        path: out/model-bench.md
        create_dirs: true
        content: |
          # Model bench — same question, measured

          ${{ with.tabulate }}

          Facts only: latency from the run's clock, length in characters.
          The answers are side by side — the quality call is yours.

outputs:
  table:
    value: ${{ tasks.tabulate.output }}
    description: "The measured comparison table · latency + length per seat"
```

## Two findings the bench surfaced on its own authoring run

Both were caught live while writing this example — they are what the
bench is FOR:

1. **A thinking model with a bounded `max_tokens` can return an empty
   answer** — it spends the whole budget reasoning before a single
   output token. The row reads `0 chars`: that is a bench *result*, not
   a bug. Seat `ollama/qwen3.5:4b` and reproduce it on your machine.
2. **On a `--resume`, rehydrated rows say `cached`** — a latency that
   was not re-measured is never re-printed as a fresh number. The
   report stays honest across resumes.

## Run it

```bash theme={"system"}
ollama pull qwen2.5:14b llama3.2:3b qwen2.5:0.5b   # or swap the seats
git clone https://github.com/supernovae-st/nika-spec && cd nika-spec
nika run examples/showcase/t2-model-bench.nika.yaml
cat bench/model-bench.md
```

<Note>
  This workflow is newer than the currently shipped engine pack:
  `nika examples run showcase/t2-model-bench` says `unknown example`
  until the next engine tag re-vendors the pack. Until then, run it
  from the spec checkout as above — the file is the same one the pack
  will embed, sha-pinned in the spec manifest.
</Note>

The first call to each model pays its load time — run the bench twice
and read the warm numbers. Swap any seat for `mistral/…`,
`anthropic/…` or `openai/…` to bench a cloud contender against your
local incumbents (the cost column of `nika check` starts telling the
price story the moment a priced model enters).


# OG images
Source: https://docs.nika.sh/examples/og-images

T1 starter · marketing: brief in, OG image variants + provenance manifest out.

> **T1 starter · marketing / content**: one task is the whole media
> pipeline. Generated images land **on disk** under a declared boundary —
> outputs carry paths and sha256 hashes, never image bytes.

## The job

Every landing page, blog post and QR campaign needs an OG image, and
someone ends up producing them one by one in a chat window. This workflow
turns that into a step: creative brief in, rendered variants + a
provenance manifest out, ready for the site build to pick up.

## The shape

```mermaid theme={"system"}
flowchart LR
  hero["hero · nika:image_generate"]:::invoke
  classDef invoke fill:#22d3ee22,stroke:#22d3ee,color:#22d3ee
```

## The file

```yaml og-images.nika.yaml theme={"system"}
nika: v1
workflow:
  id: og-images
  description: "Generate the launch OG hero image set into out/og"

permits:
  tools: ["nika:image_generate"]
  fs:
    # `check` judges the `output_dir:` ARGUMENT; the RUN gates every FINAL
    # file path under it — the images, their provenance sidecars and
    # manifest.json. `**` covers the directory AND every descendant, so one
    # entry answers both. Granting the bare directory (`out/og`) passes
    # `check` and then dies at run on the first asset: measured, and the
    # reason this comment exists.
    write: ["out/og/**"]

tasks:
  hero:
    invoke:
      tool: "nika:image_generate"
      args:
        provider: mock                # offline + deterministic · flip to local/gemini/openai to render for real
        prompt: "OG hero — a monarch butterfly over a deep-blue nebula, editorial photo, negative space left"
        aspect_ratio: "16:9"          # exact WxH is an openai gpt-image-2 feature · gemini folds to a size class
        n: 2                          # two variants to A/B
        output_dir: "out/og"
        filename_prefix: "launch-hero"
        metadata: { campaign: "launch", page_slug: "home" }

outputs:
  paths: ${{ tasks.hero.output.images }}
  manifest: ${{ tasks.hero.output.manifest_path }}
```

## Why it reads like that

* **`provider: mock` first** — it renders real, decodable PNGs offline,
  deterministically, with zero keys: the pipeline is testable in CI as-is.
  Production is a one-line flip to `local` (the sovereign path — your
  LocalAI/Ollama/sd.cpp server, `NIKA_IMAGE_LOCAL_URL`), `gemini`
  (`GEMINI_API_KEY`), `openai` (`OPENAI_API_KEY`) or `xai` (`XAI_API_KEY`);
  keys and the local URL are engine-configured, never workflow args.
* **`permits.fs.write` is the contract** — `./assets/og/**` is the ONLY
  place assets may land; a templated `output_dir` that escapes it fails
  `NIKA-SEC-004` before any byte is written. `nika check --infer-permits`
  writes this block for you.
* **assets, not blobs** — `tasks.hero.output.images` is a list of
  `{ path, filename, width, height, sha256, … }` entries, and a
  `*.manifest.json` lands beside the files (request echo · hashes ·
  usage · your `metadata:` fields). Base64 never rides outputs, logs or
  traces.
* **`n: 2` for A/B** — OpenAI renders n natively; Gemini runs n
  sequential calls (documented); mock renders n distinct deterministic
  variants.

## Run it

```sh theme={"system"}
nika examples run showcase/t1-og-images        # offline · mock renders real PNGs
ls assets/og/                                  # variants + the provenance manifest
```

Flip the provider line and re-run when you want real renders — the rest
of the file does not change.


# Examples
Source: https://docs.nika.sh/examples/overview

Real-job workflows, tiered from a 4-task starter to a multi-agent swarm: every file conformance-validated, every industry covered.

If you do the same AI task twice, make it a workflow. Every example on
these pages is a complete one you can run right now. The whole gallery
ships inside the binary:

```bash theme={"system"}
nika try 01-hello                    # the mock rehearsal · zero keys · nothing written
nika new meeting-actions             # take an example, fixtures included, then run it
```

`nika try` previews an example offline with zero setup; `nika new`
lands the file with its fixture ingredients so the real run works.

The YAML you read here is projected verbatim from
[`nika-spec/examples/showcase/`](https://github.com/supernovae-st/nika-spec/tree/main/examples/showcase),
where each file passes the same conformance gate as the spec's own test
suite. If a file is on this page, it parses, and it runs.

These  workflows ( starters ·  chains
·  fan-outs ·  epics) plus the foundation set
exercise **all  builtins**, the  verbs, and
&#x20;providers: cloud, local and mock.

<video>
  <source type="video/webm" />

  <source type="video/mp4" />
</video>

## How to read a workflow diagram

Tasks are colored by verb, the same palette everywhere in the Nika
universe:

```mermaid theme={"system"}
flowchart LR
  A["infer · call a model"]:::infer --> B["exec · run a process"]:::exec
  B --> C["invoke · call a tool"]:::invoke --> D["agent · drive a loop"]:::agent
  classDef infer fill:#5b8cff22,stroke:#5b8cff,color:#5b8cff
  classDef exec fill:#ff7a3c22,stroke:#ff7a3c,color:#ff7a3c
  classDef invoke fill:#22d3ee22,stroke:#22d3ee,color:#22d3ee
  classDef agent fill:#b07bff22,stroke:#b07bff,color:#b07bff
```

## T1 · Starters

Four tasks or fewer, one chain or one diamond. You can run one of these
in your first five minutes.

<Columns>
  <Card title="Standup digest" icon="sunrise" href="/examples/standup-digest">
    **Engineering**: your standup note, written from what you actually
    committed yesterday.
  </Card>

  <Card title="Meeting actions" icon="list-check" href="/examples/meeting-actions">
    **Every office**: transcript in, tracker-ready typed action items
    out.
  </Card>

  <Card title="Price watch" icon="tag" href="/examples/price-watch">
    **E-commerce**: a price-drop alert with zero model calls.
  </Card>

  <Card title="OG images" icon="image" href="/examples/og-images">
    **Marketing**: brief in, OG variants on disk + a provenance
    manifest out — offline-testable with the mock provider.
  </Card>

  <Card title="Social repurpose" icon="share-nodes" href="/examples/social-repurpose">
    **Marketing**: one post becomes a thread, a LinkedIn post and a
    newsletter blurb, in parallel.
  </Card>
</Columns>

## T2 · Chains

Four to six tasks. Structured outputs, human gates, and the data
builtins start pulling their weight.

<Columns>
  <Card title="Release notes" icon="rocket" href="/examples/release-notes">
    **Engineering / DevRel**: git log → typed notes → CHANGELOG edited
    in place → team pinged.
  </Card>

  <Card title="SEO content brief" icon="magnifying-glass-chart" href="/examples/seo-content-brief">
    **SEO / Content**: a brief grounded in what your competitor
    actually published.
  </Card>

  <Card title="Invoice chaser" icon="file-invoice-dollar" href="/examples/invoice-chaser">
    **Finance / Freelance**: reminders drafted, and NOTHING goes out
    until a human says yes.
  </Card>

  <Card title="Support triage" icon="headset" href="/examples/support-triage">
    **Customer support**: the overnight queue classified, first replies
    drafted, urgent ones escalated.
  </Card>

  <Card title="Contract guard" icon="scale-balanced" href="/examples/contract-guard">
    **Legal**: clause extraction on a LOCAL model. The contract never
    leaves the machine.
  </Card>

  <Card title="ETL quarantine" icon="filter" href="/examples/etl-quarantine">
    **Data engineering**: bad batches degrade to a quarantine file
    instead of killing the pipeline.
  </Card>

  <Card title="Release radar" icon="signal" href="/examples/release-radar">
    **DevOps**: dependency feeds diffed against last run. Only the
    NEW ships reach you.
  </Card>
</Columns>

## T3 · Fan-out

`for_each` over collections the workflow discovers at runtime, with
retry, bounded parallelism and jq fan-ins.

<Columns>
  <Card title="Competitor radar" icon="satellite-dish" href="/examples/competitor-radar">
    **Strategy / PMM**: everything they shipped last week, read in parallel,
    one Monday brief.
  </Card>

  <Card title="Localization factory" icon="language" href="/examples/localization-factory">
    **Product / i18n**: the whole docs tree translated, voice intact,
    zero copy-paste.
  </Card>

  <Card title="Config drift sentinel" icon="shield-halved" href="/examples/config-drift-sentinel">
    **SRE / Platform**: only unsanctioned prod drift wakes anyone. jq
    decides; the model explains.
  </Card>

  <Card title="PR review fan-out" icon="code-pull-request" href="/examples/pr-review-fanout">
    **Engineering**: a read-only review agent per changed file. A
    swarm with a leash.
  </Card>

  <Card title="Resume screener" icon="user-check" href="/examples/resume-screener">
    **HR / Recruiting**: one local-model rubric per candidate, ranked
    deterministically. PII stays home.
  </Card>
</Columns>

## T4 · Epic

Multi-stage pipelines: agents under budget, human gates, runs that
report on themselves.

<Columns>
  <Card title="Deep research brief" icon="microscope" href="/examples/deep-research-brief">
    **Research / VC**: plan → budgeted research agent → thinking-model
    synthesis. Auditable end to end.
  </Card>

  <Card title="Incident war room" icon="fire-extinguisher" href="/examples/incident-war-room">
    **SRE / On-call**: evidence in parallel, a typed timeline, and a
    recovery check before the draft.
  </Card>

  <Card title="CEO Monday brief" icon="briefcase" href="/examples/ceo-monday-brief">
    **Founders / Execs**: market + engineering + KPIs synthesized, and
    the ping tells you what the run cost.
  </Card>

  <Card title="Release train" icon="train" href="/examples/release-train">
    **DevOps / Release**: parallel gates, a human GO, a hold until the
    window. Time as a first-class citizen.
  </Card>
</Columns>

## Find the example that teaches X

Looking for one construct? This index is generated from the workflow
files, so it cannot go stale.

| Construct                                                    | Taught by                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| ------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [fan-out over a collection](/concepts/workflows)             | [bookmark-triage](/examples/bookmark-triage) · [competitor-radar](/examples/competitor-radar) · [image-fx-batch](/examples/image-fx-batch) · [localization-factory](/examples/localization-factory) · [pr-review-fanout](/examples/pr-review-fanout) · [resume-screener](/examples/resume-screener)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| [bounded concurrency](/concepts/workflows)                   | [bookmark-triage](/examples/bookmark-triage) · [competitor-radar](/examples/competitor-radar) · [image-fx-batch](/examples/image-fx-batch) · [localization-factory](/examples/localization-factory) · [pr-review-fanout](/examples/pr-review-fanout) · [resume-screener](/examples/resume-screener)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| [collect-errors batches](/concepts/workflows)                | [bookmark-triage](/examples/bookmark-triage) · [competitor-radar](/examples/competitor-radar) · [localization-factory](/examples/localization-factory) · [pr-review-fanout](/examples/pr-review-fanout) · [resume-screener](/examples/resume-screener)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| [CEL conditional gate](/concepts/workflows)                  | [ceo-monday-brief](/examples/ceo-monday-brief) · [competitor-radar](/examples/competitor-radar) · [config-drift-sentinel](/examples/config-drift-sentinel) · [etl-quarantine](/examples/etl-quarantine) · [incident-war-room](/examples/incident-war-room) · [invoice-chaser](/examples/invoice-chaser) · [pr-review-fanout](/examples/pr-review-fanout) · [price-watch](/examples/price-watch) · [release-notes](/examples/release-notes) · [release-radar](/examples/release-radar) · [release-train](/examples/release-train) · [resume-screener](/examples/resume-screener) · [support-triage](/examples/support-triage)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| [transient-error retry](/reference/error-codes)              | [bookmark-triage](/examples/bookmark-triage) · [competitor-radar](/examples/competitor-radar) · [config-drift-sentinel](/examples/config-drift-sentinel) · [incident-war-room](/examples/incident-war-room) · [release-train](/examples/release-train)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| [task time-bound](/concepts/workflows)                       | [competitor-radar](/examples/competitor-radar) · [release-train](/examples/release-train)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| [fallback recovery](/reference/error-codes)                  | [bookmark-triage](/examples/bookmark-triage) · [ceo-monday-brief](/examples/ceo-monday-brief) · [competitor-radar](/examples/competitor-radar) · [config-drift-sentinel](/examples/config-drift-sentinel) · [etl-quarantine](/examples/etl-quarantine) · [incident-war-room](/examples/incident-war-room) · [localization-factory](/examples/localization-factory) · [pr-review-fanout](/examples/pr-review-fanout) · [price-watch](/examples/price-watch) · [release-notes](/examples/release-notes) · [release-radar](/examples/release-radar) · [resume-screener](/examples/resume-screener) · [seo-content-brief](/examples/seo-content-brief)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| [the data boundary · bindings ARE edges](/concepts/bindings) | [bookmark-triage](/examples/bookmark-triage) · [ceo-monday-brief](/examples/ceo-monday-brief) · [competitor-radar](/examples/competitor-radar) · [config-drift-sentinel](/examples/config-drift-sentinel) · [contract-guard](/examples/contract-guard) · [csv-chart-report](/examples/csv-chart-report) · [deep-research-brief](/examples/deep-research-brief) · [etl-quarantine](/examples/etl-quarantine) · [image-fx-batch](/examples/image-fx-batch) · [incident-war-room](/examples/incident-war-room) · [invoice-chaser](/examples/invoice-chaser) · [localization-factory](/examples/localization-factory) · [meeting-actions](/examples/meeting-actions) · [model-bench](/examples/model-bench) · [pr-review-fanout](/examples/pr-review-fanout) · [price-watch](/examples/price-watch) · [release-notes](/examples/release-notes) · [release-radar](/examples/release-radar) · [release-train](/examples/release-train) · [resume-screener](/examples/resume-screener) · [seo-content-brief](/examples/seo-content-brief) · [social-repurpose](/examples/social-repurpose) · [standup-digest](/examples/standup-digest) · [support-triage](/examples/support-triage) · [transcript-shownotes](/examples/transcript-shownotes)                                    |
| [jq output bindings](/concepts/bindings)                     | [ceo-monday-brief](/examples/ceo-monday-brief) · [price-watch](/examples/price-watch) · [release-radar](/examples/release-radar) · [seo-content-brief](/examples/seo-content-brief)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| [typed (structured) output](/concepts/verbs)                 | [contract-guard](/examples/contract-guard) · [deep-research-brief](/examples/deep-research-brief) · [incident-war-room](/examples/incident-war-room) · [meeting-actions](/examples/meeting-actions) · [pr-review-fanout](/examples/pr-review-fanout) · [release-notes](/examples/release-notes) · [resume-screener](/examples/resume-screener) · [seo-content-brief](/examples/seo-content-brief) · [support-triage](/examples/support-triage) · [transcript-shownotes](/examples/transcript-shownotes)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| [extended thinking budget](/concepts/verbs)                  | [ceo-monday-brief](/examples/ceo-monday-brief) · [deep-research-brief](/examples/deep-research-brief) · [incident-war-room](/examples/incident-war-room)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| [vault-backed secrets](/reference/yaml-syntax)               | [ceo-monday-brief](/examples/ceo-monday-brief) · [config-drift-sentinel](/examples/config-drift-sentinel) · [incident-war-room](/examples/incident-war-room) · [price-watch](/examples/price-watch) · [release-notes](/examples/release-notes) · [support-triage](/examples/support-triage)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| [typed workflow outputs (callable)](/reference/yaml-syntax)  | [bookmark-triage](/examples/bookmark-triage) · [ceo-monday-brief](/examples/ceo-monday-brief) · [competitor-radar](/examples/competitor-radar) · [config-drift-sentinel](/examples/config-drift-sentinel) · [contract-guard](/examples/contract-guard) · [csv-chart-report](/examples/csv-chart-report) · [deep-research-brief](/examples/deep-research-brief) · [etl-quarantine](/examples/etl-quarantine) · [image-fx-batch](/examples/image-fx-batch) · [incident-war-room](/examples/incident-war-room) · [invoice-chaser](/examples/invoice-chaser) · [localization-factory](/examples/localization-factory) · [meeting-actions](/examples/meeting-actions) · [model-bench](/examples/model-bench) · [og-images](/examples/og-images) · [pr-review-fanout](/examples/pr-review-fanout) · [price-watch](/examples/price-watch) · [release-notes](/examples/release-notes) · [release-radar](/examples/release-radar) · [release-train](/examples/release-train) · [resume-screener](/examples/resume-screener) · [seo-content-brief](/examples/seo-content-brief) · [social-repurpose](/examples/social-repurpose) · [standup-digest](/examples/standup-digest) · [support-triage](/examples/support-triage) · [transcript-shownotes](/examples/transcript-shownotes) |
| [default-deny tool grants](/concepts/verbs)                  | [deep-research-brief](/examples/deep-research-brief) · [pr-review-fanout](/examples/pr-review-fanout)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| [sovereign local model](/concepts/providers)                 | [ceo-monday-brief](/examples/ceo-monday-brief) · [competitor-radar](/examples/competitor-radar) · [config-drift-sentinel](/examples/config-drift-sentinel) · [contract-guard](/examples/contract-guard) · [deep-research-brief](/examples/deep-research-brief) · [incident-war-room](/examples/incident-war-room) · [invoice-chaser](/examples/invoice-chaser) · [localization-factory](/examples/localization-factory) · [meeting-actions](/examples/meeting-actions) · [model-bench](/examples/model-bench) · [pr-review-fanout](/examples/pr-review-fanout) · [release-notes](/examples/release-notes) · [release-radar](/examples/release-radar) · [resume-screener](/examples/resume-screener) · [seo-content-brief](/examples/seo-content-brief) · [social-repurpose](/examples/social-repurpose) · [standup-digest](/examples/standup-digest) · [support-triage](/examples/support-triage) · [transcript-shownotes](/examples/transcript-shownotes)                                                                                                                                                                                                                                                                                                                |

## The rules every example obeys

* **One verb per task** · `infer`, `exec`, `invoke` or `agent`.
* **The binding IS the edge** · `${{ tasks.X.* }}` lives in `with:`
  (data) — each reference declares a typed edge — and `after:` orders on
  state. The DAG has no invisible edges, and the body reads
  `${{ with.<name> }}`, never `tasks.*` (`NIKA-VAR-021`).
* **Local by default** · every file leads `ollama/llama3.2:3b`: zero
  API keys, nothing leaves your machine. Cloud providers appear only as
  per-task overrides or swap hints, never as the envelope default.
* **Projection, not copy-paste** · these pages and the
  [nika.sh use-cases explorer](https://nika.sh/#use-cases) render the
  same files, projected by `showcase-projector.py`. Any drift fails CI.

Repeat an AI task weekly? Send it: [nika.sh/convert](https://nika.sh/convert).
We convert the best ones into showcase workflows, credited to you.

<Card title="Write your first workflow" icon="pen" href="/getting-started/first-workflow">
  Ready to write your own? Start from the guided first-workflow walk.
</Card>


# PR review fan-out
Source: https://docs.nika.sh/examples/pr-review-fanout

T3 · engineering: one read-only review agent per changed file. A swarm with a leash.

> **T3 · engineering**: `for_each` + `agent:` is the swarm pattern.
> Every changed file gets its own mini-agent with **read-only tools**
> (default-deny means exactly that), a turn budget and a token budget.
> jq flattens the typed findings; one model writes the summary.

## The job

Big PRs get shallow reviews because attention doesn't scale. Here it
does: each changed file is reviewed in isolation by an agent that can
READ and nothing else, in parallel, four at a time. A deterministic
`nika:grep` sweep counts the TODO debt beside the LLM pass, and the
final REVIEW\.md ends with a verdict.

## The shape

```mermaid theme={"system"}
flowchart TD
  approve["approve · nika:prompt"]:::invoke
  changed["changed · git"]:::exec
  files["files · nika:jq"]:::invoke
  todo_sweep["todo_sweep · nika:grep"]:::invoke
  reviews["reviews · ∥ for_each · 2 tools"]:::agent
  merged["merged · nika:jq"]:::invoke
  summary["summary"]:::infer
  save["save · nika:write"]:::invoke
  approve --> changed
  approve -.->|success| changed
  changed --> files
  approve --> todo_sweep
  approve -.->|success| todo_sweep
  files --> reviews
  reviews --> merged
  merged --> summary
  todo_sweep --> summary
  summary --> save
  classDef infer fill:#5b8cff22,stroke:#5b8cff,color:#5b8cff
  classDef exec fill:#ff7a3c22,stroke:#ff7a3c,color:#ff7a3c
  classDef invoke fill:#22d3ee22,stroke:#22d3ee,color:#22d3ee
  classDef agent fill:#b07bff22,stroke:#b07bff,color:#b07bff
```

Watch the graph execute: the human gate first, independent branches in
parallel behind it, the agent fan-out mid-graph, and the join that waits
for both branches before `summary`:

<video>
  <source type="video/webm" />

  <source type="video/mp4" />
</video>

## The file

```yaml pr-review-fanout.nika.yaml theme={"system"}
nika: v1
workflow:
  id: pr-review-fanout
  description: "changed files → one read-only review agent each → merged REVIEW.md"

model: ollama/qwen3.5:4b   # local tool-calling model · swap for anthropic/claude-sonnet-4-6 for depth

const:
  base_ref: "main"
  review_root: "src/"      # the swarm's territory · keep in step with permits.fs.read

permits:
  tools: ["nika:done", "nika:grep", "nika:jq", "nika:prompt", "nika:read", "nika:write"]
  # The argv form (`exec.command:`) runs one named program with its arguments
  # and no shell between them, which is what makes a program allowlist mean
  # something. A `exec.shell:` task is refused against a list — measured:
  # `NIKA-SEC-004 · a shell-string command cannot be verified against a
  # permits.exec program allowlist (a pipeline can launch any program) — use
  # the array form`. Only `exec: true` admits a shell, and this workflow
  # deliberately never needs one.
  #
  # An allowlisted program is not an unconfined one: `git` runs inside the
  # `fs:` boundary below, which is why the header's second `Needs ·` line is
  # about git's global config rather than about git.
  exec: ["git"]
  fs:
    # `./src/**` covers the directory AND every descendant at any depth, which
    # is what both consumers need: `nika:grep` opens `./src` itself, and the
    # swarm reads files nested under it. A bare `./src` would cover only the
    # directory entry and refuse every file inside it.
    #
    # This bound is why `files` below filters the diff down to `const.review_root`:
    # `git diff` happily reports `Cargo.toml` or `.github/workflows/ci.yml`, and
    # an agent handed one of those would die `NIKA-SEC-004` mid-swarm. The claim
    # and the territory are kept equal on purpose.
    read: ["./src/**"]
    write: ["./REVIEW.md"]

tasks:
  # The human gate (NEP-0002 · v2.2). `git diff` output is UNTRUSTED
  # content — a hostile branch names its own files — and this workflow
  # pairs it with a private `fs.read` and egress-capable tasks: the
  # lethal trifecta, unless a human dominates the path. The gate comes
  # FIRST so every task the diff output reaches descends from it (a gate
  # on a sibling branch dominates nothing — the data edge would bypass
  # it), and each root CONSUMES the answer affirmatively (NEP-0020 — a
  # bare `after:` admits the refusal: it settles success with value
  # false). Under `--answer approve=true` the CI one-pass answers it here.
  approve:
    invoke:
      tool: "nika:prompt"
      args:
        mode: "confirm"
        message: "diff ${{ const.base_ref }}...HEAD and fan out one review agent per changed file?"

  # `--diff-filter=d` drops deletions: a file that no longer exists cannot be
  # reviewed, and asking an agent to read it just burns a turn on an error.
  changed:
    after: { approve: success }
    with:
      go: ${{ tasks.approve.output }}
    when: ${{ with.go == true }}     # « no » at the gate → no diff, no swarm
    exec:
      command: ["git", "diff", "--name-only", "--diff-filter=d", "${{ const.base_ref }}...HEAD"]

  files:
    with:
      changed: ${{ tasks.changed.output }}
    when: ${{ with.changed != null }}  # a refused gate skips the diff → nothing to split
    invoke:
      tool: "nika:jq"
      args:
        input: "${{ with.changed }}"
        expression: >-
          split("\n")
          | map(select(length > 0))
          | map(select(startswith("${{ const.review_root }}")))

  # The deterministic pass. Debt does not need a model to be found, and this
  # runs whether or not anything changed. It too descends from the gate —
  # dominance is structural: a sibling branch that bypasses `approve`
  # would re-open the trifecta no matter how clean its own content is.
  todo_sweep:
    after: { approve: success }
    with:
      go: ${{ tasks.approve.output }}
    when: ${{ with.go == true }}     # the same « no » closes this branch too
    invoke:
      tool: "nika:grep"
      args:
        pattern: "TODO|FIXME|HACK"
        path: "./src"

  reviews:
    with:
      files: ${{ tasks.files.output }}
    for_each: ${{ with.files }}
    max_parallel: 4                    # four reviewers in flight · not forty
    fail_fast: false                   # one reviewer's bad day is not the swarm's
    on_error:
      recover: null                    # a budget-exhausted review yields null · filtered below
    agent:
      system: >-
        You are a precise code reviewer. Read the file, then finish with ONLY
        the schema'd object ({file, findings: [{severity, message, line}]} ·
        severity exactly one of blocker|high|med|low), then call nika:done.
      prompt: "Review ${{ item }} · bugs first, then risky patterns. Read it before judging."
      tools:
        - "nika:read"                  # read-only swarm · least privilege
        - "nika:done"
      max_turns: 6                     # read · think · answer · a little slack
      max_tokens_total: 30000          # per reviewer · the swarm's ceiling is this × the file count
      # `additionalProperties: false` on BOTH object nodes. Without it on the
      # inner one, a provider may add keys to a finding and the sort below is
      # ordering a shape that changed between runs.
      schema:
        type: object
        additionalProperties: false
        required: [file, findings]
        properties:
          file: { type: string }
          findings:
            type: array
            items:
              type: object
              additionalProperties: false
              required: [severity, message]
              properties:
                severity: { type: string, enum: [blocker, high, med, low] }
                message: { type: string }
                line: { type: integer }

  # The fan-in.
  #   `. // []`      · a clean diff SKIPS the swarm (an empty for_each resolves
  #                    null), and the fan-in has to survive its own good news.
  #   `select(. != null)` · the reviewers that recovered leave here, by value.
  #   `.findings[] + {file}` · flatten [[finding]] → [finding], each carrying
  #                    the file it came from.
  #   the rank object · `sort_by(.severity)` would be ALPHABETICAL, which puts
  #                    `low` above `med`. Severity order is a decision, so it is
  #                    written down.
  merged:
    with:
      reviews: ${{ tasks.reviews.output }}
    invoke:
      tool: "nika:jq"
      args:
        input: "${{ with.reviews }}"
        expression: >-
          (. // [])
          | map(select(. != null))
          | map(.findings[] + { file: .file })
          | sort_by({ blocker: 0, high: 1, med: 2, low: 3 }[.severity])

  summary:
    with:
      merged: ${{ tasks.merged.output }}
      todo_sweep: ${{ tasks.todo_sweep.output }}
    when: ${{ with.todo_sweep != null }}  # a refused gate skips the sweep → no page to write
    infer:
      max_tokens: 2500                 # a review page · not the whole diff back
      prompt: |
        Merge these review findings into REVIEW.md · blockers first ·
        ${{ with.merged }}
        Open TODO debt found by grep ·
        ${{ with.todo_sweep }}
        End with a verdict · ship / fix-first / redesign.

  save:
    with:
      summary: ${{ tasks.summary.output }}
    when: ${{ with.summary != null }}   # a refused gate skips the summary → no REVIEW.md
    invoke:
      tool: "nika:write"
      args:
        path: "./REVIEW.md"
        content: "${{ with.summary }}"

outputs:
  findings:
    value: ${{ tasks.merged.output }}
    description: "Every finding, blockers first, each attributed to its file"
  review:
    value: ${{ tasks.summary.output }}
    description: "The page a human reads · also written to ./REVIEW.md"
```

## How it works

<Steps>
  <Step title="exec output becomes a collection">
    `git diff --name-only` is a string; the jq `split("\n")` turns it
    into the array the fan-out iterates. Workflows turn ANY tool output
    into a collection this way.
  </Step>

  <Step title="Each agent is least-privilege">
    `tools: ["nika:read", "nika:done"]`: the reviewer can read source
    and end its loop. It cannot write, fetch, or wander. Budgets
    (`max_turns: 6`, `max_tokens_total: 30000`) bound the worst case.
  </Step>

  <Step title="Typed findings merge deterministically">
    Every agent returns `{file, findings[]}` per its schema. The jq
    fan-in flattens and sorts: blockers surface first in REVIEW\.md.
  </Step>
</Steps>

## Constructs you just used

| Construct             | Where                 | Reference                       |
| --------------------- | --------------------- | ------------------------------- |
| `for_each` + `agent:` | `reviews`             | [The 4 verbs](/concepts/verbs)  |
| default-deny `tools:` | `reviews.agent.tools` | [The 4 verbs](/concepts/verbs)  |
| `agent.schema:`       | `reviews`             | [The 4 verbs](/concepts/verbs)  |
| `nika:grep` sweep     | `todo_sweep`          | [Builtins](/reference/builtins) |

## Make it yours

* Specialize the swarm: route `*.rs` files to a Rust-prompted agent and `*.sql` to a migrations-prompted one with two filtered fan-outs.
* Add `mcp:git/*` to the tools to let reviewers read blame and history (still no write).
* Fail CI on blockers: end with `nika:assert` on `size()` of the blocker slice.

<Card title="Level up · T4 epic" icon="microscope" href="/examples/deep-research-brief">
  Final tier: multi-stage pipelines. Plan, budgeted agent, thinking
  synthesis, self-reporting runs.
</Card>


# Price watch
Source: https://docs.nika.sh/examples/price-watch

T1 starter · e-commerce: a price-drop alert with zero model calls.

> **T1 starter · e-commerce / personal**: no `infer:` anywhere in this
> file. A workflow engine is not an LLM wrapper: the DAG, the tools and
> one CEL comparison do the whole job, deterministically, for free.

## The job

You're waiting for a price to drop. Checking the page every day is a
robot's job. This workflow pulls one structured field from the shop's
API, compares it to your target, and pings your webhook only when it's
time to buy.

## The shape

```mermaid theme={"system"}
flowchart LR
  check["check · nika:fetch"]:::invoke
  alert["alert · nika:notify"]:::invoke
  check --> alert
  classDef invoke fill:#22d3ee22,stroke:#22d3ee,color:#22d3ee
```

## The file

```yaml price-watch.nika.yaml theme={"system"}
nika: v1
workflow:
  id: price-watch
  description: "Watch a product price, ping me when it drops below my target"

const:
  product_api: "https://api.shop.example.com/v1/products/macbook-air"
  alert_below: 899

secrets:
  alerts_webhook:
    source: env
    key: ALERTS_WEBHOOK_URL
    egress:                       # sanction the one send · the secret IS the URL
      - to: "nika:notify"
        host_from_self: true
permits:
  tools: ["nika:fetch", "nika:notify"]
  net:
    # TWO hosts, for two different reasons.
    #
    # `api.shop.example.com` is what `const.product_api` names — a literal
    # `check` can read, so a mismatch here is caught before the run.
    #
    # `hooks.slack.com` is the ALERT host, and it is the entry people leave
    # out. `host_from_self:` above sanctions the FLOW (this secret may be the
    # URL) — it does not grant the capability. The host stays unknown at
    # check, so it is judged at RUN against this bound: name the escalation
    # host here or the send is refused mid-run, the first time the price
    # actually drops. Swap it for wherever YOUR webhook lives.
    http: ["api.shop.example.com", "hooks.slack.com"]

tasks:
  check:
    invoke:
      tool: "nika:fetch"
      args:
        url: "${{ const.product_api }}"
        mode: jq
        jq: "."
    output:                           # named jq bindings over the raw response
      price: ".price"
      name: ".name"
    on_error:
      # Offline rehearsal · a sample ABOVE the target, so the gate below stays
      # closed and the dry run ends green with the alert skipped. The alert
      # path is therefore NOT exercised offline — which is exactly why the
      # `net:` bound above has to be right by reading, not by running.
      recover: { price: 949, name: "MacBook Air (offline sample)" }

  alert:
    with:
      price: ${{ tasks.check.price }}     # value edges · the named bindings cross the boundary here
      name: ${{ tasks.check.name }}
    when: ${{ with.price < const.alert_below }}
    invoke:
      tool: "nika:notify"
      args:
        channel: webhook
        target: "${{ secrets.alerts_webhook }}"
        message: "Price drop · ${{ with.name }} is now ${{ with.price }} (target ${{ const.alert_below }})"
        severity: info

outputs:
  price: ${{ tasks.check.price }}
```

## How it works

<Steps>
  <Step title="Fetch ONE field, not a page">
    `mode: jq` extracts structured JSON from the API response, and the
    `output:` block binds named fields: `${{ tasks.check.price }}` is a
    number, not a blob of HTML.
  </Step>

  <Step title="CEL gates the alert">
    The named binding crosses in `with:`
    (`price: ${{ tasks.check.price }}`), then
    `when: ${{ with.price < config.alert_below }}` is a plain CEL
    comparison. False → the task is skipped, not failed.
  </Step>

  <Step title="The webhook stays secret">
    `secrets:` declares a vault/env-backed reference. The URL is masked
    in logs: `${{ secrets.alerts_webhook }}` never appears in a trace.
  </Step>
</Steps>

## Constructs you just used

| Construct               | Where          | Reference                             |
| ----------------------- | -------------- | ------------------------------------- |
| `nika:fetch` `mode: jq` | `check`        | [Builtins](/reference/builtins)       |
| `output:` jq bindings   | `check.output` | [Bindings](/concepts/bindings)        |
| `when:` CEL comparison  | `alert`        | [Workflows](/concepts/workflows)      |
| `secrets:`              | envelope       | [YAML syntax](/reference/yaml-syntax) |

## Make it yours

* Watch N products: lift the URL into a list input and `for_each` over it. See [Competitor radar](/examples/competitor-radar) for the fan-out pattern.
* Schedule it: workflow files describe a run. Your host's cron (or `nika serve`) decides when runs start.
* Add a second `when:` branch that notifies on price INCREASES above a ceiling.

<Card title="Next · Social repurpose" icon="share-nodes" href="/examples/social-repurpose">
  The last starter introduces the diamond: one source fanning into
  three parallel rewrites.
</Card>


# Release notes
Source: https://docs.nika.sh/examples/release-notes

T2 chain · engineering: git log → typed notes → CHANGELOG edited in place → team pinged.

> **T2 chain · engineering / devrel**: the release-day ritual as one
> file: history in, a typed notes object out, the CHANGELOG updated
> **in place** with `nika:edit`, the team pinged with the headline.

## The job

Every release someone copy-pastes git log into a doc, rewrites it, pastes
it into the CHANGELOG, then announces it. Four manual steps, four chances
to drift. Here the git range is an input, the notes are a schema-typed
object, and the announcement quotes the same headline the CHANGELOG got.

## The shape

```mermaid theme={"system"}
flowchart LR
  approve["approve · nika:prompt"]:::invoke
  history["history · git"]:::exec
  notes["notes · typed"]:::infer
  existing["existing · nika:read"]:::invoke
  copy["copy · nika:write"]:::invoke
  changelog["changelog · nika:edit"]:::invoke
  announce["announce · nika:notify"]:::invoke
  approve --> history
  approve -.->|success| history
  history --> notes
  approve --> existing
  approve -.->|success| existing
  existing --> copy
  notes --> changelog
  copy -.->|success| changelog
  notes --> announce
  changelog -.->|success| announce
  classDef infer fill:#5b8cff22,stroke:#5b8cff,color:#5b8cff
  classDef exec fill:#ff7a3c22,stroke:#ff7a3c,color:#ff7a3c
  classDef invoke fill:#22d3ee22,stroke:#22d3ee,color:#22d3ee
```

## The file

```yaml release-notes.nika.yaml theme={"system"}
nika: v1
workflow:
  id: release-notes
  description: "git log → typed release notes → CHANGELOG insert → team ping"

# A NON-thinking local model, deliberately: a thinking model can spend the
# whole `max_tokens` budget in its think block and return before the JSON
# (engine#428). Schema showcases pick a model that answers directly.
model: ollama/llama3.2:3b

inputs:
  announce:
    type: bool
    default: false
    description: "Actually send the team ping (needs TEAM_WEBHOOK_URL)"

const:
  since_tag: "v0.80.0"
  changelog_src: "examples/fixtures/CHANGELOG.md" # point this at YOUR CHANGELOG.md
  changelog_out: "out/CHANGELOG.md"                        # the working copy this run edits

secrets:
  team_webhook:
    source: env
    key: TEAM_WEBHOOK_URL
    egress:                       # sanction the one send · the secret IS the URL
      - to: "nika:notify"
        host_from_self: true
permits:
  tools: ["nika:edit", "nika:notify", "nika:prompt", "nika:read", "nika:write"]
  exec: ["git"]                   # the ONE program this workflow may run
  fs:
    # The workflow never edits your changelog in place — it copies it and
    # edits the copy, so you move the result when the diff looks right.
    #
    # The working copy appears in BOTH lists, and that is not redundancy:
    # `nika:edit` reads the file before it writes it, so a write-only grant
    # is refused with NIKA-SEC-004 · outside permits.fs.read. Every in-place
    # builtin owes both halves.
    read: ["examples/fixtures/CHANGELOG.md", "out/CHANGELOG.md"]
    write: ["out/CHANGELOG.md"]
  net:
    # `host_from_self:` above sanctions the FLOW (the secret may be the URL) —
    # it does not grant the capability. The host stays unknown at check, so it
    # is judged at RUN against this bound: name the announce host here or the
    # send is refused mid-run, after the tokens are already spent.
    http: ["hooks.slack.com"]

tasks:
  # The human gate (NEP-0002 · v2.2). `git log` output is UNTRUSTED content —
  # a hostile branch writes its own commit subjects — and this workflow pairs
  # it with a private `fs.read` and a webhook: the lethal trifecta, unless a
  # human dominates the path. The gate comes FIRST and BOTH roots hang off it
  # (`history` carries the untrusted content, `existing` carries the private
  # read); a gate on a sibling branch dominates nothing. And each root
  # CONSUMES the answer affirmatively (NEP-0020 — a bare `after:` admits the
  # refusal: it settles success with value false), the downstream null-guards
  # passing the « no » along the value edges. Non-interactive runs answer it
  # in one pass with `--answer approve=true`.
  approve:
    invoke:
      tool: "nika:prompt"
      args:
        mode: "confirm"
        message: "read the git history since ${{ const.since_tag }}, rewrite the changelog copy, and ping the team if announce is on?"

  history:
    after: { approve: success }
    with:
      go: ${{ tasks.approve.output }}
    when: ${{ with.go == true }}       # « no » at the gate → no history read at all
    exec:
      command: ["git", "log", "${{ const.since_tag }}..HEAD", "--oneline", "--no-merges"]
    on_error:
      # No such tag here (or not a repo at all) → a sample log takes over and
      # the rest of the chain is exercised exactly as it would be on the day.
      recover: |
        a1b2c3d feat(api): pagination cursors on every list endpoint
        d4e5f6a fix(auth): refresh tokens no longer rotate on read
        7g8h9i0 refactor(store): drop the legacy write path

  notes:
    with:
      history: ${{ tasks.history.output }}
    when: ${{ with.history != null }}  # a refused gate skips history → nothing to draft
    infer:
      max_tokens: 1000
      prompt: |
        Write release notes from these commits ·
        ${{ with.history }}
        Tone · plain, direct, no marketing fluff.
      schema:
        type: object
        additionalProperties: false
        required: [headline, body]
        properties:
          headline: { type: string }
          breaking: { type: array, items: { type: string } }
          body: { type: string }

  # Copy-then-edit · `nika:edit` is strictly in place and throws when `find:`
  # matches nothing (NIKA-BUILTIN-EDIT-001), so its target must exist and must
  # carry the anchor. Read yours, write the working copy, edit THAT.
  existing:
    after: { approve: success }
    with:
      go: ${{ tasks.approve.output }}
    when: ${{ with.go == true }}       # the same « no » closes the private-read branch
    invoke:
      tool: "nika:read"
      args: { path: "${{ const.changelog_src }}" }

  copy:
    with:
      existing: ${{ tasks.existing.output }}
    when: ${{ with.existing != null }}  # a refused gate skips the read → nothing to copy
    invoke:
      tool: "nika:write"
      args:
        path: "${{ const.changelog_out }}"
        content: "${{ with.existing }}"
        create_dirs: true
        overwrite: true

  changelog:
    with:
      notes_headline: ${{ tasks.notes.output.headline }}
      notes_body: ${{ tasks.notes.output.body }}
    after:
      copy: success              # state, no data · the anchor is on disk before we edit
    invoke:
      tool: "nika:edit"
      args:
        path: "${{ const.changelog_out }}"
        find: "# Changelog"      # a LITERAL string · not a regex
        count: 1                 # the top anchor only · never every occurrence
        replace: |
          # Changelog

          ## ${{ const.since_tag }}..HEAD · ${{ with.notes_headline }}

          ${{ with.notes_body }}

  announce:
    with:
      notes_headline: ${{ tasks.notes.output.headline }}
    when: ${{ inputs.announce == true }}   # OFF by default · a rehearsal must not ping the team
    after:
      changelog: success
    invoke:
      tool: "nika:notify"
      args:
        channel: webhook
        target: "${{ secrets.team_webhook }}"
        message: "Release notes ready · ${{ with.notes_headline }}"
        severity: info

outputs:
  headline: ${{ tasks.notes.output.headline }}
  body: ${{ tasks.notes.output.body }}
```

## How it works

<Steps>
  <Step title="The range is an input, not a hardcode">
    `${{ inputs.since_tag }}..HEAD`: next release you change one input,
    or pass it at run time.
  </Step>

  <Step title="Typed notes · headline + breaking + body">
    The schema means `${{ tasks.notes.output.headline }}` is a real
    field downstream: in the CHANGELOG insert AND in the ping. One
    source, two consumers, no drift.
  </Step>

  <Step title="Edit-in-place, not overwrite">
    `nika:edit` finds the `# Changelog` heading and replaces it with
    itself + the new section: the file's history stays intact below.
  </Step>
</Steps>

## Constructs you just used

| Construct                        | Where       | Reference                       |
| -------------------------------- | ----------- | ------------------------------- |
| `exec:` with input interpolation | `history`   | [The 4 verbs](/concepts/verbs)  |
| `infer.schema:`                  | `notes`     | [The 4 verbs](/concepts/verbs)  |
| `nika:edit` find/replace         | `changelog` | [Builtins](/reference/builtins) |
| `nika:notify` + `secrets:`       | `announce`  | [Builtins](/reference/builtins) |

## Make it yours

* Gate the announce behind a human: add a `nika:prompt` task between `changelog` and `announce`. The pattern is in [Invoice chaser](/examples/invoice-chaser).
* Add `breaking:` to the ping when `size(tasks.notes.output.breaking) > 0`.
* Render a public version too: a second `infer` task with a "user-facing tone" prompt, writing `docs/changelog/`.

<Card title="Next · SEO content brief" icon="magnifying-glass-chart" href="/examples/seo-content-brief">
  Chained fetch extractions (sitemap mode, then article mode) and CEL
  indexing into a binding.
</Card>


# Release radar
Source: https://docs.nika.sh/examples/release-radar

T2 chain · devops: dependency release feeds diffed against last run · only the NEW ships reach you.

> **T2 chain · devops / dependency hygiene**: `mode: feed` parses
> RSS/Atom natively, and the **state-file pattern** (read last run →
> diff → write next state) means you only hear about what's new.

## The job

« Did anything we depend on ship this week? » Checking releases pages
is a robot's job. This workflow reads the Atom feed, diffs it against
what it saw last run (RFC 6902: empty patch means silence), digests
only the new entries, and saves the state for next time. First run?
The missing state file recovers to an empty list.

## The shape

```mermaid theme={"system"}
flowchart LR
  approve["approve · nika:prompt"]:::invoke
  no_state["no_state · nika:jq"]:::invoke
  previous["previous · nika:read"]:::invoke
  feed["feed · nika:fetch"]:::invoke
  fresh["fresh · nika:json_diff"]:::invoke
  digest["digest"]:::infer
  save_state["save_state · nika:write"]:::invoke
  approve --> no_state
  approve --> previous
  approve --> feed
  previous --> fresh
  feed --> fresh
  fresh --> digest
  feed --> digest
  feed --> save_state
  classDef infer fill:#5b8cff22,stroke:#5b8cff,color:#5b8cff
  classDef invoke fill:#22d3ee22,stroke:#22d3ee,color:#22d3ee
```

## The file

```yaml release-radar.nika.yaml theme={"system"}
nika: v1
workflow:
  id: release-radar
  description: "dependency release feed → diff vs last run → only the NEW ships"

model: ollama/qwen3.5:4b   # local · zero key · swap for any provider in the catalog

const:
  releases_feed: "https://github.com/tokio-rs/tokio/releases.atom"
  state_path: "out/release-radar.json"
permits:
  tools: ["nika:fetch", "nika:jq", "nika:json_diff", "nika:prompt", "nika:read", "nika:write"]
  fs:
    # The state-file pattern touches exactly ONE path, on both sides: read
    # last run's state, write the next. `const.state_path` names it and a run
    # cannot move a const, so the same literal is the whole boundary —
    # `create_dirs:` makes out/ underneath it on the first run.
    read: ["out/release-radar.json"]
    write: ["out/release-radar.json"]
  net:
    http: ["github.com"]   # the feed's host · net entries are exact names, never globs

tasks:
  # The human gate first (NIKA-SEC-009 · NEP-0002, the Rule of Two as a
  # static check). This boundary permits all three legs — private read
  # (the state file) + untrusted ingress (the release feed) + egress
  # (the state write) — so a blocking prompt (no default:) dominates the
  # flow before a byte moves. Headless surfaces pause durably and resume
  # with `--resume <trace> --answer approve=true`.
  approve:
    invoke:
      tool: "nika:prompt"
      args:
        message: "This run fetches ${{ const.releases_feed }}, diffs against ${{ const.state_path }}, and rewrites that state file. Proceed?"

  # First run has no state file · recover to an empty list.
  no_state:
    with:
      go: ${{ tasks.approve.output }}
    when: ${{ with.go == true }}
    invoke:
      tool: "nika:jq"
      args: { input: [], expression: "." }

  previous:
    with:
      go: ${{ tasks.approve.output }}
    when: ${{ with.go == true }}
    invoke:
      tool: "nika:read"
      args: { path: "${{ const.state_path }}" }
    on_error:
      on_codes: [NIKA-BUILTIN-READ-001]   # not-found ONLY · a permission error still fails loudly
      recover: ${{ tasks.no_state.output }}

  feed:
    with:
      go: ${{ tasks.approve.output }}
    when: ${{ with.go == true }}
    invoke:
      tool: "nika:fetch"
      args:
        url: "${{ const.releases_feed }}"
        mode: feed
    output:
      entries: "[.items[] | {title, url, published}]"
    on_error:
      # No network → this sample stands in for the RAW feed response, so it
      # carries `items:` exactly as `mode: feed` returns it and the `output:`
      # jq above runs over it unchanged. Recovering the BINDING's shape
      # instead makes the jq throw NIKA-VAR-004 — the recovery must mirror the
      # response, never the binding.
      recover:
        items:
          - { title: "tokio 1.48.0", url: "https://github.com/tokio-rs/tokio/releases/tag/tokio-1.48.0", published: "2026-07-21T09:14:00Z" }
          - { title: "tokio 1.47.1", url: "https://github.com/tokio-rs/tokio/releases/tag/tokio-1.47.1", published: "2026-07-02T16:40:00Z" }

  fresh:
    with:
      previous: ${{ tasks.previous.output }}
      entries: ${{ tasks.feed.entries }}
    invoke:
      tool: "nika:json_diff"
      args:
        before: "${{ with.previous }}"
        after: "${{ with.entries }}"

  digest:
    with:
      fresh: ${{ tasks.fresh.output }}
      entries: ${{ tasks.feed.entries }}
    when: ${{ size(with.fresh) > 0 }}
    infer:
      max_tokens: 500
      prompt: |
        New releases appeared on our dependency radar (RFC 6902 patch
        against last run) ·
        ${{ with.fresh }}
        Full current feed · ${{ with.entries }}
        Write 3 bullets · what shipped · whether it looks breaking ·
        what to check in our code.

  save_state:
    with:
      entries: ${{ tasks.feed.entries }}
    invoke:
      tool: "nika:write"
      args:
        path: "${{ const.state_path }}"
        content: "${{ with.entries }}"
        create_dirs: true
        overwrite: true

outputs:
  new_entries:
    value: ${{ tasks.fresh.output }}
    description: "RFC 6902 ops · empty = nothing new since last run"
  # Untyped on purpose: `digest` is `when:`-gated, so on a quiet week it is
  # SKIPPED and this reads null. Exporting it is also what keeps those tokens
  # from being dead spend — an infer whose output nothing consumes is paid for
  # and thrown away, and `check` says so.
  briefing: ${{ tasks.digest.output }}
```

## How it works

<Steps>
  <Step title="feed mode does the parsing">
    `mode: feed` turns RSS/Atom into structured items: no scraping,
    no XML wrangling. The `output:` binding keeps just title/url/date.
  </Step>

  <Step title="State makes it incremental">
    `previous` reads the state file (recovering to `[]` on first run) ·
    `nika:json_diff` against the fresh feed yields ONLY the new
    entries · `save_state` overwrites for next time.
  </Step>

  <Step title="Silence is the feature">
    The digest runs `when: size(...) > 0`: nothing new, no model
    call, no noise. Schedule it daily and forget it.
  </Step>
</Steps>

## Constructs you just used

| Construct                      | Where                     | Reference                             |
| ------------------------------ | ------------------------- | ------------------------------------- |
| `nika:fetch` `mode: feed`      | `feed`                    | [Builtins](/reference/builtins)       |
| state-file pattern             | `previous` · `save_state` | [Bindings](/concepts/bindings)        |
| `nika:json_diff` (RFC 6902)    | `fresh`                   | [Builtins](/reference/builtins)       |
| `on_error: recover:` first-run | `previous`                | [Error model](/reference/error-codes) |

## Make it yours

* Watch N dependencies: lift the feed URL into a list and `for_each` the fetch ([Competitor radar](/examples/competitor-radar) shows the leash).
* Pipe breaking-change suspects into [PR review fan-out](/examples/pr-review-fanout)'s reviewer prompt.
* Swap the feed for your vendor's changelog RSS. The shape doesn't change.

<Card title="Next · Resume screener" icon="user-check" href="/examples/resume-screener">
  PII never leaves the machine: a local-model rubric per candidate,
  ranked deterministically.
</Card>


# Release train
Source: https://docs.nika.sh/examples/release-train

T4 epic · devops: parallel gates, a human GO, an absolute-time hold until the window · ship, verify, record.

> **T4 epic · devops / release engineering**: time is a first-class
> citizen. The train holds with `nika:wait until:` (an absolute
> timestamp, not a sleep), the gates' duration is computed with
> `nika:date op: diff`, a human signs the departure, and the record
> lands in the journal **whether the ship success or not**.

## The job

Release day choreography: tests, lint and audit run as one parallel
wave; an assert refuses departure on any red; the conductor signs with
full information (« gates GREEN in 12 min · ship 1.4.0 in the 09:00Z
window? »); the train holds until the window; ships; re-polls prod
until it reports the new version; and `on_finally` files the departure
record either way.

## The shape

```mermaid theme={"system"}
flowchart TD
  t0["t0 · nika:date"]:::invoke
  declared["declared · nika:read"]:::invoke
  notes["notes · nika:read"]:::invoke
  schema["schema · nika:read"]:::invoke
  board["board · nika:jq"]:::invoke
  gates_green["gates_green · nika:assert"]:::invoke
  t1["t1 · nika:date"]:::invoke
  gate_time["gate_time · nika:date"]:::invoke
  conductor["conductor · nika:prompt"]:::invoke
  signed_at["signed_at · nika:date"]:::invoke
  window["window · nika:date"]:::invoke
  hold["hold · nika:wait"]:::invoke
  ship["ship · ./scripts/release.sh"]:::exec
  verify["verify · nika:fetch"]:::invoke
  live["live · nika:assert"]:::invoke
  record["record · nika:emit"]:::invoke
  declared --> board
  notes --> board
  schema --> board
  board --> gates_green
  gates_green -.->|success| t1
  t0 --> gate_time
  t1 --> gate_time
  gate_time --> conductor
  board --> conductor
  conductor --> signed_at
  signed_at --> window
  window --> hold
  hold -.->|success| ship
  ship -.->|success| verify
  verify --> live
  live --> record
  live -.->|terminal| record
  classDef exec fill:#ff7a3c22,stroke:#ff7a3c,color:#ff7a3c
  classDef invoke fill:#22d3ee22,stroke:#22d3ee,color:#22d3ee
```

## The file

```yaml release-train.nika.yaml theme={"system"}
nika: v1
workflow:
  id: release-train
  description: "parallel gates → one verdict → human GO → hold until the window → ship · verify · record"

run:
  # Pin the clock out loud. Every `timeout:` and every absolute `until:` below
  # rides it; leaving it undeclared is the honest default (the ambient system
  # clock) but never a stated choice, and the checker says so ([run-clock]).
  # `clock: virtual` swaps in a simulated clock for tests (F-P3).
  clock: system

inputs:
  version:
    type: string
    required: true
    description: "The version you intend to ship · gate 1 checks it against ./VERSION"
  depart:
    type: bool
    default: false
    description: "Actually run the release script. OFF: the train rehearses and records that it stayed."
  hold_for:
    type: string
    default: "15m"
    description: "How far out the departure window sits, measured from the moment the departure is SIGNED"

permits:
  exec: ["./scripts/release.sh"]  # ONE program · the departure, and nothing else
  tools: ["nika:assert", "nika:date", "nika:emit", "nika:fetch", "nika:jq", "nika:prompt", "nika:read", "nika:wait"]
  net:
    # ONE host, exact — the post-ship version probe and nothing else. This train
    # deliberately owns no webhook: see the `record` task for why an
    # always-fires task must never be the one that leaves the machine.
    http: ["api.example.com"]
  fs:
    # Three files, read-only, named one by one. The gates below are the release
    # checks a spec repo can actually run; in a Rust shop they are `cargo test`
    # / `clippy` / `audit` under `exec:` with `capture: structured`, and the
    # `permits.exec` list grows instead. The WAVE and the fold are the lesson —
    # the identity of the three checks is yours to choose.
    read:
      - "./VERSION"
      - "./CHANGELOG.md"
      - "./schemas/workflow.schema.json"

tasks:
  t0:
    invoke:
      tool: "nika:date"
      args: { op: now }

  # ── the gate wave · three checks, one wave, no shared state ──
  declared:
    invoke:
      tool: "nika:read"
      args: { path: "./VERSION" }

  notes:
    invoke:
      tool: "nika:read"
      args: { path: "./CHANGELOG.md" }

  schema:
    invoke:
      tool: "nika:read"
      args: { path: "./schemas/workflow.schema.json" }

  # ── fold · three answers become one board, computed, not narrated ──
  board:
    with:
      declared: ${{ tasks.declared.output }}
      notes: ${{ tasks.notes.output }}
      schema: ${{ tasks.schema.output }}
    invoke:
      tool: "nika:jq"
      args:
        # The four inputs arrive as an ARRAY and are destructured by name, so
        # the expression reads like the checklist it is. Building the verdict in
        # jq rather than in a model keeps it deterministic and free.
        input:
          - "${{ with.declared }}"
          - "${{ with.notes }}"
          - "${{ with.schema }}"
          - "${{ inputs.version }}"
        expression: |
          . as [$declared, $notes, $schema, $asked]
          | { version_matches: (($declared | rtrimstr("\n")) == $asked),
              notes_present:   ($notes  | test("\\[" + $asked + "\\]")),
              schema_parses:   (try ($schema | fromjson | has("$id")) catch false) }
          | . + { all_green: (.version_matches and .notes_present and .schema_parses) }

  gates_green:
    with:
      board: ${{ tasks.board.output }}
    invoke:
      tool: "nika:assert"
      args:
        # A RED board stops the train here: everything downstream is cancelled,
        # and `record` below still lands the fact that it never left.
        condition: "${{ with.board.all_green }}"
        message: "A release gate is RED: the train does not depart · ${{ with.board }}"

  t1:
    after:
      gates_green: success           # state, no data · the clock stops on a green board
    invoke:
      tool: "nika:date"
      args: { op: now }

  gate_time:
    with:
      t0: ${{ tasks.t0.output }}
      t1: ${{ tasks.t1.output }}
    invoke:
      tool: "nika:date"
      args:
        # `start:`/`end:` want real ISO timestamps — the literal "now" is not a
        # value here and fails NIKA-BUILTIN-DATE-001. Take the reading in a task,
        # then pass it as data; that is also what makes the run replayable.
        op: diff
        start: "${{ with.t0 }}"
        end: "${{ with.t1 }}"
        unit: minutes

  # ── the human signs the departure ──
  conductor:
    with:
      gate_time: ${{ tasks.gate_time.output }}
      board: ${{ tasks.board.output }}
    invoke:
      # Blocking · no `default:`. The alternative shape is a `default: false`
      # prompt (see templates/human-gated-ship): fail-closed, never pauses, and
      # a yes can then only come from a TTY. This file blocks instead so the
      # decision can also be handed over — `--resume <trace> --answer
      # conductor=true` — which is how a release actually gets signed when the
      # person who ran it is not the person who approves it. Either way the
      # checker leaves a [headless-prompt] hint: that is the price of a gate.
      tool: "nika:prompt"
      args:
        message: |
          Board · ${{ with.board }}
          Green in ${{ with.gate_time }} min.

          Ship ${{ inputs.version }} · departure window opens in ${{ inputs.hold_for }}?
          (depart armed: ${{ inputs.depart }})

  # ── hold until the window · an absolute instant, computed AFTER the signature ──
  #
  # The window opens `hold_for` from the moment the departure was SIGNED, which
  # is why this reading is taken here and not reused from `t1`. Measured, and
  # the reason this task exists: the run pauses at the prompt, so `t1` is
  # minutes or hours old by the time a human answers — resuming with `t1+ 15m`
  # produced `NIKA-BUILTIN-WAIT-002 · until: … is in the past` on the very
  # first resume. An absolute instant must be computed from a reading taken
  # after the last thing that can block. (Resume it a SECOND time and this
  # reading is itself a cache hit — `--from signed_at` re-takes it.)
  signed_at:
    with:
      signed: ${{ tasks.conductor.output }}
    when: ${{ with.signed == true }}
    invoke:
      tool: "nika:date"
      args: { op: now }

  window:
    with:
      at: ${{ tasks.signed_at.output }}
    when: ${{ with.at != null }}
    invoke:
      tool: "nika:date"
      args:
        op: add
        base: "${{ with.at }}"
        duration: "${{ inputs.hold_for }}"

  hold:
    with:
      window: ${{ tasks.window.output }}
    when: ${{ with.window != null }}
    invoke:
      # `until:` is an INSTANT, not a nap: restart the run and it still targets
      # the same moment, where a `duration:` would start counting again. The
      # instant is computed from `t1` above precisely so this file cannot rot —
      # a literal `until: "2026-07-28T09:00:00Z"` is correct for one day and
      # then fails NIKA-BUILTIN-WAIT-002 · the timestamp is in the past.
      tool: "nika:wait"
      args:
        until: "${{ with.window }}"
        timeout: "48h"             # `timeout:` caps an absolute wait · until-only

  # ── the irreversible step · armed, and only after the hold ──
  ship:
    after:
      hold: success
    with:
      depart: ${{ inputs.depart }}
    when: ${{ with.depart == true }}   # dry-run by default · a rehearsal ships nothing
    exec:
      # argv, never a shell string: `${{ inputs.version }}` is substituted as ONE
      # argument and cannot break out into a second command.
      #
      # Default capture (stdout) on purpose. `capture: structured` would turn a
      # non-zero exit into DATA and this task would report success even when the
      # release script died — which is exactly what `after: {ship: success}`
      # below must not be lied to about. The checker flags that shape when
      # nothing reads `exit_code` ([swallowed-exit]); here the honest answer is
      # not to read the code but to let a failed release FAIL, NIKA-EXEC-001.
      command: ["./scripts/release.sh", "${{ inputs.version }}"]
    timeout: "30m"

  verify:
    after:
      ship: success                  # never probe prod for a release that did not go out
    invoke:
      tool: "nika:fetch"
      args:
        url: "https://api.example.com/v1/version"
        mode: jq
        jq: ".version"
    retry:
      # A GET is idempotent, so retrying it replays nothing — the checker warns
      # [retry-effects] when you retry something that is not.
      max_attempts: 5
      backoff_strategy: exponential
      backoff_ms: 5000

  live:
    with:
      version_live: ${{ tasks.verify.output == inputs.version }}   # the whole check crosses as ONE boundary expression
    invoke:
      tool: "nika:assert"
      args:
        condition: "${{ with.version_live }}"
        message: "Prod does not report the shipped version: investigate before announcing"

  # ── the departure record · lands on EVERY outcome ──
  #
  # `after: {live: terminal}` admits success · failure · skipped · cancelled, so
  # this runs when the train departed, when a gate was red, and when nobody
  # armed it. `nika:emit` is the right verb for a record that must never fail:
  # it crosses no boundary, needs no host, and cannot be refused mid-flight.
  #
  # It is also the only verb that can safely sit here, and that is a rule worth
  # keeping: AN ALWAYS-FIRES TASK MUST NOT BE THE ONE THAT LEAVES THE MACHINE.
  # A `terminal` edge admits `cancelled`, so the task is reachable along a path
  # where the human never answered — no gate can dominate it, and the moment
  # such a task can egress, NIKA-SEC-009 fires (measured: hanging a
  # `nika:notify` here turns this file RED, and moving the prompt to the root
  # does not save it). If you want the outcome on a webhook, put the send under
  # the signature — `t4-ceo-monday-brief` shows that shape — and leave the
  # unconditional record to `emit`.
  record:
    after:
      live: terminal
    with:
      outcome: ${{ tasks.live.status }}   # observe the verdict · same pass-set as the after edge
    invoke:
      tool: "nika:emit"
      args:
        event_type: "release.train.departed"
        payload:
          version: "${{ inputs.version }}"
          departed: "${{ inputs.depart }}"
          # The engine's word, not a paraphrase: `cancelled` here means the
          # verification never got to run, which is the truth on a rehearsal and
          # on a red board alike. `departed:` above is what disambiguates them.
          status: "${{ with.outcome }}"

outputs:
  board:
    value: ${{ tasks.board.output }}
    description: "The gate board · one boolean per check plus the verdict that stopped or released the train"
  shipped: ${{ tasks.verify.output }}
```

## How it works

<Steps>
  <Step title="until: is a hold, not a sleep">
    `nika:wait` with `until: 2026-07-28T09:00:00Z` parks the train at
    an ABSOLUTE time (capped by `timeout: 48h`). A relative `duration:`
    would drift with however long the gates took.
  </Step>

  <Step title="The human signs with full information">
    `nika:date op: diff` computes the gates' wall time, and the
    `nika:prompt` message carries it: the conductor decides knowing
    how fresh the green is. The assert after makes « no » terminal.
  </Step>

  <Step title="The record always lands">
    `verify` re-polls prod (retry × 5, exponential) until it reports
    the shipped version · the final assert refuses to claim success
    otherwise · `on_finally` emits the journal event + team ping with
    the REAL status, even on failure.
  </Step>
</Steps>

## Constructs you just used

| Construct                       | Where                                  | Reference                        |
| ------------------------------- | -------------------------------------- | -------------------------------- |
| `nika:wait` `until:` (absolute) | `hold`                                 | [Builtins](/reference/builtins)  |
| `nika:date` `op: diff`          | `gate_time`                            | [Builtins](/reference/builtins)  |
| parallel gate wave + asserts    | `tests`/`lint`/`audit` → `gates_green` | [Workflows](/concepts/workflows) |
| `on_finally:` departure record  | `live`                                 | [Workflows](/concepts/workflows) |

## Make it yours

* Generate the notes on the same train: insert [Release notes](/examples/release-notes) between `approved` and `hold`.
* Canary first: duplicate `ship`/`verify` against staging, gate prod behind a second assert.
* The `config.window` dial makes this a scheduled artifact: your cron passes next Tuesday 09:00Z, the train handles the rest.

<Card title="Back to all examples" icon="rocket" href="/examples/overview">
  The full gallery: four tiers, every construct taught by a real job.
</Card>


# Resume screener
Source: https://docs.nika.sh/examples/resume-screener

T3 fan-out · HR: a local-model rubric per candidate, ranked deterministically. PII never leaves the machine.

> **T3 fan-out · HR / recruiting**: CVs are PII, so the **whole
> screen runs on a local model**. One schema-enforced rubric for every
> candidate (enums kill « kinda-strong »), evidence quotes required,
> and the ranking is jq: deterministic, not model mood.

## The job

Forty CVs and a Friday deadline means the rubric drifts by CV #12.
Here glob discovers the pool, every candidate gets the SAME typed
rubric (fit enum, evidence quotes mandatory), two at a time so the
GPU breathes, weak fits drop, and jq sorts strong-first then by
relevant years. The shortlist brief quotes its evidence.

## The shape

```mermaid theme={"system"}
flowchart TD
  pool["pool · nika:glob"]:::invoke
  cvs["cvs · ∥ for_each · nika:read"]:::invoke
  pairs["pairs · nika:jq"]:::invoke
  screened["screened · ∥ for_each · typed"]:::infer
  ranked["ranked · nika:jq"]:::invoke
  shortlist["shortlist · nika:jq"]:::invoke
  brief["brief"]:::infer
  save["save · nika:write"]:::invoke
  pool --> cvs
  pool --> pairs
  cvs --> pairs
  pairs --> screened
  screened --> ranked
  ranked --> shortlist
  shortlist --> brief
  brief --> save
  classDef infer fill:#5b8cff22,stroke:#5b8cff,color:#5b8cff
  classDef invoke fill:#22d3ee22,stroke:#22d3ee,color:#22d3ee
```

## The file

```yaml resume-screener.nika.yaml theme={"system"}
nika: v1
workflow:
  id: resume-screener
  description: "glob CVs → local-model rubric per candidate → deterministic shortlist"

model: ollama/qwen3.5:4b   # PII stays on the machine · the whole screen is offline

const:
  role: "Senior Rust engineer"
  shortlist_size: 5
  # The committed rehearsal inbox. Point this at ./hiring/inbox (or wherever
  # your exports land) and change `permits.fs.read` to match, same edit.
  cv_glob: "./examples/fixtures/cvs/*.md"

permits:
  tools: ["nika:glob", "nika:jq", "nika:read", "nika:write"]
  # NO `net:` category. That absence is the whole sovereignty claim: with no
  # host granted, a CV that talks the model into exfiltrating itself still
  # has nowhere to go — the boundary refuses before the request is made.
  fs:
    # TWO entries, and both earn their place. `nika:glob` opens the ROOT of
    # its pattern before it lists anything, and a directory grant does not
    # cover its children while a child grant does not cover the directory —
    # so each is named. Measured: with only the second line, the run dies
    # `NIKA-SEC-004 · ./examples/…/cvs resolves outside permits.fs.read`
    # before a single CV is read.
    #
    # `*` is one segment and never crosses `/`, which is the right width
    # here: CVs land flat in the inbox. `cvs/**` would also work and would
    # additionally hand over every sub-tree someone drops in there.
    read:
      - "./examples/fixtures/cvs"      # the directory the glob opens
      - "./examples/fixtures/cvs/*"    # the CVs one level inside it
    # One brief, one path. Nothing else on this machine is writable by this
    # workflow — not `./hiring/**`, not a sibling of the brief.
    write: ["./hiring/shortlist-brief.md"]

tasks:
  # ── the pool is discovered at runtime · the count is never written down ──
  pool:
    invoke:
      tool: "nika:glob"
      args: { pattern: "${{ const.cv_glob }}" }

  cvs:
    with:
      paths: ${{ tasks.pool.output }}
    for_each: ${{ with.paths }}
    max_parallel: 8
    fail_fast: false                   # one unreadable CV must not stop the batch
    on_error:
      recover: null                    # null holds the index so the zip below stays aligned
    invoke:
      tool: "nika:read"
      args: { path: "${{ item }}" }

  # A for_each output is an array in ITEM ORDER, so `transpose` pairs each
  # path with its own text. The `select` is where the unreadable CVs leave.
  pairs:
    with:
      paths: ${{ tasks.pool.output }}
      texts: ${{ tasks.cvs.output }}
    invoke:
      tool: "nika:jq"
      args:
        input: ["${{ with.paths }}", "${{ with.texts }}"]
        expression: >-
          transpose
          | map(select(.[1] != null))
          | map({ path: .[0], text: .[1] })

  # ── one rubric, applied identically to everyone ────────────────────
  # `with.cv_path` reads `${{ item.path }}` — a pre-fan-out import that is
  # re-evaluated per iteration, which is how a loop-local reaches the prompt
  # under a name that means something.
  screened:
    with:
      pairs: ${{ tasks.pairs.output }}
      cv_path: ${{ item.path }}
    for_each: ${{ with.pairs }}
    max_parallel: 2                    # a local model shares one GPU · don't thrash it
    fail_fast: false
    on_error:
      recover: null
    infer:
      max_tokens: 1200                 # a rubric row, not an essay
      prompt: |
        Role · ${{ const.role }}
        Candidate file · ${{ with.cv_path }}
        CV ·
        ${{ item.text }}
        Score this candidate against the role. Quote evidence from the CV
        for every rating: no rating without a quote.
      # `additionalProperties: false` on EVERY object node — the top level and
      # each nested one. Without it a provider is free to add keys, and the
      # jq below would be sorting a shape that changes between runs.
      schema:
        type: object
        additionalProperties: false
        required: [file, fit, strengths, concerns]
        properties:
          file: { type: string }
          fit: { type: string, enum: [strong, possible, weak] }
          years_relevant: { type: integer }
          strengths: { type: array, items: { type: string } }
          concerns: { type: array, items: { type: string } }

  # ── the model judged · jq decides ──────────────────────────────────
  # Ranking lives HERE, not in a prompt, so the order is reproducible: same
  # scores in, same order out. `.fit != "strong"` sorts false (0) before true
  # (1), which puts the strong candidates first; `// 0` covers the candidates
  # whose CV never stated a number.
  ranked:
    with:
      screened: ${{ tasks.screened.output }}
    invoke:
      tool: "nika:jq"
      args:
        input: "${{ with.screened }}"
        expression: >-
          map(select(. != null))
          | map(select(.fit != "weak"))
          | sort_by(.fit != "strong", -(.years_relevant // 0))

  shortlist:
    with:
      ranked: ${{ tasks.ranked.output }}
    invoke:
      tool: "nika:jq"
      args:
        input: "${{ with.ranked }}"
        expression: ".[:${{ const.shortlist_size }}]"

  brief:
    with:
      shortlist: ${{ tasks.shortlist.output }}
    when: ${{ size(with.shortlist) > 0 }}   # nobody cleared the bar · spend nothing
    infer:
      max_tokens: 2000
      prompt: |
        Write the screening brief for these shortlisted candidates ·
        ${{ with.shortlist }}
        One paragraph each · lead with the evidence quotes · end with the
        suggested interview focus.

  save:
    with:
      brief: ${{ tasks.brief.output }}
    when: ${{ with.brief != null }}    # a skipped task reads null downstream · gate on the VALUE
    invoke:
      tool: "nika:write"
      args:
        path: "./hiring/shortlist-brief.md"
        content: "${{ with.brief }}"
        create_dirs: true

outputs:
  ranked:
    value: ${{ tasks.ranked.output }}
    description: "Everyone who was not scored weak · strong first, then by relevant years"
  shortlist:
    value: ${{ tasks.shortlist.output }}
    description: "The top `const.shortlist_size` of the ranking · what the brief covers"
```

## How it works

<Steps>
  <Step title="Sovereignty is the requirement, not a preference">
    `model: ollama/llama3.2:3b` at the envelope: candidate data never
    touches a cloud API. Same file shape as any other workflow.
  </Step>

  <Step title="One rubric, enforced by schema">
    `fit: enum [strong, possible, weak]` + required evidence arrays:
    candidate #1 and #40 are judged on the same axes, and a rating
    without a quote fails validation.
  </Step>

  <Step title="The ORDER is deterministic">
    `sort_by(.fit != "strong", -(.years_relevant // 0))`: strong fits
    first, then by years. Re-run it: same input, same shortlist.
  </Step>
</Steps>

## Constructs you just used

| Construct                | Where                  | Reference                        |
| ------------------------ | ---------------------- | -------------------------------- |
| local provider (PII)     | envelope `model:`      | [Providers](/concepts/providers) |
| `nika:glob` → `for_each` | `pool` · `screened`    | [Workflows](/concepts/workflows) |
| schema enums + evidence  | `screened`             | [The 4 verbs](/concepts/verbs)   |
| jq deterministic ranking | `ranked` · `shortlist` | [Builtins](/reference/builtins)  |

## Make it yours

* Anonymize first: a pre-pass `infer` that strips names/photos before scoring. Bias mitigation in one task.
* Wire the shortlist into [Meeting actions](/examples/meeting-actions)' pattern to draft interview invites.
* The same shape screens vendor proposals, grant applications, conference talks: any « N documents, one rubric » job.

<Card title="Next · Release train" icon="train" href="/examples/release-train">
  Time as a first-class citizen: parallel gates, a human GO, and an
  absolute-time hold until the window.
</Card>


# SEO content brief
Source: https://docs.nika.sh/examples/seo-content-brief

T2 chain · SEO: a content brief grounded in what your competitor actually published, not vibes.

> **T2 chain · SEO / content marketing**: two `nika:fetch` extractions
> chained (`sitemap` mode, then `article` mode), a jq slice binding, CEL
> indexing, and a schema-typed brief at the end.

## The job

« Write something that ranks for X » usually starts with an hour of
tab-hopping through the competitor's site. This workflow maps their
sitemap, reads their best page on the topic, finds the gaps, and hands
your writer a typed brief: title, angle, outline, keywords.

## The shape

```mermaid theme={"system"}
flowchart LR
  map["map · nika:fetch"]:::invoke
  top_page["top_page · nika:fetch"]:::invoke
  brief["brief · typed"]:::infer
  save["save · nika:write"]:::invoke
  map --> top_page
  map --> brief
  top_page --> brief
  brief --> save
  classDef infer fill:#5b8cff22,stroke:#5b8cff,color:#5b8cff
  classDef invoke fill:#22d3ee22,stroke:#22d3ee,color:#22d3ee
```

## The file

```yaml seo-content-brief.nika.yaml theme={"system"}
nika: v1
workflow:
  id: seo-content-brief
  description: "Competitor sitemap → top page → gap analysis → typed brief"

# A NON-thinking local model, deliberately: a thinking model can spend the
# whole `max_tokens` budget in its think block and return before the JSON
# (engine#428). Schema showcases pick a model that answers directly.
model: ollama/llama3.2:3b

inputs:
  topic:
    type: string
    # Slug-shaped on purpose: this value lands in a FILENAME below, and a
    # caller-supplied string that reaches a path is the tainted-value case the
    # checker polices (NIKA-AUTH-008). Keep it to one path segment — `*` in
    # the write bound never crosses `/`, so `a/b` is refused, by design.
    default: "rust-async-runtimes"
    description: "The keyword/topic you want to rank for (one path segment)"
const:
  competitor_sitemap: "https://competitor.example.com/sitemap.xml"
permits:
  tools: ["nika:fetch", "nika:write"]
  fs:
    # One brief per topic, written DIRECTLY in out/briefs/. `*` matches a
    # single path segment and never crosses `/`, so a topic carrying a slash
    # is refused instead of steering the write into a subtree — which is
    # exactly why this is `out/briefs/*.json` and not `out/briefs/**`.
    write: ["out/briefs/*.json"]
  net:
    # Both fetches stay on the competitor's own host: the sitemap, then a URL
    # that same sitemap listed. Net entries are exact host names, never globs —
    # add YOUR competitor's host here when you point the const at it, or the
    # fetch is refused at run and the recover path quietly takes over.
    http: ["competitor.example.com"]

tasks:
  map:
    invoke:
      tool: "nika:fetch"
      args:
        url: "${{ const.competitor_sitemap }}"
        mode: sitemap
    output:
      top: ".[:5] | map(.loc)"
    on_error:
      # The recovery stands in for the RAW response, so it has the shape a
      # sitemap fetch returns — a root array of {loc, …} — and the `output:`
      # jq above slices it exactly as it would slice the live one. Recover the
      # BINDING's shape instead and the jq runs against the wrong thing and
      # throws NIKA-VAR-004.
      recover:
        - { loc: "https://competitor.example.com/blog/async-runtimes-compared" }
        - { loc: "https://competitor.example.com/blog/tokio-vs-smol" }
        - { loc: "https://competitor.example.com/blog/choosing-an-executor" }

  top_page:
    with:
      map_top: ${{ tasks.map.top[0] }}
    invoke:
      tool: "nika:fetch"
      args:
        url: "${{ with.map_top }}"
        mode: article
    on_error:
      recover: |
        Async runtimes compared — we benchmarked four executors on the same
        workload. Tokio wins on ecosystem breadth; smol wins on binary size.
        We did not cover structured concurrency, cancellation safety, or how
        any of this behaves under a blocking call, which is where most teams
        actually get hurt.

  brief:
    with:
      map_top: ${{ tasks.map.top }}
      top_page: ${{ tasks.top_page.output }}
    infer:
      max_tokens: 1200
      prompt: |
        Topic to rank for · ${{ inputs.topic }}
        Competitor's top URLs · ${{ with.map_top }}
        Their best page on it ·
        ${{ with.top_page }}

        Write a content brief that BEATS this page · find the gaps they
        missed · angle for search intent.
      schema:
        type: object
        additionalProperties: false
        required: [title, angle, outline, keywords]
        properties:
          title: { type: string }
          angle: { type: string }
          outline: { type: array, items: { type: string } }
          keywords: { type: array, items: { type: string } }

  save:
    with:
      brief: ${{ tasks.brief.output }}
    invoke:
      tool: "nika:write"
      args:
        # `.json` content is ONE interpolated value — the engine serializes it.
        path: "out/briefs/${{ inputs.topic }}.json"
        content: "${{ with.brief }}"
        create_dirs: true
    # The topic names the output file, and an input is UNTRUSTED by default —
    # NEP-0004 law 2 re-gates the composed path at check (NIKA-AUTH-008). The
    # authored door says why THIS value is safe: the receipt records the taint
    # path · this because · the value digest, and the declassified value must
    # STILL fit fs.write ["out/briefs/*.json"] — a door, never a bypass.
    declassify:
      - from: inputs.topic
        to: trusted
        because: "the operator's own brief subject, typed at launch — it names the output file, nothing else"

outputs:
  brief:
    value: ${{ tasks.brief.output }}
    description: "The typed content brief"
```

## How it works

<Steps>
  <Step title="Sitemap mode + a jq slice">
    `mode: sitemap` returns the URL list; the `output:` binding
    `top: ".[:5] | map(.loc)"` keeps just the head of it, as bare
    `loc` URLs. Bindings are jq: slices, filters, everything.
  </Step>

  <Step title="CEL indexes into the binding">
    The second fetch binds `map_top: ${{ tasks.map.top[0] }}` in
    `with:`: index access is part of the CEL subset, and the binding IS
    the edge — every reference is a visible edge, declared where the
    data crosses.
  </Step>

  <Step title="The brief is a contract">
    title · angle · outline · keywords: your writer (or your next
    workflow) consumes fields, not a wall of prose.
  </Step>
</Steps>

## Constructs you just used

| Construct                         | Where              | Reference                        |
| --------------------------------- | ------------------ | -------------------------------- |
| `mode: sitemap` → `mode: article` | `map` · `top_page` | [Builtins](/reference/builtins)  |
| `output:` jq slice                | `map.output.top`   | [Bindings](/concepts/bindings)   |
| CEL index access                  | `top_page.with`    | [Workflows](/concepts/workflows) |
| `create_dirs: true`               | `save.args`        | [Builtins](/reference/builtins)  |

## Make it yours

* Brief the top THREE pages instead of one: bind `top: ${{ tasks.map.top }}` in `with:` and fan out with `for_each: ${{ with.top }}`. The fan-out tier shows how ([Competitor radar](/examples/competitor-radar)).
* Feed your own sitemap too and ask the model for internal-linking opportunities.
* Pipe the brief straight into a draft: a second `infer` consuming `${{ tasks.brief.output.outline }}`.

<Card title="Next · Invoice chaser" icon="file-invoice-dollar" href="/examples/invoice-chaser">
  CSV → JSON with `nika:convert`, a jq filter, and the three-line
  human-approval gate.
</Card>


# Social repurpose
Source: https://docs.nika.sh/examples/social-repurpose

T1 starter · marketing: one post becomes a thread, a LinkedIn post and a newsletter blurb, in parallel.

> **T1 starter · marketing / creators**: the diamond DAG. One read fans
> into three rewrites that run **concurrently**, and a single write
> merges the bundle. The craft lives in the prompts; the engine handles
> the choreography.

## The job

You wrote the post. Now it needs to be a thread, a LinkedIn version and
a newsletter blurb: same ideas, three voices. Sequential chatbot
sessions drift; this file keeps one source and rewrites it three ways at
once.

## The shape

```mermaid theme={"system"}
flowchart LR
  post["post · nika:read"]:::invoke
  thread["thread"]:::infer
  linkedin["linkedin"]:::infer
  newsletter["newsletter"]:::infer
  bundle["bundle · nika:write"]:::invoke
  post --> thread
  post --> linkedin
  post --> newsletter
  thread --> bundle
  linkedin --> bundle
  newsletter --> bundle
  classDef infer fill:#5b8cff22,stroke:#5b8cff,color:#5b8cff
  classDef invoke fill:#22d3ee22,stroke:#22d3ee,color:#22d3ee
```

## The file

```yaml social-repurpose.nika.yaml theme={"system"}
nika: v1
workflow:
  id: social-repurpose
  description: "One post → thread + LinkedIn + newsletter, in parallel"

model: ollama/qwen3.5:4b   # local · zero key · swap for mistral/mistral-large or any provider

const:
  # The sample post ships with the repo. Point this at your own and move the
  # read permit with it — `permits:` cannot interpolate (NIKA-AUTH-007).
  post_path: "examples/fixtures/launch-post.md"
permits:
  tools: ["nika:read", "nika:write"]
  # One file in, one file out · each named exactly, no subtree granted.
  fs:
    read: ["examples/fixtures/launch-post.md"]
    write: ["out/social-bundle.md"]

tasks:
  post:
    invoke:
      tool: "nika:read"
      args: { path: "${{ const.post_path }}" }

  # Three rewrites · no deps between them · they run concurrently.
  thread:
    with:
      post: ${{ tasks.post.output }}
    infer:
      max_tokens: 700
      prompt: "Turn this post into a 6-tweet thread · keep the voice · ${{ with.post }}"

  linkedin:
    with:
      post: ${{ tasks.post.output }}
    infer:
      max_tokens: 500
      prompt: "Rewrite this post for LinkedIn · hook first · ${{ with.post }}"

  newsletter:
    with:
      post: ${{ tasks.post.output }}
    infer:
      max_tokens: 200
      prompt: "Write a 3-sentence newsletter blurb for this post · ${{ with.post }}"

  bundle:
    with:
      t: ${{ tasks.thread.output }}
      l: ${{ tasks.linkedin.output }}
      n: ${{ tasks.newsletter.output }}
    invoke:
      tool: "nika:write"
      args:
        path: out/social-bundle.md
        create_dirs: true
        # Prose artifact → a `content: |` block with interpolations is right
        # here. A `.json` artifact is the opposite case: one `${{ … }}` value,
        # never hand-typed braces (that emits unquoted fields).
        content: |
          # Social bundle

          ## Thread
          ${{ with.t }}

          ## LinkedIn
          ${{ with.l }}

          ## Newsletter
          ${{ with.n }}

outputs:
  bundle_path: ${{ tasks.bundle.output }}
```

## How it works

<Steps>
  <Step title="Fan-out by omission">
    `thread`, `linkedin` and `newsletter` each depend only on `post`:
    no deps between them, so the engine runs all three at the same time.
  </Step>

  <Step title="with: keeps the merge readable">
    `bundle` aliases the three outputs to one-letter names. `with:` is
    optional sugar, but a template interpolating three long task paths
    is where you want it.
  </Step>

  <Step title="One multi-line write">
    The `content:` is a YAML block scalar with three interpolations:
    the bundle file is assembled by the engine, no model needed for glue.
  </Step>
</Steps>

## Constructs you just used

| Construct                | Where         | Reference                             |
| ------------------------ | ------------- | ------------------------------------- |
| diamond fan-out / fan-in | the whole DAG | [Workflows](/concepts/workflows)      |
| `with:` aliasing         | `bundle`      | [Bindings](/concepts/bindings)        |
| block-scalar `content:`  | `bundle.args` | [YAML syntax](/reference/yaml-syntax) |

## Make it yours

* Add a fourth branch (YouTube description, Mastodon, press blurb): it's three lines and it runs in the same wave.
* Pin a glossary: put your brand terms in a `const:` entry and interpolate it into each prompt.
* Want every language too? Chain this into [Localization factory](/examples/localization-factory).

<Card title="Level up · T2 chains" icon="rocket" href="/examples/release-notes">
  Next tier: typed outputs, in-place file edits and a webhook ping.
  Release day, automated.
</Card>


# Standup digest
Source: https://docs.nika.sh/examples/standup-digest

T1 starter · engineering: the standup note writes itself from what you actually committed.

> **T1 starter · engineering / any team**: two data sources gathered in
> parallel, one model call, one file on disk. Your first taste of « the
> boring parts run themselves ».

## The job

Every morning you reconstruct yesterday from memory. Your git history
already knows. This workflow reads the commits since yesterday, stamps
the date from a builtin (not from the model's imagination), and writes
the three standup bullets in your tone.

## The shape

```mermaid theme={"system"}
flowchart LR
  today["today · nika:date"]:::invoke
  history["history · git"]:::exec
  digest["digest"]:::infer
  save["save · nika:write"]:::invoke
  today --> digest
  history --> digest
  digest --> save
  classDef infer fill:#5b8cff22,stroke:#5b8cff,color:#5b8cff
  classDef exec fill:#ff7a3c22,stroke:#ff7a3c,color:#ff7a3c
  classDef invoke fill:#22d3ee22,stroke:#22d3ee,color:#22d3ee
```

## The file

```yaml standup-digest.nika.yaml theme={"system"}
nika: v1
workflow:
  id: standup-digest
  description: "Read yesterday's commits, write today's standup note"

model: ollama/qwen3.5:4b   # local · zero key · swap for groq/llama-3.3-70b (a fast one-liner job)

permits:
  tools: ["nika:date", "nika:write"]
  exec: ["git"]              # the ONE program this workflow may run
  fs: { write: ["out/standup-note.md"] }

tasks:
  # No deps between these two → the engine runs them in parallel.
  today:
    invoke:
      tool: "nika:date"
      args: { op: now }

  history:
    exec:
      command: ["git", "log", "--since=yesterday", "--oneline", "--no-merges"]

  digest:
    with:
      today: ${{ tasks.today.output }}
      history: ${{ tasks.history.output }}
    infer:
      max_tokens: 400          # a standup note is short · the ceiling says so
      prompt: |
        Date · ${{ with.today }}
        Commits since yesterday ·
        ${{ with.history }}

        Write my standup note · 3 bullets · done / doing / blocked.
        Plain words · no fluff. If there are no commits, say so in one line.

  save:
    with:
      digest: ${{ tasks.digest.output }}
    invoke:
      tool: "nika:write"
      args:
        path: out/standup-note.md
        create_dirs: true
        content: "${{ with.digest }}"

outputs:
  note: ${{ tasks.digest.output }}
```

## How it works

<Steps>
  <Step title="Two tasks start together">
    `today` and `history` have no incoming edge: the engine runs them
    in parallel. Parallelism is the default, not an option you switch on.
  </Step>

  <Step title="The digest waits for both">
    The two `with:` bindings make `digest` the merge point — each
    `${{ tasks.X.output }}` reference IS a data edge. The prompt reads
    the bindings (`${{ with.today }}` · `${{ with.history }}`).
  </Step>

  <Step title="The note lands on disk">
    `nika:write` takes an explicit `content:`. A write without content
    writes nothing. The workflow also returns the note via `outputs:`.
  </Step>
</Steps>

## Constructs you just used

| Construct                  | Where               | Reference                             |
| -------------------------- | ------------------- | ------------------------------------- |
| implicit parallelism       | `today` + `history` | [DAG shape](/concepts/workflows)      |
| `exec:`                    | `history`           | [The 4 verbs](/concepts/verbs)        |
| `nika:date` · `nika:write` | `today` · `save`    | [Builtins](/reference/builtins)       |
| `outputs:`                 | envelope tail       | [YAML syntax](/reference/yaml-syntax) |

## Make it yours

* Point `--since` at your sprint cadence (`--since=friday` for Monday standups).
* Swap `ollama/llama3.2:3b` for `anthropic/claude-haiku-4-5`: a one-liner job wants a fast model.
* Add a `nika:notify` task to post the note straight into your team channel. See [Release notes](/examples/release-notes) for the pattern.

<Card title="Next · Meeting actions" icon="list-check" href="/examples/meeting-actions">
  Same tier, one new idea: structured output. The model returns typed
  JSON, not prose.
</Card>


# Support triage
Source: https://docs.nika.sh/examples/support-triage

T2 chain · support: the overnight queue classified, first replies drafted, urgent ones escalated.

> **T2 chain · customer support**: one schema-typed call classifies the
> WHOLE queue (enums keep the categories honest), jq slices the urgent
> ones, and the escalation fires only when there's something to escalate.

## The job

It's 8:55. There are 40 tickets from overnight. Someone reads them all,
tags them, writes first replies, and pages on-call if anything's on
fire. This file does the reading, tagging and drafting (under a
sortable v7 batch id) and pages only when `urgent` is non-empty.

## The shape

```mermaid theme={"system"}
flowchart LR
  batch["batch · nika:uuid"]:::invoke
  queue["queue · nika:read"]:::invoke
  triage["triage · typed"]:::infer
  urgent["urgent · nika:jq"]:::invoke
  escalate["escalate · nika:notify"]:::invoke
  board["board · nika:write"]:::invoke
  queue --> triage
  triage --> urgent
  urgent --> escalate
  batch --> escalate
  triage --> board
  batch --> board
  classDef infer fill:#5b8cff22,stroke:#5b8cff,color:#5b8cff
  classDef invoke fill:#22d3ee22,stroke:#22d3ee,color:#22d3ee
```

## The file

```yaml support-triage.nika.yaml theme={"system"}
nika: v1
workflow:
  id: support-triage
  description: "Ticket queue → typed triage → urgent escalation → triage board"

# A NON-thinking local model, deliberately: a thinking model can spend the
# whole `max_tokens` budget in its think block and return before the JSON
# (engine#428). Schema showcases pick a model that answers directly.
model: ollama/llama3.2:3b   # local · zero key · swap for groq/llama-3.3-70b (triage wants speed)

const:
  queue_path: "examples/fixtures/support-queue.json"

secrets:
  oncall_webhook:
    source: env
    key: ONCALL_WEBHOOK_URL
    egress:                       # sanction the one send · the secret IS the URL
      - to: "nika:notify"
        host_from_self: true
permits:
  tools: ["nika:jq", "nika:notify", "nika:read", "nika:uuid", "nika:write"]
  fs:
    read: ["examples/fixtures/support-queue.json"]
    # One board per batch id. `*` matches a single segment and never crosses
    # `/`, so the uuid can never steer the write out of out/ — `out/**` would
    # let it.
    write: ["out/triage-*.json"]
  net:
    # `host_from_self:` above sanctions the FLOW (the secret may be the URL) —
    # it does not grant the capability. The host stays unknown at check, so it
    # is judged at RUN against this bound: name the escalation host here or the
    # send is refused mid-run, after the tokens are already spent.
    http: ["hooks.slack.com"]

tasks:
  batch:
    invoke:
      tool: "nika:uuid"
      args: { version: v7 }

  queue:
    invoke:
      tool: "nika:read"
      args: { path: "${{ const.queue_path }}" }

  triage:
    with:
      queue: ${{ tasks.queue.output }}
    infer:
      max_tokens: 1500                 # the whole queue in one call · a ceiling, not UNBOUNDED
      prompt: |
        Triage every ticket in this queue ·
        ${{ with.queue }}
        For each · classify category and urgency, draft a 2-sentence first reply.
      schema:
        type: object
        additionalProperties: false    # a deterministic shape across providers
        required: [tickets]
        properties:
          tickets:
            type: array
            items:
              type: object
              additionalProperties: false
              required: [id, category, urgency, first_reply]
              properties:
                id: { type: string }
                category: { type: string, enum: [billing, bug, how-to, account, other] }
                urgency: { type: string, enum: [low, normal, high, critical] }
                first_reply: { type: string }

  urgent:
    with:
      tickets: ${{ tasks.triage.output.tickets }}
    invoke:
      tool: "nika:jq"
      args:
        input: "${{ with.tickets }}"
        expression: 'map(select(.urgency == "high" or .urgency == "critical"))'

  escalate:
    with:
      urgent: ${{ tasks.urgent.output }}
      batch: ${{ tasks.batch.output }}
    when: ${{ size(with.urgent) > 0 }}
    invoke:
      tool: "nika:notify"
      args:
        channel: webhook
        target: "${{ secrets.oncall_webhook }}"
        message: "Urgent tickets in triage batch ${{ with.batch }} · ${{ with.urgent }}"
        severity: warning

  board:
    with:
      tickets: ${{ tasks.triage.output.tickets }}
      batch: ${{ tasks.batch.output }}
    invoke:
      tool: "nika:write"
      args:
        # A `.json` artifact takes ONE interpolated value as `content:` and
        # lets the engine serialize it. Typing `{ "tickets": ${{ … }} }` by
        # hand emits unquoted fields and the board stops being JSON.
        path: "out/triage-${{ with.batch }}.json"
        content: "${{ with.tickets }}"
        create_dirs: true

outputs:
  tickets:
    value: ${{ tasks.triage.output.tickets }}
    description: "The classified queue with drafted first replies"
```

## How it works

<Steps>
  <Step title="Enums make classification honest">
    `category` and `urgency` are schema enums: the model cannot invent
    a « kinda-urgent » tier. Typed output means the jq filter downstream
    can trust the values.
  </Step>

  <Step title="jq slices, the model doesn't re-read">
    `urgent` filters `urgency == "high" or "critical"` out of the typed
    list: no second model call to ask « which ones were urgent? ».
  </Step>

  <Step title="v7 uuids sort by time">
    `nika:uuid version: v7` is timestamped: triage boards land on disk
    already in chronological order.
  </Step>
</Steps>

## Constructs you just used

| Construct                | Where      | Reference                        |
| ------------------------ | ---------- | -------------------------------- |
| schema enums over a list | `triage`   | [The 4 verbs](/concepts/verbs)   |
| `nika:jq` post-filter    | `urgent`   | [Builtins](/reference/builtins)  |
| `nika:uuid` v7           | `batch`    | [Builtins](/reference/builtins)  |
| conditional `notify`     | `escalate` | [Workflows](/concepts/workflows) |

## Make it yours

* Push the first replies as DRAFTS into your helpdesk via its API (`nika:fetch method: POST`): humans still hit send.
* Track sentiment over time: append each batch's stats to a CSV with `nika:write`.
* Speed matters at 9am: `groq/llama-3.3-70b` triages a 40-ticket queue in seconds.

<Card title="Next · Contract guard" icon="scale-balanced" href="/examples/contract-guard">
  The sovereignty example: a LOCAL model reads the contract, and a
  validate + assert pair refuses bad extractions.
</Card>


# Transcript show-notes
Source: https://docs.nika.sh/examples/transcript-shownotes

T2 chain · podcasts / meetings: raw transcript → typed show-notes (chapters, quotes, summary) in ONE bounded infer.

> **T2 chain · podcasts / meetings**: `nika:read` loads the raw
> transcript, ONE `infer:` with a strict `schema:` extracts chapters +
> pull-quotes + summary as typed data, `nika:jq` shapes the sections,
> and `nika:write` renders the publishable page. The model is called
> exactly once, and its output is schema-validated before anything
> downstream touches it.

## The job

Show-notes are the chore between "episode recorded" and "episode
published": an hour of scrubbing for chapter marks and quotes. This
workflow does the extraction in one bounded model call — bounded in
*shape* (the schema rejects free-form prose) and in *count* (one
infer, so the cost of an episode is the cost of one call, visible in
`nika check` before you run).

## The shape

```mermaid theme={"system"}
flowchart LR
  raw["raw · nika:read"]:::invoke
  notes["notes · typed"]:::infer
  sections["sections · nika:jq"]:::invoke
  page["page · nika:write"]:::invoke
  raw --> notes
  notes --> sections
  notes --> page
  sections --> page
  classDef infer fill:#5b8cff22,stroke:#5b8cff,color:#5b8cff
  classDef invoke fill:#22d3ee22,stroke:#22d3ee,color:#22d3ee
```

## The file

```yaml transcript-shownotes.nika.yaml theme={"system"}
nika: v1
workflow:
  id: transcript-shownotes
  description: "Raw transcript → typed show-notes (chapters · quotes · summary) · one bounded infer"

model: ollama/llama3.2:3b # local · zero key · deliberately NOT the qwen3.5 convention: a thinking model can burn max_tokens in its think block before the JSON (engine#428) — schema showcases pick a non-thinking model

const:
  transcript: "examples/fixtures/episode-transcript.txt"

permits:
  exec: false
  tools: ["nika:jq", "nika:read", "nika:write"]
  fs:
    # One file in, one page out — each named exactly. `data/**` would have
    # handed a whole tree to a workflow that reads a single transcript.
    read: ["examples/fixtures/episode-transcript.txt"]
    write: ["out/show-notes.md"]

tasks:
  raw:
    invoke:
      tool: "nika:read"
      args: { path: "${{ const.transcript }}" }

  # ONE bounded model call · the schema is the contract, not a suggestion.
  notes:
    with:
      raw: ${{ tasks.raw.output }}
    infer:
      prompt: |
        Turn this transcript into show-notes. Ground every chapter title
        and quote in the text — invent nothing.

        Transcript ·
        ${{ with.raw }}
      max_tokens: 800
      schema:
        type: object
        additionalProperties: false # a deterministic shape across providers (the checker's strictness hint)
        required: [summary, chapters, quotes]
        properties:
          summary: { type: string }
          chapters:
            type: array
            items:
              type: object
              additionalProperties: false
              required: [title, gist]
              properties:
                title: { type: string }
                gist: { type: string }
          quotes:
            type: array
            items: { type: string }

  # Typed JSON → markdown lines · mechanical, zero second model call.
  sections:
    with:
      notes: ${{ tasks.notes.output }}
    invoke:
      tool: "nika:jq"
      args:
        input: "${{ with.notes }}"
        expression: >-
          {
            chapters: (.chapters | map("- **\(.title)** — \(.gist)") | join("\n")),
            quotes: (.quotes | map("> \(.)") | join("\n\n"))
          }

  page:
    with:
      notes_summary: ${{ tasks.notes.output.summary }}
      sections_chapters: ${{ tasks.sections.output.chapters }}
      sections_quotes: ${{ tasks.sections.output.quotes }}
    invoke:
      tool: "nika:write"
      args:
        path: out/show-notes.md
        content: |
          # Show notes

          ${{ with.notes_summary }}

          ## Chapters

          ${{ with.sections_chapters }}

          ## Pull quotes

          ${{ with.sections_quotes }}

          *Generated by [nika](https://nika.sh) · one bounded infer, typed output · the run's trace is the receipt.*

outputs:
  notes:
    value: ${{ tasks.notes.output }}
    description: "The typed show-notes · summary + chapters + quotes"
```

## The model choice is part of the lesson

The envelope pins `ollama/llama3.2:3b` — deliberately NOT the
showcase's usual `qwen3.5` — because this is a strict-schema job and a
*thinking* model can burn the whole `max_tokens` budget inside its
think block before emitting the first JSON token (engine issue #428:
the output arrives empty yet the schema demanded content). The rule of
thumb this file encodes: **reasoning showcases pick a thinking model;
strict-schema extraction picks a non-thinking one.**

The typed seam is the other half: because `notes` is schema-shaped,
the jq step reads `.chapters[]` and `.quotes[]` as data — no regex
over model prose, no "hopefully it used the same markdown headings
this time".

## Run it

```bash theme={"system"}
ollama pull llama3.2:3b
git clone https://github.com/supernovae-st/nika-spec && cd nika-spec
nika run examples/showcase/t2-transcript-shownotes.nika.yaml
open out/show-notes.md
```

<Note>
  This workflow is newer than the currently shipped engine pack:
  `nika examples run showcase/t2-transcript-shownotes` says
  `unknown example` until the next engine tag re-vendors the pack.
  Until then, run it from the spec checkout as above — the file is the
  same one the pack will embed, sha-pinned in the spec manifest.
</Note>

Feed it any meeting transcript instead: the schema does not care
whether the speakers were recording a podcast or arguing about a
roadmap.


# Agents
Source: https://docs.nika.sh/getting-started/agents

Claude Code, Cursor, Codex, Windsurf: your agent does the work once, Nika keeps the workflow. Two commands wire any of them.

Your agent already does the work: a PR review in Claude Code, a research
brief in Codex, a triage pass in Cursor. Then the chat scrolls away and the
procedure is gone. Nika's job is to keep it: the agent writes the workflow
**as a `.nika.yaml` file**, you review it, the runtime enforces it, and it
runs again next week without re-prompting.

Two commands wire any agent:

```sh theme={"system"}
nika init            # AGENTS.md + schema wiring + Cursor rule + agent skill
nika wire <client>   # adds Nika's read-only MCP oracle to your agent client
```

## `nika init`: teach the repo

`nika init` scaffolds the repo (idempotent: existing files are skipped,
`--force` overwrites):

* **`AGENTS.md`**, the agent operating guide: the four verbs, the authoring
  loop (`nika new --from <template>` → fill → `nika check` → repair from the
  error), and the rules that keep generated workflows valid. Read natively by
  **Codex**, **Claude Code**, **Cursor**, **Jules** and every AGENTS.md-aware
  tool.
* **`.vscode/settings.json`**: maps `*.nika.yaml` to the canonical JSON
  schema, so completions and validation work in any YAML-aware editor.
* **`.cursor/rules/nika.mdc`**, the Cursor rules file (globs `*.nika.yaml`):
  the syntax floor + the check loop, auto-attached whenever the agent touches
  a workflow file.
* **Cursor, fully equipped** (next release): the three kit subagents
  (`.cursor/agents/nika-{author,debugger,migrator}.md`), the delegation rule
  (`.cursor/rules/nika-delegation.mdc`) and the three seatbelt hooks
  (`.cursor/hooks.json` + `.cursor/hooks-nika/` — session context ·
  check-on-edit · a guard that audits before any `nika run`). Cursor's local
  plugin loader consumes MCP + skills only, so the binary carries the rest
  project-side; every body is byte-identical to the kit.
* **`.agents/skills/nika-authoring/SKILL.md`** (0.93+): a
  repo-level [agent skill](https://agentskills.io) — Codex and every
  `.agents`-aware client discover it automatically and can invoke it as
  `$nika-authoring`. Same author → check → repair loop, packaged as a skill.

## Or: install the plugin (Codex · Claude Code)

Codex and Claude Code users can skip per-repo setup entirely — the engine
repo hosts one plugin for both ecosystems: 4 skills, 3 subagents, 5 slash
commands, the three seatbelt hooks (one dialect, sniffed — Codex speaks
Claude Code's hook contract verbatim) **and** the MCP oracle:

```sh theme={"system"}
# Codex
codex plugin marketplace add supernovae-st/nika-agents
codex plugin add nika@nika

# Claude Code
claude plugin marketplace add supernovae-st/nika-agents
claude plugin install nika@nika
```

One install: the `nika-authoring` skill lands (invoke it explicitly, or
let it auto-trigger on `.nika.yaml` work), and the read-only oracle is
wired (9 tools: `nika_check` + `nika_explain` + the authoring surface).
The plugin expects the `nika` binary on your PATH (`brew install supernovae-st/tap/nika`).

## `nika wire`: give the agent the real oracle

`nika wire` patches your client's MCP config to add Nika's **read-only**
oracle: the agent can *check* and *explain*, never execute (`nika run`
stays in your hands):

| Client      | Command              | What it patches                               |
| ----------- | -------------------- | --------------------------------------------- |
| Claude Code | `nika wire claude`   | `~/.claude.json` → `mcpServers.nika`          |
| Cursor      | `nika wire cursor`   | `~/.cursor/mcp.json`                          |
| Windsurf    | `nika wire windsurf` | `~/.codeium/windsurf/mcp_config.json`         |
| VS Code     | `nika wire vscode`   | `.vscode/mcp.json` (project-local)            |
| Codex CLI   | `nika wire codex`    | `~/.codex/config.toml` → `[mcp_servers.nika]` |
| Everything  | `nika wire all`      | all of the above                              |

Whatever the harness, the payloads an agent parses are the same
versioned wires — envelopes, exit codes, and evolution rules are
documented in [Machine surfaces](/reference/machine-surfaces).

Any other MCP client takes the same stanza — a stdio server,
`command: nika`, `args: ["mcp"]`. Verified shapes:

* **Gemini CLI** (has its own installer): `gemini mcp add nika nika mcp`
  (writes the project's `.gemini/settings.json`).
* **Zed**: `settings.json` → `"context_servers": { "nika": { "command":
  "nika", "args": ["mcp"] } }`.
* **opencode · Cline · Continue…**: same two fields in each client's MCP
  config. The oracle is client-agnostic.

The server exposes two tool families — **validate** and **learn**:

* **`nika_check`**: the full static audit (plan · cost ceiling · secret
  flows · types · tool args · schema) as structured JSON. The agent fixes
  its own file before you ever see it.
* **`nika_explain`**: any `NIKA-XXX` error code, explained.
* **`nika_schema` · `nika_examples` · `nika_template` · `nika_canon` ·
  `nika_catalog` · `nika_tools`**: the authoring surface — the JSON
  Schema, the runnable examples, the skeletons, the canon SSOT, and the
  provider + builtin catalogs as versioned machine projections, so the
  agent follows the template→fill→check→repair path instead of guessing
  structure. All read-only, all served from the embedded pack.

<Note>
  The `codex` target is shipped (0.93+): `nika wire codex` patches
  `~/.codex/config.toml` (`[mcp_servers.nika]` · `command = "nika"` ·
  `args = ["mcp"]`, comments preserved) — Codex also reads `AGENTS.md`
  natively, so `nika init` alone already teaches it the authoring loop.
</Note>

## The loop

```text theme={"system"}
agent writes review.nika.yaml        (from AGENTS.md + a template)
  → nika check review.nika.yaml      (agent self-repairs from the findings)
  → you read the file                (it's YAML, review it like code)
  → nika run review.nika.yaml        (you, or your CI, not the agent)
```

The division of labor is the point: the **agent authors**, the **file is
the contract**, the **human approves**, the **runtime enforces**.

## Editor surface

The [VS Code / Cursor / Windsurf extension](https://marketplace.visualstudio.com/items?itemName=supernovae.nika-lang)
adds check-as-you-type, cost inlay hints, DAG visualization and trace replay
on top. See [Editors](/getting-started/editors).

## Read next

<CardGroup>
  <Card title="Agent authoring protocol" icon="robot" href="/guides/agent-authoring">
    The deterministic path: template → fill → check → repair.
  </Card>

  <Card title="Templates" icon="clone" href="/guides/templates">
    The valid skeletons `nika new --from` instantiates.
  </Card>
</CardGroup>


# Editor setup
Source: https://docs.nika.sh/getting-started/editors

Schema validation, nika-lsp, the VS Code/Cursor extension, and MCP agent wiring.

Nika's editor story has two tiers: **(1)** generic JSON-Schema validation
that works with any yaml-language-server-compatible editor, and **(2)** the
`nika lsp` server plus the VS Code/Cursor extension for deeper workflow
intelligence.

<Info>
  **v state:** the binary ships `nika spec --schema`, `nika lsp`,
  `nika mcp`, and `nika wire`. Use `nika init` for repo-local schema/rules,
  or `nika wire <client>` for explicit MCP client setup.
</Info>

## Tier 1: JSON schema validation (today)

Any editor with `yaml-language-server` can validate `.nika.yaml` against
the workflow schema.

<Tabs>
  <Tab title="VS Code">
    Install the [YAML extension (Red Hat)](https://marketplace.visualstudio.com/items?itemName=redhat.vscode-yaml).
    It picks up the schema via the `# yaml-language-server` directive at
    the top of `.nika.yaml`, or via `settings.json`:

    ```json settings.json theme={"system"}
    {
      "yaml.schemas": {
        "https://nika.sh/spec/v1/workflow.schema.json": "*.nika.yaml"
      }
    }
    ```

    Or let `nika init` write this wiring for the current repo.
  </Tab>

  <Tab title="Neovim">
    Wire via `nvim-lspconfig`:

    ```lua theme={"system"}
    require('lspconfig').yamlls.setup {
      settings = {
        yaml = {
          schemas = {
            ["https://nika.sh/spec/v1/workflow.schema.json"] = "*.nika.yaml",
          },
        },
      },
    }
    ```
  </Tab>

  <Tab title="Helix">
    Add to `~/.config/helix/languages.toml`:

    ```toml theme={"system"}
    [[language]]
    name = "yaml"
    file-types = [{ glob = "*.nika.yaml" }]
    language-servers = ["yaml-language-server"]
    ```
  </Tab>

  <Tab title="Zed / Cursor / JetBrains">
    Any editor supporting `yaml-language-server` will validate
    `.nika.yaml` against `https://nika.sh/spec/v1/workflow.schema.json`
    once it publishes. Zed has native LSP; JetBrains supports via the
    YAML plugin.
  </Tab>
</Tabs>

## In-file schema hint

Add one comment at the top of any `.nika.yaml` so the schema works with
zero editor configuration:

```yaml theme={"system"}
# yaml-language-server: $schema=https://nika.sh/spec/v1/workflow.schema.json
nika: v1
workflow:
  id: hello

tasks:
  greet:
    infer:
      model: ollama/llama3.2:3b            # <provider>/<name> · local · zero key
      prompt: "..."
```

## What tier 1 gets you

<CardGroup>
  <Card title="Field autocomplete" icon="wand-magic-sparkles">
    Verb keys, provider names, model identifiers, capability parameters.
  </Card>

  <Card title="Inline errors" icon="triangle-exclamation">
    Missing required fields, schema mismatches, wrong types.
  </Card>

  <Card title="Hover docs" icon="circle-info">
    Every field documented inline: descriptions come from the JSON Schema.
  </Card>

  <Card title="Format on save" icon="align-left">
    Via `prettier-plugin-yaml` or LSP-driven formatting.
  </Card>
</CardGroup>

## Tier 2: the extension (VS Code · Cursor · Windsurf · VSCodium)

One extension, both registries — the
[VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=supernovae.nika-lang)
and [OpenVSX](https://open-vsx.org/extension/supernovae/nika-lang), so
Cursor, Windsurf and VSCodium install it natively. It consumes the same
binary the CLI runs: every verdict in the margin is real `nika check`
output, never a client-side guess. Workflow files carry the language
identity out of the box — the four verbs color distinctly in every
theme (`Nika: Apply Verb Colors` writes the exact canonical hues), a
🦋 badge marks workflows in the Explorer without replacing your icon
theme, and verbs, tools and `permits:` are ctrl-clickable to their
reference pages.

<AccordionGroup>
  <Accordion title="Install = everything on" icon="rocket">
    First activation with the engine present silently wires MCP for the
    host (`nika wire`, idempotent) — install the extension, accept the
    one-click verified download (SHA256SUMS, mandatory), and MCP · LSP ·
    diagnostics are live in the same window. The 🦋 status menu then
    opens on *your* next step, whichever it is: no binary → **Finish
    Setup** (one orchestrated gesture: download → wire → optional
    `nika init`, repo writes stay consented → recap) · repo not
    equipped → **Init this project** (agent rules · MCP · schema
    wiring, skip-if-exists) · fresh workspace → **Run the 10-second
    proof** (the offline hello, zero keys) · already working → the
    active file's Run · Check · Graph. The sidebar's welcome view says
    the same thing — one journey, every surface. `nika.autoSetup:
            false` opts out of all of it.
  </Accordion>

  <Accordion title="Check-as-you-type — the full audit" icon="shield">
    `nika check --json` painted as diagnostics while you type: DAG
    conformance, secret leaks and egresses, permits escapes, schema
    findings, unknown tools, typo'd or missing tool args (with the
    engine's did-you-mean), provably dead `when:` gates, hints. The
    finding families mirror the engine's `is_clean` list, so the
    editor's verdict IS the binary's exit code. Dirty buffers pipe over
    stdin (`nika check -`) — keystroke-fresh audits, nothing written to
    disk. Machine-applicable fixes (the `add "X" to permits.<path>`
    grammar) apply as quick fixes.
  </Accordion>

  <Accordion title="Lens doors — the file completes itself" icon="wand-magic-sparkles">
    Every structural line grows its own door (0.100+): the envelope
    reads top-to-bottom — a GitHub lens above `nika:`, Check · DAG ·
    Run above `workflow:`, Explain above `description:`, and the audit
    verdict with its cost ceiling above `tasks:`. `model:` lines open
    the provider picker (local-first, fed by the binary's own catalog).
    And each of the four verb keys offers proven starters: `invoke:`
    lists every builtin *this* binary carries with an args skeleton
    derived from the tool's own schema (required args as `# SLOT`
    lines), while `infer:` / `exec:` / `agent:` insert the spec's
    canonical shapes — each starter validated against the conformance
    oracle before it ships (the spec's `verb-starters` source of
    truth). Picking replaces the block surgically: one edit, one undo,
    and a moved line refuses a blind write.
  </Accordion>

  <Accordion title="The DAG canvas — content-first" icon="diagram-project">
    The file as a graph: infer cards show their prompt, exec cards their
    `$ command`, invoke cards their tool + args — before any run. Model
    chips edit through a provider picker fed by the binary's own catalog
    (`nika catalog --json` — exact models, capabilities), drag an
    out-port to wire an edge (a `with:` binding or an `after:` entry),
    cost badges and `⚠` audit chips
    ride the cards, and semantic zoom keeps 100-task graphs readable.
  </Accordion>

  <Accordion title="Run · resume · replay" icon="play">
    A ▶ Run / ▶ mock / ■ Stop pill drives the run without leaving the
    panel — ▶ mock streams `run --model mock/echo` (deterministic, zero
    keys, zero network). On a 0.93+ engine, ↻ re-runs only what changed
    (engine `--resume`: unchanged tasks cache-hit visibly). Every
    recorded run in `.nika/traces/` replays as a scrubbable timeline —
    replay re-renders, never re-executes. And **paused runs ask**: a
    `nika:prompt` task pauses the run (ADR-099 · exit 4, a pause is not
    a failure) — the verdict goes amber ⏸ with the question itself, the
    answer control matches the mode (confirm · choice · input), and the
    resume rides the exact journal the engine wrote.
  </Accordion>

  <Accordion title="Debug (F5) — time-travel a recorded run" icon="bug">
    Press **F5** on a workflow to launch the Nika debug adapter (the
    engine's `nika dap`, a Debug Adapter Protocol server over stdio, so
    the debugger is the same one any DAP editor speaks). It debugs a
    **recorded** run, not a live one: set breakpoints on tasks, then step
    forward *and backward* through the journal the engine wrote —
    inspect each task's output, cost and ADR-099 identity hashes at that
    point in time. Like replay, it re-executes nothing; it time-travels
    what already happened, so a breakpoint costs no tokens and hits no
    network.
  </Accordion>

  <Accordion title="Prove it ran — chain · verify · reproduce" icon="shield-check">
    Every run hash-chains its journal (engine 0.97+), and the editor
    carries the proof end to end: the run's verdict banner, the
    Runs-view tooltip and the run report all show the **same chain
    head** the engine printed. A journal that fails the walk gets a
    shield — its claims are unverified. **Verify Journal** (right-click
    a run) asks the engine itself (`nika trace verify`): intact with
    its head, BROKEN at its exact line, or unchained for pre-0.96
    journals (nothing to verify, nothing to distrust). **Reproduce
    Run** compares two recorded runs and classifies every task —
    `reproduced` · `NONDETERMINISTIC` (the flaky task, named) ·
    `authored` · `environment` — by reading two files: no re-run, no
    spend.
  </Accordion>

  <Accordion title="Preflight · lineage · the run understood" icon="magnifying-glass-chart">
    `Nika: Preflight` renders the flight plan before any token: cost
    (ceiling · an uncapped task stays a loud floor), every model
    resolved against the catalog's key requirements (local providers
    marked sovereign), secrets/env checked against the actual
    environment, permits + capability escapes, and the wave-by-wave
    plan — missing requirements headline as blockers. On the canvas,
    **lineage mode** follows the data: click a card (or put the caret
    in `${{ tasks.x… }}`) and the producer + every consumer stay lit
    while the rest fades. After a run, task rows grow **artifact
    children** (images · audio · manifests) with provenance, run diffs
    lead with the first divergence, and the replay says when the
    workflow's definition changed under a recorded journal.
  </Accordion>

  <Accordion title="Golden testing, one command" icon="flask">
    `Nika: Golden Test` runs `nika test <file>` (mock provider ·
    offline · deterministic) against `<file>.golden.json`, and
    `Update the Golden` re-pins it — the offline CI gate without
    leaving the editor. The golden pins the workflow's OUTPUT
    contract: schema drift and output renames go red with a precise
    diff; prompt wording alone does not.
  </Accordion>

  <Accordion title="Schema-derived intelligence" icon="wand-magic-sparkles">
    Completions, hover and expression intel come FROM the binary
    (`nika spec --schema` · `nika spec --canon` · `nika catalog --tools --json`): task
    fields, per-verb bodies, the closed builtin set,
    provider-prefixed `model:` values, `${{ }}` reference completion
    with go-to-definition, task rename across all syntactic homes. A
    new field in the engine lights up with zero extension update.
  </Accordion>

  <Accordion title="Agent-native" icon="robot">
    `nika_check` / `nika_explain` / `nika_graph` registered as editor
    LM tools — in-editor agents validate through the real oracle. One
    command wires MCP config + agent rules (`nika wire` under the
    hood), and VS Code 1.101+ discovers `nika mcp` natively.
  </Accordion>

  <Accordion title="Capability-gated by construction" icon="grid">
    The extension probes what the binary ACTUALLY ships (`--help`,
    never a hardcoded matrix): a dev build from engine main lights
    features up early, an older brew binary keeps its fallbacks —
    same extension, zero release needed.
  </Accordion>
</AccordionGroup>

### `nika lsp` (any editor)

The engine's own language server rides stdio for editors outside the
VS Code family: hover, completion (`.` `/` `[` triggers), go to
definition, document symbols, push diagnostics — and **quickfix code
actions** (engines after 0.99.0): the `nika check --fix` rename engine
projected, so a typo'd tool, arg, field or task reference offers its
did-you-mean as a one-click repair in any LSP editor. Wire it as a
generic LSP command (`nika lsp`) in Zed, Neovim or Helix alongside the
Tier-1 schema.

## File and folder icons

`*.nika.yaml` files carry the butterfly mark out of the box wherever the
icon theme honors language icons (Seti — VS Code's default — does; the
extension contributes it). Folder icons are the icon theme's territory,
not an extension's, so `.nika/` — the flight-recorder home — needs one
line in your settings until the upstream icons land:

<Tabs>
  <Tab title="Material Icon Theme">
    Map `.nika/` to the existing `flow` folder icon today:

    ```json settings.json theme={"system"}
    {
      "material-icon-theme.folders.associations": { ".nika": "flow" }
    }
    ```

    Native butterfly icons (file + folder) are
    [in review upstream](https://github.com/material-extensions/vscode-material-icon-theme/pull/3529) —
    once merged, delete the association and both arrive with the theme.
  </Tab>

  <Tab title="vscode-icons">
    A ready-made custom set (file · folder · open folder) ships in the
    extension repo's
    [`contrib/`](https://github.com/supernovae-st/nika-vscode/tree/main/contrib)
    with the wiring steps (`vsicons.customIconFolderPath` + two
    association entries).
  </Tab>
</Tabs>

## Roadmap

| Capability                         | Status             | Admission                                                            |
| ---------------------------------- | ------------------ | -------------------------------------------------------------------- |
| JSON Schema (yaml-language-server) | shipped            | `nika spec --schema` + public schema URL                             |
| `nika lsp` L4 crate                | shipped            | `nika lsp` (hover · completion · definition · symbols · diagnostics) |
| VS Code / Cursor extension         | shipped            | Marketplace + OpenVSX                                                |
| MCP agent oracle                   | shipped, read-only | `nika mcp` (9 tools: check · explain · the authoring surface)        |
| Zed / Neovim native integrations   | 🧭 planned         | Community + v1.0                                                     |

## Next

<CardGroup>
  <Card title="Schema reference" icon="file-code" href="/reference/schema">
    `.nika.yaml` top-level keys + workflow envelope.
  </Card>

  <Card title="YAML syntax" icon="align-left" href="/reference/yaml-syntax">
    Full grammar for every verb step.
  </Card>

  <Card title="First workflow" icon="play" href="/getting-started/first-workflow">
    Preview of the target first-run experience.
  </Card>

  <Card title="Constellation" icon="diagram-project" href="/reference/constellation">
    When each crate admits.
  </Card>
</CardGroup>


# Your first workflow
Source: https://docs.nika.sh/getting-started/first-workflow

Five minutes from install to a checked and runnable Nika workflow.

<Info>
  **v:** `nika check`, `nika run`, `nika doctor`, `nika lsp`,
  and `nika mcp` ship in the binary. Run `nika init` once per repo for schema
  and agent rules.
</Info>

## Goal

Write a `.nika.yaml` file, run it, get structured output. No setup beyond
`nika` installed. **Your first run needs no API key and no model server.**

## 1. Pick how the AI step runs

Three paths, from zero-setup to production:

**Instant (no model at all)**: the built-in `mock/echo` model returns a
deterministic response, so you can see a workflow's shape right now:

```yaml theme={"system"}
model: mock/echo
```

**Local (free · private)**: have [Ollama](https://ollama.com) running,
no API key, nothing leaves your machine:

```bash theme={"system"}
ollama pull llama3.2:3b
```

**Cloud**: set any provider key:

```bash theme={"system"}
export MISTRAL_API_KEY=...
# or export ANTHROPIC_API_KEY=... · any provider in the catalog
```

At any point, `nika doctor` tells you exactly what's wired and how to fix
what isn't:

```bash theme={"system"}
nika doctor
```

All provider env vars listed in [Providers catalog](/reference/providers-catalog).

## 2. Write the workflow

Create `hello.nika.yaml`:

```yaml hello.nika.yaml theme={"system"}
nika: v1
workflow:
  id: hello

tasks:
  greet:
    infer:
      model: ollama/llama3.2:3b            # <provider>/<name> · local · swap for any cloud provider
      prompt: "Say hi to the chrysalis. Be brief."
```

Three things to notice:

* **`nika: v1`** declares the workflow language + pins the contract version (a single version marker · `v1` forever).
* **`workflow:`** is an object — `id:` (kebab-case) names the run.
* **`tasks:`** is a map keyed by task id; each task declares one verb (here, `infer`).

## 3. Check it, then run it

```bash theme={"system"}
nika check hello.nika.yaml   # the static audit: plan · cost · secrets · types · before a single token is spent
nika run hello.nika.yaml
```

`nika check` catches broken references, missing dependencies and schema
problems before any model is called, and points at the exact fix:

<video>
  <source type="video/webm" />

  <source type="video/mp4" />
</video>

<Tip>
  No provider handy? Swap the `model:` line for `mock/echo`. Both commands
  work fully offline, and you can wire a real model later.
</Tip>

Example output:

```
▶ greet  infer  → ollama/llama3.2:3b
  ┌─ output ──────────────────
  │ Welcome inside the chrysalis. 🦋
  └───────────────────────────
✓ greet  T+00:00:01.42  OK
```

### Read the story back (0.98+)

`nika explain <file>` narrates any checked workflow — the waves, the
**cost before a token is spent** (an unbounded task reads `FLOOR`, a
local model reads *unpriced — not « free »* — the whole vocabulary
lives in [Cost honesty](/guides/cost-honesty)), what it touches, and
the flight recorder hand-off. Captured verbatim against the released
`0.107.0` on the chain skeleton after one recorded run:

```text theme={"system"}
cost before a token is spent
  bounded portion $0.0000 · no total ceiling · 1 uncapped
    think: ollama/llama3.2:3b has no catalog price — unknown stays unknown (never $0)
  local models: your compute · tokens unpriced — not « free »

flight recorder
  1 run in .nika/traces · latest:
  nika trace show .nika/traces/2026-08-02T01-11-53Z-7f42.ndjson
  nika trace verify <same file>   # prove the hash chain
```

The skeleton already caps the seat (`max_tokens: 800`) — the uncapped
part is the *unpriced* local model, and the report says so instead of
printing a fake `$0`. Swap in any priced cloud seat and the same report
reads `≤ $0.0005 worst case · ≥ $0.0005 cheapest path` — a hard
ceiling.

## 4. Add a second task that depends on the first

```yaml hello.nika.yaml theme={"system"}
nika: v1
workflow:
  id: hello

tasks:
  greet:
    infer:
      model: ollama/llama3.2:3b            # <provider>/<name> · local · swap for any cloud provider
      prompt: "Say hi to the chrysalis. Be brief."

  critique:
    with:
      greeting: ${{ tasks.greet.output }}  # the binding IS the edge
    infer:
      model: ollama/llama3.2:3b            # <provider>/<name> · local · swap for any cloud provider
      prompt: |
        The greeting was: ${{ with.greeting }}

        Rewrite it shorter and more enigmatic.
```

Notice the `with:` block. Each `${{ tasks.X.* }}` reference in it is a
[binding](/concepts/bindings): it **names the data** the task consumes
(`${{ with.greeting }}` in the prompt) and **declares the edge** that
orders it — greet → critique, one declaration, no invisible edges. The
engine injects the value at runtime, with explicit taint tracking.

### The graph you just built

```mermaid theme={"system"}
%%{init: {'theme':'dark','themeVariables':{'background':'transparent','mainBkg':'transparent'}}}%%
flowchart LR
    classDef task fill:#3F7DFF,color:#fff,stroke:#7FE9FF,font-weight:bold
    G["greet<br/>infer"]:::task --> F["critique<br/>infer"]:::task
```

One `with:` binding and the order falls out of the file. Tasks with no
edge between them run **in parallel automatically**. You never schedule
anything. (For an ordering with no data — run the deploy after the tests,
consume nothing — use `after: { tests: success }`, the control door.)

## 5. Get structured output

```yaml hello.nika.yaml theme={"system"}
nika: v1
workflow:
  id: hello-structured

tasks:
  names:
    infer:
      model: ollama/llama3.2:3b            # <provider>/<name> · local · swap for any cloud provider
      prompt: "Generate three names for a butterfly."
      schema:                          # structured output · JSON Schema
        type: object
        properties:
          names:
            type: array
            items:
              type: string
              minLength: 3
              maxLength: 20
            minItems: 3
            maxItems: 3
        required: [names]
```

Nika takes the JSON Schema, asks the provider for output that conforms
(using each provider's native structured-output API where the [capability
rules](/reference/capabilities) allow it: schema mode, object mode, or
JSON-mode emulation), and validates the result against your schema before
passing it on.

```bash theme={"system"}
nika run hello.nika.yaml
# Output is guaranteed to be { "names": ["...", "...", "..."] }
```

## What you just built

* Workflows are YAML files: `.nika.yaml`.
* Tasks are units of work; the map key is the identity.
* Four verbs (`infer`, `exec`, `invoke`, `agent`) define what each task does (HTTP fetch is the `nika:fetch` builtin under `invoke`).
* `with:` (data) and `after:` (control) build the DAG — the binding IS the edge.
* `${{ tasks.X.output }}` crosses a task boundary in `with:`; the body reads `${{ with.<name> }}`, with taint tracking.
* `schema:` enforces JSON schemas on AI output.

## Next checks

<Steps>
  <Step title="Check before running">
    `nika check hello.nika.yaml`: static audit before any token or effect.
  </Step>

  <Step title="Inspect the DAG">
    `nika inspect hello.nika.yaml` (add `--format mermaid|dot|json` for the machine projections).
  </Step>

  <Step title="Wire your agent">
    Run `nika wire cursor` or `nika wire all` for explicit MCP setup, or use
    the editor extension's agent setup.
  </Step>
</Steps>

## Read next

<CardGroup>
  <Card title="Examples · real jobs" icon="rocket" href="/examples/overview">
    Climb the ladder: starter chains to multi-agent swarms, every file
    conformance-validated.
  </Card>

  <Card title="How to write Nika" icon="compass-drafting" href="/guides/patterns">
    The twelve patterns: where the determinism lives, where the model
    is allowed to think.
  </Card>

  <Card title="The 4 verbs" icon="play" href="/concepts/verbs">
    Deep dive on `infer`, `exec`, `invoke`, `agent`.
  </Card>

  <Card title="Bindings" icon="link" href="/concepts/bindings">
    How data flows between tasks with taint tracking.
  </Card>

  <Card title="Providers" icon="server" href="/concepts/providers">
    Why one `InferRequest` works across  providers.
  </Card>

  <Card title="Live state" icon="gauge" href="/reference/status">
    Which verbs are admitted today.
  </Card>
</CardGroup>


# Install Nika
Source: https://docs.nika.sh/getting-started/installation

Install Nika, verify the binary, scaffold a repo, and wire editor/agent MCP clients.

<Warning>
  **Latest release: v**, what `brew install` and the install
  script give you. Main may be ahead with unreleased features. Run `nika --version`
  and `nika --help` after install; those commands are the executable source of
  truth for your local binary. The `nika: v1` language envelope is stable.
</Warning>

## Install today

<Tabs>
  <Tab title="Homebrew">
    ```bash theme={"system"}
    brew install supernovae-st/tap/nika
    ```

    Recent Homebrew versions gate third-party taps behind a trust prompt —
    if the install reports the tap as untrusted, run
    `brew trust supernovae-st/tap` once and retry.
  </Tab>

  <Tab title="curl">
    ```bash theme={"system"}
    curl -LsSf https://nika.sh/install.sh | sh
    ```

    Detects platform (macOS / Linux), prefers Homebrew when `NIKA_VERSION=latest`
    and Homebrew is available, then falls back to the GitHub release binary.
    Prefer a guided page? [nika.sh/install](https://nika.sh/install) walks the
    same install step by step, alongside this raw script.
  </Tab>

  <Tab title="cargo binstall">
    ```bash theme={"system"}
    cargo binstall --git https://github.com/supernovae-st/nika nika-cli
    ```

    Fetches the **prebuilt release tarball** (no compile — the crate ships
    [binstall metadata](https://github.com/cargo-bins/cargo-binstall) mapping
    every release asset). One honest wart until the crates.io publish: the
    binary lands as `~/.cargo/bin/nika-cli` (the crate's declared bin name) —
    add the public name once with
    `ln -sf ~/.cargo/bin/nika-cli ~/.cargo/bin/nika`.
  </Tab>

  <Tab title="nix">
    ```bash theme={"system"}
    nix run github:supernovae-st/nika
    ```

    **Builds the exact release source** via the repo's root `flake.nix` —
    the first run compiles, the store caches it, and the binary answers as
    `nika` (the flake renames the seed crate at install, same as the
    release). `nix profile install github:supernovae-st/nika` for a durable
    install. Zero gatekeeper: no nixpkgs queue, the flake ships in-repo.
  </Tab>

  <Tab title="source">
    ```bash theme={"system"}
    git clone https://github.com/supernovae-st/nika.git
    cd nika
    cargo test --workspace --lib
    cargo build --release -p nika-cli
    mkdir -p ~/.nika/bin
    ln -sf "$PWD/target/release/nika-cli" ~/.nika/bin/nika
    export PATH="$HOME/.nika/bin:$PATH"
    nika --version
    ```
  </Tab>
</Tabs>

## First-run verification

```bash theme={"system"}
nika --version
nika try       # see a canonical workflow WORK — offline, zero keys, nothing written
nika doctor    # providers + editor/agent readiness + exact fixes
nika init      # repo-local schema + AGENTS.md
nika wire all  # explicit MCP wiring for agent clients
```

`nika try` is the zero-risk first contact: it rehearses a canonical
example under the mock provider — nothing written, nothing owned, and
bare `nika try` lists what there is to see. `nika init` scaffolds
repo-local schema wiring and agent context. Newer binaries also expose
`nika wire cursor` / `nika wire all` for explicit MCP client setup.
Installers do not mutate editor configs automatically.

## Platforms

| Platform            | Release asset                       | Status                      |
| ------------------- | ----------------------------------- | --------------------------- |
| macOS Apple Silicon | `nika-macos-arm64-<release>.tar.gz` | shipped                     |
| macOS Intel         | `nika-macos-x64-<release>.tar.gz`   | shipped                     |
| Linux x86\_64       | `nika-linux-x64-<release>.tar.gz`   | shipped                     |
| Linux aarch64       | `nika-linux-arm64-<release>.tar.gz` | shipped                     |
| Windows             | `x86_64-pc-windows-msvc`            | 🧭 planned post-1.0         |
| WASM (sandboxed)    | `wasm32-wasip2`                     | 🧭 planned · a future major |

## Trust but verify

<Check>
  The install script lives at [nika.sh/install.sh](https://nika.sh/install.sh).
  **Read it before piping to `sh`.** It's a small POSIX shell script.

  Release binaries are published at
  [github.com/supernovae-st/nika/releases](https://github.com/supernovae-st/nika/releases)
  with SHA256 sums.
</Check>

## Provider keys

Nika needs a provider to run inference (local needs no key at all).

```bash theme={"system"}
# Local · zero key (Ollama daemon)
ollama pull llama3.2:3b

# Or export any cloud provider key (ephemeral)
export MISTRAL_API_KEY=...
export ANTHROPIC_API_KEY=sk-ant-...
```

See [Providers catalog](/reference/providers-catalog) for all
&#x20;providers with their env var names.

## What gets installed

* **`nika`**, the binary (single file, no daemon, no background process)
* **Nothing else.** No service, no telemetry, no home-dir pollution beyond
  files you explicitly create with `nika init` or `nika wire`.

## Shell completions

The binary generates its own completions — no separate package, always in
sync with the verbs your version actually ships:

<Tabs>
  <Tab title="zsh">
    ```bash theme={"system"}
    mkdir -p ~/.zsh/completions
    nika completions zsh > ~/.zsh/completions/_nika
    # once, in ~/.zshrc (before compinit):
    # fpath=(~/.zsh/completions $fpath)
    exec zsh
    ```
  </Tab>

  <Tab title="bash">
    ```bash theme={"system"}
    mkdir -p ~/.local/share/bash-completion/completions
    nika completions bash > ~/.local/share/bash-completion/completions/nika
    exec bash
    ```
  </Tab>

  <Tab title="fish">
    ```bash theme={"system"}
    nika completions fish > ~/.config/fish/completions/nika.fish
    ```
  </Tab>
</Tabs>

Also available: `elvish` and `powershell`. Re-run the same command after an
upgrade to pick up new verbs.

<Note>
  On engines up to 0.93.x the generated script bound completions to the
  internal binary name instead of `nika` — fixed on current main. If
  completions don't fire after installing, upgrade and regenerate.
</Note>

## Uninstall

```bash theme={"system"}
# Homebrew
brew uninstall nika

# Manual install
rm ~/.nika/bin/nika
```

## Next

<CardGroup>
  <Card title="First workflow" icon="play" href="/getting-started/first-workflow">
    Your first `.nika.yaml`.
  </Card>

  <Card title="Editor setup" icon="code" href="/getting-started/editors">
    Schema validation + LSP roadmap.
  </Card>

  <Card title="Live state" icon="gauge" href="/reference/status">
    Track live engine state.
  </Card>

  <Card title="Architecture" icon="layer-group" href="/architecture/layers">
    Why Nika is built this way.
  </Card>
</CardGroup>

## The Nika ecosystem

<Ecosystem />


# What Nika sees on your machine
Source: https://docs.nika.sh/getting-started/your-machine

One offline command maps your environment: editors wired, local model servers, key presence, media planes — and the exact fix for every gap.

Nika never asks you to configure blind. Two commands read your machine —
**offline, presence-only** — and hand you the exact next step:
`nika welcome` is the thirty-second mirror, `nika doctor` the exhaustive
diagnosis with a fix line per gap.

## The mirror

```bash theme={"system"}
nika welcome
```

Captured verbatim against the released `nika 0.107.0` on a machine with no
keys, no configs, no editors wired — the stranger's first screen (only the
workspace path is shortened to `~/demo`):

```text theme={"system"}
🦋 nika 0.107.0 — Intent as Code. The workflow language for AI.
   one file · 4 verbs · one binary · audited BEFORE it runs
   every run records a tamper-evident, hash-chained trace

this machine
  editors    cursor ✗ · windsurf ✗ · claude ✗ · zed ✗ · hermes ✗ · vscode ✗   → nika wire cursor
  local      ollama · lmstudio · llamacpp · localai · vllm · no key needed
  state      installed · no inference path — proof → nika try 01-hello
  workspace  ~/demo · git ✗ · no workflows yet · agents not briefed → nika init

this binary
  4 verbs · 28 builtins · 15 providers · 39 examples · 10 templates

a whole workflow is one file
  nika: v1
  workflow:
    id: hello
  model: mock/echo
  tasks:
    greet:
      infer: { prompt: "say hello to the operator", max_tokens: 50 }

start here (offline · zero keys)
  nika try 01-hello   # offline proof · zero keys
  nika init           # found this repo (wizard)
  nika new            # guided first workflow

learn: nika.sh · docs: docs.nika.sh · ⭐ github.com/supernovae-st/nika
```

Three details worth noticing: the seven-line workflow **is real** (an
engine test pins that it checks clean — the sample only appears while
your workspace has zero workflows), every count on the « this binary »
line is derived live from the embedded pack (never hand-typed — the
`15 providers` are the runnable cloud + local set; the
[catalog](/reference/providers-catalog) counts 17 with the deterministic
`mock`), and the `state` row names the gap, never a vendor: no inference
path yet, and the proof door is one command (`nika try 01-hello` —
offline, zero keys, nothing written).
`--json` emits the machine mirror (`welcome_version: 1`); `--ascii`
swaps every glyph for CI logs.

## The diagnosis

```bash theme={"system"}
nika doctor
```

Three honesty rules shape everything below:

* **Presence, never values.** A key is reported set or unset — the value is
  never read into a variable, so it can never reach your terminal, a log,
  or a trace.
* **Offline by default.** The base run touches nothing on the network.
  `--ping` (opt-in) TCP-probes your **local** ports only — never a vendor
  endpoint, and nothing is ever sent on the socket.
* **Diagnose-only.** Doctor prints fixes, it never runs them. Your shell,
  your `PATH`, your configs stay untouched (`nika wire` is the explicit,
  idempotent mutator when you want one).

## A fresh machine, honestly

Captured verbatim against `nika 0.107.0` on a machine with no keys, no
configs, no editors wired — the worst case, and the whole report:

```text theme={"system"}
✔ 10 ok · 18 warn · 0 fail
✔ binary     v0.107.0 · self-contained (spec v1 embedded)
✔ lsp        available via `nika lsp` (editor language server)
✔ traces     keep 10 per workflow · max age 30d · budget 256MB (NIKA_TRACE_KEEP · NIKA_TRACE_MAX_AGE_DAYS · NIKA_TRACE_BUDGET_MB)
✔ mcp        available via `nika mcp` (9 read-only tools · nika_check through nika_tools)
✔ sidecar    local inference built in — `nika model serve --model <path.gguf>` (loopback · OpenAI-compatible)
⚠ models     none pulled yet — the sidecar has nothing to serve
  fix: nika model pull Qwen/Qwen3-4B-Instruct-2507-GGUF
✔ registry   client matrix · 31 declared · 21 wireable · 6 probed · 15 declared-not-probed (codex · grok-build · claude-desktop · cline · continue · opencode · gemini-cli · antigravity · qwen-code · kimi-code · kiro · copilot-cli · amp · lmstudio · junie)
✔ local      5 providers (ollama · lmstudio · llamacpp · localai · vllm) — no key · needs a running server
  fix: nika doctor --ping   # probe the local ports (offline otherwise)
✔ image      mock ready · local → http://localhost:8080 default (set NIKA_IMAGE_LOCAL_URL to point elsewhere) · no cloud image key set
✔ tts        mock ready · local → http://localhost:8080 default (set NIKA_TTS_LOCAL_URL to point elsewhere) · no cloud speech key set
✔ pricing    633 models · 10 providers · snapshot 2026-07-28 · d5aa8fd06062f49e · list rates (public catalog)
· advisory   a healthy machine's notes — 6 agents unwired · 10 providers unconfigured · config defaults · nika doctor --verbose unfolds each
```

(A healthy machine reads calm: with no workflow in hand, doctor cannot
know which provider or editor you need, so unwired agents and unset keys
fold into the one `advisory` line instead of shouting eighteen warnings —
`nika doctor --verbose` unfolds every row with its own `fix:` line.)

Read it in one pass:

| Row             | What it tells you                                                                                                                           |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| `binary`        | The engine is self-contained — spec, schema, examples, templates all embedded. No install step is missing.                                  |
| `traces`        | The flight-recorder retention bounds (`.nika/traces/`): keep-last-N per workflow, age cap, size budget — each env override named inline.    |
| `registry`      | The client matrix: how many agent clients the binary knows, how many `nika wire` can write, how many this machine was probed for.           |
| `local`         | The keyless, sovereign path — these providers need a running server, not an account.                                                        |
| `image` · `tts` | The media planes — `mock` always works, so media workflows are testable with zero keys too.                                                 |
| `pricing`       | The embedded cost snapshot (models · providers · date · digest) — list rates, no network call.                                              |
| `advisory`      | The folded notes — unwired agents, unset keys (by **presence**, values never read), config defaults. `--verbose` unfolds each with its fix. |

## Probe the local ports

The local providers row says « needs a running server » — `--ping` answers
whether one is actually there (loopback connect, 300 ms cap, nothing sent):

```text theme={"system"}
$ nika doctor --ping
✔ ping       ollama — listening on 127.0.0.1:11434 (7ms)
⚠ ping       lmstudio — nothing listening on 127.0.0.1:1234
⚠ ping       llamacpp — nothing listening on 127.0.0.1:8080
⚠ ping       localai — nothing listening on 127.0.0.1:8080
⚠ ping       vllm — nothing listening on 127.0.0.1:8000
```

One local server up = a fully sovereign inference path: no key, no cloud,
no account. That is the machine from the capture running
[local models](/guides/local-models) with nothing else configured.

## For scripts and agents

Every fact above ships as JSON — agents and CI branch on `summary.fail`
instead of parsing glyphs:

```bash theme={"system"}
nika doctor --json
```

## The fix that mutates, explicitly

Doctor never edits configs. When a row says `fix: nika wire cursor`, that
command — and only that command — writes the MCP wiring, idempotently,
preserving whatever other servers the config already carries:

```bash theme={"system"}
nika wire cursor     # or: claude · vscode · windsurf · codex · all
```

## Next

<CardGroup>
  <Card title="First workflow" icon="play" href="/getting-started/first-workflow">
    Your first run needs none of the keys above — `mock/echo` is free and offline.
  </Card>

  <Card title="Local models" icon="server" href="/guides/local-models">
    Turn the `local` row into a running, keyless inference path.
  </Card>

  <Card title="Editors" icon="code" href="/getting-started/editors">
    What the wired editor actually does (diagnostics · canvas · time-travel).
  </Card>

  <Card title="Agents" icon="robot" href="/getting-started/agents">
    `nika init` briefs your agents; `nika wire` points them at the oracle.
  </Card>
</CardGroup>


# Writing Nika as an agent
Source: https://docs.nika.sh/guides/agent-authoring

The deterministic protocol: route to a template, fill the slots, check, repair from the error. A weak model on this path beats a strong model improvising.

Agents are the primary authors of Nika. The language is built so
that the *path* carries the quality, not the model: a small closed
grammar ( verbs ·  namespaces · one
expression surface), one canonical way per intention, and a validator
whose errors prescribe their own fix.

## The protocol

```mermaid theme={"system"}
flowchart LR
  intent["intent"]:::invoke --> route["route to a template"]:::invoke
  route --> fill["fill the SLOT lines"]:::infer
  fill --> check["check"]:::exec
  check -->|"errors"| repair["repair from the error"]:::infer
  repair --> check
  check -->|"valid"| done["ship"]:::agent
  classDef infer fill:#5b8cff22,stroke:#5b8cff,color:#5b8cff
  classDef exec fill:#ff7a3c22,stroke:#ff7a3c,color:#ff7a3c
  classDef invoke fill:#22d3ee22,stroke:#22d3ee,color:#22d3ee
  classDef agent fill:#b07bff22,stroke:#b07bff,color:#b07bff
```

<Steps>
  <Step title="Route: one intent, one template">
    The [templates](https://github.com/supernovae-st/nika-spec/tree/main/templates)
    are complete, valid skeletons (conformance-gated on every
    push). Match the outer shape of the job:

    | Intent sounds like…                   | Template           |
    | ------------------------------------- | ------------------ |
    | take data → produce words → save      | `chain`            |
    | watch X, act when Y                   | `gate-and-act`     |
    | do this for every item                | `fanout`           |
    | only what changed · survive bad input | `etl-state`        |
    | research / review / open-ended        | `agent-loop`       |
    | anything irreversible                 | `human-gated-ship` |
  </Step>

  <Step title="Instantiate: structure is copied, never invented">
    Copy the template, rename the workflow, fill every `# SLOT:` line.
    Creativity belongs only in prompts, jq expressions and paths. If
    the job needs a construct the template lacks, the
    [coverage matrix](/examples/overview#find-the-example-that-teaches-x)
    names the canonical example that exercises it: read it, don't
    guess.
  </Step>

  <Step title="Check: never ship unchecked">
    `nika check workflow.nika.yaml` (engine) or
    `python conformance/runner.py validate <file>` (spec oracle).
    Editors get the same truth live via the
    [JSON Schema](https://github.com/supernovae-st/nika-spec/blob/main/schemas/workflow.schema.json).
  </Step>

  <Step title="Repair: the error names its fix">
    Fix exactly what the code says, nothing else, then re-check:

    | Error                       | The fix                                                                                                                                                                                     |
    | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
    | `NIKA-VAR-021`              | you referenced `${{ tasks.X.* }}` in a verb body, `when:` or `for_each:`: hoist it into `with:` and read `${{ with.<name> }}` (`nika check --fix` applies it)                               |
    | `NIKA-PARSE-024`            | `depends_on:` is dead: data → a `with:` binding · control → `after: { x: success }` (`nika check --fix` migrates)                                                                           |
    | `NIKA-DAG-001`              | cycle: remove the back-edge                                                                                                                                                                 |
    | `NIKA-DAG-005`              | unknown `after:` predicate: the set is closed — `success` · `failure` · `skipped` · `terminal` (the participial `succeeded`/`failed` are dead spellings · `nika check --fix` respells them) |
    | `NIKA-VAR-001`              | undeclared name: declare it under the authority its role commands — `inputs:` · `config:` · `const:` · `secrets:` — or fix the typo                                                         |
    | `NIKA-PROVIDER`             | `model:` must be `<provider>/<name>` with a canonical prefix                                                                                                                                |
    | `NIKA-PARSE` (duplicate id) | two tasks share an id: rename one                                                                                                                                                           |
  </Step>
</Steps>

## The hard rules

These catch \~90% of LLM-written errors. The validator enforces all of
them; knowing them just saves round-trips:

1. **One verb per task** · `infer`, `exec`, `invoke` or `agent`.
2. **snake\_case task ids** (CEL-safe) · **kebab-case `workflow:`**.
3. **`tasks.*` crosses a boundary through `with:` or `after:` only** ·
   the binding IS the edge, the body reads `${{ with.<name> }}` — the
   DAG has no invisible edges (`NIKA-VAR-021` otherwise, and
   `depends_on:` is dead: `NIKA-PARSE-024`).
4. **`when:` is a `${{ }}` CEL boolean or the literal `true`/`false`** ·
   `${{ inputs.count }}` is not a condition; `${{ inputs.count > 0 }}` is;
   a bare string without `${{ }}` is rejected. It reads local namespaces
   only (the value authorities `inputs` · `config` · `const` · `secrets`,
   plus `with` · `item`/`index`), post-gate; the always-pattern is
   `after: { x: terminal }`, never a `when:` trick.
5. **The CEL function set is closed** · `size()` · the `has()` presence
   macro · the `contains`/`startsWith`/`endsWith` string tests · the
   `?:` conditional (`cel-subset/0.1`). Everything else — arithmetic,
   regex, transforms — lives in jq, not in `${{ }}`.
6. **`nika:write` needs `content:`** · a write without it writes
   nothing.
7. **`nika:done` only inside `agent.tools`** · it is the loop
   sentinel, meaningless elsewhere.
8. **Fan-outs get the leash** · `max_parallel` + `fail_fast: false` +
   per-iteration `retry`/`timeout`.
9. **Native-first** · `invoke: nika:*` → `mcp:<server>/<tool>` →
   `exec:` last. An `exec:` a builtin covers earns a `native-first`
   hint; `nika check --native-strict` fails on any that remain, and a
   surviving `exec:` gets an exec-ledger row (task · command · why ·
   unlock) in the workflow header.
10. **Every value lands under one of four authorities** · `inputs:`
    (the caller supplies it) · `config:` (the deployment supplies it) ·
    `const:` (the file owns it) · `secrets:` (a governed store). `vars:`
    and `env:` are dead envelope fields (`NIKA-VALUES-001` /
    `NIKA-VALUES-002`) — classify by the role the value plays, never
    rename in bulk.
11. **A body with effects carries `permits:`** · an absent block is
    **zero** authority, not a free pass: the check refuses with
    `NIKA-AUTH-006` before a token is spent, and the run refuses with
    `NIKA-SEC-004`. Write the block with `nika check --infer-permits`,
    which prints the tightest one and is paste-ready.

## After valid: the judgment layer

Validity is the floor. The [twelve patterns](/guides/patterns) are the
ceiling: deterministic core, typed boundaries, the right gate
(`when` = skip · `assert` = fail · `prompt` = human), sovereignty for
sensitive data, budgets on agents, `on_finally` evidence. Every
pattern links the canonical example that embodies it.

<Columns>
  <Card title="The templates" icon="copy" href="https://github.com/supernovae-st/nika-spec/tree/main/templates">
    The skeletons, every decision point a slot, conformance-gated.
  </Card>

  <Card title="The twelve patterns" icon="compass-drafting" href="/guides/patterns">
    The judgment layer: why each locked choice is locked.
  </Card>
</Columns>


# Charts
Source: https://docs.nika.sh/guides/charts

Deterministic chart artifacts — rows + a semantic spec compile to byte-identical SVG, sha256-chained into the run's trace. Five types, typed semantics, an optional Vega-Lite sibling.

`nika:chart` is the data twin of [`nika:image_fx`](/guides/image-effects):
pure compute plus one permit-gated write — no network, no clock, no
provider. Rows and a semantic spec compile to an SVG that is
**byte-identical forever** for identical inputs, and the artifact's sha256
joins the run's hash-chained trace. Your cost report draws its own
receipts.

## The 30-second chart

```yaml theme={"system"}
nika: v1
workflow:
  id: spend-report
permits:
  tools: ["nika:chart"]
  fs: { write: ["out/**"] }
tasks:
  draw:
    invoke:
      tool: "nika:chart"
      args:
        data:
          - { day: 1751328000000, cost: 0.42, provider: "anthropic" }
          - { day: 1751414400000, cost: 0.31, provider: "anthropic" }
          - { day: 1751328000000, cost: 0.05, provider: "ollama" }
          - { day: 1751414400000, cost: 0.07, provider: "ollama" }
        semantics: { day: timestamp, cost: usd, provider: category }
        chart: { type: line, x: day, y: cost, color: provider, title: "Spend by provider" }
        out: out/spend.svg

outputs:
  receipt: "${{ tasks.draw.output }}"
```

Run it twice: the second run is idempotent and the artifact hash never
moves. The SVG ships accessibility built in (`role="img"` +
`aria-label`, a `<title>` node) and carries its own recipe in a
`<metadata>` block — the chart explains itself with no sidecar.

## The five types (closed · v1)

| `type`      | Shape                     | The extra fields                             |
| ----------- | ------------------------- | -------------------------------------------- |
| `bar`       | magnitude by category     | —                                            |
| `line`      | change over time          | `color` splits series                        |
| `area_band` | a range around a line     | `y_lo` / `y_hi` bounds · `y2` actual overlay |
| `scatter`   | two measures, point cloud | `color` splits series                        |
| `heatmap`   | grid intensity            | `color` names the VALUE field                |

`x` / `y` / `y_lo` / `y_hi` / `y2` / `color` are **field names** into your
rows. `title`, `width`, `height` are optional.

## Semantics drive the rendering

`semantics:` maps each field to what it *means* — the type picks the
formatting and the palette, so the chart is right by construction:

| Semantic           | Renders as                                                                                                                          |
| ------------------ | ----------------------------------------------------------------------------------------------------------------------------------- |
| `usd`              | currency ticks (a floor stays a floor — unpriced never fakes a 0)                                                                   |
| `duration_ms`      | humanized durations                                                                                                                 |
| `tokens` · `count` | integer scales                                                                                                                      |
| `percent`          | percentage axis                                                                                                                     |
| `delta`            | **diverging palette anchored at 0** — sign is the message                                                                           |
| `timestamp`        | time axis — the value is **epoch milliseconds** (a date string is a type error at check-in: `NIKA-BUILTIN-CHART-006` names the row) |
| `category`         | the fixed categorical palette, hues assigned in order, never cycled                                                                 |

## Rows in, artifact out

`data` accepts inline rows (an array of flat string/number objects) or
`{ path: "rows.json" }` to read a JSON file — the natural pair with an
upstream task that produced it. `out` must end in `.svg` (the
attestation surface); parents are created; the write is `fs`-permit
gated like every artifact.

## The Vega-Lite sibling

```yaml theme={"system"}
        compile_to: vega_lite
```

writes `out/spend.vl.json` next to the SVG — a real Vega-Lite spec
(`$schema` · `data` · `encoding` · `mark`) for any downstream tool that
speaks it. The SVG stays the canonical, hash-verified artifact; the
sibling is a projection.

## Determinism is the contract

Same rows, same spec, same bytes — proven across architectures
(wasm32 ≡ aarch64 in the engine's own parity suite). That makes charts
*evidence*: the sha256 in the task output is the same one the trace
chain records, `nika trace verify` walks it, and a regenerated chart
that stops matching is a tamper signal, not a formatting quirk.

Pair it with the flight recorder: draw your run costs from
`.nika/traces/` data, and the report about your runs is itself a
receipt in one.


# Cost honesty
Source: https://docs.nika.sh/guides/cost-honesty

Know what a run can cost BEFORE you run it — floors, ceilings, unpriced truth, and the budget gate that refuses to start.

> The doctrine in one line: **unknown stays unknown**. A cost Nika cannot
> prove is never rendered as `$0.00`, a local model is *unpriced* — your
> compute, your electricity — never « free », and an estimate always says
> which side of the truth it sits on: a **floor** (`≥`) or a **ceiling**
> (`≤`).

## The vocabulary

Every cost surface speaks the same four words:

| Word          | Meaning                                                               | Where you see it                             |
| ------------- | --------------------------------------------------------------------- | -------------------------------------------- |
| **FLOOR**     | the provable minimum — real spend can only be higher                  | `check` COST rung · run totals (`≥ $…`)      |
| **ceiling**   | the provable worst case — real spend can only be lower                | `check` COST rung once every task is bounded |
| **UNBOUNDED** | a task whose spend has no provable limit, with the WHY                | `check` per-task rows                        |
| **unpriced**  | tokens were spent but no catalog price exists (local · unknown model) | run totals (`(N unpriced)`) · `explain`      |

There are exactly two ways a task goes UNBOUNDED, and the rung names
which one:

* `UNBOUNDED — no max_tokens declared` · the model has a price but the
  task has no output limit. **You can fix this one**: declare
  `max_tokens:` and the report upgrades from floor to hard ceiling
  (the check prints that exact hint).
* `UNBOUNDED — no catalog price (local/unknown model)` · the task is
  bounded but the model has no price row. Local models stay here **by
  design** — pricing your own hardware would be invention.

## Before a token: the COST rung

`nika check` audits cost statically, next to the plan and the permits —
the same ladder, every time:

```text theme={"system"}
 ⚠  COST     $0.0000 – $0.0000 FLOOR (unbounded tasks present)
   think  ollama/qwen3.5:4b  UNBOUNDED — no max_tokens declared
 ↳ HINT     [cost] declare `max_tokens` on `think` — the cost report
            becomes a hard ceiling instead of UNBOUNDED
```

Bound every task and the same rung flips to
`✔ COST $0.0001 – $0.0001 worst-case ceiling` with a per-task
`≤N tk · $…` row. `nika explain <file>` narrates the same numbers in
beginner words — *« ≥ \$0.0000 — a FLOOR, not a ceiling · local models:
your compute · tokens unpriced — not « free » »* — and
`nika run --dry-run` carries them onto the plan.

## The budget gate: refusal, not remorse

`--max-cost-usd` is a **block-before-spend** gate, not a post-hoc alarm:

* If the static floor already exceeds the budget, the run **refuses to
  start** (exit 2, before any provider is touched):

  ```text theme={"system"}
  refusing to start: the workflow's unavoidable cost floor $0.040000
  exceeds --max-cost-usd $0.000100 … (nika check shows the envelope)
  ```

* Since 0.99 that pre-start refusal prices the **effective** model —
  `--model` override included. On 0.98.x the override was only guarded
  mid-run; upgrading closes that gap.

* If unbounded work rides along, the gate says so loudly on stderr —
  a budget over work with no ceiling is a promise it names, not one it
  fakes.

* Mid-run, the ledger stops the workflow the moment real spend crosses
  the budget (`NIKA-1704`) — settled tasks stay settled, the trace
  records what was spent.

* The flag itself is guarded: a non-finite value (`NaN`, `inf`) is
  rejected at parse time — a budget that cannot compare is not a budget.

## After the run: the totals stay honest

Every run ends with the same honest line, mock or cloud:

```text theme={"system"}
── 1/1 done · ≥ $0.00 (1 unpriced) · elapsed 0.0s ──
```

The `≥` is load-bearing: it is printed **because** an unpriced task
rode the run. Per-task spend rides the trace itself (`cost_usd` on the
terminal events), so `nika trace show` and the run report read the
recorded ledger — never a summary's opinion.

## Where prices come from — and when they rot

Prices are a **catalog fact with provenance**, not a constant:
`nika check --json` carries the pricing snapshot (source · date ·
hash · derived counts) so a cost claim is traceable to the table that
produced it, and `nika doctor` warns when the snapshot is stale enough
to distrust — an old price table silently *undercounts*, which is the
one direction honesty cannot tolerate. Cache-aware accounting follows
the OpenTelemetry GenAI convention (input includes cache reads), so
exported traces mean the same thing your dashboards expect.

## The workflow-side controls

```yaml theme={"system"}
tasks:
  think:
    infer:
      model: ollama/qwen3.5:4b
      prompt: "${{ inputs.question }}"
      max_tokens: 600        # the ceiling lever — every infer should carry one
```

* `max_tokens:` per task · turns FLOOR into ceiling.
* `agent:` budgets (`max_turns` · token budgets) bound the loop the
  same way — exhaustion is a named failure, never a silent overrun.
* `nika check` before `nika run`, always: the cost story is part of
  the same pre-flight as permits and secrets.

<Note>
  Local-first corollary: a workflow that runs entirely on `ollama/…`,
  `llamacpp/…` or `vllm/…` reports `$0.00` **with the unpriced count
  attached** — Nika never converts « I don't know the price » into
  « it's free ». That distinction is the whole doctrine.
</Note>


# A Docker AI workflow
Source: https://docs.nika.sh/guides/docker-ai-workflow

Read the daemon's real state, have a local model explain it, keep the report — with the exec boundary pinned to argv form and default-deny permits.

Ops work is where « the agent ran a command » stops being acceptable and
« the file says exactly which commands, and the runtime enforces it »
starts to matter. This guide builds a Docker health report the audited
way: two pinned `docker` reads, one local model, one kept artifact.

## The whole workflow

Checked clean against `nika 0.107.0` (`nika check` exit 0 · permits
declared · 0 hints):

```yaml theme={"system"}
# EXEC LEDGER ·
# | task | command          | why no native path               | unlock that removes it |
# | ps   | docker ps        | product CLI · no MCP surface yet | a docker MCP server    |
# | df   | docker system df | same                             | same                   |
nika: v1
workflow:
  id: docker-health-report
  description: read the Docker daemon's state, have a local model explain it, keep the report

model: ollama/qwen3.5:4b

permits:
  exec:
    - "docker"
  tools:
    - "nika:write"
  fs:
    write:
      - "./docker-health.md"

tasks:
  ps:
    exec:
      command: ["docker", "ps", "--all", "--format", "{{.Names}}\t{{.Status}}\t{{.Image}}"]

  df:
    exec:
      command: ["docker", "system", "df"]

  diagnose:
    with:
      containers: ${{ tasks.ps.output }}
      disk: ${{ tasks.df.output }}
    infer:
      prompt: |
        You are reading a Docker host's state. Containers (name·status·image):
        ${{ with.containers }}

        Disk usage:
        ${{ with.disk }}

        Write a short health report: what is running, what exited, what
        looks unhealthy (restart loops · old exits), and whether disk
        usage needs attention. Plain prose, no preamble.
      max_tokens: 600

  keep:
    with:
      report: ${{ tasks.diagnose.output }}
    invoke:
      tool: "nika:write"
      args:
        path: "./docker-health.md"
        content: "${{ with.report }}"

outputs:
  report: ${{ tasks.keep.output }}
```

## Why the exec tasks are arrays

Write `shell: "docker ps | grep Up"` and `nika check` refuses to bless
the boundary:

```text theme={"system"}
✖ PERMITS  [exec] task `ps` · a shell-string command cannot be verified
           against a `permits.exec` program allowlist (a pipeline can
           launch any program) — use the array form
```

That refusal is the feature. A shell string can smuggle any program
through a pipe; the **argv array** names exactly one program with exactly
those arguments, so `permits.exec: ["docker"]` is a boundary the checker
can actually prove. Transforms that would have lived in `| grep | awk`
belong in `output:` bindings and `nika:jq` instead.

## What the audit says before a token is spent

```text theme={"system"}
✔ PLAN     3 wave(s) · 4 task(s) · max parallelism 2
     wave 1 ps (exec · docker) · df (exec · docker)
     wave 2 diagnose (infer · ollama/qwen3.5:4b)
     wave 3 keep (invoke · nika:write)
⚠ COST     $0.0000 – $0.0000 FLOOR (unbounded tasks present)
  diagnose  ollama/qwen3.5:4b  UNBOUNDED — no catalog price (local/unknown model)
✔ PERMITS  body fits the declared boundary
✔ audited · 4 task(s) · 3 wave(s) · permits declared · est ≥$0.0000 · 0 hints
```

Two things worth noticing:

* The two `docker` reads run **in parallel** (wave 1) — the scheduler
  proved it from the `with:` bindings, nobody ordered it.
* The cost line practices the honesty rule: a local model is **unpriced
  compute, not « free »** — the report says FLOOR and names why, it never
  rounds unknown to \$0.

## Run it

```bash theme={"system"}
nika run docker-health-report.nika.yaml
```

Captured verbatim (Apple-silicon laptop · Docker Desktop · a small local
thinking model — the two-minute `infer` is the model, not the engine):

```text theme={"system"}
🦋 nika · docker-health-report · 4 tasks
   permits ✓ declared boundary · default-deny

✔  ps        exec · docker              108ms ∥
✔  df        exec · docker              561ms ∥
✔  diagnose  infer · ollama/qwen3.5:4b  2m16s
✔  keep      invoke · nika:write          2ms
── 4/4 done · $0.00 · elapsed 137.3s ───────────────────────────
  trace: .nika/traces/2026-07-08T12-43-02Z-d3f3.ndjson · 14 events · chain 5667b30f53baf619227324e70871de71
```

`docker-health.md` now holds the model's prose, and the run left a
hash-chained journal you can prove later:

```bash theme={"system"}
nika trace verify .nika/traces/<run>.ndjson
```

## When the daemon is down

The failure is part of the design. With Docker stopped, the same run
fails **honestly and early** — the model is never called, nothing is
spent, and the card hands over:

```text theme={"system"}
✖  ps        exec · docker              167ms ∥
⊘  diagnose  blocked · upstream failed
⊘  keep      blocked · upstream failed
── 4/4 done · $0.00 · elapsed 0.2s ─────────────────────────────

✖ NIKA-EXEC-001 · command exited with status 1: failed to connect to the
  docker API at unix:///…/docker.sock; check if the path is correct and
  if the daemon is running
  fix: nika explain NIKA-EXEC-001
```

## Take it further

* **Gate an action on the report** — add an `agent:` task allowed only
  `nika:done`, or a `when:` gate on a structured `diagnose` output, and
  the workflow can *act* on unhealthy containers, still inside the
  declared boundary. See [patterns](/guides/patterns).
* **Schedule it** — the file is the artifact: cron or CI runs
  `nika run` and every execution leaves a verifiable trace.
* **Structured instead of prose** — give `diagnose` a `schema:` and the
  report becomes typed data downstream tasks can branch on. See
  [testing](/guides/testing) for pinning it with a golden.

<Note>
  The two `exec` tasks carry the repo's **exec ledger** (the header
  comment): every surviving `exec:` names why no builtin or MCP tool
  covers it yet, and what would remove it. When a Docker MCP server enters
  your stack, `invoke:` replaces both reads and the ledger empties —
  that is the [native-first law](/concepts/workflows) working as intended.
</Note>


# Energy honesty
Source: https://docs.nika.sh/guides/energy-honesty

What a run draws from the wall — the cost-honesty doctrine in watt-hours. Unknown stays unknown: never 0 Wh.

> The doctrine in one line: **unknown stays unknown**. An energy figure
> Nika cannot prove is never rendered as `0 Wh`, a local model is
> *unpriced* — your hardware, your watts — never « free », and every
> figure carries WHO measured it and WHAT it covers, so two honest
> numbers stay comparable.

<Note>
  **Status** · the doctrine and the data rail ship today — the model
  catalog carries sourced energy facts (schema `@1.3`, absence over
  guess). The `ENERGY` line in `nika check` and the `--max-energy-wh`
  gate are specified by
  [NEP-0018](https://github.com/supernovae-st/nika-spec/blob/main/governance/nep-0018-energy-honesty.md)
  (Draft) and land with its implementation. This page states the contract
  those surfaces honor — it does not claim they render yet.
</Note>

## The vocabulary

Energy speaks the same four words as [cost](/guides/cost-honesty),
with the same semantics:

| Word              | Meaning                                                                                                   |
| ----------------- | --------------------------------------------------------------------------------------------------------- |
| **floor** (`≥`)   | the provable minimum — real draw can only be higher                                                       |
| **ceiling** (`≤`) | the provable worst case — a task's `max_tokens` cap × a sourced per-token figure                          |
| **UNBOUNDED**     | a task whose energy has no provable limit, with the WHY (`no max_tokens declared` — you can fix that one) |
| **unpriced**      | tokens will be spent but no sourced figure exists for the model — local models live here **by design**    |

## A fact, not a vibe

An energy figure enters the catalog as a five-field fact or not at all:

```toml theme={"system"}
energy = { wh_per_mtok_out = 42.0,
           provenance = "independent-measured",
           scope = "gpu",
           source = "ml.energy leaderboard v3.0 · H100 · vLLM · conversation workload (arXiv 2505.06371)",
           measured_at = "2025-12" }
```

That row is real — the first sourced figure in the catalog
(`groq / qwen/qwen3-32b`). Open-weight models are the measurable
frontier: a third party can put them on a bench. Closed APIs stay
**unpriced** until a vendor discloses or an independent methodology
covers them — that asymmetry is honest, and the catalog keeps it.

Two axes make two honest numbers comparable:

* **`provenance`** — who produced the number: `measured-local` (a probe
  on your machine) · `independent-measured` (a third-party benchmark) ·
  `vendor-claim` · `independent-estimate` (modelling, labelled as such —
  an estimate may enter explicitly, never as a silent default).
* **`scope`** — what it covers: `gpu` (accelerator only) · `device`
  (whole host) · `fleet` (host + idle + datacenter PUE). A GPU-only
  figure is roughly **half** a fleet figure for the same model: without
  this axis, two truthful numbers are silently incomparable.

And the unit is per million **output** tokens (`wh_per_mtok_out`)
because decode dominates measured inference energy (≥96% in the
ML.energy v3.0 methodology) — a per-total figure would dilute the
number with nearly-free prefill and reward long prompts.

## Why never `0 Wh`

`0 Wh` would claim free inference. Nothing is: a local model draws from
your wall, an unmeasured cloud call draws from someone's datacenter.
The catalog refuses a zero at build time — the null is the **absent**
fact, and an absent fact renders **unpriced**, exactly as an unpriced
model renders on the cost side. If you have never seen an energy number
in a Nika surface, that is the feature: no number was provable, so no
number was shown.

## What lands with NEP-0018

The specified surfaces, stated here so their contract is public before
their code:

* an `ENERGY` reading beside `COST` in `nika check` — bounded part as
  `≤ N Wh` with the scope axis named, every uncapped task named with its
  reason, unmeasured models `unpriced`, mixed scopes never silently
  summed;
* energy aggregation in `nika:inspect` under the same markers;
* `--max-energy-wh` — a block-before-spend gate symmetric to
  [`--max-cost-usd`](/guides/cost-honesty): refusal, not remorse.

## Why watt-hours, not CO₂e

Carbon intensity varies by grid, hour and region — a gCO₂e constant
hides a location assumption inside a number. Watt-hours are the
measurable; a carbon projection needs YOUR grid factor as an explicit
input, and may arrive later as exactly that. First the honest unit.


# Image effects
Source: https://docs.nika.sh/guides/image-effects

Deterministic artistic styling — dither, palettes, halftone, retro, glitch, ascii. Same input, same args, same bytes forever: the styled image becomes a receipt in the run's proof chain.

`nika:image_fx` is the deterministic sibling of
[`nika:image_generate`](/guides/image-generation): a pure pixel transform —
no provider, no network, no clock. Style a PNG through an ordered pipeline of
effects and get an artifact that is **byte-identical forever** for identical
`(input, args)`.

That determinism is the point, not a detail. The artifact's sha256 joins the
run's hash-chained trace, re-rendering the recipe is the tamper check, and the
full recipe (contract tag `image_fx/v1` · input sha256 · seed · ops) travels
*inside* the PNG as a `nika` tEXt chunk — no timestamp, ever. Your workflow
draws its own receipts.

## The 30-second pipeline

```yaml theme={"system"}
nika: v1
workflow:
  id: styled-hero
permits:
  tools: ["nika:image_generate", "nika:image_fx"]
  fs:
    read: ["out/**"]
    write: ["out/**"]
tasks:
  generate:
    invoke:
      tool: "nika:image_generate"
      args:
        provider: mock            # offline dry-run · flip to local/openai/gemini/xai
        prompt: "a monarch butterfly over a nebula"
        output_dir: out
        format: png
  style:
    with:
      src: ${{ tasks.generate.output.images[0].path }}
    invoke:
      tool: "nika:image_fx"
      args:
        input: "${{ with.src }}"
        out: out/hero-gameboy.png
        seed: 42                  # the seed IS the style — same seed, same bytes
        ops:
          - resize: { width: 320 }
          - dither: { mode: floyd_steinberg, palette: gameboy }
          - grain: { intensity: 32 }
          - scanlines: { strength: 110, period: 4 }
          - vignette: { strength: 140 }
```

Run it twice: the second run reports `skipped_existing: true` and the artifact
hash never moves. Mutate one byte of the PNG and a re-render no longer matches
— that mismatch *is* the tamper detection.

## The op vocabulary (closed · v1)

`ops:` is an **ordered list of single-key maps** — a linear pipeline by design.
Branching and fan-out belong to the workflow (`with:`/`after:` edges ·
`for_each`), never inside the builtin.

| Op                     | What it does                                    | Key knobs                                                                                   |
| ---------------------- | ----------------------------------------------- | ------------------------------------------------------------------------------------------- |
| `resize`               | Linear-light resample                           | `width`/`height` (one may be omitted) · `filter: auto\|nearest\|bilinear`                   |
| `crop`                 | Exact rectangle                                 | `x` · `y` · `width` · `height`                                                              |
| `levels`               | Brightness / contrast                           | `brightness` −255..255 · `contrast` −128..128                                               |
| `grayscale`            | Linear-light luma                               | —                                                                                           |
| `palette_map`          | Nearest palette color (Oklab distance)          | `palette`                                                                                   |
| `dither`               | Quantize through a dither                       | `mode: bayer2\|bayer4\|bayer8\|blue_noise\|ign\|floyd_steinberg\|atkinson\|jjn` · `palette` |
| `duotone`              | Two-stop gradient map (Oklab ramp)              | `dark` · `light` (`#rrggbb` or `[r,g,b]`)                                                   |
| `pixelate`             | Block mosaic                                    | `block` 2..256                                                                              |
| `halftone`             | Rotated clustered-dot screen (print look)       | `cell` 3..64 · `angle: 0\|15\|45\|75`                                                       |
| `grain`                | Luminance-shaped film grain (seeded)            | `intensity` 0..128                                                                          |
| `vignette`             | Natural cos⁴ falloff                            | `strength` 0..255                                                                           |
| `chromatic_aberration` | Per-channel radial split                        | `shift` 1..16                                                                               |
| `scanlines`            | CRT row darkening                               | `strength` 0..255 · `period` 2..64                                                          |
| `glitch`               | Seeded databending                              | `line_shift` ≤64 · `channel_shift` ≤16 · `blocks` ≤64                                       |
| `ascii`                | Character-grid render — **must be the last op** | `cols` 2..1024 · `emit: png\|text\|ansi`                                                    |

Palettes: presets `bw · gray4 · gameboy · cga · okabe_ito`, or an inline list
of 2–256 colors. Unknown op parameters are **rejected loudly**
(`NIKA-BUILTIN-IMAGE_FX-001`) — a typo'd knob never silently lies about the
style.

<Warning>
  Input is **PNG in v1** (depth 8 · no interlace). Non-PNG fails with a typed
  hint: produce PNG upstream (`image_generate` with `format: png`) or convert
  once via `exec:`. Decode is budget-gated from the header **before** any
  decompression — hostile dimension claims are rejected, never allocated.
</Warning>

## Why deterministic styling matters

Every incumbent styling path is nondeterministic by default — image tools
timestamp their outputs, and generative models can't reproduce bytes across
hardware at all. That makes styled assets un-verifiable: you can sign them,
but you can't *re-derive* them.

`image_fx` inverts that: integer/fixed-point pixel math, a seeded noise
stream, zero wall-clock. So the artifact can be:

* **chained** — its sha256 lands in the trace (`nika trace verify` covers it);
* **re-rendered** — the same input + the recipe reproduces the exact bytes;
* **carried** — the recipe rides the artifact itself, so any holder of the
  input can verify the styling.

One recipe, one hash, forever. Batch-style a hundred campaign images with
`for_each` and every one of them is a receipt.

```yaml theme={"system"}
  variants:
    with:
      src: ${{ tasks.generate.output.images[0].path }}
    for_each: ["bw", "gameboy", "cga"]
    invoke:
      tool: "nika:image_fx"
      args:
        input: "${{ with.src }}"
        out: "out/variant-${{ item }}.png"
        ops:
          - dither: { mode: bayer4, palette: "${{ item }}" }
```

## Output contract

```json theme={"system"}
{
  "input": "out/hero.png",
  "input_sha256": "…",
  "path": "out/hero-gameboy.png",
  "sha256": "…",
  "size_bytes": 323953,
  "width": 320,
  "height": 200,
  "format": "png",
  "ops_applied": 5,
  "seed": 42,
  "skipped_existing": false
}
```

Artifact bytes never ride outputs (the disk law). Text artifacts (`ascii` with
`emit: text|ansi`) land as `.txt`/`.ans`, report `width`/`height` `0`, and are
sha256'd like any other artifact.

Errors are typed `NIKA-BUILTIN-IMAGE_FX-001..006` — invalid args · input read
· unsupported format · decode · pixel budget · save — plus the boundary
`NIKA-SEC-004` when a path resolves outside `permits.fs`.


# Image generation
Source: https://docs.nika.sh/guides/image-generation

Render images inside workflows — local server first, four more providers one line away, every save permit-gated, every asset provenance-carrying.

`nika:image_generate` treats images as workflow citizens: the same declared
`permits:` boundary that gates file writes gates every save, real spend lands
in the run ledger, and provenance is structural — in the manifest beside the
asset *and* inside the PNG itself.

![One workflow renders through any of five image providers — local server first; the run meters \$0.02 exactly; the asset lands sha256-named with a provenance manifest beside it](https://raw.githubusercontent.com/supernovae-st/nika/main/media/gifs/image-pipeline.gif)

## The five providers

| provider | default model            | wire                              | what to know                                                                                                                                                                                          |
| -------- | ------------------------ | --------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `local`  | `stablediffusion`        | your server's OpenAI-images route | The sovereign path. One wire covers LocalAI (`:8080`), Ollama (`:11434`), stable-diffusion.cpp `sd-server` (`:1234`), SGLang Diffusion and vLLM-Omni. Never inferred from `model:` — always explicit. |
| `openai` | `gpt-image-2`            | Images API                        | Exact sizes (`WxH`), native `n`, `background: transparent`, webp/jpeg `compression`.                                                                                                                  |
| `gemini` | `gemini-3.1-flash-image` | `generateContent`                 | Aspect-ratio classes; may return an interleaved caption (surfaced as `provider_text`, clamped).                                                                                                       |
| `xai`    | `grok-imagine-image`     | Imagine API                       | Native aspect ratios + `resolution: 1k\|2k` classes; the `-quality` model tier is the quality knob; **bills exact cost into the run ledger**.                                                         |
| `mock`   | `mock-image-1`           | in-process                        | Real, decodable, deterministic PNG files — zero network, zero keys. CI runs the whole pipeline offline.                                                                                               |

Keys and the local URL are **engine config, never workflow args**:
`OPENAI_API_KEY` / `GEMINI_API_KEY` / `XAI_API_KEY` (or `NIKA_`-prefixed),
`NIKA_IMAGE_LOCAL_URL` (+ optional `NIKA_IMAGE_LOCAL_API_KEY`). Check what's
wired with `nika doctor` — it prints an `image` line naming the ready
providers.

## Sovereign quickstart (local server)

```bash theme={"system"}
# LocalAI (first-party spec-complete compat route · :8080)
docker run -p 8080:8080 localai/localai:latest

# …or Ollama (macOS · experimental image generation · :11434)
export NIKA_IMAGE_LOCAL_URL=http://localhost:11434

# …or stable-diffusion.cpp's server (:1234)
export NIKA_IMAGE_LOCAL_URL=http://localhost:1234
```

```yaml nika: v1 theme={"system"}
workflow:
  id: og-hero-sovereign
permits:
  fs: { write: ["./assets/**"] }
  tools: ["nika:image_generate"]
tasks:
  hero:
    invoke:
      tool: "nika:image_generate"
      args:
        provider: local
        model: "x/z-image-turbo"        # model names are server-specific
        prompt: "OG hero — a monarch butterfly over a nebula"
        aspect_ratio: "16:9"
        output_dir: "./assets/og"
```

The engine forces `response_format: b64_json` (LocalAI defaults to URL mode),
refuses url-only answers (**result URLs are never fetched** — that would
reopen the SSRF surface the fixed-endpoint design closed), and gives local
renders a 300s default timeout — CPU diffusion runs minutes, raise
`timeout_ms:` up to 600000 when needed. SD-family servers honor a
`positive | negative` prompt split written directly inside `prompt:`.

## What lands on disk

```
assets/og/
├── hero-local-x-z-image-turbo-0-9ec15c15.png        # sha256-named
└── hero-local-x-z-image-turbo-66a35545.manifest.json
```

The **manifest** carries the resolved request, per-image sha256 + dimensions,
`endpoint_host` (which server actually rendered it), timing, warnings,
`cost_usd`, and your `metadata:` fields — never a credential, by construction.

The **PNG itself** carries a `nika` tEXt chunk (tool, engine version,
provider, model, prompt, seed) — so provenance survives `cp`, the practice
ComfyUI and InvokeAI standardized. Read it back with any PNG tool:

```bash theme={"system"}
python3 -c "import png"  # or: exiftool asset.png | grep -i nika
```

## Content credentials (detect-and-preserve)

OpenAI and Google **sign their API bytes** with C2PA Content Credentials —
and C2PA hashes the file's byte ranges, so any pipeline that writes into a
signed render converts valid credentials into *« present but tampered »*.
Nika detects the signals first (PNG `caBX` · JPEG APP11 JUMBF · RIFF
`C2PA` · MP3 GEOB): on signed payloads the `nika` tEXt embed **stands
down** (their signed manifest outranks our informal chunk — a loud
`content_credentials_preserved:` warning says so), and the output +
manifest surface `content_credentials: "c2pa"` plus `watermark_declared`
(SynthID is a provider fact — only the vendor can detect it). Detection
labels only: the wire never says « verified ». With EU AI Act Article 50
in force from **2026-08-02**, preserving machine-readable marks is part of
an operator's compliance surface — no other workflow engine even looks.

## Honesty rules (what the warnings mean)

Every lossy mapping is a **stable, visible warning** — silent degradation is
non-conformant per the spec:

* `count_shortfall:` — the provider returned fewer than `n:` (Ollama's compat
  route ignores `n`, moderation can filter variants).
* `size_conflict:` · `xai_size_class:` · `aspect_remapped:` — your exact size
  was folded to the provider's nearest class, loudly.
* `seed_unsupported:` · `quality_folded:` · `compression_ignored:` — the knob
  doesn't exist on that provider; the arg was dropped, visibly.
* `format_mismatch:` — fires only when you *explicitly* asked for a format
  the provider didn't honor; magic bytes name the real extension either way.

## Real spend in the ledger

xAI bills images in cost ticks — the engine converts them exactly and the
render's cost rides the task line, the run total, and the manifest:

```
✔  render  invoke · nika:image_generate  5.6s · $0.02
── 1/1 done · $0.02 · elapsed 5.6s ──────────────────
```

Any invoke tool reporting a top-level `cost_usd` in its structured output is
metered the same way. Providers that don't report exact cost show `null` —
never an estimate dressed as truth.

## Cookbook (each proven end-to-end against live APIs)

**An LLM writes the brief, another provider renders it:**

```yaml nika: v1 theme={"system"}
workflow:
  id: brief-to-image
model: gemini/gemini-2.5-flash
permits:
  fs: { write: ["./out/**"] }
  tools: ["nika:image_generate"]
tasks:
  brief:
    infer:
      prompt: "Write a vivid one-sentence OG-image brief for a post about local-first AI. Pick the ratio."
      schema:
        type: object
        required: [brief, aspect_ratio]
        properties:
          brief: { type: string }
          aspect_ratio: { type: string, enum: ["1:1", "16:9", "4:3"] }
  render:
    with:
      brief: ${{ tasks.brief.output.brief }}
      ratio: ${{ tasks.brief.output.aspect_ratio }}
    invoke:
      tool: "nika:image_generate"
      args:
        provider: xai
        prompt: "${{ with.brief }}"
        aspect_ratio: "${{ with.ratio }}"
        output_dir: "./out"
```

**Fan out one hero across locales (concurrent, one output dir):**

```yaml theme={"system"}
  hero:
    for_each: ${{ const.locales }}      # ["fr", "es", "ja"]
    max_parallel: 3
    with: { locale: ${{ item }} }
    invoke:
      tool: "nika:image_generate"
      args:
        provider: mock                   # flip to local/gemini/openai/xai
        prompt: "launch hero, locale ${{ with.locale }}"
        output_dir: "./out"
        filename_prefix: "hero-${{ with.locale }}"
```

**Let an agent decide the arguments** (the model reads the tool definition):

```yaml theme={"system"}
  designer:
    agent:
      prompt: >
        Generate exactly one minimalist butterfly logo using the image tool
        (provider xai, aspect_ratio 1:1, output_dir ./out), then call done
        with the saved path.
      tools: ["nika:image_generate", "nika:done"]
      max_turns: 4
```

**Retry transient failures** (a local server still loading its model):

```yaml theme={"system"}
  render:
    retry:
      max_attempts: 3
      on_codes: ["NIKA-BUILTIN-IMAGE_GENERATE-003"]
    invoke:
      tool: "nika:image_generate"
      args: { provider: local, prompt: "…", output_dir: "./out" }
```

## Why this design (versus every other engine)

No other workflow engine permit-gates image saves, verifies returned bytes
against declared MIME types, writes a provenance manifest with the resolved
request, refuses to fetch result URLs, or ships a local-first provider — and
none embed provenance in the file itself (that practice comes from the
image-native world). The full comparison lives in the
[builtins reference](/reference/builtins#media).

## Editing (`mode: edit`)

An input image plus an instruction — the same builtin, one arg away:

```yaml theme={"system"}
  night:
    with:
      src: ${{ tasks.render.output.images[0].path }}   # edit what you generated
    invoke:
      tool: "nika:image_generate"
      args:
        provider: openai            # the first edit wire · gemini/xai/local follow
        mode: edit
        image: ${{ with.src }}
        prompt: "make it night — starry sky"
        output_dir: "./out"
```

The rules mirror generation, inverted where reading demands it:

* **Reads are permit-gated.** Every `image:`/`images:`/`mask:` path is
  enforced against `permits.fs.read` *before* a byte is read — the exact
  mirror of the save boundary. Edit reads what generate writes, so a
  generate→edit chain declares both `read:` and `write:`.
* **`image:` XOR `images:`** — one source or many (capped per provider:
  openai 16 · gemini 14 · xai 3), 20 MB each, magic-byte sniffed.
* **A `mask:` is refused, never dropped**, on providers that edit by
  instruction only (gemini/xai): a silently-ignored mask edits the wrong
  region. openai (and local inpaint) take pixel masks.
* **The provenance chain survives.** The manifest carries `mode: "edit"`
  plus `source_images: [{path, sha256, format}]` — an edited asset records
  exactly what it derived from.

<Note>
  `reference_images:` (compose-from-references) and `save: false` remain
  reserved — refused loudly rather than pretended.
</Note>


# Local models
Source: https://docs.nika.sh/guides/local-models

Get a model onto your machine in one command: Ollama, any Hugging Face GGUF, LM Studio, llama.cpp or vLLM. Nothing leaves your laptop.

Nika is local-first: point `model:` at a local server and your data never
leaves the machine. This page is the ladder, from the one-command path to
production servers.

## 1. The one-command path: Ollama

Install [Ollama](https://ollama.com), then:

```bash theme={"system"}
ollama pull llama3.2:3b
```

That's it. In any workflow:

```yaml theme={"system"}
model: ollama/llama3.2:3b
```

`nika doctor` confirms the wiring (it detects the running Ollama server and
prints the exact fix if something is off).

<Tip>
  `llama3.2:3b` is the showcase default: small enough for most laptops,
  good enough for structured extraction. Swap the tag for anything in the
  [Ollama library](https://ollama.com/library): `qwen2.5`, `mistral`,
  `phi4`, larger llama variants.
</Tip>

## 2. Any Hugging Face GGUF, still one command

Ollama pulls directly from the Hugging Face Hub. Any public GGUF repo
works, no account needed:

```bash theme={"system"}
ollama run hf.co/bartowski/Llama-3.2-3B-Instruct-GGUF
```

Pick a quantization explicitly with a tag:

```bash theme={"system"}
ollama run hf.co/bartowski/Llama-3.2-3B-Instruct-GGUF:Q4_K_M
```

Then reference it in the workflow exactly as pulled:

```yaml theme={"system"}
model: ollama/hf.co/bartowski/Llama-3.2-3B-Instruct-GGUF:Q4_K_M
```

Rule of thumb for quantizations: `Q4_K_M` is the sane default (quality per
GB), `Q8_0` when you have RAM to spare, `Q2/Q3` only when memory is tight.
The [Hub's GGUF filter](https://huggingface.co/models?library=gguf) lists
every compatible repo.

## 3. LM Studio: the visual browser

Prefer a GUI? [LM Studio](https://lmstudio.ai) browses Hugging Face,
downloads models with a click, and serves an OpenAI-compatible endpoint.
Start its server, then:

```yaml theme={"system"}
model: lmstudio/<the-model-id-shown-in-lm-studio>
```

## 4. Servers: llama.cpp and vLLM

For shared machines and production:

* [llama.cpp](https://github.com/ggml-org/llama.cpp) `llama-server` serves
  any GGUF: `model: llamacpp/<model>`
* [vLLM](https://docs.vllm.ai) serves full-precision Hub models at
  datacenter throughput: `model: vllm/<hub-repo-id>`

Both speak the same OpenAI-compatible dialect; the prefix picks the
provider, nothing else in the file changes.

## Checking what's wired

```bash theme={"system"}
nika doctor
```

Doctor reports every provider (local servers detected, cloud keys present)
with a fix-form per missing piece. The audit before a run prices local
models at \$0.000:

```bash theme={"system"}
nika check my-workflow.nika.yaml
```

## Thinking time is budgeted for

A local thinking model legitimately needs minutes for one completion on
consumer hardware — well past the 30s a cloud round-trip expects. Nika's
provider deadlines are **per class**: local providers (`ollama`, `lmstudio`,
`llamacpp`, `localai`, `vllm`) get **≥ 300s by default**, cloud providers
30s. No 30s-everywhere default silently kills a local run mid-think.

When a task needs more than the default, the task's own `timeout:` governs
the provider deadline directly:

```yaml theme={"system"}
deep_review:
  timeout: "7m"                # Go-duration · bounds the task AND the provider call
  infer:
    prompt: "Review this diff…"
```

Full semantics (per-class defaults, the 600s silent-connection ceiling,
streaming): [YAML reference · Timeouts](/reference/yaml-syntax#timeouts).

## Swapping between local and cloud

The file does not change shape. One line moves the workflow between a
laptop and an API:

```yaml theme={"system"}
model: ollama/llama3.2:3b        # local · free · private
# model: mistral/mistral-small   # EU cloud
# model: anthropic/claude-haiku-4-5
```

<Note>
  The permits boundary applies either way: a `permits:` block with no
  `net.http` entry means the workflow cannot reach the network even if the
  model could. Local model + closed permits = fully air-gapped AI work.
</Note>

## Read next

<CardGroup>
  <Card title="Providers" icon="server" href="/concepts/providers">
    The full catalog and how one InferRequest speaks every dialect.
  </Card>

  <Card title="First workflow" icon="play" href="/getting-started/first-workflow">
    Five minutes from install to a checked, runnable file.
  </Card>

  <Card title="Model bench" icon="scale-unbalanced" href="/examples/model-bench">
    Pick your default local model on a measured table, not vibes.
  </Card>

  <Card title="Cost honesty" icon="coins" href="/guides/cost-honesty">
    Why a local run is unpriced — never « free » — and how floors work.
  </Card>
</CardGroup>


# Watch a run
Source: https://docs.nika.sh/guides/observability

Three moments to look at a workflow: inspect the waves before, read the live render during, and the waterfall + verdict card after.

A run answers three questions at three different times: *what will
happen?* (before), *what is happening?* (during), *what happened?*
(after). One command each, all offline-friendly — every frame below is
real output from this workflow:

```yaml standup-digest.nika.yaml theme={"system"}
nika: v1
workflow:
  id: standup-digest
  description: "Pull commits and tickets in parallel, then digest."

model: mock/echo                       # swap for ollama/llama3.2:3b or any provider

permits:
  exec: true                           # both probes are shell strings · only the argv form takes an allowlist

tasks:
  commits:
    exec:
      shell: "sleep 0.4 && git log --oneline -5 2>/dev/null || printf 'feat: resume'"

  tickets:
    exec:
      shell: "sleep 0.3 && printf 'NIKA-42 open'"

  digest:
    with:
      commits: ${{ tasks.commits.output }}
      tickets: ${{ tasks.tickets.output }}
    infer:
      prompt: "Digest commits ${{ with.commits }} and tickets ${{ with.tickets }}"
      max_tokens: 400

outputs:
  digest: "${{ tasks.digest.output }}"
```

## Before · `nika inspect`

Static anatomy: the DAG's **wave groups** (what runs in parallel), plus
three planning lines — the parallelism width, the pinch points, and each
task's blast radius. Zero execution, zero tokens:

```text theme={"system"}
$ nika inspect standup-digest.nika.yaml
standup-digest · 3 tasks · 2 waves · ≥ $0.0000 (floor — unbounded tasks)
  ╭ wave 1 ── 2 in parallel ─╮
  │ ◆ commits  exec          │
  │ ◆ tickets  exec          │
  ╰──────────────────────────╯
    ↓
  ◆ digest   infer · mock/echo
  (no orphans · DAG check NIKA-DAG-001 clean)

parallelism  width 2 · can run together: commits · tickets
pinch        digest · nothing else runs while these run
blast        commits blocks 1 · tickets blocks 1
```

Read it before a long run the way you read a query plan before an
expensive query.

## During · the live render

In an interactive terminal, `nika run` animates a storyboard: tasks
light up as their dependencies clear, in the wave order `inspect`
predicted. Piped (CI logs, `tee`), the same run prints one plain,
deterministic frame instead — `∥` marks tasks that ran in parallel:

```text theme={"system"}
$ nika run standup-digest.nika.yaml
  🦋 nika · standup-digest · 3 tasks
     permits ✓ declared boundary · default-deny

  ✔  commits  exec · sleep  428ms
  ✔  tickets  exec · sleep  313ms ∥
  ✔  digest   infer · mock/echo  0ms
  ── 3/3 done · ≥ $0.00 (1 unpriced) · elapsed 0.4s ──────────────
    trace: .nika/traces/2026-07-28T06-58-44Z-bb6e.ndjson · 15 events · chain b35e86afcb024cab8b17cc0c7701d99034ecf5aa70ab4fc5e28d6225933b13be
```

Four render modes, one per audience:

| Flag               | Surface                                                                                              |
| ------------------ | ---------------------------------------------------------------------------------------------------- |
| *(none, terminal)* | Live animated storyboard, then waterfall + verdict card                                              |
| `--no-progress`    | One plain final frame (the CI-stable surface · default when piped)                                   |
| `--quiet`          | The final verdict line only — `✔  standup-digest · 3 tasks · 0.4s · ≥ $0.00 (1 unpriced)`            |
| `--json`           | Pure NDJSON events on stdout, progress to stderr (the machine lane · see [Traces](/concepts/traces)) |

## After · the waterfall and the verdict card

An interactive run ends with two frames. The **waterfall** shows where
the wall-clock went — overlapping bars are the parallelism you actually
got. The **verdict card** compresses the run into one box: the wave
shape (`◆◆ ⇉ ◆` — two in parallel, then one), tasks, waves, retries,
duration, cost (its `≥`/`unpriced` grammar is the
[cost-honesty vocabulary](/guides/cost-honesty)), model, and the typed
outputs it produced:

```text theme={"system"}
  commits  ▕██████████████████████████████████▏  416ms
  tickets  ▕         █████████████████████████▏  305ms
  digest   ▕                                 █▏    0ms
  0s ···································· 417ms
  ╭─ nika ✓ standup-digest ───────────────────╮
  │  ◆◆ ⇉ ◆    3 tasks · 2 waves · 0 retries  │
  │  418ms · $0.0000 · mock/echo              │
  │  outputs → digest (string)                │
  ╰───────────────────────────────────────────╯
```

The same frames are recoverable from any recorded trace, hours or
machines later:

```bash theme={"system"}
nika run standup-digest.nika.yaml --json > .nika/traces/standup.ndjson

nika trace show   .nika/traces/standup.ndjson   # storyboard + waterfall + verdict card
nika trace replay .nika/traces/standup.ndjson   # re-render the run live · never re-execute
```

`trace show` prints the final frames; `trace replay` plays the recorded
events through the same renderer that drew the original run. Replay
calls no model and runs no command — it is a projection of what already
happened ([Traces & replay](/concepts/traces)).

## Export to your tracing stack · OTLP

A recorded trace projects to OTLP/JSON lines, so any OpenTelemetry
viewer becomes a Nika run viewer — no collector, no daemon, no vendor:

```bash theme={"system"}
nika trace export .nika/traces/standup.ndjson
# → .nika/traces/standup.otlp.jsonl  (one OTLP span per line)

nika trace export .nika/traces/standup.ndjson -o run.otlp.jsonl   # choose the path
```

Each verb becomes a span (duration, tokens, the ADR-099 identity
hashes). Drag the file into the Jaeger UI (≥ 1.60), or POST the lines to
any OTLP/HTTP endpoint (Grafana Tempo, Langfuse, your own collector).
Task outputs stay **local** by default; `--include-content` widens the
exported file to carry them as span attributes when you explicitly want
them. The export is a projection of the journal — it never re-runs
anything.

## Terminals & CI

The live surfaces are TTY-only by design. Piped or `NO_COLOR` output is
the sober register (plain per-line events — what CI logs want). Two
render themes ship: unicode (default) and `--ascii` (every glyph has an
ASCII twin — use it on terminals without good box-drawing fonts,
including older Windows setups; Windows Terminal renders the default
theme fine). `--color never` (or `--plain`), `NO_COLOR`, and
`CLICOLOR_FORCE` follow the standard resolution order — one global
colour chain, no per-verb twins.

## Related

* [Concepts · Traces](/concepts/traces): the NDJSON event stream behind
  every frame on this page.
* [Guides · Resume](/guides/resume): the same trace doubles as a
  checkpoint — `--resume` skips completed work with visible cache hits.
* [Reference · CLI](/reference/cli): every render flag.


# How to write Nika
Source: https://docs.nika.sh/guides/patterns

The twelve patterns of well-written Nika: each one taught by a canonical example, each anti-pattern named.

Nika is a small language ( verbs,&#x20;
namespaces, one expression surface), so good Nika is mostly about
shape: where the determinism lives, where the model is allowed to
think, and how data crosses task boundaries. These twelve patterns are
how the  showcase workflows are written. Each links
the canonical example that embodies it.

<Tip>
  The spec's normative cousin of this page is the
  [one-obvious-way table](https://github.com/supernovae-st/nika-spec/blob/main/spec/03-dag.md)
  (linter rules `one-obvious-way/002-007` + `/010` — `/001` is retired,
  rule ids are never reused). This page is the engineering judgment
  *around* those rules.
</Tip>

## 1 · Deterministic core, model at the edges

jq decides; the model explains. Anything that can be computed
(filtering, sums, diffs, ranking) happens in `nika:jq` or a data
builtin, deterministically and for free. The model gets the jobs only
a model can do: judgment, language, synthesis.

```yaml theme={"system"}
# ✅ jq filters · the model only explains what survived
urgent:
  with:
    tickets: ${{ tasks.triage.output.tickets }}
  invoke:
    tool: "nika:jq"
    args: { input: "${{ with.tickets }}", expression: 'map(select(.urgency == "critical"))' }
explain:
  with:
    urgent: ${{ tasks.urgent.output }}
  when: ${{ size(with.urgent) > 0 }}
  infer: { prompt: "Explain these critical tickets · ${{ with.urgent }}" }
```

**Anti-pattern** · asking the model to « pick the urgent ones » from a
list it already returned typed. You pay tokens for worse determinism.

Taught by · [Price watch](/examples/price-watch) (zero model calls) ·
[Config drift sentinel](/examples/config-drift-sentinel) ·
[ETL quarantine](/examples/etl-quarantine).

## 2 · Parallelism is the default · edges are the only ordering

Tasks with no edge between them run together. Don't serialize out of
habit: a `with:` binding IS the data edge (data and dependency are one
declaration) and an `after:` entry is the control edge — the engine
computes the graph from those two doors and schedules the waves. The
DAG has no invisible edges: a `tasks.*` reference outside the boundary
is `NIKA-VAR-021` (the fix is machine-applicable — hoist into `with:`).

**Anti-pattern** · a linear chain of tasks that never read each
other's output. That is wall-clock spent on nothing.

Taught by · [Standup digest](/examples/standup-digest) ·
[Social repurpose](/examples/social-repurpose) (the diamond) ·
[CEO Monday brief](/examples/ceo-monday-brief) (3-branch gather).

## 3 · Type the boundaries

Every place data crosses from a model into the deterministic world gets
a contract: `schema:` on `infer`/`agent` (the model must return that
shape), `nika:validate` for second opinions, `nika:assert` as the hard
gate. Enums kill « kinda-strong » ratings.

**Anti-pattern** · prose in, prose out, regex in the middle. If a
downstream task indexes into a field, the producer needs a schema.

Taught by · [Meeting actions](/examples/meeting-actions) ·
[Contract guard](/examples/contract-guard) (schema + validate + assert,
belt-and-braces) · [Support triage](/examples/support-triage) (enums).

## 4 · Fan out with a leash

`for_each` over a runtime collection is the power move. Bound it with
`max_parallel` (providers rate-limit, GPUs thrash), make it resilient
with `fail_fast: false` (collect errors instead of aborting the batch)
and give each iteration its own `retry` and `timeout`.

**Anti-pattern** · an unbounded fan-out against a rate-limited API, or
leaving `fail_fast` on its default (true) for a batch where one bad
item is normal.

Taught by · [Competitor radar](/examples/competitor-radar) ·
[Localization factory](/examples/localization-factory) ·
[Resume screener](/examples/resume-screener).

## 5 · Plan, then execute

For open-ended work: a fast model writes a typed plan, an `agent:`
executes it under budgets, a thinking model synthesizes. Three stages,
three cost profiles, every intermediate auditable on disk.

**Anti-pattern** · one giant agent loop with no plan, no budget and no
typed output. Nothing about it can be audited or bounded.

Taught by · [Deep research brief](/examples/deep-research-brief).

## 6 · Three gates, three meanings

* `when:` · the **skip** gate. Routing, not failure (skipped ≠ failed).
* `nika:assert` · the **fail-fast** gate. The run is wrong, stop loudly.
* `nika:prompt` · the **human** gate. Blocks until a person decides.

Pick the gate that matches the meaning. A workflow that sends drafts
without a `prompt` gate, or claims success without an `assert`, is
promising more than it checks.

**Anti-pattern** · a `tasks.*` status test inside `when:` as a plain
success gate. That form is illegal since W2 (`NIKA-VAR-021`): the gate
lives on the edges — a value edge already admits on `{success, skipped}`,
and `after: { a: success }` is the strict form. `when:` decides
*business* conditions on local values, post-gate.

Taught by · [Invoice chaser](/examples/invoice-chaser) (human gate) ·
[Incident war room](/examples/incident-war-room) (assert refuses
optimistic postmortems) · [Release train](/examples/release-train)
(all three in one file).

## 7 · Sovereignty is a `model:` line

Sensitive data (contracts, CVs, medical, financial) runs on a local
provider, `ollama/…` or `lmstudio/…`. Same file shape, zero cloud. The
&#x20;canonical providers make this a one-line decision,
not an architecture meeting.

Taught by · [Contract guard](/examples/contract-guard) ·
[Resume screener](/examples/resume-screener).

## 8 · Agents get budgets, tools get grants

`agent:` is default-deny: no `tools:` means no tools at all. Grant the
minimum (`nika:read` + `nika:done` makes a read-only reviewer), cap
the loop (`max_turns` · `max_tokens_total`), and let `nika:done` end
it cleanly.

**Anti-pattern** · `tools: ["nika:*", "mcp:*/*"]` on an agent that
only needed to read. Least privilege costs one line less.

Taught by · [PR review fan-out](/examples/pr-review-fanout) (the
read-only swarm) · [Code review](https://github.com/supernovae-st/nika-spec/blob/main/examples/23-code-review.nika.yaml)
(foundation).

## 9 · Evidence always lands · `on_finally`

Two tools, one rule. **`on_finally:`** is per-task cleanup: it fires
when that task *ran* (success, failure, timeout, mid-flight cancel).
**A terminal `after: {…: terminal}` task** is the always-pattern: it
runs once its producers settle, whatever happened — `terminal` admits
every terminal state (success · failure · skipped · cancelled). Pair it
with a `.status` observation in `with:` when the body branches on the
outcome. Cleanup belongs to the task; the record that must land at 3am
belongs to a terminal task.

Taught by · [Incident war room](/examples/incident-war-room) ·
[Release train](/examples/release-train) (the departure record is an
`after: { live: terminal }` task: it lands even when the train aborts).

## 10 · One data language · jq, once

`output:` bindings, `nika:jq`, the fan-in zip (`transpose`), the
state diff: all of it is the same jq. Don't invent per-task string
parsing and don't ask the model to reshape JSON. One transform
language is already there.

Taught by · [Localization factory](/examples/localization-factory)
(the transpose zip) · [ETL quarantine](/examples/etl-quarantine)
(group\_by accounting).

## 11 · Workflows are callable · type the `outputs:`

A workflow with typed `outputs:` is a building block: another workflow
(or a human, or CI) consumes a contract, not a log. Name what comes
out, type it, describe it.

Taught by · [Deep research brief](/examples/deep-research-brief)
(`{brief, sources}`) · [Schema retry](https://github.com/supernovae-st/nika-spec/blob/main/examples/19-schema-retry.nika.yaml)
(foundation · the typed-outputs shape).

## 12 · Mock-first · runnable with zero keys

`model: mock/echo` makes a workflow CI-runnable and demo-safe. Write
it mock-first and swap the provider when it ships. Every example in
this documentation that can run without keys does.

**Anti-pattern** · a workflow you can't validate without spending real
tokens. The conformance gate runs every example on every push, and
yours should pass the same way.

Taught by · the whole [examples pack](/examples/overview), and the
[state-file pattern](/examples/release-radar) makes even stateful
workflows replayable.

***

## The shape of a well-written file

```yaml the shape · a skeleton, not a runnable file theme={"system"}
nika: v1                      # the contract · one line · forever
workflow:
  id: kebab-case-name     # resource name
  description: "…"              # one honest sentence

model: mock/echo              # mock-first · sovereignty is one line away

inputs:                       # typed · what the CALLER supplies · required: true documents itself
config:                       # typed · the DEPLOYMENT's dials · may appear in logs
const:                        # fixed in the file · the destinations the boundary pins
secrets:                      # vault/env-backed · never inline

permits:                      # the blast radius · absent = zero authority

tasks:                        # the DAG · true dependencies only ·
  # deterministic core (jq · builtins) · model at the edges ·
  # gates that match their meaning · leashed fan-outs · budgeted agents

outputs:                      # the callable contract · typed
```

***

## Four recipes the patterns compose into

The 12 patterns are the values; these are the moves you reach for when a
real integration pushes back. Each is canonical in the spec: linked, not
improvised.

### Poll until ready

`retry:` fires on errors, never on values, so make « not ready » an error
*inside* the task. A jq-mode fetch whose program errors on the pending shape
turns polling into typed, bounded retry:

```yaml theme={"system"}
await_export:
  invoke:
    tool: "nika:fetch"
    args:
      url: "https://api.example.com/jobs/${{ inputs.job_id }}"
      mode: jq
      jq: 'if .status == "done" then . else error("not ready") end'
  retry:
    max_attempts: 20
    backoff_strategy: fixed
    backoff_ms: 30000          # every 30s · 20 attempts · 10-minute ceiling
```

Bounded, deterministic, zero LLM. (`retry_when:`, retrying on a value
condition directly, is reserved for a future minor.)

### Diamond join

Two exclusive `when:` branches, one consumer. A skipped branch's output is
**defined `null`** (never an error), so the join is one jq filter:

```yaml theme={"system"}
pick:
  with:                          # value edges pass on skipped · the skipped one reads null
    prod: ${{ tasks.build_prod.output }}
    dev: ${{ tasks.build_dev.output }}
  invoke:
    tool: nika:jq
    args:
      input: [ "${{ with.prod }}", "${{ with.dev }}" ]
      expression: "[ .[] | select(. != null) ] | first"
```

### Fan-out that survives partial failure

A failed iteration contributes `null` at its index: positions stay aligned
with the input. Recover per-iteration when a placeholder is acceptable,
filter downstream. The same `on_error: recover:` mechanism also degrades a
single task to a declared fallback — the run completes and the output says
what it is:

<video>
  <source type="video/webm" />

  <source type="video/mp4" />
</video>

```yaml theme={"system"}
scrape_all:
  with:
    pages: ${{ tasks.discover.pages }}
  for_each: ${{ with.pages }}
  max_parallel: 5
  fail_fast: false
  on_error: { recover: null }        # this iteration yields null · the batch lives
  invoke:
    tool: "nika:fetch"
    args: { url: "${{ item }}", mode: article }

digest:
  with:
    scraped: ${{ tasks.scrape_all.output }}
  invoke:
    tool: nika:jq
    args:
      input: ${{ with.scraped }}
      expression: "[ .[] | select(. != null) ]"   # the survivors · order preserved
```

### Matrix expansion

A matrix is precomputed data, not control flow. Build the product with jq,
fan out over it:

```yaml theme={"system"}
build_matrix:
  invoke:
    tool: nika:jq
    args:
      input: { os: ["linux", "macos"], ver: ["18", "20", "22"] }
      expression: "[ .os[] as $o | .ver[] as $v | {os: $o, ver: $v} ]"

test_all:
  with:
    matrix: ${{ tasks.build_matrix.output }}
  for_each: ${{ with.matrix }}
  max_parallel: 3
  exec:
    command: ["./test.sh", "--os", "${{ item.os }}", "--node", "${{ item.ver }}"]
```

Include/exclude rules are jq filters on the product: no second syntax to
learn.

<Card title="See every pattern live" icon="rocket" href="/examples/overview">
  The examples gallery:  real jobs, every construct taught,
  every file conformance-validated.
</Card>


# Resume a run
Source: https://docs.nika.sh/guides/resume

The trace is the checkpoint: nika run --resume skips completed work with visible cache hits, and a human gate can pause a run durably.

A long run dies at task 7 of 9 — laptop lid, ctrl-C, a provider hiccup.
With most tools that is 7 tasks of tokens re-spent. With Nika the run's
own trace is the checkpoint: **`--resume` re-executes the workflow,
skipping every task whose recorded work is still valid** (ADR-099).
No daemon, no run store, no new artifact — the reader of a file you
already have.

## Record, then resume

```yaml release-notes.nika.yaml theme={"system"}
nika: v1
workflow:
  id: release-notes
  description: "Collect commits, draft notes, stamp a file."

model: mock/echo                       # swap for ollama/llama3.2:3b or any provider

permits:
  exec: ["printf"]                     # the only program either task launches

tasks:
  collect:
    exec:
      command: ["printf", "feat: resume\nfix: deadline"]

  draft:
    with:
      commits: ${{ tasks.collect.output }}
    infer:
      prompt: "Draft release notes from: ${{ with.commits }}"
      max_tokens: 400

  stamp:
    after:
      draft: success
    exec:
      command: ["printf", "stamped"]

outputs:
  notes: "${{ tasks.draft.output }}"
```

Any `--json` run is a recording ([Traces & replay](/concepts/traces)):

```bash theme={"system"}
nika run release-notes.nika.yaml --json > .nika/traces/release-notes.ndjson
```

Resume from it:

```text theme={"system"}
$ nika run release-notes.nika.yaml --resume .nika/traces/release-notes.ndjson
  🦋 nika · release-notes · 3 tasks
     permits ✓ declared boundary · default-deny

  ↷  collect  cache hit (resume)
  ↷  draft    cache hit (resume)
  ↷  stamp    cache hit (resume)
  ── 3/3 done · $0.00 · elapsed 0.0s ─────────────────────────────
    trace: .nika/traces/2026-07-28T07-01-41Z-1a95.ndjson · 8 events · chain 1a101794c8877565c74eb34149b1530d9b59f987f422b9ff4b19acde2d8b5be0

  resumed · 3 skipped (cache hit) · 0 ran live
```

Every skip is **visible** — a `cache hit` line in the render, a
`task_cache_hit` event in the new trace, and the summary counts skipped
vs live. A resumed run never pretends work happened silently.

<Info>
  A trace recorded by an engine version without resume keys is not an
  error: `--resume` prints a notice and runs everything live.
</Info>

## The skip rule · two hashes, both must match

A task skips **iff** the trace holds its completed record and

1. the **task definition** hashes the same (the verb body, `with:`,
   `output:`, `retry:` / `on_error:`, `when:`, `for_each:` — as now
   written), and
2. the **resolved inputs** hash the same (what its `${{ }}` references
   actually resolved to — upstream outputs, `inputs`, `config`, `const`).

Edit a prompt → that task re-runs. Pass a different `--var` → the tasks
that consume it re-run, and the mismatch cascades exactly as far as the
data flows — untouched sibling branches still skip:

```text theme={"system"}
$ nika run brief.nika.yaml --var topic="local-first AI" --resume .nika/traces/brief.ndjson
  resumed · 1 skipped (cache hit) · 0 ran live

$ nika run brief.nika.yaml --var topic="sovereign memory" --resume .nika/traces/brief.ndjson
  resumed · 0 skipped (cache hit) · 1 ran live
```

An `infer:` / `agent:` task that matches replays its recorded output —
that is the point: crash-resume without re-spending tokens. There are no
determinism rules, no replay constraints, no workflow versioning:
durability is the engine's problem, never yours. A task that does not
match simply re-runs live, side effects included.

## `--from` · force a re-run the hashes cannot see

Some changes are invisible to hashing: a rotated secret, external state,
an `infer:` output you want re-rolled. `--from <task_id>` forces that
task **and its transitive downstream** to re-run even on a match —
upstream tasks still cache-hit:

```text theme={"system"}
$ nika run release-notes.nika.yaml --resume .nika/traces/release-notes.ndjson --from draft
  ✔  collect  cache hit
  ✔  draft    infer · mock/echo  0ms
  ✔  stamp    exec · printf      4ms
  ── 3/3 done · $0.000 · elapsed 0.0s ────────────────────────────

  resumed · 1 skipped (cache hit) · 2 ran live
```

An unknown task id is refused before the run, like an unknown `--var` key.

<Warning>
  **Secrets participate by name, never by value** — a trace carries no
  secret-derived material, so a *rotated* secret does not invalidate the
  cache. That is the one sharp edge: after a rotation, force the
  affected node with `--from`.
</Warning>

## The durable human gate · pause and answer

A [`nika:prompt`](/concepts/verbs#invoke) task waits on a human. **At a
terminal, the gate asks you directly** (confirm `[y/N]` · choice by
number or value · input verbatim) and the run continues through the
same verified resume path. Anywhere no human can answer (a pipe · CI ·
an agent · `--json`) with no usable `default:`, the run does not hang
and does not fail — it **pauses durably**: the trace records a
`workflow_paused` event with the prompt payload, the process exits with
code **4**, and the frame prints the exact resume line (your
`--var`/`--model` included). Pre-answer in one pass with
`--answer <task>=<value>` at launch.

```yaml gated-ship.nika.yaml theme={"system"}
nika: v1
workflow:
  id: gated-ship
  description: "Build, ask a human, ship only on yes."

permits:
  exec: ["printf"]                     # build + ship · the argv form is the provable one
  tools: ["nika:prompt"]               # the human gate · default-deny once permits: is present

tasks:
  build:
    exec:
      command: ["printf", "build ok"]

  approve:
    after:
      build: success
    invoke:
      tool: "nika:prompt"
      args:
        message: "Ship this build to production?"

  ship:
    with:
      approved: ${{ tasks.approve.output }}
    when: "${{ with.approved == true }}"
    exec:
      command: ["printf", "shipped"]
```

```bash theme={"system"}
nika run gated-ship.nika.yaml --json > .nika/traces/gated-ship.ndjson
echo $?   # 4 · paused — not a failure, but non-zero so `&& next` stops here
```

The paused trace carries everything needed to pick the run back up —
hours later, on the same machine, by a different process:

```json the workflow_paused event (one line of the trace · reformatted) theme={"system"}
{"kind": "workflow_paused", "fields": [
  {"key": "workflow", "value": "gated-ship"},
  {"key": "task",     "value": "approve"},
  {"key": "mode",     "value": "confirm"},
  {"key": "note",     "value": "awaiting a `nika:prompt` answer — resume with `--resume <trace> --answer <task>=<value>`"},
  {"key": "message",  "value": "Ship this build to production?"}]}
```

Resume with the answer bound to the task id via `--answer` (repeatable):

```text theme={"system"}
$ nika run gated-ship.nika.yaml --resume .nika/traces/gated-ship.ndjson --answer approve=true
  ✔  build    cache hit
  ✔  approve  invoke · nika:prompt  0ms
  ✔  ship     exec · printf         5ms
  ── 3/3 done · $0.000 · elapsed 0.0s ────────────────────────────

  resumed · 1 skipped (cache hit) · 2 ran live
```

The value follows the prompt's `mode:`. **`confirm` wants a boolean**
(`--answer approve=true` / `=false` — a refusal is a value, and the
`when:` gate downstream decides what happens with it). `input` takes a
string, `choice` one of the declared choices. Like `--var`, the value
parses as JSON when it parses.

Resumed **without** an answer, a `--json` run pauses again — idempotent,
exit 4 every time, so a poller can retry harmlessly. Resumed
interactively (a human at the terminal), the prompt simply asks.

## Exit codes

| Exit | Meaning                                                                             |
| ---- | ----------------------------------------------------------------------------------- |
| `0`  | Run completed                                                                       |
| `1`  | Run executed and a task failed unrecovered                                          |
| `2`  | Validation findings — the file never ran                                            |
| `3`  | Environment error (also: unknown `--var` / `--from` key)                            |
| `4`  | **Paused** on a human gate — resume with `--resume <trace> --answer <task>=<value>` |

## Related

* [Concepts · Traces](/concepts/traces): the NDJSON recorder this rides —
  record, replay, share.
* [Concepts · Workflows](/concepts/workflows): `--var` inputs (a changed
  input re-runs exactly the tasks that consume it).
* [Guides · Testing](/guides/testing): the offline golden gate for the
  same files.


# Sharing workflows
Source: https://docs.nika.sh/guides/sharing

Publish and install Nika workflows through nika-registry — every entry machine-re-proven before it runs.

Nika workflows are one portable `.nika.yaml` file, so sharing one is just
sharing text. [**nika-registry**](https://github.com/supernovae-st/nika-registry)
is where that sharing gets a **trust layer no other workflow registry has**:
every entry is re-proven by CI — pinned to a full commit + sha256, re-run
through the conformance oracle, and certified by the engine's static
analysis. You see what a workflow *can do* — exec, tools, cost ceiling,
secrets — **before a single token is spent**.

<Info>
  Trust lives in the artifact, not a gatekeeper: the certificate re-derives
  locally with `nika check`. You never have to believe the registry — you
  re-run the proof yourself, offline.
</Info>

## Install an artifact

Today the flow is a short, auditable script (the `nika add` verb is on the
[engine roadmap](https://github.com/supernovae-st/nika)):

```sh theme={"system"}
git clone https://github.com/supernovae-st/nika-registry && cd nika-registry
python3 scripts/get.py --list                 # what exists
python3 scripts/get.py meeting-actions        # fetch → verify sha256 → local audit → done
```

`get.py` refuses on any mismatch (hash · advisory · file already there) and
**never executes anything** — the workflow lands on disk and you decide to
run it. Not `curl | sh`.

## The guarantees

| Rule                                                                          | What it prevents                       |
| ----------------------------------------------------------------------------- | -------------------------------------- |
| Entries are **immutable** — new version = new file; withdrawal is an advisory | rug-pulls · silent tampering           |
| **Full-commit + full-sha256 pinning** — no tags, no branches                  | tag-rewrite attacks                    |
| CI **re-hashes** the fetched bytes and **re-runs the oracle**                 | broken or lying artifacts              |
| **Key-shaped strings refuse the gate**                                        | shared-template credential leaks       |
| **Zero install-time execution** — entries and artifacts are data              | the entire malicious-postinstall class |

## Machine surfaces (for agents)

* [`index.json`](https://raw.githubusercontent.com/supernovae-st/nika-registry/main/index.json) — every artifact with its pin, digest, cert summary and advisory state in one fetch
* [`llms.txt`](https://raw.githubusercontent.com/supernovae-st/nika-registry/main/llms.txt) — the consume/verify path in agent-readable form

## Publish

Your artifact stays in **your** git repo — the registry stores a pointer, a
digest and a proof, never a copy. Open a PR adding an entry under your
GitHub-owner namespace; CI re-proves it. See the
[contributing guide](https://github.com/supernovae-st/nika-registry/blob/main/CONTRIBUTING.md).


# Speech generation
Source: https://docs.nika.sh/guides/speech-generation

Text to speech inside workflows — the sovereign wire first, one audio file on disk with provenance, duration honesty, and scripts an LLM can write in the same run.

`nika:tts_generate` is the image pipeline's sibling for audio: one file
lands under a permit-gated `output_dir:`, sha256-named, manifest beside it,
and **audio bytes never ride workflow outputs** — tasks pass a path and a
hash, not megabytes of base64.

## The four providers

| provider     | default model            | default voice | what to know                                                                                                                                                                                                                                    |
| ------------ | ------------------------ | ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `local`      | `tts-1`                  | `alloy`       | The sovereign path: any OpenAI-speech-compatible server — LocalAI (`:8080`, also ElevenLabs-compatible upstream), Kokoro-FastAPI, Speaches, openedai-speech. One wire: `POST {base}/v1/audio/speech` → raw bytes. Never inferred from `model:`. |
| `openai`     | `gpt-4o-mini-tts`        | `alloy`       | Sync, seconds-class. `speed:` 0.25–4.0 native.                                                                                                                                                                                                  |
| `elevenlabs` | `eleven_multilingual_v2` | Rachel's id   | `voice:` is a **voice id** (find them in your voice library) — ids ride the URL path, so the engine restricts them to the id alphabet. `speed:` is warned-dropped.                                                                              |
| `mock`       | `mock-tts-1`             | `sine`        | A real, playable, deterministic 16 kHz WAV — zero network, zero keys. CI runs the pipeline offline.                                                                                                                                             |

Keys and the local URL are **engine config, never workflow args**:
`OPENAI_API_KEY` / `ELEVENLABS_API_KEY` (or `NIKA_`-prefixed),
`NIKA_TTS_LOCAL_URL` (+ optional `NIKA_TTS_LOCAL_API_KEY`). `nika doctor`
prints a `tts` line naming what's wired.

## Quickstart

```yaml nika: v1 theme={"system"}
workflow:
  id: narrate
permits:
  fs: { write: ["./out/**"] }
  tools: ["nika:tts_generate"]
tasks:
  speak:
    invoke:
      tool: "nika:tts_generate"
      args:
        provider: local             # sovereign wire · mock = zero-key dry-run · or openai · elevenlabs
        text: "Local first. Honest always. That is the whole design."
        speed: 1.1
        output_dir: "./out"
outputs:
  audio: ${{ tasks.speak.output.audio.path }}
```

```
out/
├── speech-local-tts-1-a0584738.mp3
└── speech-local-tts-1-a0584738-….manifest.json
```

## Honesty rules

* **The extension follows the bytes.** WAV `RIFF…WAVE` and MP3 headers are
  sniffed; a mislabel is a `format_mismatch:` warning, a non-audio payload
  is a hard error — never a corrupt file on disk.
* **Duration is exact or absent.** WAV `duration_ms` is pure header math;
  MP3 duration is honestly `null` rather than a frame-walking guess.
* **`text:` caps at 4096 chars** (the strictest wire's limit, held
  portably) — fan longer scripts out with `for_each` over paragraphs.
* **Content credentials are detected**, not verified: audio C2PA carriage
  (RIFF `C2PA` · MP3 GEOB) is surfaced as `content_credentials` in output
  and manifest, [the same contract as images](/guides/image-generation#content-credentials-detect-and-preserve).
* **Watermarking is declared, never byte-verified.** The manifest's
  `watermark_declared` is a catalog fact: `elevenlabs` →
  `"synthid (provider-declared · not byte-verified)"`, every other
  provider → `null` — no such declaration, honestly absent.

## Cookbook (proven against live APIs)

**An LLM writes the script, another model speaks it — one run:**

```yaml nika: v1 theme={"system"}
workflow:
  id: script-to-speech
model: gemini/gemini-2.5-flash
permits:
  fs: { write: ["./out/**"] }
  tools: ["nika:tts_generate"]
tasks:
  script:
    infer:
      prompt: "Write ONE energetic launch sentence (under 20 words) for a Rust workflow engine that just learned to speak."
  narrate:
    with:
      script: ${{ tasks.script.output }}
    invoke:
      tool: "nika:tts_generate"
      args:
        provider: openai
        text: "${{ with.script }}"
        voice: "nova"
        output_dir: "./out"
        filename_prefix: "announce"
```

The manifest records the LLM's exact sentence as the resolved request —
the provenance chain covers who *wrote* the words, not just who spoke them.

**Retry a local server that's still loading its model:**

```yaml theme={"system"}
  speak:
    retry:
      max_attempts: 3
      on_codes: ["NIKA-BUILTIN-TTS_GENERATE-003"]
    invoke:
      tool: "nika:tts_generate"
      args: { provider: local, text: "…", output_dir: "./out" }
```

<Note>
  Local CPU synthesis gets a 300s default timeout (`timeout_ms:` up to
  600000\); clouds default to 120s. Sub-second values are refused — under 1s
  is a typo'd unit.
</Note>


# Templates
Source: https://docs.nika.sh/guides/templates

The instantiable skeletons covering the recurring workflow shapes. Copy, fill the SLOT lines, check, ship: agents don't invent structure, they instantiate it.

Every recurring workflow shape has a **complete, valid skeleton** in the
spec, gated by the conformance suite on every push, with a `# SLOT:`
marker at every decision point. The path from intent to a correct file
is mechanical: **route → copy → fill slots → `nika check` → repair →
re-check.**

## Route by intent

| Your intent sounds like…                                                       | Template                                          | What it locks in                                                                   |
| ------------------------------------------------------------------------------ | ------------------------------------------------- | ---------------------------------------------------------------------------------- |
| « take data, produce words, save them »                                        | [`chain`](#chain)                                 | deterministic gather · one model job · explicit persist                            |
| « watch X, act when Y »                                                        | [`gate-and-act`](#gate-and-act)                   | jq extraction · CEL skip-gate · often zero model calls                             |
| « do this for EVERY item »                                                     | [`fanout`](#fanout)                               | runtime collection · the full leash (max\_parallel · fail\_fast · retry)           |
| « only what changed since last run »                                           | [`etl-state`](#etl-state)                         | state read→diff→write · `on_error: recover:` quarantine                            |
| « research / review / open-ended »                                             | [`agent-loop`](#agent-loop)                       | plan-then-execute · default-deny tools · budgets · typed final message             |
| « anything irreversible (deploy · send · publish) »                            | [`human-gated-ship`](#human-gated-ship)           | parallel gates · assert · `nika:prompt` GO · `on_finally` record                   |
| « understand a site (domain · theme · assets) from a URL »                     | [`website-brief`](#website-brief)                 | fetch `traverse:` crawl · one typed infer · explicit persist · zero exec           |
| « generate image/audio assets from a brief »                                   | [`media-asset-pack`](#media-asset-pack)           | `nika:image_generate` · `nika:jq` manifest · local/mock provider first             |
| « call a product API: upload a file, then create from it »                     | [`api-upload-and-create`](#api-upload-and-create) | fetch `multipart:` upload · masked secrets header · mode/jq extraction             |
| « read a system's state (docker · kubectl · gh), explain it, keep the report » | [`docker-report`](#docker-report)                 | argv-array exec (provable allowlist) · parallel reads · exec ledger · one artifact |

Composite jobs compose templates: a fanout whose merge feeds a
human-gated-ship, an etl-state whose delta fans out. Start from the
template matching the **outer** shape.

<Info>
  The YAML below is normally **projected** from
  [`nika-spec/templates/`](https://github.com/supernovae-st/nika-spec/tree/main/templates)
  — the source of truth, validated by the conformance runner — by
  `nika-spec/scripts/showcase-projector.py`.

  It is **ahead of that projection right now**: these copies were migrated
  by hand to the 0.106 grammar, and four of them gained the `permits:`
  block an effect-bearing workflow now requires. The templates upstream
  need the same pass, after which the projector reclaims these blocks and
  the two surfaces agree again.
</Info>

## chain

The default shape for « take real data, produce words, save them ».

```yaml chain.nika.yaml theme={"system"}
nika: v1
workflow:
  id: chain-template            # SLOT: kebab-case workflow id
  description: "gather → think → persist"   # SLOT: one honest sentence

# SLOT: provider/model · local · zero key. Measured seat — `ollama/llama3.2:3b`
# answers this prompt in ~50s. `--model mock/echo` needs no seat at all and is
# the path this file guarantees.
model: ollama/llama3.2:3b

const:
  source: "./README.md"             # SLOT: your input · README.md exists in most repos
  destination: "./output.md"        # SLOT: where the result lands

permits:                            # the blast radius · default-deny once present
  tools: ["nika:read", "nika:write"]
  # Two literal paths, one each way. `check` can read these (they come from
  # `const:`) and proves them against the boundary before anything runs — keep
  # them in step with the two `const:` entries above.
  fs:
    read: ["./README.md"]
    write: ["./output.md"]

tasks:
  gather:
    invoke:                         # SLOT: the fact source · nika:read / nika:fetch / exec
      tool: "nika:read"
      args: { path: "${{ const.source }}" }
    on_error:
      # Offline rehearsal. A freshly scaffolded directory has no README, and a
      # skeleton that dies on its first run teaches nothing — so a not-found
      # recovers into a literal standing in for the real document. `on_codes:`
      # keeps that narrow: ONLY not-found is forgiven, a permission error
      # still fails loudly. Delete this block once the source really exists.
      on_codes: [NIKA-BUILTIN-READ-001]
      recover: "REHEARSAL · no source document here yet."

  think:
    with:
      gather: ${{ tasks.gather.output }}
    infer:
      max_tokens: 800               # SLOT: the spend ceiling · sized for the SEAT, not the answer
      # SLOT: the one model job. Keep slot markers OUT of the block below —
      # everything indented under `prompt: |` is prompt TEXT, so a stray
      # `# SLOT:` line is sent to the model verbatim (visible in the mock
      # echo). Comments belong out here, where YAML eats them.
      prompt: |
        Summarize the following in a short paragraph.

        ${{ with.gather }}

  persist:
    with:
      think: ${{ tasks.think.output }}
    invoke:
      tool: "nika:write"
      args:
        path: "${{ const.destination }}"   # SLOT: destination · same path as permits.fs.write
        content: "${{ with.think }}"       # ALWAYS pass content · a write without it writes nothing

outputs:
  result: ${{ tasks.think.output }}  # SLOT: the callable contract
```

## gate-and-act

Watch something, act only when a condition holds (often zero model calls).

```yaml gate-and-act.nika.yaml theme={"system"}
nika: v1
workflow:
  id: gate-and-act-template     # SLOT: kebab-case workflow id
  description: "watch a value · act only when the condition holds"   # SLOT

const:
  source_url: "https://api.example.com/v1/value"   # SLOT: what to watch
  threshold: 100                    # SLOT: the trigger condition value

permits:                            # the blast radius · default-deny once present
  tools: ["nika:fetch", "nika:notify"]
  net:
    http:
      - "api.example.com"           # SLOT: the watched host from const.source_url
      - "hooks.slack.com"           # SLOT: the host ALERTS_WEBHOOK_URL points at.
                                    #   `host_from_self` below means the host is not
                                    #   knowable at check — it is judged at RUN against
                                    #   this list, so an unnamed host fails mid-flight.

secrets:
  webhook:
    source: env
    key: ALERTS_WEBHOOK_URL         # SLOT: where the act lands
    egress:
      - to: "nika:notify"
        host_from_self: true        # the secret value IS the destination URL

tasks:
  check:
    invoke:
      tool: "nika:fetch"
      args:
        url: "${{ const.source_url }}"
        mode: jq
        jq: "."
    output:
      value: ".value"               # SLOT: the jq path to the watched field
    on_error:
      # Offline rehearsal · a sample UNDER the threshold — the gate stays
      # closed, the skeleton runs green before you wire the real source.
      recover: { value: 42 }

  act:
    with:
      value: ${{ tasks.check.value }}   # the binding IS the edge · check → act
    # when: is a SKIP gate — routing, not failure (a skipped task is not an error)
    when: ${{ with.value > const.threshold }}   # SLOT: the CEL condition
    invoke:
      tool: "nika:notify"           # SLOT: the action · notify / write / exec
      args:
        channel: webhook
        target: "${{ secrets.webhook }}"
        message: "Threshold crossed · ${{ with.value }}"   # SLOT
        severity: warning

outputs:
  value: ${{ tasks.check.value }}
```

## fanout

The same work for every item of a runtime collection, fully leashed.

```yaml fanout.nika.yaml theme={"system"}
nika: v1
workflow:
  id: fanout-template           # SLOT: kebab-case workflow id
  description: "discover N items · process in parallel · merge"   # SLOT

# SLOT: provider/model · local · zero key. Measured seat — `ollama/llama3.2:3b`.
# `--model mock/echo` needs no seat and is the path this file guarantees.
model: ollama/llama3.2:3b

run:
  # A `timeout:` is a deadline, and a deadline needs a clock. Declaring it says
  # out loud which one: `system` is the ambient wall clock (the honest default);
  # `virtual` drives a simulated clock for deterministic tests.
  clock: system

const:
  collection_source: "./items"      # SLOT: where the collection comes from

permits:
  tools: ["nika:glob", "nika:jq"]
  fs:
    # `nika:glob` is gated on the DIRECTORY it walks, not on the files it
    # returns — measured: with `./items/*.md` here (the pattern) the run dies
    # `NIKA-SEC-004 · ./items resolves outside the declared permits.fs.read
    # boundary`, because `*` never crosses `/` and so never matches `./items`
    # itself. Grant the directory. A deeper pattern (`./items/**/*.md`) walks
    # deeper and needs `./items/**`. The drift detector models the walk root
    # as a read (2026-07-29) — the former NIKA-DRIFT-001 false hint is closed.
    read: ["./items"]

tasks:
  discover:
    invoke:                         # SLOT: glob / fetch sitemap / exec + jq split
      tool: "nika:glob"
      args: { pattern: "${{ const.collection_source }}/*.md" }

  process:
    with:
      discover: ${{ tasks.discover.output }}
    for_each: ${{ with.discover }}
    max_parallel: 4                 # SLOT: the polite ceiling
    fail_fast: false
    timeout: "60s"                  # SLOT: per-iteration bound
    retry:
      max_attempts: 3
      backoff_strategy: exponential
      jitter: true
    on_error:
      recover: null                 # a failed item yields null at its index · the batch lives
    infer:                          # SLOT: the per-item job (any verb)
      max_tokens: 500               # SLOT: the per-ITEM ceiling · multiply by the fan width
      prompt: |
        Process this item · ${{ item }}

  survivors:
    with:
      process: ${{ tasks.process.output }}
    invoke:                         # the null-aware fan-in · order preserved
      tool: "nika:jq"
      args:
        input: ${{ with.process }}
        # `. // []` · an EMPTY discovery skips the whole for_each (null
        # upstream) — the fan-in must survive its own quiet day.
        expression: "(. // []) | [ .[] | select(. != null) ]"

  merge:
    with:
      survivors: ${{ tasks.survivors.output }}
    infer:
      max_tokens: 800               # SLOT: the fan-in ceiling
      # SLOT: the fan-in · the survivors array (failed items filtered). Keep
      # slot markers out of the block below — it is prompt TEXT, not YAML.
      prompt: |
        Merge these results into one report · ${{ with.survivors }}

outputs:
  report: ${{ tasks.merge.output }}
```

## etl-state

Incremental runs: only what changed since last time, survive bad input.

```yaml etl-state.nika.yaml theme={"system"}
nika: v1
workflow:
  id: etl-state-template        # SLOT: kebab-case workflow id
  description: "read state · fetch fresh · diff · process the delta · save state"   # SLOT

const:
  source_url: "https://api.example.com/v1/records"   # SLOT: the data source
  state_path: "./state/etl-state.json"               # SLOT: the cursor file

permits:                            # the blast radius · default-deny once present
  tools: ["nika:read", "nika:write", "nika:fetch", "nika:jq", "nika:json_diff", "nika:prompt"]
  fs:                               # the cursor file, read then rewritten — one path, both ways
    read: ["./state/etl-state.json"]    # SLOT: keep in step with const.state_path
    write: ["./state/etl-state.json"]   # SLOT: idem — the job writes nothing else
  net: { http: ["api.example.com"] }    # SLOT: the source host from const.source_url

tasks:
  # NEP-0002 · the Rule of Two, as a check. This run holds all three legs at
  # once: it reads a private file, ingests UNTRUSTED network content, and
  # persists that content into the very file the NEXT run reads as trusted
  # state. One human decision has to dominate EVERY path to that write — so the
  # gate sits before the first network touch, not next to the write (a gate the
  # fetch can route around dominates nothing). Blocking on purpose: a `default:`
  # here would disarm it, and the checker knows — measured, adding `default:`
  # flips TRIFECTA to `✖ NIKA-SEC-009 lethal trifecta complete`.
  approve:
    invoke:
      tool: "nika:prompt"
      args:
        message: "Fetch ${{ const.source_url }} and persist it into ${{ const.state_path }}?"

  previous_raw:
    invoke:
      tool: "nika:read"
      args: { path: "${{ const.state_path }}" }
    on_error:
      on_codes: [NIKA-BUILTIN-READ-001]   # not-found ONLY · a permission error still fails loudly
      recover: "[]"                       # first run · the STRING "[]", so `previous` parses it
                                          # exactly like a real file — one code path, not two

  previous:
    with:
      raw: ${{ tasks.previous_raw.output }}
    invoke:
      # `nika:read` hands back TEXT, and `nika:json_diff` compares VALUES. Feed
      # it the raw string and the diff degrades to a single
      # `{"op":"replace","path":""}` carrying the entire new document — it looks
      # like it works, and it reports "everything changed" forever. Measured.
      # `fromjson` is what makes the next task an actual diff.
      tool: "nika:jq"
      args:
        input: "${{ with.raw }}"
        expression: "fromjson"

  fresh:
    with:
      go: ${{ tasks.approve.output }}   # the binding IS the edge · the gate dominates the fetch
    when: ${{ with.go == true }}        # declined → no network touch at all
    invoke:
      tool: "nika:fetch"            # SLOT: fetch / read / exec · the fresh data
      args:
        url: "${{ const.source_url }}"
        mode: jq
        jq: ".records"
    on_error:
      recover: []                   # offline rehearsal · an empty batch, the delta stays quiet

  delta:
    with:                           # the bindings ARE the edges · previous + fresh → delta
      previous: ${{ tasks.previous.output }}
      fresh: ${{ tasks.fresh.output }}
    invoke:
      tool: "nika:json_diff"        # RFC 6902 · empty patch = nothing new
      args:
        before: "${{ with.previous }}"
        after: "${{ with.fresh }}"

  process:
    with:
      delta: ${{ tasks.delta.output }}
    when: ${{ size(with.delta) > 0 }}
    invoke:
      tool: "nika:jq"               # SLOT: the delta job (jq · infer · write…)
      args:
        input: "${{ with.delta }}"
        expression: "length"

  save_state:
    with:
      fresh: ${{ tasks.fresh.output }}
      go: ${{ tasks.approve.output }}   # the binding IS the edge · the gate dominates the write
    when: ${{ with.go == true }}        # a refusal is a VALUE · the write is skipped, never failed
    invoke:
      tool: "nika:write"
      args:
        path: "${{ const.state_path }}"
        content: "${{ with.fresh }}"    # a VALUE · the engine serializes it, and the next run's
                                        # `fromjson` reads it straight back
        create_dirs: true
        overwrite: true

outputs:
  changes:
    value: ${{ tasks.delta.output }}
    description: "RFC 6902 ops since last run · empty = no-op run"
```

## agent-loop

Open-ended work: plan with a fast model, execute with a budgeted agent,
validate the typed result. Never ship an unleashed agent.

```yaml agent-loop.nika.yaml theme={"system"}
nika: v1
workflow:
  id: agent-loop-template       # SLOT: kebab-case workflow id
  description: "plan → budgeted agent → typed result"   # SLOT

# SLOT: a TOOL-CALLING model · local by default. This seat is measured, not
# assumed: `ollama/qwen2.5:14b` completes the planning call in ~65s under the
# ceiling below. A reasoning seat (`ollama/qwen3.5:4b`) spends its whole
# budget thinking and never emits JSON here — the guaranteed offline path is
# `--model mock/echo`, which needs no seat at all.
model: ollama/qwen2.5:14b

inputs:
  goal:
    type: string
    required: true
    # A `required:` input still carries a `default:` here so the skeleton
    # RUNS the moment it is scaffolded. Replace the default with your job;
    # `--var goal=…` overrides it at any time.
    default: "list the risks of running an agent without a turn budget"   # SLOT
    description: "What the agent must accomplish"   # SLOT

permits:                            # the blast radius · default-deny once present
  # Exactly what the body invokes: `nika:assert` (the confirm task) plus the
  # two the agent may call. No `fs:` — see the note on `tools:` below.
  tools: ["nika:assert", "nika:done", "nika:jq"]

tasks:
  plan:
    infer:
      prompt: "Break '${{ inputs.goal }}' into at most 4 concrete steps."   # SLOT
      # SLOT: the spend ceiling for the planning call. Size it for the SEAT,
      # not for the answer: a reasoning model spends tokens thinking before
      # it emits the first brace, and a ceiling that cuts it off mid-thought
      # fails NIKA-INFER-002 ("no JSON value found · the reply was cut off at
      # the token limit"). Measured — 400 starves qwen3.5:4b on this prompt.
      max_tokens: 2000
      schema:
        type: object
        additionalProperties: false
        required: [steps]
        properties:
          steps: { type: array, items: { type: string } }

  execute:
    with:
      steps: ${{ tasks.plan.output.steps }}
    agent:
      # Say what the JOB is. Do NOT describe the output shape.
      #
      # The engine binds `schema:` to the FINAL answer: a free-text answer
      # that does not conform is RE-ASKED with the schema wired, bounded by a
      # retry budget. Measured on ollama/qwen3.5:4b — this task, with zero
      # shape instruction, returns a clean typed object.
      #
      # Hand-instructing "reply with the object, then call nika:done" is
      # actively harmful: a `nika:done` carrying `result:` is validated
      # DIRECTLY and is NEVER re-asked (nika-verb-agent/src/lib.rs · "a miss
      # is a verdict, never a re-ask"), so a model that hands its JSON back
      # as a *string* dies NIKA-INFER-002 with the budget already spent.
      # Measured twice on that exact instruction. Let the engine own shape.
      system: "You are a careful analyst. Work the plan step by step and report what you actually found."   # SLOT
      prompt: "Plan · ${{ with.steps }}"
      tools:                        # SLOT: the MINIMUM grant for the job
        # Pure compute — this pair needs no filesystem, so the skeleton runs
        # anywhere. Granting the agent a tool here is only HALF a grant: every
        # call still crosses the workflow boundary above. Adding `nika:read`
        # to this list WITHOUT adding `permits.fs.read` fails at run with
        # `NIKA-SEC-004 · agent tool "nika:read" refused by the security
        # boundary` — measured, mid-loop, after the turns are paid for.
        - "nika:jq"
        - "nika:done"               # the early-exit sentinel · loop-owned
      max_turns: 15                 # SLOT: the loop bound
      max_tokens_total: 80000       # SLOT: the spend bound
      schema:                       # SLOT: the typed final-message contract
        type: object
        additionalProperties: false
        required: [findings]
        properties:
          findings: { type: array, items: { type: string } }

  confirm:
    with:
      has_findings: ${{ size(tasks.execute.output.findings) > 0 }}   # the check crosses as ONE boundary expression
    invoke:
      tool: "nika:assert"
      args:
        condition: "${{ with.has_findings }}"
        message: "Agent returned no findings, do not trust an empty run"   # SLOT

outputs:
  findings:
    value: ${{ tasks.execute.output.findings }}
    description: "The agent's typed findings"   # SLOT
```

## human-gated-ship

Anything irreversible: parallel gates, a hard assert, a human GO, and an
`on_finally` record whatever happens.

```yaml human-gated-ship.nika.yaml theme={"system"}
nika: v1
workflow:
  id: human-gated-ship-template  # SLOT: kebab-case workflow id
  description: "verify in parallel · human GO · act · record"   # SLOT

permits:                            # SLOT: the blast radius · default-deny once present
  exec: ["echo"]                    # SLOT: ONLY the programs the gates + act run (argv form)
  tools: ["nika:assert", "nika:prompt", "nika:notify"]
  # `host_from_self` below sanctions the FLOW (the secret may BE the URL) — it
  # does not grant the capability to reach anyone. The host stays unknown at
  # check, so it is judged at RUN against this list: name the webhook host here
  # or the record is refused mid-run, after the ship already happened.
  net: { http: ["hooks.slack.com"] }   # SLOT: the webhook host · nothing else may leave

secrets:
  webhook:
    source: env
    key: TEAM_WEBHOOK_URL           # SLOT: where the record lands
    egress:
      - to: "nika:notify"
        host_from_self: true        # the secret value IS the destination URL

tasks:
  # ── the verification wave · all checks run in parallel ──
  check_a:
    exec:
      command: ["echo", "ok"]        # SLOT: gate 1 (argv form · injection-safe)
      capture: structured

  check_b:
    exec:
      command: ["echo", "ok"]        # SLOT: gate 2
      capture: structured

  gates:
    with:
      all_green: ${{ tasks.check_a.output.exit_code == 0 && tasks.check_b.output.exit_code == 0 }}   # two value edges · one boundary expression
    invoke:
      tool: "nika:assert"
      args:
        condition: "${{ with.all_green }}"
        message: "A gate is RED: refusing to proceed"   # SLOT

  human:
    after:
      gates: success              # state, no data · no question until the board is green
    invoke:
      # On a terminal this ASKS. Headless, it answers with `default:` below.
      # Under `--output json` the run PAUSES durably (exit 4 · not a failure)
      # and prints its own resume line:
      #   nika run <file> --resume <trace> --answer human=true
      tool: "nika:prompt"
      args:
        message: "All gates GREEN. Proceed?"   # SLOT: the decision, fully informed
        # Fail CLOSED. The unattended answer to "should I do the irreversible
        # thing" is no — `default: true` would hand CI a rubber stamp.
        default: false

  act:
    with:
      go: ${{ tasks.human.output }}   # the answer crosses as a value edge
    when: ${{ with.go == true }}
    exec:
      command: ["echo", "shipped"]   # SLOT: the irreversible action (argv · program must be in permits.exec)
      # default capture · a failing ship fails LOUDLY (NIKA-EXEC-001):
      # never `capture: structured` on the irreversible step (exit codes
      # would become data and a red ship would read as success)

  record:
    after:
      act: terminal                 # the always-pattern · runs on success, failure, OR refusal
    with:
      acted: ${{ tasks.act.status }}   # observe the outcome · same pass-set as the after edge
    invoke:
      tool: "nika:notify"
      args:
        channel: webhook
        target: "${{ secrets.webhook }}"
        message: "Run finished · act=${{ with.acted }}"   # SLOT · success | failure | skipped
        severity: info
    on_error:
      # Rehearsal only. With TEAM_WEBHOOK_URL unset the reference cannot resolve
      # and this task fails NIKA-VAR-001 (measured) — which would make the
      # skeleton red on a machine that has no webhook. Recovering keeps the
      # scaffold runnable; DELETE this block for real use, because a ship whose
      # audit trail silently vanished is exactly what this task exists to prevent.
      recover: "REHEARSAL · no webhook configured · nothing was sent"

outputs:
  acted: ${{ tasks.act.status }}
```

## website-brief

Understand a site from a URL: bounded `traverse:` crawl → one typed brief → persist. Zero exec.

```yaml website-brief.nika.yaml theme={"system"}
nika: v1
workflow:
  id: website-brief-template    # SLOT: kebab-case workflow id
  description: "crawl → brief → persist"   # SLOT: one honest sentence

# SLOT: provider/model · local · zero key. The schema below has five required
# fields, so give it a seat that holds structure — `ollama/qwen2.5:14b` is
# measured on this shape. `--model mock/echo` needs no seat at all.
model: ollama/qwen2.5:14b

const:
  site_url: "https://example.com"   # SLOT: the site to understand
  out_path: "./out/brief.json"      # SLOT: where the brief lands

permits:                            # the blast radius · default-deny once present
  tools: ["nika:fetch", "nika:write"]
  net: { http: ["example.com"] }    # SLOT: the host from const.site_url. ONE entry is
                                    #   enough — `traverse:` is a same-origin BFS (+ the
                                    #   robots probe), so the crawl never leaves this host.
  fs: { write: ["./out/brief.json"] }   # SLOT: the one file · keep in step with const.out_path
                                        #   (the infer step needs no grant — it is pure compute)

tasks:
  crawl_site:
    invoke:
      tool: "nika:fetch"
      args:
        url: "${{ const.site_url }}"
        traverse: { max_pages: 5 }  # SLOT: crawl bound · 1..=25 (robots honored)
    on_error:
      # Offline rehearsal · a literal standing in for the crawl digest, so the
      # brief step runs with no network at all. Delete once the site is real.
      recover: "REHEARSAL DIGEST · Example Co · a small tool company · plain blue and white pages · buttons, a pricing table, one logo."

  brief:
    with:
      crawl_site: ${{ tasks.crawl_site.output }}
    infer:
      max_tokens: 1200
      # SLOT: the one model job · what should the brief capture? Keep slot
      # markers out of the block below — it is prompt TEXT, not YAML, so a
      # stray comment line is sent to the model verbatim.
      prompt: |
        From this site crawl, produce a creative brief: the domain of
        activity, the dominant visual theme, the audience, the usable
        colors and image assets.
        Crawl digest · ${{ with.crawl_site }}
      schema:                       # SLOT: the typed shape downstream tasks rely on
        type: object
        additionalProperties: false
        properties:
          domain: { type: string }
          theme: { type: string }
          audience: { type: string }
          colors: { type: array, items: { type: string } }
          assets: { type: array, items: { type: string } }
        required: [domain, theme, audience, colors, assets]

  persist:
    with:
      brief: ${{ tasks.brief.output }}
    invoke:
      tool: "nika:write"
      args:
        path: "${{ const.out_path }}"
        create_dirs: true
        # The path ends `.json`, so `content:` is ONE interpolation of a value
        # the engine serializes. Typing `{ "domain": ${{ … }} }` by hand emits
        # unquoted fields and the artifact stops being JSON.
        content: "${{ with.brief }}"

outputs:
  brief: ${{ tasks.brief.output }}   # SLOT: the callable contract
```

## media-asset-pack

Generate assets from a brief: typed creative direction → `nika:image_generate` → jq manifest.

```yaml media-asset-pack.nika.yaml theme={"system"}
nika: v1
workflow:
  id: media-asset-pack-template # SLOT: kebab-case workflow id
  description: "brief → render → manifest"  # SLOT: one honest sentence

# SLOT: provider/model · local · zero key. Measured seat — `ollama/qwen2.5:14b`
# holds the small schema below. `--model mock/echo` needs no seat at all.
model: ollama/qwen2.5:14b

const:
  subject: "a calm cosmic landing hero"   # SLOT: what the asset is about
  out_dir: "./out/assets"           # SLOT: where assets land

permits:                            # the blast radius · default-deny once present
  tools: ["nika:image_generate", "nika:jq", "nika:write"]
  fs:
    write:
      # Two entries, and both earn their place: `check` judges the `output_dir:`
      # ARGUMENT (`./out/assets`), while the RUN gates every FINAL file path under
      # it — the asset, its provenance manifest, and manifest.json. Grant only the
      # directory and the file sails through check, then dies at run on the first
      # asset. `*` is one segment and never crosses `/`, which is all this needs:
      # image_generate lands its files flat, so no subtree grant is warranted.
      - "./out/assets"              # SLOT: keep in step with const.out_dir
      - "./out/assets/*"            # SLOT: idem · the files that land inside it

tasks:
  brief:
    infer:
      max_tokens: 600
      # SLOT: the creative direction · style · constraints. Keep slot markers
      # out of the block below — it is prompt TEXT, not YAML, so a stray
      # comment line is sent to the model verbatim.
      prompt: |
        Write one vivid, concrete image prompt for: ${{ const.subject }}.
        No text in the image · no watermark · a calm central zone.
      schema:
        type: object
        additionalProperties: false
        properties:
          image_prompt: { type: string }
        required: [image_prompt]

  render:
    with:
      brief_image_prompt: ${{ tasks.brief.output.image_prompt }}
    invoke:
      tool: "nika:image_generate"
      args:
        provider: mock              # SLOT: local | openai | gemini | xai (local/mock first)
        prompt: "${{ with.brief_image_prompt }}"
        output_dir: "${{ const.out_dir }}"
        filename_prefix: "asset"    # SLOT: filename stem

  manifest:
    with:
      brief: ${{ tasks.brief.output }}
      render: ${{ tasks.render.output }}
    invoke:
      tool: "nika:jq"
      args:
        expression: "{ brief: .[0], images: .[1].images }"
        input:
          - "${{ with.brief }}"
          - "${{ with.render }}"

  persist:
    with:
      manifest: ${{ tasks.manifest.output }}
    invoke:
      tool: "nika:write"
      args:
        path: "${{ const.out_dir }}/manifest.json"
        create_dirs: true
        # `.json` path → `content:` is ONE interpolation of a value the engine
        # serializes. `nika:jq` above BUILT that value; hand-typing braces
        # around an interpolation emits unquoted fields and breaks the artifact.
        content: "${{ with.manifest }}"

outputs:
  manifest: ${{ tasks.manifest.output }}  # SLOT: the callable contract
```

## api-upload-and-create

Call a product API natively: `multipart:` upload (masked secrets header) → JSON create → typed result.

```yaml api-upload-and-create.nika.yaml theme={"system"}
nika: v1
workflow:
  id: api-upload-and-create-template  # SLOT: kebab-case workflow id
  description: "upload + create in one authenticated call"   # SLOT: one honest sentence

const:
  api_base: "https://api.example.com"     # SLOT: the product API base
  asset_path: "./out/assets/asset-1.png"  # SLOT: the file to upload

secrets:
  API_KEY:
    source: env
    key: EXAMPLE_API_KEY            # SLOT: the OS env var holding the key
    egress:
      - to: "nika:fetch"            # the send · default-deny otherwise
      - to: "outputs"               # the return value derives from the authed response

permits:                            # the blast radius · default-deny once present
  tools: ["nika:fetch"]
  # `egress:` above sanctions the FLOW (this secret may ride a fetch); it does
  # NOT grant the capability to reach anyone. The host is the separate, required
  # half — an unlisted host is refused at RUN, mid-flight, with the bytes
  # already on the wire.
  net: { http: ["api.example.com"] }   # SLOT: the host from const.api_base
  fs:
    # A `multipart:` file part names a path, and that read crosses the boundary
    # like any other: measured, without this entry the call dies `NIKA-SEC-004 ·
    # ./out/assets/asset-1.png resolves outside the declared permits.fs.read
    # boundary`. One exact file, never the tree it sits in. The drift detector
    # models a multipart part as a read (2026-07-29) — the former NIKA-DRIFT-001
    # false hint is closed.
    read: ["./out/assets/asset-1.png"]   # SLOT: keep in step with const.asset_path

tasks:
  create:
    invoke:
      tool: "nika:fetch"
      args:
        url: "${{ const.api_base }}/items"   # SLOT: the create endpoint
        method: POST
        headers:
          x-api-key: "${{ secrets.API_KEY }}"  # SLOT: the auth header name
        multipart:
          # Exactly one of `path:` (file) or `value:` (text) per part — a part
          # carrying both, or neither, is refused before anything is sent.
          - { name: file, path: "${{ const.asset_path }}" }
          - { name: title, value: "Rehearsal item" }   # SLOT: the metadata fields
        mode: jq
        jq: "{ id: .id, url: .url }"   # SLOT: the fields downstream needs
    on_error:
      # Offline rehearsal · a literal shaped EXACTLY like what the jq above
      # projects, so `outputs.result` has the same shape on both paths. It also
      # absorbs the unset key: a `secrets:` entry whose env var is missing fails
      # NIKA-VAR-001, and a recover catches that too (measured).
      recover: { id: "rehearsal-0001", url: "https://app.example.com/items/rehearsal-0001" }

outputs:
  result: ${{ tasks.create.output }}   # SLOT: the callable contract
```

## docker-report

The audited-ops shape: read a system's real state via a pinned CLI (argv-array exec — the only form a `permits.exec` allowlist can prove), explain it with one bounded model call, keep the report as a file. Swap `docker` for any product CLI. The live-proven walkthrough: [A Docker AI workflow](/guides/docker-ai-workflow).

<Tip>
  Shipped in the engine pack since 0.99.0: `nika new --from docker-report   <dest>.nika.yaml` scaffolds this exact skeleton (verified on the
  released binary). The block below is the same conformance-validated
  source, if you prefer to copy it.
</Tip>

```yaml docker-report.nika.yaml theme={"system"}
nika: v1
workflow:
  id: docker-report-template    # SLOT: kebab-case workflow id
  description: "read the daemon's state · explain it · keep the report"   # SLOT

# SLOT: local-first · `--model mock/echo` for the offline rehearsal. Measured
# seat — `ollama/llama3.2:3b` answers this prose prompt in well under a minute.
model: ollama/llama3.2:3b

permits:                            # the blast radius · default-deny once present
  exec:
    - "docker"                      # SLOT: the ONE program the reads may launch
  tools:
    - "nika:write"
  fs:
    write:
      - "./docker-health.md"        # SLOT: where the report lands (must match `keep`)

tasks:
  # The reads run IN PARALLEL (no edges between them) — the
  # scheduler proves it from the DAG, nobody orders it.
  ps:
    exec:
      # SLOT: argv ARRAY form — one program, exactly these arguments. The array
      # is why there is no shell here: no word-splitting, no globbing, nothing
      # to quote wrong. `permits.exec` above is the provable allowlist.
      command: ["docker", "ps", "--all", "--format", "{{.Names}}\t{{.Status}}\t{{.Image}}"]
    on_error:
      # Offline rehearsal · a host with no daemon answers with a literal that
      # LOOKS like the real thing, so `diagnose` reads the same shape either
      # way. Delete this once the daemon is really there.
      recover: "REHEARSAL\tno docker daemon on this host\tn/a"

  df:
    exec:
      command: ["docker", "system", "df"]   # SLOT: the second read (drop the task if one suffices)
    on_error:
      recover: "REHEARSAL · disk usage unavailable without a daemon"

  diagnose:
    with:
      ps: ${{ tasks.ps.output }}
      df: ${{ tasks.df.output }}
    infer:
      max_tokens: 600               # SLOT: the spend ceiling for this call
      # SLOT: what should the model DO with the readings? Keep slot markers out
      # of the block below — everything indented under `prompt: |` is prompt
      # TEXT, and a stray comment line is sent to the model verbatim.
      prompt: |
        You are reading a Docker host's state. Containers (name·status·image):
        ${{ with.ps }}

        Disk usage:
        ${{ with.df }}

        Write a short health report: what is running, what exited, what
        looks unhealthy (restart loops · old exits), and whether disk
        usage needs attention. Plain prose, no preamble.

  keep:
    with:
      diagnose: ${{ tasks.diagnose.output }}
    invoke:
      tool: "nika:write"
      args:
        path: "./docker-health.md"  # SLOT: same path as permits.fs.write
        content: "${{ with.diagnose }}"

outputs:
  report: ${{ tasks.keep.output }}
```

## The instantiation protocol

<Steps>
  <Step title="Route">
    Pick the template whose intent row matches. Never free-form a
    workflow when a template routes.
  </Step>

  <Step title="Copy + fill">
    Copy the skeleton, change ONLY the `# SLOT:` lines. Everything else
    is locked structure.
  </Step>

  <Step title="Check">
    `nika check workflow.nika.yaml`: the validator names the exact rule
    on every error.
  </Step>

  <Step title="Repair from the error">
    Fix exactly what the named rule says, re-check until clean. Don't
    fix what the validator didn't name.
  </Step>
</Steps>

## See also

<CardGroup>
  <Card title="Writing Nika as an agent" icon="robot" href="/guides/agent-authoring">
    The deterministic protocol these templates anchor.
  </Card>

  <Card title="Patterns" icon="diagram-project" href="/guides/patterns">
    The twelve composition patterns the templates lock in.
  </Card>

  <Card title="Examples" icon="grid" href="/examples/overview">
    &#x20;full tiered workflows built from these shapes.
  </Card>

  <Card title="Templates source" icon="github" href="https://github.com/supernovae-st/nika-spec/tree/main/templates">
    The skeletons in the spec repo, conformance-gated.
  </Card>
</CardGroup>


# Test workflows
Source: https://docs.nika.sh/guides/testing

Golden testing with nika test: every workflow runs offline under the mock provider, deterministically, and CI gates on the diff.

A workflow is code, so it gets tests. `nika test <file>` runs the workflow
under the **mock provider** — offline, deterministic, zero keys, zero
tokens — and compares the typed `outputs:` against a **golden file**
(`<file>.golden.json`) committed next to it. Same idea as snapshot testing:
pin what the workflow produces, and any future edit that changes the
contract fails loud in CI.

```bash theme={"system"}
nika test triage.nika.yaml
```

## Why the mock makes this possible

`nika test` swaps every `infer:` / `agent:` call to the mock provider,
whatever `model:` the file declares — your `ollama/llama3.2:3b` (or
`mistral/…`, or any cloud model) workflow tests offline, unchanged.

The mock is not a stub that returns `"ok"`. It is **schema-conformant**:
when a task declares a `schema:`, the mock synthesizes an instance that
validates against it — required fields present, types respected. Every
schema workflow runs offline, end to end, through the same runtime,
bindings, and typed-outputs validation as a live run.

```yaml triage.nika.yaml theme={"system"}
nika: v1
workflow:
  id: ticket-triage
  description: "Classify a support ticket into a typed verdict."

model: mock/echo                       # swap for ollama/llama3.2:3b or any provider

inputs:
  ticket:
    type: string
    default: "Payment page returns a 502 after checkout."

tasks:
  classify:
    infer:
      prompt: "Classify this ticket: ${{ inputs.ticket }}"
      max_tokens: 300
      schema:
        type: object
        required: [category, urgent]
        properties:
          category: { type: string }
          urgent: { type: boolean }

outputs:
  verdict: "${{ tasks.classify.output }}"
```

<Tip>
  The golden pins the workflow's `outputs:` block — a workflow without one
  pins `{}`. Declare typed `outputs:` and the golden guards the whole
  callable contract.
</Tip>

## The golden lifecycle

First run — no golden exists yet, so `nika test` teaches instead of
guessing (exit 3):

```text theme={"system"}
$ nika test triage.nika.yaml
nika test · no golden yet for triage.nika.yaml

  the golden pins this workflow's typed `outputs:` under the mock
  provider (offline · deterministic) — future runs must match it.

  create it:   nika test triage.nika.yaml --update
  then commit: triage.nika.yaml.golden.json
```

Create it with `--update`, review it once, commit it:

```text theme={"system"}
$ nika test triage.nika.yaml --update
✔ golden written · triage.nika.yaml.golden.json
  review it once, commit it — `nika test` now guards this workflow
```

The golden is small, readable JSON — the mock-synthesized, schema-conformant
outputs:

```json triage.nika.yaml.golden.json theme={"system"}
{
  "verdict": {
    "category": "mock",
    "urgent": false
  }
}
```

From now on `nika test` compares. A match is exit 0; drift renders a
per-path diff and exits 1:

```text theme={"system"}
$ nika test triage.nika.yaml
✖ outputs drifted from the golden · triage.nika.yaml.golden.json
  + outputs.verdict.queue · not in the golden ("mock")

  intended? re-pin with: nika test triage.nika.yaml --update
```

If the drift was intended (you changed the schema, added an output), re-pin
with `--update` and commit the new golden — the diff shows up in code
review, exactly like a snapshot test.

## Exit codes · the CI contract

| Exit | Meaning                                                                      |
| ---- | ---------------------------------------------------------------------------- |
| `0`  | Outputs match the golden (or `--update` pinned one)                          |
| `1`  | The mock run failed, or outputs drifted from the golden                      |
| `2`  | The file has validation findings (`nika check` would fail — fix those first) |
| `3`  | No golden yet (create with `--update`), or environment error                 |

`nika test` refuses to run a dirty file the same way `nika run` does: a
workflow with check findings exits 2 before anything executes.

## Wire it into CI

Offline and deterministic means no keys in CI, no flakes, no spend:

```yaml .github/workflows/nika-test.yml (fragment) theme={"system"}
- name: Golden-test the workflows
  run: |
    for wf in workflows/*.nika.yaml; do
      nika test "$wf"
    done
```

Commit the `*.golden.json` files in the same directory as the workflows
they guard. A PR that edits a workflow either keeps its golden green or
shows the re-pinned golden in the diff — both are reviewable.

## Related

* [Concepts · Workflows](/concepts/workflows): typed `inputs:` in,
  typed `outputs:` out — the callable contract the golden pins.
* [Reference · CLI](/reference/cli): every `nika test` flag.
* [Guides · Troubleshooting](/guides/troubleshooting): when `nika check`
  findings block a test (exit 2).


# Troubleshooting & FAQ
Source: https://docs.nika.sh/guides/troubleshooting

The errors you'll actually hit, what they mean, and the questions everyone asks: version story, runnable state, providers, syntax dialects.

## The questions everyone asks

<AccordionGroup>
  <Accordion title="Can I run Nika today?" icon="play">
    Yes. Install the latest tagged release with Homebrew or `install.sh`,
    then run `nika check` and `nika run` locally. The engine is still
    pre-1.0 and hardening toward the 1.0 launch, but the `nika: v1`
    language envelope is already stable.
  </Accordion>

  <Accordion title="Why is the language v1 but the engine pre-1.0?" icon="code-branch">
    Two independent axes. The **language envelope `nika: v1` is frozen
    forever**: files you write never break. The **engine** follows real
    semver toward 1.0 (`0.90` release-candidate today, then `1.0.0`, `1.1`, …).
    Same model as SQL or GraphQL: the contract is stable, implementations
    iterate.
  </Accordion>

  <Accordion title="Is fetch a verb?" icon="globe">
    No. There are exactly  verbs (`infer` · `exec` ·
    `invoke` · `agent`), locked forever. Fetching a URL is *calling a
    tool*: `invoke: { tool: "nika:fetch" }`. If you see `fetch:` as a
    verb anywhere, it's the pre-spec legacy dialect.
  </Accordion>

  <Accordion title="Which providers work offline?" icon="server">
    &#x20;local runtimes (Ollama · LM Studio · llama.cpp
    · LocalAI · vLLM). Point `model: ollama/llama3.2:3b` at your machine and
    the whole workflow runs with zero cloud. `mock/echo` runs with
    nothing at all: that's what the templates default to.
  </Accordion>

  <Accordion title="Do I write {{ }} or ${{ }}?" icon="dollar-sign">
    Always `${{ … }}`: what's inside is CEL. The bare `{{ … }}` form is
    legacy and rejected by the validator. Same rule: there are **no
    template filters** (`| upper`, `| truncate`): transforms are jq, in
    `output:` bindings or `nika:jq`.
  </Accordion>

  <Accordion title="My YAML is valid, so why does nika check still fail?" icon="shield-check">
    Schema-valid ≠ spec-valid. The validator also enforces the semantic
    rules: `tasks.*` references live at the boundary only (`with:` ·
    `after:` — a body reference is `NIKA-VAR-021`, hoist it into
    `with:`), `when:` must be a CEL boolean over local namespaces,
    `nika:done` only inside an agent's tool list, exactly one verb per
    task. The error names the exact rule. Fix that rule, nothing else,
    re-check.
  </Accordion>
</AccordionGroup>

## Errors you'll hit, decoded

Every failure is a typed structure with a stable code and a `transient`
flag ([error model](/reference/error-codes)). The frequent ones:

| Symptom                                                             | Code family                         | What it means · what to do                                                                                                                                                                                                                                                                      |
| ------------------------------------------------------------------- | ----------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| « parse error » on a file that looks fine                           | `NIKA-PARSE`                        | Usually the envelope: `nika: v1` exactly (not `v1.0` · not `1`), `workflow:` kebab-case, `tasks:` present.                                                                                                                                                                                      |
| `tasks.X` read refused at check time                                | `NIKA-VAR-021` · `NIKA-PARSE-024`   | A `tasks.*` reference outside the boundary (verb body · `when:` · `for_each:`): hoist it into `with:` — the binding IS the edge (`nika check --fix` applies it). A lingering `depends_on:` is `NIKA-PARSE-024`: data → `with:`, control → `after:`.                                             |
| `jq`/`fromjson` fails on fetch output (« expecting value, byte 0 ») | `NIKA-BUILTIN-JQ`                   | The fetch used the default `mode: markdown` (built for pages — it escapes JSON bodies). APIs take `mode: raw`, or `mode: jq` + `jq:` so the shaping rides the fetch.                                                                                                                            |
| « unknown binding »                                                 | `NIKA-VAR` · `NIKA-VALUES`          | Six namespaces only — the four value authorities (`inputs` · `config` · `const` · `secrets`) plus `with` and `tasks`. Typos like `tsaks.` are caught at validation; a read of the dead `vars`/`env` namespaces is `NIKA-VALUES-001`/`-002`, and any other value namespace is `NIKA-VALUES-003`. |
| « no boundary declared » on a workflow that touches something       | `NIKA-AUTH-006`                     | An absent `permits:` block declares ZERO authority, not a free pass. Run `nika check --infer-permits` — it prints the tightest block the body needs, ready to paste.                                                                                                                            |
| provider call fails once then works                                 | `NIKA-PROVIDER` (`transient: true`) | The engine retries with backoff per your `retry:`. Declare it instead of wrapping logic.                                                                                                                                                                                                        |
| fetch refuses a URL                                                 | `NIKA-SEC`                          | SSRF defense: private networks and cloud metadata are blocked by default ([security model](/concepts/security)).                                                                                                                                                                                |
| command blocked in exec                                             | `NIKA-SEC-001`                      | Shell-mode blocklist hit: pass tainted data via `stdin:`/`args:`, never interpolated into `command:`.                                                                                                                                                                                           |
| agent never finishes                                                | `NIKA-AGENT`                        | Budgets are mandatory leashes: `max_turns` + `max_tokens_total`, and the loop ends with `nika:done`.                                                                                                                                                                                            |

## When it breaks, in order

<Steps>
  <Step title="Read the code, not the message">
    `NIKA-<NAMESPACE>-<NNN>` is stable and greppable. The
    [catalog](/reference/error-codes) gives the namespace's contract.
  </Step>

  <Step title="Check transient">
    `transient: true` → retry can help (declare `retry:` with backoff).
    `transient: false` → the input or the file is wrong; retrying burns
    money.
  </Step>

  <Step title="Recover structurally">
    `on_error: recover:` substitutes a fallback value ·
    `on_error: on_codes:` scopes recovery to specific codes (recover the
    not-found, still fail loudly on permission-denied).
  </Step>

  <Step title="Ask with context">
    Two guided forms exist so nothing gets lost: **[First run
    failed](https://github.com/supernovae-st/nika/issues/new?template=first_run_failed.yml)**
    (a stumble in your first minutes is a bug, even when nothing
    crashed) and **[I was confused
    here](https://github.com/supernovae-st/nika/issues/new?template=confused_here.yml)**
    (paper cuts are bugs in the teaching). The output of `nika welcome`
    is the perfect diagnostic attachment — it prints key *presence*,
    never values. For everything else,
    [Discussions](https://github.com/supernovae-st/nika/discussions) is
    the fastest lane. Security findings: [security@supernovae.studio](mailto:security@supernovae.studio),
    never public issues.
  </Step>
</Steps>

<Note>
  Nika ships **zero telemetry** — the binary never phones home. These
  forms and Discussions ARE the project's analytics: a report that you
  reached your first green run in under two minutes is a data point we
  cannot get any other way.
</Note>

## See also

<CardGroup>
  <Card title="Error codes" icon="triangle-exclamation" href="/reference/error-codes">
    The  namespaces + the typed error shape.
  </Card>

  <Card title="Templates" icon="copy" href="/guides/templates">
    Skeletons that avoid most of these errors by construction.
  </Card>

  <Card title="Security model" icon="shield-halved" href="/concepts/security">
    Why fetch/exec block what they block.
  </Card>

  <Card title="Live engine state" icon="gauge" href="/reference/status">
    What's admitted today ( crates).
  </Card>
</CardGroup>


# Use Nika with AnythingLLM
Source: https://docs.nika.sh/integrations/clients/anythingllm

Add the read-only Nika oracle to AnythingLLM with the standard mcpServers stanza. Wiring is manual (no wire target).

[AnythingLLM](https://github.com/Mintplex-Labs/anything-llm) speaks MCP
through the standard `mcpServers` JSON convention (the Claude-Desktop
shape) — its MCP docs show where the servers file lives for your install
(desktop vs Docker). The binary comes first:
`brew install supernovae-st/tap/nika`
([other paths](/getting-started/installation)).

Wiring is manual — `nika wire` has no AnythingLLM target. Add the `nika`
entry to AnythingLLM's MCP servers file:

```json theme={"system"}
{ "mcpServers": { "nika": { "command": "nika", "args": ["mcp"] } } }
```

<Note>
  The stable contract is the stanza — `nika` + `mcp`, stdio. If AnythingLLM's
  documented file location has moved, the stanza still applies.
</Note>

## What you get

Validation, explanation, schema and cost answers for `.nika.yaml`
workflows — no execution, no mutation, by design
([the oracle's contract](/reference/mcp-server)). Running workflows stays
on the terminal, where the budget flags and traces live.

## Verify

AnythingLLM's agent-skills / MCP panel lists `nika` with the nine
`nika_*` tools. Then prove the loop end-to-end:
[integrate in 10 minutes](/integrations/quickstart).


# Use Nika with Cherry Studio
Source: https://docs.nika.sh/integrations/clients/cherry-studio

Add the read-only Nika oracle to Cherry Studio as a stdio MCP server. Wiring is manual (no wire target).

[Cherry Studio](https://github.com/CherryHQ/cherry-studio) configures MCP
servers in its settings UI — add Nika as a **stdio** server. The binary
comes first: `brew install supernovae-st/tap/nika`
([other paths](/getting-started/installation)).

Wiring is manual — `nika wire` has no Cherry Studio target. The three
fields, whichever form the settings take:

| Field   | Value   |
| ------- | ------- |
| type    | `stdio` |
| command | `nika`  |
| args    | `mcp`   |

Equivalently, where Cherry Studio accepts the JSON form:

```json theme={"system"}
{ "mcpServers": { "nika": { "command": "nika", "args": ["mcp"] } } }
```

## What you get

Validation, explanation, schema and cost answers for `.nika.yaml`
workflows — no execution, no mutation, by design
([the oracle's contract](/reference/mcp-server)). Running workflows stays
on the terminal, where the budget flags and traces live.

## Verify

Cherry Studio's MCP server list shows `nika` with the nine `nika_*`
tools. Then prove the loop end-to-end:
[integrate in 10 minutes](/integrations/quickstart).


# Use Nika with Claude Code
Source: https://docs.nika.sh/integrations/clients/claude-code

One command wires the read-only Nika oracle into Claude Code — plus the first-party plugin with the authoring skill and /nika:* commands.

Claude Code gets two Nika surfaces: the MCP oracle — schema, validation and
cost answers without shell round-trips
([what it exposes and refuses](/reference/mcp-server)) — and the first-party
plugin. The binary comes first: `brew install supernovae-st/tap/nika`
([other paths](/getting-started/installation)).

```sh theme={"system"}
nika wire claude
```

## What it writes

`~/.claude.json` — the `nika` entry lands under `mcpServers`; every
unrelated server and setting survives, and re-running prints `· current`
(idempotent). Prefer manual? Add the same block yourself:

```json theme={"system"}
{ "mcpServers": { "nika": { "command": "nika", "args": ["mcp"] } } }
```

## The plugin (skill + commands)

```sh theme={"system"}
claude plugin marketplace add supernovae-st/nika-agents
claude plugin install nika@nika   # authoring skill + /nika:* commands + oracle
```

Then `nika init` in the repo — the agent-teaching surface (`AGENTS.md`,
rules, the repo skill) is what makes the oracle useful
([agents guide](/getting-started/agents)).

## Keep it fresh

Two things move, on the same release train — the plugin never updates
the binary, and brew never updates the plugin. Claude Code's plugin
update is TWO rungs (proven live: an install once sat three releases
behind, silently, with a fresh clone right next to it):

```sh theme={"system"}
brew upgrade nika                        # the binary
claude plugin marketplace update nika    # rung 1: refresh the clone
claude plugin update nika@nika           # rung 2: move the install — then restart
```

`nika doctor` answers "is my suite coherent?" — from v0.107 it reads
the install rung (what your sessions actually load), names any kit
lagging or leading the binary's train, and prints both rungs when
Claude Code needs the climb. Drift is advisory (warn · exit 0), so it
never breaks automation.

## Verify

`claude mcp list` shows `nika`, and the tool list carries the nine
`nika_*` tools. Then prove the loop end-to-end:
[integrate in 10 minutes](/integrations/quickstart).


# Use Nika with Claude Desktop
Source: https://docs.nika.sh/integrations/clients/claude-desktop

Wire the read-only Nika oracle into Claude Desktop — the exact claude_desktop_config.json path per platform, the stanza, and the verify step.

Claude Desktop is a different app with a different config file than Claude
Code's `~/.claude.json` — it reads `claude_desktop_config.json` from the
platform app-config dir. The binary comes first:
`brew install supernovae-st/tap/nika`
([other paths](/getting-started/installation)).

Add the `nika` server under `mcpServers`:

```json theme={"system"}
{ "mcpServers": { "nika": { "command": "nika", "args": ["mcp"] } } }
```

The file lives at:

| Platform | Path                                                                                     |
| -------- | ---------------------------------------------------------------------------------------- |
| macOS    | `~/Library/Application Support/Claude/claude_desktop_config.json`                        |
| Windows  | `%APPDATA%\Claude\claude_desktop_config.json`                                            |
| Linux    | `~/.config/Claude/claude_desktop_config.json` (community builds — same dir the app uses) |

`nika wire claude-desktop` ships in the next release and writes exactly
this — idempotent, every unrelated server preserved.

<Note>
  Each [engine release](https://github.com/supernovae-st/nika/releases/latest)
  also ships one-click `.mcpb` bundles (macOS arm64 · Linux x64, with
  checksums) if you prefer not to touch JSON at all.
</Note>

## Verify

Restart Claude Desktop, then check its tools list — the nine `nika_*`
tools appear ([the oracle's contract](/reference/mcp-server): validate,
explain, schema, cost — no execution, no mutation). The config-file
convention is the MCP quickstart's own
([modelcontextprotocol.io](https://modelcontextprotocol.io/quickstart/user)).

Then prove the loop end-to-end:
[integrate in 10 minutes](/integrations/quickstart).


# Use Nika with Cline
Source: https://docs.nika.sh/integrations/clients/cline

Add the read-only Nika oracle to Cline's cline_mcp_settings.json — hot-reloaded, no restart; one wire command in the next release.

[Cline](https://github.com/cline/cline) configures MCP servers in
`cline_mcp_settings.json` — Cursor-style `mcpServers` record — and
hot-reloads the file (a watcher picks up external writes, no restart).
The binary comes first: `brew install supernovae-st/tap/nika`
([other paths](/getting-started/installation)).

Add the `nika` entry:

```json theme={"system"}
{ "mcpServers": { "nika": { "command": "nika", "args": ["mcp"] } } }
```

## Where the file lives

Cline's settings live in two generations of home:

* **Today's extension** keeps `settings/cline_mcp_settings.json` under the
  host IDE's globalStorage — the dir name `saoudrizwan.claude-dev` is
  stable across VS Code · Cursor · Windsurf · VSCodium · Insiders. On
  macOS: `~/Library/Application Support/<Host>/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json`
  (elsewhere: `~/.config/<Host>/User/globalStorage/…`). Cline's own MCP
  Servers panel edits the same file.
* **The stable home** — `~/.cline/data/settings/cline_mcp_settings.json` —
  is what the Cline CLI reads today and where the extension migrates next.

`nika wire cline` ships in the next release and resolves this for you: a
host IDE's existing extension dir wins (the live, hot-reloaded file); none
existing falls back to the stable home. Idempotent, unrelated servers
preserved.

## Verify

Cline's MCP Servers view lists `nika` with the nine `nika_*` tools
([the oracle's contract](/reference/mcp-server)). The repo side comes from
`nika init` (`AGENTS.md`, rules). Then prove the loop end-to-end:
[integrate in 10 minutes](/integrations/quickstart).


# Use Nika with Codex
Source: https://docs.nika.sh/integrations/clients/codex

One command wires the read-only Nika oracle into ~/.codex/config.toml — comments preserved — plus the first-party Codex plugin.

Codex gets two Nika surfaces: the MCP oracle and the first-party plugin.
Binary first (`brew install supernovae-st/tap/nika` ·
[other paths](/getting-started/installation)):

```sh theme={"system"}
nika wire codex
```

## What it writes

`~/.codex/config.toml` — TOML, not JSON. The writer edits only the
`[mcp_servers.nika]` table and keeps your comments and unrelated tables
intact; re-running prints `· current` (idempotent). The same block by hand:

```toml theme={"system"}
[mcp_servers.nika]
command = "nika"
args = ["mcp"]
```

## The plugin (skill + commands)

```sh theme={"system"}
codex plugin marketplace add supernovae-st/nika-agents
codex plugin add nika@nika
```

Then `nika init` in the repo — the agent-teaching surface (`AGENTS.md`,
rules, the repo skill) is what makes the oracle useful
([agents guide](/getting-started/agents)).

## Keep it fresh

Two things move, on the same release train — the plugin never updates
the binary, and brew never updates the plugin:

```sh theme={"system"}
brew upgrade nika                       # the binary
codex plugin marketplace upgrade nika   # the plugin kit (the per-version
                                        # cache refreshes on your next run)
```

`nika doctor` answers "is my suite coherent?" — from v0.107 it names
any kit lagging or leading the binary's train, with the exact fix per
client. Drift is advisory (warn · exit 0), so it never breaks
automation.

## Verify

Codex's MCP server list shows `nika` with the nine `nika_*` tools
([the oracle's contract](/reference/mcp-server)). Then prove the loop
end-to-end: [integrate in 10 minutes](/integrations/quickstart).


# Use Nika with Continue
Source: https://docs.nika.sh/integrations/clients/continue

Drop one file into ~/.continue/mcpServers/ and Continue gets the read-only Nika oracle — your config.yaml untouched; one wire command in the next release.

[Continue](https://github.com/continuedev/continue) scans
`~/.continue/mcpServers/*.json` for MCP servers (the Claude-Desktop JSON
shape, name-keyed) — so Nika gets its **own file** and your
comment-bearing `config.yaml` is never touched. The binary comes first:
`brew install supernovae-st/tap/nika`
([other paths](/getting-started/installation)).

Create `~/.continue/mcpServers/nika.json`:

```json theme={"system"}
{ "mcpServers": { "nika": { "command": "nika", "args": ["mcp"] } } }
```

`nika wire continue` ships in the next release and writes exactly this
file — idempotent, nothing else in your Continue setup touched.

<Note>
  External writes are **not** hot-reloaded: reload Continue (or re-save
  `config.yaml`) to pick the server up.
</Note>

## The repo side

`nika init` writes the agent-teaching surface (`AGENTS.md`, rules) plus
the `$schema` modeline for validation and completion on `*.nika.yaml`.

## Verify

Continue's tool list shows the nine `nika_*` tools
([the oracle's contract](/reference/mcp-server): validate, explain, schema,
cost — no execution, no mutation). Then prove the loop end-to-end:
[integrate in 10 minutes](/integrations/quickstart).


# Use Nika with Cursor
Source: https://docs.nika.sh/integrations/clients/cursor

One command (or one click) wires the read-only Nika oracle into ~/.cursor/mcp.json — plus the auto-attached authoring rule from nika init.

One command, or one click — binary first
(`brew install supernovae-st/tap/nika` ·
[other paths](/getting-started/installation)):

```sh theme={"system"}
nika wire cursor
```

[![Install MCP Server](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en/install-mcp?name=nika\&config=eyJjb21tYW5kIjogIm5pa2EiLCAiYXJncyI6IFsibWNwIl19)

## What it writes

`~/.cursor/mcp.json` — the `nika` entry under `mcpServers`; every unrelated
server survives, re-running prints `· current` (idempotent). The same block
by hand:

```json theme={"system"}
{ "mcpServers": { "nika": { "command": "nika", "args": ["mcp"] } } }
```

## The repo side

`nika init` writes `.cursor/rules/nika.mdc` — auto-attached on
`*.nika.yaml`, so Cursor's agent knows the check-before-run law without
being told. The VS Code extension also installs into Cursor via
[OpenVSX](https://open-vsx.org/extension/supernovae/nika).

## Verify

Cursor's MCP settings list `nika` with the nine `nika_*` tools
([the oracle's contract](/reference/mcp-server): validate, explain, schema,
cost — no execution). Then prove the loop end-to-end:
[integrate in 10 minutes](/integrations/quickstart).


# Use Nika with Gemini CLI
Source: https://docs.nika.sh/integrations/clients/gemini-cli

Add the read-only Nika oracle to Gemini CLI's settings.json — the exact stanza today, one wire command in the next release.

<Note>
  **Where Gemini CLI stands** · on 2026-06-18 Google ended the consumer
  service (AI Pro, Ultra and free tiers) in favor of
  [Antigravity CLI](https://antigravity.google/docs/gcli-migration) ·
  enterprise access and paid API keys continue, and the
  [OSS repo](https://github.com/google-gemini/gemini-cli) stays active. This
  guide remains valid for those paths; an Antigravity guide follows once our
  wiring is live-proven.
</Note>

[Gemini CLI](https://github.com/google-gemini/gemini-cli) reads MCP servers
from `mcpServers` in its user-scope `~/.gemini/settings.json`. The binary
comes first: `brew install supernovae-st/tap/nika`
([other paths](/getting-started/installation)).

Add the `nika` entry to `~/.gemini/settings.json`:

```json theme={"system"}
{ "mcpServers": { "nika": { "command": "nika", "args": ["mcp"] } } }
```

`nika wire gemini` writes exactly this · it touches only the `mcpServers`
key, so every other setting in the shared file survives, and re-running
prints `· current` (idempotent).

<Note>
  Gemini CLI's policy parser splits server names on underscores — a server
  named `my_server` misbehaves upstream. `nika` is underscore-free, safe
  as-is.
</Note>

## The repo side

`nika init` writes the agent-teaching surface (`AGENTS.md`, rules) plus
the `$schema` modeline for validation and completion on `*.nika.yaml`.

## Verify

`/mcp` in a Gemini CLI session lists `nika` with the nine `nika_*` tools
([the oracle's contract](/reference/mcp-server): validate, explain, schema,
cost — no execution). Then prove the loop end-to-end:
[integrate in 10 minutes](/integrations/quickstart).


# Use Nika with goose
Source: https://docs.nika.sh/integrations/clients/goose

Add the read-only Nika oracle to goose as a stdio extension — plus the AGENTS.md surface goose reads natively. Wiring is manual (no wire target).

[goose](https://github.com/block/goose) (the AAIF agent) discovers MCP
extensions from its config, and reads `AGENTS.md` natively — so `nika init`
in the repo teaches it the language with zero extra wiring. The binary
install is the prerequisite (`brew install supernovae-st/tap/nika` or a
release tarball · [other paths](/getting-started/installation)).

Wiring is manual — `nika wire` has no goose target. Add the oracle as a
stdio extension in goose's config:

```yaml theme={"system"}
extensions:
  nika:
    cmd: nika
    args: [mcp]
    enabled: true
    type: stdio
```

## The repo side

```sh theme={"system"}
nika init
```

`AGENTS.md`, rules and the repo skill land at the repo root — the
agent-teaching surface that makes the oracle useful. goose picks up
`AGENTS.md` on its own.

## Verify

goose's extension list shows `nika` with the nine `nika_*` tools
([the oracle's contract](/reference/mcp-server): validate, explain, schema,
cost — no execution, no mutation). Then prove the loop end-to-end:
[integrate in 10 minutes](/integrations/quickstart).


# Use Nika with Grok Build
Source: https://docs.nika.sh/integrations/clients/grok-build

Grok reads the Claude Code kit natively: two commands install the full Nika plugin (skills, subagents, commands, hooks, oracle) · zero commands on a machine that already runs it in Claude Code.

Grok Build reads Claude Code marketplaces, plugins, skills, MCPs, agents,
hooks and instruction files natively (per xAI's own compatibility contract),
so the Nika kit installs unported. Binary first
(`brew install supernovae-st/tap/nika` ·
[other paths](/getting-started/installation)):

```sh theme={"system"}
grok plugin marketplace add supernovae-st/nika-agents
grok plugin install nika@nika --trust
```

`--trust` is load-bearing, not ceremony: without it grok refuses the install
outright (plugins can run hooks, MCP servers and skills on your machine),
and even a later trust grant is what activates the plugin's hooks and MCP.

## Zero-config on a Claude Code machine

If the machine already runs the Nika plugin in Claude Code, grok picks up
the marketplace and the components from the Claude surfaces on its own ·
components dedup by name and a grok-side install takes priority. Verified
live: adding the marketplace answered `already configured` before we ever
taught grok about it.

## What loads (verified live 2026-08-02 · grok 0.2.117 · nika 0.107.0)

* the 4 skills (authoring · debugging · operating · migration)
* the 6 `/nika:*` commands (check · explain · new · trace · permits · doctor)
* the 3 subagents (`nika:nika-author` · `nika:nika-debugger` · `nika:nika-migrator`)
* the hook file (session map · check-on-edit · guard-run · claude dialect,
  registered as a unit)
* the read-only MCP oracle (9 tools · no execution by design)

## Prove it (deterministic · no model call · CI-able)

```sh theme={"system"}
grok inspect --json      # every component with its origin (the nika plugin path)
grok mcp doctor --json   # nika: command found · server started · handshake OK · 9 tools discovered
```

Trust those two outputs, not a model's enumeration · `inspect` names each
loaded skill, agent, hook and MCP server with the file it came from.

## Optional native presence

The project `.mcp.json` that ships with the kit is read natively. For a
machine-level stanza in grok's own dialect:

```toml theme={"system"}
# ~/.grok/config.toml
[mcp_servers.nika]
command = "nika"
args = ["mcp"]
```

## Caveats worth knowing

* Plugins stay OFF until enabled, and a plugin's hooks and MCP stay inactive
  until trusted · the refusal message teaches the exact re-run.
* Enterprise deployments can require pinned-commit installs
  (`require_sha`) · release tags satisfy it.
* Grok enforces version floors at startup · pin deliberately in CI.

Then `nika init` in the repo · the agent-teaching surface (`AGENTS.md`, the
`.agents/skills` authoring skill, editor wiring) is read natively and is
what makes the oracle useful ([agents guide](/getting-started/agents)).


# Use Nika with Jan
Source: https://docs.nika.sh/integrations/clients/jan

Add the read-only Nika oracle to Jan as a stdio MCP server — a fully local pairing. Wiring is manual (no wire target).

[Jan](https://github.com/janhq/jan) — the local-first assistant —
configures MCP servers in its settings. Add Nika as a **stdio** server.
The binary comes first: `brew install supernovae-st/tap/nika`
([other paths](/getting-started/installation)).

Wiring is manual — `nika wire` has no Jan target. The three fields,
whichever form the settings take:

| Field   | Value   |
| ------- | ------- |
| type    | `stdio` |
| command | `nika`  |
| args    | `mcp`   |

Equivalently, where Jan accepts the JSON form:

```json theme={"system"}
{ "mcpServers": { "nika": { "command": "nika", "args": ["mcp"] } } }
```

## A fully local pairing

Jan runs the model on your machine; Nika runs workflows on local models
with the same sovereignty (`ollama/…`, no key, no meter) — see the
[local models guide](/guides/local-models). The oracle itself is read-only:
validation, explanation, schema and cost answers, no execution
([the contract](/reference/mcp-server)).

## Verify

Jan's MCP server list shows `nika` with the nine `nika_*` tools. Then
prove the loop end-to-end:
[integrate in 10 minutes](/integrations/quickstart).


# Use Nika with Junie
Source: https://docs.nika.sh/integrations/clients/junie

Add the read-only Nika oracle to JetBrains Junie via project-scope .junie/mcp/mcp.json — the stanza today, one wire command in the next release.

[Junie](https://www.jetbrains.com/junie/) — JetBrains' coding agent —
reads MCP servers from project-scope `.junie/mcp/mcp.json` (`mcpServers`
root). The binary comes first: `brew install supernovae-st/tap/nika`
([other paths](/getting-started/installation)).

Create `.junie/mcp/mcp.json` at the repo root:

```json theme={"system"}
{ "mcpServers": { "nika": { "command": "nika", "args": ["mcp"] } } }
```

A global `~/.junie/mcp/mcp.json` exists too, but the project file is the
least-privilege home — the repo the oracle serves, same reasoning as
[OpenCode](/integrations/opencode).

`nika wire junie` ships in the next release and writes exactly this —
idempotent, unrelated servers preserved.

## The repo side

`nika init` writes the agent-teaching surface (`AGENTS.md`, rules) plus
the `$schema` modeline for validation and completion on `*.nika.yaml`.

## Verify

Junie's MCP listing shows `nika` with the nine `nika_*` tools
([the oracle's contract](/reference/mcp-server): validate, explain, schema,
cost — no execution, no mutation). Then prove the loop end-to-end:
[integrate in 10 minutes](/integrations/quickstart).


# Use Nika with Kimi Code CLI
Source: https://docs.nika.sh/integrations/clients/kimi-code

Add the read-only Nika oracle to kimi-code's mcp.json — the exact file contract, the one trap from the legacy CLI, and the deterministic proof.

[Kimi Code CLI](https://github.com/MoonshotAI/kimi-code) reads MCP servers
from `mcp.json` at two levels: user `~/.kimi-code/mcp.json` (shared across
projects) and project `.kimi-code/mcp.json` (a same-named project entry
wins). The binary comes first: `brew install supernovae-st/tap/nika`
([other paths](/getting-started/installation)).

Add the `nika` entry to `~/.kimi-code/mcp.json`:

```json theme={"system"}
{ "mcpServers": { "nika": { "command": "nika", "args": ["mcp"] } } }
```

Or conversationally: `/mcp-config` in the TUI adds servers without
hand-editing JSON · `/mcp` shows connection status.

<Warning>
  The legacy kimi-cli taught `kimi mcp add …` — **that subcommand does not
  exist in kimi-code**, its successor. The file above is the contract.
  Kimi's own docs also warn that project-level stdio entries execute when a
  session starts: trust-scope the project file accordingly.
</Warning>

## Prove it (deterministic · verified live 2026-07-31 · kimi-code 0.30.0 · nika 0.106.1)

A headless run emits one JSON object per line, tool calls included — the
oracle answering IS the receipt:

```sh theme={"system"}
kimi -p "Call the mcp__nika__nika_canon tool with no arguments and stop." \
  --output-format stream-json
```

The stream carries
`"tool_calls":[{"function":{"name":"mcp__nika__nika_canon"}}]` — the
server loaded and the agent reached it. `kimi doctor` validates the
config files (exit 0/1).

## The repo side

`nika init` writes the `.agents/skills` authoring skill — kimi-code scans
four skill tiers including project and user `.agents/skills/`, so the
skill surfaces as `/skill:nika-authoring` with zero extra wiring. Note
that kimi-code does not auto-load `AGENTS.md` today: the skill and the
oracle carry the teaching ([agents guide](/getting-started/agents)).

Division of labor unchanged: Kimi orchestrates and writes code · Nika
runs the repeatable work as a checkable file with receipts — `nika check`
before, `--max-cost-usd` during, `nika trace verify` after.


# Use Nika with LM Studio
Source: https://docs.nika.sh/integrations/clients/lm-studio

Add the read-only Nika oracle to LM Studio's mcp.json — the real macOS path quirk included; one wire command in the next release.

[LM Studio](https://lmstudio.ai) (v0.3.17+) follows Cursor's `mcp.json`
notation. The safe path is in-app — `Program` tab →
`Install > Edit mcp.json` — then add:

```json theme={"system"}
{ "mcpServers": { "nika": { "command": "nika", "args": ["mcp"] } } }
```

The binary comes first: `brew install supernovae-st/tap/nika`
([other paths](/getting-started/installation)).

## Where the file lives

LM Studio documents `~/.lmstudio/mcp.json` (macOS + Linux;
`%USERPROFILE%\.lmstudio` on Windows) — but on some macOS installs the app
actually keeps it under `~/.cache/lm-studio/` instead
(lmstudio-bug-tracker#1371, open). Writing the documented path there wires
nothing, which is why editing in-app is the safe manual route.

`nika wire lmstudio` ships in the next release and resolves this for you:
whichever app-created directory exists wins (documented location first);
neither existing falls back to the documented default. Idempotent,
unrelated servers preserved.

## Verify

LM Studio's MCP listing shows `nika` with the nine `nika_*` tools
([the oracle's contract](/reference/mcp-server): validate, explain, schema,
cost — no execution, no mutation). A fully local pairing: LM Studio serves
the model, Nika runs the workflow —
[local models guide](/guides/local-models). Then prove the loop
end-to-end: [integrate in 10 minutes](/integrations/quickstart).


# Use Nika with Open WebUI
Source: https://docs.nika.sh/integrations/clients/open-webui

The mcpo recipe: proxy the read-only Nika oracle as an OpenAPI tool server and register it in Open WebUI. Wiring is manual (no wire target).

[Open WebUI](https://github.com/open-webui/open-webui) consumes OpenAPI
tool servers, and its companion proxy
[mcpo](https://github.com/open-webui/mcpo) turns any stdio MCP server into
one. That is the recipe for Nika: run the oracle behind mcpo, register the
endpoint.

Wiring is manual — `nika wire` has no Open WebUI target.

## The recipe

The binary comes first: `brew install supernovae-st/tap/nika`
([other paths](/getting-started/installation)). Then:

```sh theme={"system"}
uvx mcpo --port 8000 -- nika mcp
```

mcpo serves the oracle's nine `nika_*` tools as OpenAPI endpoints (the
interactive docs appear at `http://localhost:8000/docs`). Register
`http://localhost:8000` as a tool server in Open WebUI — its
[mcpo guide](https://github.com/open-webui/mcpo#readme) shows where — and
the tools appear in chat.

## What you get

Validation, explanation, schema and cost answers with receipts — no
execution, no mutation, by design
([the oracle's contract](/reference/mcp-server)). Running workflows stays
on the terminal, where the budget flags and traces live.

## Verify

Ask a chat with the tool server enabled to check a workflow — the
`nika_check` call shows up in the response's tool trail. Then prove the
loop end-to-end: [integrate in 10 minutes](/integrations/quickstart).


# Use Nika with Qwen Code
Source: https://docs.nika.sh/integrations/clients/qwen-code

Add the read-only Nika oracle to Qwen Code's settings.json — same key as Gemini CLI, its own dotdir; one wire command in the next release.

[Qwen Code](https://github.com/QwenLM/qwen-code) is a Gemini CLI fork —
same `mcpServers` key, same user-scope `settings.json`, its own dotdir.
The binary comes first: `brew install supernovae-st/tap/nika`
([other paths](/getting-started/installation)).

Add the `nika` entry to `~/.qwen/settings.json`:

```json theme={"system"}
{ "mcpServers": { "nika": { "command": "nika", "args": ["mcp"] } } }
```

`nika wire qwen` ships in the next release and writes exactly this —
only the `mcpServers` key is touched, every other setting survives, and
re-running prints `· current` (idempotent).

## The repo side

`nika init` writes the agent-teaching surface (`AGENTS.md`, rules) plus
the `$schema` modeline for validation and completion on `*.nika.yaml`.

## Verify

Qwen Code's MCP listing shows `nika` with the nine `nika_*` tools
([the oracle's contract](/reference/mcp-server): validate, explain, schema,
cost — no execution, no mutation). Then prove the loop end-to-end:
[integrate in 10 minutes](/integrations/quickstart).


# Use Nika with VS Code and Copilot
Source: https://docs.nika.sh/integrations/clients/vscode

One command writes a repo-local .vscode/mcp.json for VS Code and Copilot agent mode — plus the marketplace extension with LSP and DAG canvas.

One command, or one click — binary first
(`brew install supernovae-st/tap/nika` ·
[other paths](/getting-started/installation)):

```sh theme={"system"}
nika wire vscode
```

[![Install in VS Code](https://img.shields.io/badge/VS_Code-install%20nika%20mcp-0098FF?logo=githubcopilot)](https://insiders.vscode.dev/redirect/mcp/install?name=nika\&config=%7B%22command%22%3A%20%22nika%22%2C%20%22args%22%3A%20%5B%22mcp%22%5D%7D)

## What it writes

`.vscode/mcp.json` in the current repo (`--dir` picks another workspace) —
VS Code's own MCP file, `servers` key, `stdio` type. Idempotent; unrelated
servers survive. The same block by hand:

```json theme={"system"}
{ "servers": { "nika": { "type": "stdio", "command": "nika", "args": ["mcp"] } } }
```

## The rest of the VS Code surface

* The [marketplace extension](https://marketplace.visualstudio.com/items?itemName=supernovae.nika-lang)
  — LSP, DAG canvas, preflight.
* `nika init` writes `.github/copilot-instructions.md` and the
  `.vscode/settings.json` schema mapping (validation + completion in any
  YAML-aware editor).

## Verify

Open Copilot's agent-mode tools list — the nine `nika_*` tools appear
([the oracle's contract](/reference/mcp-server)). Then prove the loop
end-to-end: [integrate in 10 minutes](/integrations/quickstart).


# Use Nika with Windsurf
Source: https://docs.nika.sh/integrations/clients/windsurf

One command wires the read-only Nika oracle into Windsurf's mcp_config.json — the exact path, the stanza, and the verify step.

One command — binary first (`brew install supernovae-st/tap/nika` ·
[other paths](/getting-started/installation)):

```sh theme={"system"}
nika wire windsurf
```

## What it writes

`~/.codeium/windsurf/mcp_config.json` — the `nika` entry under
`mcpServers`; every unrelated server survives, re-running prints
`· current` (idempotent). The same block by hand:

```json theme={"system"}
{ "mcpServers": { "nika": { "command": "nika", "args": ["mcp"] } } }
```

## The repo side

`nika init` writes the agent-teaching surface (`AGENTS.md`, rules, the repo
skill) plus the `$schema` modeline that gives any YAML-aware editor
validation and completion on `*.nika.yaml`.

## Verify

Windsurf's MCP server list shows `nika` with the nine `nika_*` tools
([the oracle's contract](/reference/mcp-server): validate, explain, schema,
cost — no execution, no mutation). Then prove the loop end-to-end:
[integrate in 10 minutes](/integrations/quickstart).


# Use Nika with Zed
Source: https://docs.nika.sh/integrations/clients/zed

Wire the read-only Nika oracle into Zed's context_servers — one command that respects your commented settings.json, plus the manual stanza.

One command — binary first (`brew install supernovae-st/tap/nika` ·
[other paths](/getting-started/installation)):

```sh theme={"system"}
nika wire zed
```

## What it writes

`~/.config/zed/settings.json` — on **every** platform, macOS included
(Zed's deliberate upstream choice). The entry lands under
`context_servers`, the shape from
[zed.dev/docs/ai/mcp](https://zed.dev/docs/ai/mcp):

```json theme={"system"}
{ "context_servers": { "nika": { "command": "nika", "args": ["mcp"], "env": {} } } }
```

<Note>
  Zed's `settings.json` is JSONC — the default file ships with comments, and
  comments would be destroyed by a rewrite. `nika wire zed` only rewrites a
  file it can round-trip losslessly; if yours carries comments it prints the
  exact snippet (`✋ manual`) and leaves the file byte-identical. Paste the
  `"nika"` entry into `context_servers` yourself.
</Note>

## Verify

Zed's agent panel lists `nika` among its context servers, with the nine
`nika_*` tools ([the oracle's contract](/reference/mcp-server)). The repo
side comes from `nika init` — `AGENTS.md` plus the `$schema` modeline for
validation and completion. Then prove the loop end-to-end:
[integrate in 10 minutes](/integrations/quickstart).


# Everywhere Nika meets you
Source: https://docs.nika.sh/integrations/everywhere

The complete map: every install path, IDE, agent, skill, plugin, CI surface, SDK and registry where Nika ships — one page, categorized.

One binary, many doors. This page is the single map of **every surface Nika
ships on** — pick your door, each row links to the exact guide.

<Info>
  The one-liner everywhere: `brew install supernovae-st/tap/nika` — then
  `nika init` teaches whatever agent you run.
</Info>

## Install paths

| Surface                  | What you get                                                                                                                                                                       | Where                                                                    |
| ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------ |
| **Homebrew tap**         | `brew install supernovae-st/tap/nika` (macOS + Linux)                                                                                                                              | [Quickstart](/integrations/quickstart)                                   |
| **Release tarballs**     | per-platform binaries + `SHA256SUMS` (verify before you trust)                                                                                                                     | [GitHub releases](https://github.com/supernovae-st/nika/releases/latest) |
| **`install.sh`**         | one-command install from the site                                                                                                                                                  | [nika.sh/install](https://nika.sh/install)                               |
| **cargo binstall**       | the prebuilt release tarball, no compile (`cargo binstall --git https://github.com/supernovae-st/nika nika-cli`)                                                                   | [Installation](/getting-started/installation)                            |
| **nix flake**            | `nix run github:supernovae-st/nika` — builds the exact release source, store-cached                                                                                                | [Installation](/getting-started/installation)                            |
| **GitHub CLI extension** | `gh extension install supernovae-st/gh-nika` → `gh nika check/run` — pass-through to a PATH `nika`, else a one-time checksum-verified release fetch (Actions runners · Codespaces) | [gh-nika](https://github.com/supernovae-st/gh-nika)                      |
| **`.mcpb` bundles**      | one-click MCP bundle (macOS arm64 · Linux x64) with checksums                                                                                                                      | [Claude Desktop guide](/integrations/clients/claude-desktop)             |
| **Docker image**         | the read-only oracle in a container (`integrations/mcp/Dockerfile` in the kit)                                                                                                     | [nika-agents kit](https://github.com/supernovae-st/nika-agents)          |

## Keeping the suite fresh

Every surface below invokes the **binary**, and the plugin kits ride its
release train — but no surface updates another: brew never touches a
plugin, a marketplace never touches the binary. The ladder, per surface:

| Surface                   | Update gesture                                                                                        | Note                                                   |
| ------------------------- | ----------------------------------------------------------------------------------------------------- | ------------------------------------------------------ |
| **Binary**                | `brew upgrade nika`                                                                                   | patch releases ship binary-only                        |
| **Claude Code plugin**    | `claude plugin marketplace update nika` **then** `claude plugin update nika@nika`                     | TWO rungs — the clone, then the install; restart after |
| **Codex plugin**          | `codex plugin marketplace upgrade nika`                                                               | the per-version cache refreshes on your next run       |
| **Cursor**                | marketplace installs self-manage; a local drop re-syncs via the kit's `scripts/update-mirrors.sh`     | —                                                      |
| **Every surface at once** | `scripts/update-mirrors.sh` in a [nika-agents](https://github.com/supernovae-st/nika-agents) checkout | `--check` reports drift read-only (CI-able)            |

<Info>
  `nika doctor` is the coherence oracle: from v0.107 it reads what each
  client actually loads, names any kit lagging or leading the binary's
  train, and prints the exact per-client fix. Drift is advisory
  (warn · exit 0) — a diagnosis never breaks automation.
</Info>

## IDEs & editors

| Surface                      | Mechanism                                                                                                                                                      | Where                                                   |
| ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------- |
| **VS Code**                  | extension on the [Marketplace](https://marketplace.visualstudio.com/items?itemName=supernovae.nika-lang) (LSP · DAG canvas · preflight)                        | [VS Code / Copilot guide](/integrations/clients/vscode) |
| **Cursor**                   | marketplace plugin (skill · subagent · commands · check-on-edit hook · MCP, one Add) + `nika wire cursor` + `nika init` (`.cursor/rules` + `.cursor/mcp.json`) | [Cursor guide](/integrations/clients/cursor)            |
| **Windsurf**                 | `nika wire windsurf`                                                                                                                                           | [Windsurf guide](/integrations/clients/windsurf)        |
| **Zed**                      | `nika wire zed` (0.99+)                                                                                                                                        | [Zed guide](/integrations/clients/zed)                  |
| **JetBrains (Junie)**        | project-scope `.junie/mcp/mcp.json` stanza                                                                                                                     | [Junie guide](/integrations/clients/junie)              |
| **Cursor forks / VSCodium**  | extension via [OpenVSX](https://open-vsx.org/extension/supernovae/nika)                                                                                        | —                                                       |
| **Neovim**                   | via the mcphub.nvim registry (covers avante · codecompanion)                                                                                                   | [MCP clients](/integrations/mcp-clients)                |
| **Any editor with YAML-LSP** | the `# yaml-language-server: $schema=` modeline `nika init` writes                                                                                             | [Editors guide](/getting-started/editors)               |

## Agents & assistants

| Surface                                            | Mechanism                                                                                                                                                | Where                                                                                                                                                                                       |
| -------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Claude Code**                                    | first-party plugin (`.claude-plugin` · the six `/nika:*` commands · 4 skills · 3 subagents) + `nika wire claude`                                         | [Claude Code guide](/integrations/clients/claude-code)                                                                                                                                      |
| **Claude Desktop**                                 | `claude_desktop_config.json` stanza + one-click `.mcpb` bundles                                                                                          | [Claude Desktop guide](/integrations/clients/claude-desktop)                                                                                                                                |
| **Codex**                                          | first-party plugin (`.codex-plugin` · same commands) + `nika wire codex`                                                                                 | [Codex guide](/integrations/clients/codex)                                                                                                                                                  |
| **Grok Build**                                     | reads the Claude Code kit natively · one marketplace add installs the full plugin (skills · subagents · commands · hooks · oracle)                       | [Grok Build guide](/integrations/clients/grok-build)                                                                                                                                        |
| **Hermes**                                         | skill pack (`skills/autonomous-ai-agents/nika` · guard-scanned SAFE)                                                                                     | [Hermes guide](/integrations/hermes)                                                                                                                                                        |
| **OpenCode**                                       | `opencode.json` MCP stanza + native `.agents/` reading — `nika init` suffices                                                                            | [OpenCode guide](/integrations/opencode)                                                                                                                                                    |
| **goose**                                          | MCP extension stanza + native `AGENTS.md` reading                                                                                                        | [goose guide](/integrations/clients/goose)                                                                                                                                                  |
| **Gemini CLI · Qwen Code**                         | `mcpServers` stanza in the user-scope `settings.json`                                                                                                    | [Gemini CLI](/integrations/clients/gemini-cli) · [Qwen Code](/integrations/clients/qwen-code)                                                                                               |
| **Kimi Code CLI**                                  | `mcpServers` entry in `~/.kimi-code/mcp.json` + the `.agents/skills` authoring skill discovered natively                                                 | [Kimi Code guide](/integrations/clients/kimi-code)                                                                                                                                          |
| **Warp (Oz)**                                      | reads the Claude Code and Codex configs plus the project `.mcp.json` natively — `nika wire claude` or `nika init` opens this door                        | [MCP clients](/integrations/mcp-clients)                                                                                                                                                    |
| **GitHub Copilot CLI**                             | reads the project `.mcp.json` (cwd up to repo root) and `AGENTS.md` — `nika init` covers both · `copilot mcp add nika -- nika mcp` for the machine level | [MCP clients](/integrations/mcp-clients)                                                                                                                                                    |
| **Amp**                                            | reads `AGENTS.md` and the `.agents/skills` dir natively (both written by `nika init`) · `amp mcp add nika -- nika mcp` wires the oracle                  | [MCP clients](/integrations/mcp-clients)                                                                                                                                                    |
| **Cline · Continue**                               | `cline_mcp_settings.json` (hot-reloaded) · own-file `~/.continue/mcpServers/nika.json`                                                                   | [Cline](/integrations/clients/cline) · [Continue](/integrations/clients/continue)                                                                                                           |
| **Open WebUI · AnythingLLM · Cherry Studio · Jan** | mcpo recipe · generic stdio stanza                                                                                                                       | [Open WebUI](/integrations/clients/open-webui) · [AnythingLLM](/integrations/clients/anythingllm) · [Cherry Studio](/integrations/clients/cherry-studio) · [Jan](/integrations/clients/jan) |
| **Aider**                                          | no MCP — `AGENTS.md` (written by `nika init`) covers it                                                                                                  | [MCP clients → Aider](/integrations/mcp-clients#aider)                                                                                                                                      |
| **Any AGENTS.md reader**                           | `nika init` writes 7 agent-facing files (AGENTS.md · `.cursor/{rules,mcp.json}` included)                                                                | [Quickstart](/integrations/quickstart)                                                                                                                                                      |

## Skills & plugins (the teaching surfaces)

| Element                      | What it is                                                                                                             | Lives at                                                          |
| ---------------------------- | ---------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------- |
| **SKILL.md pack**            | the authoring skill (check-before-run law · cost honesty) — installable via `npx skills add supernovae-st/nika-agents` | [nika-agents kit](https://github.com/supernovae-st/nika-agents)   |
| **Plugin commands**          | the six `/nika:*` commands (check · explain · new · trace · permits · doctor) mirrored from the engine                 | kit `.agents/plugins/nika/`                                       |
| **`nika-author` subagent**   | routes an intent to a template, fills the `# SLOT:` markers, loops `nika check` until rc=0 — read-only                 | kit `.agents/plugins/nika/agents/`                                |
| **Integration kit contract** | « You want to support Nika? Copy this folder » — pinned mirrors, drift-gated in CI                                     | [kit README](https://github.com/supernovae-st/nika-agents#readme) |

## MCP (the read-only oracle)

`nika mcp` exposes 9 tools — validate, explain, examples, schema, cost — **no
execution, no mutation, by design** ([threat model](https://github.com/supernovae-st/nika-agents/blob/main/integrations/mcp/THREAT-MODEL.md)).

| Element                                                        | Where                                                                                              |
| -------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
| Full tool reference                                            | [MCP server reference](/reference/mcp-server)                                                      |
| Per-client wiring (one dedicated page per client — the matrix) | [MCP clients](/integrations/mcp-clients)                                                           |
| `server.json` (registry shape) + bundles + Dockerfile          | [kit `integrations/mcp/`](https://github.com/supernovae-st/nika-agents/tree/main/integrations/mcp) |

## CI/CD

| Element                                | What it does                                                                                                   | Where                                                                                                       |
| -------------------------------------- | -------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
| **nika-action** — *plan with receipts* | check verdict · honest cost floor · permits · the DAG, as a sticky PR comment. Static, zero secrets by default | [GitHub Actions guide](/integrations/github-actions) · [repo](https://github.com/supernovae-st/nika-action) |
| **Offline test lane**                  | `nika test` golden runs on the mock provider — CI with no API key                                              | [Local-first tutorial](/examples/local-first-daily-brief)                                                   |

## SDKs & language surfaces

| Element                  | What it is                                                                                                                                                                             | Where                                                           |
| ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------- |
| **TypeScript client**    | `LocalNika` — typed driver over the shipped binary (check · run stream · dry-run plan) · Apache-2.0                                                                                    | [nika-client](https://github.com/supernovae-st/nika-client)     |
| **Language spec**        | the `.nika.yaml` contract — Apache-2.0, runtime-agnostic                                                                                                                               | [nika-spec](https://github.com/supernovae-st/nika-spec)         |
| **Registry**             | CI-re-proven workflow artifacts (hash + oracle + engine cert) — the engine pulls them natively: `nika check registry:owner/name` (digest verify · cache · the normal audit-before-run) | [nika-registry](https://github.com/supernovae-st/nika-registry) |
| **Sovereign local lane** | `nika model serve --model x.gguf` — the in-process candle sidecar (loopback · in every release binary from 0.101) · `pull`/`list`/`rm` acquire and manage GGUFs                        | [CLI reference](/reference/cli)                                 |

## Where Nika is listed

Marketplaces and directories where you'll find us today — the public
submissions ledger (with pinned descriptions and review cadence) lives in
[`listings.yaml`](https://github.com/supernovae-st/nika-agents/blob/main/listings.yaml).

* [VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=supernovae.nika-lang) · [OpenVSX](https://open-vsx.org/extension/supernovae/nika) — the extension
* [skills.sh](https://skills.sh/supernovae-st/nika-agents) — the skill pack
* GitHub topics + release feeds — engine · kit · action · docs · spec · client
* More MCP registries and community catalogs are in flight — the ledger above
  is the always-current truth (every submission registers there the day it
  goes out).

## Learn the patterns first

New to agentic workflows as a concept? [agentic-ai-systems](https://github.com/ThibautMelen/agentic-ai-systems)
(282★) teaches the workflow taxonomy with diagrams — and its
[patterns-as-code](https://github.com/ThibautMelen/agentic-ai-systems/tree/main/patterns-as-code)
folder expresses each pattern as a runnable `.nika.yaml`, checked in CI on
every push.

<Tip>
  Something missing? The kit contract makes adding a surface a folder-copy:
  [`nika-agents`](https://github.com/supernovae-st/nika-agents) — and the
  [integration quickstart](/integrations/quickstart) is the 10-minute path.
</Tip>


# Nika × GitHub Actions
Source: https://docs.nika.sh/integrations/github-actions

Plan with receipts on every PR: the check verdict, the honest cost floor, required secrets and the DAG — before anyone runs anything.

[`supernovae-st/nika-action`](https://github.com/supernovae-st/nika-action)
turns every PR that touches a `.nika.yaml` into a reviewed plan: a sticky
comment with the `nika check` verdict, the cost floor (never a fake zero),
the models and secrets the change needs, its egress statics, and the DAG —
rendered natively by GitHub as mermaid.

```yaml theme={"system"}
name: nika
on:
  pull_request:
    paths: ['**.nika.yaml']  # fire only when a workflow file changes
permissions:
  contents: read
  pull-requests: write     # drop it and the body lands in the step summary
jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      # in real use, pin by full commit SHA with the release in a comment —
      # the form Dependabot/Renovate bump: @<sha> # v1.0.2
      - uses: supernovae-st/nika-action@v1
        with:
          workflow: flows/report.nika.yaml
          mode: check        # or: test → adds the offline mock golden lane
```

No workflow yet? `nika new flows/report.nika.yaml --from chain` scaffolds
one — [authoring in 10 minutes](/integrations/quickstart).

## Already have CI? One line

The starter repo publishes a **reusable workflow** that wraps the action
with the same fork-safe posture — adopting the check in an existing repo
is a single `uses:` block:

```yaml theme={"system"}
jobs:
  nika:
    permissions:
      contents: read
      pull-requests: write
    uses: supernovae-st/nika-actions-starter/.github/workflows/nika-check.yml@main
    with:
      workflow: path/to/your.nika.yaml
```

Starting fresh instead? [`nika-actions-starter`](https://github.com/supernovae-st/nika-actions-starter)
is a template repo — **Use this template**, and the verdict lands on your
first PR with zero further wiring. Its own pull requests run the check
live, so you can read a real sticky comment before adopting anything.

## What lands on the PR

> ✅ **nika check** — clean · `flows/report.nika.yaml` · 3 task(s) · 3 wave(s)
> 💰 \*\*cost floor ≥ $0.12** · ⚠ 1 unpriced task — never rendered as $0
> 🔐 **requires** — models: `ollama/qwen3.5:4b` · `mistral/mistral-small-latest` · secrets: `MISTRAL_API_KEY`
> 🌊 **schedule** — 3 wave(s), max width 1
> 🗺 DAG *(collapsible mermaid)*

One comment per workflow file, upserted in place on every push — never
thread spam.

## The lanes — and the missing one

| lane              | runs                                                                                                                                                                                                 | secrets |
| ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
| `check` (default) | static analysis only, nothing executes                                                                                                                                                               | none    |
| `test`            | + `nika test` vs `<file>.golden.json` — mock provider, offline                                                                                                                                       | none    |
| ~~run~~           | **refused by design.** A `.nika.yaml` can declare `exec:` shell steps — executing PR content under a CI token is your decision to make explicitly, in your own workflow, never on fork-origin events | —       |

## Security posture

* The engine download is **verified against the release's `SHA256SUMS`**
  before extraction.
* Fork PRs carry a read-only token: the comment degrades to the **step
  summary** automatically. Never wire any of this via `pull_request_target`
  with a checkout of the PR head.
* Pin the action itself by commit SHA — the marketplace norm.

## Honesty semantics

The comment's cost figure is a **floor** (`spend ≥ floor`); unpriced tasks
render as `unpriced` with their reason verbatim, never `$0`. When the DAG
has parallel waves the comment states the budget bound explicitly: a
mid-run `--max-cost-usd` stops *new* admissions, so the worst-case
overshoot is one full wave (`spend ≤ floor + W · c_max`). The full
semantics: [cost honesty](/guides/cost-honesty).


# Nika × Hermes
Source: https://docs.nika.sh/integrations/hermes

Hermes orchestrates. Nika captures the repeatable work as a checkable file and runs it with receipts — budget-capped, trace-verified.

[Hermes](https://github.com/NousResearch/hermes-agent) is the always-on
orchestrator whose community pattern is delegation: Hermes plans and
coordinates, then hands work to specialist CLIs. Nika slots into exactly
that pattern as **the deterministic workflow worker** — not another coding
agent (that's OpenCode's seat), but the runner for work that should be
*repeatable, budgeted and auditable*.

> **Hermes orchestrates · Nika runs the plan with receipts.**

## Install the skill (day 1 — no catalog wait)

The Nika delegation skill lives in the public marketplace repo and installs
three ways:

```sh theme={"system"}
# as a tap (Hermes scans skills/ by default)
hermes skills tap add supernovae-st/nika-agents
hermes skills install nika

# or single-file from the raw URL
hermes skills install https://raw.githubusercontent.com/supernovae-st/nika-agents/main/skills/autonomous-ai-agents/nika/SKILL.md

# or via the skills.sh CLI
npx skills add supernovae-st/nika-agents
```

New skills take effect next session (or `--now`). The skill teaches the
delegation idiom end-to-end: scaffold via `terminal()`, the
check-before-run law, budget caps on paid models, background+poll for long
runs, and the receipts loop (`nika trace show` · `nika trace verify`).

## Wire the oracle (optional, recommended)

For schema/validation answers without shell round-trips, `nika wire hermes`
(0.99+) writes the oracle into `~/.hermes/config.yaml` for you — or add it
by hand, then `/reload-mcp`:

```yaml theme={"system"}
mcp_servers:
  nika:
    command: nika
    args: [mcp]
    timeout: 120
```

Validation and learning only — running workflows stays on the terminal,
where the budget flags and traces live
([the oracle's contract](/reference/mcp-server)).

## Prove the delegation

In a Hermes session:

> Use the nika skill: smoke-test my nika install offline, then create
> hello.nika.yaml from the chain template, check it, and run it with the
> mock model. Report the trace verify verdict.

Expected: `nika --version` → `nika try 01-hello`
(offline, zero keys) → `nika new chain hello.nika.yaml` → `nika check --json` →
mock run → `nika trace verify <trace>` exit 0 (path from the run card's
`trace:` line — the bare form is a usage error).

## The two clocks

Hermes runs live — its terminal is a pipe, and a long `nika run` renders
quietly until the final card. The skill teaches the fix: launch with
`background=true`, poll with `process(action="poll")`, then read
`nika trace show <trace>` for the run card.

## Cost honesty in delegation

* Always pass `--max-cost-usd` on paid cloud models. Since 0.99 the
  pre-start floor prices the **effective** model (`--model` override
  included): a workflow that prices above the budget **refuses to start**
  (exit 2, zero tokens). Mid-run, the ledger stops the moment real spend
  crosses — the crossing call completes, nothing new starts, the run fails
  `NIKA-1704` (exit 1) with spent-vs-budget.
* Prefer local models for drafts (`ollama/…`) — no key, no meter.
* An **uncataloged** model meters as \$0: never rely on the budget cap for a
  custom endpoint ([cost honesty](/guides/cost-honesty)).

## Field notes (verified on hermes v0.18.2)

Four traps from a real 10-step end-to-end, so you don't pay for them twice:

* **A 401 naming openrouter you never chose.** Hermes's provider
  auto-detect sees `OPENAI_API_KEY` in your shell and routes to OpenRouter
  — the first chat dies with `HTTP 401: Missing Authentication header`
  against `openrouter.ai`. Fix: set `provider:` explicitly in the config
  (`ollama` for local, or your actual vendor).
* **`~/.hermes/config.yaml` IS the live config.** Its header comment says
  "copy this file to cli-config.yaml" — that applies to the hooks layer,
  not the main config. Edit `config.yaml` itself; `mcp_servers:` blocks
  there load on the next session.
* **Trust the log, not the model's word.** The deterministic proof the
  oracle is wired is `~/.hermes/logs/agent.log`:
  `MCP server 'nika' (stdio): registered 9 tool(s)`. In-session the tools
  appear namespaced as `mcp__nika__nika_check`, so a prompt naming a bare
  tool verbatim can miss. Small local models can go further and *narrate* a
  delegation they never executed — receipts come from the terminal
  (`nika trace verify`), never from prose. Drive the delegation loop with a
  capable model.
* **Pass `workdir` on every terminal call.** The skill teaches it; a driver
  that skips it runs the workflow from Hermes's own cwd and relative reads
  fail (`NIKA-BUILTIN-READ-001` on a file that exists in your project).


# Per-client MCP wiring
Source: https://docs.nika.sh/integrations/mcp-clients

One stanza, every client: Cursor, Claude Code, Codex, Zed, Gemini CLI, Windsurf, Continue, Cline, Aider — one dedicated page per tool.

Every MCP-capable client wires the same read-only oracle
([what it exposes](/reference/mcp-server)) with the same two fields —
`command: nika` · `args: [mcp]`. The binary comes first:
`brew install supernovae-st/tap/nika` ([other paths](/getting-started/installation)).
This page is the matrix; every client has a dedicated page with the exact
file, shape, reload behavior and verify step.

One-click where the client supports it (binary still required first):

[![Install in VS Code](https://img.shields.io/badge/VS_Code-install%20nika%20mcp-0098FF?logo=githubcopilot)](https://insiders.vscode.dev/redirect/mcp/install?name=nika\&config=%7B%22command%22%3A%20%22nika%22%2C%20%22args%22%3A%20%5B%22mcp%22%5D%7D)
[![Install MCP Server](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en/install-mcp?name=nika\&config=eyJjb21tYW5kIjogIm5pa2EiLCAiYXJncyI6IFsibWNwIl19)

And in every case, `nika init` first — the agent-teaching surface
(`AGENTS.md`, rules, the repo skill) is what makes the oracle useful.

## The client matrix

| Client                                                                | Wire                           | Where it lands                                |
| --------------------------------------------------------------------- | ------------------------------ | --------------------------------------------- |
| [Claude Code](/integrations/clients/claude-code)                      | `nika wire claude`             | `~/.claude.json`                              |
| [Claude Desktop](/integrations/clients/claude-desktop)                | `nika wire claude-desktop`     | `claude_desktop_config.json` (app-config dir) |
| [VS Code / Copilot](/integrations/clients/vscode)                     | `nika wire vscode`             | `.vscode/mcp.json` (repo-local)               |
| [Cursor](/integrations/clients/cursor)                                | `nika wire cursor`             | `~/.cursor/mcp.json`                          |
| [Windsurf](/integrations/clients/windsurf)                            | `nika wire windsurf`           | `~/.codeium/windsurf/mcp_config.json`         |
| [Zed](/integrations/clients/zed)                                      | `nika wire zed`                | `~/.config/zed/settings.json`                 |
| [Codex](/integrations/clients/codex)                                  | `nika wire codex`              | `~/.codex/config.toml`                        |
| [OpenCode](/integrations/opencode)                                    | `nika wire opencode`           | `opencode.json` (repo-local)                  |
| [Hermes](/integrations/hermes)                                        | `nika wire hermes`             | `~/.hermes/config.yaml`                       |
| [Gemini CLI](/integrations/clients/gemini-cli)                        | `nika wire gemini`             | `~/.gemini/settings.json`                     |
| [Qwen Code](/integrations/clients/qwen-code)                          | `nika wire qwen`               | `~/.qwen/settings.json`                       |
| [Cline](/integrations/clients/cline)                                  | `nika wire cline`              | `cline_mcp_settings.json` (resolved)          |
| [Continue](/integrations/clients/continue)                            | `nika wire continue`           | `~/.continue/mcpServers/nika.json`            |
| [LM Studio](/integrations/clients/lm-studio)                          | `nika wire lmstudio`           | `~/.lmstudio/mcp.json` (resolved)             |
| [Junie](/integrations/clients/junie)                                  | `nika wire junie`              | `.junie/mcp/mcp.json` (repo-local)            |
| [goose](/integrations/clients/goose)                                  | manual stanza                  | goose config `extensions:`                    |
| [Open WebUI](/integrations/clients/open-webui)                        | manual — mcpo recipe           | OpenAPI tool server                           |
| [AnythingLLM](/integrations/clients/anythingllm)                      | manual stanza                  | its `mcpServers` file                         |
| [Cherry Studio](/integrations/clients/cherry-studio)                  | manual stanza                  | settings UI (stdio)                           |
| [Jan](/integrations/clients/jan)                                      | manual stanza                  | settings UI (stdio)                           |
| [Aider](#aider)                                                       | no MCP — `AGENTS.md` covers it | `.aider.conf.yml`                             |
| Every `nika wire` write is idempotent (re-run prints `· current`) and |                                |                                               |
| preserves unrelated servers.                                          |                                |                                               |

The anchors below stay for directory deep-links — each points to its
dedicated page.

## Cursor

`nika wire cursor` → `~/.cursor/mcp.json`, plus the one-click deeplink and
the auto-attached `.cursor/rules/nika.mdc` —
[full page](/integrations/clients/cursor).

## Claude Code

`nika wire claude` → `~/.claude.json`, plus the first-party plugin
(`claude plugin install nika@nika`) —
[full page](/integrations/clients/claude-code).

## Codex

`nika wire codex` → `~/.codex/config.toml` (comments preserved), plus the
plugin — [full page](/integrations/clients/codex).

## VS Code / Copilot

`nika wire vscode` → repo-local `.vscode/mcp.json`, plus the marketplace
extension — [full page](/integrations/clients/vscode).

## Zed

`nika wire zed` → `context_servers` in `~/.config/zed/settings.json`, with
the JSONC-respecting contract —
[full page](/integrations/clients/zed).

## Gemini CLI

The `mcpServers` stanza in `~/.gemini/settings.json` (wire lands next
release) — [full page](/integrations/clients/gemini-cli).

## Windsurf

`nika wire windsurf` → `~/.codeium/windsurf/mcp_config.json` —
[full page](/integrations/clients/windsurf).

## OpenCode

Native `AGENTS.md` + repo-skill discovery — see the dedicated
[OpenCode page](/integrations/opencode).

## Hermes

Tap-installable delegation skill + `mcp_servers` stanza — see the dedicated
[Hermes page](/integrations/hermes).

## Continue

An own-file drop: `~/.continue/mcpServers/nika.json` — reload to pick it
up — [full page](/integrations/clients/continue).

## Cline

`cline_mcp_settings.json` (hot-reloaded; the file's two possible homes
resolved) — [full page](/integrations/clients/cline).

## LM Studio

Cursor-notation `mcp.json`, with the real macOS path quirk —
[full page](/integrations/clients/lm-studio).

## goose

A stdio extension stanza + native `AGENTS.md` reading —
[full page](/integrations/clients/goose).

## Aider

Aider reads repo conventions rather than MCP: `nika init`'s `AGENTS.md`
covers it (add `CONVENTIONS.md: AGENTS.md` to `.aider.conf.yml` if you keep
conventions elsewhere). The check loop is the same:
`nika check <file>` after every edit.

## Verify (any client)

Ask the agent to list its tools — the nine `nika_*` names should appear.
Then prove the loop end-to-end:
[integrate in 10 minutes](/integrations/quickstart).

> Client config formats move fast. The stable contract is the stanza
> (`nika` + `mcp`) and the oracle's read-only surface — if a client's
> documented path has moved, the stanza still applies.


# Nika × OpenCode
Source: https://docs.nika.sh/integrations/opencode

OpenCode reads everything nika init writes — AGENTS.md, the repo skill — natively. Add one MCP stanza and the loop is complete. Zero packaging.

[OpenCode](https://github.com/anomalyco/opencode) is the open-source,
provider-agnostic terminal coding agent. The division of labor writes
itself: **OpenCode writes code · Nika captures the repeatable AI work as a
checkable file.** No plugin is required — OpenCode natively reads every
surface `nika init` scaffolds.

## Wire it (3 minutes)

**1 · Teach the repo** — OpenCode discovers `AGENTS.md` (project root,
upward traversal, `CLAUDE.md` fallback) and repo skills under
`.agents/skills/` natively:

```sh theme={"system"}
nika init
```

That is the whole teaching step. The `nika-authoring` skill (author → check
→ repair loop) appears in OpenCode's skill tool automatically.

**2 · Wire the oracle** — `nika wire opencode` (0.99+) writes it, or add
the two-field stanza to `opencode.json` yourself (project-local, or
`~/.config/opencode/opencode.json` globally):

```json theme={"system"}
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "nika": { "type": "local", "command": ["nika", "mcp"], "enabled": true }
  }
}
```

OpenCode's own docs warn that heavy MCP servers blow the context budget —
the Nika oracle is the lean counter-example: a handful of read-only
validate/learn tools ([what it exposes and refuses](/reference/mcp-server)).

## Prove the loop

Ask OpenCode:

> Turn my weekly changelog digest into a Nika workflow from the chain
> template, check it, and run it with the mock model.

Expected tool trail: `nika new --from chain` → edit → `nika check` (static
audit, nothing spent) → `nika run … --model mock/echo` (offline) →
receipts in `.nika/traces/`.

## When to reach for which

| task                                                                    | who                                  |
| ----------------------------------------------------------------------- | ------------------------------------ |
| implement/refactor/review code                                          | OpenCode                             |
| a repeated AI pipeline (digest, triage, ETL, report, multi-model bench) | a `.nika.yaml` OpenCode authors once |
| a one-off question                                                      | neither — just answer                |

## Troubleshooting

* **Skill not listed** — OpenCode discovers `.agents/skills/*/SKILL.md`
  from the git worktree root; re-check `nika init` ran at the repo root.
* **MCP server absent** — validate `opencode.json` against its `$schema`;
  the `nika` binary must be on PATH (`nika --version`).
* **Which config wins** — project-local `opencode.json` merges over the
  global file; keep the stanza in one place.


# Nika × pre-commit
Source: https://docs.nika.sh/integrations/pre-commit

Audit every .nika.yaml before it lands: the check verdict — DAG, types, permits, secret flows, cost floor — at commit time, before a single token is spent.

The engine ships a [pre-commit](https://pre-commit.com) manifest, so `nika
check` runs as a hook on every staged `.nika.yaml`. A workflow that names a
missing secret, wires a type mismatch, or quietly widens its permits is
stopped at the commit, with the same named finding and fix the CLI gives you
— not twenty minutes later in CI.

```yaml theme={"system"}
# .pre-commit-config.yaml
repos:
  - repo: https://github.com/supernovae-st/nika
    rev: v0.107.0       # pin a tagged release
    hooks:
      - id: nika-check
```

```bash theme={"system"}
pre-commit install     # once per clone
git commit             # every staged .nika.yaml is audited from now on
```

## What the hook checks

`nika-check` is the full static audit, the same one the
[GitHub Action](/integrations/github-actions) posts on PRs and the
[VS Code extension](https://github.com/supernovae-st/nika-vscode) surfaces
in-editor:

* the **plan** — every task, wave and wire the file declares, as a DAG
* the **types** across each wire, before any model is called
* the **permits boundary** — default-deny, and what the file actually asks for
* the **secret flows** — which secret reaches which task, statically
* the **cost floor** — an honest lower bound, never a fake zero

Nothing executes. The check spends zero tokens, needs zero keys, and works
offline.

## Requirements

The hook is `language: system`: it assumes the `nika` binary on `PATH` —
the same trade [actionlint](https://github.com/rhysd/actionlint)'s system
hook takes. Any install lane works:

```bash theme={"system"}
brew install supernovae-st/tap/nika        # macOS / Linux
cargo binstall nika --git https://github.com/supernovae-st/nika   # prebuilt
nix profile install github:supernovae-st/nika                      # flake
```

Staged files are passed in one argv and audited in one call; each file gets
its full report and the worst exit code survives, so one broken workflow
fails the commit even when its siblings are clean.

## One verdict, every surface

The commit hook, the [PR comment](/integrations/github-actions), the
[MCP oracle](/integrations/mcp-clients) an agent queries, and the editor
diagnostics all run the same check and speak the same findings. If the hook
lets a file through, CI will agree — there is one voice, not four opinions.


# Integrate Nika in 10 minutes
Source: https://docs.nika.sh/integrations/quickstart

Whatever agent you run — Claude Code, Codex, Cursor, OpenCode, Hermes, Zed — two commands teach it Nika, and CI gets receipts.

Nika is not another agent. It is **the workflow file your agents already
run** — checked before, verified after. Integration therefore means two
small things: teach your agent the language, and wire the read-only oracle.

## Minute 0-2 · install the binary

```sh theme={"system"}
brew install supernovae-st/tap/nika    # or: curl -LsSf https://nika.sh/install.sh | sh
nika --version && nika doctor          # doctor prints exact fixes, never mutates
```

No key needed yet — the mock and local providers run without one.

## Minute 2-5 · teach the repo

```sh theme={"system"}
nika init
```

One command writes the agent surface: `AGENTS.md` (read natively by Codex,
Claude Code, Cursor, OpenCode, Hermes, Jules and every AGENTS.md-aware
tool), `CLAUDE.md`, the Cursor rule, the Copilot instructions, the
repo-level [agent skill](https://agentskills.io), and the `.vscode` schema
wiring.
Idempotent — existing files are skipped.

## Minute 5-7 · wire the oracle

```sh theme={"system"}
nika wire cursor     # or: vscode · windsurf · claude · codex · all
```

For clients without a wire target yet (OpenCode, Hermes, Zed, Gemini CLI,
Continue, Cline…), it is the same two-field stanza everywhere — copy it from
[per-client wiring](/integrations/mcp-clients). What the oracle exposes (and
refuses to): [Nika as an MCP server](/reference/mcp-server).

## Minute 7-10 · prove the loop

Ask your agent:

> Create a workflow from the `chain` template that summarizes ./notes.md
> into ./out/brief.md, **check it**, then run it with the mock model.

The agent scaffolds (`nika new --from chain`), audits (`nika check` — plan,
cost floor, permits, **before** any token is spent), runs offline
(`--model mock/echo`), and the receipts land in `.nika/traces/`
(`nika trace verify .nika/traces/<run>.ndjson` → exit 0 — the run card
prints the path on its `trace:` line).

## Then: CI receipts

Put [the GitHub Action](/integrations/github-actions) on the repo — every PR
that touches a `.nika.yaml` gets a sticky comment with the check verdict,
the honest cost floor, required secrets and the DAG. Check-only, zero
secrets, by default.

## The per-tool pages

* [OpenCode](/integrations/opencode) — native skills + AGENTS.md + MCP; zero
  packaging needed.
* [Hermes](/integrations/hermes) — the delegation pattern: Hermes
  orchestrates, Nika runs the repeatable work with receipts.
* [GitHub Actions](/integrations/github-actions) — plan with receipts on
  every PR.
* [Everything MCP-capable](/integrations/mcp-clients) — Cursor · Claude Code
  · Codex · Zed · Gemini CLI · Windsurf · Continue · Cline · Aider, one
  stanza each.


# Introduction
Source: https://docs.nika.sh/introduction

Intent as Code: the workflow language for AI. One file, 4 verbs, one binary. Runs on your laptop.

Useful AI work shouldn't disappear into chats. **Nika turns repeatable AI
work into files you can run, review, diff and share**: one `.nika.yaml`
file, four verbs, one Rust binary. If you do the same AI task twice, make
it a workflow.

<Info>
  Nika runs today: `brew install supernovae-st/tap/nika`, then
  `nika check` and `nika run`. No API key needed for your first run
  (`--model mock/echo` previews any workflow offline).
</Info>

<video>
  <source type="video/webm" />

  <source type="video/mp4" />
</video>

*A repeated chat prompt becomes a workflow file. Real capture: the audit
and the run are the actual CLI output, on a local model (`$0.000`).*

Repeat an AI task weekly? Send it: [nika.sh/convert](https://nika.sh/convert).
We convert the best ones into showcase workflows, credited to you.

## What Nika is

A workflow language plus its reference engine. The YAML file is the
contract: readable by you, writable by your agents, executed
deterministically, audited **before a single token is spent**. Four verbs
(`infer`, `exec`, `invoke`, `agent`) and nothing else; fetching a URL,
writing a file, calling GitHub are all **tools** under `invoke`.

```yaml workflow.nika.yaml theme={"system"}
nika: v1
workflow:
  id: summarize

permits:                                 # the file IS the blast radius
  net: { http: ["example.com"] }         #   one host, nothing else
  fs:  { write: ["/tmp/summary.txt"] }   #   one file, nothing else
  exec: false                            #   this workflow runs zero shells
  tools: ["nika:fetch", "nika:write"]

tasks:
  read:
    invoke:
      tool: nika:fetch
      args:
        url: https://example.com/post.md
        mode: text

  summarize:
    with:
      post: ${{ tasks.read.output }}       # the binding IS the edge
    infer:
      model: ollama/llama3.2:3b            # <provider>/<name> · local · zero key
      prompt: |
        Summarize in one sentence:
        ${{ with.post }}

  save:
    with:
      summary: ${{ tasks.summarize.output }}
    invoke:
      tool: nika:write
      args:
        path: "/tmp/summary.txt"
        content: "${{ with.summary }}"
```

The `permits:` block is not decoration and not optional in spirit: an
absent one declares **zero** authority, so any workflow that touches a
file, a host or a shell is refused at check (`NIKA-AUTH-006`) until it
says what it needs. `nika check --infer-permits` writes the tightest one
for you.

<Note>
  The `nika` CLI, `nika check`, `nika run`, `nika lsp`, and read-only
  `nika mcp` are live in v. Use `nika init` once per repo
  for schema + agent rules, then `nika wire <client>` when you want an
  agent client to call the real Nika oracle.
</Note>

## What Nika is not

* **Not an agent framework.** No abstractions over agent loops you can't read.
* **Not a chatbot wrapper.** No conversation state hidden in vendor APIs.
* **Not another SDK.** The YAML file *is* the interface.
* **Not a SaaS.** AGPL means the source travels with the binary.

## I want to…

<Tip>
  Scan this table before you dive into a section. It's the fastest map.
</Tip>

| I want to…                                                       | Best option                                                                                                                                              |
| ---------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Install Nika locally                                             | [Installation](/getting-started/installation)                                                                                                            |
| Run my first workflow                                            | [First workflow](/getting-started/first-workflow)                                                                                                        |
| Start from a real example                                        | [Examples gallery](/examples/overview)                                                                                                                   |
| Write a workflow well (or have an agent write it)                | [Patterns](/guides/patterns) · [Agent authoring](/guides/agent-authoring)                                                                                |
| See every `.nika.yaml` field                                     | [YAML syntax reference](/reference/yaml-syntax)                                                                                                          |
| Understand how verbs execute                                     | [Concepts · Verbs](/concepts/verbs)                                                                                                                      |
| Pick an LLM provider                                             | [Concepts · Providers](/concepts/providers)                                                                                                              |
| Know what a run can cost BEFORE running it                       | [Cost honesty](/guides/cost-honesty)                                                                                                                     |
| Cap what a workflow may touch (files · hosts · programs · tools) | [Security · Permits](/concepts/security)                                                                                                                 |
| Prove a run really happened (hash-chained trace, replayable)     | [Traces & replay](/concepts/traces)                                                                                                                      |
| Parse Nika from a script or an agent (JSON wires · exit codes)   | [Machine surfaces](/reference/machine-surfaces)                                                                                                          |
| Pick a local model on measured facts                             | [Model bench](/examples/model-bench)                                                                                                                     |
| Look up a `NIKA-XXX` error code                                  | [Reference · Error codes](/reference/error-codes)                                                                                                        |
| Understand the engine architecture                               | [Concepts · Architecture](/concepts/architecture)                                                                                                        |
| Check the engine's live build state                              | [Reference · Status](/reference/status)                                                                                                                  |
| Report a stumble — or just talk to us                            | [Troubleshooting → ask with context](/guides/troubleshooting#when-it-breaks-in-order) · [Discussions](https://github.com/supernovae-st/nika/discussions) |
| Contribute                                                       | [GitHub → supernovae-st/nika](https://github.com/supernovae-st/nika)                                                                                     |

## Why YAML

Because the same file is read by the machine and understood by the human.
No DSL, no Python-pretending-to-be-config, no JavaScript callbacks scattered
across nodes. The schema is the contract.

## Why Rust

Because workflows fail in production, and a single binary with zero runtime
dependencies fails predictably. Because the engine must be auditable, line by
line. Because&#x20;**&#x20;clippy warnings** and **zero
unwraps** in `src/` are not aspirational. They are enforced by CI on every
commit.

## The engine in one diagram

```mermaid theme={"system"}
%%{init: {'theme':'dark','themeVariables':{'background':'transparent','mainBkg':'transparent'}}}%%
flowchart LR
    F["workflow.nika.yaml<br/><i>portable · readable · verifiable</i>"] --> E["<b>nika</b><br/>single Rust binary"]
    E -->|infer| L["LLMs<br/>Ollama · LM Studio · any API"]
    E -->|exec| S["shell"]
    E -->|invoke| T["tools · MCP"]
    E -->|agent| A["autonomous loop"]
```

<sub>Built in the open, crafted crate by crate under a strict admission
discipline. The live engineering state (crates · tests · hygiene) is one
click away at [Reference · Status](/reference/status), the design at
[Concepts · Architecture](/concepts/architecture).</sub>

## Read next

<CardGroup>
  <Card title="Examples · real jobs" icon="rocket" href="/examples/overview">
    What would YOUR Monday look like? Starter to epic, every industry.
  </Card>

  <Card title="How to write Nika" icon="compass-drafting" href="/guides/patterns">
    The twelve patterns of well-written Nika, each taught by a
    canonical example.
  </Card>

  <Card title="Install Nika" icon="download" href="/getting-started/installation">
    What ships at v, what doesn't, how to track releases.
  </Card>

  <Card title="Changelog & roadmap" icon="clock-rotate-left" href="/changelog/releases">
    The full arc — origins to v — dated, tagged,
    subscribable by RSS. And [what ships next](/changelog/roadmap).
  </Card>

  <Card title="Workflows" icon="diagram-project" href="/concepts/workflows">
    How a `.nika.yaml` file becomes an executed graph.
  </Card>

  <Card title="Providers" icon="server" href="/concepts/providers">
    Local-first: Ollama · llama.cpp · vLLM · LM Studio, or any cloud API.
  </Card>

  <Card title="Architecture" icon="layer-group" href="/concepts/architecture">
    Six layers. Why L0 has zero async and zero I/O.
  </Card>
</CardGroup>

## The Nika ecosystem

<Ecosystem />

<Visibility>
  You are reading Nika's documentation. For programmatic discovery: each
  page exposes its heading tree via the Mintlify `.md` export at
  `<url>/.md`. The canonical engine state lives at `/reference/status`
  (imports `/snippets/_status-snapshot.mdx`, which is auto-generated by
  `scripts/mintlify-snapshot.sh` from `scripts/refresh-status.sh`). Do
  not quote hard-coded counts. Import `STATUS` and reference
  `STATUS.cratesAdmitted`, `STATUS.libTests`, etc.
</Visibility>

🦋


# Run receipts
Source: https://docs.nika.sh/patterns/run-receipts

A tool-neutral pattern for AI pipelines: a reviewable contract before execution, a verifiable record after. Nika is one implementation — the pattern stands on its own.

AI runs act on the real world — they spend money, read secrets, write
files, call tools. Most of them leave nothing behind that a reviewer can
trust: a chat log is editable, a dashboard is a vendor's word, a green CI
tick says only that *something* exited zero. **Run receipts** is the
pattern that fixes this, and it is deliberately not a product: any
pipeline, framework or runtime can implement it.

## The pattern

A run deserves two documents, one on each side of the execution:

<Steps>
  <Step title="Before — a reviewable contract">
    A static, diffable statement of what the run *would* do: the task
    graph and its order, which models and secrets it needs, what it may
    read, write and reach on the network, and an honest cost bound —
    a ceiling when priceable, an explicit *unknown* when not (never a
    silent `$0`). A human can approve it in review; a machine can gate
    on it in CI. Nothing has executed yet.
  </Step>

  <Step title="During — bounded execution">
    The runtime enforces the contract instead of trusting the prose:
    effects outside the declared boundary fail, spend past the bound
    stops the run. The contract is load-bearing, not documentation.
  </Step>

  <Step title="After — a verifiable record">
    An append-only journal of what *actually* happened: every task's
    settle, output digest, spend and timing, each entry carrying a hash
    of the previous one. Anyone holding the file can recompute the chain
    and detect tampering — trust lives in the artifact, not in whoever
    hands it over.
  </Step>
</Steps>

## What a receipt answers

| The reviewer's question      | Where the answer lives                                       |
| ---------------------------- | ------------------------------------------------------------ |
| What ran, in what order?     | the task graph + per-task settle events                      |
| What did it touch?           | the declared boundary + the recorded effects                 |
| What did it cost?            | per-task spend, summed — floors stay honest floors           |
| Which model, which provider? | pinned per task in the record, not recalled from memory      |
| Can I trust this file?       | recompute the hash chain — it verifies or it names the break |
| Can I re-run it?             | the contract is the input; the record is the expected shape  |

## The minimal shape

Nothing about the record requires a platform. Newline-delimited JSON,
one event per line, each line carrying the hash of the line before it:

```text theme={"system"}
{"event":"task_settled","task":"digest","status":"success","spend_usd":0.0031,"prev":"8c41…","hash":"f09a…"}
{"event":"task_settled","task":"notes","status":"success","output_sha256":"77b2…","prev":"f09a…","hash":"d418…"}
{"event":"run_closed","verdict":"completed","total_usd":0.0031,"prev":"d418…","hash":"9e0c…"}
```

Grep-able, git-trackable, verifiable offline with a for-loop and a hash
function. That is the whole trick — the value is in *committing to it*,
not in any engine.

## Nika as one implementation

Nika ships the pattern end to end, which is why this page lives here —
but each half maps to a plain command you can inspect:

* **The contract** is [`nika check`](/concepts/how-nika-compares): the
  static audit that prints the plan, the cost bound, the secret flows and
  the permits boundary before a single token is spent, and exits non-zero
  when the file breaks its own contract.
* **The record** is the [flight recorder](/concepts/traces): every run
  journals to `.nika/traces/` as hash-chained NDJSON, and the run prints
  its chain head on close.
* **The re-proof** is `nika trace verify` — it recomputes the chain and
  either confirms the head or names the first altered link (the full
  trace verb family is in the [CLI reference](/reference/cli)).
* **The exit** is `nika trace export`: the journal projects to OTLP/JSON
  for Jaeger, Grafana or Langfuse — the receipt is portable, not a
  lock-in surface.

In CI, the same split powers [Nika × GitHub Actions](/integrations/github-actions):
pull requests get the contract as a sticky comment, and nothing executes.

## Adopt it without adopting Nika

The pattern is worth stealing. If your pipeline is LangGraph, plain
Python or a Makefile, you can still ship receipts: declare the boundary
in a reviewable file, journal settles as append-only NDJSON, chain the
hashes, and teach CI to show the contract on every change. Your reviewers
get the same two documents; no dependency required. If you later want the
enforced version, [how Nika compares](/concepts/how-nika-compares) is the
honest map — including when not to switch.


# Builtins catalog
Source: https://docs.nika.sh/reference/builtins

The canonical stdlib: engine-native nika:* tools across 6 categories, all reached through the invoke: verb.

The language stays  verbs. Everything else is a tool, and the
standard library ships&#x20;**&#x20;builtins** under the `nika:*`
namespace, engine-native (no MCP round-trip, no subprocess), all invoked
the same way:

```yaml theme={"system"}
read_config:
  invoke:
    tool: "nika:read"
    args: { path: "./config.yaml" }
```

The tables below name every builtin so you know what exists offline. For the
**argument contract** of any one of them, ask your installed binary rather
than a page that can drift:

```bash theme={"system"}
nika catalog --tools          # every builtin, by category, with one-line contracts
nika catalog --tools --json   # the model-facing JSON Schemas (args · required)
```

<Info>
  **Canonical source:** [`nika-spec/stdlib/builtins-v0.1.md`](https://github.com/supernovae-st/nika-spec/blob/main/stdlib/builtins-v0.1.md),
  the Apache-2.0 language spec. The set was curated by the Rams
  "less but better" sweep (ADR-086/087/088): one super-powerful builtin
  with mode args beats five single-purpose ones.
</Info>

## Overview

<CardGroup>
  <Card title="Builtins" icon="toolbox">
    &#x20;tools · 6 categories
  </Card>

  <Card title="Extract modes" icon="filter">
    &#x20;on `nika:fetch`
  </Card>

  <Card title="Namespace" icon="tag">
    `nika:*` · engine-native
  </Card>
</CardGroup>

## Core (6)

The workflow-control family: speak, signal, guard, ask, finish, pause.

| Builtin       | What it does                                                                                                        |
| ------------- | ------------------------------------------------------------------------------------------------------------------- |
| `nika:log`    | Emit a log entry (`debug`/`info`/`warn`/`error`) to the event stream: the human-readable diagnostic.                |
| `nika:emit`   | Emit a custom machine event (consumed by subscribers and the journal). `log` is for humans, `emit` is for machines. |
| `nika:assert` | Fail the task if a CEL `${{ }}` condition is false: the fail-fast guard (`when:` is the skip-guard).                |
| `nika:prompt` | Interactive human confirm: blocks until answered; engines may use `default` in CI.                                  |
| `nika:done`   | Mark the current `agent:` loop complete and exit. Valid only inside an agent tool whitelist.                        |
| `nika:wait`   | Temporal pause: relative `duration:` XOR absolute `until:` (ISO 8601), validated at parse time.                     |

```yaml theme={"system"}
gate:
  with:
    count: ${{ tasks.fetch_data.output.count }}
  invoke:
    tool: "nika:assert"
    args:
      condition: "${{ with.count > 0 }}"
      message: "Expected non-empty result"
```

## File (5)

| Builtin      | What it does                                                              |
| ------------ | ------------------------------------------------------------------------- |
| `nika:read`  | Read a file. Returns string content.                                      |
| `nika:write` | Write a file. Returns the path; binary upstream values are written as-is. |
| `nika:edit`  | In-place find/replace. Returns the modified path.                         |
| `nika:glob`  | Glob match. Returns an array of paths.                                    |
| `nika:grep`  | Recursive grep. Returns an array of `{ path, line, match }`.              |

## Data (9)

`jq` is THE data language: map, filter, reshape, merge. The other eight
cover what jq genuinely cannot do: diff, validate, delete-on-null merge,
format conversion, generation, time, hashing, adjudication.

| Builtin                 | What it does                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `nika:jq`               | Run a jq expression: the single transform-and-extraction language, same jq as `output:` bindings.                                                                                                                                                                                                                                                                                                                                                                                             |
| `nika:json_diff`        | JSON diff. Returns RFC 6902 JSON Patch (jq can't diff).                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `nika:validate`         | Validate data against a JSON Schema: `format: json \| yaml`, returns `{ valid, errors }`.                                                                                                                                                                                                                                                                                                                                                                                                     |
| `nika:json_merge_patch` | RFC 7396 merge patch: `null` deletes a key, the semantics jq's `*` merge does not provide.                                                                                                                                                                                                                                                                                                                                                                                                    |
| `nika:convert`          | Universal format converter: `json` · `yaml` · `toml` · `csv`, `from:`/`to:` mode args. CSV emit takes `formula_guard: true` (opt-in) to neutralize spreadsheet formula-injection in untrusted data.                                                                                                                                                                                                                                                                                           |
| `nika:uuid`             | Generate a UUID: `v7` default (timestamped/sortable, RFC 9562) or `v4`.                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `nika:date`             | Timestamp arithmetic: op-discriminated (`now`/`add`/`subtract`/`format`/`parse`/`diff`), timezone-aware, ISO 8601 out.                                                                                                                                                                                                                                                                                                                                                                        |
| `nika:hash`             | Content hashing: default blake3, or `sha256`/`sha512`; md5/sha1 are not supported.                                                                                                                                                                                                                                                                                                                                                                                                            |
| `nika:decide`           | The deterministic decision kernel ([spec 11](https://github.com/supernovae-st/nika-spec/blob/main/spec/11-decision.md)): evaluates a portable Decision Bundle (`bundle:`) against an EvidenceSnapshot (`evidence:`) and returns the full receipt — outcome, term-by-term contributions, intervals, conflicts with their witnesses, determination provenance. **The model never decides**: an `infer:` task collects the facts, this applies the rubric. Same evidence, same verdict, forever. |

```yaml theme={"system"}
# recursive deep-merge of two task outputs — pure jq, no extra builtin
merged:
  with:
    base: ${{ tasks.base.output }}
    overlay: ${{ tasks.overlay.output }}
  invoke:
    tool: "nika:jq"
    args:
      input: ["${{ with.base }}", "${{ with.overlay }}"]
      expression: ".[0] * .[1]"
```

## Network (2)

| Builtin       | What it does                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `nika:fetch`  | HTTP request + content extraction:  extract modes (`article`, `markdown`, `links`, `feed`, `sitemap`, `selector`, `text`, `metadata`, `jq`) + `raw` passthrough — plus `form:` (urlencoded), `multipart:` (file parts ride the `permits.fs` READ boundary · ≤32 MiB) and `traverse:` (bounded same-origin crawl · `max_pages` ≤ 25 · robots honored · the effect certificate counts every page). Fetching a URL is *calling a tool*, not a verb — and so is crawling: no `nika:crawl`. |
| `nika:notify` | Send notifications: `channel:` enum (`webhook`/`slack`/`email`/`discord`/`sms`), one builtin not five.                                                                                                                                                                                                                                                                                                                                                                                 |

<Warning>
  Engines MUST ship SSRF defense on `nika:fetch`: private-network and
  cloud-metadata targets are rejected unless explicitly configured, and
  self-signed TLS is rejected by default.
</Warning>

## Introspection (2)

| Builtin        | What it does                                                                                                                                                                                                |
| -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `nika:inspect` | Workflow introspection. One builtin, four `view:` modes: `cost` (running USD by task/provider), `records` (full execution record), `dag_info` (nodes/edges/waves), `threads` (engine pool state, advisory). |
| `nika:compose` | The agent loop's self-check: pass a drafted workflow YAML, get the full `nika check` verdict back as JSON — never executed. Loop-only, like `nika:done` (valid only inside an `agent:` tools whitelist).    |

```yaml theme={"system"}
budget_check:
  invoke:
    tool: "nika:inspect"
    args: { view: cost }
```

## Media (4)

| Builtin               | What it does                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `nika:chart`          | **Deterministic chart rendering** from rows + a semantic spec (`bar` · `line` · `area_band` · `scatter` · `heatmap`): a byte-identical SVG lands at `out:` (permit-gated write) and its sha256 rides the outputs as a trace-chain receipt. Pure compute + one write — no network, no clock, re-runs idempotent; optional Vega-Lite sibling via `compile_to:`. Full guide: [Charts](/guides/charts).                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `nika:image_generate` | Provider-backed image **generation and editing** as an *asset pipeline*: renders land under a declared `output_dir:` (rides `permits.fs.write`), and `mode: edit` sources are read permit-gated (`permits.fs.read` — the mirror boundary); outputs and a provenance manifest carry paths + dimensions + sha256, and an edit records its `source_images` — **image bytes never ride workflow outputs**. Providers (v1.1 · local-first): `local` (any OpenAI-images-compatible self-hosted server — LocalAI · Ollama · sd.cpp · SGLang · vLLM-Omni · base URL via `NIKA_IMAGE_LOCAL_URL`) · `openai` (`gpt-image-2`) · `gemini` (`gemini-3.1-flash-image`) · `xai` (`grok-imagine-image`) · `mock` (offline, deterministic, zero keys). Full guide: [Image generation](/guides/image-generation) — sovereign quickstart · editing · cookbook · honesty rules. |
| `nika:tts_generate`   | Speech synthesis on the same asset-pipeline contract (full guide: [Speech generation](/guides/speech-generation)): ONE audio file lands under `output_dir:` (permit-gated), output + manifest carry path + sha256 + `duration_ms` (wav-exact, mp3 honestly null) — **audio bytes never ride outputs**. Providers (sovereign-first): `local` (any OpenAI-speech-compatible server — LocalAI · Kokoro-FastAPI · Speaches — via `NIKA_TTS_LOCAL_URL`) · `openai` (`gpt-4o-mini-tts`) · `elevenlabs` (`ELEVENLABS_API_KEY`) · `mock` (real deterministic WAV, offline).                                                                                                                                                                                                                                                                                         |
| `nika:image_fx`       | **Deterministic artistic effects** on a PNG — dither (bayer · blue-noise · ign · floyd\_steinberg · atkinson · jjn) · palette mapping (Oklab) · duotone · pixelate · halftone · grain · vignette · chromatic aberration · scanlines · glitch · ascii (png/text/ansi). Zero providers, zero network: **byte-identical output forever** for identical `(input, args)` — the artifact's sha256 joins the trace chain, re-render IS the tamper check, and the full recipe (contract tag `image_fx/v1` · input sha256 · seed · ops) rides the PNG itself as a `nika` tEXt chunk. `input:` read + `out:` write both ride `permits.fs`. Full guide: [Image effects](/guides/image-effects) — the receipts story · op table · cookbook.                                                                                                                             |

```yaml theme={"system"}
hero:
  invoke:
    tool: "nika:image_generate"
    args:
      provider: mock              # offline dry-run · flip to local (sovereign) / gemini / openai / xai for real renders
      prompt: "OG hero — a monarch butterfly over a nebula"
      aspect_ratio: "16:9"
      output_dir: "./assets/og"
```

<Warning>
  API keys are **engine-configured, never workflow args**: `OPENAI_API_KEY` /
  `GEMINI_API_KEY` / `XAI_API_KEY` (or the `NIKA_`-prefixed variants) and the
  local server's `NIKA_IMAGE_LOCAL_URL` (+ optional `NIKA_IMAGE_LOCAL_API_KEY`)
  are read once at the engine's composition root. The provider endpoints are engine-fixed
  constants — `permits.net.http` does not govern them (exactly like
  `infer:`); `permits.tools` and `permits.fs` do.
</Warning>

## Design rules the set obeys

* **One super-powerful builtin, multi-mode args**: `fetch`+extract,
  `jq`, `convert`, `wait`, `date`, `inspect` all follow the same pattern.
  No per-direction or per-shape builtin slots.
* **jq subsumes**: anything that is a pure JSON transform is a jq
  expression, not a builtin. A builtin earns its slot only by doing what
  jq cannot.
* **Additive forever**: new builtins may join in stdlib v0.x; existing
  arg shapes never break (the language envelope `nika: v1` is frozen).

## See also

<CardGroup>
  <Card title="Full stdlib spec" icon="book-open" href="https://github.com/supernovae-st/nika-spec/blob/main/stdlib/builtins-v0.1.md">
    Per-builtin args, error codes (`NIKA-BUILTIN-*`), trust classes, and
    what jq subsumed out of v0.1.
  </Card>

  <Card title="Verbs" icon="code" href="/concepts/verbs">
    How `invoke:` dispatches `nika:*` builtins vs MCP tools.
  </Card>

  <Card title="MCP catalog" icon="plug" href="/reference/mcp-catalog">
    External tools: the MCP server registry Nika knows by id.
  </Card>

  <Card title="Bindings" icon="link" href="/concepts/bindings">
    Templating that pipes output from one `invoke:` to the next.
  </Card>
</CardGroup>


# Capability rules
Source: https://docs.nika.sh/reference/capabilities

The capability rules that map provider/model pairs to their feature set: modalities, tools, JSON mode, streaming, token limits.

Nika's capability system answers one question: **given a `provider + model`,
what features does it support?** Tool calling? Vision input? Audio output?
JSON schema mode? Thinking budgets? Prompt caching?

The answer is a `ModelCapabilities` struct, computed at runtime by applying&#xA;**&#x20;rules** (in file order) on top of a defaults block.
Zero regex, zero allocation, zero runtime deps.

<Info>
  **Canonical source:** [`crates/nika-catalog/data/model-capabilities.toml`](https://github.com/supernovae-st/nika/blob/main/crates/nika-catalog/data/model-capabilities.toml).
  Schema: `nika/model-capabilities@1.0`. Build-time FK checks against
  `llm-providers.toml` (unknown provider = build failure, catches typos).
</Info>

## Resolution algorithm

<Steps>
  <Step title="Start from `[defaults]`">
    Mirrors `ModelCapabilities::default()`. Current defaults:

    ```toml theme={"system"}
    token_limit_param    = "max-tokens"
    input_modalities     = ["text", "image"]
    output_modalities    = ["text"]
    supported_parameters = []
    ```
  </Step>

  <Step title="Scan `[[rules]]` in file order">
    Every rule has a `match` clause and a `caps` clause. If the rule's
    `scope.providers` list is non-empty and the canonical provider id
    isn't in it → skip. Same for `scope.api_dialect`.
  </Step>

  <Step title="Apply the rule's `caps` fields">
    Fields set by a rule **overwrite** earlier values. Fields absent from
    the rule **preserve** the accumulated state. No merging of lists:
    assignment is wholesale.
  </Step>

  <Step title="Return the accumulated `ModelCapabilities`">
    Zero allocation (every string is `&'static str` or `Cow<'static, str>`).
    Resolved at runtime in O(N) rules for a single lookup.
  </Step>
</Steps>

## The 4 match kinds

<AccordionGroup>
  <Accordion title="`any`: matches every model" icon="asterisk">
    ```toml theme={"system"}
    [[rules]]
    match = { kind = "any" }
    caps.streaming = true
    ```

    Used for provider-wide defaults (e.g., "every xAI model supports streaming").
  </Accordion>

  <Accordion title="`exact`: matches one model id" icon="equals">
    ```toml theme={"system"}
    [[rules]]
    match = { kind = "exact", model = "deepseek-reasoner" }
    caps.supported_parameters = ["include-reasoning"]
    ```

    Used for per-model overrides that deviate from a sibling family.
  </Accordion>

  <Accordion title="`exact_any`: matches a set of model ids" icon="list">
    ```toml theme={"system"}
    [[rules]]
    match = { kind = "exact_any", models = ["o1", "o3", "o4"] }
    caps.supported_parameters = ["reasoning-effort"]
    ```

    Used for explicit model enumeration when ids don't share a prefix.
  </Accordion>

  <Accordion title="`prefix_any`: matches models whose id starts with any prefix" icon="arrow-right">
    ```toml theme={"system"}
    [[rules]]
    match = { kind = "prefix_any", prefixes = ["gpt-4o", "gpt-4.1"] }
    caps.input_modalities = ["text", "image"]
    caps.json_mode = "schema"
    ```

    Most common. Covers entire model families in one rule. **No regex**:
    prefix match only (keeps zero runtime deps in L0).
  </Accordion>
</AccordionGroup>

## Capability fields

What a rule can set:

| Field                  | Type      | Example                                                      |
| ---------------------- | --------- | ------------------------------------------------------------ |
| `token_limit_param`    | enum      | `max-tokens` · `max-completion-tokens` · `max-output-tokens` |
| `input_modalities`     | string\[] | `["text", "image", "audio", "pdf"]`                          |
| `output_modalities`    | string\[] | `["text"]` · `["speech"]` · `["image-gen"]`                  |
| `tool_calling`         | bool      | `true` for function/tool use                                 |
| `parallel_tool_calls`  | bool      | parallel tool invocation                                     |
| `streaming`            | bool      | Server-Sent Events streaming                                 |
| `json_mode`            | enum      | `unavailable` · `object` · `schema`                          |
| `caching`              | enum      | `none` · `prompt-caching` · `context-caching`                |
| `supported_parameters` | string\[] | see below                                                    |

### Supported parameter vocabulary (13)

<Check>
  The vocabulary is **closed**: adding a new parameter is a `nika-catalog` schema change.
</Check>

| Parameter             | Meaning                                          |
| --------------------- | ------------------------------------------------ |
| `parallel-tool-calls` | Multiple tools invoked in one step               |
| `reasoning-effort`    | OpenAI o-series effort level (low/med/high)      |
| `thinking-budget`     | Claude extended thinking budget tokens           |
| `prompt-caching`      | Anthropic prompt caching (cache\_control blocks) |
| `file-search`         | OpenAI file search tool                          |
| `web-search`          | Perplexity / Grok web search tool                |
| `streaming-thinking`  | Stream reasoning tokens separately               |
| `batch-api`           | OpenAI / Anthropic batch mode                    |
| `context-caching`     | Gemini context caching                           |
| `predicted-outputs`   | OpenAI predicted outputs                         |
| `computer-use`        | Anthropic computer use tool                      |
| `citations`           | Perplexity / Claude citations                    |
| `include-reasoning`   | DeepSeek `include-reasoning` flag                |

### Modality vocabulary (8)

`text` · `image` · `audio` · `video` · `pdf` · `embedding` · `speech` · `image-gen`

<Warning>
  `input_modalities` **must** contain `text` (build invariant). A pure-image
  input model can't be wired as an `infer:` target without text support.
</Warning>

## Example resolution trace

<CodeGroup>
  ```toml defaults + 2 rules theme={"system"}
  [defaults]
  input_modalities     = ["text", "image"]
  output_modalities    = ["text"]
  supported_parameters = []

  # Rule 1 — all Claude models get prompt caching + 200k context
  [[rules]]
  scope.providers = ["anthropic", "bedrock"]
  match = { kind = "prefix_any", prefixes = ["claude", "anthropic.claude"] }
  caps.streaming            = true
  caps.tool_calling         = true
  caps.parallel_tool_calls  = true
  caps.json_mode            = "schema"
  caps.caching              = "prompt-caching"
  caps.token_limit_param    = "max-tokens"
  caps.supported_parameters = ["prompt-caching", "thinking-budget"]

  # Rule 2 — claude-opus-4 adds computer-use on top
  [[rules]]
  scope.providers = ["anthropic"]
  match = { kind = "prefix_any", prefixes = ["claude-opus-4"] }
  caps.supported_parameters = ["prompt-caching", "thinking-budget", "computer-use", "citations"]
  ```

  ```rust Resolved (anthropic, claude-opus-4-5-20260201) theme={"system"}
  ModelCapabilities {
      input_modalities:     ["text", "image"],         // from defaults
      output_modalities:    ["text"],                  // from defaults
      streaming:            true,                      // from rule 1
      tool_calling:         true,                      // from rule 1
      parallel_tool_calls:  true,                      // from rule 1
      json_mode:            JsonMode::Schema,          // from rule 1
      caching:              Caching::PromptCaching,    // from rule 1
      token_limit_param:    "max-tokens",              // from rule 1
      supported_parameters: ["prompt-caching",         // from rule 2 (overwrites rule 1)
                             "thinking-budget",
                             "computer-use",
                             "citations"],
  }
  ```
</CodeGroup>

## Why not regex

<Info>
  L0 crates ship zero runtime dependencies beyond `std` + `alloc`. Regex
  would pull in `regex-automata` (\~50k LOC) and force a runtime
  initialization cost. `prefix_any` covers 95% of actual model-family
  matching needs; the remaining 5% is handled by `exact_any`.
</Info>

This is Q1 (no proc macros) applied at the data-layer. See
[L0 foundation decisions](/architecture/l0-decisions).

## How to query capabilities

Two shipped subcommands project the embedded catalogs — `nika catalog`
(providers · models · capabilities · env vars) and `nika catalog --tools` (the
`nika:*` builtin schemas), each with a versioned `--json` machine form:

<CodeGroup>
  ```bash nika catalog (shipped) theme={"system"}
  $ nika catalog                # human listing · local providers first
  $ nika catalog --json         # machine projection (catalog_version: 1)
  $ nika catalog --tools --json # builtin tool catalog (tools_version: 1)
  ```

  ```rust Rust API (shipped · nika-catalog) theme={"system"}
  use nika_catalog::model_capabilities;

  let caps = model_capabilities("anthropic", "claude-opus-4-5-20260201");
  assert!(caps.streaming);
  assert!(caps.tool_calling);
  assert_eq!(caps.json_mode, JsonMode::Schema);
  assert!(caps.supported_parameters.contains(&"computer-use"));
  ```
</CodeGroup>

## Drift protection

<Check>
  **Build-time FK check:** every `scope.providers[i]` must be a canonical
  provider id in `llm-providers.toml`. Typos fail the build.

  **Build-time enum check:** every `supported_parameters` entry must be in
  the 13-value vocabulary. New additions require a schema bump.

  **Build-time ordering check:** `tags` arrays in `llm-providers.toml` must
  be sorted + deduplicated. Same applies to `caps.*` arrays by convention.
</Check>

## See also

<CardGroup>
  <Card title="Providers catalog" icon="server" href="/reference/providers-catalog">
    The  canonical providers these rules target.
  </Card>

  <Card title="Concepts · Providers" icon="plug" href="/concepts/providers">
    Runtime routing: how infer verb picks a provider.
  </Card>

  <Card title="Schema" icon="file-code" href="/reference/schema">
    `.nika.yaml` envelope + workflow schema reference.
  </Card>

  <Card title="L0 decisions" icon="list-check" href="/architecture/l0-decisions">
    Q1-Q13: why no regex, why manual impl, why prefix-only matching.
  </Card>
</CardGroup>


# CLI reference
Source: https://docs.nika.sh/reference/cli

Every nika subcommand, flag, and environment variable.

<Info>
  This page mirrors the current docs build (`v{STATUS.version}` from the status
  snapshot). Tagged release binaries can lag main; `nika --help` remains the
  executable source of truth for the binary installed on your machine.
</Info>

## Core commands

| Command                                           | What it does                                                                                                                                                                                                                                                                                                                                                                                                   |          |                                                                                                    |         |        |      |        |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| ------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | -------------------------------------------------------------------------------------------------- | ------- | ------ | ---- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `nika welcome`                                    | The mirror: what this machine has (editors · local models · key presence), what this binary carries, where to start — offline, always exit 0                                                                                                                                                                                                                                                                   |          |                                                                                                    |         |        |      |        |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `nika welcome --deep [--json]`                    | The whole workspace truth in one call: every workflow audited (verdict · tasks · waves · cost honesty · permits), recent runs folded from the flight recorder, the machine facts — capped and says so                                                                                                                                                                                                          |          |                                                                                                    |         |        |      |        |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `nika try [slug]`                                 | See a canonical workflow WORK — offline by default (the mock rehearsal · zero keys · zero flags), nothing written, nothing owned. Bare `nika try` lists what there is to see · `--model <provider>/<name>` runs the same example on a real seat                                                                                                                                                                |          |                                                                                                    |         |        |      |        |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `nika check <file>`                               | Static pre-flight audit before any run — `-` reads the workflow from stdin (0.94+) · `registry:owner/name` pulls a certified artifact first                                                                                                                                                                                                                                                                    |          |                                                                                                    |         |        |      |        |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `nika run <file>`                                 | Execute a checked workflow — `registry:owner/name` refs resolve through the verified cache, then the normal audit-before-run                                                                                                                                                                                                                                                                                   |          |                                                                                                    |         |        |      |        |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `nika model serve\|pull\|list\|rm`                | The sovereign local lane: serve a GGUF through the in-process sidecar (`serve --model x.gguf` · loopback · in every release binary (0.101+) · qwen3-family GGUFs, a wrong family refuses in milliseconds), acquire from the Hugging Face Hub (`pull` — brings `tokenizer.json` along, borrowing it from the repo's declared base model when the mirror ships none), inventory and reclaim disk (`list` · `rm`) |          |                                                                                                    |         |        |      |        |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `nika test <file> [--update]`                     | Golden-test: run under the mock provider (offline · deterministic) and compare typed `outputs:` against `<file>.golden.json`                                                                                                                                                                                                                                                                                   |          |                                                                                                    |         |        |      |        |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `nika inspect <file>`                             | Static anatomy: tasks, verbs, DAG, cost, permits — `-` reads stdin (0.94+)                                                                                                                                                                                                                                                                                                                                     |          |                                                                                                    |         |        |      |        |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `nika inspect <file> --format json\|mermaid\|dot` | Project the workflow graph — `-` reads stdin                                                                                                                                                                                                                                                                                                                                                                   |          |                                                                                                    |         |        |      |        |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `nika explain <code\|file>`                       | Teach a `NIKA-XXXX` error code — or narrate a workflow FILE (0.98+): the waves, cost before a token is spent, what it touches, the flight-recorder hand-off                                                                                                                                                                                                                                                    |          |                                                                                                    |         |        |      |        |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `nika doctor [--ping]`                            | Diagnose providers plus editor/agent readiness — findings grouped under `binary` · `config` · `lsp` · `mcp` · `provider` · `local` · `providers` · `image` · `tts`. `--ping` (0.94+) TCP-probes the local ports — loopback and configured URLs only, 300ms cap, nothing sent on the socket; the default run stays fully offline                                                                                |          |                                                                                                    |         |        |      |        |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `nika init [dir]`                                 | Scaffold schema wiring, `AGENTS.md`, and Cursor rules                                                                                                                                                                                                                                                                                                                                                          |          |                                                                                                    |         |        |      |        |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `nika wire <target>`                              | Explicitly wire MCP for `cursor`, `vscode`, `windsurf`, `claude`, `codex`, `zed`, `opencode`, `hermes`, or `all` — the [client table](/integrations/mcp-clients) carries every target and its config path                                                                                                                                                                                                      |          |                                                                                                    |         |        |      |        |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `nika spec [--canon]`                             | Print the embedded spec or canon                                                                                                                                                                                                                                                                                                                                                                               |          |                                                                                                    |         |        |      |        |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `nika spec --schema`                              | Print the embedded JSON Schema                                                                                                                                                                                                                                                                                                                                                                                 |          |                                                                                                    |         |        |      |        |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `nika catalog [--json]`                           | The embedded provider/model catalog (models · capabilities · env vars) — `--json` emits the versioned machine projection (`catalog_version: 1`)                                                                                                                                                                                                                                                                |          |                                                                                                    |         |        |      |        |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `nika catalog --tools [--json]`                   | The embedded builtin tool catalog (`nika:*` · model-facing schemas) — `--json` emits the versioned machine projection (`tools_version: 1`)                                                                                                                                                                                                                                                                     |          |                                                                                                    |         |        |      |        |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `nika new [intent] [dest]`                        | The ONE creation door (0.107): plain words route across the whole catalog · an example slug lands verbatim with its ingredients · a skeleton name instantiates (`nika new '?'` lists the set) — the old `nika examples` tree and `nika new --from` died with 0.107                                                                                                                                             |          |                                                                                                    |         |        |      |        |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `nika completions <shell>`                        | Generate shell completions ([setup](/getting-started/installation#shell-completions))                                                                                                                                                                                                                                                                                                                          |          |                                                                                                    |         |        |      |        |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `nika sign <file>`                                | Sign a workflow file (author-binding) — mints `<file>.minisig` · `--check` verifies the signature against the trusted key                                                                                                                                                                                                                                                                                      |          |                                                                                                    |         |        |      |        |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| \`nika key mint                                   | fingerprint                                                                                                                                                                                                                                                                                                                                                                                                    | rotate\` | The run-signing key lifecycle — mint · TOFU fingerprint · rotate (old public keys stay verifiable) |         |        |      |        |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `nika trace evidence <trace>`                     | Export the evidence pack for one run — journal + manifest + receipt + VERIFY.md, what an auditor reads without trusting us (moved under `trace` in 0.107 — one door on a run's dossier)                                                                                                                                                                                                                        |          |                                                                                                    |         |        |      |        |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `nika trace receipt explain <file>`               | Read a run receipt — render the readable projection of an evidence pack's `receipt.json` (stable text · a READING, never a proof — `nika trace verify` owns the proof)                                                                                                                                                                                                                                         |          |                                                                                                    |         |        |      |        |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| \`nika trace verify                               | reproduce                                                                                                                                                                                                                                                                                                                                                                                                      | replay   | show                                                                                               | outputs | export | peek | flow\` | Prove, replay, summarize, inspect, or export a recorded run — `verify` walks the tamper-evidence hash chain and names the first broken link (several traces verify per-file, worst exit wins — a shell glob just works) · `peek` renders a task's full recorded value, and a FAILED task's recorded failure + its explain line · `reproduce` re-runs and classifies every divergence — `export` projects the journal to OTLP/JSON lines (Jaeger UI, or POST to any OTLP/HTTP endpoint; a local file, zero collector, zero vendor) |
| `nika dap`                                        | Debug Adapter Protocol server over stdio — time-travel a recorded run in any DAP client (VS Code F5)                                                                                                                                                                                                                                                                                                           |          |                                                                                                    |         |        |      |        |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `nika lsp`                                        | Run the language server over stdio                                                                                                                                                                                                                                                                                                                                                                             |          |                                                                                                    |         |        |      |        |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `nika mcp`                                        | Run the read-only MCP oracle (the tool set is listed below)                                                                                                                                                                                                                                                                                                                                                    |          |                                                                                                    |         |        |      |        |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |

## Global flags

| Flag                        | Command        | Description                                                                                                                                                                            |         |                         |
| --------------------------- | -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | ----------------------- |
| `--json`                    | `check`, `run` | Machine-readable output                                                                                                                                                                |         |                         |
| `--infer-permits`           | `check`        | Print the tightest inferred `permits:` boundary — the paste-ready repair for `NIKA-AUTH-006` (absent block = zero authority)                                                           |         |                         |
| `--native-strict`           | `check`        | Fail (exit 2) while any `native-first` hint remains — an `exec:` a builtin or MCP tool probably covers (the agent/CI posture)                                                          |         |                         |
| `--output json`             | `run`          | Print typed workflow outputs as one JSON object                                                                                                                                        |         |                         |
| `--var key=value`           | `run`          | Set a workflow `inputs:` entry (repeatable) — overrides a `default:`, satisfies `required: true`, parses as JSON when it parses, refuses unknown keys ([details](/concepts/workflows)) |         |                         |
| `--model <provider>/<name>` | `run`          | Override the envelope `model:` — `--model mock/echo` previews any workflow offline (zero key, zero network)                                                                            |         |                         |
| `--resume <trace>`          | `run`          | Resume from a prior run's NDJSON trace: matching completed tasks skip with a visible `task_cache_hit` ([details](/guides/resume))                                                      |         |                         |
| `--from <task_id>`          | `run`          | With `--resume`: force this task and its transitive downstream to re-run even on a match                                                                                               |         |                         |
| `--answer <task>=<value>`   | `run`          | With `--resume`: answer a paused `nika:prompt` (repeatable) — a boolean for `confirm`, a string for `input`, one of the choices for `choice`                                           |         |                         |
| `--task <task_id>`          | `run`          | (0.94+) Run ONE task and its transitive upstream cone only — the whole file still audits, then the plan and cost re-derive for exactly what will run; workflow `outputs:` are skipped  |         |                         |
| `--no-trace-file`           | `run`          | (0.94+) Skip the run journal — every run otherwise writes `.nika/traces/<ts>-<id>.ndjson` by default (`NIKA_NO_TRACE_FILE` opts out globally)                                          |         |                         |
| `--update`                  | `test`         | (Re)write the golden from this run instead of comparing ([details](/guides/testing))                                                                                                   |         |                         |
| `--dry-run`                 | `run`          | Plan only; execute zero effects                                                                                                                                                        |         |                         |
| `--no-progress`             | `run`          | Deterministic non-animated render                                                                                                                                                      |         |                         |
| `--quiet`                   | `run`          | Compact final verdict card                                                                                                                                                             |         |                         |
| \`--format json             | mermaid        | dot\`                                                                                                                                                                                  | `graph` | Choose graph projection |
| `--force`                   | `init`, `new`  | Overwrite existing generated files                                                                                                                                                     |         |                         |

## Environment variables

The five local inference providers (Ollama · LM Studio · llama.cpp ·
LocalAI · vLLM) need **no variable at all** — keyless by construction,
loopback defaults built in. Everything below is opt-in:

| Var                    | Description                                                                                                                    |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `NIKA_IMAGE_LOCAL_URL` | Base URL for the `local` image provider (any OpenAI-images-compatible server — LocalAI · Ollama · sd.cpp · SGLang · vLLM-Omni) |
| `NIKA_TTS_LOCAL_URL`   | Base URL for the `local` speech provider (any OpenAI-speech-compatible server — LocalAI · Kokoro · Speaches)                   |
| `MISTRAL_API_KEY`      | Mistral provider                                                                                                               |
| `ANTHROPIC_API_KEY`    | Anthropic provider                                                                                                             |
| `OPENAI_API_KEY`       | OpenAI provider                                                                                                                |
| `GEMINI_API_KEY`       | Google Gemini provider                                                                                                         |
| `DEEPSEEK_API_KEY`     | DeepSeek provider                                                                                                              |
| `XAI_API_KEY`          | xAI provider                                                                                                                   |
| `GROQ_API_KEY`         | Groq provider                                                                                                                  |
| `OPENROUTER_API_KEY`   | OpenRouter provider                                                                                                            |
| `HF_TOKEN`             | Hugging Face provider (`NIKA_HUGGINGFACE_API_KEY` wins when set)                                                               |
| `NVIDIA_API_KEY`       | NVIDIA provider (`NIKA_NVIDIA_API_KEY` wins when set)                                                                          |
| `ELEVENLABS_API_KEY`   | ElevenLabs speech (`NIKA_ELEVENLABS_API_KEY` wins when set)                                                                    |

The MCP server is intentionally read-only. It exposes 9 tools — `nika_check` ·
`nika_explain` · `nika_schema` · `nika_examples` · `nika_template` ·
`nika_canon` · `nika_catalog` · `nika_tools` · `nika_inspect`; effectful
execution stays behind `nika run`.

<Note>
  **MCP protocol** · latest `2026-07-28`; the server accepts 5 versions
  (`2026-07-28` · `2025-11-25` · `2025-06-18` · `2025-03-26` · `2024-11-05`).
</Note>


# Crate constellation
Source: https://docs.nika.sh/reference/constellation

Visual map of every Nika Diamond crate across six layers. Live admission status. The architecture grows additively across 1.x minors, toward a projected horizon.

Nika Diamond grows additively across 1.x minors, organized across six
layers. Today&#x20;**&#x20;crates are admitted** and
&#x20;are WIP
(), against a
projected horizon of&#x20;**&#x20;crates** (hard cap
, per ADR-037). The horizon is a projection, never a gate:
crates are admitted when they pass the 12 gates, not to reach a number.
The remaining crates are future 1.x expansion, not required for the first-run
CLI/LSP/MCP path.

<Tip>
  Live state: [`/reference/status`](/reference/status). Layer model:
  [`/architecture/layers`](/architecture/layers). Admission process:
  [`/architecture/admission`](/architecture/admission).
</Tip>

## Full dependency graph

```mermaid theme={"system"}
%%{init: {'theme':'dark','themeVariables':{'background':'transparent','mainBkg':'transparent'}}}%%
flowchart TB
  classDef admitted fill:#22c55e,color:#000,stroke:#16a34a,font-weight:bold
  classDef wip fill:#f59e0b,color:#000,stroke:#d97706,font-weight:bold
  classDef planned fill:#1e293b,color:#94a3b8,stroke:#475569,stroke-dasharray:4
  classDef binary fill:#a78bfa,color:#000,stroke:#7c3aed,font-weight:bold

  subgraph L5["L5 · binary"]
    NIKA["nika ✅"]:::admitted
  end

  subgraph L4["L4 · interfaces"]
    CLI["nika-cli ✅"]:::admitted
    SERVE["nika-serve 🧭"]:::planned
    MCP["nika-mcp ✅"]:::admitted
    LSP["nika-lsp ✅"]:::admitted
    SDK["nika-sdk 🧭"]:::planned
    CV["nika-catalog-verify ✅"]:::admitted
  end

  subgraph L3["L3 · runtime"]
    RT["nika-runtime ✅"]:::admitted
    SH["nika-shield 🧭"]:::planned
  end

  subgraph L2["L2 · verbs + services"]
    VE["nika-verb-exec ✅"]:::admitted
    VF["nika:fetch builtin ✅"]:::admitted
    VI["nika-verb-invoke ✅"]:::admitted
    VIF["nika-verb-infer ✅"]:::admitted
    VA["nika-verb-agent ✅"]:::admitted
    PCK["nika-pck 🧭"]:::planned
    MEM["nika-connectome 🧭 v0.85+"]:::planned
    OBS["nika-observability 🧭"]:::planned
    BGH["nika-builtin-github 🧭"]:::planned
    BCL["nika-builtin-cloud 🧭"]:::planned
    BWS["nika-builtin-workspace 🧭"]:::planned
  end

  subgraph L1["L1 · effects"]
    FS["nika-fs ✅"]:::admitted
    HTTP["nika-http ✅"]:::admitted
    PROC["nika-exec-runner ✅"]:::admitted
    GIT["nika-git 🧭"]:::planned
    KEYS["nika-keys-* 🧭"]:::planned
    PROV["nika-providers ✅"]:::admitted
    PREG["nika-pck-registry 🧭"]:::planned
    PSTR["nika-pck-store 🧭"]:::planned
  end

  subgraph L05["L0.5 · kernel"]
    K["nika-kernel ✅"]:::admitted
    KM["nika-kernel-mock ✅"]:::admitted
  end

  subgraph L0["L0 · foundation"]
    T["nika-types ✅"]:::admitted
    E["nika-error ✅"]:::admitted
    C["nika-catalog ✅"]:::admitted
    CG["nika-catalog-codegen ✅"]:::admitted
    S["nika-schema ✅"]:::admitted
    EV["nika-event ✅"]:::admitted
    BN["nika-binding 🧭"]:::planned
    TR["nika-transform 🧭"]:::planned
    PM["nika-pck-manifest 🧭"]:::planned
  end

  T --> E
  T --> C
  T --> K
  E --> K
  C --> K
  C --> CV
  S --> CV
  K --> KM
  K --> FS
  K --> HTTP
  K --> PROC
  K --> GIT
  K --> KEYS
  K --> PROV
  FS --> VE
  HTTP --> VF
  PROV --> VIF
  VE --> RT
  VF --> RT
  VI --> RT
  VIF --> RT
  VA --> RT
  RT --> CLI
  RT --> SERVE
  CLI --> NIKA
```

<sub>✅ admitted (12 gates green) · 🟡 WIP · 🧭 planned. Colors by state: green admitted, amber WIP, slate planned, purple binary root. Arrows read "depends on": all point downward.</sub>

## Layer breakdown

| Layer    | Admitted                                                                                                          | WIP | Planned                                                          | Notes                                                                           |
| -------- | ----------------------------------------------------------------------------------------------------------------- | --- | ---------------------------------------------------------------- | ------------------------------------------------------------------------------- |
| **L0**   | nika-types, nika-error, nika-catalog, nika-catalog-codegen, nika-schema, nika-event                               | —   | binding, transform, pck-manifest                                 | Pure sync, zero I/O.                                                            |
| **L0.5** | nika-kernel (facade), nika-kernel-core, nika-kernel-ai, nika-kernel-runtime, nika-kernel-plugin, nika-kernel-mock | —   | —                                                                | Trait definitions (4-way split + facade hub) + mock companion. Async OK         |
| **L1**   | nika-fs, nika-http, nika-exec-runner, nika-clock, nika-providers                                                  | —   | git, keys-\*, pck-registry, pck-store, memory-satellites (v0.95) | Effect impls. Each declares capability axes                                     |
| **L2**   | nika-verb-infer, nika-verb-exec, nika-verb-invoke, nika-verb-agent, nika-builtin                                  | —   | pck, memory (v0.95), observability, builtin-                     | Verbs + domain services (`fetch` is the `nika:fetch` builtin, not a verb crate) |
| **L3**   | nika-runtime                                                                                                      | —   | shield, wasm-host (v0.100), sandbox (v0.100)                     | Runtime + policy                                                                |
| **L4**   | nika-catalog-verify, nika-cli, nika-mcp, nika-lsp                                                                 | —   | serve, sdk                                                       | Interfaces, libraries                                                           |
| **L5**   | nika                                                                                                              | —   | —                                                                | The public binary surface                                                       |

## Memory subsystem (the Connectome): separate count

The memory subsystem is **11 crates** — 1 L2 orchestrator + 10 L1
satellites — and is **not counted** in the  crate
horizon. It lands **whole before 1.0** (the
timeline's [connectome gate](https://nika.sh/timeline#gates) · a declared
pre-condition of the launch), via the `MemoryStore` + `EmbeddingProvider`
trait reservations already in `nika-kernel`.

<AccordionGroup>
  <Accordion title="L2 orchestrator" icon="brain">
    `nika-connectome` ties the 10 satellites together behind the `MemoryStore`
    trait. Exposes unified put / query / forget / recall API.
  </Accordion>

  <Accordion title="L1 satellites (10)" icon="satellite-dish">
    * `nika-hnsw`, approximate nearest neighbor (HNSW index)
    * `nika-bm25`, sparse full-text ranking
    * `nika-rrf`, reciprocal-rank fusion (hybrid search)
    * `nika-rerank`, local reranking for precision
    * `nika-fsrs`, Free Spaced Repetition Scheduler (memory decay)
    * `nika-rdfs-reasoner`, RDFS inference for knowledge triples
    * `nika-temporal`, time-aware recency + decay
    * `nika-graph-algos`, graph traversal (shortest-path, community)
    * `nika-autodesc-minimal`, provenance-attached auto-description
    * `nika-autodesc-full`, schema-evolving auto-description
  </Accordion>
</AccordionGroup>

## Admission queue

Current admission order (per Q5 decision, rev.2):

<Steps>
  <Step title="Round 3: nika-catalog-codegen">
    Extract TOML → Rust codegen to its own L0 crate. Independent of other
    crates; unblocks faster iteration on catalog data.
  </Step>

  <Step title="Round 4: nika-schema">
    Complete parser + DAG + ariadne diagnostics. Unblocks verb crates
    (they need to parse `.nika.yaml` step shapes).
  </Step>

  <Step title="Round 5: nika-event + nika-transform">
    Event envelope + 65 transforms. Can run in parallel.
  </Step>

  <Step title="Round 6: nika-binding + nika-pck-manifest">
    Template engine + package manifest. Binding depends on transform.
  </Step>

  <Step title="Rounds 7-10: verbs">
    One verb per round: infer → exec → invoke → agent (fetch is the
    `nika:fetch` builtin under `invoke`, not a verb crate).
  </Step>

  <Step title="Rounds 11-15: effects + runtime">
    L1 effect crates (fs, http, process, keys, provider-\*) and L3 runtime.
  </Step>

  <Step title="Rounds 16+: interfaces + binary">
    L4 cli / serve / mcp / lsp / sdk and the L5 `nika` binary.
  </Step>
</Steps>

<Note>
  No hard timeline per admission round. Real semver toward 1.0: quality
  over speed. Each admission = 1 atomic commit, on the tagged 0.9x train
  (`1.0.0-rc.N` when the release-candidate window opens).
</Note>

## See also

<CardGroup>
  <Card title="Live state" icon="gauge" href="/reference/status">
    HEAD, tests, hygiene: the drift-proof snapshot.
  </Card>

  <Card title="Layer registry" icon="layer-group" href="/architecture/layers">
    Six layers, mechanical sort test, security axes.
  </Card>

  <Card title="12-gate admission" icon="check-double" href="/architecture/admission">
    How a crate earns a seat at the workspace.
  </Card>

  <Card title="L0 foundation decisions" icon="list-check" href="/architecture/l0-decisions">
    Q1-Q13 decisions that shaped today's L0 layout.
  </Card>
</CardGroup>


# Design system (machine-readable)
Source: https://docs.nika.sh/reference/design-system

The nika icon ontology as data: every verb, builtin, feature and run-state with its canonical glyph, hue and motion — served as JSON, Turtle and SVG.

Every Nika **verb**, **builtin**, **feature** and **run-state** carries a
canonical icon, color role and motion pattern — declared once in an
ontology and served as data from [nika.sh/brand](https://nika.sh/brand).
If you're building a dashboard, an editor integration or an agent surface
on top of Nika, take the visual language from here instead of inventing
one: your run view and the official surfaces stay one system.

## The served surfaces

| Surface        | URL                                                                                                          | What it is                                                                                                                                                                                                                     |
| -------------- | ------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Icon catalog   | `https://nika.sh/brand/icons/<namespace>-<name>.svg`                                                         | One SVG per entity (e.g. [`verb-infer`](https://nika.sh/brand/icons/verb-infer.svg) · [`builtin-fetch`](https://nika.sh/brand/icons/builtin-fetch.svg) · [`state-recovered`](https://nika.sh/brand/icons/state-recovered.svg)) |
| JSON ontology  | [`/brand/icons.json`](https://nika.sh/brand/icons.json)                                                      | Labels, semantics, hue tokens, effects and links for every entity                                                                                                                                                              |
| RDF projection | [`/brand/icons.ttl`](https://nika.sh/brand/icons.ttl)                                                        | The same graph in Turtle — SPARQL-ready, namespace [`nkd:`](https://nika.sh/ontology/design/)                                                                                                                                  |
| Identity kit   | [`/brand/`](https://nika.sh/brand) + [BRAND.md](https://github.com/supernovae-st/nika.sh/blob/main/BRAND.md) | The butterfly-supernova marks, lockups, tiles and usage rules                                                                                                                                                                  |

Entity ids are `<namespace>/<name>` across seven namespaces: `verb` ·
`builtin` · `feature` · `state` · `ui` · `social` · `anim`. The builtin
entries track the -builtin stdlib — the ontology is
parity-gated against the spec canon, so a new builtin cannot ship without
its icon.

## The color law

The four verb hues mean **a run is alive** — they appear only on live-run
surfaces (an executing DAG, a replay). Static UI renders every icon in the
surrounding text ink. If you consume the catalog, keep that rule: it is
what makes color a signal instead of decoration.

| Verb     | Hue              |
| -------- | ---------------- |
| `infer`  | blue `#5b8cff`   |
| `exec`   | orange `#ff7a3c` |
| `invoke` | cyan `#22d3ee`   |
| `agent`  | violet `#b07bff` |

## Motion

The `anim/*` entities define the dot-matrix motion register: each verb's
pattern is its execution model — `infer` samples (a sparkle emerges from
seeded noise), `exec` scans like stdout, `invoke` round-trips, `agent`
orbits its bounded loop. The pattern names and parameters ride
`icons.json`; the reference renderer lives in the
[site source](https://github.com/supernovae-st/nika.sh/tree/main/src/fx/dotmatrix).

## Querying the ontology

The Turtle projection answers SPARQL. For example, every builtin and its
glyph:

```sparql theme={"system"}
PREFIX nkd: <https://nika.sh/ontology/design#>
SELECT ?entity ?label ?glyph WHERE {
  ?entity a nkd:Builtin ;
          rdfs:label ?label ;
          nkd:glyph ?glyph .
}
```

Classes: `nkd:Verb` · `nkd:Builtin` · `nkd:Feature` · `nkd:RunState` ·
`nkd:UiGlyph` · `nkd:SocialMark` · `nkd:Animation`. Relations worth
knowing: `nkd:parent` (every builtin points at `verb/invoke` — everything
callable is a tool reached through `invoke:`), `nkd:sharesGlyphWith`
(deliberate glyph reuse, e.g. the `compose` builtin and the check feature
share the shield — same oracle), and `nkd:hueToken` (the CSS custom
property a hue rides on the official surfaces).


# Error codes
Source: https://docs.nika.sh/reference/error-codes

The typed error model: namespaces, categories, and the registered v0.1 codes. Generated from the spec registry.

Every error Nika emits is a **typed structure** with a stable code, a
category, and a `transient` flag the retry machinery reads. The format is
`NIKA-<NAMESPACE>-<NNN>`. An optional sub-namespace self-documents builtin
errors (`NIKA-BUILTIN-WAIT-001`). The full grammar:

```
^NIKA-[A-Z]{2,9}(-[A-Z][A-Z0-9_]{1,15})?-[0-9]{3}$
```

<Info>
  **Canonical source:** [`spec/05-errors.md`](https://github.com/supernovae-st/nika-spec/blob/main/spec/05-errors.md)
  owns the taxonomy: engines *derive* from it, never the reverse. The
  machine-readable registry lives in the spec's
  [`canon.yaml`](https://github.com/supernovae-st/nika-spec/blob/main/canon.yaml)
  and is also served as JSON at
  [`nika.sh/errors/catalog.json`](https://nika.sh/errors/catalog.json).
  The tables below are generated from that registry.
</Info>

## The error shape

```json theme={"system"}
{
  "code": "NIKA-INFER-001",
  "category": "provider_error",
  "message": "Anthropic API returned 503 service unavailable",
  "transient": true,
  "details": { "provider": "anthropic", "status_code": 503 },
  "task_id": "research",
  "attempt": 2
}
```

`transient: true` means a retry might succeed. `retry:` only fires on
transient errors (unless `on_codes:` widens it). `on_error:` catches the
final error either way, and `on_error.on_codes` routes recovery by exact
code.

## Categories

| Category           | Meaning                                                           |
| ------------------ | ----------------------------------------------------------------- |
| `parse_error`      | Workflow YAML is malformed or invalid                             |
| `validation_error` | Workflow violates a spec rule (cycle · unknown field · …)         |
| `variable_error`   | Reference to undefined variable or invalid path                   |
| `provider_error`   | LLM provider returned an error                                    |
| `network_error`    | Network failure (DNS · TCP · TLS · timeout)                       |
| `tool_error`       | Builtin or MCP tool returned an error                             |
| `process_error`    | exec: subprocess failure (non-zero exit · spawn)                  |
| `budget_error`     | An agent: loop budget exhausted (max\_turns · max\_tokens\_total) |
| `security_error`   | SSRF · blocklist · capability denied                              |
| `timeout_error`    | Task or step exceeded its timeout                                 |
| `cancelled`        | Workflow or task cancelled                                        |
| `internal_error`   | Engine bug · unexpected state                                     |

## The registered codes (v0.1 normative floor)

A conformant engine emits exactly these  codes for these failures. Engines
may add codes within a namespace's `001-099` range. Never repurpose one.

| Code                    | Failure                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | Category                                                                                               | `transient`        |       |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ | ------------------ | ----- |
| `NIKA-PARSE-001`        | the YAML itself does not parse (syntax error)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | `parse_error`                                                                                          | false              |       |
| `NIKA-PARSE-002`        | missing envelope field (nika: / workflow: / non-empty tasks:)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | `validation_error`                                                                                     | false              |       |
| `NIKA-PARSE-003`        | nika: version marker is not exactly v1                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | `parse_error`                                                                                          | false              |       |
| `NIKA-PARSE-004`        | workflow: id violates ^\[a-z]\[a-z0-9-]\*\$                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | `validation_error`                                                                                     | false              |       |
| `NIKA-PARSE-005`        | unknown field — strict mode rejects anything outside the closed v1 set                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | `validation_error`                                                                                     | false              |       |
| `NIKA-PARSE-006`        | task id violates ^\[a-z]\[a-z0-9\_]\*\$ (snake\_case · CEL-safe · no hyphens)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | `validation_error`                                                                                     | false              |       |
| `NIKA-PARSE-007`        | duplicate task id within the workflow                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | `validation_error`                                                                                     | false              |       |
| `NIKA-PARSE-008`        | task declares no verb — exactly one of infer/exec/invoke/agent required                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | `validation_error`                                                                                     | false              |       |
| `NIKA-PARSE-009`        | task declares multiple verbs — exactly one required                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | `validation_error`                                                                                     | false              |       |
| `NIKA-PARSE-010`        | timeout: violates the quoted Go-duration contract (positive · max 24h · descending units)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | `validation_error`                                                                                     | false              |       |
| `NIKA-PARSE-011`        | retry: block violates the spec shape                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | `validation_error`                                                                                     | false              |       |
| `NIKA-PARSE-012`        | on\_error: block violates the spec shape (fields mutually exclusive)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | `validation_error`                                                                                     | false              |       |
| `NIKA-PARSE-013`        | with:/output: binding uses a reserved name (output · status · error · started\_at · ended\_at · duration\_ms)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | `validation_error`                                                                                     | false              |       |
| `NIKA-PARSE-014`        | secrets: entry is not a store reference — inline literals forbidden                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | `validation_error`                                                                                     | false              |       |
| `NIKA-PARSE-017`        | duplicate mapping key — no silent last-wins                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | `validation_error`                                                                                     | false              |       |
| `NIKA-PARSE-018`        | missing required field in a verb body (infer.prompt · exec.command · invoke.tool)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | `validation_error`                                                                                     | false              |       |
| `NIKA-PARSE-019`        | generic structural validation — wrong YAML shape for a field                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | `validation_error`                                                                                     | false              |       |
| `NIKA-PARSE-020`        | workflow: is a scalar — the envelope became an object (workflow: then id: \<value>)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | `validation_error`                                                                                     | false              |       |
| `NIKA-PARSE-021`        | top-level description: — it moved into workflow\.description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | `validation_error`                                                                                     | false              |       |
| `NIKA-PARSE-022`        | tasks: is a sequence — it became a map keyed by task id (drop `- id:`, the key IS the identity)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | `validation_error`                                                                                     | false              |       |
| `NIKA-PARSE-023`        | a task carries an id: field — the map key is the identity, the field is gone                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | `validation_error`                                                                                     | false              |       |
| `NIKA-PARSE-024`        | a task carries depends\_on: — dead since W2 (data → with: bindings · control → after: predicates · check --fix migrates)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | `validation_error`                                                                                     | false              |       |
| `NIKA-PARSE-025`        | decode: with capture: structured — that capture already IS an object · type it with returns:                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | `validation_error`                                                                                     | false              |       |
| `NIKA-PARSE-026`        | a declared entropy x clock contradiction · entropy: ambient paired with clock: virtual — the ambient declaration contradicts the determinism demand (NEP-0010 · F-P3)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | `validation_error`                                                                                     | false              |       |
| `NIKA-PARSE-027`        | a declared entropy x clock contradiction · entropy: none                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | seeded paired with clock: system — deterministic journals cannot ride the wall clock (NEP-0010 · F-P3) | `validation_error` | false |
| `NIKA-PARSE-028`        | entropy: none declares strict determinism while a structural randomness source is consumed (a live retry jitter · nika:uuid) — the strict declaration cannot hold (NEP-0010 · F-P3 · judged at check)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | `validation_error`                                                                                     | false              |       |
| `NIKA-COMP-001`         | invoke.workflow: target is not statically resolvable (templated · malformed · unpinned registry ref) — a call graph you cannot draw before the run cannot be bounded (spec 14)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | `validation_error`                                                                                     | false              |       |
| `NIKA-COMP-002`         | the child workflow's effect boundary exceeds the parent capped by the call-site declaration (Authority(child) subset of Authority(parent) intersect declared · spec 14 laws 3/4)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | `security_error`                                                                                       | false              |       |
| `NIKA-COMP-003`         | the static call graph is not acyclic (self-launch · cycle · spec 14 law 7 · NIKA-SEC-003 is the runtime depth backstop)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | `validation_error`                                                                                     | false              |       |
| `NIKA-COMP-004`         | the typed call does not compose — parent args do not fit child inputs, or child outputs do not fit parent returns (spec 14 law 2)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | `validation_error`                                                                                     | false              |       |
| `NIKA-DAG-001`          | cycle in the precedence graph G\_p = E\_d ∪ E\_c (incl. self-dependency · via with:/after:)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | `validation_error`                                                                                     | false              |       |
| `NIKA-DAG-002`          | with:/after: references an undeclared task                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | `validation_error`                                                                                     | false              |       |
| `NIKA-DAG-004`          | on\_error.recover references a task downstream of the declaring task (await would deadlock)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | `validation_error`                                                                                     | false              |       |
| `NIKA-DAG-005`          | after: predicate outside the closed set (success · failure · skipped · terminal)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | `validation_error`                                                                                     | false              |       |
| `NIKA-DAG-006`          | statically dead task — an incoming edge's pass-set excludes every reachable producer state, or the when: gate is false under every reachable upstream combination (gate algebra v2)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | `validation_error`                                                                                     | false              |       |
| `NIKA-DAG-007`          | status compared against a literal outside the vocabulary (success · failure · skipped · cancelled) — == never matches, != always holds                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | `validation_error`                                                                                     | false              |       |
| `NIKA-TYPE-001`         | unknown type name (in types: · returns: · an outputs: type) — did-you-mean when close                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | `validation_error`                                                                                     | false              |       |
| `NIKA-TYPE-002`         | recursive type reference — the types: graph must be acyclic                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | `validation_error`                                                                                     | false              |       |
| `NIKA-TYPE-003`         | returns: and schema: on the same task — one contract, one spelling                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | `validation_error`                                                                                     | false              |       |
| `NIKA-TYPE-004`         | returns: type unreachable from the declared decode: (an object contract over decode: text · …)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | `validation_error`                                                                                     | false              |       |
| `NIKA-TYPE-005`         | a secret-carrying type in a lowered position (reserved with secret\<T> · W4)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | `security_error`                                                                                       | false              |       |
| `NIKA-TYPE-006`         | regex pattern outside the locked dialect (backreference · lookaround · named group · inline flags · lazy/possessive · word-boundary · unicode-class — spec 09 §the regex dialect)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | `validation_error`                                                                                     | false              |       |
| `NIKA-TYPE-101`         | run-time contract violation — the decoded value does not fit returns: (exec:/invoke: lane)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | `validation_error`                                                                                     | false              |       |
| `NIKA-VAR-001`          | unresolved reference (unknown namespace entry · undeclared inputs/config/const/secrets/with key)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | `variable_error`                                                                                       | false              |       |
| `NIKA-VAR-002`          | binding cardinality — a jq binding emitted zero or multiple values                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | `variable_error`                                                                                       | false              |       |
| `NIKA-VAR-003`          | provably-invalid path into a declared schema (static walk)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | `validation_error`                                                                                     | false              |       |
| `NIKA-VAR-004`          | jq runtime error while evaluating a binding                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | `variable_error`                                                                                       | false              |       |
| `NIKA-VAR-005`          | static expression violation — outside cel-subset/0.1 · chained relation · unknown function · non-boolean when: root · jq compile error                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | `validation_error`                                                                                     | false              |       |
| `NIKA-VAR-006`          | expression type error at evaluation — cross-type compare · non-boolean when: value · for\_each over a non-array                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | `variable_error`                                                                                       | false              |       |
| `NIKA-VAR-007`          | bytes value substituted into a string position                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | `variable_error`                                                                                       | false              |       |
| `NIKA-VAR-008`          | unclosed \$\{\{ opener                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | `validation_error`                                                                                     | false              |       |
| `NIKA-VAR-020`          | bare tasks.X is the envelope, not a value — the projection set (.output/.status/.error/.duration\_ms) is closed and required (04 §namespaces · 0.103 · #75 D2)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | `validation_error`                                                                                     | false              |       |
| `NIKA-VAR-021`          | a tasks.\* reference outside the boundary (with: · after: · on\_error.recover · on\_finally parent-only · workflow outputs) — hoist it into with: (check --fix applies it)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | `validation_error`                                                                                     | false              |       |
| `NIKA-VAR-009`          | typed outputs value did not match its declared type: at run end (the output half of the callable contract)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | `validation_error`                                                                                     | false              |       |
| `NIKA-INFER-001`        | provider call failed (HTTP error · provider refusal)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | `provider_error`                                                                                       | engine-assessed    |       |
| `NIKA-INFER-002`        | structured output failed schema validation (after any engine-internal retries)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | `validation_error`                                                                                     | false              |       |
| `NIKA-INFER-003`        | the provider reported no token usage for a priced model — the ledger cannot bill the call honestly (fail-closed · R3-F1)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | `validation_error`                                                                                     | false              |       |
| `NIKA-EXEC-001`         | non-zero exit code (default capture modes)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | `process_error`                                                                                        | false              |       |
| `NIKA-EXEC-002`         | spawn failure (command not found · permission)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | `process_error`                                                                                        | false              |       |
| `NIKA-INVOKE-001`       | unknown tool (unresolvable nika:/mcp: id)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | `validation_error`                                                                                     | false              |       |
| `NIKA-INVOKE-002`       | tool args failed the tool's schema                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | `validation_error`                                                                                     | false              |       |
| `NIKA-AGENT-001`        | max\_turns exhausted before completion                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | `budget_error`                                                                                         | false              |       |
| `NIKA-AGENT-002`        | max\_tokens\_total exhausted before completion                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | `budget_error`                                                                                         | false              |       |
| `NIKA-AGENT-003`        | a skills: path does not resolve (file missing/unreadable at compose time)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | `validation_error`                                                                                     | false              |       |
| `NIKA-AGENT-004`        | a skills: file is not a valid Agent Skill (frontmatter shape · missing/empty name/description)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | `validation_error`                                                                                     | false              |       |
| `NIKA-AGENT-005`        | the provider reported no token usage for a priced model — every budget and ledger reads the turn as free, so the loop fails closed (R3-F1 · the usage-absence gate)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | `budget_error`                                                                                         | false              |       |
| `NIKA-MCP-001`          | MCP server not configured / not reachable at call time                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | `tool_error`                                                                                           | engine-assessed    |       |
| `NIKA-MCP-002`          | MCP tool call failed (transport · tool-side error)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | `tool_error`                                                                                           | engine-assessed    |       |
| `NIKA-DECIDE-001`       | the decision bundle is malformed or violates its own laws (float weight · undeclared evidence key in rules · identity key feeding a technical dimension · missing contradictory fixture · monotonicity violated by the bundle's own fixtures) (spec 11)                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | `validation_error`                                                                                     | false              |       |
| `NIKA-DECIDE-002`       | the evidence snapshot does not satisfy the bundle's evidence schema (type misfit · unauthorized source · integrity below the declared floor · undeclared key) (spec 11)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | `validation_error`                                                                                     | false              |       |
| `NIKA-POLICY-001`       | a hard policy: rule is violated (require.human\_gate\_before · forbid.exec\_after · allow\.providers · limits.max\_tasks) — the diagnostic names rule + task + witness (order rules: the path) · check-time, before any token (spec 10)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | `security_error`                                                                                       | false              |       |
| `NIKA-PORT-001`         | a gateway artifact (deployment bundle · capabilities report · lowering report · fidelity report · authority delta) is malformed or violates its laws (unknown promoted · permissive\_unsafe without refusal · disclosure subset-chain violated · child authority exceeding parent) (spec 12)                                                                                                                                                                                                                                                                                                                                                                                                                                    | `validation_error`                                                                                     | false              |       |
| `NIKA-PORT-002`         | policy lowering is permissive\_unsafe — the backend would allow what the policy forbids · refused with the divergence witness (spec 12)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | `security_error`                                                                                       | false              |       |
| `NIKA-SEC-001`          | exec: blocklist hit                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | `security_error`                                                                                       | false              |       |
| `NIKA-SEC-002`          | agent tool call outside the tools: whitelist                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | `security_error`                                                                                       | false              |       |
| `NIKA-SEC-003`          | run-recursion bound — nested-run depth exceeded OR self-launching workflow                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | `security_error`                                                                                       | false              |       |
| `NIKA-SEC-004`          | effect outside the declared permits: capability boundary (fs/net/exec/tool)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | `security_error`                                                                                       | false              |       |
| `NIKA-SEC-005`          | SSRF block — a nika:fetch/nika:notify URL resolves to a loopback/private/link-local/metadata target (always-on engine floor · independent of permits:)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | `security_error`                                                                                       | false              |       |
| `NIKA-SEC-006`          | secret flow — a secrets.\<name> value reaches an unsanctioned sink (exec argument · invoke payload · infer/agent prompt) · the diagnostic carries the taint path + the egress clause that would sanction it (spec 10 · flow rules in 01 §egress)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | `security_error`                                                                                       | false              |       |
| `NIKA-SEC-007`          | secret egress — a tainted value reaches the workflow boundary (outputs:) · the diagnostic carries the taint path (spec 10 · the to: outputs sanction in 01 §egress)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | `security_error`                                                                                       | false              |       |
| `NIKA-SEC-008`          | data-as-code sink · a nika:fetch resolved URL path names a code-bearing class (serialized-executable · script/interpreter · executable binary/module · the closed NEP-0006 list) and the task declares no inert: door · the read hides an execution sink (F-O7 · NEP-0006)                                                                                                                                                                                                                                                                                                                                                                                                                                                      | `security_error`                                                                                       | false              |       |
| `NIKA-SEC-009`          | lethal trifecta complete — the declared boundary grants private read (fs.read non-empty) + untrusted ingress (a nika:fetch builtin invoked · an mcp:\* tool invoked · an agent: whose whitelist admits ingress · an exec: task, permits.exec itself the ingress channel) + external egress (net.http non-empty · an escaping fs.write glob · exec enabled), the untrusted content REACHES an egress-capable task's effect surface (a realized flow), and no blocking invoke: nika:prompt (no default:) dominates it (NEP-0002 v2.0 · the Rule of Two as a static check)                                                                                                                                                         | `security_error`                                                                                       | false              |       |
| `NIKA-SEC-010`          | the approval-capability law is violated · a rate-limited approval burst (the N+1th distinct mint of a run) · an approval whose resolved content hash differs from the shown hash (content\_mismatch) · a ticket replayed across runs or steps (scope\_mismatch) · or the static heterogeneous-batch refusal (one prompt unleashing two or more effect classes) — the 6th invariant (NEP-0013 · F-P4)                                                                                                                                                                                                                                                                                                                            | `security_error`                                                                                       | false              |       |
| `NIKA-SEC-011`          | preview-commit divergence — the commit digest recomputed at the sink over the exact bytes about to fire differs from the preview digest computed at resolution (one bit of rendered argv · a permuted context field · a mutated tool argument) · the step refuses fail-closed and the receipt carries divergence:\{preview, commit} — judged = executed at the action scale (NEP-0015 · F-P6)                                                                                                                                                                                                                                                                                                                                   | `security_error`                                                                                       | false              |       |
| `NIKA-SEC-012`          | unordered shared writes — two tasks incomparable in the DAG closure whose literal nika:write/nika:edit paths collide with no ordering edge (after: · with:) to serialize them, or a for\_each fan writing one constant path · parallelism is safe exactly where the writes are provably disjoint (NEP-0014 law 1 · F-P15)                                                                                                                                                                                                                                                                                                                                                                                                       | `security_error`                                                                                       | false              |       |
| `NIKA-SEC-013`          | the endorsement mode law — a human gate (invoke: nika:prompt) declared under a policy: block that names no endorsement mode refuses fail-closed (endorsement.undeclared\_mode · F-F5 · zero implicit escape), and endorsement: solo carried by a workflow with more than one gate refuses as the declaration lying (endorsement.solo\_count · exactly one endorser) (NEP-0017 · F-P23)                                                                                                                                                                                                                                                                                                                                          | `security_error`                                                                                       | false              |       |
| `NIKA-SEC-014`          | the affirmative-consent law — a confirm-mode human gate (invoke: nika:prompt · mode absent or confirm) reaches an egress-capable task over a route no affirmative gate closes: a REFUSED confirm settles success with value false, so a bare after: \{ gate: success } edge, a when: that never reads the answer, and a when: provably true on the refusal all let the effect through · the gate is credited only when every route consumes the answer and proves false on it (the Kleene-falsifiable when: · when: false · a closer confirm gate owns its closure) · an undecidable gate (a nested binding · a non-fragment expression) defers to the advisory hint, never a refusal (NEP-0020 · P0-2 of the 2026-07-30 audit) | `security_error`                                                                                       | false              |       |
| `NIKA-TIMEOUT-001`      | task (or for\_each iteration) exceeded timeout:                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | `timeout_error`                                                                                        | false              |       |
| `NIKA-CANCEL-001`       | task cancelled (workflow failure gate · user cancellation)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | `cancelled`                                                                                            | false              |       |
| `NIKA-ASSERT-001`       | an assert: claims a level the evidence does not support (a StaticProof the IR cannot decide · a mis-leveled obligation · spec 15)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | `validation_error`                                                                                     | false              |       |
| `NIKA-LOCK-001`         | a dependency resolved that nika.lock does not pin, or a hand-edited lock digest does not match (pin-by-default · the lock's own hash catches the edit · spec 15)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | `validation_error`                                                                                     | false              |       |
| `NIKA-BUILTIN-001`      | builtin invoke violates its statically-checkable arg contract (e.g. nika:fetch without url: · nika:jq arg shape)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | `validation_error`                                                                                     | false              |       |
| `NIKA-BUILTIN-DONE-001` | nika:done invoked outside an agent: loop                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | `validation_error`                                                                                     | false              |       |
| `NIKA-DRIFT-001`        | declared-but-unused — a vars\:/env:/secrets: name or a permits: entry (exec program · tool glob · net host · fs path) that nothing in the body references (advisory check hint · never fails the audit — the reverse direction, used-but-undeclared, is the hard NIKA-VAR-001/NIKA-DAG-002/NIKA-SEC-004 surface)                                                                                                                                                                                                                                                                                                                                                                                                                | `validation_error`                                                                                     | false              |       |
| `NIKA-AUTH-006`         | no permits: block declared and the body has effects — absent = zero authority (F-O8 · NEP-0003)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | `security_error`                                                                                       | false              |       |
| `NIKA-AUTH-007`         | an interpolation reaches a permit bound (host · glob · program · env name) — a bound MUST be a literal, the boundary would be self-serve (F-O1 · NEP-0004 · env per NEP-0005)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | `security_error`                                                                                       | false              |       |
| `NIKA-AUTH-008`         | an untrusted value reaches a permitted verb's argument and its canonical resolved form escapes the step's permit — re-gate refused (F-O1 · NEP-0004)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | `security_error`                                                                                       | false              |       |
| `NIKA-AUTH-009`         | a permits env: entry names a dangerous-floor variable · the engine strips the name unconditionally, the grant can never take effect: an inert dead grant (F-O4 · NEP-0005)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | `security_error`                                                                                       | false              |       |
| `NIKA-AUTH-010`         | a permits net.http: entry carries the \*. subdomain wildcard · the grant delegates the boundary to the zone operator (every host under the suffix, present and future) — refused: name exact hosts, or the bare \* when allow-all is genuinely intended (F-P5 · NEP-0008)                                                                                                                                                                                                                                                                                                                                                                                                                                                       | `security_error`                                                                                       | false              |       |
| `NIKA-VALUES-001`       | vars: is a dead envelope field (R3a · the E-split)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | `validation_error`                                                                                     | false              |       |
| `NIKA-VALUES-002`       | env: is a dead envelope field (R3a · the E-split)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | `validation_error`                                                                                     | false              |       |
| `NIKA-VALUES-003`       | a value-namespace read outside the four-authority family (R3a · LAW-SURFACE-0201)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | `validation_error`                                                                                     | false              |       |
| `NIKA-DEFAULT-001`      | a declared default (inputs · config) or typed const value does not conform to its declared type (R3b · LAW-TYPE-0211)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | `validation_error`                                                                                     | false              |       |

### Retired codes (never reuse)

Two allocation holes in the table above are deliberate — a retired code is
never repurposed:

* **`NIKA-PARSE-016`** — the jq-binding-contains-template class folded into
  `NIKA-VAR-005`.
* **`NIKA-DAG-003`** — « a `tasks.X` reference with no declared edge »
  became **inexpressible** in W2 « the flow »: the `with:` binding IS the
  edge (derived, never restated), and a reference outside the boundary is
  `NIKA-VAR-021`.

## Namespaces

| Namespace       | Scope                                           | Range   |
| --------------- | ----------------------------------------------- | ------- |
| `NIKA-AGENT`    | agent: verb errors                              | 001-099 |
| `NIKA-ASSERT`   |                                                 | 001-099 |
| `NIKA-AUTH`     |                                                 | 001-099 |
| `NIKA-BUILTIN`  | Builtin tool errors · per-builtin sub-namespace | 001-099 |
| `NIKA-CANCEL`   | Task or workflow cancellation                   | 001-099 |
| `NIKA-COMP`     |                                                 | 001-099 |
| `NIKA-DAG`      | DAG topology · cycles · invalid deps            | 001-099 |
| `NIKA-DEFAULT`  |                                                 | 001-099 |
| `NIKA-EXEC`     | exec: verb errors                               | 001-099 |
| `NIKA-IMPL`     | Engine internal errors                          | 001-099 |
| `NIKA-INFER`    | infer: verb errors                              | 001-099 |
| `NIKA-INVOKE`   | invoke: verb errors                             | 001-099 |
| `NIKA-LOCK`     |                                                 | 001-099 |
| `NIKA-MCP`      | MCP client errors                               | 001-099 |
| `NIKA-DECIDE`   |                                                 | 001-099 |
| `NIKA-DRIFT`    |                                                 | 001-099 |
| `NIKA-PARSE`    | YAML parse + envelope validation                | 001-099 |
| `NIKA-POLICY`   |                                                 | 001-099 |
| `NIKA-PORT`     |                                                 | 001-099 |
| `NIKA-PROVIDER` | Provider adapter errors                         | 001-099 |
| `NIKA-SEC`      | Security policy violations (SSRF · blocklist)   | 001-099 |
| `NIKA-TIMEOUT`  | Task or step timeouts                           | 001-099 |
| `NIKA-TYPE`     |                                                 | 001-099 |
| `NIKA-VAR`      | Variable resolution failures                    | 001-099 |
| `NIKA-VALUES`   |                                                 | 001-099 |

Builtin errors use a per-builtin sub-namespace: each builtin owns its own
`001-099` (`NIKA-BUILTIN-FETCH-001` is the fetch tool's network/extraction
failure). Underscore-named builtins encode naturally:
`NIKA-BUILTIN-JSON_MERGE_PATCH-001`.

## Routing on codes

```yaml theme={"system"}
# Retry ONLY on the fetch network error · fixed 30s backoff
retry:
  max_attempts: 5
  backoff_strategy: fixed
  backoff_ms: 30000
  on_codes: [NIKA-BUILTIN-FETCH-001]

# Recover ONLY on timeout · any other code still fails
on_error:
  on_codes: [NIKA-TIMEOUT-001]
  recover: { stale: true, items: [] }
```

`on_error.skip` preserves the original error at `tasks.X.error`: a
downstream task can branch on `${{ tasks.X.error.code }}` while the status
reads `skipped`.

<Card title="The full error model" icon="book" href="https://github.com/supernovae-st/nika-spec/blob/main/spec/05-errors.md">
  Retry policies, backoff strategies, recovery semantics, and the
  gate-based failure propagation rules. See spec/05-errors.md.
</Card>


# Machine surfaces
Source: https://docs.nika.sh/reference/machine-surfaces

The versioned JSON wires — every human surface has a machine twin, envelopes are versioned and additive-only, exit codes are a contract.

> The law: **every human-facing surface has a `--json` twin**, every
> machine payload carries a **version envelope**, and evolution is
> **additive-only** — a field is added, never renamed or removed within
> a version. Agents and tooling parse the JSON; the pretty output is
> free to improve without breaking anyone.

## The wires

| Surface                             | Envelope             | What it carries                                                                                                                                                                                                                                                                                                                                                                                                                      |
| ----------------------------------- | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `nika check <file> --json`          | `report_version`     | the full audit report: conformance findings (each with `code` · `severity` · `docs_url` · span), cost intervals per task, the derivation certificate, requirements (models · secrets · env), secret-flow findings, hints, pricing provenance (`pricing.snapshot`)                                                                                                                                                                    |
| `nika doctor --json`                | — (stable shape)     | the environment diagnosis: per-finding status + the exact fix command, key PRESENCE (never values), local provider reachability                                                                                                                                                                                                                                                                                                      |
| `nika catalog --json`               | `catalog_version`    | the provider/model vocabulary: models, capabilities, key env-var NAMES                                                                                                                                                                                                                                                                                                                                                               |
| `nika catalog --tools --json`       | `tools_version`      | the builtin tool catalog with model-facing JSON Schemas per tool                                                                                                                                                                                                                                                                                                                                                                     |
| `nika inspect <file> --format json` | `graph_format` (`2`) | the ONE graph projection: nodes (id · verb · model/tool · when · fan-out · permits · cost interval) + **typed edges** (`kind`: `value` · `terminal-observation` · `failure-observation` · `control` + `predicate` · `recovery` — `binding` on data edges) — mermaid and dot are derived from this, never parallel truths. Format 1 is dead: a reader refuses a format it does not speak; within format 2, evolution is additive-only |
| `nika run <file> --json`            | NDJSON stream        | the live event stream, one JSON object per line — the same events the trace records                                                                                                                                                                                                                                                                                                                                                  |
| `nika trace export`                 | OTLP                 | any recorded journal projected to OpenTelemetry (Jaeger · Grafana · Langfuse)                                                                                                                                                                                                                                                                                                                                                        |
| `nika spec --canon`                 | `schema_version`     | the embedded canon SSOT (counts and names — cite it, never a remembered number)                                                                                                                                                                                                                                                                                                                                                      |
| `nika spec --schema`                | JSON Schema `$id`    | the embedded workflow schema — the same one editors validate against                                                                                                                                                                                                                                                                                                                                                                 |

`nika check -` reads the workflow from **stdin** — editors and agents
audit keystroke-fresh buffers without touching the disk.

## The hosted twins

The same law reaches the web: the machine surfaces an agent can fetch
without a binary, each probed and versioned like the CLI wires.

| URL                                                                                                    | What it carries                                                                                                                             |
| ------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------- |
| [`nika.sh/spec/v1/workflow.schema.json`](https://nika.sh/spec/v1/workflow.schema.json)                 | the published workflow JSON Schema — the same one `nika spec --schema` embeds                                                               |
| [`nika.sh/errors/catalog.json`](https://nika.sh/errors/catalog.json)                                   | the error catalog, projected from the spec's normative table                                                                                |
| [`nika.sh/brand/icons.json`](https://nika.sh/brand/icons.json)                                         | the [design ontology](/reference/design-system): every verb, builtin, feature and run-state with glyph, hue and motion                      |
| [`nika.sh/brand/icons.ttl`](https://nika.sh/brand/icons.ttl)                                           | the same graph in Turtle — SPARQL-ready, namespace [`nkd:`](https://nika.sh/ontology/design/)                                               |
| [`nika.sh/llms.txt`](https://nika.sh/llms.txt)                                                         | the agent-readable site summary (llmstxt.org shape)                                                                                         |
| [registry `index.json`](https://raw.githubusercontent.com/supernovae-st/nika-registry/main/index.json) | every shared artifact with its pin, digest, cert summary and advisory state — resolve names here before installing anything an LLM suggests |

## The exit-code contract

Scripts and agents branch on exit codes, so they are the engine CLI
exit-code contract (locked · additive-only), not an accident:

| Code | Meaning                                                                                                                                                                                 |
| ---- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `0`  | success — clean check · completed run                                                                                                                                                   |
| `1`  | the workflow ran and failed (a task settled failed)                                                                                                                                     |
| `2`  | findings / usage / refusal — check findings, bad flags, the `--max-cost-usd` floor refusal                                                                                              |
| `3`  | environment — missing file, no golden to compare, binary-level trouble                                                                                                                  |
| `4`  | paused — the run parked on a blocking `nika:prompt` (durable pause · ADR-099) · not a failure but non-zero on purpose · resume with `nika run --resume <trace> --answer <task>=<value>` |

Stream discipline: product output goes to **stdout**, only
environmental noise goes to stderr — and in `--json` modes, progress
moves to stderr so stdout stays parseable.

## The MCP oracle

`nika mcp` serves the same truths over the Model Context Protocol
(stdio, read-only): validate (`nika_check` — a dirty workflow returns
`isError: true`, mirroring the CLI's exit 2) and learn (`nika_schema` ·
`nika_examples` · `nika_template` · `nika_canon` · `nika_catalog` ·
`nika_tools` · `nika_explain`). Same owning builders as the CLI
payloads — the two lanes cannot drift apart by construction.

## The evolution rules

* **Versioned**: breaking a payload shape means bumping its envelope
  field — consumers pin on it.
* **Additive-only within a version**: new fields appear, existing ones
  keep their meaning.
* **Deterministic**: stable key ordering, no timestamps injected into
  otherwise-stable payloads — machine output is cache- and
  diff-friendly.
* **Presence, never values**: no secret VALUE crosses any wire, human
  or machine. Requirements name the env var; doctor reports set/unset.

<Note>
  Next on this page once the next engine tag ships: `nika welcome --deep   --json` (`context_version`) — the whole workspace truth in one call
  (file map with per-file verdicts · run inventory with actual cost ·
  environment snapshot · wiring state · caps always reported, relative
  paths only). It is merged on `main` today and rides the next release.
</Note>


# MCP catalog
Source: https://docs.nika.sh/reference/mcp-catalog

Every MCP server Nika knows about by id. Registry schema + stdio/HTTP packages, with the catalog count derived in-page.

Nika ships with **105 MCP server entries** in its catalog, aligned with
the official [MCP Registry schema](https://registry.modelcontextprotocol.io/)
(`v2025-12-11`). Each entry declares one or more local-install
`packages` (npm / pypi / oci / cargo / mcpb) and/or `remotes`
(streamable-http / sse endpoints). The workflow YAML `invoke:` verb
references servers by id: Nika handles the rest.

<Info>
  **Canonical source:** [`crates/nika-catalog/data/mcp-servers.toml`](https://github.com/supernovae-st/nika/blob/main/crates/nika-catalog/data/mcp-servers.toml).
  Schema: `nika/mcp-servers@1.0`. Snapshot 2026-04-17: `grep -c '^\[\[servers\]\]'`
  \= **105**. Build-time invariants (enforced in `build.rs`): unique ids,
  packages+remotes non-empty, known category, pricing ∈ , alias non-collision.
</Info>

## Overview

<CardGroup>
  <Card title="Servers" icon="plug">
    **105** entries
  </Card>

  <Card title="Categories" icon="folder">
    **17**: from `anthropic` to `vectordb`
  </Card>

  <Card title="Invocation" icon="bolt">
    `invoke:` verb with `server: <id>`
  </Card>
</CardGroup>

## How to invoke one

<CodeGroup>
  ```yaml workflow.nika.yaml theme={"system"}
  nika: v1
  workflow:
    id: scrape-and-summarise

  permits:                              # an MCP tool is granted like any other
    exec: false
    tools: ["mcp:firecrawl/scrape"]     # the server's own reach is its side of the boundary

  tasks:
    crawl:
      invoke:
        tool: "mcp:firecrawl/scrape"   # mcp:<server>/<tool> · server id from the catalog below
        args:
          url: https://example.com

    summarise:
      with:
        page: ${{ tasks.crawl.output.content }}
      infer:
        model: anthropic/claude-sonnet-4-6   # <provider>/<name>
        prompt: "Summarise: ${{ with.page }}"
  ```

  ```bash Required env theme={"system"}
  # Each server declares its env_var in mcp-servers.toml.
  # Firecrawl needs FIRECRAWL_API_KEY — read mcp-servers.toml for the full
  # list. Run `nika doctor` to inspect provider readiness.
  export FIRECRAWL_API_KEY=fc-...
  nika run workflow.nika.yaml
  ```
</CodeGroup>

<Note>
  Verb `invoke:` is live in v. The Nika MCP catalog here is
  about workflows calling external MCP tools; Nika's own agent-facing MCP
  server remains read-only (9 tools — `nika_check` · `nika_explain` ·
  the authoring surface).
</Note>

## By category

<Tabs>
  <Tab title="Anthropic official (3)">
    Shipped by the Model Context Protocol project itself.

    | Id           | Title      | Registry | Identifier                                |
    | ------------ | ---------- | -------- | ----------------------------------------- |
    | `filesystem` | Filesystem | npm      | `@modelcontextprotocol/server-filesystem` |
    | `memory`     | Memory     | npm      | `@modelcontextprotocol/server-memory`     |
    | `pdf`        | PDF        | npm      | `@modelcontextprotocol/server-pdf`        |

    One-liners:

    * **filesystem**: read and write local files with path-based access control.
    * **memory**: persistent key/value memory store.
    * **pdf**: PDF text + structure extraction.
  </Tab>

  <Tab title="Developer tools (17)">
    Build systems, browser automation, error trackers, CI / CD.

    | Id                | Title                           | Registry | Identifier                          |
    | ----------------- | ------------------------------- | -------- | ----------------------------------- |
    | `aws`             | AWS                             | npm      | `aws-mcp`                           |
    | `bitbucket`       | Bitbucket                       | npm      | `@nexus2520/bitbucket-mcp-server`   |
    | `browserbase`     | Browserbase                     | npm      | `@browserbasehq/mcp`                |
    | `browserstack`    | BrowserStack                    | npm      | `@browserstack/mcp-server`          |
    | `chrome-devtools` | Chrome DevTools                 | npm      | `chrome-devtools-mcp`               |
    | `circleci`        | CircleCI                        | npm      | `@circleci/mcp-server-circleci`     |
    | `cloudflare`      | Cloudflare                      | npm      | `@cloudflare/mcp-server-cloudflare` |
    | `eslint`          | ESLint                          | npm      | `@eslint/mcp`                       |
    | `figma`           | Figma                           | npm      | `figma-developer-mcp`               |
    | `launchdarkly`    | LaunchDarkly                    | npm      | `@launchdarkly/mcp-server`          |
    | `linear`          | Linear                          | npm      | `mcp-server-linear`                 |
    | `nx`              | Nx                              | npm      | `nx-mcp`                            |
    | `playwright`      | Playwright (browser automation) | npm      | `@playwright/mcp`                   |
    | `postman`         | Postman                         | npm      | `@postman/postman-mcp-server`       |
    | `sentry`          | Sentry                          | npm      | `@sentry/mcp-server`                |
    | `vercel`          | Vercel                          | npm      | `vercel-mcp`                        |
    | `xcode`           | Xcode (build + simulator)       | npm      | `xcodebuildmcp`                     |
  </Tab>

  <Tab title="Productivity (12)">
    Calendars, project trackers, note-taking, knowledge bases.

    | Id                | Title                   | Registry | Identifier                            |
    | ----------------- | ----------------------- | -------- | ------------------------------------- |
    | `airtable`        | Airtable                | npm      | `airtable-mcp-server`                 |
    | `clickup`         | ClickUp                 | npm      | `@taazkareem/clickup-mcp-server`      |
    | `excel`           | Excel                   | npm      | `@negokaz/excel-mcp-server`           |
    | `google-calendar` | Google Calendar         | npm      | `@cocal/google-calendar-mcp`          |
    | `google-drive`    | Google Drive            | npm      | `@modelcontextprotocol/server-gdrive` |
    | `jira`            | Jira                    | npm      | `jira-mcp`                            |
    | `monday`          | Monday                  | npm      | `@mondaydotcomorg/monday-api-mcp`     |
    | `n8n`             | n8n                     | npm      | `n8n-mcp`                             |
    | `notion`          | Notion                  | npm      | `@notionhq/notion-mcp-server`         |
    | `obsidian`        | Obsidian (vault access) | npm      | `obsidian-mcp`                        |
    | `slack`           | Slack                   | npm      | `@modelcontextprotocol/server-slack`  |
    | `zendesk`         | Zendesk                 | npm      | `zendesk-mcp`                         |
  </Tab>

  <Tab title="AI & specialized (8)">
    Embeddings, agents, sandboxes, documentation lookup.

    | Id                    | Title               | Registry | Identifier                                         |
    | --------------------- | ------------------- | -------- | -------------------------------------------------- |
    | `21st`                | 21st.dev Magic      | npm      | `@21st-dev/magic`                                  |
    | `ahrefs`              | Ahrefs              | npm      | `@ahrefs/mcp`                                      |
    | `context7`            | Context7            | npm      | `@upstash/context7-mcp`                            |
    | `dataforseo`          | DataForSEO          | npm      | `dataforseo-mcp-server`                            |
    | `e2b`                 | E2B                 | npm      | `@e2b/mcp-server`                                  |
    | `langchain`           | Langchain           | npm      | `langchain-mcp`                                    |
    | `sequential-thinking` | Sequential Thinking | npm      | `@modelcontextprotocol/server-sequential-thinking` |
    | `supadata`            | Supadata            | npm      | `@supadata/mcp`                                    |
  </Tab>

  <Tab title="Search & web (7)">
    Scrapers, search APIs, crawlers.

    | Id           | Title                       | Registry | Identifier                 |
    | ------------ | --------------------------- | -------- | -------------------------- |
    | `apify`      | Apify                       | npm      | `@apify/actors-mcp-server` |
    | `exa`        | Exa                         | npm      | `exa-mcp-server`           |
    | `firecrawl`  | Firecrawl (scrape + crawl)  | npm      | `firecrawl-mcp`            |
    | `perplexity` | Perplexity (search + sonar) | npm      | `perplexity-mcp`           |
    | `searchapi`  | Searchapi                   | npm      | `searchapi-mcp`            |
    | `serper`     | Serper                      | npm      | `mcp-server-serper`        |
    | `tavily`     | Tavily                      | npm      | `tavily-mcp`               |
  </Tab>

  <Tab title="Databases (7)">
    Relational, document, key-value, graph stores.

    | Id         | Title    | Registry | Identifier                |
    | ---------- | -------- | -------- | ------------------------- |
    | `mongodb`  | MongoDB  | npm      | `mongodb-mcp-server`      |
    | `mysql`    | MySQL    | npm      | `mcp-server-mysql`        |
    | `neo4j`    | Neo4j    | npm      | `@johnymontana/neo4j-mcp` |
    | `redis`    | Redis    | npm      | `redis-mcp`               |
    | `supabase` | Supabase | npm      | `supabase-mcp`            |
    | `turso`    | Turso    | npm      | `mcp-server-turso`        |
    | `upstash`  | Upstash  | npm      | `@upstash/mcp-server`     |
  </Tab>

  <Tab title="Analytics & monitoring (7)">
    Dashboards, metrics, product analytics.

    | Id           | Title                       | Registry | Identifier                            |
    | ------------ | --------------------------- | -------- | ------------------------------------- |
    | `axiom`      | Axiom                       | npm      | `mcp-server-axiom`                    |
    | `datadog`    | Datadog                     | npm      | `@winor30/mcp-server-datadog`         |
    | `dynatrace`  | Dynatrace                   | npm      | `@dynatrace-oss/dynatrace-mcp-server` |
    | `grafana`    | Grafana (Go binary via OCI) | oci      | `ghcr.io/grafana/mcp-grafana`         |
    | `mixpanel`   | Mixpanel                    | npm      | `mixpanel-mcp-server`                 |
    | `plausible`  | Plausible                   | npm      | `plausible-mcp`                       |
    | `prometheus` | Prometheus                  | npm      | `prometheus-mcp`                      |
  </Tab>

  <Tab title="CMS & content (6)">
    Headless content platforms, blogs, marketing ops.

    | Id           | Title      | Registry | Identifier               |
    | ------------ | ---------- | -------- | ------------------------ |
    | `contentful` | Contentful | npm      | `@contentful/mcp-server` |
    | `ghost`      | Ghost      | npm      | `ghost-mcp`              |
    | `hubspot`    | HubSpot    | npm      | `@hubspot/mcp-server`    |
    | `sanity`     | Sanity     | npm      | `@sanity/mcp-server`     |
    | `strapi`     | Strapi     | npm      | `strapi-mcp`             |
    | `wordpress`  | Wordpress  | npm      | `wordpress-mcp`          |
  </Tab>

  <Tab title="Communication (6)">
    Chat, customer messaging, transactional email, SMS.

    | Id         | Title                   | Registry | Identifier     |
    | ---------- | ----------------------- | -------- | -------------- |
    | `discord`  | Discord                 | npm      | `discord-mcp`  |
    | `intercom` | Intercom (remote OAuth) | remote   | `(HTTP)`       |
    | `resend`   | Resend                  | npm      | `resend-mcp`   |
    | `sendgrid` | SendGrid                | npm      | `sendgrid-mcp` |
    | `telegram` | Telegram                | npm      | `telegram-mcp` |
    | `twilio`   | Twilio                  | npm      | `twilio-mcp`   |
  </Tab>

  <Tab title="E-commerce & finance (6)">
    Payment processors, marketplaces, market data.

    | Id           | Title      | Registry | Identifier        |
    | ------------ | ---------- | -------- | ----------------- |
    | `alpaca`     | Alpaca     | npm      | `alpaca-mcp`      |
    | `paypal`     | PayPal     | npm      | `@paypal/mcp`     |
    | `polygon`    | Polygon    | npm      | `polygon-mcp`     |
    | `salesforce` | Salesforce | npm      | `@salesforce/mcp` |
    | `shopify`    | Shopify    | npm      | `shopify-mcp`     |
    | `stripe`     | Stripe     | npm      | `@stripe/mcp`     |
  </Tab>

  <Tab title="Infrastructure & DevOps (6)">
    Containers, clusters, IaC, PaaS.

    | Id           | Title                    | Registry | Identifier              |
    | ------------ | ------------------------ | -------- | ----------------------- |
    | `docker`     | Docker (daemon control)  | npm      | `docker-mcp`            |
    | `heroku`     | Heroku                   | npm      | `@heroku/mcp-server`    |
    | `kubernetes` | Kubernetes (cluster API) | npm      | `mcp-server-kubernetes` |
    | `pulumi`     | Pulumi                   | npm      | `@pulumi/mcp-server`    |
    | `railway`    | Railway                  | npm      | `@railway/mcp-server`   |
    | `terraform`  | Terraform                | npm      | `terraform-mcp-server`  |
  </Tab>

  <Tab title="Social media (5)">
    Public posting + metadata lookup.

    | Id         | Title    | Registry | Identifier     |
    | ---------- | -------- | -------- | -------------- |
    | `linkedin` | LinkedIn | npm      | `linkedin-mcp` |
    | `reddit`   | Reddit   | npm      | `reddit-mcp`   |
    | `tiktok`   | TikTok   | npm      | `tiktok-mcp`   |
    | `twitter`  | Twitter  | npm      | `twitter-mcp`  |
    | `youtube`  | YouTube  | npm      | `youtube-mcp`  |
  </Tab>

  <Tab title="Lifestyle (5)">
    Weather, recipes, news, music, general knowledge.

    | Id            | Title       | Registry | Identifier        |
    | ------------- | ----------- | -------- | ----------------- |
    | `news-api`    | NewsAPI     | npm      | `newsapi-mcp`     |
    | `openweather` | OpenWeather | npm      | `openweather-mcp` |
    | `recipe`      | Recipe      | npm      | `recipe-mcp`      |
    | `spotify`     | Spotify     | npm      | `spotify-mcp`     |
    | `wolfram`     | Wolfram     | npm      | `wolfram-mcp`     |
  </Tab>

  <Tab title="AI image generation (3)">
    Text-to-image, model inference for images.

    | Id          | Title     | Registry | Identifier      |
    | ----------- | --------- | -------- | --------------- |
    | `comfyui`   | ComfyUI   | npm      | `comfyui-mcp`   |
    | `fal`       | Fal       | npm      | `fal-mcp`       |
    | `replicate` | Replicate | npm      | `replicate-mcp` |
  </Tab>

  <Tab title="Vector DB (3)">
    Embeddings stores + ANN search.

    | Id            | Title                   | Registry | Identifier                     |
    | ------------- | ----------------------- | -------- | ------------------------------ |
    | `pinecone`    | Pinecone                | npm      | `@pinecone-database/mcp`       |
    | `qdrant`      | Qdrant (Python via uvx) | pypi     | `mcp-server-qdrant`            |
    | `turbopuffer` | Turbopuffer             | npm      | `@turbopuffer/turbopuffer-mcp` |
  </Tab>

  <Tab title="Marketing (3)">
    Ad platforms + email marketing.

    | Id           | Title      | Registry | Identifier       |
    | ------------ | ---------- | -------- | ---------------- |
    | `google-ads` | Google Ads | npm      | `google-ads-mcp` |
    | `mailchimp`  | Mailchimp  | npm      | `mailchimp-mcp`  |
    | `meta-ads`   | Meta Ads   | npm      | `meta-ads-mcp`   |
  </Tab>

  <Tab title="Maps (1)">
    Geospatial + routing.

    | Id       | Title  | Registry | Identifier           |
    | -------- | ------ | -------- | -------------------- |
    | `mapbox` | Mapbox | npm      | `@mapbox/mcp-server` |
  </Tab>
</Tabs>

## Distribution mix

Of the 105 entries:

* **102** ship as `npm` packages (stdio via `npx`).
* **1** ships as `pypi` (`qdrant`, runs via `uvx`).
* **1** ships as `oci` (`grafana`, Go binary in a container image).
* **1** is a pure `remote` endpoint (`intercom`, OAuth streamable-http).

The catalog's `registry_type` field is validated at build time: `runner`
is required for pypi packages and forbidden for every other registry
type.

## Authentication

Every server that needs credentials declares at least one
`[[servers.env_vars]]` entry with `is_secret = true` or `false`. The
env var names are visible in [`mcp-servers.toml`](https://github.com/supernovae-st/nika/blob/main/crates/nika-catalog/data/mcp-servers.toml).
Search for `^name = ` under your chosen server.

<Warning>
  Nika never stores API tokens in workflow YAML. Secrets are read from
  environment variables at run time. Use `nika doctor` to see which provider
  variables are present or missing; it reports presence only and never prints
  values.
</Warning>

## See also

<CardGroup>
  <Card title="Verbs" icon="code" href="/concepts/verbs">
    How `invoke:` routes to MCP tools + built-ins at runtime.
  </Card>

  <Card title="Builtins" icon="toolbox" href="/reference/builtins">
    The engine-native tools under `nika:*`.
  </Card>

  <Card title="Providers catalog" icon="server" href="/reference/providers-catalog">
    LLM providers for the `infer:` and `agent:` verbs.
  </Card>

  <Card title="Error codes" icon="triangle-exclamation" href="/reference/error-codes">
    MCP errors: the spec's `NIKA-MCP` namespace (`NIKA-MCP-001` server unreachable · `NIKA-MCP-002` call failed); the engine's internal diagnostics registry stays engine-side.
  </Card>
</CardGroup>


# Nika as an MCP server
Source: https://docs.nika.sh/reference/mcp-server

The read-only oracle: 9 validate-and-learn tools over stdio. Agents inspect freely; execution stays on the CLI, where the budget flags and traces live.

`nika mcp` serves the **read-only oracle** over stdio — the in-binary MCP
server every wired client talks to. Its contract is one sentence:

> **Agents can inspect freely, execute deliberately.** The oracle validates
> and teaches; running a workflow stays on the CLI, where `--max-cost-usd`,
> the permits boundary and the trace file live.

The released binary serves stdio; a **Streamable HTTP** transport
(`nika mcp --transport http` — POST JSON-RPC, origin-gated against
DNS-rebinding, loopback bind by default on port 8123) has landed on `main`
and ships with the next release, for managed hosts that cannot spawn a
process. Widening `--bind` beyond loopback is on you: put TLS + auth in
front first. Either transport, there is no write tool and no way to make
the oracle execute anything. That is the design, not a gap: generation and
repair belong to [the authoring skill](/getting-started/agents), execution
belongs to a human-gated `nika run`.

## Start it

No binary yet? `brew install supernovae-st/tap/nika` — other paths (script,
Docker) in [installation](/getting-started/installation). Then every client
uses the same two fields:

```json theme={"system"}
{ "command": "nika", "args": ["mcp"] }
```

`nika wire <client>` writes this stanza into the right config file for
cursor · vscode · windsurf · claude · codex · opencode · hermes (and
`all`). For any other MCP-capable client, paste the stanza into its
server config — see [per-client wiring](/integrations/mcp-clients).

## The 9 tools

Projected from the live wire (`tools/list`), never hand-counted:

| tool            | what it answers                                                                                                                                       |
| --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| `nika_check`    | Statically audit a workflow (schema · DAG · CEL · effects · permits · cost) **before** running it — findings, or a clean bill.                        |
| `nika_explain`  | Teach one `NIKA-XXXX` error code: cause, category, and the fix form.                                                                                  |
| `nika_schema`   | The embedded JSON Schema for `*.nika.yaml` — the structural contract an agent authors against.                                                        |
| `nika_examples` | Browse the embedded runnable examples; with a `slug`, that example's full source.                                                                     |
| `nika_template` | The canonical workflow skeletons (chain · gate-and-act · fanout · …); with a `name`, that skeleton's source — copy it, never invent structure.        |
| `nika_canon`    | The spec canon SSOT (`canon.yaml`) — the locked counts and names. Cite it, never a remembered number.                                                 |
| `nika_catalog`  | The embedded provider/model catalog — models, capabilities, context windows, API-key env vars.                                                        |
| `nika_tools`    | The embedded builtin-tool catalog — every `nika:*` tool with its model-facing JSON Schema.                                                            |
| `nika_inspect`  | The typed graph of a checked workflow (`graph_format: 2`) — nodes, edges with their kinds, byte-parity with `nika inspect --format json` and the LSP. |

The split is deliberate: **validate** (`nika_check` · `nika_explain`) and
**learn** (`nika_schema` · `nika_examples` · `nika_template` · `nika_canon` ·
`nika_catalog` · `nika_tools` · `nika_inspect`).

## Why read-only is the whole point

A `.nika.yaml` can declare `exec:` shell steps — that is the language working
as designed. An MCP tool that *ran* workflows would hand every wired agent a
shell with your credentials, one prompt-injection away. So the oracle refuses
the category:

* **No `nika_run`, no `nika_generate`, no write tools — ever.** Authoring is
  the skill's job (the agent writes the file, you review it); running is the
  CLI's job (`nika run`, with budget flags, under your eyes).
* **Secrets never transit the oracle.** The catalog names the env var a
  provider needs; it never reads or returns values.
* What the trace's hash chain proves — and what it does not — is stated
  plainly in [machine surfaces](/reference/machine-surfaces): tamper-evidence
  for the recorded run, not a signature. Signed attestations are a separate,
  future layer.

## Context budget

The oracle is lean by design — a handful of read-only tools with compact
outputs, sized so wiring it costs an agent almost nothing. Clients that
support per-server tool filtering can narrow further (e.g. expose only
`nika_check` + `nika_template` to a coding agent).

## Verify a wiring

Ask the connected agent to list its tools — the nine names above should
appear. From a shell, the JSON-RPC handshake works too:

```sh theme={"system"}
printf '%s\n' \
  '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"probe","version":"1"}}}' \
  '{"jsonrpc":"2.0","method":"notifications/initialized"}' \
  '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}' \
  | nika mcp
```

And the last inch — a real `nika_check` call. `workflow` takes the file's
**source text** (the oracle has no filesystem access by design), so shell in
the file's contents:

```sh theme={"system"}
printf '%s\n' \
  '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"probe","version":"1"}}}' \
  '{"jsonrpc":"2.0","method":"notifications/initialized"}' \
  "{\"jsonrpc\":\"2.0\",\"id\":2,\"method\":\"tools/call\",\"params\":{\"name\":\"nika_check\",\"arguments\":{\"workflow\":$(python3 -c 'import json,sys;print(json.dumps(open(sys.argv[1]).read()))' flow.nika.yaml)}}}" \
  | nika mcp
```

A clean workflow answers with the audit verdict in `content[0].text` —
same output as `nika check`, over the wire.


# Providers catalog
Source: https://docs.nika.sh/reference/providers-catalog

Every LLM provider Nika knows about: the canonical stdlib catalog — local-first — plus API dialects and environment variables.

Nika's stdlib v0.1 ships&#x20;**&#x20;canonical providers**:
&#x20;local / self-hosted runners,&#x20;
cloud APIs, and  deterministic mock. You select one with
a single `model: <provider>/<name>` field. **Local first** · nothing leaves
your machine unless a cloud provider is explicitly selected.

<Info>
  **Canonical source:** [`stdlib/providers-v0.1.md`](https://github.com/supernovae-st/nika-spec/blob/main/stdlib/providers-v0.1.md)
  in the spec (counts from `canon.yaml`). The engine additionally carries an
  extended catalog of  TOML records
  ([`crates/nika-catalog/data/llm-providers.toml`](https://github.com/supernovae-st/nika/blob/main/crates/nika-catalog/data/llm-providers.toml))
  used for capability metadata. Anything outside the canonical catalog routes
  through the `openai` + `base_url` escape hatch, not its own prefix.
</Info>

## Overview

<CardGroup>
  <Card title="Providers" icon="server">
    &#x20;canonical:  local ·  cloud ·  mock
  </Card>

  <Card title="API dialects" icon="plug">
    **3**: openai-chat (the 5 local + most cloud) · anthropic · gemini
  </Card>

  <Card title="Capability rules" icon="grid">
    &#x20;in `model-capabilities.toml`
  </Card>
</CardGroup>

## How to pick a provider

<Steps>
  <Step title="Pick your trust model">
    Local / self-hosted (Ollama / LM Studio / llama.cpp / LocalAI / vLLM): zero key, zero egress, sovereign by default. EU cloud (Mistral). US frontier (Anthropic / OpenAI / Google). Aggregator (OpenRouter). Each has different residency and compliance trade-offs.
  </Step>

  <Step title="Check the `api_dialect`">
    All 5 local providers + most cloud providers speak `openai-chat`: same request shape, differing base URL. `anthropic` and `gemini` have native dialects.
  </Step>

  <Step title="Verify the backend is reachable">
    Local providers need their server running (e.g. the Ollama daemon on `localhost:11434`) and no key. Cloud providers declare an `env_var` (e.g., `MISTRAL_API_KEY`). `nika doctor` checks provider readiness before run.
  </Step>

  <Step title="Pick default vs cheap model">
    Every provider declares both. `default_model` is the capable tier; `cheap_model` is the cost-optimized tier. Capability rules in `model-capabilities.toml` determine which models support vision / tools / streaming / structured output.
  </Step>
</Steps>

## By category

Local/open-weight first (sovereignty default), then cloud starting with
Mistral (EU) — anthropic/openai are never presented first, per the
catalog's own presentation-order note in `canon.yaml`.

<Tabs>
  <Tab title="Local / self-hosted (5)">
    | ID         | Name                                           | Dialect       | Env var  | Example model                 |
    | ---------- | ---------------------------------------------- | ------------- | -------- | ----------------------------- |
    | `ollama`   | Ollama daemon (`localhost:11434`)              | `openai-chat` | `(none)` | `llama3.1`                    |
    | `llamacpp` | llama.cpp `llama-server` (`localhost:8080/v1`) | `openai-chat` | `(none)` | `qwen2.5-7b-instruct`         |
    | `vllm`     | vLLM OpenAI server (`localhost:8000/v1`)       | `openai-chat` | `(none)` | `meta-llama-3.1-70b-instruct` |
    | `lmstudio` | LM Studio (`localhost:1234/v1`)                | `openai-chat` | `(none)` | `qwen2.5-14b-instruct`        |
    | `localai`  | LocalAI (`localhost:8080/v1`)                  | `openai-chat` | `(none)` | `llama-3.1-8b-instruct`       |

    <Tip>
      **The sovereign default.** No API key, no cloud egress:
      `model: ollama/llama3.2:3b` runs offline / air-gapped. Any other
      OpenAI-compatible local server (Jan · llamafile · KoboldCpp) routes
      through the `openai` + `base_url` escape hatch.
    </Tip>
  </Tab>

  <Tab title="Cloud (11)">
    | ID            | Name                                                              | Dialect       | Env var              | Default model                       |
    | ------------- | ----------------------------------------------------------------- | ------------- | -------------------- | ----------------------------------- |
    | `mistral`     | Mistral AI (EU · sovereign-leaning)                               | `openai-chat` | `MISTRAL_API_KEY`    | `mistral-large-latest`              |
    | `huggingface` | Hugging Face Inference Providers (100+ open-weight · 18 backends) | `openai-chat` | `HF_TOKEN`           | `Qwen/Qwen3.5-9B:cheapest`          |
    | `openai`      | OpenAI                                                            | `openai-chat` | `OPENAI_API_KEY`     | `gpt-4o`                            |
    | `xai`         | xAI Grok                                                          | `openai-chat` | `XAI_API_KEY`        | `grok-3`                            |
    | `anthropic`   | Anthropic Claude                                                  | `anthropic`   | `ANTHROPIC_API_KEY`  | `claude-sonnet-4-6`                 |
    | `gemini`      | Google Gemini                                                     | `gemini`      | `GEMINI_API_KEY`     | `gemini-2.5-flash`                  |
    | `deepseek`    | DeepSeek                                                          | `openai-chat` | `DEEPSEEK_API_KEY`   | `deepseek-chat`                     |
    | `groq`        | Groq (fastest open-weight)                                        | `openai-chat` | `GROQ_API_KEY`       | `llama-3.3-70b-versatile`           |
    | `openrouter`  | OpenRouter gateway                                                | `openai-chat` | `OPENROUTER_API_KEY` | `anthropic/claude-sonnet-4-6`       |
    | `nvidia`      | NVIDIA API (Nemotron 3 · NIM self-hostable)                       | `openai-chat` | `NVIDIA_API_KEY`     | `nvidia/nemotron-3-super-120b-a12b` |
    | `moonshot`    | Moonshot AI (Kimi K3 · frontier open-weight)                      | `openai-chat` | `MOONSHOT_API_KEY`   | `kimi-k3`                           |

    <Tip>
      Keys live in `${{ secrets.* }}` / env vars, never inline in the
      workflow. OpenRouter aggregates \~200 models under one key
      (`openrouter/<vendor>/<model>`); Hugging Face routes 100+ open models
      across 18 backends under one `HF_TOKEN`. Use either to experiment
      across vendors without per-vendor keys.
    </Tip>
  </Tab>

  <Tab title="Test (1)">
    | ID     | Name          | Dialect | Env var  | Default model          |
    | ------ | ------------- | ------- | -------- | ---------------------- |
    | `mock` | Mock provider | custom  | `(none)` | `echo` (deterministic) |

    <Note>
      **Mock** ships with every install for deterministic tests:
      `model: mock/echo` returns the prompt verbatim, zero network, zero
      entropy. The canonical examples + CI rely on it.
    </Note>
  </Tab>
</Tabs>

## Full alphabetical list

<AccordionGroup>
  <Accordion title={`The ${CANON.providers} canonical spec v0.1 IDs (sorted)`} icon="list">
    `anthropic` · `deepseek` · `gemini` · `groq` · `huggingface` ·
    `llamacpp` · `lmstudio` · `localai` · `mistral` · `mock` · `moonshot` ·
    `nvidia` · `ollama` · `openai` · `openrouter` · `vllm` · `xai`

    &#x20;total:  local ·  cloud ·
    &#x20;test · matches `canon.yaml` in the spec repo. The
    engine's extended capability catalog ( TOML records)
    is an implementation detail: extended IDs are reached via the
    `openai` + `base_url` escape hatch, never their own prefix.
  </Accordion>
</AccordionGroup>

## Example: invoke a provider

<CodeGroup>
  ```yaml workflow.nika.yaml theme={"system"}
  nika: v1
  workflow:
    id: multi-provider

  tasks:
    primary:
      on_error: { skip: true }   # a dead provider skips (error preserved) · the gate below reads it
      infer:
        model: ollama/llama3.2:3b              # local · zero key
        prompt: "Explain linear algebra in one sentence."

    fallback:
      with:
        problem: ${{ tasks.primary.error }}   # failure-observation edge · a skip carries its preserved error
      when: "${{ with.problem != null }}"     # local read of the binding
      infer:
        model: mistral/mistral-large
        prompt: "Explain linear algebra in one sentence."
  ```

  ```bash Required env theme={"system"}
  ollama pull llama3.2:3b         # local primary · no key
  export MISTRAL_API_KEY=...      # cloud fallback only
  nika run workflow.nika.yaml
  ```
</CodeGroup>

<Info>
  `infer:` is live in v. Run `nika doctor` first to see
  which provider keys or local servers are available without printing secrets.
</Info>

## See also

<CardGroup>
  <Card title="Capability rules" icon="grid" href="/reference/capabilities">
    The  rules that govern which models support which features.
  </Card>

  <Card title="Concepts · Providers" icon="server" href="/concepts/providers">
    How provider routing works at runtime.
  </Card>

  <Card title="Error codes" icon="triangle-exclamation" href="/reference/error-codes">
    `NIKA-1xx` provider errors.
  </Card>

  <Card title="Schema" icon="file-code" href="/reference/schema">
    Workflow envelope, `.nika.yaml` top-level keys.
  </Card>
</CardGroup>


# JSON Schema
Source: https://docs.nika.sh/reference/schema

The machine-authoritative schema for .nika.yaml.

The canonical schema lives at:

**[https://nika.sh/schema/workflow.json](https://nika.sh/schema/workflow.json)**

It's a standard [JSON Schema draft 2020-12](https://json-schema.org/)
document. Your editor's YAML LSP can consume it directly.

## Contract version

`nika: v1`, the first line of every workflow. A **single version marker**:
the key `nika` declares "this is a Nika workflow", the value `v1` pins the
language contract version. There is no separate `schema:` or `apiVersion:`
field (the engine's internal canonical URI stays `https://nika.sh/spec/v1`
for RDF / conformance tooling, but the author never types a URL).

## Point your editor

Add the LSP modeline at the top of any `.nika.yaml` so your editor's YAML
language server consumes the JSON Schema directly:

```yaml the modeline · paste at the top of any workflow theme={"system"}
# yaml-language-server: $schema=https://nika.sh/schema/workflow.json
nika: v1
workflow:
  id: my-workflow-id
```

See [editor setup](/getting-started/editors) for per-IDE instructions.

## Local validation

```bash theme={"system"}
nika check workflow.nika.yaml   # validates against the v1 contract
nika check workflow.nika.yaml --strict   # + extra lints
```

## Versioning policy

* `v1` is the **only value for the entire lifetime** of the v1 contract.
* Minor additions (a new optional field, a new builtin) are **additive**
  and never change the marker: no `@minor` bumps, no `nika migrate` for them.
* **There is no `nika: v2` — ever**: pre-1.0 grammar changes happen inside
  `v1` (the pre-1.0 stability contract) · after engine 1.0.0 the grammar is
  additive only.
* Anti-pattern: `nika: v1.0` · `nika: "1"` · `nika: 1.0`. The value is exactly `v1`.


# Live state
Source: https://docs.nika.sh/reference/status

Live state of the Nika Diamond rewrite, snapshotted by hand from the engine's `scripts/refresh-status.sh` block. Read the provenance note before quoting it.

<Info>
  Every number here imports `STATUS` from [`/snippets/_status-snapshot.mdx`](https://github.com/supernovae-st/nika-docs/blob/main/snippets/_status-snapshot.mdx).
  **Mixed provenance, and worth knowing which is which:** `version` and
  `lastUpdated` are auto-derived from the published release by
  `scripts/mintlify-snapshot.sh`; the counts are a **hand-maintained periodic
  snapshot** of the engine's canonical
  [`scripts/refresh-status.sh`](https://github.com/supernovae-st/nika/blob/main/scripts/refresh-status.sh)
  block. The engine's hygiene vector 23 guards that block *inside the engine
  repo* — it cannot see this one. So a fresh `lastUpdated` is not evidence
  that the counts are fresh.

  **Counts as of engine `main`&#x20;**&#x20;· branch `{STATUS.branch}` ·
  **snapshot refreshed** .
</Info>

## At a glance

<CardGroup>
  <Card title="Admitted" icon="cube">
    &#x20;crates past 12 gates
  </Card>

  <Card title="Library tests" icon="flask">
    &#x20;passing ·  clippy warnings
  </Card>

  <Card title="Hygiene" icon="shield-check">
    &#x20;vectors gate every push
  </Card>

  <Card title="ADRs" icon="scroll">
    &#x20;total ·  Accepted ·  Proposed
  </Card>

  <Card title="Providers" icon="server">
    &#x20;LLM providers in the catalog
  </Card>

  <Card title="Capability rules" icon="grid">
    &#x20;rules in `model-capabilities.toml`
  </Card>
</CardGroup>

## Canonical block

The engine's `refresh-status.sh` emits this block inside the engine repo
(`ROADMAP.md`, `.claude/CLAUDE.md`). The rows below are a hand-copy of it,
taken at `{STATUS.head}`.

| field                       | value                    |
| --------------------------- | ------------------------ |
| branch                      | `{STATUS.branch}`        |
| HEAD                        | `{STATUS.head}`          |
| workspace version           | v                        |
| crates (workspace)          |                          |
| crates (admitted)           |                          |
| crates (WIP)                |  ·                       |
| crates (projected horizon)  |  · hard cap  (ADR-037)   |
| library tests               |  passed, 0 failed        |
| clippy                      |  warnings                |
| ADRs                        |  ( Accepted +  Proposed) |
| hygiene vectors             |                          |
| providers (catalog records) |                          |
| capability rules            |                          |

A per-vector green/yellow/red breakdown is deliberately absent: it is a live
CI result, not a docs constant. Run `bash scripts/hygiene/check-all.sh --format=json` in the engine repo for it.

## How to refresh

<CodeGroup>
  ```bash Engine repo · the counts theme={"system"}
  git clone https://github.com/supernovae-st/nika.git
  cd nika
  bash scripts/refresh-status.sh              # full refresh (runs cargo test + clippy)
  bash scripts/refresh-status.sh --quick      # structural fields only, skips cargo
  # then hand-copy the regenerated block into this repo's snippets/_status-snapshot.mdx
  ```

  ```bash Docs repo · the release fields theme={"system"}
  bash scripts/mintlify-snapshot.sh           # version + lastUpdated ONLY
  ```
</CodeGroup>

## Drift protection, stated honestly

<Warning>
  Engine hygiene vector 23 (`check-status-claims-sync.sh`) parity-checks the
  block against `ROADMAP.md` and `.claude/CLAUDE.md` **within the engine
  repo**. It has no visibility into this repo, so nothing fails CI when the
  counts here go stale. `scripts/mintlify-snapshot.sh` only rewrites
  `version` and `lastUpdated` — it will happily bump the date on a page whose
  counts are months old. Treat a recent `lastUpdated` as evidence about the
  release, never about the crate, test, or ADR numbers.
</Warning>

## What's admitted today

&#x20;Diamond crates are admitted, with WIP
. The
admitted set spans the foundation crates, kernel traits, local/effect crates,
providers, all four verbs, runtime, LSP, MCP, and CLI surfaces needed for the
first public release candidate.

## What's locked (decisions the project won't revisit)

* **Crate count is a projection, never a gate**: ADR-037 revised the old 40-42 target to a  horizon (hard cap ); crates are admitted when they pass the 12 gates, reached additively across 1.x minors.
* **Real semver toward 1.0**: 0.90.0 is the first public release-candidate; 1.0 ships when release gates are green. Quality over speed.
* **Layer discipline**: L0 zero I/O, L0.5 traits only, strict downward deps, cargo-deny enforced. See [Layers](/architecture/layers).
* **12 gates per crate**: no exceptions. See [Admission](/architecture/admission).
* **Zero `.unwrap()` / `.expect(` in `src/`**: `?` propagation; `workspace.lints.clippy.unwrap_used = "deny"`.
* **Not an extraction**: every crate written fresh, legacy as reference only.
* **TDD with mutation ≥ 90%**: RED before GREEN; `cargo mutants -p <crate>` gates admission.
* **`#[non_exhaustive]` on every public type**: see [Forward-compat invariants](/architecture/forward-compat-invariants).

## What's next

<AccordionGroup>
  <Accordion title="L0-completion crates">
    The remaining Diamond target crates are additive hardening work, not
    prerequisites for the shipped 0.90 release-candidate surface. See the
    roadmap for the exact current sequence.
  </Accordion>

  <Accordion title="1.0 release hardening">
    The user-facing front door is already installable. The 1.0 work is about
    proving the release checklist, docs, editor setup, and shadow-zone gates
    stay true end-to-end.
  </Accordion>

  <Accordion title="The Connectome (sovereign memory): post-foundation">
    **Separate count** from the  Diamond crate horizon.
    11 crates: 1 L2 orchestrator (`nika-connectome`) + 10 L1 satellites (hnsw,
    bm25, rrf, rerank, fsrs, rdfs-reasoner, temporal, graph-algos,
    autodesc-minimal, autodesc-full). Plugs into
    `MemoryStore` / `EmbeddingProvider` trait reservations in `nika-kernel`.
    No breaking changes. Design tracked via ADR-004 + ADRs 029-032.
  </Accordion>
</AccordionGroup>

## What's NOT in scope

Explicitly removed or deferred by POST\_AUDIT\_REVISIONS 2026-04-14:

| What                         | Why                                     | Status               |
| ---------------------------- | --------------------------------------- | -------------------- |
| `nika-sdk`                   | 0 consumers, speculative                | Deleted              |
| `nika-napi` / `nika-py`      | W1 speculative, rebuild Act 3 if needed | Deferred             |
| `nika-tui`                   | W1 speculative                          | Deferred to post-1.0 |
| `nika-macros`                | No proc macros in L0 (Q1 locked)        | Never a crate        |
| `nika-lsp-core`              | Merged into `nika-lsp`                  | Module, not crate    |
| `nika-policy` / `nika-cache` | Modules in `nika-runtime`               | Not crates           |
| `nika-storage`               | Module in `nika-daemon`                 | Not a crate          |

## See also

<CardGroup>
  <Card title="Constellation" icon="diagram-project" href="/reference/constellation">
    Visual map of admitted / WIP / planned crates by layer.
  </Card>

  <Card title="Admission" icon="check-double" href="/architecture/admission">
    The 12 gates every crate passes before joining.
  </Card>

  <Card title="Error codes" icon="triangle-exclamation" href="/reference/error-codes">
    NIKA-XXX code reference per crate range.
  </Card>

  <Card title="CHANGELOG" icon="clock-rotate-left" href="https://github.com/supernovae-st/nika/blob/main/CHANGELOG.md">
    Every crate admission with verified numbers.
  </Card>
</CardGroup>

## The Nika ecosystem

<Ecosystem />


# YAML syntax reference
Source: https://docs.nika.sh/reference/yaml-syntax

Full .nika.yaml schema. Every field, type, and validation rule.

<Warning>
  The machine-readable schema is at
  [https://nika.sh/schema/workflow.json](https://nika.sh/schema/workflow.json).
  Point your editor at it for live validation. See [editor setup](/getting-started/editors).
</Warning>

## Top level

```yaml the envelope · a skeleton, not a runnable file theme={"system"}
nika: v1                     # required · language + contract version (single marker)
workflow:                    # required · the identity object
  id: <identifier>           #   required · kebab-case · unique within file
  description: <string>      #   optional · human-readable

model: <provider>/<name>     # optional · default model for infer/agent tasks

# the four value authorities · one role each · no other value namespace exists
inputs: { ... }              # optional · TYPED · the caller supplies at launch · ${{ inputs.* }}
config: { ... }              # optional · TYPED · the deployment supplies · logged · ${{ config.* }}
const:  { ... }              # optional · fixed in the file · never caller-supplied · ${{ const.* }}
secrets: { ... }             # optional · vault/env/file references · masked · ${{ secrets.* }}

permits: { ... }             # optional KEY · but ABSENT = zero authority (see below)
policy: { ... }              # optional · the run's declared limits
types: { ... }               # optional · named PascalCase type declarations
run: { ... }                 # optional · the run's entropy + clock declaration

tasks: { ... }               # required · non-empty MAP · the key IS the task id

outputs: { ... }             # optional · the workflow's return value
assert: [ ... ]              # optional · the author's obligations, checked
```

## The four value authorities

Every value a workflow declares lands under exactly one of four authorities.
The family is closed — a value-namespace read outside it is `NIKA-VALUES-003`.

| Authority  | Who supplies it                                                               | Shape                                                                     | Integrity |
| ---------- | ----------------------------------------------------------------------------- | ------------------------------------------------------------------------- | --------- |
| `inputs:`  | the **caller**, at launch (`--var k=v` · an MCP `nika.run_workflow` argument) | `{ type, required?, default?, description? }` · `type:` required          | untrusted |
| `config:`  | the **deployment** · may appear in logs and traces                            | `{ type, default?, description? }` · `type:` required · never `required:` | untrusted |
| `const:`   | the **file** · immutable across the run, never caller-supplied                | a bare literal, or `{ type, value }`                                      | trusted   |
| `secrets:` | a **governed store** · masked everywhere                                      | `{ source: vault\|env\|file, key\|path, egress? }`                        | trusted   |

```yaml theme={"system"}
inputs:
  topic:    { type: string, required: true, description: "Subject to research" }
  bullets:  { type: integer, default: 3 }
config:
  log_level: { type: string, default: "info" }
const:
  output_dir: "./output"                 # the file owns the destination
secrets:
  api_key: { source: env, key: MISTRAL_API_KEY }
```

The integrity column is not decoration: under a `permits:` block an
**untrusted** value that reaches a verb argument is re-gated on its canonical
resolved form, and an escape is refused `NIKA-AUTH-008`. That is the practical
reason a destination the boundary pins belongs in `const:` — a caller cannot
move it out from under the permit.

`vars:` and `env:` are **dead envelope fields** (`NIKA-VALUES-001` /
`NIKA-VALUES-002`), and so are the `${{ vars.X }}` / `${{ env.X }}` reads.
There is no alias: each old use **classifies** into the authority its role
commands — a typed parameter is an `inputs:` declaration, a fixed value a
`const:` entry, non-sensitive runtime configuration a `config:` declaration, a
governed store reference a `secrets:` entry. `nika check --fix` migrates the
provable cases. (The `env:` **inside** an `exec:` block is a different field
and is alive: it is the child process's environment map.)

## `permits:` — the key is optional, the authority is not

An absent `permits:` block declares **zero** authority. Every effect the body
requires is refused at check with `NIKA-AUTH-006` — before a single token —
and any effect attempted at run time fails the task with `NIKA-SEC-004`. A
pure-compute workflow passes with an informational hint; `permits: {}` is the
authored spelling of "I touch nothing".

```bash theme={"system"}
nika check flow.nika.yaml --infer-permits   # prints the tightest block, ready to paste
```

Once the block is present every category is **default-deny unless listed** —
including `tools:`, which must name every builtin the file invokes, even the
pure-compute ones.

## The run declaration

```yaml theme={"system"}
run:
  entropy: ambient           # none | ambient | { seeded: <u64> }
  clock: system              # system | virtual
```

Every source of randomness and time is declared, never ambient. Absent, the
run behaves as `entropy: ambient` + `clock: system`. The two dimensions
couple: only `ambient × system` and `none | seeded × virtual` are legal —
byte-identical journals need deterministic time as much as deterministic
randomness. A declared contradiction refuses at parse (`NIKA-PARSE-026` ·
`NIKA-PARSE-027`); `entropy: none` with a live randomness source consumed
refuses at check (`NIKA-PARSE-028`).

## Types and policy

Two optional envelope keys that most workflows never need — and that the
checker enforces the moment they appear.

`types:` declares named PascalCase types once; `returns:` (and `outputs:`)
then reference them by name instead of restating the shape. `policy:`
declares the limits the run must obey, checked **before** any token is spent.

```yaml typed-triage.nika.yaml theme={"system"}
nika: v1
workflow:
  id: typed-triage

types:
  Finding:
    object:
      severity: { enum: ["low", "medium", "high"] }
      summary: string
      line: { integer: { min: 1 } }

permits:
  tools: ["nika:jq"]

policy:
  limits:
    max_tasks: 20

tasks:
  classify:
    invoke:
      tool: "nika:jq"
      args:
        input: { severity: "high", summary: "unbounded retry", line: 42 }
        expression: "."
    returns: Finding

outputs:
  severity: "${{ tasks.classify.output.severity }}"
```

The type grammar is closed: the primitives (`null` · `bool` · `integer` ·
`number` · `string` · `bytes` · `uri` · `path` · `duration` · `timestamp`), a
PascalCase reference to one of your own, or a constructor — `object:` ·
`array:` · `map:` · `union:` · `enum:` · plus the refinements `integer:`/
`number:` (`min`/`max`) and `string:` (`pattern`/`min_len`/`max_len`). An
unknown name is `NIKA-TYPE-001`; a recursive `types:` graph is
`NIKA-TYPE-002`.

The policy rule set is closed per minor. Rather than trust a list here, ask
the binary — a refused `policy:` block prints the whole current set:

```bash theme={"system"}
nika explain NIKA-POLICY-001
```

Today that set is six families — `require` · `forbid` · `allow` · `limits` ·
`prefer` · `optimize` — carrying `require.human_gate_before` ·
`forbid.exec_after` (both over `exec`/`write`/`net`/`tools`) ·
`allow.providers` · `limits.max_tasks` · `prefer.providers` · `optimize`
(`cost`/`latency`/`quality`). A violated hard rule is `NIKA-POLICY-001` at
check time, naming rule, task and witness.

## A task

```yaml theme={"system"}
<identifier>:                # the map KEY is the identity (snake_case · unique)

  with: { ... }              # optional · the DATA boundary · each tasks.* ref = one typed edge
  after: { <id>: <pred> }    # optional · the CONTROL boundary · pred ∈ success|failure|skipped|terminal
  when: <expression>         # optional · LOCAL business condition · evaluated POST-gate
  for_each: <expression>     # optional fan-out (an array · local read)
  max_parallel: <int>        # optional · cap concurrent iterations
  fail_fast: <bool>          # optional · default true · false = collect errors
  timeout: "<duration>"      # optional · quoted Go-duration · per-iteration on for_each
  retry: { ... }             # optional retry policy (max_attempts · backoff · on_codes)
  on_error: { ... }          # optional recovery · recover/skip/fail_workflow + on_codes
  output: { <name>: <jq> }   # optional named jq bindings over the raw output
  on_finally: [ ... ]        # optional cleanup steps · run if the task STARTED
  returns: <type>            # optional · the task's output contract (a type expression)
  declassify: [ ... ]        # optional · raise ONE binding untrusted → trusted
  inert: "<because>"         # optional · this fetch is a code-bearing artifact, never loaded

  # exactly one verb block:
  infer: { ... }
  exec: { ... }
  invoke: { ... }            # tool: <builtin|mcp> XOR workflow: <path|registry ref>
  agent: { ... }
```

The eighteen modifiers above are the complete task surface. `returns:`,
`declassify:` and `inert:` are the three that carry a contract of their own:

| Modifier      | What it declares                                                                                                                                                                                                                                                                                                                                               |
| ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `returns:`    | The task's output type, as a [type expression](#types-and-policy) — exclusive with a verb-level `schema:` (`NIKA-TYPE-003`). Under composition it is how the parent states the child's shape.                                                                                                                                                                  |
| `declassify:` | The **only** door through the permit-parameterization taint. Each entry raises exactly one binding: `from:` (a dotted path) · `to: trusted` · a non-empty `because:`. It lifts the taint law only — the value is still matched against the declared boundary, so it is never a permit bypass.                                                                  |
| `inert:`      | The **only** door through the data-as-code sink. A `nika:fetch` whose resolved URL names a code-bearing class (`.pkl` · `.py` · `.so` · the closed NEP-0006 list) is refused with `NIKA-SEC-008`; a non-empty `inert:` string declares the artifact will never be loaded or run. It lifts that law only — never the `net.http` boundary, never the SSRF floor. |

```yaml inert-fetch.nika.yaml theme={"system"}
nika: v1
workflow:
  id: inert-fetch

permits:
  net: { http: ["example.com"] }
  tools: ["nika:fetch"]

tasks:
  audit_weights:
    inert: "checksum audit only · the file is hashed, never deserialized"
    invoke:
      tool: "nika:fetch"
      args: { url: "https://example.com/model.pkl" }

outputs:
  status: "${{ tasks.audit_weights.output.status }}"
```

Drop the `inert:` line and that same file fails the check with
`NIKA-SEC-008`. Both doors are greppable by design: a reviewer can find every
place a law was waived, and each one carries its written justification into
the run receipt.

`tasks.*` crosses a task boundary through exactly **two doors** — `with:`
(data · observations) and `after:` (control) — and the engine computes the
graph FROM those doors. A `with:` binding that references `${{ tasks.X.* }}`
both names the data and declares a typed edge; an `after:` entry
(`{producer: predicate}`) orders on state and carries no data. `depends_on`
is dead (`NIKA-PARSE-024` · `nika check --fix` migrates it), and a `tasks.*`
reference outside the boundary — in a verb body, `when:`, or `for_each:` —
is `NIKA-VAR-021` with a machine-applicable fix (hoist into `with:`).

The `after:` predicate set is **closed**: `success` · `failure` · `skipped` ·
`terminal` (`terminal` admits any settled state, cancelled included). Anything
else is `NIKA-DAG-005`; the participial spellings `succeeded` and `failed` are
dead forms and refuse with their respelling, which `nika check --fix` applies.

The full per-field semantics live in the spec:
[03 · The flow](https://github.com/supernovae-st/nika-spec/blob/main/spec/03-dag.md).

## Timeouts

`timeout:` is a quoted **Go-duration string** (`"90s"`, `"7m"`, `"1h30m"`) and
bounds the **entire task**, wall-clock: retries and their backoff sleeps
included. Exceeding it fails the task with `NIKA-TIMEOUT-001` — catchable by
`on_error:`, never retryable (the timeout already covered the retries by
definition). On a `for_each` task the clock applies **per iteration**.

On an `infer:` / `agent:` task the declared `timeout:` also **governs the
provider HTTP deadline**: `timeout: "7m"` gives the provider round-trip those
seven minutes — no internal HTTP default undercuts the declared budget.

```yaml theme={"system"}
deep_review:
  timeout: "7m"                # the whole task AND the provider deadline
  infer:
    model: ollama/qwen3:8b     # a thinking model legitimately needs minutes
    prompt: "Review this diff…"
```

When **no** `timeout:` is declared, the provider deadline defaults per
provider **class**:

| Class | Providers                                                                                  | Default deadline |
| ----- | ------------------------------------------------------------------------------------------ | ---------------- |
| Local | `ollama` · `lmstudio` · `llamacpp` · `localai` · `vllm`                                    | **≥ 300s**       |
| Cloud | `mistral` · `anthropic` · `openai` · `openrouter` · `groq` · `deepseek` · `gemini` · `xai` | 30s              |

A local model routinely needs minutes for one completion on consumer
hardware — a 30s-everywhere default would silently kill every serious
local-first workflow before the model finishes thinking. The class is keyed
on the **canonical provider id**: a `base_url` override never flips it.

Two honest bounds ride the transport (pinned by the engine's wire tests):

* **600s ceiling on a fully-silent connection.** A non-streaming completion
  delivers zero bytes while the model computes, so the transport cannot tell
  *thinking* from *dead*. A longer `timeout:` still bounds the task, but only
  a connection that starts delivering can use it.
* **Streaming rides only an explicit budget.** A declared `timeout:` bounds a
  streaming request; when none is declared, the idle-read guard reaps a
  *stalled* stream instead of capping a healthy one.

Normative home: [stdlib · providers §Transport deadline](https://github.com/supernovae-st/nika-spec/blob/main/stdlib/providers-v0.1.md).

## Verbs

See individual pages:

* [`infer`](/concepts/verbs#infer): LLM call
* [`exec`](/concepts/verbs#exec): shell commands
* [`invoke`](/concepts/verbs#invoke): built-in or MCP tool (HTTP fetch is `invoke: nika:fetch`)
* [`agent`](/concepts/verbs#agent): tool-calling loop

## Full schema

The canonical JSON Schema is at
[https://nika.sh/schema/workflow.json](https://nika.sh/schema/workflow.json).
It's 100% machine-authoritative. This doc is a readable summary.

## Contract version policy

`nika: v1` is a **single version marker**: `v1` is the only value for the
entire lifetime of the v1 contract. Minor additions (a new optional field, a
new builtin) are **additive** and never change it (no `@minor` bumps, no
`nika migrate` for them). There is no `nika: v2` — ever:
pre-1.0 grammar changes happen inside `v1` (the pre-1.0 stability contract) ·
after engine 1.0.0 the grammar is additive only.