Skip to main content

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.

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: 
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 mirrors the canonical repository layout — 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: 
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, so reruns are reproducible and CI replays from synheart.lock. Pin a specific version, or point at a non-prod CDN: 
# Pin a release explicitly
synheart install spec --version v0.0.1

# Override the CDN (staging / mirror)
SYNHEART_DIST_URL=https://dist.staging.example.com synheart install spec

​
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: 
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.

​
Direct artifact fetch

For tooling that can’t run the CLI (a CI runner, a release pipeline, a language we don’t ship an SDK for), fetch the tarball directly and verify checksums before using it: 
VERSION=v0.0.1
BASE=https://dist.synheart.ai/syni-spec/${VERSION}

curl -fsSL "${BASE}/spec.tar.gz" -o spec.tar.gz
curl -fsSL "${BASE}/checksums.json" -o checksums.json

# Verify before unpacking
sha256sum -c <(jq -r '.files | to_entries[] | "\(.value)  \(.key)"' checksums.json)

tar -xzf spec.tar.gz

​
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