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

# Pages

> Create, read and rewrite HTML page artifacts; writes require expected_version and return a diff on conflict.

Create, read and rewrite HTML page artifacts under a required version check.

| Tool                          | Scope             | Kind               |
| ----------------------------- | ----------------- | ------------------ |
| [`create_page`](#create-page) | `documents:write` | write              |
| [`read_page`](#read-page)     | `documents:read`  | read-only          |
| [`write_page`](#write-page)   | `documents:write` | write, destructive |

## create\_page

**Scope:** `documents:write` (step-up) · **Kind:** write · **Annotations:** `readOnlyHint: false`, `destructiveHint: false`, `idempotentHint: false`, `openWorldHint: false`

> Create an HTML page artifact — in a conversation (`conversation_id`, its
> card is posted to the room) or in the person's library with a `scope`:
> `user` (private, the default), `pod` (needs `pod_id`), or `org`. The HTML
> is stored verbatim; scripts are stripped when the page is viewed, and you
> are warned when that will happen. Returns {page_id, version} — the version
> write\_page requires.

### Parameters

Pass **either** `conversation_id` **or** `scope` (with `pod_id` when the
scope is `pod`), never both.

<ParamField body="title" type="string" required />

<ParamField body="html" type="string" required>
  The page's HTML, stored verbatim. Must be non-empty.
</ParamField>

<ParamField body="conversation_id" type="string">
  Create inside this conversation; a card is posted to the room.
</ParamField>

<ParamField body="scope" type="'user' | 'pod' | 'org'" default="user">
  Where the page lives when no `conversation_id` is given.
</ParamField>

<ParamField body="pod_id" type="string">
  Required with `scope: "pod"`.
</ParamField>

### Returns

<ResponseField name="page_id" type="string">The artifact id. Use it as `page_id` for `read_page` and `write_page`, and as `document_id` for comments and export.</ResponseField>

<ResponseField name="title" type="string" />

<ResponseField name="version" type="number">The version `write_page` must pass as `expected_version`.</ResponseField>

<ResponseField name="byte_size" type="number" />

<ResponseField name="warnings" type="string[]">
  `["script_stripped"]` when the HTML contains `<script>` elements, inline
  event handlers or `javascript:` URLs. They are stored but removed when the
  page is viewed, so its interactivity will not run.
</ResponseField>

Text: `Created page "<title>" (page_id: <id>, version <n>).` plus
`Note: its scripts will be stripped when viewed.` when applicable.

### Permissions and side effects

* Needs `documents:write`.
* The access gate runs inside the create transaction: with
  `conversation_id` you must be able to participate in the room; with
  `scope: "pod"` you must be a pod member.
* The caller becomes the owner. With `conversation_id` a card lands in the
  room; with a scope nothing is posted.

### Errors

| Text                                                                    | Cause                                |
| ----------------------------------------------------------------------- | ------------------------------------ |
| `Tool failed: Pass either \`conversation\_id\` or \`scope\`, not both\` | Both targets given                   |
| `Tool failed: \`pod\_id\` is required for scope pod\`                   | Pod scope without a pod              |
| `Tool failed: … Artifact not found`                                     | Conversation or pod you cannot reach |
| `That conversation is archived or gone, so nothing was created.`        | Archived room                        |

### Limitations

* No idempotency key on this tool; a retried create makes a second page.
* Pages are served with scripts stripped. Style with inline CSS.

### Example

**Request**

```json theme={null}
{
  "name": "create_page",
  "arguments": {
    "scope": "user",
    "title": "Acme rollout timeline",
    "html": "<h1>Acme rollout</h1><ol><li>Sandbox — September</li><li>Pilot — October</li><li>GA — November</li></ol>"
  }
}
```

**Response (structuredContent)**

```json theme={null}
{
  "page_id": "k55timeline0example000000000000000",
  "title": "Acme rollout timeline",
  "version": 1,
  "byte_size": 104,
  "warnings": []
}
```

## read\_page

**Scope:** `documents:read` (step-up) · **Kind:** read-only · **Annotations:** `readOnlyHint: true`, `destructiveHint: false`, `openWorldHint: false`

> Read a page's stored HTML source and its version — the token write\_page's
> expected\_version is checked against.

### Parameters

<ParamField body="page_id" type="string" required>
  The page's artifact id.
</ParamField>

### Returns

<ResponseField name="page_id" type="string" />

<ResponseField name="title" type="string" />

<ResponseField name="html" type="string">The stored source, scripts included (they are stripped only at view time).</ResponseField>
<ResponseField name="version" type="number">Pass as `expected_version` to `write_page`.</ResponseField>

Text: `# <title> (version <n>)` followed by the HTML.

### Permissions and side effects

* Needs `documents:read` and any role on the page. The access check and the
  source read happen in one transaction.
* Reads only. Recorded in the agent activity history.

### Errors

| Text                                                                 | Cause                                      |
| -------------------------------------------------------------------- | ------------------------------------------ |
| `That artifact is a document, not an HTML page — use read_document.` | The id names a document or table           |
| `That page has no content yet.`                                      | The page exists but has no stored source   |
| `Tool failed: … Artifact not found`                                  | Not visible, wrong workspace or no such id |

### Example

**Request**

```json theme={null}
{ "name": "read_page", "arguments": { "page_id": "k55timeline0example000000000000000" } }
```

**Response (structuredContent)**

```json theme={null}
{
  "page_id": "k55timeline0example000000000000000",
  "title": "Acme rollout timeline",
  "html": "<h1>Acme rollout</h1><ol><li>Sandbox — September</li><li>Pilot — October</li><li>GA — November</li></ol>",
  "version": 1
}
```

## write\_page

**Scope:** `documents:write` (step-up) · **Kind:** write, destructive · **Annotations:** `readOnlyHint: false`, `destructiveHint: true`, `idempotentHint: false`, `openWorldHint: false`

> Replace a page's HTML wholesale. `expected_version` is REQUIRED — the
> version read\_page (or create\_page) returned. If the page moved since your
> read, the write refuses with the current version and a line-level diff of
> what changed, so you can merge and retry; there is no force flag, by
> design. Scripts are stored but stripped at view.

### Parameters

<ParamField body="page_id" type="string" required />

<ParamField body="html" type="string" required>
  The complete new HTML. Must be non-empty.
</ParamField>

<ParamField body="expected_version" type="number" required>
  The version `read_page` or `create_page` returned. Must be a non-negative
  integer.
</ParamField>

### Returns

<ResponseField name="page_id" type="string" />

<ResponseField name="new_version" type="number" />

<ResponseField name="byte_size" type="number" />

<ResponseField name="warnings" type="string[]">`["script_stripped"]` when the HTML carries scripts.</ResponseField>

Text: `Wrote the page; it is now at version <n> (<bytes> bytes).`

### Permissions and side effects

* Needs `documents:write` and the `editor` or `owner` role. The role is
  re-checked inside the write transaction.
* Replaces the whole page. The previous source is kept as a checkpoint.
* Attributed to you via the host.

### Errors

| `error`            | Text (abridged)                                                                                                                                                              | What to do                                                                      |
| ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- |
| —                  | `Tool failed: \`expected\_version\` must be a non-negative integer\`                                                                                                         | Pass the integer from your read                                                 |
| —                  | `That artifact is a document, not an HTML page — use edit_document.`                                                                                                         | Use `edit_document`                                                             |
| —                  | `That artifact is a table, not an HTML page. …`                                                                                                                              | Tables are not editable                                                         |
| `version_conflict` | `The page moved from version A to B since you read it. What changed:\n<diff>\nMerge your changes onto the current page (read_page) and write again with expected_version B.` | Merge and retry; `diff_excerpt` and `changed_range` are included when available |
| —                  | `Tool failed: … This document is read-only for you`                                                                                                                          | You are a viewer                                                                |
| —                  | `Tool failed: … You can comment on this document but not edit it`                                                                                                            | You are a commenter                                                             |
| —                  | `Tool failed: … This document is archived`                                                                                                                                   | Archived                                                                        |
| —                  | `Tool failed: … Artifact not found`                                                                                                                                          | Not visible, wrong workspace or no such id                                      |

There is deliberately **no** way to overwrite a newer version without reading
it first.

### Example

**Request**

```json theme={null}
{
  "name": "write_page",
  "arguments": {
    "page_id": "k55timeline0example000000000000000",
    "expected_version": 1,
    "html": "<h1>Acme rollout</h1><ol><li>Sandbox — September</li><li>Pilot — October</li><li>GA — December</li></ol>"
  }
}
```

**Response (structuredContent)**

```json theme={null}
{
  "page_id": "k55timeline0example000000000000000",
  "new_version": 2,
  "byte_size": 103,
  "warnings": []
}
```

**Conflict response (structuredContent)**

```json theme={null}
{
  "error": "version_conflict",
  "expected_version": 1,
  "current_version": 3,
  "diff_excerpt": "-<li>GA — November</li>\n+<li>GA — 2 December</li>"
}
```