---
name: workbench
description: Create, read, and update Workbench Markdown artifacts through private URLs.
---

# Workbench

Workbench is an agent-first Markdown artifact service. One private workspace URL gives an agent a persistent catalog for creating, finding, reading, and revising drafts; artifact pages render the result without app controls. A shared Workbench URL is both an invitation and an API discovery surface.

## When you receive a private workspace link

A workspace link looks like:

```text
https://workbench.foo/connect?token=<credential>
```

The complete URL already contains access to the persistent artifact catalog. Do not ask the human for a workspace token and do not require separate MCP setup.

1. GET the private URL with `Accept: application/json` to list remembered artifacts and read the machine-readable contract.
2. Match earlier work by title, slug, or ID. Add `artifact=<id-or-slug>` to the same URL and GET it before editing.
3. POST `action=create` to that exact same URL for a new artifact.
4. POST `action=update` with the latest `expected_version` to revise an existing artifact.
5. Give the returned `review_url` to the human instead of pasting the complete draft into chat.

Example create body:

```json
{
  "action": "create",
  "title": "Draft title",
  "markdown": "# Draft title\n\nComplete Markdown here.",
  "status": "draft",
  "by": "ai:grok",
  "change_summary": "Created the first draft"
}
```

Example update body:

```json
{
  "action": "update",
  "artifact_id": "artifact-id-or-slug",
  "expected_version": 4,
  "markdown": "# Revised draft\n\nComplete Markdown here.",
  "by": "ai:grok",
  "change_summary": "Revised the saved artifact"
}
```

The catalog is Workbench's memory. Use it instead of relying on chat history. Keep using the same private URL for later drafts and revisions.

## When you receive a Workbench link

A scoped link looks like:

```text
https://workbench.foo/share/<artifact-slug>?token=<token>
```

Treat the complete URL as a credential. The token grants read and edit access to that artifact only and expires automatically.

1. Fetch the shared URL. HTML contains complete instructions. Prefer `Accept: application/json` for machine-readable state and API links, or `Accept: text/markdown` for the current Markdown.
2. Take the `token` query parameter from the URL. Send it as `Authorization: Bearer <token>` on API requests.
3. POST to `_links.presence` before working so the human can see you joined.
4. GET `_links.state` immediately before editing.
5. POST to `_links.update` with the state response's `artifact.version` as `expected_version`.
6. If the update returns HTTP 409, read state again, reconsider the latest Markdown, and retry with the new version.
7. While collaborating, poll `_links.events`. Refresh state whenever an event arrives.

No browser automation or separate MCP setup is required for a scoped artifact link.

## Presence

```json
{
  "agent_id": "grok",
  "status": "active",
  "summary": "Reading the draft"
}
```

You may use `agentId` or the `X-Agent-Id` header instead of `agent_id`.

## Update

```json
{
  "expected_version": 4,
  "markdown": "# Revised draft\n\nComplete Markdown here.",
  "by": "ai:grok",
  "change_summary": "Tightened the opening"
}
```

At least one of `markdown`, `title`, or `status` is required. Allowed statuses are `draft`, `review`, and `approved`.

## Boundaries

- Workbench stores and reviews drafts; it does not publish them.
- There is no delete endpoint.
- Preserve Markdown as the canonical format.
- Do not ask the human for separate MCP setup when a private Workbench link was provided.

## Discovery

- Service description: `/.well-known/agent.json`
- Full instructions: `/agent-docs`
- Optional MCP transport for preconfigured clients: `/mcp`