---
title: Docs
description: Docs agents write and keep for the owner, such as proposals, briefs, checklists and recurring reports. 5 tools.
group: docs
tools: [docs.list, docs.read, docs.write, docs.edit, docs.answer]
source: [packages/agents/src/tools/docs.ts]
generated: true
---
> Roadstar docs for agents. Every page, as markdown: https://docs.roadstar.app/llms.txt
A doc is a page an agent writes and keeps for the owner: a proposal, a brief, a checklist, a monthly report. Its text is one MDX file: Markdown plus a few components for callouts, figures, columns and charts. The owner reads it under Docs in Pro and can leave notes on it.
- `write` sets a doc's whole text: a new doc, the first draft of one the owner asked for, or a full rewrite such as a routine's monthly report. Writing a new doc needs no yes; rewriting one that's there is checked.
- `edit` changes parts: each edit finds words the doc has now, once, and replaces them. All edits apply or none do.
- `read` gives the text, the brief it was asked with, and the owner's open notes. Answer a note by editing, or with `answer` when you keep the text as it is.
Write a doc when the work is long, structured or worth keeping. Otherwise answer in a message.
## How to use it
What `find_tools` sends with these tools, word for word:
> Docs you write for the owner and keep: SOPs and briefs, write-ups of your work, reports that recur. Write a doc when the work is long, structured or worth keeping; answer in a message otherwise. A doc you were asked to write already exists: write into its docId. A doc's text is MDX: Markdown (## headings, lists, tables, **bold**, links) plus …, , …, and a chart as holding one ```vega-lite JSON block with its data inline. Link people and things you read as roadstar links: [Juniper Dental](roadstar:contact/); kinds: contact, email, file, invoice, bill, agent, doc, page, table, project. A report or tracker reads like a dashboard: one line on as of when and from what; a MetricGrid of the three or four figures that matter; a short table of what needs the owner; then one table of every item, a row each, in short cells: dates like Nov 6, amounts right-aligned (|---:|), a status of a word or two, each row's name linked to its source. A recurring one opens with what moved since the last. What you couldn't check goes in one line at the end; your own working notes stay out of it.
## Tools
| Tool | What it does | Owner's yes |
| --- | --- | --- |
| [docs.list](#list) | Docs, newest first | No |
| [docs.read](#read) | A doc's current text, the brief it was asked with, what to read first, and the notes the owner sent you on it | No |
| [docs.write](#write) | Write a doc's whole text: a new doc, the first draft of one you were asked for, or a full rewrite such as a routine's. | Depends |
| [docs.edit](#edit) | Change parts of a doc you've read: each find is words it has now, once. All edits apply together or none; the rest stays as it is. | Checked |
| [docs.answer](#answer) | Answer a note without changing the doc: kept, with why; or done, for a note that asked you to do something else, with what you did | Checked |
## list
`docs.list` · Docs, newest first.
**Owner's yes:** No. Nothing of the owner's changes.
| Input | Type | Required | Limits |
| --- | --- | --- | --- |
| `projectId` | id | no | |
| `title` | text | no | up to 300 characters |
| `offset` | whole number | no | 0 or more |
Returns:
```ts
{
items: {
id: string;
title: string;
type: "question" | "thesis" | "doc";
projectId: string;
projectName: string;
status: "draft" | "published" | "archived";
generationStatus: "queued" | "running" | "failed" | "completed" | null;
updatedAt: string;
}[];
nextOffset: number | null;
}
```
## read
`docs.read` · A doc's current text, the brief it was asked with, what to read first, and the notes the owner sent you on it.
**Owner's yes:** No. Nothing of the owner's changes.
| Input | Type | Required | Limits |
| --- | --- | --- | --- |
| `docId` | id | yes | |
Returns:
```ts
{
id: string;
title: string;
projectId: string | null;
brief: string | null;
readFirst: {
kind: "page" | "table" | "doc" | "contact";
id: string;
label: string;
}[];
updates: "once" | "weekly" | "monthly" | "quarterly";
text: string | null;
notes: {
noteId: string;
on: string;
note: string | null;
}[];
}
```
## write
`docs.write` · Write a doc's whole text: a new doc, the first draft of one you were asked for, or a full rewrite such as a routine's.
**Owner's yes:** Depends on the input: checked when it changes what's there, not when it makes something new.\
**Your work:** listed on Home.
| Input | Type | Required | What it is | Limits |
| --- | --- | --- | --- | --- |
| `docId` | id | no | | |
| `projectId` | id | no | | |
| `title` | text | yes | | 1–300 characters |
| `text` | text | yes | MDX, as the docs how-to says | 1–100,000 characters |
| `lines` | list of text | no | what changed, one plain sentence each, for the owner | up to 20 items, each 1–300 characters |
Returns:
```ts
{
pageId: string;
versionId: string;
version: number;
}
```
## edit
`docs.edit` · Change parts of a doc you've read: each find is words it has now, once. All edits apply together or none; the rest stays as it is.
**Owner's yes:** Checked. It changes what's there.\
**Your work:** listed on Home.
| Input | Type | Required | What it is | Limits |
| --- | --- | --- | --- | --- |
| `docId` | id | yes | | |
| `edits` | list of `{ find, replace }` | yes | | 1–30 items |
| `edits[].find` | text | yes | | 1–20,000 characters |
| `edits[].replace` | text | yes | | up to 20,000 characters |
| `lines` | list of text | no | what changed, one plain sentence each, for the owner | up to 20 items, each 1–300 characters |
| `answers` | list of `{ noteId, outcome, text }` | no | When the owner sent notes, answer every one: changed with what you did, or kept with why | up to 40 items |
| `answers[].noteId` | id | yes | | |
| `answers[].outcome` | one of `changed`, `kept` | yes | | |
| `answers[].text` | text | yes | | 1–1,000 characters |
Returns:
```ts
{
pageId: string;
versionId: string;
version: number;
}
```
## answer
`docs.answer` · Answer a note without changing the doc: kept, with why; or done, for a note that asked you to do something else, with what you did.
**Owner's yes:** Checked. It changes what's there.\
**Your work:** listed on Home.
| Input | Type | Required | Limits |
| --- | --- | --- | --- |
| `docId` | id | yes | |
| `noteId` | id | yes | |
| `outcome` | one of `kept`, `done` | yes | |
| `text` | text | yes | 1–1,000 characters |
Returns:
```ts
{
commentId: string;
}
```