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

# Install

> How syni-spec is distributed, and how SDKs consume it.

You usually don't install `syni-spec` directly. The Syni SDKs
(`syni-flutter`, `syni-swift`, `syni-kotlin`) and the Syni Cloud Gateway all
embed a pinned spec version at build time — so for most app developers,
adding the SDK is enough.

This page describes the underlying distribution channel for the rare cases
where you do need direct access (writing a new SDK, running validation
tooling, building a gateway).

## Distribution channel

Spec releases are published to the Synheart CDN at `dist.synheart.ai`, the
same publishing pipeline used for the Synheart runtime, the CLI, and every
other Synheart artifact.

Each release `vX.Y.Z` ships:

```text theme={null}
dist.synheart.ai/syni-spec/vX.Y.Z/
├── manifest.json       # version + integrity metadata
├── spec.tar.gz         # canonical spec payload (schemas, personas, grammars, …)
└── checksums.json      # SHA-256 per file in the payload
```

The payload structure is canonical — `schemas/`,
`personas/`, `grammars/`, `rules/`, `safety/`, `budgets/`, `registries/`,
`compatibility/`, `prompts/` — with `conformance/` and language wrappers
excluded.

## Install via the Synheart CLI

The `synheart` CLI resolves the latest spec for your project, downloads it,
verifies checksums, and writes the pinned version into `synheart.lock`:

```bash theme={null}
synheart install spec
```

This is the recommended path for backends, gateways, and SDK development.
It uses the same lockfile-driven flow as
[`synheart install runtime`](/setup/install-runtime), so reruns are
reproducible and CI replays from `synheart.lock`.

Pin a specific version:

```bash theme={null}
synheart install spec --version vX.Y.Z
```

Pick an explicit `vX.Y.Z` from the published releases — never track a moving channel for production.

## Consuming from an SDK

If you're building an app on top of `syni-flutter`, `syni-swift`, or
`syni-kotlin`, the SDK already bundles the spec it was built against. You
load personas by id — the SDK handles the asset resolution:

```dart theme={null}
final persona = await SyniSpecPersona.load('focus.coach.v1');
```

Each SDK declares the spec version it supports; mismatched spec versions
fail safely rather than silently disagreeing.

## Integrity rules

Regardless of how you consume the spec, every consumer MUST:

* pin to an explicit `vX.Y.Z` — never track a moving channel for production
* verify `checksums.json` against the unpacked payload
* reject unknown or unsigned releases