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
+- `showTitle = false` — suppress the file path title
 
 ### Compile-Checked Code Blocks with mdoc
 
@@ -335,15 +385,39 @@ object IntoSchemaEvolutionExample extends App {
 }
 ```
 
-## Step 4: Integrate
+## Step 4: Lint Check (Mandatory Before Integration)
+
+After creating all example files, stage them in git first, then ensure all Scala files pass the CI formatting gate:
+
+```bash
+git add schema-examples/src/main/scala/**/*.scala
+sbt fmtChanged
+```
+
+If any files were reformatted, commit the changes immediately:
+
+```bash
+git add -A
+git commit -m "docs(<type>): apply scalafmt to examples"
+```
+
+Verify the CI lint gate locally:
+
+```bash
+sbt check
+```
+
+**Success criterion:** zero formatting violations reported.
+
+## Step 5: Integrate
 
 See the **`docs-integrate`** skill for the complete integration checklist (sidebars.js, index.md,
 cross-references, link verification).
 
 Additional note for reference pages: if creating a new file, place it in the appropriate
 `docs/reference/` subdirectory based on where it logically belongs.
 
-## Step 5: Review and Verify Compilation
+## Step 6: Review and Verify Compilation
 
 After writing, re-read the document and verify:
 - All method signatures match the actual source code

.claude/skills/docs-document-pr/SKILL.md

@@ -272,6 +272,34 @@ Once documentation is written, tell the user:
 
 ---
 
+## Phase 6: Verify Lint (If Examples Created)
+
+If documentation involved creating or modifying `.scala` example files in `schema-examples/`, stage them in git first, then verify that all Scala code passes the CI formatting gate before reporting completion:
+
+```bash
+git add schema-examples/src/main/scala/**/*.scala
+sbt fmtChanged
+```
+
+If any files were reformatted, commit the changes:
+
+```bash
+git add -A
+git commit -m "docs(<topic>): apply scalafmt to examples"
+```
+
+Then verify the CI lint gate locally:
+
+```bash
+sbt check
+```
+
+**Success criterion:** zero formatting violations reported.
+
+**If no `.scala` files were created or modified**, skip this phase.
+
+---
+
 ## Implementation Checklist
 
 When you invoke this skill:
@@ -285,6 +313,7 @@ When you invoke this skill:
 - [ ] **Phase 3c:** If subsection → manually edit existing page, consult `docs-writing-style` and `docs-mdoc-conventions` skills
 - [ ] **Phase 4:** If new page → invoke `docs-integrate` skill to update sidebar
 - [ ] **Phase 5:** Report findings and file paths to user
+- [ ] **Phase 6:** If `.scala` examples were created, run `sbt fmt` and `sbt check` to verify lint compliance
 
 ---
 

.claude/skills/docs-how-to-guide/SKILL.md

@@ -420,6 +420,30 @@ sbt "schema-examples/compile"
 
 If any example fails to compile, fix it before proceeding. The examples must compile successfully.
 
+### 4f. Lint Check (Mandatory Before Integration)
+
+After all examples compile, stage them in git first, then run Scalafmt to ensure all Scala files pass the CI formatting gate:
+
+```bash
+git add schema-examples/src/main/scala/**/*.scala
+sbt fmtChanged
+```
+
+If any files were reformatted, commit the changes immediately:
+
+```bash
+git add -A
+git commit -m "docs(<guide-id>): apply scalafmt to examples"
+```
+
+Verify the CI lint gate locally:
+
+```bash
+sbt check
+```
+
+**Success criterion:** zero formatting violations reported.
+
 ---
 
 ## Step 5: Integrate

.claude/skills/docs-mdoc-conventions/SKILL.md

@@ -106,6 +106,59 @@ modifiers are used more than in reference pages:
 
 ---
 
+## Tabbed Scala 2 / Scala 3 Examples
+
+When a section shows syntax that differs between Scala 2 and Scala 3, use Docusaurus tabs
+instead of sequential prose blocks. This lets readers pick their version once and have all
+tab groups on the page sync together.
+
+### Required MDX imports
+
+Add these two lines at the top of any `.md` file that uses tabs (right after the closing
+`---` of the frontmatter, before any prose):
+
+```mdx
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+```
+
+### Tab structure
+
+````mdx
+<Tabs groupId="scala-version" defaultValue="scala2">
+  <TabItem value="scala2" label="Scala 2">
+
+```scala mdoc:compile-only
+// Scala 2 syntax here
+```
+
+  </TabItem>
+  <TabItem value="scala3" label="Scala 3">
+
+```scala mdoc:compile-only
+// Scala 3 syntax here
+```
+
+  </TabItem>
+</Tabs>
+````
+
+### Rules
+
+- Always use `groupId="scala-version"` — this syncs all tab groups on the page when the
+  reader picks a version.
+- Always use `defaultValue="scala2"` — Scala 2 is shown first by default.
+- Blank lines inside `<TabItem>` are required for mdoc to process fenced code blocks
+  correctly.
+- `mdoc:compile-only` is the correct modifier for code inside tabs (same as everywhere
+  else).
+- mdoc passes JSX components through unchanged — only fenced `scala mdoc:*` blocks are
+  rewritten.
+- Do **not** use tabs for examples that are identical in both versions — only use them
+  when the syntax genuinely differs.
+
+---
+
 ## Docusaurus Admonitions
 
 Use Docusaurus admonition syntax for callouts:

.claude/skills/docs-writing-style/SKILL.md

@@ -82,7 +82,12 @@ Apply these conventions consistently in all prose, section headings, and inline
 
 ## Scala Version
 
-All code in documentation and companion example files **must use Scala 2.13.x syntax**. When in
-doubt, check the companion example files — they are the source of truth for syntax style.
+All code in documentation and companion example files **defaults to Scala 2.13.x syntax**.
+When in doubt, check the companion example files — they are the source of truth for syntax style.
+
+When a section shows syntax that genuinely differs between Scala 2 and Scala 3 (e.g., `using`
+vs `implicit`, native union types vs backtick infix), use tabbed code blocks instead of
+sequential prose. See `docs-mdoc-conventions` for the exact tab structure. Scala 2 is always
+the default tab (`defaultValue="scala2"`).
 
 ---

build.sbt

@@ -31,6 +31,10 @@ com.github.sbt.git.SbtGit.useReadableConsoleGit
 addCommandAlias("build", "; fmt; coverage; root/test; coverageReport")
 addCommandAlias("fmt", "all root/scalafmtSbt root/scalafmtAll")
 addCommandAlias("fmtCheck", "all root/scalafmtSbtCheck root/scalafmtCheckAll")
+addCommandAlias(
+  "fmtChanged",
+  "; set scalafmtFilter in ThisBuild := \"diff-ref=main\"; scalafmtAll; set scalafmtFilter in ThisBuild := \"\""
+)
 addCommandAlias("check", "; scalafmtSbtCheck; scalafmtCheckAll")
 addCommandAlias("mimaChecks", "all schemaJVM/mimaReportBinaryIssues")
 addCommandAlias(

docs/index.md

@@ -536,6 +536,7 @@ ZIO Blocks supports **Scala 2.13** and **Scala 3.x** with full source compatibil
 ### Core Schema Concepts
 
 - [Schema](./reference/schema.md) - Core schema definitions and derivation
+- [Allows](./reference/allows.md) - Compile-time structural grammar constraints
 - [Reflect](./reference/reflect.md) - Structural reflection API
 - [Binding](./reference/binding.md) - Runtime constructors and deconstructors
 - [BindingResolver](./reference/binding-resolver.md) - Binding lookup and schema rebinding