nika-docs

Source of docs.nika.sh: the Mintlify-built documentation for Nika, the AGPL Rust workflow engine for AI.

Live at docs.nika.sh. Every merge to main deploys via the Mintlify GitHub App. Preview locally with the steps below.

What this repo is

A standalone public repository whose only job is to host the Mintlify documentation source: a docs.json navigation config plus .mdx pages. Mintlify watches main via its GitHub App and rebuilds the live site on push. The repo also runs its own drift gate in CI (.github/workflows/gate.yml, scripts/link-audit.py): internal links resolve · every page registered in docs.json nav · no dead-branch GitHub refs · no legacy {{ }} binding syntax.

This repo is not the Nika engine source, not the marketing site, and not a library you install.

Structure

nika-docs/
├── docs.json              Mintlify config + navigation (every page MUST be registered)
├── introduction.mdx       Landing
├── getting-started/       installation · your-machine · first-workflow · editors · agents
├── guides/                patterns · agent-authoring · templates · troubleshooting · local-models · … (task-oriented)
├── concepts/              architecture · verbs · workflows · bindings · events · providers · security · …
├── examples/              overview + the tiered showcase workflows (PROJECTED; counts live in the projector)
├── integrations/          editor · CI · agent-client wiring (nested)
├── sdk/                   TypeScript SDK · start · project control · local · runtime · remote preview · operations · reference
├── patterns/              cross-cutting pattern index
├── architecture/          layers · FCI · L0 decisions · admission · ADR index
├── reference/             YAML · CLI · schema · error codes · builtins · providers catalog · MCP catalog · MCP server · capabilities · constellation · design system · machine surfaces · status
├── changelog/             releases · roadmap
├── snippets/              _canon · _status-snapshot · _showcase · _ecosystem (auto-generated/shared; see below)
├── scripts/link-audit.py  the repo's own drift gate (see CI)
├── .github/workflows/     gate.yml (link-audit on every push/PR)
├── images/                logos + favicon
└── global.css             Mermaid transparent background

Curated MDX across four tabs: Guide · Architecture · Reference · Changelog. No page count here on purpose — docs.json is the nav source of truth, and a hand-typed total is the first thing to rot.

Local preview

Node 22 LTS is required (Mintlify blocks Node 25+). A .nvmrc is checked in.

# Pick up Node 22 (.nvmrc says 22):
nvm use                    # or: export PATH="/opt/homebrew/opt/node@22/bin:$PATH"

# Zero-config preview (no install step):
npx mintlify@latest dev    # serves http://localhost:3000

# Broken-link check before opening a PR:
npx mintlify@latest broken-links

There is no package.json; Mintlify's CLI runs standalone via npx.

Generated content: never hand-edit

Three classes of content are PROJECTED from external sources of truth. Hand edits are overwritten on the next regeneration (and the projector --check gates catch drift in the monorepo audit):

Surface	Source of truth	Regenerate
snippets/_status-snapshot.mdx · version + lastUpdated	published GitHub release	bash scripts/mintlify-snapshot.sh (here)
snippets/_status-snapshot.mdx · every count	engine main refresh-status.sh block	hand-copied. No gate watches it — see the file header for the per-field derivation commands
snippets/_canon.mdx (language facts: verbs/builtins/providers counts)	nika-spec/canon.yaml	python3 scripts/canon-projectors.py --write (in the spec)
examples/*.mdx YAML+mermaid blocks · guides/templates.mdx template blocks · reference/error-codes.mdx tables	nika-spec showcase/ · templates/ · error registry	python3 scripts/showcase-projector.py --write (in the spec)

In page bodies, never hardcode counts. Import {CANON} / {STATUS} from the snippets and reference fields ({CANON.builtins}, {STATUS.cratesAdmitted}). Frontmatter description: cannot import, so keep volatile numbers out of descriptions entirely.

Deploy

The Mintlify GitHub App is installed on this repo. Each push to main triggers an automatic rebuild (typically ~30 seconds) and updates docs.nika.sh. No CI configuration lives in this repo.

Content conventions

• Brand assets (images/logo-{light,dark}.svg · images/favicon.svg) are vendored from the Nika brand kit; canonical files + usage rules at nika.sh/brand (BRAND.md). Sync contents from the kit, never hand-tune colors here.
• Narrative vocabulary (locked): "organ" not "module", "admitted" not "added", "grew" not "shipped", "chrysalis" not "beta", "emerge" reserved for the 1.0 release.
• Butterfly 🦋 is used sparingly: only in introduction.mdx's closing line, never in nav, chrome, or headings.
• Headings: sentence case, never title case.
• Voice: direct, technical, AGPL-proud, never try-hard.

Contributing

Pull requests are welcome.

1. Fork + branch from main.
2. Run npx mintlify@latest dev locally and verify your changes render.
3. Run npx mintlify@latest broken-links AND python3 scripts/link-audit.py. Both must be clean (CI enforces the latter).
4. One .mdx file per page, and every page must be listed in docs.json.
5. Keep conventions above (vocabulary, headings, voice) + the generated-content rules (no hand-edits to projected blocks · no hardcoded counts).

The city · where this repo sits

📜 nika-spec ──── the civil code · the law tables, the corpus, the exam
    │ sync-pack: byte-gated mirror        │ projectors: drift-gated
    ▼                                     ▼
⚙️ nika ───────── the engine + the catalog (the yellow pages)
    │ the release train                  🖥️ nika.sh · 📖 nika-docs   ◀── you are here
    ▼                                     the showroom · the manual
📦 homebrew-tap · npm · Docker ── the docks
🔌 nika-client · 🎨 nika-vscode · 🤖 nika-plugins · ⚡ gh-nika ── the doors
🏭 nika-action · 🧪 nika-actions-starter ── the CI district
🏪 nika-registry ── the market · 🏛 nika-estate ── the land registry

This building · THE MANUAL · explains the language; same projection law as the showroom.

Root · neither · this building projects both. Language facts come from nika-spec (the canon snippet, the showcase markers), engine facts from the released binary · nothing authoritative is typed here.

Consumes · the spec (canon snippets, projected) · the engine (status snapshot, refreshed).

Serves · readers at docs.nika.sh.

Truth lives · see « Generated content: never hand-edit » above — a fact is imported, never typed.

All the buildings: nika-spec · nika · nika.sh · nika-docs · nika-client · nika-vscode · nika-plugins · gh-nika · homebrew-tap · nika-action · nika-actions-starter · nika-registry · nika-estate

Every fact has one home · everything else is a gated projection. The living map: nika.sh/map.

License

AGPL-3.0-or-later, same as the engine.

_{Start from a template: nika-actions-starter (workflow + editor wiring + CI receipts)
Docs: docs.nika.sh · Engine (AGPL-3.0): nika · 🦋 SuperNovae Studio · Paris}