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