Merge PR #508: docs(features): add motivation and worked example to file-kinds-schemas

Author: merge-queue-bot

docs/features/file-kinds-schemas.md

@@ -13,19 +13,56 @@ group: "A connected docs tree"
 # File kinds and schemas
 
 Not every Markdown file plays the same role. A plan is not a rule
-README, and a release-channel page is not a guide. mdsmith lets
-you model that.
-
-A **kind** is a named bundle of rule config. You bind files to it
-by front matter, a `kind-assignment` glob, or a `path-pattern`.
-Each kind can attach a **schema** that constrains required
-headings, section order, and front-matter fields.
-
-Declare the schema inline on the kind or share it from a
-`proto.md` template, so a whole directory validates against one
-source of truth. Named field-type shortcuts keep the schema
-short. `MDS020` reports a precise diagnostic when a file breaks
-its contract.
-
-See the [file-kinds guide](../guides/file-kinds.md) and the
-[schemas guide](../guides/schemas.md) for the full vocabulary.
+README, and a release-channel page is not a guide. A per-file
+style linter treats them all alike: it catches a long line, but
+not a missing Decision section or an invented `status` value. A
+directory of similar files drifts as it grows.
+
+A **kind** gives each file a role; a **schema** gives that role a
+contract. Bind files to a kind by a front-matter `kinds:` field or
+a `kind-assignment` glob. The kind's schema then constrains
+required headings, section order, and front-matter fields. Declare
+it inline on the kind, or share it from a `proto.md` template so a
+whole directory validates against one source of truth.
+
+For example, an `rfc` kind can declare its schema inline in
+`.mdsmith.yml`:
+
+```yaml
+kinds:
+  rfc:
+    schema:
+      frontmatter:
+        status: '"draft" | "ratified" | "deprecated"'
+      sections:
+        - heading: "Context"
+        - heading: "Decision"
+```
+
+Tag a file with that kind:
+
+```markdown
+---
+kinds: [rfc]
+status: approved
+---
+# RFC-0007: Adopt structured logging
+
+## Context
+
+We keep losing requests in unstructured log lines.
+```
+
+This file breaks the contract twice. `approved` is not an allowed
+`status`. The required `Decision` section is missing. `MDS020`
+reports both:
+
+```text
+RFC-0007.md:3:1 MDS020 status: got "approved", expected one of: "draft", "ratified", "deprecated"
+RFC-0007.md:7:1 MDS020 ## Decision: got <missing>, expected section to be present
+```
+
+Schemas go further: they nest sections, repeat them, and inherit
+from a parent. See the [file-kinds guide](../guides/file-kinds.md)
+and the [schemas guide](../guides/schemas.md) for the full
+vocabulary.