# 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: 55 · 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 (on the CREATE tools it must be a UUID)
→ 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"` works on the READ tools, not the create ones.** Since 22 Sep 2026 `get_folder_tree` / `get_policy_tree` / `get_training_tree` accept `"root"`, and it means the same as omitting `parent` (the top level). On `create_folder` / `create_policy_folder` / `create_training_folder`, `parent` is still typed `format: uuid` and `"root"` is rejected — omit it entirely for a top-level folder. (Between 28 Aug and 22 Sep `"root"` was rejected everywhere, which is what earlier versions of this page said.)

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.

> ⚠️ **Tags are case-sensitive.** `Sales` and `sales` are two separate tag objects with different UUIDs, so a filter or count returns only the documents matching the exact casing. In one audited library this split a single tag across 11 documents and 2, with the same tag appearing twice in the tag list. `add_document_tags` matches existing tags **by exact title** and silently creates a new one for anything that doesn't match — so a difference in capitalisation quietly forks your taxonomy. **Read the existing tag titles before writing, and reuse them verbatim.** (Verified on one pair, 28 Aug 2026; several more suspected.)

## 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).