coach

Training Coach — the experience corpus, run diagnosis with in-whitelist proposals, and programme planning. Every claim cites a card.

8 operations · 26 schemas

GET `/v1/coach/doctrine`

The coach's doctrine (numbered methodology rules)

getCoachDoctrine · scope none

The distilled methodology the Training Coach reasons with, as numbered rules with the cases that taught them. Public: it is the corpus that makes the coach's advice citable, and a claim nobody can check is not worth making. Cite a rule as doctrine-{number}.

Responses

getCoachDoctrine responses
Status	Description	Body
`200`	The doctrine.	`CoachDoctrine`
`401`	Missing or invalid credentials.	`Problem`application/problem+json
`503`	A service this endpoint needs is not configured in this deployment (M0's boot guarantee: the API boots with zero secrets, and an endpoint that needs one says so instead of returning a stack trace).	`Problem`application/problem+json

GET `/v1/coach/cards`

Search the experience corpus

searchExperienceCards · scope none

Keyword + tag search over the experience cards (no vector index in v0). q is scored against card id, title, rule, trigger conditions, tags and symptom with inverse-document-frequency weighting, so a term common to the whole corpus contributes nothing. tags is a conjunction — tags=reward-shaping,curriculum returns cards carrying both. With no q the result is every matching card ordered by id, which is what the corpus browser lists.

Parameters

searchExperienceCards parameters
Name	In	Type	Description
`q`	query	`string` length ≤ `500`	Free-text query.
`tags`	query	`string` length ≤ `300`	Comma-separated tags; a card must carry all of them.
`task`	query	`string` length ≤ `32`	Task line filter: walk \| omni \| run \| recovery \| arm \| infra.
`phase`	query	`string` length ≤ `32`	Pipeline phase filter (plant-calibration, reward-shaping, …).
`confidence`	query	`CardConfidence`
`limit`	query	`integer` default `500` · ≥ `1` · ≤ `1000`	Page size (tree listings allow larger pages).
`cursor`	query	`string` length ≤ `512`	Opaque cursor from the previous page's `next_cursor`.

Responses

searchExperienceCards responses
Status	Description	Body
`200`	Page of cards, most relevant first.	`ExperienceCardPage`
`422`	Request failed validation.	`Problem`application/problem+json
`503`	A service this endpoint needs is not configured in this deployment (M0's boot guarantee: the API boots with zero secrets, and an endpoint that needs one says so instead of returning a stack trace).	`Problem`application/problem+json

GET `/v1/coach/cards/{card_id}`

Get one experience card

getExperienceCard · scope none

The full card including its provenance quote — what a citation in an advice report expands to.

Parameters

getExperienceCard parameters
Name	In	Type	Description
`card_id`required	path	`CardId`	Experience card slug, e.g. `resume-state-dr-audit`.

Responses

getExperienceCard responses
Status	Description	Body
`200`	The card.	`ExperienceCard`
`404`	Resource not found (or hidden from the caller).	`Problem`application/problem+json
`503`	A service this endpoint needs is not configured in this deployment (M0's boot guarantee: the API boots with zero secrets, and an endpoint that needs one says so instead of returning a stack trace).	`Problem`application/problem+json

POST `/v1/coach/advice`

Diagnose a training run

createAdvice · scope key:train

Reads a training run — by run_id, or inlined — and returns a structured AdviceReport: diagnosis, in-whitelist proposals, an experiment plan, and flags for anything that would need a contract change. When parent_run_id is set (or the run has one), the resolved-config diff against the parent goes into the prompt as attribution evidence.

Four things are enforced in code, on the model's output, not asked for in the prompt: every proposal's category is in the whitelist; every proposal cites at least one card or doctrine rule that exists in the corpus; every PASS gate found in the scorecard is echoed under experiment_plan.constraints; and no proposal touches the policy contract, observation space, action space or robot description — those may appear only in flags. An invalid report is retried once and then fails with 502 carrying the validation errors.

This endpoint spends model dollars, so it needs key:train like the other compute endpoints, and is additionally capped by a per-account daily quota — every key, session, plan and agent session of the user shares one (429 with X-Coach-Quota-* headers when exhausted).

Request body

application/json · required · AdviceRequest

createAdvice request body
Field	Type	Description
`run_id`	`Id \| null`
`inline`	`AdviceInline \| null`
`parent_run_id`	`Id \| null`
`robot_repo`	`string \| null` pattern `^[a-z0-9](?:[a-z0-9-][a-z0-9])?/[a-z0-9](?:[a-z0-9-][a-z0-9])?$`	Robot repo `{owner}/{slug}`; its card sizes plant advice.
`question`	`string \| null` length ≤ `4000`	What the team actually wants to know.

Responses

createAdvice responses
Status	Description	Body
`201`	Report produced and persisted.	`AdviceSession`
`401`	Missing or invalid credentials.	`Problem`application/problem+json
`403`	Authenticated but not allowed (visibility, membership or scope).	`Problem`application/problem+json
`404`	Resource not found (or hidden from the caller).	`Problem`application/problem+json
`422`	Request failed validation.	`Problem`application/problem+json
`502`	The model's report failed validation twice. `errors[]` carries the broken guarantees; nothing was persisted.	`Problem`application/problem+json
`503`	A service this endpoint needs is not configured in this deployment (M0's boot guarantee: the API boots with zero secrets, and an endpoint that needs one says so instead of returning a stack trace).	`Problem`application/problem+json

POST `/v1/coach/plan`

Plan a training programme from a task brief

createCoachPlan · scope key:train

The zero-runs path. From a task brief (and a robot repo's card, when given) returns the contract to freeze, the plant measurements to take before any training, a minimal reward table, a DR baseline, a ladder outline of one-variable rungs, and a first acceptance battery — every item cited to the corpus. Spends model dollars: key:train, same daily quota as advice.

Request body

application/json · required · CoachPlanRequest

createCoachPlan request body
Field	Type	Description
`task_brief`required	`string` length `1–8000`
`robot_repo`	`string \| null` pattern `^[a-z0-9](?:[a-z0-9-][a-z0-9])?/[a-z0-9](?:[a-z0-9-][a-z0-9])?$`	Robot repo `{owner}/{slug}` whose card sizes the plan.

Responses

createCoachPlan responses
Status	Description	Body
`201`	Plan produced and persisted.	`AdviceSession`
`401`	Missing or invalid credentials.	`Problem`application/problem+json
`403`	Authenticated but not allowed (visibility, membership or scope).	`Problem`application/problem+json
`404`	Resource not found (or hidden from the caller).	`Problem`application/problem+json
`422`	Request failed validation.	`Problem`application/problem+json
`502`	The model's plan failed validation twice.	`Problem`application/problem+json
`503`	A service this endpoint needs is not configured in this deployment (M0's boot guarantee: the API boots with zero secrets, and an endpoint that needs one says so instead of returning a stack trace).	`Problem`application/problem+json

GET `/v1/coach/sessions`

List coach sessions

listAdviceSessions · scope key:read

Sessions visible to the caller, newest first.

Parameters

listAdviceSessions parameters
Name	In	Type	Description
`run_id`	query	`Id`	Only sessions about this run.
`limit`	query	`integer` default `20` · ≥ `1` · ≤ `100`	Page size.
`cursor`	query	`string` length ≤ `512`	Opaque cursor from the previous page's `next_cursor`.

Responses

listAdviceSessions responses
Status	Description	Body
`200`	Page of sessions.	`AdviceSessionPage`
`401`	Missing or invalid credentials.	`Problem`application/problem+json

GET `/v1/coach/sessions/{session_id}`

Get a coach session

getAdviceSession · scope key:read

Parameters

getAdviceSession parameters
Name	In	Type	Description
`session_id`required	path	`Id`	Coach session id (`advice_...`).

Responses

getAdviceSession responses
Status	Description	Body
`200`	The session.	`AdviceSession`
`401`	Missing or invalid credentials.	`Problem`application/problem+json
`404`	Resource not found (or hidden from the caller).	`Problem`application/problem+json

POST `/v1/coach/sessions/{session_id}/feedback`

Rate a coach report

setAdviceFeedback · scope key:write

Thumbs up or down, with an optional note. Feedback is a corpus candidate: a report plus a verdict plus the run that actually followed is the raw material of the next experience card. Idempotent — the last verdict wins.

Parameters

setAdviceFeedback parameters
Name	In	Type	Description
`session_id`required	path	`Id`	Coach session id (`advice_...`).

Request body

application/json · required · AdviceFeedback

setAdviceFeedback request body
Field	Type	Description
`verdict`required	`string` one of `up` · `down`
`note`	`string \| null` length ≤ `4000`

Responses

setAdviceFeedback responses
Status	Description	Body
`200`	Feedback recorded; the session is returned.	`AdviceSession`
`401`	Missing or invalid credentials.	`Problem`application/problem+json
`403`	Authenticated but not allowed (visibility, membership or scope).	`Problem`application/problem+json
`404`	Resource not found (or hidden from the caller).	`Problem`application/problem+json
`422`	Request failed validation.	`Problem`application/problem+json

Schemas (26)

The schemas these operations reach before any other tag’s do. A type that links elsewhere is rendered on that tag’s page.

CoachDoctrine

object

CoachDoctrine fields
Field	Type	Description
`rules`required	`array of DoctrineRule`
`markdown`	`string` length ≤ `200000`	The doctrine as written, for rendering.
`card_count`required	`integer` ≥ `0`
`tags`	`array of CardTag`

CardConfidence

string

one of observed-once · replicated · mechanism-understood · hypothesis

How well the card's mechanism is established. observed-once — it happened once, mechanism plausible. replicated — the same effect at least twice. mechanism-understood — cause demonstrated by a targeted experiment. hypothesis — inferred by the corpus author, not demonstrated. A proposal resting only on hypothesis cards must say so in its risk.

ExperienceCardPage

object

ExperienceCardPage fields
Field	Type	Description
`items`required	`array of ExperienceCard`
`next_cursor`required	`string \| null`
`total`required	`integer` ≥ `0`	Cards matching the query across all pages.

CardId

string

length ≤ 96 · pattern ^[a-z0-9][a-z0-9-]*$

Experience card slug — stable, never renumbered.

ExperienceCard

object

One distilled sim2real / RL-training lesson.

ExperienceCard fields
Field	Type	Description
`id`required	`CardId`
`title`required	`string` length ≤ `400`
`robot`	`string` length ≤ `200`
`task`	`string` length ≤ `32`	walk \| omni \| run \| recovery \| arm \| infra
`phase`	`string` length ≤ `32`	plant-calibration \| reward-shaping \| dr-tuning \| attribution \| ...
`symptom`	`string` length ≤ `4000`
`context`	`string` length ≤ `8000`
`change`	`string` length ≤ `4000`
`outcome`	`string` length ≤ `4000`
`mechanism`	`string` length ≤ `4000`
`rule`required	`string` length ≤ `2000`	The transferable one-liner. Robot-agnostic by construction.
`applies_when`	`array of string`
`tags`required	`array of CardTag`
`confidence`required	`CardConfidence`
`conflicts`	`string \| null` length ≤ `4000`
`provenance`	`CardProvenance \| null`
`score`	`number \| null`	Search relevance; null when the listing is unscored.

AdviceRequest

object

Exactly one of run_id or inline. parent_run_id overrides the run's stored parent for this call.

AdviceRequest fields
Field	Type	Description
`run_id`	`Id \| null`
`inline`	`AdviceInline \| null`
`parent_run_id`	`Id \| null`
`robot_repo`	`string \| null` pattern `^[a-z0-9](?:[a-z0-9-][a-z0-9])?/[a-z0-9](?:[a-z0-9-][a-z0-9])?$`	Robot repo `{owner}/{slug}`; its card sizes plant advice.
`question`	`string \| null` length ≤ `4000`	What the team actually wants to know.

AdviceSession

object

One persisted coach call. Retained even when the user throws the report away: a report plus a verdict plus the run that actually followed is the raw material of the next experience card.

AdviceSession fields
Field	Type	Description
`id`required	`Id`
`kind`required	`string` one of `advice` · `plan`
`run_id`	`Id \| null`
`run_ref`required	`string` length ≤ `128`	The subject: a run id, `inline`, or `plan`.
`report`	`AdviceReport \| null`	Present when `kind` is `advice`.
`plan`	`CoachPlan \| null`	Present when `kind` is `plan`.
`cited_card_details`	`array of ExperienceCard`	The full cards this report cites, so a client can expand a citation to its provenance quote without a second round trip.
`retrieved_cards`	`array of CardId`	Card ids put in front of the model (≤15).
`model`required	`string` length ≤ `64`
`backend`	`string` length ≤ `32`	`anthropic` or `recorded`. A replayed report must never read as a real one.
`usage`required	`AdviceUsage`
`feedback`	`string \| null` one of `up` · `down`
`feedback_note`	`string \| null` length ≤ `4000`
`created_at`required	`string (date-time)`

CoachPlanRequest

object

CoachPlanRequest fields
Field	Type	Description
`task_brief`required	`string` length `1–8000`
`robot_repo`	`string \| null` pattern `^[a-z0-9](?:[a-z0-9-][a-z0-9])?/[a-z0-9](?:[a-z0-9-][a-z0-9])?$`	Robot repo `{owner}/{slug}` whose card sizes the plan.

AdviceSessionPage

object

AdviceSessionPage fields
Field	Type	Description
`items`required	`array of AdviceSession`
`next_cursor`required	`string \| null`

AdviceFeedback

object

AdviceFeedback fields
Field	Type	Description
`verdict`required	`string` one of `up` · `down`
`note`	`string \| null` length ≤ `4000`

DoctrineRule

object

DoctrineRule fields
Field	Type	Description
`id`required	`string` pattern `^doctrine-[0-9]+$`	Citation form: `doctrine-{number}`.
`number`required	`integer` ≥ `1`
`title`required	`string` length ≤ `300`
`statement`required	`string` length ≤ `4000`
`case`	`string` length ≤ `8000`	The episode that taught the rule.
`application`	`string` length ≤ `4000`	How the coach applies it.
`cited_cards`	`array of CardId`

CardTag

string

one of plant-calibration · actuator-modeling · observation-honesty · reward-shaping · action-rate · domain-randomization · fork-selection · gate-battery · real-acceptance · attribution · process · contract-freeze · sim2sim · curriculum · termination · hardware · measurement

Controlled retrieval vocabulary (see assets/experience/schema.json).

CardProvenance

object

Where the card's claim comes from. This is what a citation in a report expands to in the UI — the point of the corpus is that every number is traceable to a sentence somebody actually wrote at the time.

CardProvenance fields
Field	Type	Description
`file`required	`string` length ≤ `512`
`section`required	`string` length ≤ `512`
`quote`required	`string` length ≤ `8192`
`extra`	`array of object`	Additional corroborating citations.
`file`required	`string` length ≤ `512`
`section`required	`string` length ≤ `512`
`quote`required	`string` length ≤ `8192`

AdviceInline

object

A run snapshot supplied by value, for a run not on the hub.

AdviceInline fields
Field	Type	Description
`config_yaml`required	`string` length ≤ `400000`	The run's RESOLVED training config (YAML or JSON).
`metrics_summary`	`string` length ≤ `200000`	Metrics as text — a CSV tail, a table, or prose.
`scorecard_json`	`object \| null`	Acceptance results. PASS/FAIL rows are read from a `gates` key when present, otherwise discovered from any leaf carrying a PASS/FAIL token; every PASS row becomes a constraint in the report.
`parent_config_yaml`	`string` length ≤ `400000`	The parent run's resolved config, for the attribution diff.

AdviceReport

object

AdviceReport fields
Field	Type	Description
`summary`	`string` length ≤ `4000`
`diagnosis`required	`array of Diagnosis`
`proposals`required	`array of Proposal`
`experiment_plan`required	`ExperimentPlan`
`flags`required	`array of AdviceFlag`

CoachPlan

object

CoachPlan fields
Field	Type	Description
`contract_checklist`required	`array of string`
`plant_calibration_checklist`required	`array of string`
`reward_baseline`required	`array of CoachRewardTerm`
`dr_baseline`required	`array of CoachDRTerm`
`ladder_outline`required	`array of ExperimentRung`
`acceptance_battery_draft`required	`array of CoachAcceptanceRow`
`cited_cards`	`array of string`
`notes`	`string` length ≤ `4000`

AdviceUsage

object

What this call cost. Metered per session, retries included.

AdviceUsage fields
Field	Type	Description
`input_tokens`required	`integer` ≥ `0`
`output_tokens`required	`integer` ≥ `0`
`cache_read_tokens`	`integer` ≥ `0`
`cache_write_tokens`	`integer` ≥ `0`
`cost_usd`required	`number`	USD to 6 decimal places; 0 when the model has no rate row.
`priced`	`boolean`	False means usage was recorded but the model is unpriced.
`attempts`	`integer` ≥ `1`	Model calls made, including the retry after a validation failure.

Diagnosis

object

Diagnosis fields
Field	Type	Description
`symptom`required	`string` length ≤ `2000`
`likely_mechanism`required	`string` length ≤ `4000`
`confidence`required	`string` one of `high` · `medium` · `low`
`missing_evidence`	`array of string`	What would settle it. The most valuable field in the report.
`cited_cards`	`array of string`

Proposal

object

One in-whitelist parameter change. Guaranteed in code: category is in the whitelist, cited_cards is non-empty and every entry resolves in the corpus, and param_path touches nothing contract-, observation-, action- or robot-description-shaped.

Proposal fields
Field	Type	Description
`param_path`required	`string` length ≤ `300`	Dotted path in the run's config, e.g. `rewards.feet_air_time.weight`.
`from`	`string \| null` length ≤ `300`	Current value as text; null when the key is absent today.
`to`required	`string` length ≤ `300`
`category`required	`ProposalCategory`
`rationale`required	`string` length ≤ `4000`
`cited_cards`required	`array of string` items ≥ `1`	Card ids and/or `doctrine-N` rule ids. At least one, all real.
`risk`required	`string` length ≤ `2000`	What this could cost. When every cited card is `confidence: hypothesis`, this must say the mechanism is a hypothesis — enforced.

ExperimentPlan

object

ExperimentPlan fields
Field	Type	Description
`rungs`required	`array of ExperimentRung`
`stop_rules`required	`array of string`	Hit any one, stop. Frozen before training.
`constraints`required	`array of string`	Standing regression constraints. Every PASS gate in the scorecard appears here — enforced in code, not requested in the prompt.

AdviceFlag

object

A suspicion that lands outside the whitelist. Contract, observation space, action space and robot description changes appear here and nowhere else: they need a versioned profile, a fingerprint update and a checker extension in the same change, none of which a coach can promise.

AdviceFlag fields
Field	Type	Description
`concern`required	`string` length ≤ `2000`
`param_path`	`string \| null` length ≤ `300`
`why_out_of_whitelist`required	`string` length ≤ `2000`
`cited_cards`	`array of string`

CoachRewardTerm

object

CoachRewardTerm fields
Field	Type	Description
`name`required	`string` length ≤ `120`
`purpose`required	`string` length ≤ `1000`
`starting_weight`	`string \| null` length ≤ `120`
`cited_cards`	`array of string`

CoachDRTerm

object

CoachDRTerm fields
Field	Type	Description
`name`required	`string` length ≤ `120`
`range`required	`string` length ≤ `200`
`measured_from`required	`string` length ≤ `1000`	How the nominal and the band were measured (never guessed).
`cited_cards`	`array of string`

ExperimentRung

object

One ladder rung — exactly one variable, read off a pre-registered table.

ExperimentRung fields
Field	Type	Description
`name`required	`string` length ≤ `200`
`variable`required	`string` length ≤ `300`	The single thing this rung changes.
`expected_reading`required	`string` length ≤ `2000`	How each plausible outcome will be read, written before it runs.
`stop_after`	`string \| null` length ≤ `200`

CoachAcceptanceRow

object

CoachAcceptanceRow fields
Field	Type	Description
`name`required	`string` length ≤ `160`
`metric`required	`string` length ≤ `300`
`threshold`required	`string` length ≤ `200`
`kind`	`string` length ≤ `32`	task \| posture \| margin \| assist-stripped \| chirality

ProposalCategory

string

one of reward · domain_rand · command · curriculum · ppo_hyperparam · calibration

What a proposal is allowed to touch. Two whitelists exist by design and this is the wider one — a human reads the report and pulls the trigger, so hyperparameters and calibration are in scope. The future auto-loop (agent pulls the trigger) uses the same validator configured down to reward | domain_rand | command.

coach

GET /v1/coach/doctrine

Responses

GET /v1/coach/cards

Parameters

Responses

GET /v1/coach/cards/{card_id}

Parameters

Responses

POST /v1/coach/advice

Request body

Responses

POST /v1/coach/plan

Request body

Responses

GET /v1/coach/sessions

Parameters

Responses

GET /v1/coach/sessions/{session_id}

Parameters

Responses

POST /v1/coach/sessions/{session_id}/feedback

Parameters

Request body

Responses

Schemas (26)

CoachDoctrine

CardConfidence

ExperienceCardPage

CardId

ExperienceCard

AdviceRequest

AdviceSession

CoachPlanRequest

AdviceSessionPage

AdviceFeedback

DoctrineRule

CardTag

CardProvenance

AdviceInline

AdviceReport

CoachPlan

AdviceUsage

Diagnosis

Proposal

ExperimentPlan

AdviceFlag

CoachRewardTerm

CoachDRTerm

ExperimentRung

CoachAcceptanceRow

ProposalCategory

GET `/v1/coach/doctrine`

GET `/v1/coach/cards`

GET `/v1/coach/cards/{card_id}`

POST `/v1/coach/advice`

POST `/v1/coach/plan`

GET `/v1/coach/sessions`

GET `/v1/coach/sessions/{session_id}`

POST `/v1/coach/sessions/{session_id}/feedback`