feat: add manpages example demonstrating schema validation

Add comprehensive example showcasing schema validation with self-documenting
manpage system:

- markdown-manpage-schema.json: Reusable schema for Unix manpage structure
- markdown-schema-validation.1.md: Complete manual about schema validation
- README.md: Usage guide, integration examples, and best practices
- SCHEMA_EVOLUTION_WORKPLAN.md: Roadmap for enhanced schema system

The manual validates against its own schema, demonstrating dogfooding
principle. Workplan outlines 5-phase evolution from rigid structural
validation to flexible content control with blueprints.

Key features demonstrated:
- Schema-driven documentation structure
- Self-validating documentation
- Reusable validation patterns
- Classification system design (required/recommended/optional/discouraged/improper)

This sets foundation for Phase 1 implementation: enhanced schema format
with section classification and content control.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

examples/manpages/markdown-manpage-schema.json

@@ -0,0 +1,126 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "object",
+  "title": "Markdown Manpage Schema",
+  "description": "JSON schema defining the structure of Unix-style manual pages written in Markdown. Compatible with man(1) section format and conventions.",
+  "properties": {
+    "headings": {
+      "type": "object",
+      "description": "Document heading structure following Unix manpage conventions",
+      "properties": {
+        "level_1": {
+          "type": "array",
+          "description": "Title heading: command(section) - brief description",
+          "items": {
+            "type": "object",
+            "properties": {
+              "content": {
+                "type": "string",
+                "pattern": "^[a-z0-9-]+\\([0-9]\\) - .+",
+                "description": "Must follow format: command(section) - description"
+              },
+              "level": {
+                "type": "integer",
+                "const": 1
+              }
+            },
+            "required": ["content", "level"]
+          },
+          "minItems": 1,
+          "maxItems": 1
+        },
+        "level_2": {
+          "type": "array",
+          "description": "Main section headings (SYNOPSIS, DESCRIPTION, etc.)",
+          "items": {
+            "type": "object",
+            "properties": {
+              "content": {
+                "type": "string",
+                "description": "Section name in UPPERCASE"
+              },
+              "level": {
+                "type": "integer",
+                "const": 2
+              }
+            },
+            "required": ["content", "level"]
+          },
+          "minItems": 3,
+          "maxItems": 30
+        },
+        "level_3": {
+          "type": "array",
+          "description": "Subsection headings (optional, for grouping commands or options)",
+          "items": {
+            "type": "object",
+            "properties": {
+              "content": {
+                "type": "string"
+              },
+              "level": {
+                "type": "integer",
+                "const": 3
+              }
+            },
+            "required": ["content", "level"]
+          },
+          "minItems": 0,
+          "maxItems": 50
+        }
+      },
+      "required": ["level_1", "level_2"]
+    },
+    "paragraphs": {
+      "type": "array",
+      "description": "Text paragraphs containing descriptions and explanations",
+      "minItems": 5,
+      "maxItems": 500
+    },
+    "lists": {
+      "type": "array",
+      "description": "Lists for options, examples, or structured information",
+      "minItems": 0,
+      "maxItems": 100
+    },
+    "code_blocks": {
+      "type": "array",
+      "description": "Code examples and command demonstrations",
+      "minItems": 1,
+      "maxItems": 50
+    },
+    "emphasis": {
+      "type": "array",
+      "description": "Bold and italic emphasis for commands, options, and arguments",
+      "minItems": 10,
+      "maxItems": 500
+    }
+  },
+  "required": ["headings", "paragraphs", "code_blocks", "emphasis"],
+  "x-markitect-required-sections": [
+    "SYNOPSIS",
+    "DESCRIPTION"
+  ],
+  "x-markitect-recommended-sections": [
+    "OPTIONS",
+    "EXAMPLES",
+    "SEE ALSO",
+    "COPYRIGHT"
+  ],
+  "x-markitect-optional-sections": [
+    "COMMANDS",
+    "CONFIGURATION",
+    "FILES",
+    "EXIT STATUS",
+    "ENVIRONMENT",
+    "BUGS",
+    "AUTHORS"
+  ],
+  "x-markitect-conventions": {
+    "heading_case": "UPPERCASE for H2 sections",
+    "command_format": "Bold with **command** for commands and options",
+    "argument_format": "Italic with *ARG* for arguments and placeholders",
+    "example_language": "bash for code blocks",
+    "definition_lists": "Use bold followed by colon for FILES, EXIT STATUS, ENVIRONMENT sections"
+  }
+}