Guide: audit access, sign-off & training

The read side of governance: who can see a document, who has agreed to it, who has completed the training on it, who has touched it, and what a given person owns. Bodies below are abridged and illustrative — see the tool reference for the full contracts.

Who can access this document, and how?

→ get_document_members_and_roles { "documentId": "7d4f2a90-…", "topicType": "system" }

{
  "roles": [{ "title": "Client Delivery" }],
  "members": [
    { "name": "Jane Smith",  "email": "jane@acme.com",  "accessType": "role-based", "roles": ["Client Delivery"] },
    { "name": "Sam Nguyen",  "email": "sam@acme.com",   "accessType": "direct" },
    { "name": "Priya Patel", "email": "priya@acme.com", "accessType": "both", "roles": ["Client Delivery"] }
  ]
}

Present it as an audit: roles first, then members grouped by how they got in (direct vs role-based vs both). Access is the union of the two mechanisms — see Roles & seats.

Who has signed off?

→ get_document_agreement_status { "documentId": "7d4f2a90-…", "topicType": "policy" }

Returns each assigned member with agreed / not-agreed status — the compliance view for policy acknowledgements (“who has actually agreed to the new leave policy?”).

Who has completed the training?

→ get_document_training_progress { "documentId": "b2c91e08-…" }

Returns per-user completion percentage and status for a training document. Combine with get_document_members_and_roles to report “assigned vs actually completed”.

What does this person own?

→ list_documents_by_owner { "owner": "Jane Smith", "fetchAll": true }

[
  { "id": "…", "title": "Onboard a new client", "section": "system",  "state": 3, "materializedPath": "3. Client Delivery" },
  { "id": "…", "title": "Leave policy",         "section": "policy",  "state": 1, "materializedPath": "HR" }
]

One call spans systems + policies + trainings (omit section for all three). The name must match exactly or the call returns a 400 — when unsure, use the person’s user UUID (visible on tree nodes as ownerId). ownership defaults to either (primary OR secondary owner).

Who created or changed this document?

→ get_document_activity_log { "documentId": "7d4f2a90-…", "topicType": "system" }

Returns creation (who/when), last modification (who/when, with change summary where available), and the full event feed — pass includeViews: true to include view events. Lead with creation and last-modified when presenting; the feed is supporting detail.

Fixing what the audit finds

Access audits usually end in an assignment change, and that’s now writable:

→ list_company_members { "search": "Priya Patel" }        // resolve name → userId
→ manage_document_members { "documentId": "7d4f2a90-…", "topicType": "system", "action": "add", "userIds": ["…"] }

Resolve names with list_company_members / list_roles first (never ask the user for UUIDs), then verify the result with get_document_members_and_roles. Seat provisioning (inviting new people, licences) remains app-UI only.

Recipes these unlock

• Offboarding sweep: list_documents_by_owner for the leaver → report everything that needs a new owner.
• Review-debt report: walk the tree and group by owner using reviewDate (on every response) — anything in the past, plus anything with reviewDate: null. Don’t filter on state: 2 (RED) alone; RED is set manually, so an untended library reports zero debt.
• Compliance gap: agreement status across every policy → who hasn’t signed off, per policy.
• Training rollout check: progress on each training in a learning track → completion by team.

The boundary

Document-level assignment is writable (manage_document_members); seat provisioning is not — inviting new people to the workspace, allocating licences, or changing company-role membership happens in the app UI. Don’t attempt those; direct the user there instead.