> ## 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.
# Agent Guide
> The one guidance document every agent on an OpenTrain job receives: the typed job context plus a human-published Playbook, synchronized automatically.
The Agent Guide is the one guidance document for an employer job. Every authorized agent that manages the job through the OpenTrain CLI, MCP server, SDK, or API receives the same guide, and every employer team member can read and shape it from the job's **Agent Guide** tab.
It combines two things under one context revision:
* **The canonical operating context.** A read-only, typed projection of what OpenTrain already knows about the job: the objective and typed workflow gates, effective typed policies and prohibitions, recorded decisions and exceptions, open action claims, fresh attention signals, the job's Work Catalog, and external coverage. This part is authoritative because it is generated from canonical records.
* **The Playbook.** Human-written guidance that your team publishes in versions. It carries the judgment that canonical records cannot: how to handle edge cases, what "good" looks like for this job, and where agents should slow down and ask.
Agents do not maintain competing local copies. They read the guide from OpenTrain, follow the exact changes it reports, and propose improvements that a human reviews.
Agents learn all of this automatically. The first job-scoped call through an
official client starts or resumes a private sync session, and the response
directs exactly one Agent Guide read. Later responses name the exact Playbook
delta to fetch only when the published guidance actually changed. Nobody has
to ask an agent to set this up.
The Agent Guide, Playbook reads and deltas, Playbook proposals, and human
publication require CLI 0.26.0+, MCP 0.26.0+, or SDK 0.24.0+, and a
deployment whose `GET /api/public/v1/capabilities` response reports
`job_operations` as `available`. If npm `latest` is older, the matching
package release has not shipped yet.
## Authority is explicit and ordered
Every Agent Guide states its precedence, highest authority first:
| Layer | Class | Meaning |
| --------------------------------- | --------- | ---------------------------------------------------------------------------------------------------------- |
| Platform invariants | Authority | Rules OpenTrain enforces for every job. Nothing below can relax them. |
| Applied typed policies & workflow | Authority | The effective typed policies and workflow gates recorded for this job. |
| Recorded decisions & exceptions | Authority | Attributed decisions and scoped exceptions recorded in the shared context. |
| Published Playbook | Guidance | Human-published sections. Guidance below every typed record; it can never waive a gate or grant authority. |
| Team overlay notes | Notes | Short attributed notes shared with the team. Not a published document. |
| Personal overlay notes | Notes | Short notes visible only to their author. |
| Session scratch | Notes | An agent session's own working notes. Never authority. |
When Playbook text disagrees with a typed record, the agent raises the disagreement to the responsible human instead of acting on the text. Typed records win.
## The Playbook is versioned Markdown, not an editor file
Your team writes the Playbook in a rich-text editor inside the OpenTrain app. That editor document is private editor storage. No agent surface returns it.
What agents receive is the published version: a bounded set of Markdown sections, each with
* a **stable section id** that survives edits and reorders;
* a **content hash** (SHA-256) over the exact canonical section text;
* the section level, heading, and Markdown body.
Each published version also records the exact **delta** against the version it supersedes: `addedSectionIds`, `changedSectionIds`, and `removedSectionIds`. Removed ids are tombstones. An agent that holds version 3 and learns that version 5 is current can fetch the exact delta from 3 to 5, refresh only the added and changed sections, and drop the removed ones. It never re-reads the whole document to stay current.
Versions are immutable and linear. Publishing never edits a version in place; it creates the next one.
Limits that agents can rely on: at most 64 sections per version, at most 12,000 characters of Markdown per section, version history pages of up to 200 entries, and proposal listings of up to 200 entries.
## Humans publish, agents propose
Publishing a Playbook version is a human job-manager act. The organization owner, or a team member with access to the job, publishes from the **Agent Guide** tab or through the API under a human token. An agent account cannot publish, and an agent acting under a human's token is recorded by its `agentLabel` on the version.
Agents contribute through **proposals**. A proposal carries `RECOMMENDED` authority: it is never enforced and no projection or policy resolver reads it. Three kinds exist:
| Kind | What it proposes |
| ---------------- | -------------------------------------------------------------------------------------------- |
| `SECTION_UPSERT` | A complete section (level, heading, Markdown body) for a stable section id, new or existing. |
| `SECTION_REMOVE` | A tombstone for a section that exists at the current head. |
| `NOTE` | Attributed commentary, optionally anchored to a section, with no proposed content. |
Rules that keep proposals honest:
* `basePlaybookVersion` must equal the current published head, so a proposal is always written against what humans actually published.
* A `dedupeKey` deduplicates concurrent submissions. A live open proposal under the same key is returned as `DEDUPLICATED` instead of creating a duplicate.
* A proposal can expire after a bounded time to live between one hour and 90 days.
* Accepting a `SECTION_UPSERT` or `SECTION_REMOVE` is the human court and must name the published version that landed it. OpenTrain verifies that the landed section's content hash equals the proposed hash exactly. A human can also accept open proposals as part of a publication; the same exact-hash check runs before anything is written.
* Declining is the assigned job court. Withdrawing is the proposer only.
## Synchronization is automatic
The Agent Guide rides the same automatic sync envelope as the rest of [Shared Job Context](/docs/developers/concepts/shared-job-context). The behavior an agent can rely on:
1. **Bootstrap directs one read.** When a session starts or resumes, `sync.nextOperations` ends with `job_operations.agent_guide.get`. The agent reads the composite guide once. It never reads it again as a second bootstrap.
2. **Deltas are conditional.** Whenever the published Playbook head moves past the version the agent could have held at its last acknowledged revision, the next covered response carries `recommendation.agent_guide_changed`. It names the exact delta read, `fromVersion` to `toVersion`, so the agent fetches only what changed. Unchanged guidance is silence, never noise.
3. **Nothing published yet is taught, not hidden.** While no Playbook exists, a new session receives `recommendation.agent_guide_playbook_absent`: read the guide once, then propose sections; humans publish.
4. **Acknowledge only what was delivered.** An agent acknowledges a context revision it actually received. The delivery token can never acknowledge undelivered pages; they replay on the next call. Every agent session's last delivered and acknowledged revisions are visible to your team in the **Activity** node.
The canonical operating context already appears in every context read as a digest (its version and checksum). The Agent Guide read adds the Playbook and the open-proposal count under one checksum.
### Client-instance persistence
The official clients keep the private sync state that makes this automatic:
* The **CLI** persists it only when the runtime supplies a stable agent identity through `PASEO_AGENT_ID` or `OPENTRAIN_AGENT_INSTANCE`. Without one, every command is deliberately ephemeral: it re-bootstraps, is directed to the guide read again, and receives the advisory `recommendation.establish_durable_agent_session`. Never reuse one instance value across concurrent agents; they would share a cursor.
* The **MCP server** keeps the state private to the authenticated connection.
* The **SDK** keeps it private to one `OpenTrainClient` instance.
Deleting local state is always safe. Canonical OpenTrain context remains the authority, and the next covered call bootstraps again.
## What the rest of the guide tells an agent
The canonical part of the Agent Guide is where the other shared-context planes meet, so an agent sees them together:
* **Attention and priorities.** The top fresh attention signals with their claim state. Priority is a triage aid, not permission to act.
* **Action claims and leases.** Who owns which coordinated action and when the lease expires. Claim before work; respect an unexpired claim.
* **Policies and exceptions.** Effective typed policies, prohibitions, and recorded exceptions with attribution and supersession.
* **Work Catalog.** This job's own work definitions, provisional work, and coordination mode. Work types are per-job catalog data that agents define and propose during real use, never a fixed platform list of grading or retraining task types. See [Dynamic Work Catalog](/docs/developers/concepts/dynamic-work-catalog).
* **Activity.** Recent shared-context events and each agent session's last sync, visible to the team in the app.
## Job Instructions are a different document
The Agent Guide is operational guidance for agents and managers. [Job Instructions](/docs/developers/concepts/job-instructions) remain the only canonical source of worker-facing instructions for AI trainers. Publishing a Playbook never changes what AI trainers see, and editing Instructions never changes the Agent Guide.
## Where to go next
The exact CLI, MCP, SDK, and API operations for reading the guide, following deltas, and proposing changes.
Where your team sees the seven-node workspace and publishes the Playbook.
Provenance, readiness gates, claims, policies, and automatic synchronization.
How agents define and coordinate each job's own atomic work.