> ## 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.

# Editor setup

> Schema validation, nika-lsp, the VS Code/Cursor extension, and MCP agent wiring.

export const CANON = {
  schemaVersion: 1,
  verbs: 4,
  verbNames: ["infer", "exec", "invoke", "agent"],
  namespaces: 5,
  namespaceNames: ["vars", "with", "tasks", "env", "secrets"],
  builtins: 23,
  builtinNames: ["assert", "compose", "convert", "date", "done", "edit", "emit", "fetch", "glob", "grep", "hash", "inspect", "jq", "json_diff", "json_merge_patch", "log", "notify", "prompt", "read", "uuid", "validate", "wait", "write"],
  providers: 14,
  providersCloud: 8,
  providersLocal: 5,
  providersTest: 1,
  providerIdsCloud: ["mistral", "anthropic", "openai", "gemini", "deepseek", "xai", "groq", "openrouter"],
  providerIdsLocal: ["ollama", "lmstudio", "llamacpp", "localai", "vllm"],
  providerIdsTest: ["mock"],
  extractModes: 9,
  extractModeNames: ["article", "feed", "jq", "links", "markdown", "metadata", "selector", "sitemap", "text"],
  errorNamespaces: 14,
  errorNamespaceNames: ["NIKA-AGENT", "NIKA-BUILTIN", "NIKA-CANCEL", "NIKA-DAG", "NIKA-EXEC", "NIKA-IMPL", "NIKA-INFER", "NIKA-INVOKE", "NIKA-MCP", "NIKA-PARSE", "NIKA-PROVIDER", "NIKA-SEC", "NIKA-TIMEOUT", "NIKA-VAR"],
  errorCategories: 12,
  errorCodes: 50,
  pillars: 5
};

export const STATUS = {
  head: "95962d5cd",
  branch: "main",
  version: "0.91.0",
  cratesWorkspace: 39,
  cratesAdmitted: 39,
  cratesTarget: "42",
  wipCrates: [],
  libTests: 2989,
  clippyWarnings: 0,
  adrs: 62,
  adrsAccepted: 42,
  adrsProposed: 18,
  providers: 32,
  capabilityRules: 49,
  hygieneVectors: 38,
  hygieneGreen: 28,
  hygieneYellow: 3,
  hygieneRed: 0,
  lastUpdated: "2026-06-25"
};

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{STATUS.version} state:** the binary ships `nika 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: hello

tasks:
  - id: greet
    infer:
      model: ollama/llama3.1               # <provider>/<name> · local · zero key
      prompt: "..."
```

## What tier 1 gets you

<CardGroup cols={2}>
  <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 — `nika lsp` + extension

The generic `yaml-language-server` covers structural validation. A
custom `nika-lsp` crate adds Nika-specific semantics:

<AccordionGroup>
  <Accordion title="Cross-task binding analysis" icon="link">
    Resolves `${{ tasks.X.output }}` across task boundaries. "Go to
    definition" jumps from a binding reference to the source task. Unused
    outputs flagged. Circular dependencies detected before run.
  </Accordion>

  <Accordion title="Taint propagation warnings" icon="shield">
    Tracks untrusted inputs (fetched URLs, user-provided strings) flowing
    into sensitive sinks (shell commands, MCP invocations). Surfaces
    violations in the editor before CI catches them.
  </Accordion>

  <Accordion title="Workflow visualizer" icon="diagram-project">
    Inline DAG preview — a small panel showing the task graph as you
    type. Click a node to jump to its definition.
  </Accordion>

  <Accordion title="Provider / model completion" icon="server">
    Types `provider: ` → autocompletes from the catalog ({CANON.providers} canonical providers · plus extended catalog IDs).
    Types `model: ` after a provider → autocompletes from that
    provider's models. Invalid pairs flagged inline.
  </Accordion>

  <Accordion title="Capability-aware warnings" icon="grid">
    `tools: [...]` on a model without tool\_calling → warning. JSON
    schema on a model without `json_mode: schema` → warning with
    fallback suggestion.
  </Accordion>
</AccordionGroup>

## Roadmap

| Capability                         | Status             | Admission                                 |
| ---------------------------------- | ------------------ | ----------------------------------------- |
| JSON Schema (yaml-language-server) | shipped            | `nika schema` + public schema URL         |
| `nika lsp` L4 crate                | shipped            | `nika lsp`                                |
| VS Code / Cursor extension         | shipped            | Marketplace + OpenVSX                     |
| MCP agent oracle                   | shipped, read-only | `nika mcp` (`nika_check`, `nika_explain`) |
| Zed / Neovim native integrations   | 🧭 planned         | Community + v1.0                          |

## Next

<CardGroup cols={2}>
  <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>