CollHub

Replace text in a document, three forms. TEXT form: old_text → new_text, exactly one match required (section_id or search_from narrows the search; replace_all replaces every match). RANGE form (old_text OMITTED): when you already hold an exact span, pass from/to + expect_revision copied from the locate_regex result — never re-type the span as old_text (one mistyped character fails the edit); a stale expect_revision rejects the edit instead of splicing at shifted offsets; from == to inserts. SECTION form (old_text omitted, section_id alone): replaces the WHOLE section, its span resolved live (n…

Keyword search in one collection that returns the matching passages with their text: the documents that match, best first, the top ones with their best passages and the enclosing section (breadcrumb, span, durable uri). It matches by keywords only: use search_documents for a question or a topic whose wording may differ from the text. The query reads the text, the name and the short metadata values of a document. A result that matched in its passages reports `matches`, the number of passages the search found for it (at most 10); a result without `matches` matched by its name or short metadata v…

Documents in the same collection that resemble a given one, most similar first — takes a document instead of a query, so it reaches near-duplicates, earlier/later versions and same-subject neighbours in other words, which keyword search cannot. The tail is autocut where similarity drops, generously on a single-subject corpus: treat the ORDER as the signal, not list membership. Scores are not comparable across source documents. To group a collection, call per document and read each list on its own: a pair that ranks each other highly (reciprocal rank) is a weak secondary signal at most, not wha…

Get full details of a collection including permissions and configuration. Its `instructions`, when set, say how documents there are written and handled: follow them for every document of the collection.

Get the version history of a document.

Get metadata for a document, or for MANY in one call (document_ids, max 200 — one list read, every id answered in the order asked; a missing or unreadable one is an {error} entry, so an absence never needs a second call). Returns label_ids (the raw label id array); use include to request extra fields — status_object (the current workflow step) is null unless included. The batch form serves each document's compact list shape (published version, parent_id, status_id, label_ids, metadata, plus what include adds): where it lives, whether it is open, who holds it. type_instructions, when the single…

Extracted passages in document order — the only text of a binary (PDF, DOCX, …), a passage index for markdown. offset/limit count PASSAGES; query keeps only the matching passages, still in document order and not ranked (find ranks documents across a collection); page restricts to one source page label (a workbook's sheet position); seq_num reads the exact passage a find result cited. section_id reads ONE SECTION of a binary — a PDF whose embedded outline gave it sections, or a workbook, one section per sheet (get_document_toc reports frame "extracted" and each section's page): the passages ins…

Document outline: the live section tree — durable section ids (deep-linkable as #s{id}), heading, level, from/to spans, occurrence (> 1 = duplicate heading). No content is read; the ids feed read_document, edit_document, add_comment, add_bookmark, and are the id source for cross-reference links (/documents/{id}#s{section_id} — see the guide's "Relationships and cross-references"). `frame` says what the spans count into: "native" (the markdown) or "extracted" — a PDF whose embedded outline gave it sections, each with its `page` (1-based) and `boundary: "page"` when its heading was not located i…

Read an agent plan, or the part of it you hold: the open steps of node's subtree as a tree, with ids. The status of a step that contains steps is computed from them (never a stale stored one); a step handed to another agent shows as one line with its executor and last activity. Read on a step, it starts with the step's brief, your starting context. Then: ready (pending, with every predecessor of it and of the steps containing it done), running, blocked with its question and the update_plan {id, answer} that answers it (or its answer), and finished steps counted — the steps that contain nothing…

First project intake: the visible markdown brief plus document counters, to size the get_project_graph read. Counts cover every readable document in non-deleted branches (root, containers, hidden anchors, archived, unclassified); Tasks and Trackers are counted separately, by_kind/by_type include both. Returns source/version, truncation and next_offset (code points); possibly_depth_limited means counts may be lower bounds. No bodies, no edges. latest_document_modified_at is NOT a graph-change watermark: never pass it as get_project_graph.since, which wants the newest modified_at already seen fr…

Read a page of the project graph: the subtree's documents as nodes (kind and lifecycle state resolved) plus typed, directional edges. Default limit 500, max 1000: follow next_after with identical filters until null (edges may target nodes on other pages; truncated stays true on the last page when after > 0). Each node is compact — id, name, kind, state (display label), status (the step name set_document_status takes), group, type_name, parent_id, depth, modified_at, labels, metadata, locker, outgoing edges; empty fields omitted, metadata.snippet only with snippet:true. `fields` keeps only what…

Get the full definition of a workflow: all steps (states), transitions (directed edges between steps) and accepted_types — the document types it applies to, as [{type_id, type_name}]. Use to understand the complete lifecycle graph before transitioning a document.

Insert one or more records into an existing data source.

The user's private bookmarks on documents and sections. Section bookmarks carry a durable target_uri (collhub://documents/{id}#s{section_id}); section_gone: true = the section was edited away, inaccessible: true = the target is no longer readable.

List available collections. Use this first to discover collection IDs before searching or browsing documents.

List comments on one document, or on MANY in one call (document_ids, max 200 — every id is answered, so an empty list is a fact; get_project_graph comment_counts says which nodes have any). Filter by source and resolved. Comments routinely correct the document they sit on: read them before acting on a body. Two system-maintained stamps per comment: section_id (the enclosing section) and location_state — "exact": location.from/to sit on the quoted text; "approximate": the anchor was re-homed after edits — treat the offsets as a neighbourhood and re-locate the quote before acting on them.

List available data sources. Returns source names and schemas.

List available document types that can be created — the complete list, never a page. Call this before create_document to discover valid types. A type's `instructions` (own or inherited from its parent type) say how its documents are written — what the body must and must not contain: FOLLOW them when you create or edit a document of that type. `convertible_to` lists the mime types a document of the type can be turned into with convert_document. A format missing from THIS list is not unavailable: the list holds the types you can author, and DOCX, for one, is a type documents are converted into a…

List the workflows that can be applied to a document, based on its document type. Returns each workflow with its steps. To put the document into a workflow, call set_document_status with the id of that workflow's is_initial step.

List the contents of a folder or project, folders and projects first (an is_folder item can be listed further by its id). For navigating INSIDE a hierarchical collection — a flat collection, or a hierarchical collection's top level, is listed with search_documents(collection_id). depth: 1 (default) immediate children, N levels, 0 the entire subtree; when depth != 1 each item carries parent_id. filters narrow by type_id, name, labels or metadata; limit 0 (default) is unbounded.

List the configured CollHub instances. Pass an instance name as the `instance` argument of any tool to target it; omit it to use the default. There is no persistent "current instance" — routing is per call, so parallel sessions never interfere.

List labels — the complete list, never a page — to find ids for update_labels or check existence before create_label. Empty fields are left out; the document_deny_* ACL lists only with include_deny.

Metadata fields and their types. Without type_id: the collection-level fields (the filter fields for search_documents). With type_id: the EFFECTIVE schema of that document type in the collection — collection fields merged with the type's own (a Task's assignee, due_date, priority, estimate). When WRITING metadata use each field's `metadata_key`, NOT its display name: type-scoped fields are prefixed (name "assignee" → "type:assignee"); `scope` says which.

The valid transitions from a document's current workflow step — one hop, each with the step it leads to; pass a returned step_id to set_document_status. Empty when the document is in no workflow or on a terminal step. For the whole lifecycle graph call get_workflow; to reach a step several hops away give set_document_status the destination — it resolves the route.

The project ontology: the kinds apply_project accepts (group, description, lifecycle policy), the configured methodologies with their guidance, and contexts. SVG icons only with include_icons.

Users and groups — the directory behind principal-typed fields such as a Task's `assignee`, which accept a name on write but store a numeric id. `query` (case-insensitive substring of username, first/last name, email or group name) turns "luca" into the id; `ids` labels ids read back from a document. One id space for both. Only users, teams and dynamic teams can hold an assignment. Capped per kind at `limit` (default 100, max 500): truncated: true + truncated_kinds says a kind has more.

The project templates create_project can scaffold from — each a brief skeleton + anchor documents, stamping its like-named methodology on the project.

List projects across all collections (most recently modified first) as {count, projects}; truncated: true says more than limit match. A project is a special folder that anchors AI project workflows. Take one in with get_project_brief (brief + counts, sizes the graph read) then get_project_graph; list_folder walks its file tree, set_document_status advances its workflow.

List available relationship types — the complete list, never a page. Call this before create_relationship to discover valid types and their directional labels.

Description is built at runtime.

Messages in a thread, chronological: role, content, attachments, tool calls. Paged — the result is {thread_id, messages, next}, and `next` is the call for the following page whenever one exists (null when the thread ends here); limit 0 returns the whole thread in one call. Never treat a full page as the end of the thread.

List AI chat threads. Returns id, name, type, status, and timestamps.

List all workflow definitions with their steps — the complete list, never a page; enough to find a workflow's is_initial step. get_workflow gives the transitions, list_eligible_workflows the workflows applicable to a document.

Regex matches in a document's markdown: from/to (code points), a snippet per match, and content_revision. TO REPLACE A MATCH pass its from/to plus content_revision (as expect_revision) to edit_document with old_text OMITTED — nothing re-typed, a stale range rejected. For targets inside prose, ::: blocks, table cells; for section-level targets get_document_toc already has the heading text and span (fall back to "^#+ .*$" here only when the TOC is empty). Default flags "im" (case-insensitive, ^/$ per line). Generated PDF types are searched in their markdown draft; a binary with no textual draft …

Log in to the instance in the browser — only when the user asks. Plain: resumes the stored session, opens a browser only when there is none, and keeps the account this host was logged in as — when the browser is signed in as someone else, the login page asks the user which account to keep. `switch_user`, the only way to change account: opens the browser on the login form (signing the browser out first), so a different account can be entered even when the browser is already signed in; the previous session ends once the new login has landed, so a switch that fails leaves the user logged in as be…

Sign out of the instance — only when the user asks. Ends this host's session on the backend and forgets it here; the user's other sessions and the app stay signed in. The next call to that instance opens a browser login for the same account (another one is refused); `login` with `switch_user` changes account.

Stamp status markers (✅ 🚧 ⬜ ⏸️) on headings addressed by NUMBER ("4.2") or exact TITLE; "" clears one; no marks = read back the heading map. IDEMPOTENT: an existing marker is REPLACED, never stacked — a regex character class cannot recognise these markers (⏸️ is two code points, 🚧 a surrogate pair), which is why replace_in_document silently appends a second one. Markers sit inside the title after any heading number, so renumber_document still parses it. Table rows, fenced code and headings outside `levels` are never touched; an unmatched key is reported, an ambiguous one written nowhere. Use…

Move a document to another folder, project or collection: parent_id for a container (folder or project root — the document lands inside it), collection_id alone for that collection's root, both for a folder elsewhere. Content, versions, comments, labels, workflow status and relationships travel with it; edges to nodes left behind become cross-project links (visible via list_relationships, in neither graph). This is how a node moves between projects — apply_project cannot pull one in or push one out. Folders and projects cannot move across collections. 423 if checked out by someone else.

Query rows from a data source. Supports PostgREST-style filters, column selection, ordering, and limits. A :::chart / :::table / :::template block binds the same query as a path, `name?select=…&col=op.value&order=…&limit=N`, built from these arguments.

Read a document's native text: the whole document, a [from, from+length) code-point range, or one section (section_id, resolved server-side to its CURRENT span; a gone section lands on its absorbing/parent section with a warning; a stale stored span is relocated by its heading line, or the whole document is served with a warning — never the stale span). Output is bounded by max_chars: two blocks, the text then one JSON line {stream, version, from, to, total_chars, truncated, next, etag, content_revision, warnings} — when truncated is true call `next` verbatim, never treat a truncated read as t…

Read the native text of MANY documents in one call — the batch form of read_document for a bulk intake (every card of a project, a folder of notes): document_ids, at most 200, duplicates collapsed. max_chars (default 20,000, maximum 100,000) bounds EACH document, from its start. One JSON entry per document, in the order asked: {document_id, name, stream, version, content, from, to, total_chars, truncated, next} — when truncated is true, next is the read_document call for the rest of that document: call it verbatim, never treat the head as the whole. version is null for your own unpublished dra…

Read a named stream from a document as text. System streams are "draft" (Markdown), "data" (JSON), "style" (CSS: the theme binding and the document's own rules) and "theme" (CSS: the private slot overlay); an application stream carries a typed extension (props.json, notes.md). A stream whose type is not textual errors instead of dumping bytes. The text comes with a JSON line {etag, content_revision}: write_stream over this content names the etag.

Remove one of the user's bookmarks (id from list_bookmarks).

Rename a document by changing its `name` field. File-named documents keep their extension ("Report Q3.pdf"); typed documents keep plain titles (see the guide's "Creating documents"). Does not change collection, content, or version. To move across collections or folders, use move_document.

Re-sequence a document's already-numbered headings with Word-style multilevel numbers (1, 1.1, 1.1.1) from nesting + position, and remap the inline §refs using the same scheme so they stop drifting. By default only headings ALREADY carrying a number are re-sequenced — the title and preamble headings ("## Related") stay clean. Do NOT use it to ADD numbers to a clean document: numbering is moving to render-time CSS, and baking numbers in fights that (skip_unnumbered:false is a deliberate opt-out). Preview-first (heading map + diff); on commit locks if needed and leaves the document locked.

Bulk regex find/replace across a document — the sed/awk-style tool. Each rule: `pattern` (JS regex) + `replacement` with $1/$<name> captures and COMPUTED `${expr}` values, where a capture resolves to its NUMERIC value (pattern "§(?<n>\\d+)" + replacement "§${n+3}" shifts every section number by 3 in ONE rule); an optional `where` guard (boolean, same language) skips matches. Rules apply in one cascade-safe left-to-right pass (single_pass). ^ and $ are string-anchored without the "m" flag; case-sensitive without "i". Preview-first (diff + per-rule counts); on commit locks if needed, splices, le…

Toggle the resolved status of a comment.

Finds the documents of one collection that match a query, by keywords and by meaning, and filters them by fields; collection_id=0 lists/filters across ALL collections (system fields only, no query). Use it to learn WHICH documents are relevant; use find to read the matching passages. The query reads the text, the name and the short metadata values of a document. Structured filters need field names from list_metadata_fields; cursor pages. Each query result reports WHERE it matched: by default the distinct sections that hold its matches (breadcrumb + durable #s{id}, usable as read_document secti…

Send a message to a thread and wait for the turn that answers it (no thread_id = a new "chat" thread). The result names thread_id, message_id, turn_id and the turn's outcome, with the messages of that turn. Past the timeout it is no error: status "running" (its turn goes on) or "waiting" (no turn took it yet) with the ids — read the answer later with list_thread_messages, never send the message again. Edits follow the thread's edit mode: "auto" applies and publishes them; "manual" writes them into the locked draft and withholds the publish for a human to approve — written, not proposed; only a…

Change a document's workflow status — one document, or MANY in one call. (1) ENTER: the is_initial step_id from list_eligible_workflows; (2) TRANSITION: a step_id from list_next_steps; (3) EXIT: step_id=null (from a terminal step only); (4) BATCH: documents: [{document_id, step}] with step an id, a step NAME or label ("completed", "In Review") or null — names where each document must END UP and walks the route (several hops = one call); items succeed or fail on their own and each result reports path, the steps walked. Every result carries effects — what the move did to RELATED documents (a tra…

Unlock a document after editing. Call this when done writing to release the lock. Unlocking PUBLISHES: it mints the new version and re-extracts the section tree, so a stale TOC (spans_fresh: false) is refreshed by this call — there is no other refresh. It publishes only a lock this server took whose draft holds only writes made here: a draft that is a person's (their editor's lock), or that took a write made elsewhere, is refused — the person publishes it. After a refused write here, it publishes once a write lands again.

Patch a label: rename, recolour, rewrite the description, or change its behaviour — the only way to repair a label after creation (create_label errors on an existing path and puts every attribute on the leaf, so an auto-created parent is fixed only here: e.g. max_child_card:1 to make an existing group exclusive). `name` renames IN PLACE, descendants included — the path is rebuilt, so anything holding the old path by string goes stale (ids do not). Omitted fields are left alone.

Add or remove labels on a document. Use list_labels to discover available label IDs. Use get_document_info with include=["labels"] to see current labels.

Set metadata field values on a document — collection fields plus the document type's own (a Task's assignee, due_date, priority; list_metadata_fields with the type_id shows them). Keys are each field's metadata_key; bare type-field names are auto-prefixed to `type:`. Partial merge: only the given fields change; null removes one. `expected` names, for every key you change, the value you read (get_document_info; null if it had none): a key someone changed since is refused with its current value — read it again before deciding.

Create or change an agent plan — for agents; people keep projects and tasks. A plan is a todo list that lasts: steps can contain steps, come `after` other steps, and go to another agent with `executor`. Change only the steps under the node you hold. Never give a status to a step that contains steps. Worth it when steps outlive a turn, more than one agent works, or the order matters. Without node and with goal: creates the plan in your personal system/plans/ (first line of the goal = its name) and returns its id; get_plan(id) resumes it from any session. node = the plan, or the step handed to y…

Update records in a data source matching the given filters.

Upload a local file — as a NEW document, or as the next version of an existing one. The bytes go from disk to the server, never through the conversation: use it for any binary or large file. New: collection_id, or parent_id alone — a folder or project in any collection, which the document is created inside (no move needed). name defaults to the file name; keep the extension, it picks the type unless `type` names one. document_id instead writes the file as that document's new content: same id, links and history; name, type and place stay (rename_document, move_document change them). With docume…

Who the server is logged in as on the instance: `user` (email, name) first, then the session (the host profile it belongs to) and the account (id, privileges, memberships). Answer a "who am I logged in as" question with the email.

Write markdown to an existing document: the whole content, or from a code-point position onward — `from` REPLACES everything from that position to the end (to append, pass the document's length). Pass the etag your read_document returned: the write lands only on the content you read, and a refusal (412) means it changed since — re-read and redo the change, never resend. Locks if needed, commits, leaves the document locked; the result carries the etag a next write names. Generated PDF types write to the draft stream. For a change inside existing content prefer edit_document. Every mention of an…

Write the whole content of a named stream on a document; the write commits by itself. Over an existing stream pass the etag your read_stream returned (a refusal means it changed: re-read, never resend); without etag the write only creates a stream that does not exist yet. Writing "main", or "draft" of a type that generates from Markdown, locks the document if needed and leaves it locked; another stream of an unlocked document is written without a lock. The name declares the type: a system stream ("draft", "data", "style", "theme") or an application stream with a typed extension (props.json, no…