# 99-reference — read-only worked examples

> [!IMPORTANT]
> **Nothing in this folder is edited, built or deployed.** It is reference
> material only. It sorts last deliberately — you do not start here.

**CI Server has no published file-format documentation.** The `.qli` import
format and the display XML schema were both learned by reading real exports.
That is what this folder preserves: without it, `04-scada/modbus/gen_ciserver_qli.py`
and `04-scada/hmi/build_display.py` become generated code nobody can extend.

Neither folder is read at build time — the knowledge is already encoded in those
scripts. These files are here for **the next person who needs to change them**.

## `ciserver-qli-exports/` — the `.qli` format specification

Ten real exports from a live CI Server. Every field layout and constant in
`gen_ciserver_qli.py` was copied from these.

| File | Shows |
|---|---|
| `section_df.qli` | `@SECTION_DF` — the hierarchy CI Server derives from dots in a name |
| `item_df.qli` | `@ITEM_DF` — item definitions |
| `modbus_point_df.qli` | `@MODBUS_POINT_DF` — Modbus point definitions and addressing |
| `items.qli`, `items_to_import.qli`, `export.qli` | Item exports in their various shapes |
| `ITEM_HIS.qli`, `ITEM_HIS_IN.qli` | Historian item configuration |
| `MQTT_RULE.qli` | MQTT rule definitions — not used by this demo, kept as format reference |
| `TestTagsShortlist.qli` | A small hand-made list, useful as a minimal example |

## `ciserver-hmi-deployment/` — the display and component vocabulary

A subset of a real CI Server HMI deployment (the "Straddle" project). This is
where `build_display.py`'s component kit came from.

| Folder | Contents | Why it is here |
|---|---|---|
| `components/` | The component definitions | **The vocabulary.** What CI View can actually draw, and the exact XML each component expects. The most important folder here. |
| `layouts/` | Screen layouts | How displays are framed and navigated |
| `thresholds/`, `locales/` | Threshold and locale config | Small, and completes the picture of a deployment's shape |
| `displays/` | **6 of 84** finished screens | Worked examples — see below |

### The six displays, and why each was chosen

| File | Why |
|---|---|
| `AOG_DisplayTemplate.xml` | The blank template — the **minimal valid display**. Start here. |
| `AOG_ItemFaceplate.xml` | The standard AOG faceplate. The pattern this demo's pump faceplates follow. |
| `Straddle_Overview.xml` | A real process overview — the closest analogue to a pump-station overview screen. |
| `Straddle_01_Detail.xml` | An equipment detail screen — one asset in depth. |
| `Straddle_Trends.xml` | Trend display construction. |
| `Straddle_Alarms.xml` | Alarm list display. |

## What was deliberately left out

| Dropped | Size | Reason |
|---|---|---|
| `symbols/` | 107 MB | 3130 symbol graphics, 177 of them the AOG standard set. This is CI Server's **own installed library** — it is already on `yau-poc-cicore1`. Committing it would make it 78% of this repo, permanently, in every clone. |
| 78 further displays | ~11 MB | Colour variants (`_Grey`, `_Light`) and near-duplicates. Six convey the format; 84 do not. |
| `.lck`, `.autosave`, `visualizationCache.ser` | — | Editor lock files, autosaves and a binary cache. No informational value. |
| OpenPLC sample projects | 6.5 MB | *Water Tower*, *Production Line*, *Traffic Light SFC* — stock vendor samples, not specific to this work. Download them from the OpenPLC Editor's own examples if wanted. |

Original size 138 MB; kept 5 MB.