> ## 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.

# Example workflows

> Realistic requests to give a connected agent, with the Sidecars tools it will run and the one thing to watch for in each.

Each example is a request you can type to a connected agent, followed by the
tools it runs. Names, ids and dates are fictional. An agent with the
[Sidecars skills](/skills) installed runs these the careful way by default:
read before write, exact excerpts, human edits kept.

## Where the ids come from

[`list_conversations`](/reference/conversations#list_conversations) turns a
room or pod name into the `conversation_id` and `pod_id` the other tools
take: `{ "pod": "launch", "query": "checklist" }` finds the room. A name that
matches two pods is refused with the candidates rather than guessed, so an
agent never creates a document in the wrong room or in the person's library
by accident. Ids also arrive on
[`list_documents`](/reference/documents#list_documents) rows and as `parent`
on [`read_document`](/reference/documents#read_document); the full table is
in [IDs for other things](/reference/artifacts#ids-for-other-things).

## Summarise what we know about Acme into a doc in the launch room

> Pull together what we have on the Acme sandbox timeline and write it up as a
> document in the launch room.

1. [`list_conversations`](/reference/conversations#list_conversations) with
   `pod: "launch"` to resolve the room's `conversation_id`.
2. [`ask_knowledge`](/reference/knowledge#ask_knowledge) for a sourced answer,
   then [`search_knowledge`](/reference/knowledge#search_knowledge) for the
   passages worth quoting.
3. [`list_documents`](/reference/documents#list_documents) with
   `conversation_id` to check nothing similar exists.
4. [`create_document`](/reference/documents#create_document) with
   `conversation_id`, `content_markdown` and an `idempotency_key`. A card is
   posted to the room.

**Watch for:** the `document_id` values the knowledge tools return identify
ingested sources, not necessarily Sidecars documents. Pass only ids from
`list_documents` or a create to the document tools.

## Update the Risks section of the Q3 plan

> In the Q3 launch plan, update the Risks section: the vendor SDK now has a GA
> date of 1 October, and add the Northwind contract as a risk.

1. [`read_document`](/reference/documents#read_document); keep `version`.
2. [`edit_document`](/reference/documents#edit_document) with
   `mode: "replace_section"`, a `section_excerpt` quoted exactly from the read,
   and `expected_version`.
3. Read the result: `kept_blocks` means someone edited nearby while the agent
   wrote, and their text was kept.

**Watch for:** a stale excerpt is refused with `excerpt_not_found` and the
nearest candidates. The agent re-reads and quotes one exactly; a failed
replace is never turned into an append.

## Review this doc and leave comments, don't edit it

> Review the Q3 launch plan and leave comments where the dates don't line up
> with the kickoff notes. Don't change the text.

1. [`read_document`](/reference/documents#read_document) and
   [`read_comments`](/reference/comments#read_comments). The `role` in the
   comments result says whether commenting is allowed at all.
2. [`add_comment`](/reference/comments#add_comment) with an `anchor_excerpt`
   for each finding, so the thread attaches to the passage.
3. [`resolve_comment`](/reference/comments#resolve_comment) later, once a
   thread is addressed.

**Watch for:** a quote that appears more than once, or not at all, still
creates the thread, unanchored. Check `anchored` in the result.

## Rebuild the rollout page with December GA

> The rollout timeline page still says GA in November. Change it to 2 December
> and keep everything else.

1. [`read_page`](/reference/pages#read_page); keep `version`.
2. [`write_page`](/reference/pages#write_page) with the full new HTML and
   `expected_version`.

**Watch for:** if someone changed the page after the read, the write is
refused with `version_conflict`, the current version and a line diff. The
agent merges onto the current page and writes again. There is no force flag.

## Export the plan as a PDF for the board

> Give me the Q3 launch plan as a PDF.

1. [`export_document`](/reference/export#export_document) with
   `format: "pdf"`.
2. Fetch `download_url` within 15 minutes.

**Watch for:** the file captures `source_version`. After further edits, export
again; an unchanged version is served from cache.

## Put the doc I just copied into context

> Here's a doc from Sidecars. Use the latest saved version if you can reach it.
> *(pasted: a Copy for agent handoff)*

1. Read the `Artifact ID` line from the handoff.
2. [`read_document`](/reference/documents#read_document) with that id for the
   latest saved content and `version`.
3. If the handoff carries the `UNSAVED CHANGES` block, the snapshot holds
   edits the server never saw, and the server copy may have moved on too.
   Merge the snapshot's edits onto the live version and write with the
   live `version`; on `version_conflict`, read and merge again.

**Watch for:** without an MCP connection the agent works from the snapshot and
should say the original was not updated. The handoff format is described in
[IDs and URLs](/reference/artifacts#copy-for-agent).