Guide: organise & maintain the library

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.

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):

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.

Learning tracks