_contract git:20260920.87073e5A

Immutable. This exact content never changes and is served at /api/v1/blob/81ae5d06be67daa5.

---
name: _contract
description: "The shared vocabulary that domain skills use to name Montaj operations. Domain skills phrase every Montaj interaction as one of these verbs; an interface skill defines how each verb is actually performed. Load this to learn the canonical verbs before authoring or reading a domain skill."
---

# The Vocabulary Contract

Montaj's skills are split into **domain skills** (what to do — transport-agnostic) and **interface skills** (how Montaj is reached — native CLI/HTTP here, or a consumer's remote interface in another repo). This document is the small, stable vocabulary the two sides share.

A **domain skill** describes creative/editing work in terms of the canonical verbs below — and nothing else. An **interface skill** defines HOW each verb is performed on a particular transport. The domain skills never need to know which interface is in play.

This is a contract written for an LLM reader: it is prose conventions, not a strict schema. Phrase things naturally, but stay inside these verbs.

## The canonical verbs

Each Montaj interaction is exactly one of these:

- **run step `<name>` with `<args>`** — invoke a Montaj step and use its output. Steps are the core compute units: e.g. `waveform_trim`, `rm_nonspeech`, `transcribe`, `crop_spec`, `virtual_to_original`, `search_images`, `fetch_image`. (Authoring an overlay is NOT a step — overlays are written as files and saved into the project.)
- **read the project** — get the current project state: clips, tracks, settings.
- **save the project (delta)** — persist only the fields you changed. See the discipline below; this verb is never "save the whole thing I had cached."
- **write a file `<path>` `<contents>`** — create or overwrite a workspace file (overlay JSX, fetched images, assets).
- **read a file `<path>`** — read a workspace file back.
- **log `<message>`** — emit operator-visible progress.

## Save discipline (domain rule, transport-neutral)

Saving the project is always **GET-fresh → merge → save**:

1. **read the project** immediately before saving — get the current state right now.
2. **merge** only your changed fields into that fresh state.
3. **save the project (delta)** with those fields.

Never save from a stale cached body. The operator may be editing the project concurrently, so a body you read minutes ago can clobber their work. Re-read every time, even if you "just" read it.

## Two hard rules

**No transport language.** Domain skills MUST phrase every Montaj interaction as one of the verbs above and MUST NOT name a transport. No `localhost`, no port numbers, no `montaj run`, no `PUT /api/...`, no `curl`, no reading or writing `project.json` directly. If a domain skill mentions a URL, a port, an HTTP method, or a literal on-disk project file, it has leaked the transport and is wrong. The interface skill owns all of that.

**Name-based sub-skill references.** Refer to other skills by name, not by file path — e.g. "load skill `write-overlay`", not `skills/write-overlay/SKILL.md`. The reader resolves the name; the path may differ per interface.

## Coverage note

These verbs are sufficient for the Phase-1 domain skills:

- **select-takes** — run step `crop_spec`, run step `virtual_to_original`; read the project; write a file (the trim spec comes back inline from `waveform_trim` and must be on disk before `crop_spec` can take it as `--input`).
- **overlay** — read the project; save the project (delta); load skill `write-overlay`.
- **write-overlay** — save the project (delta); write a file (the JSX); run step `sample_overlay` (the end-of-authoring measure pass, required for any overlay that declares `googleFonts`); reference asset paths via written/read files.
- **image-search** — run step `search_images`, run step `fetch_image`; write a file / read a file.

If a future domain skill needs an operation not on this list, extend this contract first — do not let a domain skill invent its own transport-specific phrasing.

**This list is a starting index, not the final word.** It has drifted from the skill bodies before: `select-takes`'s "write a file" and `write-overlay`'s `sample_overlay` were both required by their skills and missing here. Anyone deriving the operations a workflow needs must confirm against the skill body itself — a set derived from this list alone can silently omit something the skill genuinely requires.