@blockml/bom 0.1.0

package/blocks/org/blockml/bml/bom/composition/DirectiveAttribute.bml

@@ -0,0 +1,35 @@
+<!--
+  BOM Urmodell — DirectiveAttribute
+  FQN: org.blockml.bml.bom.composition.DirectiveAttribute
+-->
+<block
+  xmlns="http://blockml.org/bml"
+  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+  xsi:schemaLocation="http://blockml.org/bml https://blockml.org/schemas/bml.xsd
+                      "
+  xmlns:blockml="org.blockml.bml"
+  xmlns:bom="org.blockml.bml.bom"
+  xmlns:bomapi="org.blockml.bml.bom.api"
+  xmlns:bomblock="org.blockml.bml.bom.block"
+  xmlns:bomcap="org.blockml.bml.bom.capability"
+  xmlns:bomcommon="org.blockml.bml.bom.common"
+  xmlns:bomcomp="org.blockml.bml.bom.composition"
+  xmlns:bomdoc="org.blockml.bml.bom.document"
+  xmlns:bomdocumentation="org.blockml.bml.bom.documentation"
+  xmlns:bommember="org.blockml.bml.bom.member"
+  xmlns:bomtype="org.blockml.bml.bom.type"
+  xmlns:bomvalue="org.blockml.bml.bom.value"
+  xmlns:core="org.blockml.bml.core"
+  xmlns:def="org.blockml.bml.definition"
+  xmlns:type="org.blockml.bml.type">
+
+  <name>DirectiveAttribute</name>
+  <type>bomcomp:DirectiveAttribute</type>
+  <baseType>bom:UrmodellType</baseType>
+  <is>Abstract union of flow-control directives</is>
+
+  <documentation>EachDirective | IfDirective | UnlessDirective | WithDirective. Stored unexpanded.</documentation>
+
+  <abstract>true</abstract>
+
+</block>

package/blocks/org/blockml/bml/bom/composition/EachDirective.bml

@@ -0,0 +1,49 @@
+<!--
+  BOM Urmodell — EachDirective
+  FQN: org.blockml.bml.bom.composition.EachDirective
+-->
+<block
+  xmlns="http://blockml.org/bml"
+  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+  xsi:schemaLocation="http://blockml.org/bml https://blockml.org/schemas/bml.xsd
+                      "
+  xmlns:blockml="org.blockml.bml"
+  xmlns:bom="org.blockml.bml.bom"
+  xmlns:bomapi="org.blockml.bml.bom.api"
+  xmlns:bomblock="org.blockml.bml.bom.block"
+  xmlns:bomcap="org.blockml.bml.bom.capability"
+  xmlns:bomcommon="org.blockml.bml.bom.common"
+  xmlns:bomcomp="org.blockml.bml.bom.composition"
+  xmlns:bomdoc="org.blockml.bml.bom.document"
+  xmlns:bomdocumentation="org.blockml.bml.bom.documentation"
+  xmlns:bommember="org.blockml.bml.bom.member"
+  xmlns:bomtype="org.blockml.bml.bom.type"
+  xmlns:bomvalue="org.blockml.bml.bom.value"
+  xmlns:core="org.blockml.bml.core"
+  xmlns:def="org.blockml.bml.definition"
+  xmlns:type="org.blockml.bml.type">
+
+  <name>EachDirective</name>
+  <type>bomcomp:EachDirective</type>
+  <baseType>bomcomp:DirectiveAttribute</baseType>
+  <is>bml:each directive (type: each)</is>
+
+  <documentation>bml:each directive (type: each)</documentation>
+
+  <properties>
+    <type type="type:Text">
+      <documentation>type (required). TS type: type:Text.</documentation>
+      <value>each</value>
+    </type>
+    <variables type="type:Text[]">
+      <documentation>variables (required). TS type: type:Text[].</documentation>
+    </variables>
+    <statVariable type="type:Text">
+      <documentation>statVariable (optional). TS type: type:Text.</documentation>
+    </statVariable>
+    <collection type="bomvalue:ExpressionValue">
+      <documentation>collection (required). TS type: bomvalue:ExpressionValue.</documentation>
+    </collection>
+  </properties>
+
+</block>

package/blocks/org/blockml/bml/bom/composition/IfDirective.bml

@@ -0,0 +1,43 @@
+<!--
+  BOM Urmodell — IfDirective
+  FQN: org.blockml.bml.bom.composition.IfDirective
+-->
+<block
+  xmlns="http://blockml.org/bml"
+  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+  xsi:schemaLocation="http://blockml.org/bml https://blockml.org/schemas/bml.xsd
+                      "
+  xmlns:blockml="org.blockml.bml"
+  xmlns:bom="org.blockml.bml.bom"
+  xmlns:bomapi="org.blockml.bml.bom.api"
+  xmlns:bomblock="org.blockml.bml.bom.block"
+  xmlns:bomcap="org.blockml.bml.bom.capability"
+  xmlns:bomcommon="org.blockml.bml.bom.common"
+  xmlns:bomcomp="org.blockml.bml.bom.composition"
+  xmlns:bomdoc="org.blockml.bml.bom.document"
+  xmlns:bomdocumentation="org.blockml.bml.bom.documentation"
+  xmlns:bommember="org.blockml.bml.bom.member"
+  xmlns:bomtype="org.blockml.bml.bom.type"
+  xmlns:bomvalue="org.blockml.bml.bom.value"
+  xmlns:core="org.blockml.bml.core"
+  xmlns:def="org.blockml.bml.definition"
+  xmlns:type="org.blockml.bml.type">
+
+  <name>IfDirective</name>
+  <type>bomcomp:IfDirective</type>
+  <baseType>bomcomp:DirectiveAttribute</baseType>
+  <is>bml:if directive (type: if)</is>
+
+  <documentation>bml:if directive (type: if)</documentation>
+
+  <properties>
+    <type type="type:Text">
+      <documentation>type (required). TS type: type:Text.</documentation>
+      <value>if</value>
+    </type>
+    <condition type="bomvalue:ExpressionValue">
+      <documentation>condition (required). TS type: bomvalue:ExpressionValue.</documentation>
+    </condition>
+  </properties>
+
+</block>

package/blocks/org/blockml/bml/bom/composition/InstanceAggregationComposition.bml

@@ -0,0 +1,42 @@
+<!--
+  BOM Urmodell — InstanceAggregationComposition
+  FQN: org.blockml.bml.bom.composition.InstanceAggregationComposition
+-->
+<block
+  xmlns="http://blockml.org/bml"
+  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+  xsi:schemaLocation="http://blockml.org/bml https://blockml.org/schemas/bml.xsd
+                      "
+  xmlns:blockml="org.blockml.bml"
+  xmlns:bom="org.blockml.bml.bom"
+  xmlns:bomapi="org.blockml.bml.bom.api"
+  xmlns:bomblock="org.blockml.bml.bom.block"
+  xmlns:bomcap="org.blockml.bml.bom.capability"
+  xmlns:bomcommon="org.blockml.bml.bom.common"
+  xmlns:bomcomp="org.blockml.bml.bom.composition"
+  xmlns:bomdoc="org.blockml.bml.bom.document"
+  xmlns:bomdocumentation="org.blockml.bml.bom.documentation"
+  xmlns:bommember="org.blockml.bml.bom.member"
+  xmlns:bomtype="org.blockml.bml.bom.type"
+  xmlns:bomvalue="org.blockml.bml.bom.value"
+  xmlns:core="org.blockml.bml.core"
+  xmlns:def="org.blockml.bml.definition"
+  xmlns:type="org.blockml.bml.type">
+
+  <name>InstanceAggregationComposition</name>
+  <type>bomcomp:InstanceAggregationComposition</type>
+  <baseType>bom:UrmodellType</baseType>
+  <is>Inline aggregation composition on a Block instance</is>
+
+  <documentation>Inline aggregation composition on a Block instance</documentation>
+
+  <properties>
+    <aggregationName type="type:Text">
+      <documentation>aggregationName (required). TS type: type:Text.</documentation>
+    </aggregationName>
+    <composition type="bomcomp:CompositionTemplate">
+      <documentation>composition (required). TS type: bomcomp:CompositionTemplate.</documentation>
+    </composition>
+  </properties>
+
+</block>

package/blocks/org/blockml/bml/bom/composition/UnlessDirective.bml

@@ -0,0 +1,43 @@
+<!--
+  BOM Urmodell — UnlessDirective
+  FQN: org.blockml.bml.bom.composition.UnlessDirective
+-->
+<block
+  xmlns="http://blockml.org/bml"
+  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+  xsi:schemaLocation="http://blockml.org/bml https://blockml.org/schemas/bml.xsd
+                      "
+  xmlns:blockml="org.blockml.bml"
+  xmlns:bom="org.blockml.bml.bom"
+  xmlns:bomapi="org.blockml.bml.bom.api"
+  xmlns:bomblock="org.blockml.bml.bom.block"
+  xmlns:bomcap="org.blockml.bml.bom.capability"
+  xmlns:bomcommon="org.blockml.bml.bom.common"
+  xmlns:bomcomp="org.blockml.bml.bom.composition"
+  xmlns:bomdoc="org.blockml.bml.bom.document"
+  xmlns:bomdocumentation="org.blockml.bml.bom.documentation"
+  xmlns:bommember="org.blockml.bml.bom.member"
+  xmlns:bomtype="org.blockml.bml.bom.type"
+  xmlns:bomvalue="org.blockml.bml.bom.value"
+  xmlns:core="org.blockml.bml.core"
+  xmlns:def="org.blockml.bml.definition"
+  xmlns:type="org.blockml.bml.type">
+
+  <name>UnlessDirective</name>
+  <type>bomcomp:UnlessDirective</type>
+  <baseType>bomcomp:DirectiveAttribute</baseType>
+  <is>bml:unless directive (type: unless)</is>
+
+  <documentation>bml:unless directive (type: unless)</documentation>
+
+  <properties>
+    <type type="type:Text">
+      <documentation>type (required). TS type: type:Text.</documentation>
+      <value>unless</value>
+    </type>
+    <condition type="bomvalue:ExpressionValue">
+      <documentation>condition (required). TS type: bomvalue:ExpressionValue.</documentation>
+    </condition>
+  </properties>
+
+</block>

package/blocks/org/blockml/bml/bom/composition/VirtualContainerNode.bml

@@ -0,0 +1,49 @@
+<!--
+  BOM Urmodell — VirtualContainerNode
+  FQN: org.blockml.bml.bom.composition.VirtualContainerNode
+-->
+<block
+  xmlns="http://blockml.org/bml"
+  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+  xsi:schemaLocation="http://blockml.org/bml https://blockml.org/schemas/bml.xsd
+                      "
+  xmlns:blockml="org.blockml.bml"
+  xmlns:bom="org.blockml.bml.bom"
+  xmlns:bomapi="org.blockml.bml.bom.api"
+  xmlns:bomblock="org.blockml.bml.bom.block"
+  xmlns:bomcap="org.blockml.bml.bom.capability"
+  xmlns:bomcommon="org.blockml.bml.bom.common"
+  xmlns:bomcomp="org.blockml.bml.bom.composition"
+  xmlns:bomdoc="org.blockml.bml.bom.document"
+  xmlns:bomdocumentation="org.blockml.bml.bom.documentation"
+  xmlns:bommember="org.blockml.bml.bom.member"
+  xmlns:bomtype="org.blockml.bml.bom.type"
+  xmlns:bomvalue="org.blockml.bml.bom.value"
+  xmlns:core="org.blockml.bml.core"
+  xmlns:def="org.blockml.bml.definition"
+  xmlns:type="org.blockml.bml.type">
+
+  <name>VirtualContainerNode</name>
+  <type>bomcomp:VirtualContainerNode</type>
+  <baseType>bomcomp:CompositionNode</baseType>
+  <is>Virtual bml:container node (kind: virtualContainer)</is>
+
+  <documentation>Virtual bml:container node (kind: virtualContainer)</documentation>
+
+  <properties>
+    <kind type="type:Text">
+      <documentation>kind (required). TS type: type:Text.</documentation>
+      <value>virtualContainer</value>
+    </kind>
+    <directives type="bomcomp:DirectiveAttribute[]">
+      <documentation>directives (optional). TS type: bomcomp:DirectiveAttribute[].</documentation>
+    </directives>
+    <children type="bomcomp:CompositionNode[]">
+      <documentation>children (required). TS type: bomcomp:CompositionNode[].</documentation>
+    </children>
+    <source type="bomcommon:SourceLocation">
+      <documentation>source (optional). TS type: bomcommon:SourceLocation.</documentation>
+    </source>
+  </properties>
+
+</block>

package/blocks/org/blockml/bml/bom/composition/WithBinding.bml

@@ -0,0 +1,42 @@
+<!--
+  BOM Urmodell — WithBinding
+  FQN: org.blockml.bml.bom.composition.WithBinding
+-->
+<block
+  xmlns="http://blockml.org/bml"
+  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+  xsi:schemaLocation="http://blockml.org/bml https://blockml.org/schemas/bml.xsd
+                      "
+  xmlns:blockml="org.blockml.bml"
+  xmlns:bom="org.blockml.bml.bom"
+  xmlns:bomapi="org.blockml.bml.bom.api"
+  xmlns:bomblock="org.blockml.bml.bom.block"
+  xmlns:bomcap="org.blockml.bml.bom.capability"
+  xmlns:bomcommon="org.blockml.bml.bom.common"
+  xmlns:bomcomp="org.blockml.bml.bom.composition"
+  xmlns:bomdoc="org.blockml.bml.bom.document"
+  xmlns:bomdocumentation="org.blockml.bml.bom.documentation"
+  xmlns:bommember="org.blockml.bml.bom.member"
+  xmlns:bomtype="org.blockml.bml.bom.type"
+  xmlns:bomvalue="org.blockml.bml.bom.value"
+  xmlns:core="org.blockml.bml.core"
+  xmlns:def="org.blockml.bml.definition"
+  xmlns:type="org.blockml.bml.type">
+
+  <name>WithBinding</name>
+  <type>bomcomp:WithBinding</type>
+  <baseType>bom:UrmodellType</baseType>
+  <is>bml:with binding entry</is>
+
+  <documentation>bml:with binding entry</documentation>
+
+  <properties>
+    <name type="type:Text">
+      <documentation>name (required). TS type: type:Text.</documentation>
+    </name>
+    <value type="bomvalue:ExpressionValue">
+      <documentation>value (required). TS type: bomvalue:ExpressionValue.</documentation>
+    </value>
+  </properties>
+
+</block>

package/blocks/org/blockml/bml/bom/composition/WithDirective.bml

@@ -0,0 +1,43 @@
+<!--
+  BOM Urmodell — WithDirective
+  FQN: org.blockml.bml.bom.composition.WithDirective
+-->
+<block
+  xmlns="http://blockml.org/bml"
+  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+  xsi:schemaLocation="http://blockml.org/bml https://blockml.org/schemas/bml.xsd
+                      "
+  xmlns:blockml="org.blockml.bml"
+  xmlns:bom="org.blockml.bml.bom"
+  xmlns:bomapi="org.blockml.bml.bom.api"
+  xmlns:bomblock="org.blockml.bml.bom.block"
+  xmlns:bomcap="org.blockml.bml.bom.capability"
+  xmlns:bomcommon="org.blockml.bml.bom.common"
+  xmlns:bomcomp="org.blockml.bml.bom.composition"
+  xmlns:bomdoc="org.blockml.bml.bom.document"
+  xmlns:bomdocumentation="org.blockml.bml.bom.documentation"
+  xmlns:bommember="org.blockml.bml.bom.member"
+  xmlns:bomtype="org.blockml.bml.bom.type"
+  xmlns:bomvalue="org.blockml.bml.bom.value"
+  xmlns:core="org.blockml.bml.core"
+  xmlns:def="org.blockml.bml.definition"
+  xmlns:type="org.blockml.bml.type">
+
+  <name>WithDirective</name>
+  <type>bomcomp:WithDirective</type>
+  <baseType>bomcomp:DirectiveAttribute</baseType>
+  <is>bml:with directive (type: with)</is>
+
+  <documentation>bml:with directive (type: with)</documentation>
+
+  <properties>
+    <type type="type:Text">
+      <documentation>type (required). TS type: type:Text.</documentation>
+      <value>with</value>
+    </type>
+    <bindings type="bomcomp:WithBinding[]">
+      <documentation>bindings (required). TS type: bomcomp:WithBinding[].</documentation>
+    </bindings>
+  </properties>
+
+</block>

package/blocks/org/blockml/bml/bom/document/BomDocument.bml

@@ -0,0 +1,49 @@
+<!--
+  BOM Urmodell — BomDocument
+  FQN: org.blockml.bml.bom.document.BomDocument
+-->
+<block
+  xmlns="http://blockml.org/bml"
+  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+  xsi:schemaLocation="http://blockml.org/bml https://blockml.org/schemas/bml.xsd
+                      "
+  xmlns:blockml="org.blockml.bml"
+  xmlns:bom="org.blockml.bml.bom"
+  xmlns:bomapi="org.blockml.bml.bom.api"
+  xmlns:bomblock="org.blockml.bml.bom.block"
+  xmlns:bomcap="org.blockml.bml.bom.capability"
+  xmlns:bomcommon="org.blockml.bml.bom.common"
+  xmlns:bomcomp="org.blockml.bml.bom.composition"
+  xmlns:bomdoc="org.blockml.bml.bom.document"
+  xmlns:bomdocumentation="org.blockml.bml.bom.documentation"
+  xmlns:bommember="org.blockml.bml.bom.member"
+  xmlns:bomtype="org.blockml.bml.bom.type"
+  xmlns:bomvalue="org.blockml.bml.bom.value"
+  xmlns:core="org.blockml.bml.core"
+  xmlns:def="org.blockml.bml.definition"
+  xmlns:type="org.blockml.bml.type">
+
+  <name>BomDocument</name>
+  <type>bomdoc:BomDocument</type>
+  <baseType>bom:UrmodellType</baseType>
+  <is>Root Urmodell document — every parsed BML file</is>
+
+  <documentation>Immutable after parse or BomBuilder.seal(). kind is always "block" in V1.</documentation>
+
+  <examples>
+    <example title="Calibrator reference shape">Reference BomDocument from com.machineblocks.bml.calibration.Calibrator. Root BlockDefinition with declared members, subBlocks (Utils, Base, StudDiameter, …), and compositions from _utils/_parts aggregations. Inherited native properties are NOT in members[].</example>
+  </examples>
+
+  <properties>
+    <kind type="type:Text">
+      <documentation>V1: always "block". (required)</documentation>
+    </kind>
+    <source type="bomcommon:SourceInfo">
+      <documentation>source (required). TS type: bomcommon:SourceInfo.</documentation>
+    </source>
+    <block type="bomblock:BlockDefinition">
+      <documentation>block (required). TS type: bomblock:BlockDefinition.</documentation>
+    </block>
+  </properties>
+
+</block>

package/blocks/org/blockml/bml/bom/documentation/AbstractionPrinciple.bml

@@ -0,0 +1,46 @@
+<!--
+  BOM Documentation — AbstractionPrinciple
+  FQN: org.blockml.bml.bom.documentation.AbstractionPrinciple
+-->
+<block
+  xmlns="http://blockml.org/bml"
+  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+  xsi:schemaLocation="http://blockml.org/bml https://blockml.org/schemas/bml.xsd
+                      "
+  xmlns:blockml="org.blockml.bml"
+  xmlns:bom="org.blockml.bml.bom"
+  xmlns:bomapi="org.blockml.bml.bom.api"
+  xmlns:bomblock="org.blockml.bml.bom.block"
+  xmlns:bomcap="org.blockml.bml.bom.capability"
+  xmlns:bomcommon="org.blockml.bml.bom.common"
+  xmlns:bomcomp="org.blockml.bml.bom.composition"
+  xmlns:bomdoc="org.blockml.bml.bom.document"
+  xmlns:bomdocumentation="org.blockml.bml.bom.documentation"
+  xmlns:bommember="org.blockml.bml.bom.member"
+  xmlns:bomtype="org.blockml.bml.bom.type"
+  xmlns:bomvalue="org.blockml.bml.bom.value"
+  xmlns:core="org.blockml.bml.core"
+  xmlns:def="org.blockml.bml.definition"
+  xmlns:type="org.blockml.bml.type"
+  xmlns:doc="org.blockml.bml.documentation">
+
+  <name>AbstractionPrinciple</name>
+  <type>bomdocumentation:AbstractionPrinciple</type>
+  <baseType>core:Documentation</baseType>
+  <is>Lossless representation and roundtrip guarantee</is>
+
+  <documentation>A BOM document is a lossless representation of BML source. It preserves authored
+    structure and values — directives, aggregation declarations, literal syntax, unresolved
+    type references, namespace bindings, and bml:xml metadata. BOM makes no statement about
+    directive expansion, aggregation interpretation, or block rendering.
+
+    Maximum authored surface: render targets and the serializer must read as much of the
+    original document as the Urmodell can carry. Prefer first-class fields over hidden side channels.
+
+    BML → BOM → BML must always be possible.</documentation>
+
+  <references>
+    <see type="bomdocumentation:AuthoredSurfaceTable" relation="ReadNext"></see>
+  </references>
+
+</block>

package/blocks/org/blockml/bml/bom/documentation/ArchitectureOverview.bml

@@ -0,0 +1,49 @@
+<!--
+  BOM Documentation — ArchitectureOverview
+  FQN: org.blockml.bml.bom.documentation.ArchitectureOverview
+-->
+<block
+  xmlns="http://blockml.org/bml"
+  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+  xsi:schemaLocation="http://blockml.org/bml https://blockml.org/schemas/bml.xsd
+                      "
+  xmlns:blockml="org.blockml.bml"
+  xmlns:bom="org.blockml.bml.bom"
+  xmlns:bomapi="org.blockml.bml.bom.api"
+  xmlns:bomblock="org.blockml.bml.bom.block"
+  xmlns:bomcap="org.blockml.bml.bom.capability"
+  xmlns:bomcommon="org.blockml.bml.bom.common"
+  xmlns:bomcomp="org.blockml.bml.bom.composition"
+  xmlns:bomdoc="org.blockml.bml.bom.document"
+  xmlns:bomdocumentation="org.blockml.bml.bom.documentation"
+  xmlns:bommember="org.blockml.bml.bom.member"
+  xmlns:bomtype="org.blockml.bml.bom.type"
+  xmlns:bomvalue="org.blockml.bml.bom.value"
+  xmlns:core="org.blockml.bml.core"
+  xmlns:def="org.blockml.bml.definition"
+  xmlns:type="org.blockml.bml.type"
+  xmlns:doc="org.blockml.bml.documentation">
+
+  <name>ArchitectureOverview</name>
+  <type>bomdocumentation:ArchitectureOverview</type>
+  <baseType>core:Documentation</baseType>
+  <is>BML source to render pipeline</is>
+
+  <documentation>Pipeline roles:
+
+    BML source → universal authoring and interchange format
+    Urmodell (BOM) → canonical, immutable, lossless parse/build result (SSOT, read-only)
+    BomBuilder (V3) → planned writable session; seal() → Urmodell (same types)
+    Pragmatic Model → validator default fork + optional renderer forks (resolve only)
+    Framework Utilities → derived views / merges on forks — never mutate Urmodell
+    Render Target → chooses Urmodell / pragmatic / own forks + optional target working model
+
+    Block in BML is the mandatory input concept — not a uniform runtime object model.
+    The parser must read block documents; validators walk baseType chains. Internal
+    representation after parse is implementation freedom.</documentation>
+
+  <references>
+    <see type="bomdocumentation:AbstractionPrinciple" relation="ReadNext"></see>
+  </references>
+
+</block>

package/blocks/org/blockml/bml/bom/documentation/AuthoredSurfaceTable.bml

@@ -0,0 +1,47 @@
+<!--
+  BOM Documentation — AuthoredSurfaceTable
+  FQN: org.blockml.bml.bom.documentation.AuthoredSurfaceTable
+-->
+<block
+  xmlns="http://blockml.org/bml"
+  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+  xsi:schemaLocation="http://blockml.org/bml https://blockml.org/schemas/bml.xsd
+                      "
+  xmlns:blockml="org.blockml.bml"
+  xmlns:bom="org.blockml.bml.bom"
+  xmlns:bomapi="org.blockml.bml.bom.api"
+  xmlns:bomblock="org.blockml.bml.bom.block"
+  xmlns:bomcap="org.blockml.bml.bom.capability"
+  xmlns:bomcommon="org.blockml.bml.bom.common"
+  xmlns:bomcomp="org.blockml.bml.bom.composition"
+  xmlns:bomdoc="org.blockml.bml.bom.document"
+  xmlns:bomdocumentation="org.blockml.bml.bom.documentation"
+  xmlns:bommember="org.blockml.bml.bom.member"
+  xmlns:bomtype="org.blockml.bml.bom.type"
+  xmlns:bomvalue="org.blockml.bml.bom.value"
+  xmlns:core="org.blockml.bml.core"
+  xmlns:def="org.blockml.bml.definition"
+  xmlns:type="org.blockml.bml.type"
+  xmlns:doc="org.blockml.bml.documentation">
+
+  <name>AuthoredSurfaceTable</name>
+  <type>bomdocumentation:AuthoredSurfaceTable</type>
+  <baseType>core:Documentation</baseType>
+  <is>What BOM stores vs what downstream interprets</is>
+
+  <documentation>bml:each / bml:if / bml:with → directives[] unexpanded → Renderer expands
+    xmlns / xmlns:prefix → SourceInfo.namespaceBindings 1:1 authored → Serializer QName emit (B21)
+    xsi:schemaLocation / xsi:noNamespaceSchemaLocation → SourceInfo (B25) → re-emit on root
+    bml:xml → xmlRendering block+member — NOT directives[] → Serializer, FatBlock, XSD
+    element|attribute dual placement → authoredPlacement (D9) → MUST roundtrip authored form
+    Text vs CDATA → authoredCharacterDataForm (D8) → emit CDATA when needed or authored
+    Literal syntax [5,5,6] vs {x:5,…} → LiteralValue authored form → Renderer serializes
+    ${ expr } → ExpressionValue { raw } — AST via parseExpression(), not evaluated
+    aggregations declaration → AggregationDefinition declared only → TypeRegistry metadata
+    composition children → CompositionNode tree → Renderer assembly patterns
+    baseType FQN → string reference → TypeRegistry effective members
+    Preset reference FQN::id → unmerged string → Renderer preset merge
+    Capabilities → CapabilityDefinition in BOM → Renderer interprets (not invoked at parse)
+    XML comments → XmlTrivia on following element (B11) → Serializer re-emits</documentation>
+
+</block>

package/blocks/org/blockml/bml/bom/documentation/CalibratorExample.bml

@@ -0,0 +1,53 @@
+<!--
+  BOM Documentation — CalibratorExample
+  FQN: org.blockml.bml.bom.documentation.CalibratorExample
+-->
+<block
+  xmlns="http://blockml.org/bml"
+  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+  xsi:schemaLocation="http://blockml.org/bml https://blockml.org/schemas/bml.xsd
+                      "
+  xmlns:blockml="org.blockml.bml"
+  xmlns:bom="org.blockml.bml.bom"
+  xmlns:bomapi="org.blockml.bml.bom.api"
+  xmlns:bomblock="org.blockml.bml.bom.block"
+  xmlns:bomcap="org.blockml.bml.bom.capability"
+  xmlns:bomcommon="org.blockml.bml.bom.common"
+  xmlns:bomcomp="org.blockml.bml.bom.composition"
+  xmlns:bomdoc="org.blockml.bml.bom.document"
+  xmlns:bomdocumentation="org.blockml.bml.bom.documentation"
+  xmlns:bommember="org.blockml.bml.bom.member"
+  xmlns:bomtype="org.blockml.bml.bom.type"
+  xmlns:bomvalue="org.blockml.bml.bom.value"
+  xmlns:core="org.blockml.bml.core"
+  xmlns:def="org.blockml.bml.definition"
+  xmlns:type="org.blockml.bml.type"
+  xmlns:doc="org.blockml.bml.documentation">
+
+  <name>CalibratorExample</name>
+  <type>bomdocumentation:CalibratorExample</type>
+  <baseType>core:Documentation</baseType>
+  <is>Reference BomDocument walkthrough</is>
+
+  <documentation>Source: com.machineblocks.bml.calibration.Calibrator.bml
+
+    BomDocument kind block → BlockDefinition Calibrator
+    type com.machineblocks.bml.calibration.Calibrator, baseType CompositeBlock, version 1.0.0
+
+    Declared members only (not inherited size, offset, baseColor):
+    numberOfSamples, font, size (ExpressionValue), _utils aggregation (Utils bean context),
+    _parts aggregation (4 calibration rows).
+
+    subBlocks: Utils, Base, StudDiameter, BaseWallThickness, TubeDiameter, PinDiameter.
+
+    compositions: _utils → Utils instance; _parts → Base, StudDiameter, Base (id=base_wall), …
+
+    Observations: Sub-Block refs by short name resolved via subBlocks[] tree.
+    @utils.formatValue and #math.* stored as ExpressionValue { raw }.
+    Inherited native properties not in members[] — validator uses resolveEffectiveMembers().</documentation>
+
+  <references>
+    <see type="bomdoc:BomDocument" relation="ExampleOf"></see>
+  </references>
+
+</block>

package/blocks/org/blockml/bml/bom/documentation/CompositionDirectives.bml

@@ -0,0 +1,45 @@
+<!--
+  BOM Documentation — CompositionDirectives
+  FQN: org.blockml.bml.bom.documentation.CompositionDirectives
+-->
+<block
+  xmlns="http://blockml.org/bml"
+  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+  xsi:schemaLocation="http://blockml.org/bml https://blockml.org/schemas/bml.xsd
+                      "
+  xmlns:blockml="org.blockml.bml"
+  xmlns:bom="org.blockml.bml.bom"
+  xmlns:bomapi="org.blockml.bml.bom.api"
+  xmlns:bomblock="org.blockml.bml.bom.block"
+  xmlns:bomcap="org.blockml.bml.bom.capability"
+  xmlns:bomcommon="org.blockml.bml.bom.common"
+  xmlns:bomcomp="org.blockml.bml.bom.composition"
+  xmlns:bomdoc="org.blockml.bml.bom.document"
+  xmlns:bomdocumentation="org.blockml.bml.bom.documentation"
+  xmlns:bommember="org.blockml.bml.bom.member"
+  xmlns:bomtype="org.blockml.bml.bom.type"
+  xmlns:bomvalue="org.blockml.bml.bom.value"
+  xmlns:core="org.blockml.bml.core"
+  xmlns:def="org.blockml.bml.definition"
+  xmlns:type="org.blockml.bml.type"
+  xmlns:doc="org.blockml.bml.documentation">
+
+  <name>CompositionDirectives</name>
+  <type>bomdocumentation:CompositionDirectives</type>
+  <baseType>core:Documentation</baseType>
+  <is>Directive placement and Thymeleaf model</is>
+
+  <documentation>Directives follow Thymeleaf model — attributes on modified element, stored unexpanded.
+
+    bml:id, bml:version, bml:bean, bml:scope → BlockInstance fields (NOT directives[]).
+    bml:with → composition, aggregation, bml:container, block instances.
+    bml:each, bml:if, bml:unless → bml:container, block instances.
+
+    Dynamic ids: bml:id="${ 'val_' + i }" stored as ExpressionValue or literal on BlockInstance.id.
+    Omitted bml:id stored absent — parser does not assign auto-IDs.</documentation>
+
+  <references>
+    <see type="bomcomp:DirectiveAttribute" relation="Defines"></see>
+  </references>
+
+</block>