> For the complete documentation index, see [llms.txt](https://docs.kula.digital/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.kula.digital/whats-in-your-data/equipment.md).

# Equipment — ontology map

What the Equipment register gives Kula Intelligence — machines, planned maintenance, faults and what repairs cost — what it leaves out on purpose, and why an empty register means the app is unused, no

**Source id:** none — this is not a connected system. · **Role:** the studio's own register of machines and fittings, kept in Kula's **Equipment** app (photo capture, a fault checklist, planned maintenance). Nothing is synced from a booking or accounting system; every row was entered or confirmed by someone at the studio. · **Access:** read-only views in the **`facilities`** schema, through `execute_query`.

Equipment answers questions no other map can: what the studio **owns**, where each machine sits, what is **due for maintenance**, what is **broken right now**, and what repairs have **cost**. It knows nothing about members, classes or sales.

## Coverage at a glance

| View                           | Grain                                | What it holds                                                                                                                           |
| ------------------------------ | ------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------- |
| `facilities.equipment`         | **one machine**                      | site, room and floor, name, category, make, model, serial, status, install and purchase dates, purchase cost, supplier, warranty        |
| `facilities.maintenance_plan`  | **one repeating task on a machine**  | the task, its interval, when it was last done, when it next falls due, and `overdue` / `days_until_due`                                 |
| `facilities.maintenance_event` | **one fault, service or inspection** | kind, event\_title, event\_severity, status, reported and closed times, vendor, downtime, parts and labour cost, `is_open`, `days_open` |

There is no `source` column to filter by and no history before the studio started using the app. The seed on the Juniper demo studio is rebuilt every night, with dates set back from the run.

## What is left out on purpose

These stay in the app and its `ops_equipment_list` / `ops_equipment_get` tools, not in SQL:

* **People.** Who reported, was assigned or closed a fault, and who added a machine. There is no person column anywhere in `facilities`.
* **Free text.** Machine notes, the fault description, the outcome, parts used, and a plan's step-by-step procedure. A fault's **title** is kept, as `event_title`.
* **Photos, manuals, repair videos** and the capture queue.

## Counting traps

* **`site_id` is the Ops site code** (the studio's short name for a site, such as `highlands`). It is **not** `people.location.site_id`. Do not join the two on it; name the site from the code.
* **A retired machine stays.** Filter `status <> 'retired'` for what the studio has now. `out_of_service` is still owned.
* **Open means not done and not deferred.** Use `is_open`. A `deferred` fault is neither open nor fixed.
* **A NULL cost is not a free repair.** Costs are optional and typed at close-out; sum with that in mind and say how many jobs were costed.
* **A plan with no `last_done_at` has never been done.** Its `next_due_at` is the first due date, not a missed one, until that date passes.
* **Name your own columns plainly.** Do not alias a cast or expression (`next_due_at::date AS due`); it can come back null. Select the column as it is and format it afterwards.
* **`overdue`, `days_until_due`, `days_open` and `under_warranty` move with the clock.** They are computed when the query runs.
* **Plans are per machine.** Ten machines with the same task are ten rows; count distinct tasks if you mean the routine, not the workload.
* **An empty result is an unused app,** not missing data. Check `facilities.equipment` for any rows before telling an operator something is absent.

## Fastest tool for each question

| Question                                           | Use                                                                                                                                             |
| -------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| What do we own, by site and category?              | `SELECT site_id, category, COUNT(*) FROM facilities.equipment WHERE status <> 'retired' GROUP BY 1, 2`                                          |
| What maintenance is overdue?                       | `SELECT site_id, equipment_name, task, days_until_due FROM facilities.maintenance_plan WHERE overdue`                                           |
| What is broken right now?                          | `SELECT site_id, equipment_name, event_title, event_severity, days_open FROM facilities.maintenance_event WHERE is_open AND kind = 'unplanned'` |
| What did repairs cost?                             | `SELECT equipment_name, COUNT(*), SUM(total_cost) FROM facilities.maintenance_event WHERE closed_at IS NOT NULL GROUP BY 1`                     |
| The notes, the fault text, the people on a machine | the `ops_equipment_get` tool, not SQL                                                                                                           |
