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

# Update the Playbook and publish an agent

> Preview Playbook changes in staging and publish the exact approved agent version.

Use the Hobbes API when a backend service or coding agent needs to read or
update the Playbook. Updates always go to staging first. Publishing production
is a separate action with its own scope, confirmation, and test gate.

<Note>
  For a person working from Claude or another AI client, connect to the
  [Hobbes MCP server](/guides/connect-ai-clients) instead of managing an API key.
</Note>

## Choose scopes

| Scope            | Use it for                                                                                   |
| ---------------- | -------------------------------------------------------------------------------------------- |
| `playbook:read`  | Read staging and production Playbooks, version details, links, and ready suggestions         |
| `playbook:write` | Preview authored changes and apply approved previews or stored suggestions to staging        |
| `agent:publish`  | Queue the exact current staging version for production after explicit confirmation and tests |

These scopes are off by default and are never added to existing keys. Create or
rotate a key with only the access the integration needs.

## Preview and apply a change

<Steps>
  <Step title="Read the current Playbook">
    Call `GET /api/v1/playbook`. Save `sectionsEtag` and use the returned
    section catalog to target supported fields. The response also includes
    links for testing the staging and production agents.
  </Step>

  <Step title="Create a preview">
    Call `POST /api/v1/playbook/update-previews` with restricted JSON Patch
    operations and a stable `operationKey`. Set `expectedSectionsEtag` to the
    current `sectionsEtag`.
    Hobbes validates the request against a clone and returns a before-and-after
    summary without changing staging.
  </Step>

  <Step title="Review the summary">
    Show the changed sections to the person who requested the update. Do not
    treat a preview as an applied or published change.
  </Step>

  <Step title="Apply the preview to staging">
    Call `POST /api/v1/playbook/update-previews/{preview_id}/apply`. The preview
    must be unexpired and created by the same API key. If staging changed after
    the preview, Hobbes returns `409` and creates no version. Create a fresh
    preview against the latest `sectionsEtag`.
  </Step>

  <Step title="Test staging">
    Open the staging link from Hobbes and verify the changed behavior before
    publishing.
  </Step>
</Steps>

Previews expire after 24 hours. Repeating a successful apply returns the
original result instead of creating another version.

## Apply a Hobbes suggestion

Call `GET /api/v1/playbook/suggestions` to list ready suggestion groups with
their evidence and exact proposed changes. Apply one with
`POST /api/v1/playbook/suggestions/{group_id}/apply` only when the stored wording
should be used as generated. Use the preview process when the wording needs to
change.

## Publish the staged agent

Publishing changes production and requires a new confirmation at the time of
the request.

1. Read the Playbook again and confirm the exact current staging version.
2. Ask the user to confirm publishing that version to production.
3. Call `POST /api/v1/agent/publish-jobs` with a stable `operationKey`, the
   current staging version, and `confirmation: "publish_to_production"`.
4. Poll `GET /api/v1/agent/publish-jobs/{job_id}`. Send the returned `ETag` as
   `If-None-Match` and honor `Retry-After`.

Hobbes runs its conversation tests before changing production. A failed job
does not publish the agent. Review its safe failure message, correct staging,
and ask for confirmation again before creating a different publish job.

<Warning>
  Never infer publishing approval from an earlier Playbook request. The user must
  confirm the exact staged version immediately before the publish job is queued.
</Warning>