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

# Job Instructions

> How agents and employers share one canonical, rich instruction document for each OpenTrain job.

Every OpenTrain job has one canonical set of worker instructions: the pages in
that job's employer **Instructions** tab. The web editor, worker view, API,
SDK, CLI, and MCP server all read and write that same content.

There are no standalone instruction workspaces, reusable manuals, job
bindings, publication copies, or separate review queues. A successful
job-instruction write must be visible at the employer URL returned in the
response.

## Page tree

Instructions are a multi-page tree with two supported levels:

* Root pages
* One level of subpages beneath a root

This is the same limit enforced by the employer editor. An agent cannot create
a deeper tree through another surface.

A job can also inherit read-only pages from its folder. The inspect response
identifies inherited pages and explains when the job is locked to the folder
source.

## Rich documents and checksums

Each page body is a TipTap JSON document:

```json theme={null}
{
  "type": "doc",
  "content": [
    {
      "type": "heading",
      "attrs": { "level": 1, "id": "overview" },
      "content": [{ "type": "text", "text": "Task overview" }]
    }
  ]
}
```

Reads return the document with a deterministic SHA-256 checksum. Patch and
replacement requests present the last-read checksum, so a concurrent human
edit produces a conflict instead of being overwritten.

## Preview and live writes

The current job editor is immediately live: there is no separate publication
step. Use the preview operation to validate and render a complete TipTap
document without writing. Mutations require `confirmLive: true` (or
`--confirm-live` in the CLI) to acknowledge that hired AI trainers can see the
result immediately.

Agent tools read the canonical page back after a mutation before reporting
success. Treat only that readback and returned employer URL as confirmation;
a response from any unrelated document system is not worker-visibility
evidence.

## Images and DOCX files

The canonical image endpoint accepts JPEG, PNG, WebP, GIF, and AVIF files up to
5 MB and returns a URL for a TipTap image node. Uploading an image does not edit
a page by itself.

The CLI can import a DOCX file into a new job page. It converts supported
headings, paragraphs, formatting, links, lists, tables, and embedded images.
Preview mode uses visible placeholders and uploads nothing. A confirmed import
uploads each embedded image and places it in the canonical TipTap document.

General file, audio, and video attachments are not currently part of the job
Instructions API. Do not assume support based on another OpenTrain feature.

## Required scopes

* `instructions:read` reads a job tree or page.
* `instructions:write` previews content, uploads images, and mutates pages.

The token owner must also have employer access to the job. A scope never grants
cross-organization access.

Next, follow [Manage job Instructions](/docs/developers/guides/manage-job-instructions)
or choose the [CLI](/docs/developers/cli/instructions),
[MCP](/docs/developers/mcp/instructions), or
[HTTP API](/docs/developers/api-reference/instructions/overview).