# Guide: draft an SOP into systemHUB

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": "<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. Record it being done</h3><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`
- [ ] 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