MCP Tools — Company Brain (Knowledge)

Company Brain is your workspace's living knowledge system. These MCP tools let you search, read, and write every entity in the Brain — meetings, notes, tasks, decisions, topics, people, org units, glossary terms, playbooks, and versioned documents — all scoped to your tenant. They also expose a profile surface for reading and updating the authenticated user's own account fields.

For connection and authentication details, see MCP Overview.

Scopes#

Profile#

profile_get#

Return the authenticated user's name, email, and the linked client's public company fields.

• Auth: profile:read

Tool call example:

{ "name": "profile_get", "arguments": {} }

Response:

{
  "user": { "id": 42, "name": "Ada Lovelace", "email": "ada@example.com" },
  "client": {
    "id": 7,
    "company": "Example Co",
    "phone": "+1 555-0100",
    "website": "https://example.com",
    "address": "123 Main St",
    "emailPrefix": "example"
  }
}

profile_update#

Update the authenticated user's name / email and / or the linked client's company fields. All fields are optional; only provided fields are written. Email must be unique across all users.

• Auth: profile:write

Tool call example:

{
  "name": "profile_update",
  "arguments": { "name": "Ada Lovelace", "company": "Example Co" }
}

Response:

{ "success": true }

Errors:

Search & Dashboard#

brain_search#

Hybrid lexical + semantic search across the entire workspace: notes, meetings, CRM companies / contacts / deals, tasks, relationships, and pages. Returns ranked hits with snippets and absolute citation URLs.

• Auth: brain:read

Tool call example:

{
  "name": "brain_search",
  "arguments": { "query": "Q3 OKR kickoff", "types": ["meeting", "note"], "limit": 5 }
}

Response:

{
  "hits": [
    {
      "type": "meeting",
      "id": 101,
      "title": "Q3 OKR Kickoff",
      "snippet": "…discussed revenue targets for Q3…",
      "score": 0.94,
      "url": "https://simplerdevelopment.com/portal/brain/communications/101"
    }
  ]
}

brain_dashboard_summary#

Return the command-center snapshot: meetings needing review, overdue / blocked / upcoming tasks, stale prospects, priority relationships, recent meetings, and entity counts (including decisionsCount and topicsCount).

• Auth: brain:read
• No input fields.

Tool call example:

{ "name": "brain_dashboard_summary", "arguments": {} }

Response:

{
  "counts": {
    "pendingMeetings": 3,
    "openTasks": 12,
    "decisionsCount": 47,
    "topicsCount": 28
  },
  "needsReviewMeetings": [...],
  "overdueTasksCount": 2
}

Meetings#

brain_list_meetings#

List meetings, optionally filtered by status. Returns full rows including transcripts (MCP callers receive transcripts by default).

• Auth: brain:read

brain_get_meeting#

Get a meeting with participants, transcript, AI summary, and the linked CRM record (if any).

• Auth: brain:read

Errors: Meeting not found.

brain_create_meeting#

Create a meeting from pasted transcript text. Optionally link to a CRM company or deal at creation time.

• Auth: brain:write

Tool call example:

{
  "name": "brain_create_meeting",
  "arguments": {
    "transcript": "Ada: Let's review the pipeline...",
    "title": "Pipeline Review",
    "meetingDate": "2026-06-04T14:00:00Z",
    "companyId": 55
  }
}

Response (slim — transcript is never echoed back):

{
  "id": 201,
  "title": "Pipeline Review",
  "status": "processing",
  "source": "paste",
  "sourceRef": null,
  "createdAt": "2026-06-04T14:01:00.000Z"
}

Errors: Company Brain is not enabled for this workspace. | Error if companyId and dealId are both supplied.

brain_link_meeting#

Set or clear a meeting's CRM link (company or deal). Pass null to clear.

• Auth: brain:write

Tasks#

brain_list_tasks#

List Brain tasks with optional filters.

• Auth: brain:read

brain_get_task#

Fetch a single Brain task by id.

• Auth: brain:read

brain_create_task#

Create a Brain task directly (bypasses the review queue).

• Auth: brain:write

brain_propose_task#

Stage a suggested task in the AI review queue for a human to approve, edit, or reject. Prefer this over brain_create_task when acting on AI analysis.

• Auth: brain:write

brain_update_task#

Patch task fields (title, description, status, priority, due date, owner, blocked reason).

• Auth: brain:write

AI Review Queue#

brain_list_review_items#

List items in the AI proposal queue.

• Auth: brain:read

brain_get_review_item#

Get a single AI proposal by id, including the full proposed payload.

• Auth: brain:read

brain_approve_review_item#

Approve a pending AI proposal. For task proposals this materializes a brain task row. Optionally patch the payload before approving. Audited.

• Auth: brain:approve

brain_reject_review_item#

Reject a pending AI proposal. Audited.

• Auth: brain:approve

brain_review_items_suggest_reviewer#

Score active Brain people for who should review an AI proposal based on expertise, org-unit context, past approval history, and current workload. Persists the top candidate (score ≥ 3) on the review item. Audited.

• Auth: brain:write

Response:

{
  "reviewItemId": 88,
  "suggestedPersonId": 14,
  "score": 4,
  "reason": "Matched 2 expertise tags; low workload"
}

brain_review_items_list_for_reviewer#

List review items where suggested_reviewer_person_id matches the given brain_people.id. Capped at 50 rows.

• Auth: brain:read

Relationships#

brain_list_relationships#

List relationship overlays with optional filters.

• Auth: brain:read

brain_get_relationship#

Get a relationship overlay by id with linked CRM record, contacts, recent meetings, and open tasks.

• Auth: brain:read

brain_create_relationship#

Start tracking a CRM company or deal as a Brain relationship. Idempotent.

• Auth: brain:write

brain_update_relationship#

Edit a Brain relationship overlay. Audited.

• Auth: brain:approve

Knowledge Notes#

brain_list_notes#

List / search knowledge notes. Slim by default (400-char body preview + length). Use sourceUrl / sourceUrlStartsWith to deduplicate before crawling. Paginated via { items, total, limit, offset }.

• Auth: brain:read

brain_get_note#

Fetch a single note with its full body.

• Auth: brain:read

brain_create_note#

Save a knowledge note. Primary write surface for AI-driven web ingestion — pass source: "crawl" and sourceUrl when ingesting from the web. Body is markdown, capped at 50 KB.

• Auth: brain:write

brain_upsert_note_by_url#

Idempotent crawl primitive: update an existing note for sourceUrl if found, otherwise create it. Returns { note, created: boolean }. Prefer this over brain_create_note when ingesting web pages.

• Auth: brain:write

brain_update_note#

Patch fields on an existing note. Pass null for nullable fields to clear them.

• Auth: brain:write

brain_delete_note#

Two-stage delete. Default (force: false) soft-deletes — note moves to trash and can be restored. If the note is already trashed, this hard-deletes it. Pass force: true to hard-delete immediately. Audited.

• Auth: brain:write

Response:

{ "id": 55, "deleted": "soft" }

brain_restore_note#

Restore a soft-deleted note back to the active list.

• Auth: brain:write

brain_bulk_update_notes#

Apply a bulk operation to up to 500 notes at once. Cross-tenant IDs are silently skipped.

• Auth: brain:write

Op shapes:

{ "kind": "add_tags", "tags": ["competitor", "q3"] }
{ "kind": "replace_tag_prefix", "from": "old-prefix", "to": "new-prefix" }

Response:

{ "updated": 48, "skipped": 2 }

brain_classify_notes#

Run the LLM classifier to assign BRAIN-1 taxonomy facets (source / slate-area / audience / content-type / recency / competitor / status). Default dryRun: true — returns counts and a 5-row sample without writing anything. Set dryRun: false to get the full per-note output to feed into brain_apply_classifications.

• Auth: brain:write

brain_apply_classifications#

Persist classifier output from brain_classify_notes: writes the note status enum and attaches matching reserved taxonomy topics. Rows below minConfidence (default 0.7) are routed to the AI review queue unless routeBelowMinToReview: false. Idempotent.

• Auth: brain:write

Response:

{
  "notesUpdated": 45,
  "topicsAttached": 120,
  "attachmentsExisted": 3,
  "routedToReview": 2,
  "skippedTotal": 1,
  "skipped": [{ "noteId": 99, "reason": "below_min_confidence" }]
}

brain_list_note_history#

Audit log for a single note: created, updated, soft_deleted, restored, hard_deleted, etc.

• Auth: brain:read

Saved Searches#

brain_list_saved_searches#

List sidebar-pinned filter sets.

• Auth: brain:read

brain_get_saved_search#

Fetch a saved search by id, including the full filters JSON.

• Auth: brain:read

brain_create_saved_search#

Pin a knowledge filter set to the sidebar.

• Auth: brain:write

brain_update_saved_search#

Patch fields on a saved search. Pass scope to move between personal and shared.

• Auth: brain:write

brain_delete_saved_search#

Remove a saved-search pin from the sidebar.

• Auth: brain:write

Note Templates#

brain_list_note_templates#

List reusable note templates. Slim by default (no body). Pass includeBody: true to inline bodies.

• Auth: brain:read

brain_get_note_template#

Fetch a template by id, including the full markdown body.

• Auth: brain:read

brain_create_note_template#

Define a reusable note template. Body is markdown and supports {{variables}}. Returns an error if a template with this name already exists for the tenant.

• Auth: brain:write

brain_update_note_template#

Patch any field on a template.

• Auth: brain:write

brain_delete_note_template#

Permanently delete a template. Existing notes created from it are unaffected.

• Auth: brain:write

brain_create_note_from_template#

Apply a template (resolving {{today}}, {{userName}}, etc.) and create a new note.

• Auth: brain:write

Response (slim):

{ "id": 301, "title": "Daily Standup 2026-06-04", "bodyLength": 420, "tags": ["standup"], "updatedAt": "..." }

CRM (via Brain)#

brain_list_companies#

List CRM companies. Use brain_search for semantic matching; use this for structured field filters.

• Auth: brain:read

brain_get_company#

Get a CRM company with its linked contacts and open deals.

• Auth: brain:read

brain_list_contacts#

List CRM contacts with optional filters.

• Auth: brain:read

brain_get_contact#

Get a CRM contact with their linked company and open deals.

• Auth: brain:read

brain_list_deals#

List CRM deals with optional filters.

• Auth: brain:read

brain_get_deal#

Get a CRM deal with its linked company, primary contact, and stage info.

• Auth: brain:read

brain_list_posts#

List website posts / pages owned by this tenant. Slim response (no body JSON). Use brain_get_post for the full block content.

• Auth: brain:read

brain_get_post#

Get a post including its full block JSON (posts.content). Validates tenancy via the website ownership.

• Auth: brain:read

Initiatives#

brain_initiatives_list#

List initiatives. Slim by default — returns { id, name, slug, status, priority, ownerId, targetDate, goalCount } per row. Heavy text fields are opt-in via include.

• Auth: brain:read

brain_initiatives_get#

Get one initiative by id with optional goals and linked entities.

• Auth: brain:read

brain_initiatives_links#

List polymorphic entities linked to an initiative (tasks, notes, meetings, decisions, topics, CRM deals/companies).

• Auth: brain:read

brain_initiatives_create#

Create a multi-quarter initiative. Echo: { id, slug, status }.

• Auth: brain:write

brain_initiatives_update#

Patch fields on an initiative. Status changes are rejected — use brain_initiatives_close or brain_initiatives_reopen instead.

• Auth: brain:write

brain_initiatives_close#

Terminal status transition — outcome must be completed or cancelled. Requires at least one of reason / lessonsLearned. When lessonsLearned is provided, a pinned brain note is auto-created.

• Auth: brain:write

brain_initiatives_reopen#

Reopen a previously closed initiative — only from completed or cancelled. Sets status to active.

• Auth: brain:write

brain_initiatives_link#

Attach a polymorphic entity to an initiative. Idempotent.

• Auth: brain:write

brain_initiatives_unlink#

Remove a polymorphic link from an initiative.

• Auth: brain:write

Goals#

brain_goals_list#

List goals. Slim by default; opt into "description" and "lastProgressNote" via include.

• Auth: brain:read

brain_goals_get#

Get one goal by id with a slim parent-initiative reference.

• Auth: brain:read

brain_goals_create#

Create a goal under an existing initiative.

• Auth: brain:write

brain_goals_update#

Patch fields on a goal (including status).

• Auth: brain:write

brain_goals_checkin#

Drop a progress check-in: updates currentMetric, lastProgressNote, lastCheckedInAt. When status is omitted but currentMetric is provided, the auto-classifier picks the new status.

• Auth: brain:write

brain_goals_delete#

Hard-delete a goal.

• Auth: brain:write

Decisions#

Decisions are immutable history — rationale and decision text cannot be edited in place. Use brain_decisions_supersede to create a successor and atomically link it.

brain_decisions_list#

List decisions with optional filters. Slim by default; opt into heavy text fields via include. Paginated via { items, total, limit, offset }.

• Auth: brain:read

brain_decisions_get#

Fetch a decision by id with its supersedes chain (ancestors + descendants). Heavy text fields are opt-in.

• Auth: brain:read

brain_decisions_create#

Create a new accepted decision. Echo is slim — full prose lives in the input but is not echoed back. Audited.

• Auth: brain:write

brain_decisions_update#

Patch mutable fields on a decision (title, context, decisionMakerId, anchors, confidentialityLevel, alternativesConsidered). Attempts to mutate decision, rationale, or reversibility return { error: "use_supersede" }. Audited.

• Auth: brain:write

brain_decisions_supersede#

Atomically create a successor decision and link it back to the old one (old.status → "superseded"). Use when you need to change rationale, decision text, or reversibility. Audited.

• Auth: brain:write

Response:

{
  "previous": { "id": 10, "status": "superseded" },
  "current": { "id": 11, "status": "accepted", "decidedAt": "2026-06-04T..." }
}

brain_decisions_reject#

Soft-reject a decision by transitioning status to rejected. Idempotent. Audited.

• Auth: brain:write

Topics#

brain_topics_list#

Flat list of every topic in path order. Pass tagPrefix to scope to a subtree; includeEntityCounts to add per-row count.

• Auth: brain:read

brain_topics_tree#

Nested topic taxonomy tree with per-node childCount and entityCount. Descriptions are opt-in.

• Auth: brain:read

brain_topics_get#

Fetch a topic by id with its breadcrumb (root → immediate parent).

• Auth: brain:read

brain_topics_entities#

List entities attached to a topic (notes, meetings, tasks, decisions, relationship overlays, initiatives, people). Paginated; limit capped at 100.

• Auth: brain:read

brain_topics_create#

Create a topic. Slug and path auto-derive from name; collisions get a -2, -3 suffix. Audited.

• Auth: brain:write

brain_topics_update#

Patch a topic. Rename does NOT change slug (stable URLs). Use brain_topics_move to reparent. Audited.

• Auth: brain:write

brain_topics_move#

Move a topic under a new parent, recomputing the materialized path for the entire subtree atomically. Pass newParentId: null to promote to root. Audited.

• Auth: brain:write

brain_topics_merge#

Fold sourceId into targetId: reattach entity links (skipping duplicates), reparent source's children under target, then delete source. Refuses to merge into a descendant. Audited.

• Auth: brain:write

brain_topics_delete#

Delete a topic. Refuses if it has children. Refuses if entities are attached unless force: true.

• Auth: brain:write

brain_topics_attach#

Bulk-attach one or more topics to a single entity. Idempotent; cross-tenant topic IDs are silently dropped.

• Auth: brain:write

brain_topics_detach#

Bulk-detach one or more topics from a single entity. Missing rows are a no-op.

• Auth: brain:write

brain_topics_import_from_tags#

Walk every brain_notes.tags string, split hierarchical a/b/c tags into a topic tree, find-or-create each segment, and attach notes to the leaf topic. dryRun: true returns the report without writing. Idempotent.

• Auth: brain:write

People#

brain_people_list#

List internal people (employees / advisors / contractors). Slim by default; opt into "notes" and "profileUrls" via include.

• Auth: brain:read

brain_people_get#

Fetch a person with manager, direct reports, org-unit memberships, and expertise tags.

• Auth: brain:read

brain_who_knows#

Resolve a free-text query to expertise tags, then rank people by matched-tag count, level bonus, and primary-org-unit bonus. Use this for "who should I talk to about X" queries.

• Auth: brain:read

Tool call example:

{ "name": "brain_who_knows", "arguments": { "query": "Postgres query optimization", "limit": 5 } }

brain_people_create#

Add an internal person. Echo: { id, status }.

• Auth: brain:write

brain_people_update#

Patch fields on a person. Manager change is cycle-guarded — assigning a descendant returns { error: "manager_cycle" }.

• Auth: brain:write

brain_people_delete#

Delete a person. Cascades org-unit memberships and expertise junctions; direct reports chains are nulled out.

• Auth: brain:write

brain_people_attach_expertise#

Attach an expertise tag to a person with an optional proficiency level (1–4). Idempotent — updates level if the row already exists.

• Auth: brain:write

brain_people_detach_expertise#

Remove an expertise tag from a person.

• Auth: brain:write

Expertise Tags#

brain_expertise_tags_list#

List per-tenant expertise tags. peopleCount is always populated. Slim by default.

• Auth: brain:read

brain_expertise_tags_create#

Create a per-tenant expertise tag. Slug auto-derived; collisions suffixed -2, -3. Echo: { id, slug }.

• Auth: brain:write

brain_expertise_tags_update#

Patch name or description on an expertise tag. Slug stays stable.

• Auth: brain:write

brain_expertise_tags_delete#

Delete an expertise tag. Refuses by default if any person still holds it — pass force: true to cascade-detach. Returns { error: "in_use", peopleAttached } on conflict.

• Auth: brain:write

brain_expertise_tags_merge#

Re-attach every person–expertise row from sourceTagId to targetTagId, then delete the source tag.

• Auth: brain:write

Org Units#

brain_org_units_list#

Flat list of org units ordered by path. memberCount always populated. Descriptions are opt-in.

• Auth: brain:read

brain_org_units_tree#

Nested org-unit tree with per-node childCount and memberCount.

• Auth: brain:read

brain_org_units_get#

Fetch an org unit with its ancestor chain and members.

• Auth: brain:read

brain_org_units_create#

Create a hierarchical org unit. Slug auto-derived; path computed from parent. Echo: { id, slug, path }.

• Auth: brain:write

brain_org_units_update#

Patch fields on an org unit. Slug and path stay stable on rename. Use brain_org_units_move to reparent.

• Auth: brain:write

brain_org_units_move#

Re-parent an org unit, rewriting the path prefix for the unit and all descendants. Cycle-guarded.

• Auth: brain:write

brain_org_units_merge#

Re-parent source's children under target, re-attach source's members to target (dedup-safe), then delete source.

• Auth: brain:write

brain_org_units_delete#

Delete an org unit. Refuses by default if it has members or children — pass force: true to cascade. Returns { error: "in_use", memberCount, childCount } on conflict.

• Auth: brain:write

brain_org_units_add_member#

Attach a person to an org unit. Idempotent — re-attaching updates primary and roleInUnit. Marking primary: true flips other memberships to primary: false.

• Auth: brain:write

brain_org_units_remove_member#

Detach a person from an org unit.

• Auth: brain:write

brain_org_units_set_primary#

Mark an org unit as the primary membership for a person. Flips all other memberships to primary: false. Requires the membership to already exist.

• Auth: brain:write

Glossary#

brain_glossary_list#

List tenant glossary terms (acronyms, codenames, jargon). Slim by default; opt into "definition" and "aliases" via include. Limit capped at 100.

• Auth: brain:read

brain_glossary_get#

Fetch a single term with its "see also" related terms.

• Auth: brain:read

brain_glossary_lookup#

Scored lookup against active glossary terms — returns ranked matches (exact term → exact alias → prefix → substring → definition). Use before answering any question that may contain tenant-specific acronyms. Limit capped at 25.

• Auth: brain:read

Tool call example:

{ "name": "brain_glossary_lookup", "arguments": { "query": "OKR", "limit": 3 } }

brain_glossary_create#

Add a new glossary term. Slug auto-derived from term. Echo: { id, slug }.

• Auth: brain:write

brain_glossary_update#

Patch any field on a glossary term except slug. Echo: { id, updatedFields }.

• Auth: brain:write

brain_glossary_delete#

Hard-delete a term. Also prunes this ID from every other term's relatedTermIds list.

• Auth: brain:write

Response:

{ "id": 22, "deleted": true, "prunedRelatedTermFromCount": 3 }

brain_glossary_bulk_import#

Insert or update up to 200 terms in one call. Upsert keyed on slug (auto-derived from term) per tenant. Echo: { created, updated, errors }.

• Auth: brain:write

Playbooks#

brain_playbooks_list#

List multi-step playbooks. Slim by default — returns { id, name, slug, status, category, triggerKind, ownerId, stepCount, activeRunCount }. Opt into "description", "triggerConfig", "defaultTopicIds" via include.

• Auth: brain:read

brain_playbooks_get#

Get one playbook with its ordered steps. Heavy fields (description, step config / condition blobs) are opt-in.

• Auth: brain:read

brain_playbooks_create#

Create a new playbook (always starts in draft). Use brain_playbooks_add_step to attach steps, then brain_playbooks_activate to make it runnable.

• Auth: brain:write

brain_playbooks_update#

Patch fields on a playbook definition. Status changes are rejected — use brain_playbooks_activate or brain_playbooks_archive instead.

• Auth: brain:write

brain_playbooks_activate#

Flip status from draft to active. Refuses if the playbook has zero steps or the step graph fails DAG validation (cycles, missing refs, no entry point). Returns { error: "dag_invalid", errors: string[] } on failure.

• Auth: brain:write

brain_playbooks_archive#

Archive an active playbook (no new runs can be started).

• Auth: brain:write

brain_playbooks_delete#

Permanently delete a playbook. Refuses if there are any active or paused runs.

• Auth: brain:write

brain_playbooks_add_step#

Add a step to a playbook (only on draft playbooks).

• Auth: brain:write

brain_playbooks_update_step#

Patch fields on a step.

• Auth: brain:write

brain_playbooks_remove_step#

Remove a step from a playbook.

• Auth: brain:write

brain_playbooks_reorder_steps#

Reorder steps within a playbook by providing the full ordered list of step IDs.

• Auth: brain:write

Playbook Runs#

brain_playbook_runs_list#

List runs. Slim row default. Filter by status and/or playbookId. Limit capped at 100.

• Auth: brain:read

brain_playbook_runs_get#

Get one run with { run, playbook (slim), steps, links }. Heavy JSON columns are opt-in.

• Auth: brain:read

brain_playbook_runs_active_for_entity#

List active and paused runs anchored to a given entity via playbook links.

• Auth: brain:read

brain_playbook_runs_start#

Start a playbook run.

• Auth: brain:write

brain_playbook_runs_advance#

Advance a run to the next step (or complete it if no further steps). Triggers recursive spawn chaining when explicit step completion is used.

• Auth: brain:write

brain_playbook_run_steps_complete#

Mark a specific run step as completed, providing an optional result entity reference.

• Auth: brain:write

brain_playbook_run_steps_skip#

Skip a specific run step with a reason.

• Auth: brain:write

brain_playbook_runs_abort#

Abort a run.

• Auth: brain:write

Documents#

Documents are versioned SOPs, policies, and required-reads. The lifecycle is: create → edit draft → publish → (archive / unarchive). Acknowledgments are the compliance record.

brain_documents_list#

List versioned documents. Slim by default. Pass include: ["body"] to hydrate each row with the current published version's body (heavy). Limit capped at 100.

• Auth: brain:read

brain_documents_get#

Fetch a single document with version list and links. includeBody: true attaches current published + draft version full rows; includeAllVersions: true attaches every version row.

• Auth: brain:read

brain_document_versions_list#

List a document's versions newest-first. Slim by default; opt into "body", "changeNotes", "summary" via include. Limit capped at 100.

• Auth: brain:read

brain_document_versions_get#

Fetch one specific document version. Full markdown body ships by default. Optional "changeNotes" and "summary" via include.

• Auth: brain:read

brain_documents_create#

Create a new document seeded with an empty v1 draft. Echo: { id, slug, status, version1Id }. Follow up with brain_document_versions_edit_draft, then brain_documents_publish.

• Auth: brain:write

brain_documents_update#

Patch document-level metadata (title, category, ownerId, confidentialityLevel, defaultTopicIds). Status changes return { error: "use_publish_or_archive" }.

• Auth: brain:write

brain_document_versions_edit_draft#

Patch the document's draft body / summary / changeNotes. If no draft exists (last action was a publish), creates a new draft seeded from the latest version body. Refuses if the document is archived.

• Auth: brain:write

Response:

{ "documentId": 5, "versionId": 18, "versionNumber": 3, "isDraft": true }

brain_documents_publish#

Flip the current draft to a published version. Refuses if no draft exists or if the draft body is empty — returns { error: "empty_draft_body" } in that case.

• Auth: brain:write

brain_documents_archive#

Soft-archive a document — sets status to archived. Document remains in the database.

• Auth: brain:write

brain_documents_unarchive#

Reverse archive — restores status to published (if a published version exists) or draft otherwise.

• Auth: brain:write

brain_documents_delete#

Hard-delete a document and (via FK cascade) every version, required-read, link, and acknowledgment. Refuses by default if any acknowledgments exist — returns { error: "document_has_acks", ackCount }. Pass force: true to cascade.

• Auth: brain:write

brain_documents_promote_from_note#

Create a new document seeded from an existing brain note — the note's body becomes the v1 draft body. Echo: { documentId, slug, version1Id }.

• Auth: brain:write

brain_documents_link#

Attach a polymorphic entity (topic, initiative, decision, meeting, glossary_term, person) to a document. Idempotent.

• Auth: brain:write

brain_documents_unlink#

Remove a polymorphic link from a document.

• Auth: brain:write

Document Required Reads & Compliance#

brain_document_required_reads_list_for_document#

Who is required to read this document? Returns rows with targetType, targetId, targetName, pinnedVersionId, dueAt, assignedAt. Limit capped at 100.

• Auth: brain:read

brain_document_required_reads_list_for_person#

What does this person have to read? Returns direct required-read assignments with acknowledgment status. status filter: open, acknowledged, all (default).

• Auth: brain:read

brain_document_acknowledgments_list_for_document#

Audit trail of every (version, person, acknowledgedAt) recorded against a document.

• Auth: brain:read

brain_document_acknowledgments_list_for_person#

Every document a person has acknowledged, newest first.

• Auth: brain:read

brain_document_compliance_report#

The canonical "who has read this, who hasn't" view. Expands org-unit required-reads to active member person IDs, partitions the assigned universe into acknowledged / pending / overdue, and returns full ID arrays plus a summary count rollup.

• Auth: brain:read

Response:

{
  "documentId": 5,
  "currentPublishedVersionId": 18,
  "acknowledged": [14, 22],
  "pending": [33],
  "overdue": [41],
  "counts": { "acknowledged": 2, "pending": 1, "overdue": 1, "total": 4 }
}

brain_document_required_reads_assign#

Make a person or org unit required to read a document. Idempotent on (documentId, targetType, targetId). When targetType: "org_unit" and expandOrgUnit: true, fans out to one row per active member (current snapshot). Echo: { assigned, alreadyAssigned, expandedTo? }.

• Auth: brain:write

brain_document_required_reads_remove#

Delete a required-read row. Refuses by default if any acknowledgments reference it — returns { error: "has_acks" }. Pass force: true to unlink (acks survive but lose their pointer).

• Auth: brain:write

brain_documents_acknowledge#

Record a (documentId, versionId, personId) acknowledgment. Idempotent. If requiredReadId is omitted, auto-links to a matching person-target required-read when one exists.

• Auth: brain:write

Response:

{
  "ackId": 77,
  "documentId": 5,
  "versionId": 18,
  "personId": 14,
  "acknowledgedAt": "2026-06-04T09:00:00.000Z"
}