docs: add frontmatter validation examples to schema system docs

Adds a new "Validating frontmatter fields" section with examples for
settings.frontmatter rules including enum constraints, required keys,
and array types. Updates the complete example to include frontmatter
validation. Based on test cases in test_schema_router.py.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: phernandez

content/5.concepts/6.schema-system.md

@@ -338,7 +338,7 @@ The note body is regular markdown — use it to describe the schema's purpose, p
 | `entity` | Yes | The note type this schema applies to (e.g., `person`) |
 | `version` | No | Schema version number for tracking changes |
 | `schema` | Yes | The field definitions in picoschema syntax |
-| `settings` | No | Configuration like `validation: warn` |
+| `settings` | No | Configuration like `validation: warn` and `frontmatter` rules |
 
 Place schema notes in a `schemas/` folder by convention (e.g., `schemas/person.md`), though any location works.
 
@@ -409,6 +409,87 @@ Each field in a schema corresponds to something Basic Memory expects to find in
 | `works_at?: Organization` | Optional relation (wiki-link) | `- works_at [[Analytical Engine Project]]` |
 | `status?(enum): [active, inactive]` | Observation with constrained value | `- [status] active` |
 
+### Validating frontmatter fields
+
+Schemas can also validate a note's YAML frontmatter — not just observations and relations. Use `settings.frontmatter` to declare rules for frontmatter keys using the same picoschema syntax:
+
+```yaml
+---
+title: Person
+type: schema
+entity: person
+schema:
+  name: string, full name
+  role?: string, job title
+settings:
+  validation: warn
+  frontmatter:
+    tags?(array): string
+    status?(enum): [draft, published, archived]
+---
+```
+
+This schema validates two things about each `person` note's frontmatter:
+
+- **`tags`** — optional array of strings (e.g., `tags: [engineer, python]`)
+- **`status`** — optional enum that must be one of `draft`, `published`, or `archived`
+
+A conforming note:
+
+```yaml
+---
+title: Grace Hopper
+type: person
+tags: [computing, compilers]
+status: published
+---
+
+# Grace Hopper
+
+## Observations
+- [name] Grace Hopper
+- [role] Computer Scientist
+```
+
+Validation checks both the body fields (`name`, `role`) and the frontmatter fields (`tags`, `status`):
+
+```bash
+$ bm schema validate people/grace-hopper.md
+✓ grace-hopper: valid (0 warnings)
+```
+
+If a note has a frontmatter value outside the allowed enum:
+
+```yaml
+---
+title: Iris West
+type: person
+status: archived   # not in [draft, published]
+---
+```
+
+```bash
+$ bm schema validate people/iris-west.md
+⚠ iris-west: frontmatter field 'status' enum mismatch (got 'archived', expected one of: draft, published)
+```
+
+If a required frontmatter key is missing (no `?` suffix), validation warns or errors depending on the mode:
+
+```yaml
+settings:
+  frontmatter:
+    status: string   # required — no ? suffix
+```
+
+```bash
+$ bm schema validate people/hank-pym.md
+⚠ hank-pym: missing required frontmatter field: status
+```
+
+::note
+Frontmatter rules use the same picoschema syntax as body fields. Add `?` for optional, `(array)` for lists, and `(enum)` for constrained values.
+::
+
 ---
 
 ### CLI reference
@@ -460,6 +541,9 @@ schema:
   expertise?(array): string, areas of knowledge
 settings:
   validation: warn
+  frontmatter:
+    tags?(array): string
+    status?(enum): [active, inactive, archived]
 ---
 ```
 
@@ -469,6 +553,8 @@ settings:
 ---
 title: Ada Lovelace
 type: person
+tags: [mathematics, computing]
+status: active
 ---
 
 # Ada Lovelace