Skip to main content

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

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

1

Create a MoveSpec

Create the top-level MoveSpec resource in a project. This also creates a mutable draft.
2

Update the draft YAML

Replace the full draft YAML when you make authoring changes. See the YAML reference for the schema.
3

Validate the draft

Run validation before versioning so you can inspect blocking errors and non-blocking warnings.
4

Create an immutable version

Snapshot the draft into an immutable version when it is ready for runtime use.
5

Release the version

Release the immutable version you want future sessions to resolve by default.

​
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

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 for the complete schema and MoveSpec validation troubleshooting for common issues.