list_documents
Lists the rich documents (ProseMirror tree) attached to the blocks of the project — a LIGHT index (title, block, modification date, archiving), without the content. cellId filters on ONE block; omitted, the index covers the whole project and excludes archived documents in every case. A document can be attached to SEVERAL blocks (anchor_document): without cellId, each entry then carries cellIds — ALL its blocks, from the oldest attachment to the most recent — and cellId is only the first of them. WITH cellId, the response is limited to the requested block and does NOT carry cellIds: computing it there would cost one query per document. The number of blocks of a document is read by listing WITHOUT cellId. Each entry carries empty: the document contains NOTHING (created but never filled). On BOTH branches — an index that counts documents without saying which are hollow lets empty shells be taken for documentation. A RAW FILE dropped as is (PDF, image, spreadsheet, docx) is NOT "empty": its content lives in the file, and the entry then carries attachment: { mimeType } (field ABSENT for a rich document); file name, size and upload date are read with get_document. No tool writes a raw file, and the text of a PDF is not readable by an agent. Documents live OUTSIDE SchemaData: no other tool that reads or serializes the schema (neither get_full_data, nor the diagrams, nor a version diff) sees them. WITHOUT cellId only, also returns orphanedAnchors: the document attachments that LOST their block (the block was deleted or detached) — {documentId, documentTitle, anchorId, rememberedCellId}. Field absent = no dead attachment visible, which does not mean "I did not look". And relocatedAnchors: among these dead attachments, those whose remembered block was FOUND again — moved to ANOTHER project that YOU can access — with the project and block name, to re-attach (anchor_document) or detach (unanchor_document) knowingly. Field absent = no accessible block found, which means neither "I did not look" nor "no access". Covers ONLY this class of orphaned object — not tasks without a block, not broken cross-project pointers. Each entry carries ageDays (days since the last edit: age alone says nothing about correctness). freshness appears ONLY if the subject of the document has DRIFTED — a change of substance (content block, name, description; not a drag, a collapse or a task) touched an attached block since its last edit, the first dating from more than 14 d (state: 'a-verifier') or more than 90 d ('perime'): { state, lagDays, evidence: { count, firstAt, lastAt } }. Field absent = no drift SEEN, which does not mean "guaranteed up to date": the log only exists since 2026-07-30, a bulk replacement (replace_schema, import, restore) leaves only an aggregate there with no attributable block, and archiving or setting the visibility of a document counts as an edit. freshnessUnchecked ({ reason, documents }), present only if there is a gap — unreadable log, log too active to be read in full, or more blocks than the reading cap: this number of documents could NOT be verified, so their lack of freshness says nothing. notUpdatedSinceDays only keeps the documents not edited for at least that many days (filter on ageDays, both branches); orphanedAnchors and relocatedAnchors are NOT filtered by it.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| query | No | WHOLE-PROJECT filter by TITLE OR by CONTENT (`search_text`, the text derived from the document — filtering is done IN THE SQL QUERY, not in memory, unlike `list_tasks.query`). Used to check that an equivalent document does not already exist before `create_document` — `anchor_document` attaches an existing result instead of creating a duplicate. IGNORED if `cellId` is provided: looking for a document to attach HERE assumes precisely that it is not attached yet (same rule as the `?q=`/`?cellId=` of the HTTP route). | |
| cellId | No | Only return the documents attached to THIS block. Omitted: the light index of the whole project. | |
| includeArchived | No | Include archived documents — relevant only with `cellId`: the project index (without `cellId`) excludes archived documents in every case, whatever this value. | |
| expectedProjectId | No | UUID of the project targeted by THIS call. ACTUALLY targets this project instead of the session project. Refused without changing anything if access is not granted. | |
| notUpdatedSinceDays | No | Only keep the documents NOT EDITED for at least N days (`ageDays` >= N) — the candidates for a review. Applies to BOTH branches (with or without `cellId`). In-memory filter on the date of the last edit; it says nothing about the correctness of a document (see `freshness` for drift). Omitted: no filter. |