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

# Manage Job Instructions

> Inspect, preview, create, import, edit, and verify a job's real Instructions pages with an agent.

This workflow updates the same pages an employer sees in the selected job's
**Instructions** tab.

**Requirements:** an employer API token with `instructions:read` for reads and
`instructions:write` for preview or mutations. The token owner must have access
to the target job.

## 1. Inspect the job

```bash theme={null}
opentrain instructions inspect --job <job-id> --json
```

The response identifies `canonicalSource: "JOB_INSTRUCTION_SET"`, the page
tree, folder inheritance, and the exact employer URL. Use only page IDs from
this response.

## 2. Preview rich content

Save a TipTap `doc` node in `page.json`, then validate and render it without
writing:

```bash theme={null}
opentrain instructions page preview --job <job-id> \
  --content-file ./page.json --json
```

The response includes `writesApplied: false`. Review the rendered HTML before
confirming a live mutation.

## 3. Create a page

```bash theme={null}
opentrain instructions page create --job <job-id> \
  --title "Quality standards" \
  --content-file ./page.json \
  --key quality-standards-v1 \
  --confirm-live --json
```

The idempotency key makes a retry safe. Omit `--confirm-live` to preview the
content and command summary without writing.

Use `--parent <root-page-id>` to create one subpage beneath a root. A subpage
cannot have children.

## Import a DOCX file

```bash theme={null}
opentrain instructions import docx --job <job-id> \
  --file ./project-guide.docx \
  --title "Project guide" \
  --key project-guide-docx-v1
```

The first run previews the converted structure. Embedded images appear as
placeholders and no bytes are uploaded. After review, rerun with
`--confirm-live`. The CLI uploads the images, inserts them in the TipTap page,
creates the canonical job page, and reads it back.

## 4. Edit without overwriting another writer

Read the current page and retain its checksum:

```bash theme={null}
opentrain instructions page get --job <job-id> --page <page-id> --json
```

Apply node patches with that checksum:

```bash theme={null}
opentrain instructions page patch --job <job-id> --page <page-id> \
  --expected-checksum <sha256> \
  --ops-file ./patch.json \
  --confirm-live --json
```

For a complete replacement, preview the new document first and then use both
`--confirm-replace` and `--confirm-live`. A stale checksum returns a conflict;
read the page again and reconcile the human's changes.

Rename, move, or archive pages with the corresponding `page` command. These
operations also require `--confirm-live`; archive additionally requires
`--confirm-archive`.

## 5. Verify worker-visible state

```bash theme={null}
opentrain instructions verify --job <job-id> --json
```

Open the returned employer URL when human visual verification is needed. CLI
success already includes canonical readback, but only this job URL represents
the worker instruction source—there is no separate publish command.