> ## Documentation Index
> Fetch the complete documentation index at: https://docs.holos.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Guidebooks

> Everything an organization knows about one physical thing, in one place.

A **Guidebook** collects everything an organization knows about a single physical thing: a drawing, an assembly, a piece of equipment. It gathers the [procedures](/domains/procedures) that apply to it, the technical documentation for it, and its CAD or digital-twin [model](/domains/objects).

A guidebook does not own procedures. It links them, so the same procedure can appear in any number of guidebooks and still have one place where its content lives.

## Key fields

| Field                   | Description                                                           |
| ----------------------- | --------------------------------------------------------------------- |
| `shortId`               | Stable public identifier. Renaming never breaks a link                |
| `title` / `description` | The guidebook itself                                                  |
| `drawing_number`        | The customer's drawing number, where the subject is a drawing         |
| `drawing_revision`      | Revision of that drawing                                              |
| `customer_item_id`      | The customer's own identifier for the item                            |
| `procedures`            | Links to procedures, each with its own placement (see below)          |
| `trackedObjects`        | Objects the Capture app should track for this guidebook               |
| `referenceMaterials`    | Uploaded documentation such as PDFs and drawings                      |
| `archivedAt`            | Set when archived; archived guidebooks are hidden rather than deleted |

## Linked procedures

Each link carries how it got there and how it is presented:

| Field        | Description                                                                                                                    |
| ------------ | ------------------------------------------------------------------------------------------------------------------------------ |
| `provenance` | `manual` (someone added it), `derived` (it came from the subject), or `extracted` (it was generated from a reference document) |
| `pinned`     | Surfaced above the rest                                                                                                        |
| `hidden`     | Kept on the guidebook but out of the default view                                                                              |
| `order`      | Explicit position, when the default ordering is not wanted                                                                     |

## Extracting a procedure from a document

A reference document can become a draft procedure. `POST /guidebooks/{guidebookId}/reference-material/{fileId}/extract-procedure` reads the document and produces a procedure with steps, callouts, and outline structure, linked back with `provenance: extracted`. Converting a document first, with `/convert`, gives the structured form the extraction reads.

## Endpoints

Full endpoint reference is available in the OpenAPI spec. Key operations:

* `GET /guidebooks`: list guidebooks
* `POST /guidebooks`: create one
* `GET /guidebooks/{guidebookId}`: get a guidebook with its links
* `PATCH /guidebooks/{guidebookId}`: update its fields
* `POST /guidebooks/{guidebookId}/procedures`: link a procedure
* `PATCH /guidebooks/{guidebookId}/procedures/{procedureId}`: pin, hide, or reorder a link
* `POST /guidebooks/{guidebookId}/tracked-objects`: link an object for tracking
* `POST /guidebooks/{guidebookId}/reference-material/upload-url`: upload documentation