Document EditingCAUTION

A framework for building agentic apps

The instruction file, verbatim from the audited commit — this is the text the model reads, and the surface the audit's instruction layer examines. Quoted here so you can judge it without cloning anything.

---
name: document-editing
description: >-
  How to create, read, update, and delete documents. Covers the document scripts,
  markdown content model, parent-child hierarchy, and position ordering.
---

# Document Editing

Documents are stored in the SQL database via Drizzle ORM. Each document has a
title, stable description, markdown content, optional parent (for nesting), and
a position for ordering. The description explains why the page exists and what
belongs there; it is not a changing synopsis of the current body.

When operating Content through a connected MCP server, call these actions
yourself; route work through `ask_app` only when delegating to Content's own
agent is the explicit point of the request. Reaching tools you can call
directly through `ask_app` adds a second interpretation of the request and
hides real errors.

## Scripts

Always use the dedicated scripts for document operations. Never use raw `db-exec` SQL.

In dev, call actions with `pnpm action <name>`; in production, call native
tools. Never use `curl`, raw HTTP requests, or `db-exec` with raw SQL for
document operations. `.env` is loaded automatically — never manually set
`DATABASE_URL` or other env vars.

### list-documents

List document metadata in a tree structure. This intentionally does not return full document bodies; call `get-document` for the one document you need to read.

```bash
pnpm action list-documents
pnpm action list-documents --format json
```

### search-documents

Search documents by title and content. Results include snippets, not full document bodies; call `get-document` before editing or summarizing a specific result.

```bash
pnpm action search-documents --query "meeting notes"
pnpm action search-documents --query "project plan" --format json
```

### get-document

Get a single document by ID with full content and description. MCP callers read
the complete values from `structuredContent`; the text preview may be shortened.

```bash
pnpm action get-document --id abc123
pnpm action get-document --id abc123 --format json
```

### create-document

Create a new document.

```bash
pnpm action create-document --title "Meeting Notes" --content "# Meeting Notes\n\nAttendees: ..."
pnpm action create-document --title "Sub Page" --parentId parent123
pnpm action create-document --title "My Page" --icon "📝"
pnpm action create-document --title "Research" --description "Evidence and source notes that support the current project"
pnpm action create-document --title "Placeholder 1" --spaceName "Foobar"
```

If the result has `creativeContextProjectionStatus: "pending"`, the Page is
already committed. Retry the same arguments with the returned `id` to repair
its Creative Context projection; do not create another Page.

When a user asks for a Page in an interactive Content conversation, creation is
not a complete handoff. After `create-document` succeeds, call `navigate` with
the returned document `id`, then call `view-screen` and compare its document ID
with the create result. Navigation is asynchronous: if `view-screen` still
reports the previous Page, repeat `navigate` and `view-screen` up to two more
times. Say the Page is open only after the IDs match. If they never match, say
the Page was created but navigation could not be verified, and provide the
stable Page link from the create result. Do not navigate for background, batch,
or API creation unless the caller explicitly asked to open the result.

When the user names a workspace ("in my Foobar workspace"), pass `spaceName`
(or a `spaceId` from `list-content-spaces`). A named workspace that does not
resolve is an error, never a silent fall back. With no `parentId`, `spaceId`,
or `spaceName` the page is created in the caller's Personal workspace, so read
the returned `spaceId` before telling the user where the page landed. The
Workspaces catalog is not a create target: its rows only list workspaces, and
`add-database-item` against it is rejected.

### update-document

Update a page's or database's metadata while preserving omitted fields. To
replace its guidance, pass only `id` and `description`; an empty string clears
the description. For a database, use its backing `documentId`, not its collection
`databaseId`. The saved description is returned in MCP `structuredContent`.
Agent responses contain metadata only; `get-document` returns the body.
This does not change the Markdown body; body edits use `edit-document`.

### import-content

Turn Markdown files the user hands over into new pages. Prefer it to
`create-document` whenever the source is a file: it takes the title from
frontmatter or the first heading, keeps the original file, uploads referenced
images, records "Imported from <file>" in History, and names everything that
did not come across.

```bash
pnpm action import-content --dryRun true --parentId abc123 --files '[{"name":"guide.md","text":"# Guide\n..."},{"name":"logo.png"}]'
pnpm action import-content --dryRun false --parentId abc123 --idempotencyKey guide-1 --files '[{"name":"guide.md","text":"..."},{"name":"logo.png","url":"https://..."}]'
```

Run the dry run first and tell the user each page's `status` and `notes`
before applying. Applying fails with `IMPORT_IMAGE_NOT_UPLOADED` until every
image named in `uploads` has a `url`; leave an image nobody can supply out of
`files`, and its references become visible placeholders on the page. Other
formats come back in `skipped` as not supported yet. Pass an
`idempotencyKey` on every apply, and reuse it only to retry the same files,
with the same image `url`s, into the same place. `IMPORT_INCOMPLETE` means
some pages landed before a failure: its `details` name the `importId` and
created page ids (with `documentIdsComplete: false`, more may exist), and the
same call again finishes the import. `IMPORT_PAGE_TRASHED` means the import
was undone or its pages trashed; restore them, or import with a new key.

`undo-content-import --importId <id>` moves the import's pages to Trash. It
needs only editor

CAUTIONgrade B · trust 89/100 Install with care. The audit found things worth knowing before you trust its output.

What the source does

Filesystem

none-observed

Network

none-observed

Shell

none-observed

Dependencies

pinned

Secrets in source

none-found

Findings (5)

.agents/skills/an

.agents/skills/content-product-development

.agents/skills/design-exploration

.agents/skills/turn-into-app

.agents/skills/visual-edit

Gates applied: no_behavioural_pass.

[![ModelsAtlas audit: Document Editing](https://modelsatlas.com/skills/builderio/document-editing/badge.svg)](https://modelsatlas.com/skills/builderio/document-editing/)

Not your listing, or something out of date? Claim or update your listing.