# systemHUB Docs — full corpus

> Every page of https://systemhub.com/docs/ in one file, for AI agents. Curated index: https://systemhub.com/llms.txt · Each page is also served individually as markdown (append .md to its URL). Generated with the site build.

---

# systemHUB Docs (https://systemhub.com/docs/)

> Part of systemHUB Docs · Connect: Settings → AI Gateway in systemHUB · Auth: OAuth (scoping is workspace-level today — see Getting started) · MCP tools: 48 · Full corpus: https://systemhub.com/llms-full.txt

> Machine-readable documentation for connecting AI agents and technical users to systemHUB.

systemHUB is a platform for documenting, organising, and training teams on business systems — **Systems** (procedures/SOPs), **Policies** (compliance documents), and **Trainings** (learning modules). This documentation set describes how an AI agent (via the systemHUB MCP server) or a developer can connect to systemHUB, read a company's content, and author or maintain it programmatically.

This is the **AI-facing** surface. If you're a human looking for friendly, task-oriented help, use [help.systemhub.com](https://help.systemhub.com) instead. The two layer together — they don't replace each other.

## Who this is for

- **A prospect's or customer's AI assistant** connecting to systemHUB via MCP, so it can find and use the company's systems with no friction.
- **Technical users / developers** integrating with, or building on top of, the systemHUB MCP server.

## Start here

1. **[Getting started](/docs/getting-started)** — connect the systemHUB MCP server and make your first call.
2. **[Quick wins](/docs/quick-wins)** — verified copy-paste prompts for a newly connected agent.
3. **[Teach your AI](/docs/teach-your-ai)** — make it stick: the first-session prompt and the briefing your AI saves into its standing context.
4. **[Document lifecycle](/docs/concepts/document-lifecycle)** — how documents, states, and publishing work.
5. **[Roles & seats](/docs/concepts/roles-and-seats)** — how access is granted and counted.
6. **[Sharing & links](/docs/concepts/sharing-and-links)** — app links (login required) vs public share links (no login, machine-readable).
7. **[Authoring content](/docs/concepts/authoring-content)** — the formatting contract: what survives the editor and what gets stripped.
8. **[Errors & limits](/docs/concepts/errors-and-limits)** — known failure modes and validation limits, stated up front.
9. **[Tool reference](/docs/tool-reference)** — every MCP tool, its inputs, and what it returns, generated from the live schema.

## Guides (worked examples)

Task-oriented walkthroughs with request→response examples:

- **[Draft an SOP into systemHUB](/docs/guides/drafting-sops)** — orient, dedupe, create to the house format, attach templates/media, version.
- **[Audit access, sign-off & training](/docs/guides/auditing-access)** — who can see what, who's agreed, who's completed training, what a person owns.
- **[Organise & maintain the library](/docs/guides/organising-content)** — folders, moves, states, tags, learning tracks, master templates.

## What you can do through the MCP today

- **Discover & read** — browse the folder tree; search systems, policies, and trainings by name; read full document content, owners, tags, media, and attachments.
- **Audit** — see who a document is assigned to (members & roles), agreement/sign-off status, and training completion progress.
- **Author & maintain** — create, edit, move, and publish systems, policies, trainings, folders, learning tracks, tags, and media.

## Known limits


These are documented honestly so a connecting agent doesn't try what isn't there yet:

- **No seat provisioning** via the MCP — inviting people and allocating licences happens in the app UI. (Document-level member/role *assignment* IS available — see `manage_document_members`.)
- **No headless / service credential yet** — the MCP connection is per-user OAuth, designed for a person's AI client. Unattended automations (cron jobs, scheduled pipelines) have no non-expiring credential today; a long-lived API-key path is on the product roadmap.
- **No workspace-wide usage analytics** via the MCP. (Per-document activity, including views, IS readable — see `get_document_activity_log`.)
- **No deletes** — an agent can create, edit, move, and publish, but never destroy.
- **Images cannot be injected via the API** — they're uploaded through the editor. See [Authoring content](/docs/concepts/authoring-content).

Recent capability changes are tracked in the **[changelog](/docs/changelog)**.

## For AI agents reading this

Every page on this site is also servable as plain markdown — append `.md` to the page URL (e.g. [/docs/getting-started.md](/docs/getting-started.md)). A machine-readable index lives at [/llms.txt](/llms.txt).


---

# Getting started (https://systemhub.com/docs/getting-started)

> Part of systemHUB Docs · Connect: Settings → AI Gateway in systemHUB · Auth: OAuth (scoping is workspace-level today — see Getting started) · MCP tools: 48 · Full corpus: https://systemhub.com/llms-full.txt

This guide gets an AI agent or technical user connected to systemHUB through the **MCP server** and making a first read call.

## 1. What the MCP server is

The systemHUB MCP server exposes your company's systemHUB content — Systems, Policies, and Trainings — to an AI agent as a set of callable tools. An agent that speaks the [Model Context Protocol](https://modelcontextprotocol.io) can connect to it, discover the available tools, and call them to search, read, author, and audit content on your behalf.

## 2. Prerequisites

- A systemHUB account with content you want the agent to reach.
- **AI Gateway access** enabled on your plan (included with Accelerator). If you don't see **AI Gateway** under Settings, contact [support@systemology.com](mailto:support@systemology.com).
- An MCP-capable client (e.g. Claude, ChatGPT, or any agent framework that supports MCP servers).

> ⚠️ **Authentication note (important, being fixed):** a connection is currently scoped to the **identity attached to the workspace's most recently generated AI Gateway token** — *not* to each person who connects. On a workspace where several people connect, everyone's agent can therefore resolve to the same identity and visibility. Treat MCP access as **workspace-level** for now: only connect agents for people you're comfortable seeing everything the token generator can see. A fix binding each connection to the person connecting is in progress — see the [changelog](/docs/changelog).

## 3. Connect

Everything you need lives in one place in systemHUB: **Settings → AI Gateway**. Three things matter:

1. **Server URL** — `https://mcp.systemhub.com/mcp` (the same for every workspace).
2. **OAuth Client ID** — your **company alias**, which is your account subdomain (the part before `.systemhub.com`), lowercase, no spaces (e.g. `acme`, not `Acme`).
3. **Token** — click **Generate New Token** and copy it immediately; **it is shown only once**. Tokens live for **180 days** from generation (you'll get an email reminder at day 144 to rotate). ⚠️ Generating a new token **immediately revokes the existing one** and disconnects any AI agent currently connected with it — they'll need to reconnect with the new token.

Then connect from your AI client:

- **Claude (web or desktop):** **Settings → Connectors → Add custom connector** — name it `systemHUB`, enter the server URL `https://mcp.systemhub.com/mcp`, and in advanced settings set the OAuth Client ID to your company alias and paste the token. Click **Connect**, log in with your systemHUB credentials and approve access.
- **Google Gemini CLI** (verified 7 Aug 2026): `gemini mcp add -s user --transport http systemhub https://mcp.systemhub.com/mcp`, then `/mcp auth systemhub` and complete the browser flow. `/mcp` should then report `systemhub - Ready (48 tools) (OAuth)`.
- **Any other MCP client** (agent frameworks, IDEs): configure a remote MCP server with the Connector URL as the endpoint and OAuth as the auth method, then complete the browser login when prompted. The MCP Inspector is a quick way to verify the server responds before wiring it into an agent.

### Which AI clients can actually connect

The MCP protocol is open, but **not every client lets you add a custom server**, and several gate it behind a paid or admin tier. Verified 7 Aug 2026:

| Client | Custom MCP server? | Notes |
|---|---|---|
| **Claude** (web, desktop, Code) | ✅ Yes | Paid plan. Verified. |
| **Google Gemini CLI** | ✅ Yes | Free, but technical (Node install). Verified end to end against a production workspace. Needs an AI Studio API key for the CLI's own model auth — on a Workspace account that also means importing a Cloud project. |
| **ChatGPT** | ⚠️ Paid tiers only | Reported to require Plus or above with developer mode. **Not available on the free tier.** |
| **Gemini web app** | ❌ No | Connected Apps is a curated catalogue with no way to add a custom server. Custom MCP needs **Gemini Enterprise** (admin-registered) or the CLI above. |

> **Plan for this when rolling out to a team.** Someone using free ChatGPT or the Gemini web app cannot connect at all — no setting exists. They'll need a paid AI client, or the Gemini CLI if they're comfortable in a terminal.

> **One token, several clients.** You can connect more than one AI client with the same token — Claude and Gemini CLI running against the same workspace concurrently has been verified, as has Claude desktop plus Claude web. Remember that *generating* a new token disconnects all of your own connected clients at once (see above).

Step-by-step with screenshots: [Connecting systemHUB to Claude + ChatGPT (AI Gateway / MCP)](https://kb.systemology.com/help-center/connecting-systemhub-to-claude-ai-gateway-/-mcp).

### Connecting your team

The server URL, alias, and token are **company-level** — there is one token per workspace, not one per person.

> ⚠️ **Multi-user connection is being confirmed (as of 31 Jul 2026).** Field reports conflict: some workspaces have connected several team members with the same values, while in others additional members hit an error even when they are systemHUB admins. We are also confirming whether the connection carries the *token generator's* access or each member's own access — until that's answered, **don't assume an editor's AI is limited to editor permissions**. If you're rolling out to a team, connect one person first and [check with support](mailto:support@systemology.com) before wider rollout. This note will be updated when the behaviour is confirmed — see the [changelog](/docs/changelog).

**Each person generates their own token — don't pass yours around.** Sharing a token means your colleague's agent runs with *your* identity and access. Generating your own token does **not** disconnect your colleagues: tokens are per-person, and generating one only revokes your own previous token and your own sessions.

**Adding a team member (field-tested procedure):**

1. **They log into systemHUB as themselves** → Settings → Company → AI Gateway → **Generate New Token**. This is their token, separate from everyone else's.
2. **In their AI client, use the existing systemHUB connector entry** and click **Connect** — in a shared Claude Teams workspace, one person adds the connector once and everyone else connects through it.
3. **They enter the company alias, sign in as themselves, and approve.** Done.

> **Don't add a second custom connector** pointing at the same server URL — the client rejects it with *"a server with this URL already exists"*. If a connector for systemHUB is already in the workspace, connect to that one.

> ⚠️ **If they haven't generated their own token first**, the approve step fails with *"No active agent token found"*. That's the most common cause of a failed team connection — generate the token, then approve.

Also worth knowing:

- Reaching Settings → Company → AI Gateway may require elevated permissions. If a team member can't see that screen to generate their own token, they can't complete this flow — [tell us](mailto:support@systemology.com), as we're confirming which roles can self-serve.
- **Don't rely on MCP activity for audit attribution** yet — sessions can report as the token's identity rather than the person acting.

### Troubleshooting

| Symptom | Likely cause → fix |
|---|---|
| **"Invalid or expired client ID"** | Company alias format is wrong (must be lowercase, no spaces) or the token is stale → regenerate in Settings → AI Gateway. |
| **Tools don't appear in the client** | Connection added but not authorised → re-run Connect and complete the login/approval; after regenerating a token, reconnect. |
| **Agent was working, suddenly can't connect** | *You* generated a new token (which revokes your own previous one), or your token passed its 180-day lifetime → reconnect. A colleague generating their token does not affect you. |
| **"No active agent token found" on the Approve Connection screen** | You reached the consent screen signed in as yourself, but *you* don't have a token of your own — someone else's token doesn't satisfy this check → generate your own in Settings → AI Gateway, then approve again. This is the per-user path working as intended. |
| **"A server with this URL already exists"** | You're adding a *new* custom connector for a systemHUB server already configured in that workspace → don't add a second one; connect through the existing entry. |
| **"Document not found" on a document that exists** | Visibility scoping — the connected user can't see it — or it's a master template (`get_*_details` returns 404 on those by design). |
| **400 on an owner lookup** | Full name didn't match exactly → use the exact name from a tree node, or the user UUID. |
| **502 on a large edit** | Content over ~126KB → split the document or write in sections. |
| **"My formatting changed after a human edited the doc"** | You authored outside the supported set; the editor filtered it → see [Authoring content](/docs/concepts/authoring-content). |

More failure modes: [Errors & limits](/docs/concepts/errors-and-limits).

## 4. Your first call

Once connected, the agent should **orient before acting**:

1. **Map the structure** — call `get_folder_tree` (Systems), `get_policy_tree` (Policies), or `get_training_tree` (Trainings) to see folders and documents, their owners, and publication state.
2. **Find a document** — call `search_by_name` (systems), `search_policy`, or `search_training` with a title fragment.
3. **Read it** — call `get_system_details` / `get_policy_details` / `get_training_details` with the document UUID to pull full content, overview, tags, media, and comments.

A minimal "can you see my systems?" smoke test is a single `get_folder_tree` call with no arguments — it returns the top of the Systems tree.

## 5. Good-citizen rules for connecting agents

- **Read before you write.** Orient with the tree/search tools before creating or editing anything.
- **Respect master templates.** Nodes flagged `isMasterTemplate: true` are read-only reference content from the master workspace — never edit, move, publish, or delete them. `get_*_details` returns `404` on them by design.
- **Match names exactly for owner lookups.** `list_documents_by_owner` needs the person's full name exactly or their user UUID.
- **Publishing is deliberate.** Creating a document *with content* publishes it automatically so assigned users can see it. Pass `publish: false` to keep a draft. See [Document lifecycle](/docs/concepts/document-lifecycle).
- **Author within the supported formatting set.** The editor silently strips unsupported HTML on the next human save. See [Authoring content](/docs/concepts/authoring-content).

Next: **[Quick wins →](/docs/quick-wins)** — verified copy-paste prompts for your first ten minutes connected — or dive into **[Document lifecycle](/docs/concepts/document-lifecycle)**.


---

# Quick wins (https://systemhub.com/docs/quick-wins)

> Part of systemHUB Docs · Connect: Settings → AI Gateway in systemHUB · Auth: OAuth (scoping is workspace-level today — see Getting started) · MCP tools: 48 · Full corpus: https://systemhub.com/llms-full.txt

Copy-paste prompts to run with your connected AI (Claude, ChatGPT or any MCP-capable client) once systemHUB is connected. Every prompt on this page has been verified against the live systemHUB MCP server — each one maps to tools that exist today, so none of them will leave your AI apologising.

Not connected yet? Start with **[Getting started](/docs/getting-started)** or the step-by-step help article: [Connecting systemHUB to Claude + ChatGPT (AI Gateway / MCP)](https://kb.systemology.com/help-center/connecting-systemhub-to-claude-ai-gateway-/-mcp).

## Accountability

The reports that used to mean chasing people or exporting spreadsheets. Ten seconds each.

**1. Policy sign-off status**

> Check our [policy name] policy in systemHUB. Who still hasn't signed off on it? Draft me a friendly chase-up message for each person.

Returns the exact signed-off and pending lists with names and emails, from `get_document_agreement_status`.

**2. Training progress**

> How's the team going on the [training name] training? Show me who's done, who's mid-way and who hasn't started.

Returns per-person completion status and percentages, from `get_document_training_progress`.

**3. Ownership handover**

> [Name] is going on leave. List every system, policy and training they own so we can reassign them.

Returns everything they own across all three sections in one call, from `list_documents_by_owner`. Use the person's exact full name as it appears in systemHUB.

## Build and update

**4. Talk a process into a draft SOP**

> I'm going to talk you through how we [do a task]. Ask me questions until you've got it, then draft it as a system in systemHUB for my review.

The AI creates the document in systemHUB where your team can see and review it — not in a chat window that disappears. The full worked loop: [Draft an SOP](/docs/guides/drafting-sops).

**5. Keep a system current**

> Our [process] changed: [describe the change]. Find the system in systemHUB and update it to match, keeping the same format.

**6. Gap and contradiction scan**

> Search systemHUB for everything we have about [topic]. What's covered, what's missing and where do two documents contradict each other?

## Daily use

**7. Answer from your own systems**

> Using only our systemHUB, how do I [do the task]? Cite which system you're reading from.

**8. New-hire week one**

> We've got a new [role] starting Monday. Pull their relevant systems and trainings from systemHUB and build a week-one onboarding checklist.

**9. Share a system with an outsider**

> Get me a share link for our [system name] system that I can send to our new contractor — they don't have a systemHUB login.

Your AI calls `get_document_share_link`, then hands you the **human-readable** form — `https://{alias}.systemhub.com/systems/{uuid}/{shareCode}` — which opens the document in a browser with no login. (The raw `api.systemhub.com` version of the same code returns JSON, which is for programs, not people.) See [Sharing & links](/docs/concepts/sharing-and-links). Anyone with the URL can read it, so share deliberately.

**10. Who touched this document?**

> Who created our [system name] system, and who last edited it? Anything change recently?

Returns the creation and edit history from `get_document_activity_log`.

## What the MCP can't do yet

Stated plainly so your AI doesn't attempt it (see also [Known limits](/docs/#known-limits), [Errors & limits](/docs/concepts/errors-and-limits), and the [changelog](/docs/changelog)):

- **Workspace-wide "who viewed what" analytics.** Per-document activity (including views) is readable via the activity log, and sign-offs (a deliberate "I agree" click) are fully reportable — but for accountability, ask "who hasn't signed off", never "who hasn't read": a view proves nothing.
- **Inviting users or managing seats.** Assigning existing members and roles *to a document* works via the MCP; bringing new people into the workspace or changing licences is app UI only.
- **Deleting documents.** Blocked by design — your AI can create, edit, move and publish, but never destroy.

Next: **[Document lifecycle →](/docs/concepts/document-lifecycle)**


---

# Document lifecycle: states, Save vs Publish (https://systemhub.com/docs/concepts/document-lifecycle)

> Part of systemHUB Docs · Connect: Settings → AI Gateway in systemHUB · Auth: OAuth (scoping is workspace-level today — see Getting started) · MCP tools: 48 · Full corpus: https://systemhub.com/llms-full.txt

Every systemHUB document — whether a System, Policy, or Training — moves through a defined lifecycle. An AI agent must understand this before authoring, or it will create content nobody can see, or overwrite an approved document.

## Document states

A document's `state` is an integer with a fixed meaning and colour:

| `state` | Colour | Meaning |
|---|---|---|
| `0` | GREY | Draft — being written, not yet reviewed |
| `1` | ORANGE | Needs review — drafted, awaiting approval |
| `2` | RED | Overdue — past its review date |
| `3` | GREEN | Approved — current, reviewed, live |
| `4` | PURPLE | Archived — retired, kept for reference |

These values are returned on every tree node, search result, and `get_*_details` call, and are accepted by the `state` parameter on create/edit tools.

## Save vs Publish (the distinction that matters most)

**Save records your changes. Publish is what your team sees** — until you publish, assigned members keep viewing the last published version.

- **Save** — writes the current content. On its own, saving does not push a new visible version to assigned users.
- **Publish** — releases a version so that assigned members actually see it. Publishing is what makes content live.

For agents, the practical rules are:

- **Creating a document *with content* auto-publishes it** — assigned users can see it immediately. This is intentional; you do **not** need to ask the user to confirm publishing.
- **To create a draft that stays hidden**, pass `publish: false` on the create call. It's saved but not released.
- **Editing auto-publishes too.** `edit_*` releases the change to assigned members unless you pass `publish: false`. Use `publish_system` / `publish_policy` / `publish_training` when you want to cut a *named* version (e.g. `"v1.1 - Added billing steps"`), not to make an edit visible — it already is.
- **So do metadata writes.** `add_document_tags`, template, media and attachment tools all default to `publish: true` — *tagging a document publishes it*. That means a document you created with `publish: false` stops being hidden the moment you tag it. If something must stay unpublished, pass `publish: false` on **every** write to it, not just the create.

> ⚠️ **The practical consequence:** there is no "work quietly then release" mode by default. Any write to a live document — including one that only touches metadata — is visible to the whole team immediately. Before editing an approved document, be sure the user wants the change live now.

> **Canonical wording:** the summary line above is the current agreed phrasing; the app empty-state copy is being finalised from the internal content audit and will be reconciled here so the docs and the product never disagree.

## View vs Edit

Access to a document is not all-or-nothing:

- **View** — a member can read the document but not change it.
- **Edit** — a member can modify content.

What a given person can do is a function of their **role** and any **direct assignment** on the document. See [Roles & seats](/docs/concepts/roles-and-seats). An agent connected with a user's token inherits exactly that user's view/edit scope.

## How systemHUB behaves over time (the model to reason with)

The sequence an agent should hold in its head:

| You do | What happens | When |
|---|---|---|
| `create_system` with content | Document saved AND published — assigned members can see it | Immediately |
| `create_system` with `publish: false` | Document saved as a hidden draft | Visible to no one until published |
| `edit_system` | Content updated at the API layer, stored **verbatim** | Immediately; a new published version only when you cut one |
| `publish_system` | A named version released to assigned members | Immediately |
| A human opens the doc in the editor and saves | The editor **filters the stored HTML** to its supported feature set | First human save — this is when out-of-contract formatting silently changes |

That last row is the one that surprises agents: the API stores whatever HTML you send, but the *editor* is the filter, applied on the next human save — which may be days later. Author within the [supported set](/docs/concepts/authoring-content) and the document is stable forever; author outside it and the document changes under the owner's feet the first time they touch it.

## Master templates

Some content is a **master template** — read-only reference content supplied from the master workspace (`isMasterTemplate: true`). It appears in trees and search so it can be browsed and copied, but it cannot be edited, moved, published, or deleted, and `get_*_details` returns `404` for it. Treat master templates as immutable.

Next: **[Roles & seats →](/docs/concepts/roles-and-seats)**


---

# Roles, members & seats (https://systemhub.com/docs/concepts/roles-and-seats)

> Part of systemHUB Docs · Connect: Settings → AI Gateway in systemHUB · Auth: OAuth (scoping is workspace-level today — see Getting started) · MCP tools: 48 · Full corpus: https://systemhub.com/llms-full.txt

systemHUB controls who can see and do what through **roles** and **member assignments**. This page explains the model an agent needs to reason about access — and where the current MCP boundary sits.

## The access model

A document's access is the union of two mechanisms:

- **Role-based access** — a document is assigned to one or more **roles** (e.g. a department or job function). Every member holding that role gets access.
- **Direct assignment** — an individual member is assigned to the document specifically, regardless of role.

A member can therefore have access that is **direct**, **role-based**, or **both**. The `get_document_members_and_roles` tool returns exactly this: the roles on a document, plus each member's name, email, role title(s), and access type.

Present an access picture as an audit: roles first, then members grouped by how they got in (direct vs role-based vs both).

## Document owners

Separate from access, every document carries a **primary owner** (mandatory — the person accountable for it) and an optional **secondary owner** (a backup). Owners are about accountability, not permission: owning a document is not what grants access to it.

Three behaviours to know before changing owners programmatically:

> **Changing the primary owner moves the outgoing owner into an empty secondary slot.** If the secondary slot is empty, the person you just replaced is automatically recorded as secondary owner — the intent being that a handover keeps the previous owner attached as backup. If a *distinct* secondary owner already occupies the slot, it is left untouched and the outgoing owner simply drops off. This fires on every owner change and is not reported in the response, so **re-read the document after reassigning** rather than assuming the secondary slot is unchanged.

- **A secondary owner equal to the primary owner is treated as no secondary owner.** It is returned as null and displayed as empty. This is why `list_documents_by_owner` describes matching a *distinct* secondary owner, and why a document can appear to gain a secondary owner the moment its primary changes.
- **To clear a secondary owner, pass `secondaryOwner: null`** on `edit_system` / `edit_policy` / `edit_training`. Omitting the field leaves it unchanged.

**Reassigning in bulk (e.g. someone leaving):** deleting a user in the app UI is the intended path — it asks for a replacement primary *and* secondary owner and swaps the departing person out of both slots across every document in one action, without triggering the auto-fill above. Reassigning documents one at a time instead means the auto-fill applies to each, so plan on a second pass to tidy the secondary slots.

## Seats

A **seat** is a licensed member of the workspace. Seat/member management — inviting people, allocating seats, changing who holds which role — is done in the **systemHUB app UI**.

> **MCP boundary (important for connecting agents):** the MCP can **read** the full access picture (members, roles, assignment type, agreement status, training progress) and can **write document-level access** — `manage_document_members` assigns or removes members and roles on a document, with `list_company_members` / `list_roles` to resolve names to UUIDs. What it can **not** do is seat provisioning: inviting new people to the workspace, allocating licences, or changing who holds which company role. That stays in the app UI — direct the user there.

## What agents can audit today

- `get_document_members_and_roles` — who can access a document, and how.
- `get_document_agreement_status` — who has agreed/signed off on a document (e.g. a policy acknowledgement).
- `get_document_training_progress` — for trainings, each assigned user's completion percentage and status.
- `get_document_activity_log` — who created and last modified a document, plus the event feed (`includeViews: true` to include views).
- `list_documents_by_owner` — everything a given person owns across systems, policies, and trainings, in one call.

> ⚠️ **`manage_document_members` with `action: "update"` REPLACES the document's assigned roles — it does not merge.** Passing a partial list silently removes every role you left out. To add or remove without collateral damage, use `action: "add"` / `"remove"`. Always confirm the result with `get_document_members_and_roles`.

> **Paginate deliberately.** The audit tools page their results. Pass `fetchAll: true` (the default on most) when you need a complete roster — a partial page will otherwise be reported as the whole answer, which is how an agent confidently states the wrong list of who has signed off.

Together these cover "who owns / can see / has completed what" — the read side of governance. The write side (provisioning) stays in the app for now.

Next: **[Authoring content →](/docs/concepts/authoring-content)**


---

# Sharing & links (https://systemhub.com/docs/concepts/sharing-and-links)

> Part of systemHUB Docs · Connect: Settings → AI Gateway in systemHUB · Auth: OAuth (scoping is workspace-level today — see Getting started) · MCP tools: 48 · Full corpus: https://systemhub.com/llms-full.txt

systemHUB documents can be reached two ways, and an agent should know which one it's handing out. They behave very differently.

## The two link types

| | App link | Share link |
|---|---|---|
| **Who can open it** | Logged-in members with access to that document | **Anyone with the URL — no login** |
| **What it shows** | The document in the systemHUB app | The **published** version, as machine-readable JSON |
| **Respects roles/visibility** | Yes — same access model as everything else | No — the link itself is the access |
| **Best for** | Team members working inside systemHUB | External contractors, auditors, clients — or **feeding a document to an AI that isn't connected via MCP** |

## App links

A regular link to a document inside the app. Opening it requires the person to log in and have access (via role or direct assignment — see [Roles & seats](/docs/concepts/roles-and-seats)). If they can't see the document in systemHUB, the link won't show it to them.

**An agent can construct an app link** from the workspace alias and the document UUID (which every tree, search, and details response carries):

```
https://{alias}.systemhub.com/systems/{uuid}     ← Systems
https://{alias}.systemhub.com/policies/{uuid}    ← Policies
https://{alias}.systemhub.com/trainings/{uuid}   ← Trainings
```

This also works in reverse: when a user pastes an app URL at you, the UUID in it is the same UUID the MCP tools address — extract it and call `get_system_details` (or the matching section's tool) directly. Caveats: this form **requires login** and access to the document, and the app won't error on a malformed UUID until after login — so treat a constructed link as "the right address," not proof the document exists.

> **Sending it to someone without a login?** Add the share code to make it public — see [the human-readable share link](#the-human-readable-share-link-use-this-one-for-people) below. (Both forms were surfaced by SYSTEMologists in the field.)

## Share links

A share link is a public URL for one document. Generate or retrieve one with:

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

Key behaviours:

- **Designed for no-login access.** The intent is that anyone holding the URL can fetch the published version as machine-readable JSON — the lightest-weight way to hand one process to an outside party or an AI without an MCP connection.
- **It reuses an existing share code** when the document already has one, and generates one if missing. Calling it twice doesn't create two links.
- ⚠️ **Share codes are not unique per document.** **Duplicating a document copies its share code**, so the copy and the original share one code (reported and reproduced across two document pairs, 4 Aug 2026). If you're building an index keyed on share codes, key on the document UUID instead — a share code can point at more than one document. Two code formats are also in circulation (longer codes on older documents, shorter on newer), so don't validate them by shape.
- **It shows the published version only** — unpublished edits stay private until published (see [Document lifecycle](/docs/concepts/document-lifecycle)).
- Generating one requires SHARE permission on that document type.

> ⚠️ **Known issue (verified 28 Jul 2026):** fetching the raw `api.systemhub.com/...` share URL from outside returns **403 "Company not found"** — that endpoint cannot resolve the workspace from the bare URL. Use the human-readable form below instead, which works.

## The human-readable share link (use this one for people)

Take the share code from `get_document_share_link` and put it on the **app host**, qualified by your workspace alias:

```
https://{alias}.systemhub.com/systems/{uuid}/{shareCode}
https://{alias}.systemhub.com/policies/{uuid}/{shareCode}
https://{alias}.systemhub.com/trainings/{uuid}/{shareCode}
```

**Verified 4 Aug 2026: this renders the published document in a browser with no login**, in a clean session — title, Overview and Details. A wrong or missing share code returns 404, so the code is doing the work, not an existing session.

- `{alias}` is your **company alias** — your systemHUB subdomain, the part before `.systemhub.com` (the same value used as the OAuth Client ID; find it in Settings → AI Gateway).
- `{uuid}` is the document ID, present on every tree, search and details response.
- `{shareCode}` is the trailing path segment of the `shareLink` returned by the share-link tool (or the `shareLink` field on `get_*_details`).

Two behaviours worth knowing when you construct or inspect these links:

- **The app rewrites to a guest route.** Opening the link lands on `/{section}/guest/{uuid}/{shareCode}?company={alias}` — the alias carried explicitly. That's expected; share the short form and let the app do the rewrite.
- **The section segment is not validated.** A system's UUID and code requested under `/policies/` still renders the system (reported 7 Aug 2026). So don't infer a document's section from the URL it was shared under — use `discriminator` on the document itself.

**This is the link to give a human.** It needs no login and no seat, which makes it the right answer for a contractor, an auditor, a client, or a team member on their phone.

> ⚠️ **Agents: you cannot fetch this form.** The share view is a client-rendered app, so a plain HTTP request (curl, an agent's fetch tool, a link unfurler, a preview bot) gets the JavaScript shell — *not* the document. It only renders in a real browser. Two consequences: don't try to read a document by fetching this URL (use `get_*_details` instead), and don't treat a 200 as proof the link is valid — **the 404 for a wrong share code is also rendered client-side**, so status codes tell you nothing here.
>
> **There is currently no share URL an external agent can fetch without a browser.** The `api.systemhub.com` form is the machine-readable one — it returns the published document as JSON — but it currently 403s externally (see the known issue above). Until that's fixed, hand share links to *people*, and give programs MCP access instead.

`get_*_details` responses include a `shareLink` field (the URL, or `null` if none exists).

## Rules for agents

- **Never hide an existing share link.** When presenting a document's details, always surface its share link if one exists — it's part of the document's identity, not metadata to trim.
- **Say which kind of link you're giving.** "Here's the share link (public, no login)" vs "here's the app link (they'll need to log in)". The difference matters to the user even when it doesn't matter to you.
- **Treat share links as public.** Before generating one, make sure the user understands anyone with the URL can read the document. Don't generate share links for sensitive documents unprompted.

Next: **[Errors & limits →](/docs/concepts/errors-and-limits)**


---

# Authoring content (https://systemhub.com/docs/concepts/authoring-content)

> Part of systemHUB Docs · Connect: Settings → AI Gateway in systemHUB · Auth: OAuth (scoping is workspace-level today — see Getting started) · MCP tools: 48 · Full corpus: https://systemhub.com/llms-full.txt

An agent that can call `create_system` is not yet an agent that produces *good* systemHUB documents. This page is the authoring contract: which HTML survives, which is silently changed, and the conventions that make a document genuinely usable. It is extracted from the live editor configuration (a custom CKEditor 5 build) and verified by round-trip audit — not guessed.

## The rule that matters most

> 🚨 **Send raw HTML, never entity-escaped HTML.** Write `<h2>Title</h2>`, not `&lt;h2&gt;Title&lt;/h2&gt;`. The API stores escaped content verbatim and returns success — but the document renders as visible tag soup (literal `<h2>` characters on screen). Nothing warns you. Escaping HTML while serialising into JSON is a classic agent failure mode: if your framework auto-escapes, unescape before sending, and read the document back after writing to confirm it rendered.

**The MCP/REST layer stores your HTML verbatim. The editor is the filter.** Content outside the supported set is not rejected at write time — it is silently removed or downgraded the first time a human opens the document in the editor and saves. No error is raised. So author *within* the supported set, or your content will change under the user's feet later.

## The four content fields

Every system, policy, and training document has four content areas. All except Title are rich text with the same formatting rules:

| Field | API parameter | Purpose |
|---|---|---|
| Title | `title` | Plain text, max 255 chars. |
| Overview | `description` | One or two sentences: what this is and why it matters. Not the steps. |
| Details (body) | `content` | The main content. Steps live here. |
| Notes | `note` | Internal notes for editors and reviewers. |

## Supported formatting (survives the editor)

- **Headings:** `<h1>`, `<h2>`, `<h3>` **only**. Use one `<h3>` per step.
- **Inline:** `<strong>`, `<i>`, `<u>`, `<s>`.
- **Highlights:** exactly four — `<mark class="marker-yellow">`, `marker-green`, `marker-blue`, `marker-pink`.
- **Text colour / font:** inline styles only — `style="color:#e74c3c"`, `font-size`, `font-family` (arbitrary values allowed).
- **Alignment / indent:** inline styles only — `style="text-align:center|right|justify"`, `style="margin-left:40px"` (40px steps).
- **Lists:** `<ul>` / `<ol>`, nesting fine. Checklists: `<ul class="todo-list"><li><label class="todo-list__label"><input type="checkbox" disabled><span class="todo-list__label__description">Task</span></label></li></ul>` (add `checked` for ticked).
- **Blocks:** `<blockquote>`, `<hr>`, code blocks `<pre><code class="language-python">` (24 languages incl. bash, javascript, sql, json, yaml).
- **Links:** `<a href>` — every link is forced to open in a new tab (`target="_blank"` added automatically).
- **Tables:** full support incl. header rows, `colspan`/`rowspan`, cell background colour, captions.
- **Video embeds:** paste the plain share URL, or write `<figure class="media"><oembed url="https://www.loom.com/share/abc"></oembed></figure>`. Auto-embed providers: YouTube, Vimeo, Wistia, Loom, Google Drive, ScribeHow, Pickaxe, Zoom clips, SharePoint, Dropbox mp4. NOT supported: Instagram, Twitter/X, Facebook, Maps, Flickr.
- **Emoji and unicode:** all fine.

## Silently stripped (do not use)

| Don't write | What happens / do instead |
|---|---|
| `<h4>` `<h5>` `<h6>` | Downgraded to plain paragraph. Only H1–H3 exist. |
| Inline `<code>` | Removed, text kept. Use a `<pre><code>` block instead. |
| `<sup>` / `<sub>` | Removed entirely. |
| `<mark>` without a `marker-*` class, or `pen-*` classes | Removed. Only the 4 markers survive. |
| `background-color` on a `<span>` | Removed. Use a marker highlight. |
| Formatting via CSS class (e.g. `class="text-center"`) | Ignored. Inline `style` only. |
| External images `<img src="https://…">` | **Removed entirely.** Images must be uploaded through the editor UI — the API cannot inject images. Mark the spot instead: `<p><mark class="marker-yellow">[Upload screenshot of the dashboard here]</mark></p>` |

**Auto-normalised (harmless):** `<b>`→`<strong>`, `<em>`→`<i>`, `<del>`→`<s>`; raw `<iframe>` becomes a responsive media wrapper.

## Structured fields are not body content

Email templates and video/media lists are structured data, not HTML:

- **Templates** (`{title, subject, details}`) — use `add_document_templates` / `edit_document_templates` / `remove_document_templates`.
- **Videos and media** (`{title, videoLink}`) — use `add_document_videos_and_media` / `remove_document_videos_and_media`.

Do not jam these into the `content` HTML; use the dedicated tools so they render in the app's Templates and Video & Media sections.

## Attachments: use `fileUrl`, not base64

`add_document_attachments` takes either `contentBase64` **or** `fileUrl` (a public HTTP(S) URL it fetches server-side). Prefer `fileUrl` for anything beyond a trivial file, and always when attaching in bulk — base64 sends the whole file through the tool call, so an agent pays for the content twice (once reading it, once writing it into the call). Any public URL works: a Drive share link, an S3 object, a static host. Attaching a dozen files by URL is a dozen two-line calls.

Two behaviours worth knowing before you script against it:

> **Attachments cannot be replaced.** Uploading a file whose name already exists on the document returns `skipped` with `reason: "duplicate"` and **leaves the original content in place** — it is not an error and it is not an overwrite. To ship a corrected file you must either use a different filename or delete the old attachment in the app, since the MCP has no delete.

- **Supported types are documents only**: PDF · `.doc/.docx/.docm` · `.xls/.xlsx/.xlsm` · `.ppt/.pptx/.pptm` · `.txt/.csv/.rtf` · `.md`. Anything else returns `skipped` with `reason: "invalid_type"` — **`.zip` is rejected**, so a multi-file kit cannot be attached as an archive. Images, MP3 and MP4 must be uploaded in the app.
- **Download URLs are public and unauthenticated.** The returned `downloadUrl` is a plain S3 object that anyone with the link can fetch, with no login. The path is UUID-based, so it is unguessable, but that is obscurity rather than access control — treat a leaked URL as permanent public read, and do not attach sensitive material to a document whose links get shared around.

## Size limit

Edits above roughly **126KB of content can fail with a 502**. `edit_*` replaces the entire `content` field on every call, so building a long document incrementally makes this *worse* — each edit resends everything written so far. Split genuinely large content across multiple documents instead.

## The anatomy of a good system (the SYSTEMology house format)

A real system answers four questions in order — *when does this run, what are the steps, how do you know it worked, and what does it look like done well*. Structure every draft as:

1. **Overview = context** (`description` field): what this system is and why it matters, 1–2 sentences.
2. **Trigger** — the first thing in the body: *when do you run this?* The event, schedule, or signal that kicks the system off ("When a new contract is signed…", "Every Monday before 10am…"). A system without a trigger never gets run.
3. **Steps** — numbered, each as an `<h3>`, action-first ("Send the welcome email", not "Welcome email"), in the order someone actually does the work.
4. **Definition of done** — the last section: *how do you know it worked?* The observable outcome ("The client has received the welcome email and the kickoff call is in both calendars"). Without it, "done" means "I stopped".

And the craft rules around that skeleton:

- **Yellow-highlight every genuine gap** the owner must fill (a name, link, threshold): `<p><mark class="marker-yellow">[Add the exact email template link here]</mark></p>`. Never invent specifics.
- **End with a "record it being done" note** — the best version of a system is screen-recorded while someone runs it, then refined.
- **First drafts get state ORANGE (`state: 1`, needs review)** so the owner knows to check and green-light it.

## Quick example

What an unbriefed agent writes (half disappears on first human save):

```html
<h4>Step 1</h4>
<p>Open the <code>CRM</code> and click <span style="background-color:yellow">New Deal</span>.</p>
<img src="https://example.com/screenshot.png">
```

systemHUB-ready:

```html
<h3>1. Create the new deal</h3>
<p>Open the CRM and click <strong>New Deal</strong>.</p>
<p><mark class="marker-yellow">[Upload a screenshot of the New Deal button here]</mark></p>
```

Next: **[Tool reference →](/docs/tool-reference)**


---

# Errors & limits (https://systemhub.com/docs/concepts/errors-and-limits)

> Part of systemHUB Docs · Connect: Settings → AI Gateway in systemHUB · Auth: OAuth (scoping is workspace-level today — see Getting started) · MCP tools: 48 · Full corpus: https://systemhub.com/llms-full.txt

The known failure modes, stated up front so a connecting agent handles them by design instead of flailing. If you hit behaviour not listed here, treat the [tool reference](/docs/tool-reference) (generated from the live schema) as the source of truth.

## Errors you will meet, and what they actually mean

| Symptom | Actual cause | What to do |
|---|---|---|
| `404` from `get_system_details` / `get_policy_details` / `get_training_details` | The document is a **master template** (`isMasterTemplate: true`) — its content lives in the master workspace only | Expected behaviour, not a missing document. Check `isMasterTemplate` on the tree/search result before fetching details. |
| `400` from `list_documents_by_owner` | The `owner` full name didn't match **exactly** (e.g. "Kristian Basilio" vs "Kristian Philippe Basilio") | Use the exact full name from a tree node, or the user UUID (`ownerId`) instead. |
| `502` on `edit_system` with a large body | Content above roughly **126KB** | **Split into multiple documents.** Note `edit_*` replaces the whole `content` field, so "writing in sections" means resending an ever-larger body — it reaches the ceiling sooner, not later. |
| Write/move/publish/delete fails on a document that clearly exists | It's a master template — they're immutable | Create your own document instead; see [organising guide](/docs/guides/organising-content). |
| Content you wrote looks different after a human edited the document | The **editor filtered it** — you authored outside the supported set | Not data loss at the API layer; re-author within the [authoring contract](/docs/concepts/authoring-content). |
| Document renders as **visible tag soup** (literal `<h2>` characters on screen) | You sent **HTML-escaped content** (`&lt;h2&gt;` instead of `<h2>`); the API stores it verbatim and returns success | Send raw HTML. Read the document back after writing to confirm rendering. |
| `403` "Company not found" fetching a **share link** externally | Known issue — the share endpoint can't resolve the workspace from the bare URL (verified 28 Jul 2026) | Tracked with the product team; test a share link before promising it to an outside party. See [Sharing & links](/docs/concepts/sharing-and-links). |

## Validation limits

| Field / parameter | Limit |
|---|---|
| `title` (documents, folders) | 255 characters, plain text |
| `publishTitle` (version label) | 255 characters |
| `state` | Integer 0–4 only — see [Document lifecycle](/docs/concepts/document-lifecycle) |
| `content` per edit | Keep under ~126KB (see above) |
| Search `limit` | ≤ 100 per page |
| `list_documents_by_owner` `limit` | ≤ 500 per page; `fetchAll: true` caps at 5,000 documents |
| Member/audit tools `limit` | ≤ 500 per page (`fetchAll` defaults true for complete audits) |

## Behaviours that surprise agents (by design, not bugs)

- **Create-with-content auto-publishes.** Assigned members see the document immediately; pass `publish: false` for a hidden draft. You do not need to ask the user to confirm publishing on create.
- **Every link opens in a new tab.** The editor forces `target="_blank"` on all links — don't try to control link behaviour.
- **Visibility follows the token, not the person.** Reads and writes are scoped to the identity on the workspace's most recently generated AI Gateway token — not necessarily whoever is connected (known issue, fix in progress). "Document not found" can simply mean *that identity* can't see it.
- **No seat provisioning, no deletes, no workspace-wide analytics** via the MCP — see [Known limits](/docs/#known-limits) and the [changelog](/docs/changelog) for what's recently landed (document-level member assignment and per-document activity logs are now available).

## Being a good citizen

There are no published rate limits, but the practical rules are: orient before acting (tree/search before create/edit), page with `fetchAll` rather than hammering per-item calls, and batch related edits rather than re-editing the same document dozens of times — each edit is a real revision in the document's history.


---

# Guide: draft an SOP into systemHUB (https://systemhub.com/docs/guides/drafting-sops)

> Part of systemHUB Docs · Connect: Settings → AI Gateway in systemHUB · Auth: OAuth (scoping is workspace-level today — see Getting started) · MCP tools: 48 · Full corpus: https://systemhub.com/llms-full.txt

The highest-value thing a connected agent can do: take what it knows about a business process and file it as a well-formed, reviewable system. This guide walks the full loop. Request/response bodies are **abridged and illustrative** — the authoritative contract for every parameter is the [tool reference](/docs/tool-reference).

## 1. Orient — find where the SOP belongs

Never create into a guessed location. Map the tree first:

```
→ get_folder_tree { }
```

```json
[
  {
    "id": "9f2e6c1a-…", "title": "1. Marketing", "type": 1, "state": 3,
    "owner": "Jane Smith", "isMasterTemplate": false,
    "children": [
      { "id": "4b8d0e7f-…", "title": "Publish the weekly newsletter", "type": 2, "state": 3 }
    ]
  },
  { "id": "c31a9d55-…", "title": "2. Sales", "type": 1, "state": 3, "children": [ … ] }
]
```

`type` 1 = folder, 2 = document. Skip anything with `isMasterTemplate: true` — that's read-only reference content.

If the right department folder doesn't exist, create it:

```
→ create_folder { "parent": "root", "title": "3. Client Delivery" }
```

## 2. Check it doesn't already exist

```
→ search_by_name { "query": "onboard" }
```

If a near-match exists, read it with `get_system_details` and decide: update the existing document (usually right) or create a genuinely distinct one. Duplicate systems are worse than missing ones.

## 3. Create the system

Write to the [authoring contract](/docs/concepts/authoring-content): Overview in `description`, one `<h3>` per step in `content`, yellow marks for every gap you can't fill truthfully, and `state: 1` (ORANGE, needs review) so a human knows to check it.

```
→ create_system {
    "parent": "c31a9d55-…",
    "title": "Onboard a new client",
    "description": "How we take a signed client from contract to kickoff call, so every client gets the same first week.",
    "content": "<p><strong>Trigger:</strong> a new client contract is signed.</p><h3>1. Send the welcome email</h3><p>Send within 24 hours of the signed contract. Use the template in the Templates section of this document.</p><p><mark class=\"marker-yellow\">[Confirm who sends this — currently unassigned]</mark></p><h3>2. Book the kickoff call</h3><p>30 minutes, within the first week.</p><h3>3. Done when</h3><p>The client has received the welcome email and the kickoff call is in both calendars.</p><p><strong>Tip:</strong> next time you run this process, screen-record it and embed the video here — the recorded version beats the written one.</p>",
    "note": "Drafted by AI from the intake call on 22 Jul. Steps 4-6 (billing setup) still to be captured.",
    "state": 1
  }
```

```json
{ "id": "7d4f2a90-…", "title": "Onboard a new client", "state": 1, "published": true }
```

**Publishing behaviour:** creating a document *with content* auto-publishes it — assigned members can see it immediately, and you don't need to ask the user to confirm. Pass `"publish": false` to keep it as a hidden draft instead. See [Document lifecycle](/docs/concepts/document-lifecycle).

## 4. Attach the structured extras

Email templates and videos are structured fields, not body HTML:

```
→ add_document_templates {
    "id": "7d4f2a90-…",
    "templates": [{ "title": "Client welcome email", "subject": "Welcome aboard!", "details": "<p>Hi {first name}, …</p>" }]
  }
```

```
→ add_document_videos_and_media {
    "id": "7d4f2a90-…",
    "videosAndMedia": [{ "title": "Kickoff call walkthrough", "videoLink": "https://www.loom.com/share/…" }]
  }
```

## 5. Revise and cut a version

Later edits go through `edit_system`; when a revision is ready for assigned members, cut an explicit version:

```
→ edit_system { "id": "7d4f2a90-…", "content": "<h3>1. …updated steps…</h3>" }
→ publish_system { "id": "7d4f2a90-…", "publishTitle": "v1.1 - Added billing setup steps" }
```

## The checklist

- [ ] Oriented with `get_folder_tree`, searched for duplicates first
- [ ] Overview in `description`, steps as `<h3>` in `content`, internal context in `note`
- [ ] **Trigger stated up front** (when does this run?) and a **definition of done** at the end (how do you know it worked?)
- [ ] Only [supported formatting](/docs/concepts/authoring-content) — no inline `code`, no external images
- [ ] Every unknown yellow-marked, nothing invented
- [ ] `state: 1` (ORANGE) so the owner reviews before it turns GREEN
- [ ] Templates/media added via their dedicated tools, not jammed into the body
- [ ] Ends with the "record it being done" tip


---

# Guide: audit access, sign-off & training (https://systemhub.com/docs/guides/auditing-access)

> Part of systemHUB Docs · Connect: Settings → AI Gateway in systemHUB · Auth: OAuth (scoping is workspace-level today — see Getting started) · MCP tools: 48 · Full corpus: https://systemhub.com/llms-full.txt

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](/docs/tool-reference) for the full contracts.

## Who can access this document, and how?

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

```json
{
  "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](/docs/concepts/roles-and-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 }
```

```json
[
  { "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.


---

# Guide: organise & maintain the library (https://systemhub.com/docs/guides/organising-content)

> Part of systemHUB Docs · Connect: Settings → AI Gateway in systemHUB · Auth: OAuth (scoping is workspace-level today — see Getting started) · MCP tools: 48 · Full corpus: https://systemhub.com/llms-full.txt

Folders, moves, renames, and the habits that keep a systemHUB library navigable as it grows. Bodies are **abridged and illustrative** — full contracts in the [tool reference](/docs/tool-reference).

## The shape of a good library

systemHUB libraries work best organised **by department, in run-order**, with numbered folder prefixes so the tree reads top-to-bottom:

```
1. Marketing
2. Sales
3. Client Delivery
4. Finance
5. HR
6. Operations
```

Documents inside are **named as actions** ("Onboard a new client", "Reconcile the weekly payments") — a title should say what running the system achieves.

## Working with folders

Each section has its own folder tools:

```
// Top-level folder — OMIT parent entirely (it must be a UUID; "root" is rejected)
→ create_folder          { "title": "3. Client Delivery" }                      // Systems
→ create_policy_folder   { "title": "HR Policies" }                             // Policies
→ create_training_folder { "title": "New Starter Training" }                    // Trainings

// Nested folder — parent is the UUID of an existing folder
→ create_folder          { "parent": "c31a9d55-…", "title": "Onboarding" }
```

> ⚠️ `"parent": "root"` is valid on `get_folder_tree` but **not** on the create tools, where `parent` is typed as a UUID. Passing it returns `Invalid uuid`. Omit the field for top level.

Rename with `rename_system_folder` / `rename_policy_folder` / `rename_training_folder`; relocate documents with `move_system` / `move_policy` / `move_training`.

**Rule: read before you restructure.** Always `get_folder_tree` first and confirm with the user before bulk moves — folder structure is something teams navigate by muscle memory, and a "tidy up" an owner didn't ask for is a regression, not a favour.

## Keeping states honest

The review cycle runs on document states (see [Document lifecycle](/docs/concepts/document-lifecycle)):

- New AI drafts → `state: 1` (ORANGE) so a human reviews them.
- A useful maintenance sweep: report the library's review debt by owner. **Use `reviewDate`, not `state`** — every tree, search and details response carries `reviewDate` (ISO 8601, or `null` if unset), so compare it to today. Documents in `state: 2` (RED) are *also* worth reporting, but don't rely on RED alone: it doesn't set itself, so a library full of lapsed reviews can report zero debt while every `reviewDate` is months past. The two useful buckets are **past `reviewDate`** and **no `reviewDate` set at all**.
- Don't set documents to GREEN (`state: 3`) yourself unless the user explicitly says the content is approved. Approval is a human call.

## Master templates

Trees include master-template content (`isMasterTemplate: true`) supplied from the master workspace: browsable for reference, **never editable** — edit/move/publish/delete all fail, and `get_*_details` returns `404` on them by design. When a user wants "their own version" of a master template, read the template's *structure* from the tree, then create a fresh document in their folders and author it for their business.

## Tags

`add_document_tags` / `remove_document_tags` attach tags to any document — useful for cross-cutting views the folder tree can't express (e.g. tag everything touching a software tool, a compliance regime, or a client type). Keep the tag set small and deliberate; fifty ad-hoc tags are worse than none.

## Learning tracks

For trainings, `create_training_learning_track` / `edit_training_learning_track` / `remove_training_learning_tracks` group training documents into ordered tracks (e.g. "New starter week 1"). Pair with `get_document_training_progress` to report completion per track — see the [auditing guide](/docs/guides/auditing-access).


---

> **This page is generated from the live systemHUB MCP schemas.** A hand-written reference drifts, and a client's AI flails when the docs say X and the tool does Y. This reference is regenerated from the schema snapshot on every deploy so it cannot lie. Guides and examples are hand-written; this reference is not.
>
> Because it mirrors the schema faithfully, it also reproduces the schema's known inaccuracies until they're fixed upstream. Where this page conflicts with the concepts pages, **the concepts pages win** — currently one known case: the schema describes `description` as "plain-text", but the field holds rich text (it's the Overview, same editor rules as the body — see [Authoring content](concepts/authoring-content)). A schema fix is logged.

Documents are addressed by **UUID**. States are integers — see [Document lifecycle](concepts/document-lifecycle) (`0` GREY draft · `1` ORANGE needs-review · `2` RED overdue · `3` GREEN approved · `4` PURPLE archived). Node/item `type`: `1` = FOLDER, `2` = DOCUMENT.

## Discovery & navigation

### `get_folder_tree`

Returns the hierarchical folder and document tree for the Systems section of SystemHub. Each node includes its ID, title, type (1=FOLDER, 2=DOCUMENT), document state, owner full name, ownerId for filtering, optional secondary owner full name, publication status, isMasterTemplate, isRootMasterTemplate, and nested children. Optionally scope the result to a specific subtree by providing a parent folder UUID. Filter by type to get only folders or only documents. Filter by role to see items assigned to a specific role. Use this tool first to understand the organizational structure before navigating to specific documents. Use ownerId for programmatic owner-based filtering. Results include both operational content (company-owned) and master templates (read-only reference content from the master workspace). Each node/item has isMasterTemplate; tree nodes also have isRootMasterTemplate. When the user asks about their own content, filter to isMasterTemplate=false. Do not edit, delete, move, or publish master templates. get_*_details on master template documents returns 404 — content lives in the master workspace only. Templates appear in trees for browsing.

| Parameter | Type | Required | Notes |
|---|---|---|---|
| `parent` | string (uuid) | No | UUID of parent folder or "root" to scope the subtree |
| `type` | integer | No | Filter by type: 1=FOLDER, 2=DOCUMENT |
| `role` | string (uuid) | No | Filter by role UUID to show only items assigned to that role |

**Returns**

| Field | Type | Notes |
|---|---|---|
| `tree` | array of object | Contains: `id`, `title`, `type`, `state`, `parent`, `ownerId`, `owner`, `secondaryOwnerId`, `secondaryOwner`, `published`, `isMasterTemplate`, `isRootMasterTemplate`… |

### `get_policy_tree`

Returns the hierarchical folder and document tree for the Policies section of SystemHub. Each node includes its ID, title, type (1=FOLDER, 2=DOCUMENT), document state, owner full name, ownerId for filtering, optional secondary owner full name, publication status, isMasterTemplate, isRootMasterTemplate, and nested children. Optionally scope the result to a specific subtree by providing a parent folder UUID. Filter by type to get only folders or only documents. Filter by role to see items assigned to a specific role. Use ownerId for programmatic owner-based filtering. Results include both operational content (company-owned) and master templates (read-only reference content from the master workspace). Each node/item has isMasterTemplate; tree nodes also have isRootMasterTemplate. When the user asks about their own content, filter to isMasterTemplate=false. Do not edit, delete, move, or publish master templates. get_*_details on master template documents returns 404 — content lives in the master workspace only. Templates appear in trees for browsing.

| Parameter | Type | Required | Notes |
|---|---|---|---|
| `parent` | string (uuid) | No | UUID of parent folder or "root" to scope the subtree |
| `type` | integer | No | Filter by type: 1=FOLDER, 2=DOCUMENT |
| `role` | string (uuid) | No | Filter by role UUID to show only items assigned to that role |

**Returns**

| Field | Type | Notes |
|---|---|---|
| `tree` | array of object | Contains: `id`, `title`, `type`, `state`, `parent`, `ownerId`, `owner`, `secondaryOwnerId`, `secondaryOwner`, `published`, `isMasterTemplate`, `isRootMasterTemplate`… |

### `get_training_tree`

Returns the hierarchical folder and training document tree for the Training section of SystemHub. Each node includes its ID, title, type (1=FOLDER, 2=DOCUMENT), document state, owner full name, ownerId for filtering, optional secondary owner full name, publication status, isMasterTemplate, isRootMasterTemplate, and nested children. Optionally scope the result to a specific subtree by providing a parent folder UUID. Filter by type to get only folders or only trainings. Filter by role to see items assigned to a specific role. Use this tool first to understand the organizational structure before navigating to specific trainings. Use ownerId for programmatic owner-based filtering. Results include both operational content (company-owned) and master templates (read-only reference content from the master workspace). Each node/item has isMasterTemplate; tree nodes also have isRootMasterTemplate. When the user asks about their own content, filter to isMasterTemplate=false. Do not edit, delete, move, or publish master templates. get_*_details on master template documents returns 404 — content lives in the master workspace only. Templates appear in trees for browsing.

| Parameter | Type | Required | Notes |
|---|---|---|---|
| `parent` | string (uuid) | No | UUID of parent folder or "root" to scope the subtree |
| `type` | integer | No | Filter by type: 1=FOLDER, 2=DOCUMENT |
| `role` | string (uuid) | No | Filter by role UUID to show only items assigned to that role |

**Returns**

| Field | Type | Notes |
|---|---|---|
| `tree` | array of object | Contains: `id`, `title`, `type`, `state`, `parent`, `ownerId`, `owner`, `secondaryOwnerId`, `secondaryOwner`, `published`, `isMasterTemplate`, `isRootMasterTemplate`… |

### `search_by_name`

Searches for system documents and folders by title using case-insensitive partial matching. Returns a paginated list of matching items with their ID, title, type (1=FOLDER, 2=DOCUMENT), document state, discriminator, owner full name, ownerId, optional secondary owner full name, shareLink (public web URL or null), document content, tags, templates (numbered, with title/subject/details), Videos & Media (numbered media links with title and videoLink), attachments (folder/file tree with download URLs), comments (discussion threads with nested replies), and isMasterTemplate. Use the 'page' and 'limit' parameters to control pagination. This is useful for finding specific documents when you don't know their UUID or location in the folder tree. Use ownerId for programmatic owner-based filtering. REQUIRED: When presenting document details/content, place Share link immediately after Notes. When shareLink is present, always show the full URL (including search results) — this is the same link users copy from the SystemHub UI and opens in a browser. Never hide an existing share link. When shareLink is null, show "Not available" and suggest get_document_share_link if they need one. Results include both operational content (company-owned) and master templates (read-only reference content from the master workspace). Each node/item has isMasterTemplate; tree nodes also have isRootMasterTemplate. When the user asks about their own content, filter to isMasterTemplate=false. Do not edit, delete, move, or publish master templates. get_*_details on master template documents returns 404 — content lives in the master workspace only. Templates appear in trees for browsing.

| Parameter | Type | Required | Notes |
|---|---|---|---|
| `query` | string | Yes | Search string to match against document/folder titles |
| `page` | integer | No | Page number (default 1) |
| `limit` | integer | No | Results per page (default 20, max 100) |

**Returns**

| Field | Type | Notes |
|---|---|---|
| `items` | array of object | Contains: `id`, `title`, `type`, `state`, `discriminator`, `parent`, `ownerId`, `owner`, `secondaryOwnerId`, `secondaryOwner`, `createdAt`, `reviewDate`… |

### `search_policy`

Searches for policy documents and folders by title using case-insensitive partial matching. Returns a paginated list of matching items with their ID, title, type (1=FOLDER, 2=DOCUMENT), document state, discriminator, owner full name, ownerId, optional secondary owner full name, shareLink (public web URL or null), document content, tags, templates (numbered, with title/subject/details), Videos & Media (numbered media links with title and videoLink), attachments (folder/file tree with download URLs), comments (discussion threads with nested replies), and isMasterTemplate. Use the 'page' and 'limit' parameters to control pagination. Use ownerId for programmatic owner-based filtering. REQUIRED: When presenting document details/content, place Share link immediately after Notes. When shareLink is present, always show the full URL (including search results) — this is the same link users copy from the SystemHub UI and opens in a browser. Never hide an existing share link. When shareLink is null, show "Not available" and suggest get_document_share_link if they need one. Results include both operational content (company-owned) and master templates (read-only reference content from the master workspace). Each node/item has isMasterTemplate; tree nodes also have isRootMasterTemplate. When the user asks about their own content, filter to isMasterTemplate=false. Do not edit, delete, move, or publish master templates. get_*_details on master template documents returns 404 — content lives in the master workspace only. Templates appear in trees for browsing.

| Parameter | Type | Required | Notes |
|---|---|---|---|
| `query` | string | Yes | Search string to match against document/folder titles |
| `page` | integer | No | Page number (default 1) |
| `limit` | integer | No | Results per page (default 20, max 100) |

**Returns**

| Field | Type | Notes |
|---|---|---|
| `items` | array of object | Contains: `id`, `title`, `type`, `state`, `discriminator`, `parent`, `ownerId`, `owner`, `secondaryOwnerId`, `secondaryOwner`, `createdAt`, `reviewDate`… |

### `search_training`

Searches for training documents and folders by title using case-insensitive partial matching. Returns a paginated list of matching items with their ID, title, type (1=FOLDER, 2=DOCUMENT), document state, discriminator, owner full name, ownerId, optional secondary owner full name, shareLink (public web URL or null), document content, tags, templates (numbered, with title/subject/details), Videos & Media (numbered media links with title and videoLink), attachments (folder/file tree with download URLs), comments (discussion threads with nested replies), learning tracks (numbered curriculum steps for training documents), and isMasterTemplate. Use the 'page' and 'limit' parameters to control pagination. Use ownerId for programmatic owner-based filtering. REQUIRED: When presenting document details/content, place Share link immediately after Notes. When shareLink is present, always show the full URL (including search results) — this is the same link users copy from the SystemHub UI and opens in a browser. Never hide an existing share link. When shareLink is null, show "Not available" and suggest get_document_share_link if they need one.

| Parameter | Type | Required | Notes |
|---|---|---|---|
| `query` | string | Yes | Search string to match against training document/folder titles |
| `page` | integer | No | Page number (default 1) |
| `limit` | integer | No | Results per page (default 20, max 100) |

**Returns**

| Field | Type | Notes |
|---|---|---|
| `items` | array of object | Contains: `id`, `title`, `type`, `state`, `discriminator`, `parent`, `ownerId`, `owner`, `secondaryOwnerId`, `secondaryOwner`, `createdAt`, `reviewDate`… |

### `list_documents_by_owner`

Returns a flat, paginated list of SystemHub documents (systems + policies + trainings) filtered by primary owner, secondary owner, and/or role — in one call, without per-document detail requests. Each item includes id, title, type (1=FOLDER, 2=DOCUMENT), state, section (discriminator), folder path (materializedPath), and owner metadata. Use owner or secondaryOwner as a user UUID or full name. Use ownership=either (default) to find documents where someone is primary OR distinct secondary owner — e.g. "list everything owned by [person UUID]". Use roleId to filter by assigned role. Omit section to search all three areas at once. Set fetchAll=true to retrieve every matching document across pages (up to 5000). Use ownerId for programmatic owner-based filtering.

| Parameter | Type | Required | Notes |
|---|---|---|---|
| `owner` | string | No | Primary owner UUID or full name (e.g. "Jane Smith"). Required unless secondaryOwner or roleId is set. |
| `secondaryOwner` | string | No | Secondary owner UUID or full name. When set alone, returns documents with this distinct secondary owner. |
| `roleId` | string (uuid) | No | Role UUID. Returns documents assigned to this role. |
| `ownership` | enum: `primary` · `secondary` · `either` | No | How to match owner when owner is set: primary (owner_id only), secondary (distinct secondary owner only), either (primary OR distinct secondary). Default: either. |
| `section` | enum: `system` · `policy` · `training` | No | Limit to one section. Omit to search systems, policies, and trainings together. |
| `type` | integer | No | Item type: 1=FOLDER, 2=DOCUMENT. Default 2 (documents only). |
| `page` | integer | No | Page number (default 1) |
| `limit` | integer | No | Results per page (default 100, max 500). Use fetchAll to retrieve every matching document. |
| `fetchAll` | boolean | No | When true, automatically fetches all pages (up to 5000 documents) so you get every match in one response. |

**Returns**

| Field | Type | Notes |
|---|---|---|
| `items` | array of object | Contains: `id`, `title`, `type`, `state`, `discriminator`, `materializedPath`, `parent`, `ownerId`, `owner`, `secondaryOwnerId`, `secondaryOwner` |
| `page` | integer |  |
| `limit` | integer |  |
| `hasMore` | boolean | True when more pages are available — increase page or set fetchAll. |

## Reading documents

### `get_system_details`

Retrieves the full details of a system document by UUID, including its title, document state (0=GREY/draft, 1=ORANGE/needs-review, 2=RED/overdue, 3=GREEN/approved, 4=PURPLE/archived), HTML content, description, internal notes, tags, templates (numbered, with title/subject/details), Videos & Media (numbered media links with title and videoLink), attachments (folder/file tree with download URLs), comments (discussion threads with author, text, and nested replies), owner full name, ownerId, optional secondary owner full name, review date, isMasterTemplate, shareLink (public web URL or null), and publication status. Use this after finding a document via search_by_name or get_folder_tree to read its content. Check isMasterTemplate from tree/search before calling — master template documents return 404 here. CRITICAL: If shareLink is a non-null URL, you MUST display it in a Share link section whenever you present document details or content — never omit an existing share link.

| Parameter | Type | Required | Notes |
|---|---|---|---|
| `id` | string (uuid) | Yes | UUID of the system document |

**Returns**

| Field | Type | Notes |
|---|---|---|
| `id` | string (uuid) | Unique identifier of the system document |
| `title` | string | Display name of the system document |
| `type` | number | Item type: 1=FOLDER, 2=DOCUMENT |
| `state` | number | Document state: 0=GREY/draft, 1=ORANGE/needs-review, 2=RED/overdue, 3=GREEN/approved, 4=PURPLE/archived |
| `discriminator` | string | Item category: System, Policy, or Training |
| `parent` | string (uuid) or null | UUID of the parent folder, or null for root items |
| `ownerId` | string (uuid) or null | UUID of the primary owner — use for owner-based filtering |
| `owner` | string or null | Full name of the primary owner |
| `secondaryOwnerId` | string (uuid) | UUID of the secondary owner — omitted when not set |
| `secondaryOwner` | string | Full name of the secondary owner — omitted when not set |
| `createdAt` | string | ISO timestamp of when the document was created |
| `reviewDate` | string or null | ISO timestamp of the next scheduled review, or null if not set |
| `isMasterTemplate` | boolean | True if this item is a read-only master template from the master workspace, not company-owned operational content. When the user asks about their own content, filter to isMasterTemplate=false. |
| `shareLink` | string (uri) or null | Public share URL matching the SystemHub UI (e.g. https://{company}.systemhub.com/systems/{id}/{shareCode}). Always surface this to the user when non-null. Null when no share code exists, the item is a folder, or the user lacks SHARE permission. |
| `document` | object or null | Document content details, or null for folders |
| `tags` | array of object | Tags associated with this system document Contains: `id`, `title`, `createdAt` |
| `templates` | array of object | Numbered document templates (title, subject, details) attached to this system document Contains: `number`, `title`, `subject`, `details` |
| `videosAndMedia` | array of object | Videos & Media — numbered media links (title, videoLink) on this system document Contains: `number`, `id`, `title`, `videoLink` |
| `attachments` | array of object | Attachments — tree of folders and files on this document. Files include downloadUrl for downloading the attached file. Contains: `id`, `title`, `type`, `downloadUrl`, `children` |
| `comments` | array of object | Comments — discussion threads on this system document, each with nested replies Contains: `id`, `createdAt`, `author`, `text`, `quote`, `topicType`, `replies` |

### `get_policy_details`

Retrieves the full details of a policy document by UUID, including its title, document state (0=GREY/draft, 1=ORANGE/needs-review, 2=RED/overdue, 3=GREEN/approved, 4=PURPLE/archived), HTML content, description, internal notes, tags, templates (numbered, with title/subject/details), Videos & Media (numbered media links with title and videoLink), attachments (folder/file tree with download URLs), comments (discussion threads with author, text, and nested replies), owner full name, ownerId, optional secondary owner full name, review date, isMasterTemplate, shareLink (public web URL or null). Check isMasterTemplate from tree/search before calling — master template documents return 404 here. CRITICAL: If shareLink is a non-null URL, you MUST display it in a Share link section whenever you present document details or content — never omit an existing share link.

| Parameter | Type | Required | Notes |
|---|---|---|---|
| `id` | string (uuid) | Yes | UUID of the policy document |

**Returns**

| Field | Type | Notes |
|---|---|---|
| `id` | string (uuid) | Unique identifier of the policy document |
| `title` | string | Display name of the policy document |
| `type` | number | Item type: 1=FOLDER, 2=DOCUMENT |
| `state` | number | Document state: 0=GREY/draft, 1=ORANGE/needs-review, 2=RED/overdue, 3=GREEN/approved, 4=PURPLE/archived |
| `discriminator` | string | Item category: System, Policy, or Training |
| `parent` | string (uuid) or null | UUID of the parent folder, or null for root items |
| `ownerId` | string (uuid) or null | UUID of the primary owner — use for owner-based filtering |
| `owner` | string or null | Full name of the primary owner |
| `secondaryOwnerId` | string (uuid) | UUID of the secondary owner — omitted when not set |
| `secondaryOwner` | string | Full name of the secondary owner — omitted when not set |
| `createdAt` | string | ISO timestamp of when the document was created |
| `reviewDate` | string or null | ISO timestamp of the next scheduled review, or null if not set |
| `isMasterTemplate` | boolean | True if this item is a read-only master template from the master workspace, not company-owned operational content. When the user asks about their own content, filter to isMasterTemplate=false. |
| `shareLink` | string (uri) or null | Public share URL matching the SystemHub UI (e.g. https://{company}.systemhub.com/systems/{id}/{shareCode}). Always surface this to the user when non-null. Null when no share code exists, the item is a folder, or the user lacks SHARE permission. |
| `document` | object or null | Document content details, or null for folders |
| `tags` | array of object | Tags associated with this policy document Contains: `id`, `title`, `createdAt` |
| `templates` | array of object | Numbered document templates (title, subject, details) attached to this policy document Contains: `number`, `title`, `subject`, `details` |
| `videosAndMedia` | array of object | Videos & Media — numbered media links (title, videoLink) on this policy document Contains: `number`, `id`, `title`, `videoLink` |
| `attachments` | array of object | Attachments — tree of folders and files on this document. Files include downloadUrl for downloading the attached file. Contains: `id`, `title`, `type`, `downloadUrl`, `children` |
| `comments` | array of object | Comments — discussion threads on this policy document, each with nested replies Contains: `id`, `createdAt`, `author`, `text`, `quote`, `topicType`, `replies` |

### `get_training_details`

Retrieves the full details of a training document by UUID, including its title, document state (0=GREY/draft, 1=ORANGE/needs-review, 2=RED/overdue, 3=GREEN/approved, 4=PURPLE/archived), HTML content, description, internal notes, tags, templates (numbered, with title/subject/details), Videos & Media (numbered media links with title and videoLink), attachments (folder/file tree with download URLs), comments (discussion threads with author, text, and nested replies), learning tracks (numbered curriculum steps with linked document UUIDs), owner full name, ownerId, optional secondary owner full name, review date, isMasterTemplate, shareLink (public web URL or null), and whether it has learning tracks. Use this after finding a training via search_training or get_training_tree to read its content. Check isMasterTemplate from tree/search before calling — master template documents return 404 here. CRITICAL: If shareLink is a non-null URL, you MUST display it in a Share link section whenever you present document details or content — never omit an existing share link.

| Parameter | Type | Required | Notes |
|---|---|---|---|
| `id` | string (uuid) | Yes | UUID of the training document |

**Returns**

| Field | Type | Notes |
|---|---|---|
| `id` | string (uuid) | Unique identifier of the training document |
| `title` | string | Display name of the training document |
| `type` | number | Item type: 1=FOLDER, 2=DOCUMENT |
| `state` | number | Document state: 0=GREY/draft, 1=ORANGE/needs-review, 2=RED/overdue, 3=GREEN/approved, 4=PURPLE/archived |
| `discriminator` | string | Item category: System, Policy, or Training |
| `parent` | string (uuid) or null | UUID of the parent folder, or null for root items |
| `ownerId` | string (uuid) or null | UUID of the primary owner — use for owner-based filtering |
| `owner` | string or null | Full name of the primary owner |
| `secondaryOwnerId` | string (uuid) | UUID of the secondary owner — omitted when not set |
| `secondaryOwner` | string | Full name of the secondary owner — omitted when not set |
| `createdAt` | string | ISO timestamp of when the training was created |
| `reviewDate` | string or null | ISO timestamp of the next scheduled review, or null if not set |
| `isLearningTrack` | boolean | Whether this training document has learning track curriculum steps |
| `hasLearningTracks` | boolean | Whether this training document has at least one learning track step |
| `isMasterTemplate` | boolean | True if this item is a read-only master template from the master workspace, not company-owned operational content. When the user asks about their own content, filter to isMasterTemplate=false. |
| `shareLink` | string (uri) or null | Public share URL matching the SystemHub UI (e.g. https://{company}.systemhub.com/systems/{id}/{shareCode}). Always surface this to the user when non-null. Null when no share code exists, the item is a folder, or the user lacks SHARE permission. |
| `document` | object or null | Document content details, or null for folders |
| `tags` | array of object | Tags associated with this training document Contains: `id`, `title`, `createdAt` |
| `templates` | array of object | Numbered document templates (title, subject, details) attached to this training document Contains: `number`, `title`, `subject`, `details` |
| `videosAndMedia` | array of object | Videos & Media — numbered media links (title, videoLink) on this training document Contains: `number`, `id`, `title`, `videoLink` |
| `attachments` | array of object | Attachments — tree of folders and files on this document. Files include downloadUrl for downloading the attached file. Contains: `id`, `title`, `type`, `downloadUrl`, `children` |
| `comments` | array of object | Comments — discussion threads on this training document, each with nested replies Contains: `id`, `createdAt`, `author`, `text`, `quote`, `topicType`, `replies` |
| `learningTracks` | array of object | Learning track curriculum steps for this training document, ordered by sortOrder Contains: `number`, `id`, `baseItem`, `title`, `estimatedTime`, `discriminator`, `sortOrder`, `createdAt` |

## Access, agreement & progress

### `get_document_members_and_roles`

Retrieves assigned members and roles for a system, policy, or training document. Returns roles assigned to the document plus each member's name, email, role title(s), and access type (direct assignment, role-based, or both). Use after finding the document UUID via search_by_name, search_policy, or search_training. Respects the authenticated user's visibility scope. Set fetchAll=true (default) for a complete access audit.

| Parameter | Type | Required | Notes |
|---|---|---|---|
| `documentId` | string (uuid) | Yes | UUID of the system, policy, or training document. Find it via search_by_name, search_policy, search_training, or get_*_details. |
| `topicType` | enum: `system` · `policy` · `training` | Yes | Document section: "system" for procedures, "policy" for compliance documents, "training" for learning modules. |
| `search` | string | No | Optional filter — partial match on member first name, last name, or email |
| `page` | integer | No | Page number when not using fetchAll (default 1) |
| `limit` | integer | No | Results per page when not using fetchAll (default 100, max 500) |
| `fetchAll` | boolean | No | When true (default), fetches all assigned roles and members across pages (up to 5000 users) for a complete access audit. |

**Returns**

| Field | Type | Notes |
|---|---|---|
| `documentId` | string (uuid) | UUID of the document queried |
| `topicType` | enum: `system` · `policy` · `training` | Document section that was queried |
| `summary` | object | Contains: `assignedRoleCount`, `directMemberCount`, `roleMemberCount`, `totalUniqueMembers` |
| `assignedRoles` | array of object | Roles currently assigned to this document Contains: `roleId`, `roleTitle`, `description`, `membersAmount` |
| `members` | array of object | All members with access, deduplicated by user Contains: `userId`, `userName`, `firstName`, `lastName`, `email`, `userRole`, `accessType`, `roles` |

### `get_document_agreement_status`

Retrieves sign-off / agreement status for a system, policy, or training document. Returns who has signed off (with timestamp) and who is still pending acknowledgement among users assigned to the document. Use after finding the document UUID via search_by_name, search_policy, or search_training. Respects the authenticated user's visibility scope on the item API. Set fetchAll=true (default) for a complete audit list.

| Parameter | Type | Required | Notes |
|---|---|---|---|
| `documentId` | string (uuid) | Yes | UUID of the system, policy, or training document. Find it via search_by_name, search_policy, search_training, or get_*_details. |
| `topicType` | enum: `system` · `policy` · `training` | Yes | Document section: "system" for procedures, "policy" for compliance documents, "training" for learning modules. |
| `firstName` | string | No | Optional filter — partial match on user first or last name |
| `lastName` | string | No | Optional filter — partial match on user first or last name |
| `page` | integer | No | Page number when not using fetchAll (default 1) |
| `limit` | integer | No | Results per page when not using fetchAll (default 100, max 500) |
| `fetchAll` | boolean | No | When true (default), automatically fetches every assigned user across pages (up to 5000) so signed-off and pending lists are complete. |

**Returns**

| Field | Type | Notes |
|---|---|---|
| `documentId` | string (uuid) | UUID of the document queried |
| `topicType` | enum: `system` · `policy` · `training` | Document section that was queried |
| `summary` | object | High-level compliance counts Contains: `totalAssigned`, `signedOffCount`, `pendingCount` |
| `signedOffUsers` | array of object | Users who have confirmed agreement, with sign-off timestamp Contains: `userId`, `firstName`, `lastName`, `email`, `fullName`, `signedOffAt`, `agreementLogId` |
| `pendingUsers` | array of object | Users assigned to the document who have not yet signed off Contains: `userId`, `firstName`, `lastName`, `email`, `fullName` |
| `hasMore` | boolean | True when pagination was used and more pages may exist — increase page or set fetchAll=true |

### `get_document_training_progress`

Retrieves learning completion progress for a training document. Returns each assigned user's percentage complete (based on learning track sign-offs), status (complete, in progress, or not started), and last update time. Use after finding the training UUID via search_training or get_training_details. Respects the authenticated user's visibility scope. Set fetchAll=true (default) for a complete audit list.

| Parameter | Type | Required | Notes |
|---|---|---|---|
| `documentId` | string (uuid) | Yes | UUID of the training document. Find it via search_training or get_training_details — training progress only applies to training documents. |
| `firstName` | string | No | Optional filter — partial match on user first or last name |
| `lastName` | string | No | Optional filter — partial match on user first or last name |
| `page` | integer | No | Page number when not using fetchAll (default 1) |
| `limit` | integer | No | Results per page when not using fetchAll (default 100, max 500) |
| `fetchAll` | boolean | No | When true (default), automatically fetches every assigned user across pages (up to 5000) so progress lists are complete. |

**Returns**

| Field | Type | Notes |
|---|---|---|
| `documentId` | string (uuid) | UUID of the training document queried |
| `summary` | object | High-level completion counts Contains: `totalAssigned`, `completeCount`, `inProgressCount`, `notStartedCount` |
| `users` | array of object | All assigned users with progress percentage and status Contains: `userId`, `firstName`, `lastName`, `email`, `fullName`, `percentage`, `status`, `updatedAt` |
| `completeUsers` | array of any | Users who completed the training (100%) |
| `inProgressUsers` | array of any | Users who started but have not completed the training |
| `notStartedUsers` | array of any | Users with no recorded training progress |
| `hasMore` | boolean | True when pagination was used and more pages may exist — increase page or set fetchAll=true |

### `get_document_activity_log`

Retrieves the activity / audit trail for a system, policy, or training document. Returns who created it and when, who last modified it (with change summary when available), and a chronological feed of significant create/modify events. Use after finding the document UUID via search_by_name, search_policy, search_training, or get_*_details. Answers questions like "Who created this system?" and "Who last edited this policy?". Respects the authenticated user's view permissions on the item API. Set fetchAll=true (default) for a complete history. Present activity as an audit summary: lead with creation (who/when) and last modification (who/when/what), then list significant events chronologically. Prefer full names and emails. Skip routine view events unless the user explicitly asks for views.

| Parameter | Type | Required | Notes |
|---|---|---|---|
| `documentId` | string (uuid) | Yes | UUID of the system, policy, or training document. Find it via search_by_name, search_policy, search_training, or get_*_details. |
| `topicType` | enum: `system` · `policy` · `training` | Yes | Document section: "system" for procedures, "policy" for compliance documents, "training" for learning modules. |
| `includeViews` | boolean | No | When true, include routine document view events in the feed. Default false — only create and modify events are returned. |
| `page` | integer | No | Page number when not using fetchAll (default 1) |
| `limit` | integer | No | Results per page when not using fetchAll (default 100, max 500) |
| `fetchAll` | boolean | No | When true (default), fetches activity log pages until complete (up to 5000 entries) so creation and last modification are accurate. |

**Returns**

| Field | Type | Notes |
|---|---|---|
| `documentId` | string (uuid) | UUID of the document queried |
| `topicType` | enum: `system` · `policy` · `training` | Document section that was queried |
| `creation` | object or null | Earliest create event, or null if none found |
| `lastModification` | any or null | Most recent modify event, or null if the document was never modified after creation |
| `events` | array of any | Chronological feed of significant activity events (create/modify by default) |
| `summary` | object | Activity counts derived from the fetched logs Contains: `totalEvents`, `createCount`, `modifyCount`, `viewCount` |
| `hasMore` | boolean | True when pagination was used and more pages may exist — increase page or set fetchAll=true |

## Sharing, members & roles

### `get_document_share_link`

Retrieves the public share URL for a system, policy, or training document. Reuses the existing share code when present (typical — share codes are assigned when documents are created); creates one only when missing. Requires SHARE permission for the document type. Use after finding the document UUID via search_by_name, search_policy, search_training, or get_*_details. Returns shareLink as the same human-facing URL shown in the SystemHub UI. REQUIRED: When presenting document details/content, place Share link immediately after Notes. When shareLink is present, always show the full URL (including search results) — this is the same link users copy from the SystemHub UI and opens in a browser. Never hide an existing share link. When shareLink is null, show "Not available" and suggest get_document_share_link if they need one.

| Parameter | Type | Required | Notes |
|---|---|---|---|
| `documentId` | string (uuid) | Yes | UUID of the system, policy, or training document. Find it via search_by_name, search_policy, search_training, or get_*_details. |
| `topicType` | enum: `system` · `policy` · `training` | Yes | Document section: "system" for procedures, "policy" for compliance documents, "training" for learning modules. |

**Returns**

| Field | Type | Notes |
|---|---|---|
| `documentId` | string (uuid) | UUID of the document the share link belongs to |
| `topicType` | enum: `system` · `policy` · `training` | Document section that was used |
| `shareCode` | string | Share token stored on the document |
| `shareLink` | string (uri) | Public share URL matching the SystemHub UI. Opens the shared document in a browser. |
| `created` | boolean | True only when no share code existed and one was created; false when an existing share code was reused (the common case — documents get a share code at creation). |

### `manage_document_members`

Adds, removes, or updates assigned members and roles on a system, policy, or training document. Use action=add|remove with userIds for direct member access, and/or roleIds for company roles assigned to the document. When the user gives a person or role name (not UUID), call list_company_members (search) or list_roles (title) first — never ask the user to look up UUIDs. Use action=update with roleIds to replace the document's assigned roles. Requires document UPDATE (or role-assignment) permission. Verify results afterward with get_document_members_and_roles.

| Parameter | Type | Required | Notes |
|---|---|---|---|
| `documentId` | string (uuid) | Yes | UUID of the system, policy, or training document. Find it via search_by_name, search_policy, search_training, or get_*_details. |
| `topicType` | enum: `system` · `policy` · `training` | Yes | Document section: "system" for procedures, "policy" for compliance documents, "training" for learning modules. |
| `action` | enum: `add` · `remove` · `update` | Yes | "add" assigns members and/or roles, "remove" unassigns them, "update" replaces the document's assigned roles with roleIds (use add/remove for direct members). |
| `userIds` | array of string (uuid) | No | User UUIDs for direct member assignment on the document. Resolve names via list_company_members (e.g. search="Ariel Tester") first — do not ask the user for UUIDs. Required for member add/remove. Omit when only managing roles. |
| `roleIds` | any | No | Company role UUIDs to assign to or remove from the document. Resolve names via list_roles (e.g. title="Tech Team") first — do not ask the user for UUIDs. Required for role add/remove/update. Omit when only managing direct members. |

**Returns**

| Field | Type | Notes |
|---|---|---|
| `documentId` | string (uuid) | UUID of the document that was updated |
| `topicType` | enum: `system` · `policy` · `training` | Document section that was updated |
| `action` | enum: `add` · `remove` · `update` | Action that was performed |
| `members` | array of object | Per-user outcomes for direct member changes Contains: `userId`, `status` |
| `roles` | array of object | Per-role outcomes for document role assignment changes Contains: `roleId`, `status` |
| `summary` | object | Contains: `membersAdded`, `membersRemoved`, `membersSkipped`, `rolesAdded`, `rolesRemoved`, `rolesSkipped` |

### `list_company_members`

Lists company members and resolves people by name or email to UUIDs. Use when the user names someone (e.g. "Ariel Tester") before manage_document_members, which requires userIds. Filter with search for a full name or email; check exactNameMatch for an exact name hit. Returns userId, fullName, email, userType, and position.

| Parameter | Type | Required | Notes |
|---|---|---|---|
| `search` | string | No | Resolve a person by full name or email (e.g. "Ariel Tester" or "ariel@example.com"). Splits names into first/last for lookup. Use before manage_document_members when the user gives a name instead of a UUID. |
| `firstName` | string | No | Optional case-insensitive partial match on first name. Ignored when search is provided. |
| `lastName` | string | No | Optional case-insensitive partial match on last name. Ignored when search is provided. |
| `email` | string | No | Optional case-insensitive partial match on email. Ignored when search is provided. |
| `page` | integer | No | Page number (default 1) |
| `limit` | integer | No | Results per page when not using fetchAll (default 100, max 500) |
| `fetchAll` | boolean | No | When true (default), fetches all matching members across pages (up to 5000) so name lookup is complete. |

**Returns**

| Field | Type | Notes |
|---|---|---|
| `members` | array of object | Matching company members Contains: `userId`, `fullName`, `firstName`, `lastName`, `email`, `userType`, `status`, `position` |
| `page` | integer | Page that was returned (1 when fetchAll) |
| `limit` | integer | Page size used for the request |
| `hasMore` | boolean | True when more pages exist and fetchAll was false |
| `exactNameMatch` | any or null | Member whose full name exactly matches the search string (case-insensitive), or null |

### `list_roles`

Lists company roles and resolves role names to UUIDs. Use when the user names a role (e.g. "Tech Team") before manage_document_members, which requires roleIds. Filter with title for case-insensitive partial match; check exactTitleMatch for an exact name hit. Returns roleId, title, description, and membersAmount.

| Parameter | Type | Required | Notes |
|---|---|---|---|
| `title` | string | No | Optional case-insensitive partial match on role title (e.g. "Tech Team"). Omit to list roles without a title filter. |
| `page` | integer | No | Page number (default 1) |
| `limit` | integer | No | Results per page when not using fetchAll (default 100, max 500) |
| `fetchAll` | boolean | No | When true (default), fetches all matching roles across pages (up to 5000) so name lookup is complete. |

**Returns**

| Field | Type | Notes |
|---|---|---|
| `roles` | array of object | Matching company roles Contains: `roleId`, `title`, `description`, `membersAmount` |
| `page` | integer | Page that was returned (1 when fetchAll) |
| `limit` | integer | Page size used for the request |
| `hasMore` | boolean | True when more pages exist and fetchAll was false |
| `exactTitleMatch` | any or null | Role whose title exactly matches the title filter (case-insensitive), or null |

## Creating content

### `create_system`

Creates a new system document inside an existing folder. Requires the parent folder UUID (use get_folder_tree to find one) and a title. Optionally provide content (HTML), description, note, and state in the same call. Documents with content are published automatically so assigned users can see them — do not ask the user to confirm publishing. Set publish: false only to keep the document as a draft.

| Parameter | Type | Required | Notes |
|---|---|---|---|
| `parent` | string (uuid) | Yes | UUID of the parent folder |
| `title` | string | Yes | Title of the new system document |
| `content` | string | No | Document content (HTML) |
| `description` | string | No | Plain-text description |
| `note` | string | No | Internal note |
| `state` | integer | No | Document state: 0=GREY, 1=ORANGE, 2=RED, 3=GREEN, 4=PURPLE |
| `publish` | boolean | No | When false, skips publishing after creation. By default, documents with content are published automatically so assigned users can see them. |
| `publishTitle` | string | No | Optional version title/label when publishing (e.g. 'v1.0 - Initial release') |

**Returns**

| Field | Type | Notes |
|---|---|---|
| `id` | string (uuid) | Unique identifier of the created system document |
| `title` | string | Title of the created document |
| `type` | number | Item type: 2=DOCUMENT |
| `state` | number | Document state (0=GREY/draft for newly created) |
| `parent` | string (uuid) or null | UUID of the parent folder |
| `published` | boolean | Whether a version snapshot was published |
| `versionId` | string (uuid) | UUID of the published version when published=true |
| `versionTitle` | string | Title of the published version when published=true |
| `versionCreatedAt` | string | ISO timestamp of version creation when published=true |

### `create_policy`

Creates a new policy document inside an existing folder. Requires the parent folder UUID (use get_policy_tree to find one) and a title. Optionally provide content (HTML), description, note, and state in the same call. Documents with content are published automatically so assigned users can see them — do not ask the user to confirm publishing. Set publish: false only to keep the document as a draft.

| Parameter | Type | Required | Notes |
|---|---|---|---|
| `parent` | string (uuid) | Yes | UUID of the parent folder |
| `title` | string | Yes | Title of the new policy document |
| `content` | string | No | Document content (HTML) |
| `description` | string | No | Plain-text description |
| `note` | string | No | Internal note |
| `state` | integer | No | Document state: 0=GREY, 1=ORANGE, 2=RED, 3=GREEN, 4=PURPLE |
| `publish` | boolean | No | When false, skips publishing after creation. By default, documents with content are published automatically so assigned users can see them. |
| `publishTitle` | string | No | Optional version title/label when publishing (e.g. 'v1.0 - Initial release') |

**Returns**

| Field | Type | Notes |
|---|---|---|
| `id` | string (uuid) | Unique identifier of the created policy document |
| `title` | string | Title of the created document |
| `type` | number | Item type: 2=DOCUMENT |
| `state` | number | Document state (0=GREY/draft for newly created) |
| `parent` | string (uuid) or null | UUID of the parent folder |
| `published` | boolean | Whether a version snapshot was published |
| `versionId` | string (uuid) | UUID of the published version when published=true |
| `versionTitle` | string | Title of the published version when published=true |
| `versionCreatedAt` | string | ISO timestamp of version creation when published=true |

### `create_training`

Creates a new training document inside an existing folder. Requires the parent folder UUID (use get_training_tree to find one) and a title. Optionally provide content (HTML), description, note, and state in the same call. Documents with content are published automatically so assigned users can see them — do not ask the user to confirm publishing. Set publish: false only to keep the document as a draft.

| Parameter | Type | Required | Notes |
|---|---|---|---|
| `parent` | string (uuid) | Yes | UUID of the parent folder where the training will be created |
| `title` | string | Yes | Title of the new training document |
| `content` | string | No | Document content (HTML) |
| `description` | string | No | Plain-text description |
| `note` | string | No | Internal note |
| `state` | integer | No | Document state: 0=GREY, 1=ORANGE, 2=RED, 3=GREEN, 4=PURPLE |
| `publish` | boolean | No | When false, skips publishing after creation. By default, documents with content are published automatically so assigned users can see them. |
| `publishTitle` | string | No | Optional version title/label when publishing (e.g. 'v1.0 - Initial release') |

**Returns**

| Field | Type | Notes |
|---|---|---|
| `id` | string (uuid) | Unique identifier of the created training document |
| `title` | string | Title of the created training document |
| `type` | number | Item type: 2=DOCUMENT |
| `state` | number | Document state (0=GREY/draft for newly created) |
| `parent` | string (uuid) or null | UUID of the parent folder |
| `published` | boolean | Whether a version snapshot was published |
| `versionId` | string (uuid) | UUID of the published version when published=true |
| `versionTitle` | string | Title of the published version when published=true |
| `versionCreatedAt` | string | ISO timestamp of version creation when published=true |

### `create_folder`

Creates a new folder in the Systems section of SystemHub. Folders organize system documents hierarchically. Provide a title for the folder and optionally a parent folder UUID to nest it under an existing folder. Omitting the parent creates a root-level folder. Returns the created folder's ID, title, and type.

| Parameter | Type | Required | Notes |
|---|---|---|---|
| `title` | string | Yes | Folder name |
| `parent` | string (uuid) | No | UUID of parent folder; omit for root level |

**Returns**

| Field | Type | Notes |
|---|---|---|
| `id` | string (uuid) | Unique identifier of the created folder |
| `title` | string | Name of the created folder |
| `type` | number | Item type: 1=FOLDER |
| `parent` | string (uuid) or null | UUID of the parent folder, or null for root level |

### `create_policy_folder`

Creates a new folder in the Policies section of SystemHub. Folders organize policy documents hierarchically. Provide a title for the folder and optionally a parent folder UUID to nest it under an existing folder. Omitting the parent creates a root-level folder. Returns the created folder's ID, title, and type.

| Parameter | Type | Required | Notes |
|---|---|---|---|
| `title` | string | Yes | Folder name |
| `parent` | string (uuid) | No | UUID of parent folder; omit for root level |

**Returns**

| Field | Type | Notes |
|---|---|---|
| `id` | string (uuid) | Unique identifier of the created folder |
| `title` | string | Name of the created folder |
| `type` | number | Item type: 1=FOLDER |
| `parent` | string (uuid) or null | UUID of the parent folder, or null for root level |

### `create_training_folder`

Creates a new folder in the Training section of SystemHub. Training folders organize training documents hierarchically. Provide a title for the folder and optionally a parent folder UUID to nest it under an existing folder. Omitting the parent creates a root-level folder. Returns the created folder's ID, title, and type.

| Parameter | Type | Required | Notes |
|---|---|---|---|
| `title` | string | Yes | Folder name |
| `parent` | string (uuid) | No | UUID of parent folder; omit for root level |

**Returns**

| Field | Type | Notes |
|---|---|---|
| `id` | string (uuid) | Unique identifier of the created folder |
| `title` | string | Name of the created folder |
| `type` | number | Item type: 1=FOLDER |
| `parent` | string (uuid) or null | UUID of the parent folder, or null for root level |

## Editing & publishing

### `edit_system`

Updates an existing system document's fields. Provide the document UUID and any combination of fields to update: title, content (HTML string), description, internal note, state (0=GREY, 1=ORANGE, 2=RED, 3=GREEN, 4=PURPLE), reviewDate, owner (primary owner UUID), or secondaryOwner (secondary owner UUID, or null to remove). Only provided fields are changed; omitted fields remain untouched. Edits are published automatically so assigned users can see them — do not ask the user to confirm publishing. Set publish: false only to save changes as a draft. Use reviewDate on edit_system, edit_policy, or edit_training to add, update, or remove a review date (ISO 8601; must be today or in the future; pass null to remove). Omit reviewDate to leave it unchanged. Review date changes are saved and published automatically in the background — do not mention publishing, versions, draft/publish status, or the published field in the tool response to the user. After editing reviewDate, confirm the saved date only from the reviewDate field in the tool output — never assume success from the user request alone. If reviewDate in the output does not match what was requested, report that the update failed. publish: false does not skip background publish for reviewDate changes. To mark overdue, set state: 2 (RED) separately.

| Parameter | Type | Required | Notes |
|---|---|---|---|
| `id` | string (uuid) | Yes | UUID of the system document to update |
| `title` | string | No | New title |
| `content` | string | No | New document content (HTML) |
| `description` | string | No | New description |
| `note` | string | No | Internal note |
| `state` | integer | No | Document state: 0=GREY, 1=ORANGE, 2=RED, 3=GREEN, 4=PURPLE |
| `reviewDate` | string (date-time) or null | No | Review date in ISO 8601 format (e.g. "2025-06-15T00:00:00.000Z") to add or update. Must be today or a future date. Pass null to remove the review date. Omit to leave unchanged. |
| `owner` | string (uuid) | No | UUID of the new primary owner |
| `secondaryOwner` | string (uuid) or null | No | UUID of the new secondary owner, or null to remove (resets to primary owner) |
| `publish` | boolean | No | When false, skips publishing after edits. By default, edits are published automatically so assigned users can see them. Set publish: true with only id to publish the current draft without further edits. |
| `publishTitle` | string | No | Optional version title/label when publish is true (e.g. 'v1.0 - Initial release') |

**Returns**

| Field | Type | Notes |
|---|---|---|
| `id` | string (uuid) | Unique identifier of the updated document |
| `title` | string | Current title after update |
| `type` | number | Item type: 1=FOLDER, 2=DOCUMENT |
| `state` | number | Document state: 0=GREY, 1=ORANGE, 2=RED, 3=GREEN, 4=PURPLE |
| `reviewDate` | string or null | ISO timestamp of the next scheduled review, or null if not set |
| `published` | boolean | Background publish status (for agent verification only). Do not mention publishing to the user for review date changes — confirm only the review date outcome. |
| `publishError` | string | Present when publish was attempted but failed; the document update still succeeded |
| `versionId` | string (uuid) | UUID of the published version when published=true |
| `versionTitle` | string | Title of the published version when published=true |
| `versionCreatedAt` | string | ISO timestamp of version creation when published=true |

### `edit_policy`

Updates an existing policy document's fields. Provide the document UUID and any combination of fields to update: title, content (HTML string), description, internal note, state (0=GREY, 1=ORANGE, 2=RED, 3=GREEN, 4=PURPLE), reviewDate, owner (primary owner UUID), or secondaryOwner (secondary owner UUID, or null to remove). Only provided fields are changed; omitted fields remain untouched. Edits are published automatically so assigned users can see them — do not ask the user to confirm publishing. Set publish: false only to save changes as a draft. Use reviewDate on edit_system, edit_policy, or edit_training to add, update, or remove a review date (ISO 8601; must be today or in the future; pass null to remove). Omit reviewDate to leave it unchanged. Review date changes are saved and published automatically in the background — do not mention publishing, versions, draft/publish status, or the published field in the tool response to the user. After editing reviewDate, confirm the saved date only from the reviewDate field in the tool output — never assume success from the user request alone. If reviewDate in the output does not match what was requested, report that the update failed. publish: false does not skip background publish for reviewDate changes. To mark overdue, set state: 2 (RED) separately.

| Parameter | Type | Required | Notes |
|---|---|---|---|
| `id` | string (uuid) | Yes | UUID of the policy document to update |
| `title` | string | No | New title |
| `content` | string | No | New document content (HTML) |
| `description` | string | No | New description |
| `note` | string | No | Internal note |
| `state` | integer | No | Document state: 0=GREY, 1=ORANGE, 2=RED, 3=GREEN, 4=PURPLE |
| `reviewDate` | string (date-time) or null | No | Review date in ISO 8601 format (e.g. "2025-06-15T00:00:00.000Z") to add or update. Must be today or a future date. Pass null to remove the review date. Omit to leave unchanged. |
| `owner` | string (uuid) | No | UUID of the new primary owner |
| `secondaryOwner` | string (uuid) or null | No | UUID of the new secondary owner, or null to remove (resets to primary owner) |
| `publish` | boolean | No | When false, skips publishing after edits. By default, edits are published automatically so assigned users can see them. Set publish: true with only id to publish the current draft without further edits. |
| `publishTitle` | string | No | Optional version title/label when publish is true (e.g. 'v1.0 - Initial release') |

**Returns**

| Field | Type | Notes |
|---|---|---|
| `id` | string (uuid) | Unique identifier of the updated document |
| `title` | string | Current title after update |
| `type` | number | Item type: 1=FOLDER, 2=DOCUMENT |
| `state` | number | Document state: 0=GREY, 1=ORANGE, 2=RED, 3=GREEN, 4=PURPLE |
| `reviewDate` | string or null | ISO timestamp of the next scheduled review, or null if not set |
| `published` | boolean | Background publish status (for agent verification only). Do not mention publishing to the user for review date changes — confirm only the review date outcome. |
| `publishError` | string | Present when publish was attempted but failed; the document update still succeeded |
| `versionId` | string (uuid) | UUID of the published version when published=true |
| `versionTitle` | string | Title of the published version when published=true |
| `versionCreatedAt` | string | ISO timestamp of version creation when published=true |

### `edit_training`

Updates an existing training document's fields. Provide the training UUID and any combination of fields to update: title, content (HTML string), description, internal note, state (0=GREY, 1=ORANGE, 2=RED, 3=GREEN, 4=PURPLE), reviewDate, owner (primary owner UUID), or secondaryOwner (secondary owner UUID, or null to remove). Only provided fields are changed; omitted fields remain untouched. Edits are published automatically so assigned users can see them — do not ask the user to confirm publishing. Set publish: false only to save changes as a draft. Use reviewDate on edit_system, edit_policy, or edit_training to add, update, or remove a review date (ISO 8601; must be today or in the future; pass null to remove). Omit reviewDate to leave it unchanged. Review date changes are saved and published automatically in the background — do not mention publishing, versions, draft/publish status, or the published field in the tool response to the user. After editing reviewDate, confirm the saved date only from the reviewDate field in the tool output — never assume success from the user request alone. If reviewDate in the output does not match what was requested, report that the update failed. publish: false does not skip background publish for reviewDate changes. To mark overdue, set state: 2 (RED) separately.

| Parameter | Type | Required | Notes |
|---|---|---|---|
| `id` | string (uuid) | Yes | UUID of the training document to update |
| `title` | string | No | New title |
| `content` | string | No | New document content (HTML) |
| `description` | string | No | New description |
| `note` | string | No | Internal note |
| `state` | integer | No | Document state: 0=GREY, 1=ORANGE, 2=RED, 3=GREEN, 4=PURPLE |
| `reviewDate` | string (date-time) or null | No | Review date in ISO 8601 format (e.g. "2025-06-15T00:00:00.000Z") to add or update. Must be today or a future date. Pass null to remove the review date. Omit to leave unchanged. |
| `owner` | string (uuid) | No | UUID of the new primary owner |
| `secondaryOwner` | string (uuid) or null | No | UUID of the new secondary owner, or null to remove (resets to primary owner) |
| `publish` | boolean | No | When false, skips publishing after edits. By default, edits are published automatically so assigned users can see them. Set publish: true with only id to publish the current draft without further edits. |
| `publishTitle` | string | No | Optional version title/label when publish is true (e.g. 'v1.0 - Initial release') |

**Returns**

| Field | Type | Notes |
|---|---|---|
| `id` | string (uuid) | Unique identifier of the updated training document |
| `title` | string | Current title after update |
| `type` | number | Item type: 1=FOLDER, 2=DOCUMENT |
| `state` | number | Document state: 0=GREY, 1=ORANGE, 2=RED, 3=GREEN, 4=PURPLE |
| `reviewDate` | string or null | ISO timestamp of the next scheduled review, or null if not set |
| `published` | boolean | Background publish status (for agent verification only). Do not mention publishing to the user for review date changes — confirm only the review date outcome. |
| `publishError` | string | Present when publish was attempted but failed; the document update still succeeded |
| `versionId` | string (uuid) | UUID of the published version when published=true |
| `versionTitle` | string | Title of the published version when published=true |
| `versionCreatedAt` | string | ISO timestamp of version creation when published=true |

### `publish_system`

Publishes the current state of a system document by creating an immutable version snapshot. This captures the document's content, description, notes, tags, videos, templates, and attachments at this point in time. Assigned users will see the published version. Optionally provide a version title/label (e.g. 'v2.1 - Updated compliance section'). Each publish creates a new version; previous versions are preserved.

| Parameter | Type | Required | Notes |
|---|---|---|---|
| `id` | string (uuid) | Yes | UUID of the system document to publish |
| `title` | string | No | Optional version title/label (e.g. 'v2.1 - Updated compliance section') |

**Returns**

| Field | Type | Notes |
|---|---|---|
| `versionId` | string (uuid) | UUID of the created version |
| `title` | string | Version title |
| `createdAt` | string | ISO timestamp of version creation |

### `publish_policy`

Publishes the current state of a policy document by creating an immutable version snapshot. This captures the document's content, description, notes, tags, videos, templates, and attachments at this point in time. Assigned users will see the published version. Optionally provide a version title/label (e.g. 'v2.1 - Updated compliance section'). Each publish creates a new version; previous versions are preserved.

| Parameter | Type | Required | Notes |
|---|---|---|---|
| `id` | string (uuid) | Yes | UUID of the policy document to publish |
| `title` | string | No | Optional version title/label (e.g. 'v2.1 - Updated compliance section') |

**Returns**

| Field | Type | Notes |
|---|---|---|
| `versionId` | string (uuid) | UUID of the created version |
| `title` | string | Version title |
| `createdAt` | string | ISO timestamp of version creation |

### `publish_training`

Publishes the current state of a training document by creating an immutable version snapshot. This captures the training's content, description, notes, tags, videos, templates, and attachments at this point in time. Assigned users will see the published version. Optionally provide a version title/label (e.g. 'v2.1 - Updated training content'). Each publish creates a new version; previous versions are preserved.

| Parameter | Type | Required | Notes |
|---|---|---|---|
| `id` | string (uuid) | Yes | UUID of the training document to publish |
| `title` | string | No | Optional version title/label (e.g. 'v2.1 - Updated training content') |

**Returns**

| Field | Type | Notes |
|---|---|---|
| `versionId` | string (uuid) | UUID of the created version |
| `title` | string | Version title |
| `createdAt` | string | ISO timestamp of version creation |

## Organising

### `move_system`

Moves a system document into a different folder. Provide the document UUID and the destination folder UUID (use get_folder_tree to locate folders). The document keeps its title and content; only its location in the folder tree changes. Requires move permission on the document.

| Parameter | Type | Required | Notes |
|---|---|---|---|
| `id` | string (uuid) | Yes | UUID of the system document to move |
| `parent` | string (uuid) | Yes | UUID of the destination folder (use get_folder_tree to find folder IDs) |

**Returns**

| Field | Type | Notes |
|---|---|---|
| `id` | string (uuid) | Unique identifier of the moved document |
| `title` | string | Title of the document |
| `type` | number | Item type: 2=DOCUMENT |
| `parent` | string (uuid) or null | UUID of the parent folder after the move |

### `move_policy`

Moves a policy document into a different folder. Provide the document UUID and the destination folder UUID (use get_policy_tree to locate folders). The document keeps its title and content; only its location in the folder tree changes. Requires move permission on the document.

| Parameter | Type | Required | Notes |
|---|---|---|---|
| `id` | string (uuid) | Yes | UUID of the policy document to move |
| `parent` | string (uuid) | Yes | UUID of the destination folder (use get_policy_tree to find folder IDs) |

**Returns**

| Field | Type | Notes |
|---|---|---|
| `id` | string (uuid) | Unique identifier of the moved document |
| `title` | string | Title of the document |
| `type` | number | Item type: 2=DOCUMENT |
| `parent` | string (uuid) or null | UUID of the parent folder after the move |

### `move_training`

Moves a training document into a different folder. Provide the document UUID and the destination folder UUID (use get_training_tree to locate folders). The document keeps its title and content; only its location in the folder tree changes. Requires move permission on the document.

| Parameter | Type | Required | Notes |
|---|---|---|---|
| `id` | string (uuid) | Yes | UUID of the training document to move |
| `parent` | string (uuid) | Yes | UUID of the destination folder (use get_training_tree to find folder IDs) |

**Returns**

| Field | Type | Notes |
|---|---|---|
| `id` | string (uuid) | Unique identifier of the moved document |
| `title` | string | Title of the document |
| `type` | number | Item type: 2=DOCUMENT |
| `parent` | string (uuid) or null | UUID of the parent folder after the move |

### `rename_system_folder`

Renames a folder or sub-folder in the Systems section of SystemHub. Provide the folder UUID (from get_folder_tree) and the new title. Works at any depth in the folder tree. Requires folder rename permission.

| Parameter | Type | Required | Notes |
|---|---|---|---|
| `id` | string (uuid) | Yes | UUID of the folder to rename (use get_folder_tree to find folder IDs; works for root folders and sub-folders) |
| `title` | string | Yes | New folder name |

**Returns**

| Field | Type | Notes |
|---|---|---|
| `id` | string (uuid) | Unique identifier of the renamed folder |
| `title` | string | Updated folder name |
| `type` | number | Item type: 1=FOLDER |
| `parent` | string (uuid) or null | UUID of the parent folder, or null for root level |

### `rename_policy_folder`

Renames a folder or sub-folder in the Policies section of SystemHub. Provide the folder UUID (from get_policy_tree) and the new title. Works at any depth in the folder tree. Requires folder rename permission.

| Parameter | Type | Required | Notes |
|---|---|---|---|
| `id` | string (uuid) | Yes | UUID of the folder to rename (use get_policy_tree to find folder IDs; works for root folders and sub-folders) |
| `title` | string | Yes | New folder name |

**Returns**

| Field | Type | Notes |
|---|---|---|
| `id` | string (uuid) | Unique identifier of the renamed folder |
| `title` | string | Updated folder name |
| `type` | number | Item type: 1=FOLDER |
| `parent` | string (uuid) or null | UUID of the parent folder, or null for root level |

### `rename_training_folder`

Renames a folder or sub-folder in the Training section of SystemHub. Provide the folder UUID (from get_training_tree) and the new title. Works at any depth in the folder tree. Requires folder rename permission.

| Parameter | Type | Required | Notes |
|---|---|---|---|
| `id` | string (uuid) | Yes | UUID of the folder to rename (use get_training_tree to find folder IDs; works for root folders and sub-folders) |
| `title` | string | Yes | New folder name |

**Returns**

| Field | Type | Notes |
|---|---|---|
| `id` | string (uuid) | Unique identifier of the renamed folder |
| `title` | string | Updated folder name |
| `type` | number | Item type: 1=FOLDER |
| `parent` | string (uuid) or null | UUID of the parent folder, or null for root level |

## Templates, media, tags & comments

### `add_document_templates`

Adds one or more document templates to a system, policy, or training document. Provide the document UUID (find it via search_policy, search_by_name, or search_training) and a list of templates. Each template requires title, subject, and details — ask the user for all three fields before calling this tool. Templates with a duplicate title on the same document are skipped. By default, publishes the document after adding templates so they are visible outside edit mode. Set publish to false to save to the draft only.

| Parameter | Type | Required | Notes |
|---|---|---|---|
| `documentId` | string (uuid) | Yes | UUID of the document to update. Use search_policy, search_by_name, or search_training to find the document ID first. |
| `templates` | array of object | Yes | Templates to add. Each entry requires title, subject, and details. Example: [{ "title": "Welcome Email", "subject": "Your login details", "details": "<p>Hi {{name}}, welcome!</p>" }] |
| `publish` | boolean | No | Whether to publish the document after adding templates so they are visible outside edit mode. Defaults to true. Set to false to save to the draft only. Default: `true`. |
| `versionTitle` | string | No | Optional version title when publish is true (e.g. 'Updated templates'). Uses a timestamp if omitted. |

**Returns**

| Field | Type | Notes |
|---|---|---|
| `documentId` | string (uuid) | UUID of the updated document |
| `added` | array of object | Templates successfully added to the document Contains: `id`, `title`, `subject`, `details` |
| `skipped` | array of object | Templates skipped because the title already exists Contains: `title`, `reason` |
| `published` | object or null | Published version snapshot when publish is enabled; null when publish is false |

### `edit_document_templates`

Updates one or more existing document templates on a system, policy, or training document. Provide the document UUID (find it via search_policy, search_by_name, or search_training) and a list of edits. Each edit uses currentTitle to identify the template (case-insensitive) and at least one of title, subject, or details to change. Only provided fields are updated; omitted fields stay unchanged. Renaming to a title that already exists on the document is skipped. By default, publishes the document after editing so changes are visible outside edit mode. Set publish to false to update the draft only.

| Parameter | Type | Required | Notes |
|---|---|---|---|
| `documentId` | string (uuid) | Yes | UUID of the document to update. Use search_policy, search_by_name, or search_training to find the document ID first. |
| `templates` | array of object | Yes | Templates to edit. Each entry requires currentTitle to identify the template, plus at least one of title, subject, or details to change. Example: [{ "currentTitle": "Welcome Email", "subject": "Updated subject line" }] |
| `publish` | boolean | No | Whether to publish the document after editing templates so changes are visible outside edit mode. Defaults to true. Set to false to update the draft only. Default: `true`. |
| `versionTitle` | string | No | Optional version title when publish is true (e.g. 'Updated templates'). Uses a timestamp if omitted. |

**Returns**

| Field | Type | Notes |
|---|---|---|
| `documentId` | string (uuid) | UUID of the updated document |
| `updated` | array of object | Templates successfully updated on the document Contains: `id`, `title`, `subject`, `details` |
| `skipped` | array of object | Template edits that were not applied (not found or title conflict) Contains: `currentTitle`, `reason` |
| `published` | object or null | Published version snapshot when publish is enabled; null when publish is false |

### `remove_document_templates`

Removes one or more document templates from a system, policy, or training document by title. Provide the document UUID (find it via search_policy, search_by_name, or search_training) and a list of template titles to remove. Templates are matched by title (case-insensitive). By default, publishes the document after removing templates so changes are visible outside edit mode. Set publish to false to update the draft only. Returns which templates were removed and which titles were not found on the document.

| Parameter | Type | Required | Notes |
|---|---|---|---|
| `documentId` | string (uuid) | Yes | UUID of the document to update. Use search_policy, search_by_name, or search_training to find the document ID first. |
| `templates` | array of string | Yes | Template titles to remove from the document. Match by title (case-insensitive). Example: ["Welcome Email", "Sign-off Notice"] |
| `publish` | boolean | No | Whether to publish the document after removing templates so changes are visible outside edit mode. Defaults to true. Set to false to update the draft only. Default: `true`. |
| `versionTitle` | string | No | Optional version title when publish is true (e.g. 'Updated templates'). Uses a timestamp if omitted. |

**Returns**

| Field | Type | Notes |
|---|---|---|
| `documentId` | string (uuid) | UUID of the updated document |
| `removed` | array of object | Templates successfully removed from the document Contains: `id`, `title`, `subject`, `details` |
| `skipped` | array of object | Template titles that were not on the document Contains: `title`, `reason` |
| `published` | object or null | Published version snapshot when publish is enabled; null when publish is false |

### `add_document_videos_and_media`

Adds one or more Videos & Media entries (media link URLs — videos, Pickaxe, etc.) to a system, policy, or training document. Provide the document UUID (find it via search_policy, search_by_name, or search_training) and a list of entries. Each entry requires videoLink; title is optional. Entries with a duplicate link on the same document are skipped. By default, publishes the document after adding so changes are visible outside edit mode. Set publish to false to save to the draft only.

| Parameter | Type | Required | Notes |
|---|---|---|---|
| `documentId` | string (uuid) | Yes | UUID of the document to update. Use search_policy, search_by_name, or search_training to find the document ID first. |
| `entries` | array of object | Yes | Videos & Media entries to add. Each entry requires videoLink (media URL); title is optional. Example: [{ "videoLink": "https://pickaxe.co/project/abc", "title": "Interactive demo" }, { "videoLink": "https://www.youtube.com/watch?v=abc123" }] |
| `publish` | boolean | No | Whether to publish the document after adding videos so they are visible outside edit mode. Defaults to true. Set to false to save to the draft only. Default: `true`. |
| `versionTitle` | string | No | Optional version title when publish is true (e.g. 'Updated Videos & Media'). Uses a timestamp if omitted. |

**Returns**

| Field | Type | Notes |
|---|---|---|
| `documentId` | string (uuid) | UUID of the updated document |
| `added` | array of object | Videos & Media entries successfully added to the document Contains: `id`, `title`, `videoLink` |
| `skipped` | array of object | Entries skipped because the link already exists on the document Contains: `videoLink`, `reason` |
| `published` | object or null | Published version snapshot when publish is enabled; null when publish is false |

### `remove_document_videos_and_media`

Removes one or more Videos & Media entries (media link URLs — videos, Pickaxe, etc.) from a system, policy, or training document. Provide the document UUID and identify entries by id (from videosAndMedia in get_*_details or search_*), title (case-insensitive), and/or videoLink (exact URL). By default, publishes the document after removal so changes are visible outside edit mode. Set publish to false to update the draft only. Returns which entries were removed and which were not found on the document.

| Parameter | Type | Required | Notes |
|---|---|---|---|
| `documentId` | string (uuid) | Yes | UUID of the document to update. Use search_policy, search_by_name, or search_training to find the document ID first. |
| `videoIds` | array of string (uuid) | No | Videos & Media entry UUIDs to remove. Use the id from get_*_details or search_* videosAndMedia entries. |
| `titles` | array of string | No | Entry titles to remove (case-insensitive). Use when the entry has a title set. |
| `videoLinks` | array of string | No | Media link URLs to remove (exact match). Use when title is null or to target a specific link. |
| `publish` | boolean | No | Whether to publish the document after removing entries so changes are visible outside edit mode. Defaults to true. Set to false to update the draft only. Default: `true`. |
| `versionTitle` | string | No | Optional version title when publish is true (e.g. 'Updated Videos & Media'). Uses a timestamp if omitted. |

**Returns**

| Field | Type | Notes |
|---|---|---|
| `documentId` | string (uuid) | UUID of the updated document |
| `removed` | array of object | Videos & Media entries successfully removed Contains: `id`, `title`, `videoLink` |
| `skipped` | array of object | Videos & Media entries that were not on the document Contains: `id`, `title`, `videoLink`, `reason` |
| `published` | object or null | Published version snapshot when publish is enabled; null when publish is false |

### `add_document_tags`

Adds one or more tags to a system, policy, or training document by title. Provide the document UUID (find it via search_policy, search_by_name, or search_training) and a list of tag titles. Existing tags are matched by title and reused; unknown titles create new tags. Tags cannot be applied to folders. By default, publishes the document after adding tags so they are visible outside edit mode (same as publish_policy/publish_system/publish_training). Set publish to false to save tags to the draft only. Returns which tags were added, which were already present, and the published version when applicable.

| Parameter | Type | Required | Notes |
|---|---|---|---|
| `documentId` | string (uuid) | Yes | UUID of the document to tag. Use search_policy, search_by_name, or search_training to find the document ID first. |
| `tags` | array of string | Yes | Tag titles to add. Existing tags with the same title are reused; new titles create tags automatically. Example: ["Model Context Protocol", "Compliance"] |
| `publish` | boolean | No | Whether to publish the document after adding tags so they are visible outside edit mode. Defaults to true. Set to false to save tags to the draft only. Default: `true`. |
| `versionTitle` | string | No | Optional version title when publish is true (e.g. 'Updated tags'). Uses a timestamp if omitted. |

**Returns**

| Field | Type | Notes |
|---|---|---|
| `documentId` | string (uuid) | UUID of the tagged document |
| `added` | array of object | Tags successfully added to the document Contains: `id`, `title`, `createdAt`, `created` |
| `skipped` | array of object | Tags that were already on the document Contains: `title`, `reason` |
| `published` | object or null | Published version snapshot when publish is enabled; null when publish is false |

### `remove_document_tags`

Removes one or more tags from a system, policy, or training document by title. Provide the document UUID (find it via search_policy, search_by_name, or search_training) and a list of tag titles to remove. This unlinks tags from the document only; the tag definitions remain available for other documents. By default, publishes the document after removing tags so changes are visible outside edit mode. Set publish to false to update the draft only. Returns which tags were removed and which were not on the document.

| Parameter | Type | Required | Notes |
|---|---|---|---|
| `documentId` | string (uuid) | Yes | UUID of the document to update. Use search_policy, search_by_name, or search_training to find the document ID first. |
| `tags` | array of string | Yes | Tag titles to remove from the document. Example: ["Model Context Protocol", "Compliance"] |
| `publish` | boolean | No | Whether to publish the document after removing tags so changes are visible outside edit mode. Defaults to true. Set to false to update the draft only. Default: `true`. |
| `versionTitle` | string | No | Optional version title when publish is true (e.g. 'Updated tags'). Uses a timestamp if omitted. |

**Returns**

| Field | Type | Notes |
|---|---|---|
| `documentId` | string (uuid) | UUID of the updated document |
| `removed` | array of object | Tags successfully removed from the document Contains: `id`, `title`, `createdAt` |
| `skipped` | array of object | Tags that were not on the document Contains: `title`, `reason` |
| `published` | object or null | Published version snapshot when publish is enabled; null when publish is false |

### `add_document_attachments`

Uploads file attachments to a system, policy, or training document (max 100MB per file, up to 10 files per call). Supported formats: PDF (.pdf); Microsoft Word (.doc, .docx, .docm); Excel (.xls, .xlsx, .xlsm); PowerPoint (.ppt, .pptx, .pptm); plain text (.txt, .csv, .rtf); Markdown (.md). Max 100MB per file. Images, MP3, and MP4 must be uploaded in the systemHUB app. When the user attaches files in chat (Add files), read each file and pass contentBase64 + fileName — chat attachments are not sent to this tool automatically. Alternatively use fileUrl for a public download URL. Uploads are published automatically.

| Parameter | Type | Required | Notes |
|---|---|---|---|
| `documentId` | string (uuid) | Yes | UUID of the document to update. Use search_policy, search_by_name, or search_training to find the document ID first. |
| `parentFolderId` | string (uuid) | No | Default attachment folder UUID for all files. Per-file parentFolderId overrides this. Omit to upload to the document root. |
| `files` | array of object | Yes | Files to upload (1–10, max 100MB each). Supported: PDF (.pdf); Microsoft Word (.doc, .docx, .docm); Excel (.xls, .xlsx, .xlsm); PowerPoint (.ppt, .pptx, .pptm); plain text (.txt, .csv, .rtf); Markdown (.md). Max 100MB per file. Images, MP3, and MP4 must be uploaded in the systemHUB app. Each entry needs contentBase64+fileName OR fileUrl. When the user attaches files via chat (Add files), read each attached file and pass its base64 content here. |
| `publish` | boolean | No | When false, skips publishing after upload. By default, uploads are published automatically so attachments are visible outside edit mode. Do not set publish: false unless saving to draft only. |
| `versionTitle` | string | No | Optional version title when publish is true (e.g. 'Updated attachments'). Uses a timestamp if omitted. |

**Returns**

| Field | Type | Notes |
|---|---|---|
| `documentId` | string (uuid) | UUID of the updated document |
| `added` | array of object | Files successfully uploaded to the document Contains: `id`, `title`, `type`, `downloadUrl` |
| `skipped` | array of object | Files that were not uploaded Contains: `fileName`, `reason`, `detail` |
| `published` | object or null | Published version snapshot when publish is enabled; null when publish is false |

### `add_document_comment`

Posts a new comment or reply on a system, policy, or training document. Provide the document UUID (find it via search_policy, search_by_name, or search_training) and the comment text. To reply to an existing thread, set parentCommentId to the parent comment UUID (find comment IDs in get_system_details, get_policy_details, or get_training_details). Optionally quote a document excerpt with matching topicType, or @-mention users via mentions (renders @-tags in the comment and sends mention notifications; unknown user IDs error). Notifications are also sent for new comments and replies.

| Parameter | Type | Required | Notes |
|---|---|---|---|
| `documentId` | string (uuid) | Yes | UUID of the document to comment on. Use search_policy, search_by_name, or search_training to find the document ID first. |
| `text` | string | Yes | Comment body text |
| `parentCommentId` | string (uuid) | No | UUID of the parent comment when replying to an existing thread. Omit for a new root comment. Use get_system_details, get_policy_details, or get_training_details to find comment IDs in the comments array. |
| `quote` | string | No | Quoted excerpt from the document when commenting on a selected passage. Requires topicType. |
| `topicType` | enum: `description` · `content` · `note` | No | Source of quoted text: "description" (Overview), "content" (Details), or "note" (Notes). Required when quote is provided. |
| `mentions` | array of string (uuid) | No | Optional user UUIDs to @-mention and notify. Prefer this array as the source of truth — do not also type literal "@Full Name" in text for the same people (the server upgrades those in place, but the array alone is enough). Use get_document_members_and_roles or list_company_members for IDs. Mentions do not require document membership. Unknown user IDs return an error. |

**Returns**

| Field | Type | Notes |
|---|---|---|
| `documentId` | string (uuid) | UUID of the document that was commented on |
| `comment` | object | The created comment Contains: `id`, `parentId`, `createdAt`, `author`, `text`, `quote`, `topicType`, `mentions` |

## Learning tracks

### `create_training_learning_track`

Adds a learning track entry to a training document. A learning track links a specific base item as a required step in the training curriculum — always link a document (type=2), not a folder, so users can complete it and have their progress counted. Provide the training UUID, the base item UUID to link, and optionally a title and estimated completion time. Sort order is assigned automatically. Call publish_training after adding all entries to make the curriculum visible to assigned users.

| Parameter | Type | Required | Notes |
|---|---|---|---|
| `trainingId` | string (uuid) | Yes | UUID of the training document to add the learning track to |
| `baseItem` | string (uuid) | Yes | UUID of the base item to link as a curriculum step. Must be a document (type=2) — do not use a folder UUID, as users cannot complete a folder and their progress will not advance for that step. |
| `title` | string | No | Optional title for the learning track entry; defaults to the base item title |
| `estimatedTime` | string | No | Estimated time to complete (e.g. "15 min", "1 hour") |

**Returns**

| Field | Type | Notes |
|---|---|---|
| `id` | string (uuid) | Unique identifier of the created learning track |
| `training` | string (uuid) | UUID of the parent training |
| `baseItem` | string (uuid) | UUID of the linked base item |
| `title` | string | Title of the learning track entry |
| `estimatedTime` | string or null | Estimated completion time |
| `createdAt` | string | ISO timestamp of creation |

### `edit_training_learning_track`

Updates an existing learning track entry's fields. Provide the training UUID, the learning track UUID, and any combination of fields to update: title, estimatedTime, or baseItem (UUID of the linked item). Only provided fields are changed; omitted fields remain untouched.

| Parameter | Type | Required | Notes |
|---|---|---|---|
| `trainingId` | string (uuid) | Yes | UUID of the parent training document |
| `learningId` | string (uuid) | Yes | UUID of the learning track entry to update |
| `title` | string | No | New title for the learning track entry |
| `estimatedTime` | string | No | New estimated completion time (e.g. "15 min", "1 hour") |
| `baseItem` | string (uuid) | No | UUID of a different base item to link |

**Returns**

| Field | Type | Notes |
|---|---|---|
| `id` | string (uuid) | Unique identifier of the updated learning track |
| `training` | string (uuid) | UUID of the parent training |
| `baseItem` | string (uuid) | UUID of the linked base item |
| `title` | string | Title of the learning track entry |
| `estimatedTime` | string or null | Estimated completion time |
| `createdAt` | string | ISO timestamp of creation |

### `remove_training_learning_tracks`

Removes one or more learning track curriculum steps from a training document. Provide the training UUID (find it via search_training or get_training_details) and identify steps by learningTrackIds (from learningTracks), titles (case-insensitive), and/or baseItems (linked document UUIDs). By default, publishes the training after removal so changes are visible outside edit mode. Set publish to false to update the draft only. Returns which steps were removed and which were not found.

| Parameter | Type | Required | Notes |
|---|---|---|---|
| `trainingId` | string (uuid) | Yes | UUID of the training document. Use search_training or get_training_details to find the training ID first. |
| `learningTrackIds` | array of string (uuid) | No | Learning track entry UUIDs to remove. Use id from learningTracks in get_training_details or search_training. |
| `titles` | array of string | No | Curriculum step titles to remove (case-insensitive). |
| `baseItems` | array of string (uuid) | No | Linked document UUIDs to remove (matches learning track baseItem). |
| `publish` | boolean | No | Whether to publish the training after removing steps so changes are visible outside edit mode. Defaults to true. Set to false to update the draft only. Default: `true`. |
| `versionTitle` | string | No | Optional version title when publish is true (e.g. 'Updated learning track'). Uses a timestamp if omitted. |

**Returns**

| Field | Type | Notes |
|---|---|---|
| `trainingId` | string (uuid) | UUID of the updated training document |
| `removed` | array of object | Learning track steps successfully removed Contains: `id`, `baseItem`, `title`, `estimatedTime`, `discriminator`, `sortOrder`, `createdAt` |
| `skipped` | array of object | Learning track steps that were not found on this training Contains: `id`, `title`, `baseItem`, `reason` |
| `published` | object or null | Published version snapshot when publish is enabled; null when publish is false |

---

*Generated from the MCP schema snapshot. Refresh: re-dump `data/mcp-schemas.json` from the live connector, then run `python3 scripts/generate_tool_reference.py`. In the production pipeline this runs on every deploy.*


---

# Changelog (https://systemhub.com/docs/changelog)

> Part of systemHUB Docs · Connect: Settings → AI Gateway in systemHUB · Auth: OAuth (scoping is workspace-level today — see Getting started) · MCP tools: 48 · Full corpus: https://systemhub.com/llms-full.txt

What changed in the systemHUB MCP and these docs, newest first. The [tool reference](/docs/tool-reference) is regenerated from the live schema snapshot on every deploy; this page records the deltas so a returning agent (or its human) can see what's new at a glance.

## 2026-08-08

- **Tool renamed: `generate_document_share_link` → `get_document_share_link`.** The rename happened on the live MCP after our last schema pull, so the docs were pointing agents at a tool that no longer exists. Caught in technical review before the public flip. Snapshot re-pulled from the live endpoint and all references updated. (Earlier changelog entries keep the old name — they're a record of what was true at the time.)
- Reminder for maintainers: **the schema snapshot goes stale.** Re-pull from the live MCP endpoint as part of any deploy that matters, not just when tools are added.

## 2026-08-07 (later)

- **[Tool reference](/docs/tool-reference) now documents response shapes.** Every one of the 48 tools gains a generated **Returns** table with field names, types and one level of nesting — so `state` vs `documentState` and `reviewDate` vs `review_date` are answerable from the page instead of by calling each tool and reverse-engineering the response. Generated from the live schemas like the rest of the page, so it can't drift.
- **Corrected the review-debt recipe** on [Organise the library](/docs/guides/organising-content) and [Audit access](/docs/guides/auditing-access). Both said to find overdue documents by scanning for `state: 2` (RED). RED doesn't set itself, so an untended library reports zero debt. Use **`reviewDate`** (on every response) — anything in the past, plus anything with no review date set.
- **[Sharing & links](/docs/concepts/sharing-and-links):** noted that opening a share link rewrites to a `/guest/` route carrying the alias, and that **the section segment isn't validated** — a system's UUID and code under `/policies/` still renders the system, so don't infer section from the URL.

## 2026-08-07

**Client compatibility documented honestly, after an independent cross-platform test.** [Getting started](/docs/getting-started) previously implied any MCP client would work, with ChatGPT as a "same pattern" aside. That overclaimed:

- **Google Gemini CLI is verified working** — 48 tools over OAuth against a production workspace, with the exact `gemini mcp add` command now documented. Retrieval behaviour was identical to Claude's, confirming the server behaves the same regardless of client.
- **Concurrent clients verified** — Claude and Gemini CLI held live sessions on the same user simultaneously. One token can serve several clients (generating a *new* token still disconnects all of your own at once).
- **But several clients can't connect at all:** ChatGPT needs a paid tier with developer mode, and the Gemini **web app** has no custom-server option whatsoever (Gemini Enterprise or the CLI only). A new compatibility table states which clients work, and a rollout warning flags that free-tier users may have no route in.

## 2026-08-05

From a second-round external audit (Jim Carlin), both on [Sharing & links](/docs/concepts/sharing-and-links):

- **The human-readable share link is not agent-fetchable.** It's a client-rendered view, so a plain HTTP request returns the JavaScript shell rather than the document — and the 404 for a wrong share code is *also* client-side, so status codes prove nothing. Stated explicitly now, along with the consequence: with the api-host form still 403ing, **there is currently no share URL an external agent can fetch without a browser**. Share links are for people; programs should use MCP.
- **Share codes are not unique per document.** Duplicating a document copies its share code, so a copy and its original share one code (reproduced across two document pairs). Index on document UUID, not share code. Two code formats are also in circulation, so don't validate by shape. Logged with the product team.

## 2026-08-04

**Corrections from a second external field audit** (all 15 pages read and cross-checked against the live schemas and a 30-call pipeline run — thank you, Jim Carlin):

- **NEW — the human-readable share link is documented.** `https://{alias}.systemhub.com/systems/{uuid}/{shareCode}` **renders the published document in a browser with no login** (verified 4 Aug in a clean session; a wrong share code 404s). [Sharing & links](/docs/concepts/sharing-and-links) previously said no human app URL existed via the API — that was wrong, and it was steering agents away from a working answer. This is also the practical workaround for the `api.systemhub.com` 403.
- **Fixed a broken example.** [Organise the library](/docs/guides/organising-content) showed `{"parent": "root"}` on the folder-create tools. `parent` is typed as a UUID there and `"root"` is rejected — omit the field for top level. (`"root"` is valid on `get_folder_tree`, which is where it was copied from.)
- **Corrected the publish model.** [Document lifecycle](/docs/concepts/document-lifecycle) implied edits need an explicit publish. They don't — `edit_*` auto-publishes, **and so do metadata writes**: `add_document_tags` and the template/media/attachment tools default to `publish: true`. Tagging a document publishes it, which defeats a `publish: false` created earlier. There is no quiet-editing mode by default.
- **[Teach your AI](/docs/teach-your-ai)** no longer writes an ambiguous state fact into permanent agent memory ("drafts are ORANGE" collided with state 0 = GREY/draft and with `publish: false`); it now names all three senses.
- **Corrected the 126KB advice.** "Write in sections" made it worse — `edit_*` replaces the whole content field, so incremental writing resends everything each time. Split across documents instead.
- Also: `get_document_activity_log` added to the audit tool list, a warning that `manage_document_members` `update` **replaces** roles rather than merging, a pagination warning, and a corrected tool count on [Audit access](/docs/guides/auditing-access).

## 2026-07-31 (later)

- **[Getting started](/docs/getting-started) now carries a field-tested team-connection procedure**, verified live by a SYSTEMologist agency connecting a second team member: each person generates their own token from their own login, then connects through the *existing* connector entry and approves as themselves. Added troubleshooting rows for *"No active agent token found"* and *"a server with this URL already exists"*.
- **Correction:** generating a token does **not** disconnect colleagues. Tokens are per-person — generating revokes only your own previous token and your own sessions. Earlier wording here implied it was account-wide; that was wrong, and it was disproven in a live test (one member generated a token while another stayed connected throughout).

## 2026-07-31

- **Correction — MCP session scoping is workspace-level, not per-user.** These docs previously stated that a connection is scoped to the connecting user's visibility. That is **not** how the current OAuth flow behaves: a session is bound to the identity on the workspace's **most recently generated AI Gateway token**, regardless of who connects. On a multi-user workspace, agents can therefore resolve to the same identity — in either direction (a restricted user inheriting broader visibility, or an admin being scoped down). The claim has been corrected on Getting started, Errors & limits, Teach your AI and llms.txt. A fix binding each connection to the person connecting is logged as a critical item with the product team; these docs will be updated when it ships.
- Practical guidance until then: treat MCP access as **workspace-level**. Connect agents only for people you're comfortable seeing everything the token generator can see, and don't rely on MCP session identity for audit attribution.

## 2026-07-29

- **Docs now live at systemhub.com/docs** (review mode — noindex until final technical sign-off). llms.txt and llms-full.txt are served at the systemhub.com root.
- **Getting started now carries the confirmed connection details from the product UI:** server URL `https://mcp.systemhub.com/mcp`, OAuth Client ID = company alias, token shown once with a **180-day lifetime** (rotation reminder at day 144), and the gotcha that generating a new token immediately revokes the old one and disconnects connected agents (also added to troubleshooting).

## 2026-07-28

**Field-tested by a beta agency** (25-call end-to-end SOP pipeline). Two issues confirmed and documented while fixes are tracked with the product team:

- **HTML-escaped `content` is stored silently** and publishes as visible tag soup — warning added to [Authoring content](/docs/concepts/authoring-content) and the [errors table](/docs/concepts/errors-and-limits): send raw HTML, read back after writing.
- **Share links currently fail external fetch** (403 "Company not found") — [Sharing & links](/docs/concepts/sharing-and-links) updated with the known issue; don't promise external access until the fix lands.
- Also noted on Sharing & links: **no human app URL exists in any API response** today (`appUrl` is a requested enhancement).

## 2026-07-27

**Docs: machine-affordance upgrades** (patterns adopted from an audit of Outstand's docs — the headless reference standard):

- **`/llms-full.txt`** — the entire docs corpus in one fetch, generated with every build. Linked from llms.txt.
- **Canonical metadata on every raw page** — each `.md` now carries its canonical URL and a connect/auth/tool-count line, so a page quoted into an agent's context keeps its address.
- **llms.txt hardened** — dated, with a "Canonical facts" block (authoritative over stale third-party write-ups) and a "What the MCP does not do" list.
- **Getting started expanded** — per-client connection steps (Claude, ChatGPT, any MCP client) and a six-symptom troubleshooting table.
- **[Document lifecycle](/docs/concepts/document-lifecycle)** gained a "How systemHUB behaves over time" table — the create/publish/edit/editor-filter sequence an agent should reason with.
- **[Teach your AI](/docs/teach-your-ai)** — new page: the first-session prompt and the standing-context briefing an agent saves (CLAUDE.md or equivalent) so every future session can drive systemHUB without re-learning.

## 2026-07-23

**MCP: 5 new tools** (snapshot 43 → 48):

- `generate_document_share_link` — public, no-login share URLs that serve the published document as machine-readable JSON. See the new [Sharing & links](/docs/concepts/sharing-and-links) page.
- `get_document_activity_log` — per-document audit trail: who created it, who last edited it, full event feed (optionally including view events).
- `manage_document_members` — **write-side document access**: assign/remove members and roles on a document.
- `list_company_members` / `list_roles` — resolve people and roles by name to UUIDs (companions to `manage_document_members`).

**Known-limits changes** these tools unlock:

- ~~"No write-side user management"~~ → narrowed: document-level member/role **assignment is now writable**. Seat provisioning (inviting people, allocating licences) remains app-UI only.
- ~~"No who-viewed-what telemetry"~~ → narrowed: **per-document activity (including views) is now readable** via the activity log. Workspace-wide usage analytics remain unavailable.

**Docs:** added [Sharing & links](/docs/concepts/sharing-and-links) and this changelog; system anatomy in [Authoring content](/docs/concepts/authoring-content) extended to Trigger → Steps → Definition of done.

## 2026-07-22

- Initial public preview: getting started (with real AI Gateway connection steps), [quick wins](/docs/quick-wins) (8 verified prompts), four concept pages, three worked guides, and the full generated tool reference (43 tools).
- Every page dual-served as raw markdown (`.md`), curated `llms.txt` published.


---

# Teach your AI systemHUB (https://systemhub.com/docs/teach-your-ai)

> Part of systemHUB Docs · Connect: Settings → AI Gateway in systemHUB · Auth: OAuth (scoping is workspace-level today — see Getting started) · MCP tools: 48 · Full corpus: https://systemhub.com/llms-full.txt

AI sessions forget. These docs make any connected agent capable *today*; this page makes it capable **every day** — by saving a short systemHUB briefing into your own workspace (your repo's `CLAUDE.md`, your project instructions, or wherever your AI keeps standing context), so future sessions start already knowing how to drive systemHUB well.

## The first-session prompt

Paste this into your AI once systemHUB is connected (see [Getting started](/docs/getting-started)):

> You're connected to our systemHUB via the MCP connector. Do four things:
>
> 1. Fetch https://systemhub.com/llms-full.txt and read it — it's the full guide to driving systemHUB well.
> 2. Map our Systems folder tree and give me a one-paragraph read on how our library is organised and where the gaps look biggest.
> 3. Pick one process we clearly run but haven't documented, and draft it as a system for my review — follow the docs' authoring contract: trigger, steps, definition of done, ORANGE state, yellow-highlight anything you'd have to guess.
> 4. Save a concise systemHUB briefing into our standing context (CLAUDE.md or equivalent) so future sessions don't need to re-learn any of this — the docs suggest what to include at systemhub.com/docs/teach-your-ai.
>
> Then tell me: what did the docs not explain that you needed?

## What the saved briefing should contain

The generic layer lives in these docs — don't copy it all. The briefing is the *bridge*: just enough standing context plus pointers back here. A good one:

```markdown
## systemHUB (via MCP connector)

Our process library. Systems (SOPs), Policies, Trainings. Connected via the
systemHUB MCP connector. Note: MCP scoping is workspace-level today
(a known issue — the connection follows the workspace token, not the
individual), so treat what the agent can see as account-wide.

Ground rules (full docs: https://systemhub.com/llms-full.txt):
- Orient before acting: get_folder_tree / search_by_name first; never create
  into a guessed location; check for duplicates before creating.
- New work goes in ORANGE (state: 1 = needs review). Never set GREEN (3)
  yourself — approval is human. Note "draft" is ambiguous here: state 0 is
  GREY/draft, and `publish: false` is a separate, unrelated hidden-draft
  concept. Our convention is ORANGE for anything awaiting human review.
- Edits and even tagging auto-publish. There is no quiet-editing mode by
  default — assume any write to a live document is immediately visible.
- Author to the contract: Overview in `description`; body = Trigger, then
  <h3> steps, then Definition of done. H1–H3 only, 4 marker-* highlights,
  no inline <code>, no external images (yellow-flag an upload spot instead).
- Yellow-highlight every gap — never invent names, links or thresholds.
- Never touch master templates (isMasterTemplate: true).
- Can't do: deletes, seat provisioning, workspace analytics.
- If a tool behaves unexpectedly, check the changelog:
  https://systemhub.com/docs/changelog

Our specifics:
- Folder convention: [e.g. numbered departments — 1. Marketing, 2. Sales…]
- Owners: [who owns which department's systems]
- House style: [anything your business wants systems to always include]
```

The `Our specifics` block is the part only you can supply — your AI should fill it in from what it finds in your library, and you should correct it. That's the piece these docs can never know.

## Why this works

- **One fetch, full context.** The [llms-full.txt](https://systemhub.com/llms-full.txt) corpus is designed to be read in one go; the briefing means future sessions only re-fetch it when something's changed (the [changelog](/docs/changelog) says when).
- **Your library becomes the source of truth your AI reasons from** — "answer from our systemHUB, cite the system" beats "answer from memory" every time. See [Quick wins](/docs/quick-wins) for the prompts that exploit this.
- **The contract travels.** The authoring rules in the briefing mean even a session that never reads the full docs still produces documents that survive the editor.

Next: **[Quick wins →](/docs/quick-wins)**