From cd1339494497ec8bab01d3d13e0fde3b40a868e0 Mon Sep 17 00:00:00 2001
From: Rick Jennings <rjennings055@gmail.com>
Date: Wed, 9 Sep 2026 16:35:53 -0400
Subject: [PATCH] ph.doc: add Equip Templates chapter

---
 src/xeto/ph.doc/EquipTemplates.md | 66 +++++++++++++++++++++++++++++++
 src/xeto/ph.doc/index.md          |  1 +
 2 files changed, 67 insertions(+)
 create mode 100644 src/xeto/ph.doc/EquipTemplates.md

diff --git a/src/xeto/ph.doc/EquipTemplates.md b/src/xeto/ph.doc/EquipTemplates.md
new file mode 100644
index 0000000..13c7d42
--- /dev/null
+++ b/src/xeto/ph.doc/EquipTemplates.md
@@ -0,0 +1,66 @@
+<!--
+title:      EquipTemplates
+author:     Rick Jennings
+created:    9 Sep 2026
+copyright:  Copyright (c) 2026, Project-Haystack
+-->
+
+# Equip Templates
+An equip template models a piece of equipment from a manufacturer as an extension of
+[ph::Equip] using attributes and points. The site-specific tags defined in the
+[Equips](Equips.md) chapter, such as `siteRef` and `spaceRef`, are not part of
+an equip template because it is not bound to a location.
+
+# Attributes
+An attribute is a single piece of static information about a piece of equipment,
+such as its manufacturer, model, or physical dimensions, modeled as a subtype
+of [ph::Attr]. At this time, only `Attr` subtypes already defined in the core
+`ph.attrs` library should be used in an equip template to avoid overwhelming
+reviewers.
+
+# Points
+Project Haystack supports modeling all data points made available by a manufacturer,
+including those outside Haystack's standard vocabulary, by applying the `notHaystack`
+marker tag to the applicable points. These points still extend [ph::PhEntity]
+even though their meaning is not fully expressed by a standard spec required
+for interoperability.
+
+Each point should include every protocol address available for it, modeled as a
+[ph.protocols::ProtocolAddr] such as [ph.protocols::ModbusAddr] or
+[ph.protocols::BacnetAddr].
+
+Every point in an equip template must have a `dis` tag defined according to the
+manufacturer's documentation. When the documentation gives conflicting definitions
+(for example, a point available via both Modbus and BACnet with mismatched
+descriptions), resolving the conflict is the responsibility of the tool creating
+the template.
+
+# Example
+
+```xeto
+// Sample device model for a generic manufacturer's power meter
+ExampleAcElecMeter : AcElecMeter {
+  attrs: {
+    ManufacturerAttr { val: "Example Manufacturer" }
+    ModelSeriesAttr { val: "Example Series 100" }
+  }
+  points: {
+    // non-standard point
+    NumberPoint {
+      sensor
+      dis: "Real Part of Voltage Positive Sequence"
+      unit: Unit <invariant> "%"
+      notHaystack
+      modbusAddr: { addr: "416385", encoding: "f4" }
+      bacnetAddr: { addr: "AI3" }
+    }
+    // standard point
+    ElecAcPhaseRmsVoltageSensor {
+      phase: "L1"
+      dis: "L1 Voltage"
+      modbusAddr: { addr: "416387", encoding: "f4" }
+      bacnetAddr: { addr: "AI4" }
+    }
+  }
+}
+```
diff --git a/src/xeto/ph.doc/index.md b/src/xeto/ph.doc/index.md
index a9614df..9f69a62 100644
--- a/src/xeto/ph.doc/index.md
+++ b/src/xeto/ph.doc/index.md
@@ -15,6 +15,7 @@
 - [Synthetics](Synthetics.md): Synthetic data
 - [Spaces](Spaces.md): Space entities including floors, rooms, and zones
 - [Equips](Equips.md): Equipment entities
+- [EquipTemplates](EquipTemplates.md): Equipment templates
 - [Points](Points.md): Point entities - sensors, actuators, and setpoints
 - [PointPatterns](PointPatterns.md): Standardized specs and patterns for points
 - [Weather](Weather.md): Weather station entities