docs: add runnable examples and SourceFile embedding for Allows reference

[khajavi]

Summary

• Add 4 new runnable App examples in schema-examples/ covering Allows doc scenarios that lacked examples: CSV flat records, event bus with sealed trait auto-unwrap, GraphQL/tree structures with Self recursion, and sealed trait auto-unwrap with nested hierarchies
• Add SourceFile utility (package docs) for embedding example source files in documentation via mdoc:passthrough
• Update allows.md with "Running the Examples" section that embeds all 6 example files using SourceFile.print
• Update docs-data-type-ref skill with SourceFile.print convention and correct import pattern

Test plan

• sbt "schema-examples/compile" passes
• All 4 new examples run successfully via sbt "schema-examples/runMain ..."
• sbt "docs/mdoc" compiles with 0 errors

🤖 Generated with Claude Code

[Copilot]

Pull request overview

Adds documentation support for embedding full runnable example sources in the Allows reference, and introduces several new schema-examples Apps to cover previously undocumented scenarios.

Changes:

• Added docs.SourceFile helper to embed source files into docs via mdoc:passthrough.
• Added 4 new runnable schema-examples Apps demonstrating Allows scenarios (CSV, event bus, GraphQL/tree recursion, sealed trait auto-unwrap).
• Updated docs/reference/allows.md to embed all example sources, and updated the docs skill guide to codify the SourceFile.print convention.

Reviewed changes

Copilot reviewed 7 out of 7 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
zio-blocks-docs/src/main/scala/SourceFile.scala	New helper for reading/printing source files into mdoc output.
schema-examples/src/main/scala/comptime/AllowsSealedTraitExample.scala	Runnable example for sealed trait auto-unwrap behavior.
schema-examples/src/main/scala/comptime/AllowsGraphQLTreeExample.scala	Runnable example showing Self for recursive/tree-like grammars.
schema-examples/src/main/scala/comptime/AllowsEventBusExample.scala	Runnable example for event bus publishing constraints over sealed traits.
schema-examples/src/main/scala/comptime/AllowsCsvExample.scala	Runnable example for CSV flat-record constraints.
docs/reference/allows.md	Adds “Running the Examples” section and embeds example sources via SourceFile.print.
.claude/skills/docs-data-type-ref/SKILL.md	Documents the SourceFile.print embedding pattern and import convention.

[Copilot]

Pull request overview

Copilot reviewed 13 out of 14 changed files in this pull request and generated 4 comments.

[Copilot]

fileExtension uses .split('.'), but String.split takes a regex where . matches any character. This will typically produce an empty/incorrect extension (so embedded fences won’t get the expected language like scala). Use a literal-dot split (e.g., split("\\.")) or lastIndexOf('.')/substring to extract the extension safely.

Suggested change

	val javaPath = java.nio.file.Paths.get(path)
	val fileExtension =
	javaPath.getFileName.toString
	.split('.')
	.lastOption
	.getOrElse("")
	val javaPath = java.nio.file.Paths.get(path)
	val fileName = javaPath.getFileName.toString
	val lastDotIndex = fileName.lastIndexOf('.')
	val fileExtension =
	if (lastDotIndex >= 0 && lastDotIndex < fileName.length - 1)
	fileName.substring(lastDotIndex + 1)
	else
	""

[Copilot]

SourceFile is a new public utility in src/main/scala, but it currently has no Scaladoc. Please add Scaladoc for the object and its public methods (read, fileExtension, print), documenting parameters (especially the lines ranges being 1-indexed/inclusive) and expected output format, since this is intended for reuse from mdoc sessions.

[Copilot]

In the grammar table, the union node is shown as `\|` and described with A \| B. \| isn’t valid Scala syntax; the Allows union is written as A | B (Scala 3 native unions; Scala 2 infix type | from Allows). Please adjust this row to display | / A | B (escape the pipe for the Markdown table without changing the visible syntax).

Suggested change

	| `` `\|` `` | Union of two grammar nodes: `A \| B`. In Scala 2 write `` A `\|` B `` in infix position. |
	| \| | Union of two grammar nodes: `A | B`. In Scala 2 write `A | B` in infix position. |

[Copilot]

The empty table rows (| | |) inside the Grammar Nodes table render as blank entries and look accidental. If you want visual grouping, consider removing these rows and using prose/heading breaks outside the table instead.