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

# MoveSpec

> Author, validate, version, and release movement definitions.

# MoveSpec

MoveSpec is a YAML-first movement definition format. You author a MoveSpec to describe the movements you want to detect, then version and release it for use in detection sessions.

## Lifecycle

<Steps>
  <Step title="Create a MoveSpec">
    Create the top-level MoveSpec resource in a project. This also creates a mutable draft.
  </Step>

  <Step title="Update the draft YAML">
    Replace the full draft YAML when you make authoring changes. See the [YAML reference](/movespec/yaml-reference) for the schema.
  </Step>

  <Step title="Validate the draft">
    Run validation before versioning so you can inspect blocking errors and non-blocking warnings.
  </Step>

  <Step title="Create an immutable version">
    Snapshot the draft into an immutable version when it is ready for runtime use.
  </Step>

  <Step title="Release the version">
    Release the immutable version you want future sessions to resolve by default.
  </Step>
</Steps>

## Runtime resolution

Detection sessions can resolve a MoveSpec in two ways:

* **`movespec_version_id`** — Use a specific immutable version for deterministic replay or staged rollout control.
* **`movespec_id`** — Resolve the current released version automatically. Your sessions follow the latest release.

## Example

```python theme={null}
from kynasmith import KynasmithClient
from kynasmith.models import MoveSpecCreate, MoveSpecDraftUpdate

client = KynasmithClient(api_key="ks_key_123:secret_123")

movespec = client.movespecs.create(
    MoveSpecCreate(name="Squat counter")
)
client.movespecs.update_draft(
    movespec.movespec_id,
    MoveSpecDraftUpdate(yaml_source="""
name: squat
version: "1.0"
detection:
  type: repetition
  movement:
    name: squat
    phases:
      - name: standing
        criteria:
          - joint: knee
            angle_min: 160
            angle_max: 180
      - name: bottom
        criteria:
          - joint: knee
            angle_min: 60
            angle_max: 100
    sequence:
      - standing
      - bottom
      - standing
"""),
)
validation = client.movespecs.validate_draft(movespec.movespec_id)
version = client.movespecs.create_version(movespec.movespec_id)
client.movespecs.release_version(
    movespec.movespec_id,
    version.movespec_version_id,
)
```

## Visibility and catalogue

Visibility applies to the top-level MoveSpec resource:

* **`private`** keeps the MoveSpec inside the owning project boundary.
* **`public`** makes the MoveSpec visible through the public catalogue.

Changing visibility does not skip the normal lifecycle. You still validate, version, and release.

## Forking

Treat a public catalogue MoveSpec as a starting point, not as a shared mutable dependency:

* Fork when you want to adapt a public MoveSpec to your own project.
* Release your own immutable version after changing the YAML.
* Keep production integrations pinned to your released version.

This keeps runtime behavior under your control even when the source catalogue entry evolves.

## Public surface

The public developer API covers:

* MoveSpec creation and metadata updates (name, description, visibility)
* Draft reads and full draft replacement
* Draft validation results
* Immutable version listing and creation
* Explicit release of an immutable version
* Forking a MoveSpec into your own project

## Validation output

Validation results include:

* **`errors`** — Block version creation and release readiness. Must be resolved.
* **`warnings`** — Flag risky but non-blocking YAML patterns.

See the [YAML reference](/movespec/yaml-reference) for the complete schema and [MoveSpec validation troubleshooting](/troubleshooting/movespec-validation) for common issues.