docs: add runnable examples and SourceFile embedding for Allows reference

.claude/skills/docs-data-type-ref/SKILL.md

@@ -243,6 +243,56 @@ Rules for this section:
 - The bolded description must be a short plain-English description of what that specific `App` demonstrates — not the object name rephrased.
 - Keep the two numbered steps (clone, run individually) in that order; do not add or remove steps.
 - If no example `App` objects were written (rare), omit this section entirely.
+- When the full example source is also **embedded earlier in the document** via `SourceFile.print`,
+  the `([source](...))` link in this section serves as a convenient shortcut to the GitHub file;
+  there is no need to embed the source again here.
+
+### Embedding Example Files with `SourceFile`
+
+When the documentation needs to show a **full example file** from the `schema-examples` project
+(written in Step 3), **do not copy-paste the code inline**. Instead, use `mdoc:passthrough` with
+the `SourceFile.print` helper to include it by reference. This keeps the doc and the example in
+sync — any change to the example file automatically appears in the rendered docs on the next
+mdoc build.
+
+Use this pattern:
+
+````markdown
+```scala mdoc:passthrough
+import docs.SourceFile
+
+SourceFile.print("schema-examples/src/main/scala/<package>/<ExampleFile>.scala")
+```
+````
+
+**Important:** Import as `import docs.SourceFile` and call `SourceFile.print(...)` — do NOT use
+`import docs.SourceFile._` with bare `print(...)` because `print` conflicts with `Predef.print`
+inside mdoc sessions.
+
+`SourceFile.print(path)` reads the file at mdoc compile time and emits a fenced code block with
+the file path shown as the title. The path is relative to the repository root (the helper tries
+`../<path>` first, then `<path>`).
+
+**When to use `SourceFile.print`:**
+- Showing a complete, runnable `App` example from `schema-examples/`
+- Showing a large, self-contained example that would be unwieldy to maintain in two places
+
+**When NOT to use it — use regular mdoc blocks instead:**
+- Short inline snippets (< 20 lines) that illustrate a single method or concept
+- Code that needs `mdoc` evaluated output (e.g., `// res0: Int = 42`)
+- Code that is documentation-specific and doesn't exist as a standalone file
+
+**Optional parameters:**
+- `lines = Seq((from, to))` — include only specific line ranges (1-indexed):
+  ````markdown
+  ```scala mdoc:passthrough
+  import docs.SourceFile
+
+  SourceFile.print("schema-examples/src/main/scala/into/IntoNumericExample.scala", lines = Seq((10, 25)))
+  ```
+  ````
+- `showLineNumbers = true` — render with line numbers in the output
+- `comment = false` — suppress the file path title
 
 ### Compile-Checked Code Blocks with mdoc
 

docs/reference/allows.md

@@ -350,3 +350,86 @@ val ev: Allows[EmptyEvent.type, Record[Primitive]] = implicitly  // vacuously tr
 | Derivation keyword | `Schema.derived` implicit | `Schema.derived` or `derives Schema` |
 
 Both Scala versions produce the same macro behavior and the same error messages.
+
+## Running the Examples
+
+All code from this guide is available as runnable examples in the `schema-examples` module.
+
+**1. Clone the repository and navigate to the project:**
+
+```bash
+git clone https://github.com/zio/zio-blocks.git
+cd zio-blocks
+```
+
+**2. Run individual examples with sbt:**
+
+**CSV serializer with flat record compile-time constraints**
+([source](https://github.com/zio/zio-blocks/blob/main/schema-examples/src/main/scala/comptime/AllowsCsvExample.scala))
+
+```bash
+sbt "schema-examples/runMain comptime.AllowsCsvExample"
+```
+
+```scala mdoc:passthrough
+import docs.SourceFile
+
+SourceFile.print("schema-examples/src/main/scala/comptime/AllowsCsvExample.scala")
+```
+
+**Event bus with sealed trait auto-unwrap and nested hierarchies**
+([source](https://github.com/zio/zio-blocks/blob/main/schema-examples/src/main/scala/comptime/AllowsEventBusExample.scala))
+
+```bash
+sbt "schema-examples/runMain comptime.AllowsEventBusExample"
+```
+
+```scala mdoc:passthrough
+import docs.SourceFile
+
+SourceFile.print("schema-examples/src/main/scala/comptime/AllowsEventBusExample.scala")
+```
+
+**GraphQL / tree structures using Self for recursive grammars**
+([source](https://github.com/zio/zio-blocks/blob/main/schema-examples/src/main/scala/comptime/AllowsGraphQLTreeExample.scala))
+
+```bash
+sbt "schema-examples/runMain comptime.AllowsGraphQLTreeExample"
+```
+
+```scala mdoc:passthrough
+import docs.SourceFile
+
+SourceFile.print("schema-examples/src/main/scala/comptime/AllowsGraphQLTreeExample.scala")
+```
+
+**Sealed trait auto-unwrap with nested hierarchies and case objects**
+([source](https://github.com/zio/zio-blocks/blob/main/schema-examples/src/main/scala/comptime/AllowsSealedTraitExample.scala))
+
+```bash
+sbt "schema-examples/runMain comptime.AllowsSealedTraitExample"
+```
+
+```scala mdoc:passthrough
+import docs.SourceFile
+
+SourceFile.print("schema-examples/src/main/scala/comptime/AllowsSealedTraitExample.scala")
+```
+
+**RDBMS library with CREATE TABLE and INSERT using flat record constraints**
+([source](https://github.com/zio/zio-blocks/blob/main/schema-examples/src/main/scala/comptime/RdbmsExample.scala))
+
+```scala mdoc:passthrough
+import docs.SourceFile
+
+SourceFile.print("schema-examples/src/main/scala/comptime/RdbmsExample.scala")
+```
+
+**JSON document store with specific primitives and recursive Self grammar**
+([source](https://github.com/zio/zio-blocks/blob/main/schema-examples/src/main/scala/comptime/DocumentStoreExample.scala))
+
+```scala mdoc:passthrough
+import docs.SourceFile
+
+SourceFile.print("schema-examples/src/main/scala/comptime/DocumentStoreExample.scala")
+```

schema-examples/src/main/scala/comptime/AllowsCsvExample.scala

@@ -0,0 +1,98 @@
+package comptime
+
+import zio.blocks.schema._
+import zio.blocks.schema.comptime.Allows
+import Allows.{Primitive, Record, `|`}
+import Allows.{Optional => AOptional}
+import util.ShowExpr.show
+
+// ---------------------------------------------------------------------------
+// CSV serializer example using Allows[A, S] compile-time shape constraints
+//
+// A CSV row is a flat record: every field must be a primitive scalar or an
+// optional primitive (for nullable columns). Nested records, sequences, and
+// maps are all rejected at compile time.
+// ---------------------------------------------------------------------------
+
+// Compatible: flat record of primitives and optional primitives
+case class Employee(name: String, department: String, salary: BigDecimal, active: Boolean)
+object Employee { implicit val schema: Schema[Employee] = Schema.derived }
+
+case class SensorReading(sensorId: String, timestamp: Long, value: Double, unit: Option[String])
+object SensorReading { implicit val schema: Schema[SensorReading] = Schema.derived }
+
+object CsvSerializer {
+
+  type FlatRow = Primitive | AOptional[Primitive]
+
+  /** Serialize a sequence of flat records to CSV format. */
+  def toCsv[A](rows: Seq[A])(implicit schema: Schema[A], ev: Allows[A, Record[FlatRow]]): String = {
+    val reflect = schema.reflect.asRecord.get
+    val header  = reflect.fields.map(_.name).mkString(",")
+    val lines = rows.map { row =>
+      val dv = schema.toDynamicValue(row)
+      dv match {
+        case DynamicValue.Record(fields) =>
+          fields.map { case (_, v) => csvEscape(dvToString(v)) }.mkString(",")
+        case _ => ""
+      }
+    }
+    (header +: lines).mkString("\n")
+  }
+
+  private def dvToString(dv: DynamicValue): String = dv match {
+    case DynamicValue.Primitive(PrimitiveValue.String(s))     => s
+    case DynamicValue.Primitive(PrimitiveValue.Boolean(b))    => b.toString
+    case DynamicValue.Primitive(PrimitiveValue.Int(n))        => n.toString
+    case DynamicValue.Primitive(PrimitiveValue.Long(n))       => n.toString
+    case DynamicValue.Primitive(PrimitiveValue.Double(n))     => n.toString
+    case DynamicValue.Primitive(PrimitiveValue.Float(n))      => n.toString
+    case DynamicValue.Primitive(PrimitiveValue.BigDecimal(n)) => n.toString
+    case DynamicValue.Primitive(v)                            => v.toString
+    case DynamicValue.Null                                    => ""
+    case DynamicValue.Variant(tag, inner) if tag == "Some"    => dvToString(inner)
+    case DynamicValue.Variant(tag, _) if tag == "None"        => ""
+    case DynamicValue.Record(fields) =>
+      fields.headOption.map { case (_, v) => dvToString(v) }.getOrElse("")
+    case other => other.toString
+  }
+
+  private def csvEscape(s: String): String =
+    if (s.contains(",") || s.contains("\"") || s.contains("\n"))
+      "\"" + s.replace("\"", "\"\"") + "\""
+    else s
+}
+
+// ---------------------------------------------------------------------------
+// Demonstration
+// ---------------------------------------------------------------------------
+
+object AllowsCsvExample extends App {
+
+  // Flat records of primitives — compiles fine
+  val employees = Seq(
+    Employee("Alice", "Engineering", BigDecimal("120000.00"), true),
+    Employee("Bob", "Marketing", BigDecimal("95000.50"), true),
+    Employee("Carol", "Engineering", BigDecimal("115000.00"), false)
+  )
+
+  // CSV output for a flat record of primitives
+  show(CsvSerializer.toCsv(employees))
+
+  // Flat record with optional fields — also compiles
+  val readings = Seq(
+    SensorReading("temp-01", 1709712000L, 23.5, Some("celsius")),
+    SensorReading("temp-02", 1709712060L, 72.1, None)
+  )
+
+  // Optional fields become empty CSV cells when None
+  show(CsvSerializer.toCsv(readings))
+
+  // The following would NOT compile — uncomment to see the error:
+  //
+  // case class Nested(name: String, address: Address)
+  // object Nested { implicit val schema: Schema[Nested] = Schema.derived }
+  // CsvSerializer.toCsv(Seq(Nested("Alice", Address("1 Main St", "NY", "10001"))))
+  //   [error] Schema shape violation at Nested.address: found Record(Address),
+  //           required Primitive | Optional[Primitive]
+}

schema-examples/src/main/scala/comptime/AllowsEventBusExample.scala

@@ -0,0 +1,92 @@
+package comptime
+
+import zio.blocks.schema._
+import zio.blocks.schema.comptime.Allows
+import Allows.{Primitive, Record, Sequence, `|`}
+import Allows.{Optional => AOptional}
+import util.ShowExpr.show
+
+// ---------------------------------------------------------------------------
+// Event bus / message broker example using Allows[A, S]
+//
+// Published events are typically sealed traits of flat record cases. Sealed
+// traits are automatically unwrapped by the Allows macro — each case is
+// checked individually against the grammar. No Variant node is needed.
+//
+// This example also shows nested sealed traits (auto-unwrap is recursive).
+// ---------------------------------------------------------------------------
+
+// Domain events — a sealed trait hierarchy
+sealed trait AccountEvent
+case class AccountOpened(accountId: String, owner: String, initialBalance: BigDecimal) extends AccountEvent
+case class FundsDeposited(accountId: String, amount: BigDecimal)                       extends AccountEvent
+case class FundsWithdrawn(accountId: String, amount: BigDecimal)                       extends AccountEvent
+case class AccountClosed(accountId: String, reason: Option[String])                    extends AccountEvent
+object AccountEvent { implicit val schema: Schema[AccountEvent] = Schema.derived }
+
+// Nested sealed trait — InventoryEvent has a sub-hierarchy
+sealed trait InventoryEvent
+case class ItemAdded(sku: String, quantity: Int)    extends InventoryEvent
+case class ItemRemoved(sku: String, quantity: Int)  extends InventoryEvent
+
+sealed trait InventoryAlert extends InventoryEvent
+case class LowStock(sku: String, remaining: Int)    extends InventoryAlert
+case class OutOfStock(sku: String)                   extends InventoryAlert
+
+object InventoryEvent { implicit val schema: Schema[InventoryEvent] = Schema.derived }
+
+// Event with sequence fields (e.g. tags or batch items)
+sealed trait BatchEvent
+case class BatchImport(batchId: String, itemIds: List[String]) extends BatchEvent
+case class BatchComplete(batchId: String, count: Int)          extends BatchEvent
+object BatchEvent { implicit val schema: Schema[BatchEvent] = Schema.derived }
+
+object EventBus {
+
+  type EventShape = Primitive | AOptional[Primitive]
+
+  /** Publish a domain event. All cases of the sealed trait must be flat records. */
+  def publish[A](event: A)(implicit schema: Schema[A], ev: Allows[A, Record[EventShape]]): String = {
+    val dv = schema.toDynamicValue(event)
+    val (typeName, payload) = dv match {
+      case DynamicValue.Variant(name, inner) => (name, inner.toJson.toString)
+      case _                                 => (schema.reflect.typeId.name, dv.toJson.toString)
+    }
+    s"PUBLISH topic=${schema.reflect.typeId.name} type=$typeName payload=$payload"
+  }
+
+  /** Publish events that may contain sequence fields (e.g. batch operations). */
+  def publishBatch[A](event: A)(implicit
+    schema: Schema[A],
+    ev: Allows[A, Record[Primitive | Sequence[Primitive]]]
+  ): String = {
+    val dv = schema.toDynamicValue(event)
+    val (typeName, payload) = dv match {
+      case DynamicValue.Variant(name, inner) => (name, inner.toJson.toString)
+      case _                                 => (schema.reflect.typeId.name, dv.toJson.toString)
+    }
+    s"PUBLISH topic=${schema.reflect.typeId.name} type=$typeName payload=$payload"
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Demonstration
+// ---------------------------------------------------------------------------
+
+object AllowsEventBusExample extends App {
+
+  // Flat sealed trait — all cases are records of primitives/optionals
+  show(EventBus.publish[AccountEvent](AccountOpened("acc-001", "Alice", BigDecimal("1000.00"))))
+  show(EventBus.publish[AccountEvent](FundsDeposited("acc-001", BigDecimal("500.00"))))
+  show(EventBus.publish[AccountEvent](AccountClosed("acc-001", Some("customer request"))))
+
+  // Nested sealed trait — auto-unwrap is recursive
+  // InventoryAlert extends InventoryEvent, both are unwrapped
+  show(EventBus.publish[InventoryEvent](ItemAdded("SKU-100", 50)))
+  show(EventBus.publish[InventoryEvent](LowStock("SKU-100", 3)))
+  show(EventBus.publish[InventoryEvent](OutOfStock("SKU-100")))
+
+  // Events with sequence fields use a wider grammar
+  show(EventBus.publishBatch[BatchEvent](BatchImport("batch-42", List("item-1", "item-2", "item-3"))))
+  show(EventBus.publishBatch[BatchEvent](BatchComplete("batch-42", 3)))
+}