> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nika.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# TypeScript SDK

> Build around a Nika run with a live local driver and a clearly marked preview remote client.

export const Ecosystem = () => <CardGroup cols={3}>
    <Card title="nika.sh" icon="globe" href="https://nika.sh">
      The site: what Nika is, in one scroll.
    </Card>
    <Card title="Timeline" icon="timeline" href="https://nika.sh/timeline">
      The verifiable record: eras · releases · claims re-proven in CI.
    </Card>
    <Card title="Language spec" icon="file-contract" href="https://github.com/supernovae-st/nika-spec">
      the nine-key envelope, Apache-2.0. The contract these docs explain.
    </Card>
    <Card title="Engine source" icon="gem" href="https://github.com/supernovae-st/nika">
      Rust, AGPL-3.0-or-later. Every commit public.
    </Card>
    <Card title="TypeScript SDK" icon="code" href="/sdk/overview">
      Drive the released local CLI today. Explore the remote client as a clearly marked preview.
    </Card>
    <Card title="Editor extension" icon="puzzle-piece" href="https://marketplace.visualstudio.com/items?itemName=supernovae.nika-lang">
      VS Code · Cursor · Windsurf: check-as-you-type, DAG view, trace replay.
    </Card>
    <Card title="Homebrew tap" icon="beer-mug-empty" href="https://github.com/supernovae-st/homebrew-tap">
      `brew install supernovae-st/tap/nika` for the latest tagged CLI release.
    </Card>
    <Card title="SuperNovae" icon="star" href="https://supernovae.studio">
      The Paris studio crafting Nika. 🦋
    </Card>
  </CardGroup>;

export const ProjectContract = () => <>
    <Info>
      <strong>Live project control plane.</strong> The released engine
      discovers <code>nika.yaml</code> from the working directory toward its
      ancestors. The file is optional when built-in defaults are enough. Its
      project-shape grammar is closed: <code>nika</code> ·
      <code>ceiling</code> · <code>arm</code> · <code>traces</code> ·
      <code>registry</code>.
    </Info>
    <Warning>
      <strong>Current released reader limit.</strong> Direct workflow operations
      accept the <code>traces</code> and <code>registry</code> project-policy
      rungs. The cadence path behind <code>nika arm</code> and
      <code>nika serve</code> currently accepts only <code>nika</code>, optional
      <code>ceiling</code> and <code>arm</code>. Keep those profiles separate
      until the engine readers converge.
    </Warning>
  </>;

export const SdkDoors = () => <CardGroup cols={3}>
    <Card title="Start" icon="play" href="/sdk/start/quickstart">
      Install both halves and complete one typed run.
    </Card>
    <Card title="Project" icon="folder-tree" href="/sdk/project/nika-yaml">
      nika.yaml, arm policy, precedence and runtime state.
    </Card>
    <Card title="Local API" icon="terminal" href="/sdk/local/client">
      Check, plan, run, test and verify through the released binary.
    </Card>
    <Card title="Runtime" icon="wave-pulse" href="/sdk/runtime/events">
      Events, typed failures and durable receipts.
    </Card>
    <Card title="Remote API" icon="satellite-dish" href="/sdk/remote/client">
      Preview jobs, SSE, artifacts, workflows and webhooks.
    </Card>
    <Card title="Operations" icon="shield-halved" href="/sdk/operations/ci">
      Admission, resident serving, OS bridges and security.
    </Card>
    <Card title="Reference" icon="brackets-curly" href="/sdk/reference/methods">
      Constructors, methods and exported types.
    </Card>
  </CardGroup>;

export const RemoteContract = () => <Warning>
    <strong>Preview surface.</strong> The root package types the intended
    workflow HTTP and SSE API. The reference engine does not ship a compatible
    workflow service today. Do not point it at the stable resident firer or
    <code>nika model serve</code>.
  </Warning>;

export const LocalContract = () => <Tip>
    <strong>Live surface.</strong> <code>@supernovae-st/nika-client/local</code>
    drives the released <code>nika</code> binary through its versioned machine
    contracts. It is the production path today.
  </Tip>;

export const SDK = {
  package: "@supernovae-st/nika-client",
  localModule: "@supernovae-st/nika-client/local",
  source: "https://github.com/supernovae-st/nika-client",
  site: "https://nika.sh/sdk"
};

The SDK is the application seam around a Nika workflow. Your product owns
the request, interface and business state. Nika owns the workflow contract,
the execution boundary and the receipt.

<div className="sdk-flight">
  <span>APPLICATION FLIGHT COMPUTER · TYPESCRIPT</span>

  <pre tabIndex={0}>
    {`nika.yaml ── ceiling + arm profile ───────── serve / OS       [ LIVE ]
             │
             ├── run-policy profile ─────────────── direct runs      [ LIVE ]
             └── workflows/*.nika.yaml
                         ├── LocalNika ── argv + NDJSON ── nika     [ LIVE ]
                         │                                └── trace receipt
                         └── Nika ─────── HTTP + SSE ── workflow API [ PREVIEW ]`}
  </pre>
</div>

<ProjectContract />

<LocalContract />

<RemoteContract />

## Choose the surface

| Need                                    | Surface                              | Status                            |
| --------------------------------------- | ------------------------------------ | --------------------------------- |
| Govern the released project profiles    | Root `nika.yaml`                     | Live, with the reader limit above |
| Audit and run the installed engine      | `LocalNika` from {SDK.localModule}   | Live                              |
| Stream local run events                 | `LocalNika.run()`                    | Live                              |
| Rehearse with goldens and verify traces | `LocalNika.test()` · `traceVerify()` | Live                              |
| Fire the project clock on a server      | `nika serve` or emitted OS units     | Live                              |
| Design a remote jobs integration        | `Nika` from {SDK.package}            | Preview                           |
| Consume remote SSE and artifacts        | `nika.jobs.*`                        | Preview                           |

The two modules share a package, not a deployment assumption. Import the
local module when the application and engine share a machine. Import the
root module only when a compatible workflow service exists at the other end.

## Install both halves

<CodeGroup>
  ```sh macOS theme={"system"}
  brew install supernovae-st/tap/nika
  npm install @supernovae-st/nika-client
  nika init --project-file
  ```

  ```sh Linux theme={"system"}
  curl -LsSf https://nika.sh/install.sh | sh
  npm install @supernovae-st/nika-client
  nika init --project-file
  ```
</CodeGroup>

Then probe the actual binary:

```ts theme={"system"}
import { LocalNika } from '@supernovae-st/nika-client/local'

const nika = new LocalNika()
console.log(await nika.version())
```

## The application loop

<Steps>
  <Step title="Anchor the project">
    Put `nika.yaml` at the project root and construct `LocalNika` with that
    working directory. The engine discovers project policy around every run.
  </Step>

  <Step title="Audit">
    Call `check()`. Findings resolve as typed data, so the interface can show
    the complete refusal instead of catching one opaque exception.
  </Step>

  <Step title="Admit">
    Read the cost floor, unbounded flag, permits and requirements. Product
    policy decides whether the clean workflow may run here.
  </Step>

  <Step title="Run">
    Stream events with `run()` or collect them with `runToEnd()`. Pass the
    caller's cancellation signal and spend ceiling.
  </Step>

  <Step title="Keep the receipt">
    Store the trace identity beside business state. Verify the chain before
    treating a copied receipt as evidence.
  </Step>
</Steps>

## Documentation graph

<SdkDoors />

## What the SDK does not own

* It does not parse or enforce a second Nika language.
* It does not turn an unpriced model into a zero-cost model.
* It does not infer success from the last event a UI happened to recognize.
* It does not turn the resident firer or local model endpoint into a
  workflow HTTP service.

<CardGroup cols={2}>
  <Card title="Open the visual SDK map" icon="diagram-project" href="https://nika.sh/sdk">
    The public site connects every guide to the language, workflows, boundary
    and proof registers.
  </Card>

  <Card title="Read the source" icon="github" href={SDK.source}>
    The package is Apache-2.0, zero dependency at runtime and tested against
    both local machine contracts and remote fixtures.
  </Card>
</CardGroup>

<Ecosystem />