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

# Overview

> The canonical behavioral and safety specification for Syni.

`syni-spec` is the single source of truth for how Syni behaves across every
platform and environment. It defines what Syni is allowed to do, how it is
allowed to behave, what it must never do, and what it must always guarantee.

Every Syni SDK (Dart, Swift, Kotlin) and the Syni Cloud Gateway conforms to
this spec.

> If it's in `syni-spec`, it is a contract. If it's not here, it is an
> implementation detail.

## What syni-spec is

* a **behavioral contract**, not an implementation
* a **versioned, immutable** spec — released artifacts are append-only,
  never edited in place
* the **canonical source** of personas, schemas, grammars, safety rules,
  and budgets consumed by every Syni SDK
* distributed as signed, pinned artifacts via
  [`dist.synheart.ai`](/syni-spec/install)

## What syni-spec is not

* not an SDK
* not a runtime
* not a place for feature flags, dynamic configuration, or anything that
  executes code

## What you get on disk

After running `synheart install spec`, the spec payload lands under your
project's `synheart/vendor/syni-spec/` tree:

```text theme={null}
syni-spec/
├── VERSION
├── LICENSE
├── schemas/        # JSON Schemas for outputs and persona meta-schemas
├── personas/       # core / research / prod persona definitions
├── grammars/       # GBNF grammars bound to output schemas
├── rules/          # behavior rules referenced by personas
├── safety/         # global safety policies
├── budgets/        # per-persona resource budgets
├── registries/     # canonical id → file mappings
├── compatibility/  # version compatibility matrices
└── prompts/        # persona prompt fragments
```

Paths inside the payload are identical across language ecosystems — a
persona at `personas/prod/focus.coach.v1.json` lives at the same relative
path whether you consume the spec from Dart, Swift, Kotlin, or a backend
service.

Files released under `personas/prod/`, `schemas/`, and `grammars/` are
**immutable once a version ships** — behavior changes require a new
persona / schema version and a new spec release.

## Personas in the current spec

| Id                       | Purpose                                                                                          | Capability tier |
| ------------------------ | ------------------------------------------------------------------------------------------------ | --------------- |
| `focus.coach.v1`         | Proposes one tiny next action when the user is stuck; summarizes recent session state on request | standard        |
| `stress.coach.v1`        | Validates feelings; offers gentle regulation steps when the user is overwhelmed                  | standard        |
| `cognitive.companion.v1` | Adapts cognitive load to capacity and recovery signals                                           | standard        |
| `performance.coach.v1`   | Schedules peak windows; prioritizes recovery when scores are low                                 | standard        |
| `wellness.guide.v1`      | Favors rest under high stress / low recovery; nudges light movement when sedentary               | standard        |

Every persona produces output conforming to the `coach.response.v1` JSON
Schema, with `global.no_harmful_content` and `global.no_medical_diagnosis`
applied as safety constraints.

The `capability_tier` column is the persona's preferred cloud-model lane
(`fast` / `standard` / `deep`). The Syni Cloud Gateway uses it to pick
a route when the caller hasn't pinned a model — each tier maps to a
different model on the backend, with its own latency and per-day token
budget. Empty / unknown tiers resolve to `standard`, so personas without
the field stay on the default lane.

Synheart ships additional app-specific personas (tuned to particular
Synheart products) that aren't part of the general persona catalog
above. They follow the same spec contract — including `capability_tier`,
safety rules, output schema — but their system prompts and rules are
coupled to a single Synheart app's surface, so they aren't useful as
generic building blocks for tenant apps. Tenants creating their own
personas should model after the general personas in the table above.

## Distribution

Releases are published to `dist.synheart.ai/syni-spec/vX.Y.Z/` with:

* `spec.tar.gz` — the canonical payload (the tree above, packed)
* `checksums.json` — SHA-256 per file in the payload
* `manifest.json` — release metadata
* `SHA256SUMS` — top-level archive checksum

Same publishing pipeline used for the Synheart Runtime and the Syni Runtime.
See [Install](/syni-spec/install) for how to consume the spec from each
language ecosystem.