Manage Job Instructions

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

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:

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.

Every mutation runs the same operation-aware preflight. It verifies the target, checksum, placement, content, and resulting tree, then signs that exact plan for a short time. A changed operation must be preflighted again.

3. Create a page

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. Use --before, --after, or --position to place the page during creation.

Import a DOCX file

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 and plans stable final URLs for embedded images without uploading bytes. Repeated previews produce the same node IDs and checksums. Review any conversion warnings, then rerun with --confirm-live. The CLI verifies that uploaded image URLs match the reviewed plan, creates the canonical job page, and reads it back.

Upload a standalone image

Use the CLI when an image is not embedded in a DOCX file:

opentrain instructions image upload --job <job-id> \
  --file ./quality-example.png --key quality-example-v1 --json

The first run plans the final URL without uploading. Rerun the exact command with the returned --expected-sha256 value and --confirm-live. The CLI refuses if the local file changed after preview. Then place the returned URL in an image node through a page patch, replacement, or bundle. Check opentrain instructions capabilities --json first: an existing external image URL is renderable only when its hostname matches one of image.allowedHostPatterns.

4. Edit without overwriting another writer

Read the current page and retain its checksum:

opentrain instructions page get --job <job-id> --page <page-id> --json

Apply node patches with that checksum:

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. Patch and replacement stage a canonical TipTap document and switch the job page atomically, so an already-open collaboration session is not mutated in place.

Use opentrain instructions page patch --help and opentrain instructions page replace --help for command-specific schemas and examples.

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

5. Revise several pages atomically

opentrain instructions checkout --job <job-id> --dir ./instructions
# Edit the manifest and page JSON files.
opentrain instructions diff --dir ./instructions
opentrain instructions validate --dir ./instructions
opentrain instructions plan --dir ./instructions --out ./instructions.plan.json
opentrain instructions apply --plan ./instructions.plan.json --confirm-live

The local bundle is a working copy, never a second source of truth. Planning fails on remote drift. Applying the immutable plan changes the complete worker-visible tree atomically and writes a local completion journal.

6. Verify canonical and visual state

opentrain instructions verify --job <job-id> --json
opentrain instructions verify --job <job-id> --against-bundle ./instructions --json
opentrain instructions visual-check --job <job-id> --json
opentrain instructions visual session create \
  --job-id <job-id> --audience EMPLOYER --page-id <page-id> \
  --idempotency-key instructions-review-v1 --json
opentrain instructions visual render \
  --session-id <session-id> --expected-state-revision <revision> \
  --viewports desktop,mobile --out ./instructions-proof \
  --idempotency-key instructions-render-v1 --json

visual-check is a checklist. The hosted instructions visual workflow captures the real job editor as checksum-verified desktop/mobile PNGs plus ARIA, diagnostics, and provenance, so an agent can inspect the result directly. Worker-view proof requires --audience WORKER and a designated real test contract; synthetic worker evidence is never substituted. Human review links use normal OpenTrain authentication, not Vercel access. There is no separate publish command.