feat: add changelog schema for Keep a Changelog validation

Created comprehensive changelog-schema-v1.0.md to validate CHANGELOG.md files following the Keep a Changelog format. This schema demonstrates the practical application of the schema evolution system. **Schema Features**: - Section validation: Enforces [Unreleased] section presence - Version format validation: [X.Y.Z] - YYYY-MM-DD pattern - Semantic versioning compliance - ISO 8601 date format checking - Change type subsections: Added, Changed, Deprecated, Removed, Fixed, Security - Content pattern matching via x-markitect-content-control extensions - Structural validation via JSON Schema properties **Validation Results**: ✅ Successfully validates project CHANGELOG.md ✅ All section requirements met (7 sections checked, 11 found) ✅ All content requirements met ✅ All semantic checks passing **Implementation Notes**: - H1 "Changelog" title validated via JSON Schema structural checks - H2 sections validated via x-markitect-sections classifications - SectionValidator limitation: Only checks H2+ headings, not H1 - Workaround: Structural validation covers H1 title requirement **Philosophy**: "The release that validates itself" - v0.10.0 uses its own schema system to validate its CHANGELOG - Perfect showcase of schema evolution practical value - Demonstrates x-markitect extensions in real-world use case **Stage 2 Complete** per release-management-optimization workplan. Files: - markitect/schemas/changelog-schema-v1.0.md (new) - CHANGELOG.md (documented new schema)
fix: resolve version detection and prepare v0.10.0 release
2026-01-06 13:31:02 +01:00 · 2026-01-06 13:22:45 +01:00 · 2026-01-06 13:18:39 +01:00 · 2026-01-06 12:32:38 +01:00 · 2026-01-06 03:57:42 +01:00 · 2026-01-06 03:50:57 +01:00
193 changed files with 17238 additions and 376 deletions
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -5,22 +5,95 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

+See roadmap/YYMMDD-ROADMAPTOPIC/ directories for planning information like concepts, workplans, etc...
+See history/YYMMDD-ROADMAOTOPIC/ directories for planning information of closed topics
+
 ## [Unreleased]

+## [0.10.0] - 2026-01-06
+
 ### Added
+- **Schema Management System**: Comprehensive schema management infrastructure with naming conventions and versioning
+  - Naming convention: `{domain}-schema-v{major}.{minor}.md` for all schemas
+  - Markdown-first schema format with embedded JSON (documentation + schema in one file)
+  - Schema catalog (`markitect/schemas/schema-catalog.yaml`) for metadata and discovery
+  - Terminology validation example (`examples/terminology/`) demonstrating schema usage beyond manpages
+  - Schema-of-schemas implementation archived in `history/2026-01-05-schema-of-schemas/`
+- **Enhanced schema-list Command**: Now displays numbered references in all output formats for easy selection
+  - Simple format: `[1] schema-name.md` prefix for each schema
+  - Table format: `#` column as first column
+  - JSON/YAML: `number` field added to each schema
+  - Default format shows timestamps inline: `schema-name.json (added: 2026-01-04T23:01:19)`
+  - Table format includes Created/Updated columns
+  - Cleaner timestamp formatting (removed microseconds)
+- **Multi-Schema Validation**: Enhanced schema-validate command with multiple selection methods
+  - Number selection: `markitect schema-validate 1` validates schema #1
+  - Range selection: `markitect schema-validate 1-3` validates schemas #1-3
+  - List selection: `markitect schema-validate 1,3,5` validates schemas #1,3,5
+  - Batch validation: `markitect schema-validate --all` validates all registered schemas
+  - Filename selection: `markitect schema-validate schema.md` from registry
+  - Filesystem path: `markitect schema-validate ./schema.md` from disk
+  - Batch results displayed as clear summary table with validation status
+  - Registry schemas take precedence over filesystem (with fallback)
+  - Full backward compatibility with existing single-file validation
 - Enhanced control panel UI with better resize handle positioning for improved user interaction
+- **Semantic Document Validation**: Complete semantic validation system for markdown documents against x-markitect schema extensions
+  - Section classification enforcement: required/recommended/optional/discouraged/improper sections validated
+  - Content pattern validation: required_patterns, forbidden_patterns, discouraged_patterns with regex matching
+  - Quality metrics checking: min_words, max_words, min_sentences validation with configurable thresholds
+  - Link validation: Internal/external link checking with configurable policies
+    - Internal links: Fragment anchors (#section) and file paths validated by default
+    - External links: HTTP/HTTPS validation with --check-links flag (opt-in, may be slow)
+    - Email validation: mailto: link format checking
+    - Broken link detection with line numbers and detailed error messages
+  - Modular validator architecture: SectionValidator, ContentValidator, LinkValidator with clean separation of concerns
+  - CLI integration: `--semantic/--no-semantic`, `--strict`, `--check-links` flags for validate command
+  - Comprehensive reporting: Detailed validation reports with errors/warnings, line numbers, matched text
+  - Test coverage: 25 tests for semantic validators (16 section/content + 9 link), 100% passing
+  - Full documentation: Semantic validation guide in SCHEMA_MANAGEMENT_GUIDE.md with examples
+  - Complements existing structural AST validation for complete document compliance checking
+- **Changelog Schema**: Production schema for validating CHANGELOG.md files following Keep a Changelog format
+  - Schema file: `changelog-schema-v1.0.md` validates version history structure and formatting
+  - Enforces Unreleased section presence (required)
+  - Validates version format: `[X.Y.Z] - YYYY-MM-DD` with semantic versioning
+  - Validates change type subsections: Added, Changed, Deprecated, Removed, Fixed, Security
+  - Content pattern validation for version sections, date formats (ISO 8601), and change types
+  - Demonstrates real-world schema system usage: "The release that validates itself"
+  - Successfully validates project CHANGELOG.md with all semantic checks passing

 ### Changed
+- **Directory Reorganization**:
+  - Renamed `todo/` → `roadmap/` for better organization of planning documents
+  - Completed schema-of-schemas implementation archived to `history/2026-01-05-schema-of-schemas/`
+  - Moved completed planning artifacts to history for reference
 - Refactored contents control architecture to use base class pattern properly for better code organization
 - Updated all file references and paths to point to single source of truth in capabilities/testdrive-jsui/js/controls/ directory

 ### Fixed
+- **Version Detection Issue**: Fixed `markitect --version` returning "unknown" instead of actual version
+  - Added `git_describe_command` to setuptools-scm configuration to filter version tags correctly
+  - Configured git describe to use `--match 'v*'` pattern to ignore non-version tags
+  - Version detection now works correctly with development versions (e.g., 0.9.1.dev76)
+- **Missing v0.9.0 Git Tag**: Retroactively created v0.9.0 annotated tag on commit b9c1b90 from 2025-11-14
+  - Maintains version history integrity (CHANGELOG documented v0.9.0 but tag was missing)
+  - Enables proper version progression to v0.10.0
 - Duplicate file structure issue by eliminating duplicate control files and consolidating to capabilities/ directory
 - Contents panel scrollbar behavior - moved overflow-y: auto to correct container level so scrollbar only spans content area when panel reaches max-height

 ### Removed
 - **BREAKING**: Legacy DocumentControls component from TestDrive JSUI plugin system - all control panel functionality now provided by enhanced control panels (ContentsControl, StatusControl, DebugControl, EditControl) with Reset All button functionality moved to EditControl for better maintainability and elimination of code duplication

+### Completed Features
+- **Schema-of-Schemas Implementation** (All 6 Phases Complete ✅)
+  - ✅ Phase 1: Filename validation for schema naming convention (`markitect/schema_naming.py`, 50 tests)
+  - ✅ Phase 2: Markdown schema loader to parse `.md` schema files (`markitect/schema_loader.py`, 35 tests)
+  - ✅ Phase 3: Schema-for-schemas metaschema for schema validation (`schema-schema-v1.0.md`, 12 tests)
+  - ✅ Phase 4: Migration of 5 existing schemas to new format (migrated 2, deleted 3 duplicates)
+  - ✅ Phase 5: CLI enhancements - numbered schema-list, multi-schema validation with selection methods
+  - ✅ Phase 6: Integration testing and comprehensive documentation (SCHEMA_MANAGEMENT_GUIDE.md)
+  - **Total Test Coverage**: 97 tests, 100% passing
+  - **Complete Documentation**: Usage guide, naming spec, loader guide, metaschema reference
+
 ## [0.9.0] - 2025-11-14

 ### Added
--- a/TODO.html
+++ b/TODO.html
@@ -1,149 +0,0 @@
-<!DOCTYPE html>
-<html lang="en">
-<head>
-    <meta charset="utf-8">
-    <meta name="viewport" content="width=device-width, initial-scale=1.0">
-    <meta name="generator" content="TestDrive JSUI Markitect 1.0.0">
-    <title>TestDrive JSUI Document</title>
-
-    <style>
-        body {
-            font-family: -apple-system, BlinkMacSystemFont, Segoe UI, Helvetica, Arial, sans-serif;
-            max-width: 800px;
-            margin: 0 auto;
-            padding: 2rem;
-            line-height: 1.6;
-            color: #333333;
-            background-color: #ffffff;
-        }
-        #markdown-content {
-            min-height: 200px;
-        }
-        h1, h2, h3, h4, h5, h6 {
-            color: #333333;
-        }
-        pre {
-            background-color: #f6f8fa;
-            color: #333333;
-            padding: 1rem;
-            border-radius: 6px;
-            overflow-x: auto;
-            border: 1px solid #d0d7de;
-        }
-        code {
-            background-color: #f6f8fa;
-            color: #333333;
-            padding: 0.2em 0.4em;
-            border-radius: 3px;
-            font-size: 0.9em;
-        }
-        pre code {
-            background: none;
-            padding: 0;
-        }
-        blockquote {
-            border-left: 4px solid #dfe2e5;
-            margin: 0;
-            padding-left: 1rem;
-            color: #6a737d;
-        }
-        table {
-            font-size: 0.85em;
-            border-collapse: collapse;
-            margin: 1rem 0;
-            width: 100%;
-            border: 1px solid #d0d7de;
-        }
-        th, td {
-            font-size: inherit;
-            border: 1px solid #d0d7de;
-            padding: 0.5rem;
-            text-align: left;
-        }
-        th {
-            background-color: #f6f8fa;
-            font-weight: 600;
-        }
-        img {
-            max-width: 12cm;
-            max-height: 20cm;
-            height: auto;
-            display: block;
-            margin: 1rem auto;
-        }
-    </style>
-
-    <!-- Plugin-specific CSS -->
-    <link rel="stylesheet" href="_markitect/plugins/testdrive-jsui/static/css/editor.css">
-<link rel="stylesheet" href="_markitect/plugins/testdrive-jsui/static/css/controls.css">
-<link rel="stylesheet" href="_markitect/plugins/testdrive-jsui/static/css/themes/github.css">
-
-    <!-- External dependencies -->
-    <script src="https://cdn.jsdelivr.net/npm/marked/marked.min.js"
-            onload="window.markitectMarkedLoaded = true"
-            onerror="console.error('CDN library failed to load - network or firewall blocking marked.js'); window.markitectMarkedError = true;"></script>
-</head>
-<body class="markitect-edit-mode">
-
-    <!-- Content container with fallback content -->
-    <div id="markdown-content">
-        <h1>Todofile</h1></p><p>This is a "to do next" file, particularly useful to keep the human and a coding assistant in sync.</p><p>The format is based on [Keep a Todofile V0.0.1](https://coulomb.social/open/KeepaTodofile).</p><p>The structure organizes **future tasks** by their impact, just as a changelog organizes past changes by their impact.</p><p>***</p><p><h2>[Unreleased] - *Active Vibe-Coding State* 💡</h2></p><p>This section is for tasks currently being discussed with or worked on by the coding assistant. These are the ephemeral, flow-of-thought tasks.</p><p>*No active tasks at this time.*</p><p>***</p><p><h2>Completed Tasks</h2></p><p>*Recent completed tasks have been documented in CHANGELOG.md following Keep a Changelog format.*
-    </div>
-
-    <!-- Configuration Data Interface - Clean JSON configuration -->
-    <script id="markitect-config" type="application/json">{
-  "markdownContent": "# Todofile\n\nThis is a \"to do next\" file, particularly useful to keep the human and a coding assistant in sync.\n\nThe format is based on [Keep a Todofile V0.0.1](https://coulomb.social/open/KeepaTodofile).\n\nThe structure organizes **future tasks** by their impact, just as a changelog organizes past changes by their impact.\n\n***\n\n## [Unreleased] - *Active Vibe-Coding State* \ud83d\udca1\n\nThis section is for tasks currently being discussed with or worked on by the coding assistant. These are the ephemeral, flow-of-thought tasks.\n\n*No active tasks at this time.*\n\n***\n\n## Completed Tasks\n\n*Recent completed tasks have been documented in CHANGELOG.md following Keep a Changelog format.*",
-  "markdownContentWithDogtag": "# Todofile\n\nThis is a \"to do next\" file, particularly useful to keep the human and a coding assistant in sync.\n\nThe format is based on [Keep a Todofile V0.0.1](https://coulomb.social/open/KeepaTodofile).\n\nThe structure organizes **future tasks** by their impact, just as a changelog organizes past changes by their impact.\n\n***\n\n## [Unreleased] - *Active Vibe-Coding State* \ud83d\udca1\n\nThis section is for tasks currently being discussed with or worked on by the coding assistant. These are the ephemeral, flow-of-thought tasks.\n\n*No active tasks at this time.*\n\n***\n\n## Completed Tasks\n\n*Recent completed tasks have been documented in CHANGELOG.md following Keep a Changelog format.*",
-  "dogtagContent": "",
-  "mode": "edit",
-  "theme": "github",
-  "keyboardShortcuts": true,
-  "autosave": false,
-  "sections": true,
-  "originalFilename": "document",
-  "base64References": {},
-  "version": "Markitect 1.0.0",
-  "repoName": "Markitect"
-}</script>
-
-    <!-- Plugin JavaScript Assets -->
-    <script src="https://cdn.jsdelivr.net/npm/marked/marked.min.js"></script>
-<script src="_markitect/plugins/testdrive-jsui/static/js/core/debug-system.js"></script>
-<script src="_markitect/plugins/testdrive-jsui/static/js/core/section-manager.js"></script>
-<script src="_markitect/plugins/testdrive-jsui/static/js/components/debug-panel.js"></script>
-<script src="_markitect/plugins/testdrive-jsui/static/js/components/document-controls.js"></script>
-<script src="_markitect/plugins/testdrive-jsui/static/js/components/dom-renderer.js"></script>
-<script src="_markitect/plugins/testdrive-jsui/static/js/controls/control-base.js"></script>
-<script src="_markitect/plugins/testdrive-jsui/static/js/controls/contents-control.js"></script>
-<script src="_markitect/plugins/testdrive-jsui/static/js/controls/status-control.js"></script>
-<script src="_markitect/plugins/testdrive-jsui/static/js/controls/debug-control.js"></script>
-<script src="_markitect/plugins/testdrive-jsui/static/js/controls/edit-control.js"></script>
-<script src="_markitect/plugins/testdrive-jsui/static/js/config-loader.js"></script>
-<script src="_markitect/plugins/testdrive-jsui/static/js/main-updated.js"></script>
-
-    <!-- Initialization Script -->
-    <script>
-        window.addEventListener('load', function() {
-            console.log('🎯 TestDrive JSUI loading complete, initializing...');
-
-            // Handle CDN loading errors
-            if (window.markitectMarkedError) {
-                console.error("CDN library failed to load - network or firewall blocking marked.js");
-            }
-
-            // Initialize main application
-            try {
-                if (typeof MarkitectMain !== 'undefined') {
-                    console.log('🚀 Starting MarkitectMain initialization...');
-                    MarkitectMain.initialize();
-                } else {
-                    console.warn('⚠️ MarkitectMain not available, edit functionality may be limited');
-                }
-            } catch (error) {
-                console.error('❌ TestDrive JSUI initialization failed:', error);
-                console.log('📄 Content should still be visible in fallback mode');
-            }
-        });
-    </script>
-</body>
-</html>
--- a/TODO.md
+++ b/TODO.md
@@ -6,15 +6,15 @@ The format is based on [Keep a Todofile V0.0.1](https://coulomb.social/open/Keep

 The structure organizes **future tasks** by their impact, just as a changelog organizes past changes by their impact.

+See roadmap/YYMMDD-ROADMAPTOPIC/ directories for planning information like concepts, workplans, etc...
+
 ***

 ## [Unreleased] - *Active Vibe-Coding State* 💡

 This section is for tasks currently being discussed with or worked on by the coding assistant. These are the ephemeral, flow-of-thought tasks.

-0. the file TODO.html is legacy i think and can be removed 
-
-### Extract Capability-Capability from Issue-Facade
+### Extract Capability-Capability from Issue-Facade (Paused)

 **Context:** Issue-facade currently provides two capabilities:
 1. **issue-tracking** (explicit in CAPABILITY-issue-tracking.yaml) - Issue management across platforms
@@ -70,17 +70,3 @@ The **capability-capability** includes:

 **Current Step:** Phase 1, Task 1 - Create CAPABILITY-capability.yaml

-***
-
-## Completed Tasks
-
-*Recent completed tasks have been documented in _issue-tracking/issue-facade/CHANGELOG.md following Keep a Changelog format.*
-
-### 2025-12-17 - Architecture Refactoring
- ✅ Implemented ReusableCapabilitiesArchitecture v0.1
- ✅ Added feedback capability to issue-facade
- ✅ Created detachment facility
- ✅ Refactored to family-based directory structure (_issue-tracking/issue-facade)
- ✅ Made feedback directory visible (feedback/ not .feedback/)
- ✅ Renamed to explicit family declaration (CAPABILITY-issue-tracking.yaml)
- ✅ Created CHANGELOG.md documenting v1.0.0
--- a/agents/agent-project-management.md
+++ b/agents/agent-project-management.md
@@ -15,19 +15,25 @@ You are the MarkiTect project assistant, specialized in providing project status

 ### Key Project Files & Their Purpose

- **ProjectStatusDigest.md**: The canonical source of truth for project architecture, features, and current state
- **ProjectDiary.md**: Chronological record of major work packages, milestones, and development sessions
- **TODO.md**: Task management and priorities following Keep a Todofile format for maintaining coding flow
+- **TODO.md**: Current state of implemenation based on the Keep-A-Todofile format for maintaining coding flow
+- **CHANGELOG.md**: History of releases based on the Keep-A-Changelog format for easy access to what happend before
+- **roadmap/**: Directory with current and close range roadmap-topic-directories for concepts, workplans, examples...
+- **history/**: Directory with closed roadmap-topic-directories including finishd TODO.md files as YYMMDD-DONE.md
 - **Makefile**: Provides helpers to use and improve the capabilities provided by the project
-  **Gitea Issues**: Backlog of issues and backlog of tasks stored as issues in gitea
+  **Gitea Issues**: Backlog of issues and backlog of tasks stored as issues in gitea before selection as roadmap topics

 ### Project Infrastructure Knowledge

 **Repository Structure:**
 - Main project hosted on Gitea with issue tracking for use cases and tasks
- Documentation maintained in `wiki/` submodule
+- Planning documentation goes to roadmap/ROADMAPTOPIC subdirectories
+- Closed roadmap-topic-directories git-mv to history/ 
+- Auto generated documentation maintained in docs/ 
+- Human generated documentation maintained in wiki/ submodule
 - Test-driven development workflow with comprehensive test coverage

+Important: Respect the directory structure! If in doubt ask or use directories under tmp/ to keep the structure clean!
+
 **Development Workflow:**
 - Issue-driven development using Gitea API integration
 - Issue management via universal issue-facade CLI that works with multiple backends
@@ -56,17 +62,19 @@ You are the MarkiTect project assistant, specialized in providing project status

 When asked about project status or next steps:

-1. **Start with Current State**: Always check ProjectStatusDigest.md for the latest architecture and status
-2. **Review Recent Progress**: Check ProjectDiary.md for recent accomplishments and context
-3. **Check Planned Work**: Read Next.md for documented next steps and priorities
-4. **Consider Git Status**: Be aware of current working directory state and recent commits
+1. **Start with Current State**: Always check TODO.md for the latest activity 
+2. **Review Recent Progress**: Check CHANGELOG.md for previous work and progress
+3. **Check Planned Work**: TODO.md documents next steps and priorities, if empty see topics in roadmap/
+4. **Project Scope and Goals**: Vision, Mission, Guidelines and Usecases live in wiki/ if available
+5. **Planning New Stuff**: Requirements (Epics and Stories) are gitea issues to be planned as roadmap topics
+6. **Consider Git Status**: Allways be aware of current working directory state and recent commits

 ### Issue Management Guidelines

 **When to Create Gitea Issues:**
 - New feature requests or enhancement ideas emerge during development
 - Bugs or technical debt are discovered but not immediately fixable
- Future improvements are identified but outside current session scope
+- Future improvements are identified but outside current session and topic scope
 - Architecture decisions require documentation and future review
 - Sidequests that we want to remember for later implementation

@@ -78,10 +86,12 @@ When asked about project status or next steps:
 - Do NOT implement immediately - issues are for tracking and planning

 **Issue vs. Immediate Work:**
- Current session planned work: implement directly (from Next.md)
- Discovered improvements: create issue, continue with planned work
+- Current session planned work: document in TODO.md and roadmap/ROADMAPTOPIC 
+- Discovered improvements: add to workplan in roadmap topic, continue with planned work
 - Critical bugs affecting current work: fix immediately, then create issue for root cause analysis
- Future enhancements: always create issue first for proper planning
+- Future enhancements: note in roadmap-topic to create issues first for proper planning
+- If possible create issues interactively when closing a topic, they are for human oversight and longterm
+- Do not create issues for stuff that is detailed and can be adressed before closing the current topic

 **Response Format:**
 - Provide a brief status summary (2-3 sentences)
@@ -102,8 +112,6 @@ When asked about project status or next steps:
 1. [Action from Next.md or logical progression]
 2. [Secondary priority or alternative approach]
 3. [Maintenance or validation task if applicable]
-
-Based on: ProjectStatusDigest.md:74-79, Next.md:7-13
 ```

 ## Session Start-Up Protocol
@@ -113,10 +121,10 @@ When asked what's up for a new coding session, follow this standardized routine:
 ### Start-of-Session Checklist
 1. **Mission Status**: Provide reminder to project vision and how we are doing
 2. **Recently**: Provide reminder what we did last from the last entry to the diary
-3. **NEXT.txt**: Check if we provided guidance for what to do next at the end of the last coding session
+3. **TODO.md**: Check if we provided guidance for what to do next at the end of the last coding session
 4. **git status**: Check if git is clean or work has been left unfinished 
 5. **Workspace clean**: Check if workspace is clean or we left of in the middle of a TDD cycle
-6. **Issue finished**: Check if we are currently working on a specific issue or need to select the next one
+6. **Topic or issue finished**: Check if we are currently working on a specific roadmap-topic or issue
 7. **Suggestion**: Provide a sensible suggestion of what to do next 

 ## Session Wrap-Up Protocol
@@ -124,11 +132,10 @@ When asked what's up for a new coding session, follow this standardized routine:
 When asked to help wrap up a development session, follow this standardized routine:

 ### End-of-Session Checklist:
-1. **Update ProjectDiary.md**: Add entry documenting progress, challenges, and achievements
 2. **Update TODO.md**: Set clear priorities and strategy for next session using todofile format
-3. **Update ProjectStatusDigest.md**: Refresh current status, metrics, and completed features
+3. **Update roadmap-topic directory information**: Refresh current status, metrics, and completed features
 4. **Issue Management**: Review and create any issues for sidequests and discoveries made during session
-5. **Anchor patterns**: Update this project-assistant definition with any new workflow patterns
+5. **Anchor patterns**: Add Update suggestions for this project-assistant definition with any new workflow patterns
 6. **Prepare for commit**: Ensure all documentation reflects current state

 ### Session Success Indicators:
@@ -143,9 +150,9 @@ When asked to help wrap up a development session, follow this standardized routi
 [Brief overview of accomplishments and current state]

 ## Documentation Updates
- ✅ ProjectDiary.md: [what was added]
- ✅ Next.md: [priorities set]
- ✅ ProjectStatusDigest.md: [status updated]
+- ✅ TODO.md: [priorities set]
+- ✅ roadmap/TOPIC files: [what was added or changed]
+- ✅ CHANGELOG.ms: [status updated especially on release]

 ## Issues Created/Updated
 - 🎯 Issue #X: [brief description] - [reason for creation]
@@ -157,9 +164,19 @@ When asked to help wrap up a development session, follow this standardized routi
 Ready for commit: [list of files to commit]
 ```

+### Example Capture Small Off-Topic Improvements in roadmap/eat-the-frog:
+**Smell**: Different filename conventions od conflicting concepts, unclear guideance
+**Hunch**: Ideas to explore that need consideration if useful and in scope
+**Hickups**: Notes on inefficient or roundtripping implementation to analyse later
+
+Collect these in the roadmap-topic-directory and move stuff to eat-the-frog on close if unfinished 
+
 ### Example Issue Creation During Development:
 **Scenario**: While implementing CLI commands, discover that error messages could be improved
 **Action**: Create issue "Enhance CLI error messages with user-friendly formatting and suggestions"
 **Result**: Continue with current CLI implementation, address error enhancement in future session

+Generate issues for relevantly expensive or risky stuff and in direct feedback with developers.
+Controled in-scope-work does not need the costly issue capture, refinement, selection roundtrip. 
+
 Remember: Your role is to help developers quickly understand "where we are" and "what should we do next" when picking up work on the MarkiTect project, and to ensure proper session wrap-up for continuity.
--- a/capabilities/kaizen-agentic
+++ b/capabilities/kaizen-agentic
--- a/docs/SCHEMA_MANAGEMENT_GUIDE.md
+++ b/docs/SCHEMA_MANAGEMENT_GUIDE.md
@@ -0,0 +1,548 @@
+# Schema Management Guide
+
+Complete guide to managing schemas in MarkiTect using the Schema-of-Schemas system.
+
+## Overview
+
+MarkiTect provides a comprehensive schema management system with:
+- Markdown-first schema format with embedded JSON
+- Strict naming conventions for consistency
+- Metaschema validation for all schemas
+- Multi-schema batch validation
+- Schema registry with version tracking
+
+## Quick Start
+
+### 1. Create a New Schema
+
+Create a markdown file following the naming convention: `{domain}-schema-v{major}.{minor}.md`
+
+```bash
+# Example: blog-post-schema-v1.0.md
+```
+
+**Template:**
+
+```markdown
+---
+schema-id: https://markitect.dev/schemas/blog-post/v1.0
+version: 1.0.0
+status: stable
+domain: blog-post
+description: Schema for blog post documents
+---
+
+# Blog Post Schema v1.0.0
+
+## Overview
+This schema validates blog post documents with frontmatter and content sections.
+
+## Schema Definition
+
+```json
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://markitect.dev/schemas/blog-post/v1.0",
+  "title": "Blog Post Schema",
+  "description": "Schema for blog post documents",
+  "version": "1.0.0",
+  "type": "object",
+  "properties": {
+    "title": {
+      "type": "string",
+      "minLength": 1
+    },
+    "author": {
+      "type": "string"
+    },
+    "date": {
+      "type": "string",
+      "format": "date"
+    }
+  },
+  "required": ["title", "author"]
+}
+```
+\`\`\`
+
+### 2. Validate Your Schema
+
+Validate against the metaschema to ensure it follows MarkiTect conventions:
+
+```bash
+# Validate a single schema file
+markitect schema-validate ./blog-post-schema-v1.0.md
+
+# See detailed errors
+markitect schema-validate ./blog-post-schema-v1.0.md --detailed-errors
+```
+
+### 3. Ingest into Registry
+
+Add your schema to the registry:
+
+```bash
+markitect schema-ingest blog-post-schema-v1.0.md
+```
+
+### 4. List Registered Schemas
+
+View all schemas with numbered references:
+
+```bash
+# Simple format (default)
+markitect schema-list
+
+# Table format
+markitect schema-list --format table
+
+# JSON format
+markitect schema-list --format json
+```
+
+**Output:**
+```
+Found 4 schema(s):
+
+[1] 🔧 blog-post-schema-v1.0.md         (added: 2026-01-05T10:30:00)
+[2] 🔧 schema-schema-v1.0.md            (added: 2026-01-05T03:33:42)
+[3] 🔧 manpage-schema-v1.0.md           (added: 2026-01-05T03:33:42)
+[4] 🔧 api-documentation-schema-v1.0.md (added: 2026-01-05T03:33:35)
+```
+
+## Schema Validation
+
+### Single Schema Validation
+
+**By number:**
+```bash
+markitect schema-validate 1
+```
+
+**By filename (from registry):**
+```bash
+markitect schema-validate blog-post-schema-v1.0.md
+```
+
+**By filesystem path:**
+```bash
+markitect schema-validate ./my-schema.md
+```
+
+### Batch Validation
+
+**Validate a range:**
+```bash
+markitect schema-validate 1-3
+```
+
+**Validate specific schemas:**
+```bash
+markitect schema-validate 1,3,5
+```
+
+**Validate all schemas:**
+```bash
+markitect schema-validate --all
+```
+
+**Output:**
+```
+Validating 4 schema(s)...
+
+Results:
+
+  #  Schema                            Status    Details
+---  --------------------------------  --------  ---------
+  1  blog-post-schema-v1.0.md          ✅ Valid   v1.0.0
+  2  schema-schema-v1.0.md             ✅ Valid   v1.0.0
+  3  manpage-schema-v1.0.md            ✅ Valid   v1.0.0
+  4  api-documentation-schema-v1.0.md  ✅ Valid   v1.0.0
+
+Summary: 4 valid, 0 failed
+```
+
+## Document Validation (Semantic)
+
+### Validate Documents Against Schemas
+
+Beyond validating schema structure, MarkiTect can validate actual markdown documents against schemas, checking both structural (AST) and semantic (x-markitect extensions) aspects.
+
+**Validate a document:**
+
+```bash
+# Full validation (structural + semantic)
+markitect validate my-document.md --schema manpage-schema-v1.0.md
+
+# Only structural validation (classic mode)
+markitect validate my-document.md --schema schema.json --no-semantic
+
+# With external link checking (may be slow)
+markitect validate my-document.md --schema manpage-schema-v1.0.md --check-links
+
+# Strict mode (warnings become errors)
+markitect validate my-document.md --schema manpage-schema-v1.0.md --strict
+```
+
+### What is Validated
+
+**Structural Validation** (always enabled):
+- Document AST structure matches JSON Schema properties
+- Heading counts, paragraph counts, code block counts
+- Element types and nesting
+
+**Semantic Validation** (enabled by default with --semantic):
+- **Section Classifications**: Checks that documents have required sections, don't have improper sections
+  - REQUIRED sections must be present (ERROR if missing)
+  - RECOMMENDED sections should be present (WARNING if missing)
+  - IMPROPER sections must not be present (ERROR if found)
+  - DISCOURAGED sections should not be present (WARNING if found)
+  - OPTIONAL sections may or may not be present (no check)
+- **Content Patterns**: Validates content matches regex patterns
+  - `required_patterns`: Content must match (ERROR if missing)
+  - `forbidden_patterns`: Content must not match (ERROR if found)
+  - `discouraged_patterns`: Content should not match (WARNING if found)
+- **Quality Metrics**: Checks word counts, sentence counts
+  - `min_words`, `max_words`: Word count requirements (WARNING)
+  - `min_sentences`: Minimum sentence count (WARNING)
+- **Link Validation**: Validates internal and external links (optional)
+  - Internal links: Checked by default when semantic validation enabled
+    - Fragment links (#section-name) verified to exist (ERROR if broken)
+    - Relative file paths checked for existence (ERROR if broken)
+  - External links: Opt-in with --check-links flag (may be slow)
+    - HTTP/HTTPS URLs validated with HEAD requests (WARNING if broken)
+  - Email validation: Validates mailto: link format (WARNING if invalid)
+  - Fragment policy: Configurable allow/disallow fragment identifiers
+
+### Validation Output
+
+```
+Validation result: VALID
+File: my-command.1.md
+Schema: schema file: manpage-schema-v1.0.md
+✅ Document structure matches schema requirements
+
+============================================================
+Semantic Validation Results:
+============================================================
+Section Validation:
+  ✅ SYNOPSIS - Present (required)
+  ✅ DESCRIPTION - Present (required)
+  ✅ EXAMPLES - Present (recommended)
+
+Content Validation:
+  ✅ All content requirements met
+
+Link Validation:
+  ✅ All 12 links valid
+
+Summary:
+  Sections checked: 3
+  Sections found: 5
+  Errors: 0
+  Warnings: 0
+  Status: PASSED ✅
+```
+
+### Common Validation Scenarios
+
+**Example 1: Missing Required Section**
+```bash
+$ markitect validate doc.md --schema manpage-schema-v1.0.md
+❌ Document validation failed
+
+Section Validation:
+  ❌ SYNOPSIS - SYNOPSIS section is mandatory
+  ✅ DESCRIPTION - Present (required)
+
+Errors: 1
+Status: FAILED ❌
+```
+
+**Example 2: Forbidden Pattern Found**
+```bash
+$ markitect validate doc.md --schema manpage-schema-v1.0.md
+
+Content Validation:
+  ❌ SYNOPSIS - Forbidden pattern found: 'TODO'
+
+Errors: 1
+Status: FAILED ❌
+```
+
+**Example 3: Content Too Short (Warning)**
+```bash
+$ markitect validate doc.md --schema manpage-schema-v1.0.md
+
+Content Validation:
+  ⚠️  DESCRIPTION - Content too short (25 words, minimum 50)
+
+Warnings: 1
+Status: PASSED ✅
+
+# With --strict flag, this would fail:
+$ markitect validate doc.md --schema manpage-schema-v1.0.md --strict
+Status: FAILED ❌  (warnings treated as errors)
+```
+
+**Example 4: Broken Internal Link**
+```bash
+$ markitect validate doc.md --schema manpage-schema-v1.0.md
+
+Link Validation:
+  ❌ #nonexistent-section - Internal link target not found: #nonexistent-section
+
+Errors: 1
+Status: FAILED ❌
+```
+
+**Example 5: External Link Validation**
+```bash
+# Enable external link checking (may be slow)
+$ markitect validate doc.md --schema manpage-schema-v1.0.md --check-links
+
+Link Validation:
+  ✅ http://example.com - Valid
+  ⚠️  http://broken-link.invalid - External link unreachable: Name or service not known
+
+Warnings: 1
+Status: PASSED ✅
+```
+
+## Schema Naming Conventions
+
+All schema filenames must follow this pattern:
+
+```
+{domain}-schema-v{major}.{minor}.md
+```
+
+### Rules
+
+- **Domain**: Lowercase letters, numbers, and hyphens only
+- **Version**: Major.minor format (e.g., `v1.0`, `v2.3`)
+- **Extension**: Must be `.md`
+- **No spaces**: Use hyphens for separation
+
+### Valid Examples
+
+- `blog-post-schema-v1.0.md`
+- `api-documentation-schema-v2.1.md`
+- `user-profile-schema-v1.0.md`
+
+### Invalid Examples
+
+- `BlogPost-schema-v1.0.md` (uppercase)
+- `blog_post-schema-v1.0.md` (underscore)
+- `blog-post-v1.0.md` (missing "schema")
+- `blog-post-schema-v1.md` (missing minor version)
+
+## Required Schema Fields
+
+All schemas must include these fields:
+
+### Frontmatter (YAML)
+```yaml
+---
+schema-id: https://markitect.dev/schemas/{domain}/v{major}.{minor}
+version: {major}.{minor}.{patch}
+status: draft|stable|deprecated
+domain: {domain}
+description: Brief description
+---
+```
+
+### JSON Schema
+```json
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://markitect.dev/schemas/{domain}/v{major}.{minor}",
+  "title": "Schema Title",
+  "description": "Schema description",
+  "version": "{major}.{minor}.{patch}"
+}
+```
+
+## Common Workflows
+
+### Revalidate All Schemas After Metaschema Changes
+
+When you update the metaschema, revalidate all registered schemas:
+
+```bash
+markitect schema-validate --all
+```
+
+### Check Schema Rigidity
+
+Analyze a schema for overly rigid constraints:
+
+```bash
+markitect schema-analyze my-schema.md
+```
+
+### Refine a Rigid Schema
+
+Automatically loosen overly specific constraints:
+
+```bash
+# Dry run (preview changes)
+markitect schema-refine my-schema.md --dry-run
+
+# Apply changes
+markitect schema-refine my-schema.md
+
+# Interactive mode
+markitect schema-refine my-schema.md --interactive
+```
+
+### Get Schema Details
+
+View schema metadata:
+
+```bash
+markitect schema-get blog-post-schema-v1.0.md
+```
+
+### Delete a Schema
+
+Remove a schema from the registry:
+
+```bash
+markitect schema-delete blog-post-schema-v1.0.md --confirm
+```
+
+## Resolution Precedence
+
+When validating schemas, MarkiTect uses this resolution order:
+
+1. **Registry (by filename)**: Exact match in the database
+2. **Filesystem (fallback)**: If not found in registry or looks like a path
+
+### Examples
+
+```bash
+# Looks up in registry first
+markitect schema-validate blog-post-schema-v1.0.md
+
+# Forces filesystem lookup (contains /)
+markitect schema-validate ./blog-post-schema-v1.0.md
+
+# Also forces filesystem
+markitect schema-validate ../schemas/blog-post-schema-v1.0.md
+```
+
+## Best Practices
+
+### Schema Development
+
+1. **Start with a template**: Use an existing schema as a starting point
+2. **Validate early**: Validate against the metaschema before ingesting
+3. **Use semantic versioning**: Major.minor.patch for all versions
+4. **Document thoroughly**: Include overview, usage, and examples
+5. **Test with real documents**: Validate actual documents against your schema
+
+### Version Management
+
+- **Increment major version**: Breaking changes to schema structure
+- **Increment minor version**: Backward-compatible additions
+- **Increment patch version**: Bug fixes and clarifications
+
+### Schema Organization
+
+```
+markitect/schemas/
+├── schema-schema-v1.0.md        # Metaschema
+├── manpage-schema-v1.0.md       # Man page documents
+├── api-documentation-schema-v1.0.md
+├── terminology-schema-v1.0.md
+└── blog-post-schema-v1.0.md     # Your schemas
+```
+
+## Troubleshooting
+
+### Schema Not Found
+
+```
+❌ Schema 'my-schema.md' not found in registry or filesystem
+```
+
+**Solution:** Use `markitect schema-list` to see available schemas, or provide a path: `./my-schema.md`
+
+### Validation Fails
+
+```
+❌ Schema validation failed: my-schema.md
+Found 2 validation error(s):
+```
+
+**Solution:** Check error messages and compare with metaschema requirements. Use `--detailed-errors` for more context.
+
+### Invalid Selector
+
+```
+❌ Invalid selector: Range 1-10 is out of bounds. Valid range: 1-4
+```
+
+**Solution:** Use `markitect schema-list` to see valid numbers, or check your range syntax.
+
+## Advanced Usage
+
+### Scripting with Schema Commands
+
+Validate schemas in CI/CD:
+
+```bash
+#!/bin/bash
+# Validate all schemas and exit with error if any fail
+if ! markitect schema-validate --all; then
+    echo "Schema validation failed!"
+    exit 1
+fi
+echo "All schemas valid"
+```
+
+### Batch Operations
+
+```bash
+# Validate recently added schemas
+markitect schema-validate 1-3
+
+# Validate specific critical schemas
+markitect schema-validate 1,5,8
+
+# Check just the metaschema
+markitect schema-validate 2
+```
+
+## Schema Extensions
+
+MarkiTect supports custom extensions in schemas:
+
+- `x-markitect-sections`: Section classification (required, recommended, optional, discouraged, improper)
+- `x-markitect-content-control`: Content validation rules and patterns
+- `x-markitect-metadata`: Additional metadata for MarkiTect processing
+
+See existing schemas for examples of these extensions.
+
+## Future Enhancements
+
+Planned features:
+- Wildcard/globbing support: `markitect schema-validate */manpage*`
+- Schema diff tool: Compare schema versions
+- Schema migration assistant: Help upgrade documents to new schema versions
+
+## Related Documentation
+
+- [Schema Naming Specification](../history/260105-schema-of-schemas/SCHEMA_NAMING_SPEC.md)
+- [Schema Loader Guide](../history/260105-schema-of-schemas/SCHEMA_LOADER_GUIDE.md)
+- [Metaschema Reference](../markitect/schemas/schema-schema-v1.0.md)
+- [Implementation Workplan](../history/260105-schema-of-schemas/WORKPLAN.md) (archived)
+
+## Support
+
+For issues or questions:
+- Check existing schemas as examples
+- Review metaschema validation errors carefully
+- Use `--detailed-errors` for more context
+- Consult the metaschema for requirements
--- a/docs/user-guides/SCHEMA_REFINEMENT_TOOLS.md
+++ b/docs/user-guides/SCHEMA_REFINEMENT_TOOLS.md
@@ -0,0 +1,495 @@
+# Schema Refinement Tools - User Guide
+
+## Overview
+
+MarkiTect Phase 2 introduces powerful schema refinement tools to help you analyze and improve JSON schemas for markdown validation. These tools detect rigidity issues and automatically apply fixes to make schemas more flexible and reusable.
+
+## Quick Start
+
+```bash
+# Analyze a schema for rigidity issues
+markitect schema-analyze examples/manpages/markdown-manpage-schema.json
+
+# Refine a schema automatically
+markitect schema-refine examples/manpages/markdown-manpage-schema.json --output refined-schema.json
+
+# Review each fix interactively
+markitect schema-refine examples/manpages/markdown-manpage-schema.json --interactive
+```
+
+## Commands
+
+### schema-analyze
+
+Analyzes a JSON schema to detect rigidity issues and calculate a rigidity score (0-100).
+
+#### Usage
+
+```bash
+markitect schema-analyze <schema-file> [OPTIONS]
+```
+
+#### Options
+
+- `--verbose`, `-v`: Show detailed analysis with current and suggested values
+
+#### Examples
+
+```bash
+# Basic analysis
+markitect schema-analyze schema.json
+
+# Verbose output with details
+markitect schema-analyze schema.json --verbose
+```
+
+#### Output
+
+The analyzer provides:
+
+- **Rigidity Score** (0-100): Higher scores indicate more rigid schemas
+  - 0-40: LOW - Flexible, good design
+  - 41-70: MEDIUM - Some rigidity detected
+  - 71-100: HIGH - Very rigid, needs refinement
+
+- **Phase 1 Features**: Checks for classification system and content control
+- **Issue Count**: Breakdown by severity (Errors, Warnings, Info)
+- **Detected Issues**: List of problems with suggestions
+
+#### Exit Codes
+
+- `0`: Schema is flexible (score ≤ 50)
+- `1`: Schema is rigid (score > 50)
+- `2`: Error occurred
+
+### schema-refine
+
+Automatically refines rigid schemas by applying fixes for detected issues.
+
+#### Usage
+
+```bash
+markitect schema-refine <schema-file> [OPTIONS]
+```
+
+#### Options
+
+- `--output`, `-o PATH`: Output file (default: overwrite input file)
+- `--loosen-counts`: Convert exact counts to flexible ranges (default: enabled)
+- `--no-loosen-counts`: Disable count loosening
+- `--round-numbers`: Round overly specific numbers (default: enabled)
+- `--no-round-numbers`: Disable number rounding
+- `--migrate-deprecated`: Document deprecated extensions (default: disabled)
+- `--dry-run`: Show changes without applying them
+- `--interactive`, `-i`: Prompt for each refinement interactively
+
+#### Examples
+
+```bash
+# Refine schema in place
+markitect schema-refine schema.json
+
+# Preview changes without applying
+markitect schema-refine schema.json --dry-run
+
+# Save refined schema to new file
+markitect schema-refine schema.json --output refined-schema.json
+
+# Review each fix interactively
+markitect schema-refine schema.json --interactive
+
+# Disable specific refinements
+markitect schema-refine schema.json --no-loosen-counts
+```
+
+#### Refinement Actions
+
+The refiner automatically applies these fixes:
+
+1. **Exact Count Loosening**: Converts exact counts to flexible ranges
+   - Before: `"minItems": 5, "maxItems": 5`
+   - After: `"minItems": 3, "maxItems": 10`
+
+2. **Const Value Conversion**: Replaces exact value constraints with ranges
+   - Before: `"const": 1`
+   - After: `"minimum": 0, "maximum": 2`
+
+3. **Number Rounding**: Rounds overly specific numbers
+   - Before: `"minItems": 73`
+   - After: `"minItems": 70`
+
+4. **Range Widening**: Expands narrow integer ranges
+   - Before: `"minimum": 5, "maximum": 6`
+   - After: `"minimum": 0, "maximum": 11`
+
+#### Exit Codes
+
+- `0`: Success with changes applied
+- `1`: Success but no changes needed
+- `2`: Error occurred
+
+## Issue Types
+
+### Exact Count (WARNING)
+
+**Problem**: Schema requires exact number of items, leaving no flexibility.
+
+**Example**:
+```json
+{
+  "type": "array",
+  "minItems": 5,
+  "maxItems": 5
+}
+```
+
+**Fix**: Convert to a range
+```json
+{
+  "type": "array",
+  "minItems": 3,
+  "maxItems": 10
+}
+```
+
+### Const Value (WARNING)
+
+**Problem**: Property must have exact value.
+
+**Example**:
+```json
+{
+  "type": "integer",
+  "const": 1
+}
+```
+
+**Fix**: Replace with range for numeric values
+```json
+{
+  "type": "integer",
+  "minimum": 0,
+  "maximum": 2
+}
+```
+
+### Overly Specific Numbers (INFO)
+
+**Problem**: Numbers are too specific (like 73 instead of 70).
+
+**Example**:
+```json
+{
+  "type": "array",
+  "minItems": 73
+}
+```
+
+**Fix**: Round to nearest 10
+```json
+{
+  "type": "array",
+  "minItems": 70
+}
+```
+
+### No Flexibility (INFO)
+
+**Problem**: Integer range is too narrow.
+
+**Example**:
+```json
+{
+  "type": "integer",
+  "minimum": 5,
+  "maximum": 6
+}
+```
+
+**Fix**: Widen the range
+```json
+{
+  "type": "integer",
+  "minimum": 0,
+  "maximum": 11
+}
+```
+
+### Missing Classifications (INFO)
+
+**Problem**: Schema doesn't use the Phase 1 classification system.
+
+**Suggestion**: Add `x-markitect-sections` to classify sections as required/recommended/optional/discouraged/improper.
+
+### Missing Content Control (INFO)
+
+**Problem**: Schema lacks content validation patterns and quality metrics.
+
+**Suggestion**: Add `x-markitect-content-control` for pattern validation and quality requirements.
+
+### Deprecated Extensions (WARNING)
+
+**Problem**: Schema uses old extension format.
+
+**Example**: `x-markitect-required-sections`
+
+**Suggestion**: Migrate to `x-markitect-sections` with classification system.
+
+## Workflows
+
+### Basic Workflow: Analyze and Refine
+
+1. **Analyze** your schema to understand issues:
+   ```bash
+   markitect schema-analyze my-schema.json --verbose
+   ```
+
+2. **Preview** refinements before applying:
+   ```bash
+   markitect schema-refine my-schema.json --dry-run
+   ```
+
+3. **Apply** refinements:
+   ```bash
+   markitect schema-refine my-schema.json --output my-schema-refined.json
+   ```
+
+4. **Verify** improvements:
+   ```bash
+   markitect schema-analyze my-schema-refined.json
+   ```
+
+### Interactive Workflow
+
+For fine-grained control, use interactive mode:
+
+```bash
+markitect schema-refine my-schema.json --interactive
+```
+
+The tool will:
+1. Show each detected issue
+2. Display current and suggested values
+3. Prompt for confirmation (y/N/q)
+4. Apply only approved fixes
+
+Example session:
+```
+Issue 1/4
+  Type: exact_count
+  Path: properties.headings.level_1
+  Array 'level_1' requires exactly 1 items
+  Suggestion: Use a range like minItems: 0, maxItems: 6
+  Current: {"minItems": 1, "maxItems": 1}
+  Suggested: {"minItems": 0, "maxItems": 6}
+
+Apply this fix? [y/N/q]: y
+  ✓ Applied
+```
+
+### CI/CD Integration
+
+Use exit codes to enforce schema quality in your pipeline:
+
+```bash
+#!/bin/bash
+
+# Analyze schema and fail if rigid
+if ! markitect schema-analyze schema.json; then
+    echo "Schema is too rigid (score > 50)"
+    echo "Run: markitect schema-refine schema.json"
+    exit 1
+fi
+
+echo "Schema quality check passed"
+```
+
+### Schema Migration Workflow
+
+Migrating from old format to Phase 1:
+
+1. **Analyze** to identify deprecated extensions:
+   ```bash
+   markitect schema-analyze old-schema.json
+   ```
+
+2. **Document** deprecated extensions:
+   ```bash
+   markitect schema-refine old-schema.json --migrate-deprecated
+   ```
+
+3. **Manually migrate** to new format (automatic migration not implemented due to complexity)
+
+## Best Practices
+
+### When to Use schema-analyze
+
+- Before committing schemas to version control
+- During code review to ensure quality
+- When creating new schemas from examples
+- To understand why a schema fails validation
+
+### When to Use schema-refine
+
+- After auto-generating schemas from documents
+- When inheriting legacy schemas
+- To quickly fix common rigidity issues
+- Before publishing schemas for reuse
+
+### When to Use --interactive
+
+- When you need fine-grained control
+- For schemas with domain-specific requirements
+- When learning about schema design
+- To review fixes before applying
+
+### Recommended Settings
+
+For most use cases:
+```bash
+# Balanced refinement (default)
+markitect schema-refine schema.json
+
+# Conservative (preserve more constraints)
+markitect schema-refine schema.json --no-round-numbers
+
+# Aggressive (maximum flexibility)
+markitect schema-refine schema.json --loosen-counts --round-numbers
+```
+
+## Understanding Rigidity Scores
+
+The rigidity score is calculated by weighting detected issues:
+
+| Issue Type | Weight |
+|------------|--------|
+| Exact Count | 15 |
+| Overly Specific | 10 |
+| No Flexibility | 8 |
+| Missing Classifications | 5 |
+| Deprecated Extensions | 5 |
+| Missing Content Control | 3 |
+
+**Score Interpretation**:
+- **0-20**: Excellent - Well-designed, flexible schema
+- **21-40**: Good - Minor improvements possible
+- **41-60**: Fair - Moderate rigidity, refinement recommended
+- **61-80**: Poor - Significant rigidity, refinement needed
+- **81-100**: Very Poor - Highly rigid, manual review recommended
+
+## Integration Examples
+
+### Git Pre-commit Hook
+
+```bash
+#!/bin/bash
+# .git/hooks/pre-commit
+
+SCHEMAS=$(git diff --cached --name-only --diff-filter=ACM | grep '\.json$')
+
+for schema in $SCHEMAS; do
+    if markitect schema-analyze "$schema" 2>&1 | grep -q "RIGID"; then
+        echo "Error: $schema is too rigid"
+        echo "Run: markitect schema-refine $schema"
+        exit 1
+    fi
+done
+```
+
+### Makefile Target
+
+```makefile
+.PHONY: check-schemas
+check-schemas:
+    @for schema in schemas/*.json; do \
+        echo "Checking $$schema..."; \
+        markitect schema-analyze $$schema || exit 1; \
+    done
+
+.PHONY: refine-schemas
+refine-schemas:
+    @for schema in schemas/*.json; do \
+        echo "Refining $$schema..."; \
+        markitect schema-refine $$schema; \
+    done
+```
+
+### Python Integration
+
+```python
+import subprocess
+import json
+
+def analyze_schema(schema_path):
+    """Analyze a schema and return rigidity score."""
+    result = subprocess.run(
+        ["markitect", "schema-analyze", schema_path],
+        capture_output=True,
+        text=True
+    )
+
+    # Parse output for score
+    for line in result.stdout.split('\n'):
+        if 'Rigidity Score:' in line:
+            score = int(line.split(':')[1].split('/')[0].strip())
+            return score
+    return None
+
+def refine_schema(schema_path, output_path):
+    """Refine a schema and save to output path."""
+    result = subprocess.run(
+        ["markitect", "schema-refine", schema_path, "-o", output_path],
+        capture_output=True,
+        text=True
+    )
+    return result.returncode == 0
+
+# Usage
+score = analyze_schema("schema.json")
+if score > 50:
+    print(f"Schema is rigid (score: {score})")
+    refine_schema("schema.json", "schema-refined.json")
+```
+
+## Troubleshooting
+
+### Schema Not Found
+
+**Error**: `Error: Schema file not found: schema.json`
+
+**Solution**: Check file path and ensure file exists.
+
+### Invalid JSON
+
+**Error**: `Error: Invalid JSON in schema file`
+
+**Solution**: Validate JSON syntax using `jsonlint` or similar tool.
+
+### No Changes Applied
+
+**Output**: `No refinements needed - schema is already flexible`
+
+**Reason**: Schema doesn't have any detectable rigidity issues or has rigidity score < 50.
+
+**Action**: Use `--verbose` to see all issues including INFO level.
+
+### Refinement Broke Schema
+
+**Problem**: Refined schema is too permissive.
+
+**Solution**:
+1. Use `--interactive` to selectively apply fixes
+2. Use `--no-loosen-counts` or `--no-round-numbers` to preserve constraints
+3. Manually adjust ranges after refinement
+
+## See Also
+
+- [Schema Extensions Specification](../specifications/schema-extensions-spec.md) - Complete Phase 1 specification
+- [Schema Evolution Workplan](../../examples/manpages/SCHEMA_EVOLUTION_WORKPLAN.md) - Roadmap for schema features
+- [Manpage Example](../../examples/manpages/README.md) - Complete example demonstrating schema validation
+
+## Support
+
+For issues, questions, or feature requests:
+- GitHub Issues: https://github.com/anthropics/markitect/issues
+- Documentation: https://github.com/anthropics/markitect/docs
--- a/examples/manpages/README.md
+++ b/examples/manpages/README.md
@@ -13,9 +13,14 @@ This example showcases the "dogfooding" principle - using MarkiTect's schema val

 ## Files in This Example

-### `markdown-manpage-schema.json`
+### Schema File

-A JSON Schema defining the structure of Unix-style manual pages written in Markdown.
+The manpage schema is now managed in MarkiTect's schema registry:
+- **Schema Name**: `manpage-schema-v1.0.md`
+- **Location**: `markitect/schemas/manpage-schema-v1.0.md`
+- **Format**: Markdown with embedded JSON (following schema-of-schemas standard)
+
+This schema defines the structure of Unix-style manual pages written in Markdown.

 **Key Features:**
 - Validates H1 title format: `command(section) - description`
@@ -58,63 +63,68 @@ A comprehensive manual page (section 7) documenting MarkiTect's markdown schema

 ## Running the Example

-### 1. Validate the Manual Against the Schema
+### 1. List Available Schemas

-Verify that the manual conforms to the manpage schema:
+View all registered schemas (including the manpage schema):
+
+```bash
+markitect schema-list
+```
+
+You should see `manpage-schema-v1.0.md` listed with a number.
+
+### 2. Validate the Manual Against the Schema
+
+Verify that the manual conforms to the manpage schema using the new multi-schema validation:

 ```bash
 cd examples/manpages

+# Validate by schema filename (from registry)
+markitect schema-validate manpage-schema-v1.0.md
+
+# Or validate by number (if schema is #2 in the list)
+markitect schema-validate 2
+
+# Or validate a specific document file
 markitect validate markdown-schema-validation.1.md \
-    --schema markdown-manpage-schema.json
+    --schema manpage-schema-v1.0.md
 ```

 Expected output: ✅ **VALID** - Document structure matches schema requirements

-### 2. Show Detailed Validation
+### 3. Show Detailed Validation

 See detailed validation information:

 ```bash
-markitect validate markdown-schema-validation.1.md \
-    --schema markdown-manpage-schema.json \
-    --detailed-errors
+markitect schema-validate manpage-schema-v1.0.md --detailed-errors
 ```

-### 3. Generate Schema from the Manual
+### 4. Validate Multiple Schemas

-Analyze the manual's actual structure:
+Validate all registered schemas at once:

 ```bash
-markitect schema-generate markdown-schema-validation.1.md \
-    --output actual-structure-schema.json
+# Validate all schemas
+markitect schema-validate --all

-cat actual-structure-schema.json
+# Validate a range of schemas
+markitect schema-validate 1-3
+
+# Validate specific schemas
+markitect schema-validate 1,3,5
 ```

-Compare the generated schema with the manpage schema to see how the manual conforms.
+### 5. Examine the Schema

-### 4. Examine AST Structure
-
-View the parsed structure of the manual:
+View the manpage schema in markdown format:

 ```bash
-markitect ast-show markdown-schema-validation.1.md --format tree
-```
+markitect schema-get manpage-schema-v1.0.md

-Or in compact format:
-
-```bash
-markitect ast-show markdown-schema-validation.1.md --format compact | head -50
-```
-
-### 5. Store Schema for Reuse
-
-Add the manpage schema to MarkiTect's database:
-
-```bash
-markitect schema-ingest markdown-manpage-schema.json
-markitect schema-list
+# Or view the file directly
+cat ../../markitect/schemas/manpage-schema-v1.0.md
 ```

 ### 6. Validate Other Manpages
@@ -122,22 +132,9 @@ markitect schema-list
 Use the schema to validate other manual pages in the project:

 ```bash
+# Validate using schema name from registry
 markitect validate ../../docs/manuals/markitect.1.md \
-    --schema markdown-manpage-schema.json
-
-markitect validate ../../docs/manuals/issue.1.md \
-    --schema markdown-manpage-schema.json
-```
-
-### 7. Generate Manpage Template
-
-Create a template for new manpages:
-
-```bash
-markitect generate-stub markdown-manpage-schema.json \
-    --output new-manpage-template.md
-
-cat new-manpage-template.md
+    --schema manpage-schema-v1.0.md
 ```

 ## What This Example Demonstrates
@@ -246,7 +243,7 @@ Add to `.github/workflows/docs.yml` or similar:
  run: |
    for manpage in docs/manuals/*.md; do
      markitect validate "$manpage" \
-        --schema examples/manpages/markdown-manpage-schema.json \
+        --schema manpage-schema-v1.0.md \
        || exit 1
    done
 ```
@@ -261,11 +258,11 @@ changed_manpages=$(git diff --cached --name-only --diff-filter=ACM | grep 'docs/

 for manpage in $changed_manpages; do
    markitect validate "$manpage" \
-        --schema examples/manpages/markdown-manpage-schema.json \
+        --schema manpage-schema-v1.0.md \
        --quiet || {
        echo "Manpage validation failed: $manpage"
        markitect validate "$manpage" \
-            --schema examples/manpages/markdown-manpage-schema.json \
+            --schema manpage-schema-v1.0.md \
            --detailed-errors
        exit 1
    }
@@ -282,7 +279,7 @@ validate-manpages:
 	@echo "Validating manual pages..."
 	@for manpage in docs/manuals/*.md; do \
 		markitect validate "$$manpage" \
-			--schema examples/manpages/markdown-manpage-schema.json \
+			--schema manpage-schema-v1.0.md \
 			|| exit 1; \
 	done
 	@echo "✅ All manpages valid"
@@ -326,15 +323,17 @@ Create specialized schemas for different manpage types:

 ```bash
 # For command manpages (section 1)
-cp markdown-manpage-schema.json command-manpage-schema.json
+cp markitect/schemas/manpage-schema-v1.0.md command-manpage-schema-v1.0.md
 # Edit to require COMMANDS section
+markitect schema-validate ./command-manpage-schema-v1.0.md
+markitect schema-ingest ./command-manpage-schema-v1.0.md

 # For format manpages (section 5)
-cp markdown-manpage-schema.json format-manpage-schema.json
+cp markitect/schemas/manpage-schema-v1.0.md format-manpage-schema-v1.0.md
 # Edit to require FORMAT section

 # For convention manpages (section 7)
-cp markdown-manpage-schema.json convention-manpage-schema.json
+cp markitect/schemas/manpage-schema-v1.0.md convention-manpage-schema-v1.0.md
 # Edit to be more flexible
 ```

@@ -343,9 +342,9 @@ cp markdown-manpage-schema.json convention-manpage-schema.json
 Apply the manpage schema to your project:

 ```bash
-# Validate README
+# Validate README (if it follows manpage structure)
 markitect validate README.md \
-    --schema markdown-manpage-schema.json
+    --schema manpage-schema-v1.0.md

 # May need adjustments for non-manpage docs
 ```
--- a/examples/manpages/markdown-manpage-schema.json
+++ b/examples/manpages/markdown-manpage-schema.json
@@ -3,6 +3,152 @@
  "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.",
+  "x-markitect-sections": {
+    "SYNOPSIS": {
+      "classification": "required",
+      "heading_level": 2,
+      "position": "after_title",
+      "content_instruction": "Brief command syntax showing options and arguments in standard Unix format",
+      "min_paragraphs": 1,
+      "max_paragraphs": 5,
+      "error_message": "SYNOPSIS section is mandatory for all Unix manual pages"
+    },
+    "DESCRIPTION": {
+      "classification": "required",
+      "heading_level": 2,
+      "content_instruction": "Detailed explanation of the command's purpose and functionality",
+      "min_paragraphs": 2,
+      "error_message": "DESCRIPTION section is mandatory for all Unix manual pages"
+    },
+    "OPTIONS": {
+      "classification": "recommended",
+      "heading_level": 2,
+      "content_instruction": "Command-line options and flags with descriptions",
+      "alternatives": ["GLOBAL OPTIONS", "COMMAND OPTIONS", "FLAGS"],
+      "warning_if_missing": "Documenting command options improves usability"
+    },
+    "EXAMPLES": {
+      "classification": "recommended",
+      "heading_level": 2,
+      "content_instruction": "Practical usage examples demonstrating common use cases",
+      "min_code_blocks": 2,
+      "warning_if_missing": "Examples significantly improve manpage usability and comprehension"
+    },
+    "SEE ALSO": {
+      "classification": "recommended",
+      "heading_level": 2,
+      "content_instruction": "Related commands, configuration files, and documentation references",
+      "warning_if_missing": "Cross-references help users discover related functionality"
+    },
+    "COPYRIGHT": {
+      "classification": "recommended",
+      "heading_level": 2,
+      "content_instruction": "Copyright statement and license information",
+      "warning_if_missing": "License information should be documented for clarity"
+    },
+    "COMMANDS": {
+      "classification": "optional",
+      "heading_level": 2,
+      "content_instruction": "Subcommands and their brief descriptions"
+    },
+    "CONFIGURATION": {
+      "classification": "optional",
+      "heading_level": 2,
+      "content_instruction": "Configuration file format and options"
+    },
+    "FILES": {
+      "classification": "optional",
+      "heading_level": 2,
+      "content_instruction": "Important files used by the command with their purposes"
+    },
+    "EXIT STATUS": {
+      "classification": "optional",
+      "heading_level": 2,
+      "content_instruction": "Exit codes and their meanings"
+    },
+    "ENVIRONMENT": {
+      "classification": "optional",
+      "heading_level": 2,
+      "content_instruction": "Environment variables used or set by the command"
+    },
+    "BUGS": {
+      "classification": "optional",
+      "heading_level": 2,
+      "content_instruction": "Known issues and bug reporting instructions"
+    },
+    "AUTHORS": {
+      "classification": "optional",
+      "heading_level": 2,
+      "content_instruction": "List of contributors and maintainers"
+    }
+  },
+  "x-markitect-content-control": {
+    "synopsis": {
+      "required_patterns": [
+        "\\*\\*[a-z][a-z0-9-]*\\*\\*",
+        "\\[.*\\]"
+      ],
+      "discouraged_patterns": [
+        "TODO",
+        "FIXME"
+      ],
+      "content_quality": {
+        "min_words": 5,
+        "max_words": 150,
+        "readability_target": "technical"
+      },
+      "content_instructions": [
+        "Show command name in bold: **command**",
+        "Use brackets [] for optional arguments",
+        "Use italic *ARG* for required arguments",
+        "Keep synopsis concise (1-5 lines)",
+        "Follow man(1) synopsis conventions"
+      ]
+    },
+    "description": {
+      "discouraged_patterns": [
+        "TODO",
+        "FIXME",
+        "\\bWIP\\b",
+        "TBD"
+      ],
+      "forbidden_patterns": [
+        "password\\s*=\\s*[\"'].*[\"']",
+        "api[_-]?key\\s*=\\s*[\"'].*[\"']"
+      ],
+      "content_quality": {
+        "min_words": 50,
+        "max_words": 1000,
+        "readability_target": "technical",
+        "min_sentences": 3
+      },
+      "content_instructions": [
+        "Explain what the command does",
+        "Describe the primary purpose",
+        "Mention key features and capabilities",
+        "Note any prerequisites or dependencies",
+        "Keep language clear and technical"
+      ]
+    },
+    "examples": {
+      "required_patterns": [
+        "```",
+        "#"
+      ],
+      "content_quality": {
+        "min_words": 50,
+        "max_words": 2000,
+        "readability_target": "general"
+      },
+      "content_instructions": [
+        "Use bash code blocks with syntax highlighting",
+        "Include comments explaining each example",
+        "Start with simple examples, progress to complex",
+        "Show actual output when helpful",
+        "Cover the most common use cases"
+      ]
+    }
+  },
  "properties": {
    "headings": {
      "type": "object",
@@ -96,31 +242,5 @@
      "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"
-  }
+  "required": ["headings", "paragraphs", "code_blocks", "emphasis"]
 }
--- a/examples/manpages/markdown-schema-validation.1.md
+++ b/examples/manpages/markdown-schema-validation.1.md
@@ -27,6 +27,106 @@ MarkiTect parses markdown files into an AST representation, then validates the A

 Schemas validate structure, not semantics. A document can pass validation while containing incorrect content, as long as the structure matches the schema.

+## OPTIONS
+
+### Validation Options
+
+**--schema** *PATH*, **-s** *PATH*
+: Path to JSON schema file for validation
+: Used with **validate** command to specify schema location
+
+**--schema-json** *TEXT*
+: JSON schema provided as inline string
+: Alternative to --schema for programmatic use
+: Useful for testing or dynamic schema generation
+
+**--detailed-errors**, **--errors**
+: Show detailed validation errors with line numbers
+: Provides specific locations and descriptions of failures
+: Essential for debugging complex schema validation issues
+
+**--error-format** *FORMAT*
+: Format for error output: **text**, **json**, or **markdown**
+: Default: **text**
+: JSON format useful for CI/CD pipeline integration
+: Markdown format for inclusion in documentation
+
+**--quiet**, **-q**
+: Only output validation result (true/false)
+: Suppresses all other output for scripting
+: Exit code indicates success (0) or failure (non-zero)
+
+### Schema Generation Options
+
+**--output** *PATH*, **-o** *PATH*
+: Output file path for generated schema or document
+: Used with **schema-generate** and **generate-stub** commands
+: If omitted, outputs to stdout
+
+**--style** *STYLE*
+: Placeholder content style for **generate-stub** command
+: Options: **default**, **custom**, **detailed**
+: Affects the verbosity of generated stub content
+
+**--title** *TEXT*
+: Custom document title for generated stubs
+: Overrides default title derived from schema
+: Useful for creating multiple documents from one schema
+
+### Schema Management Options
+
+**--schema-list**
+: List all available schemas in the library
+: Shows schema names and descriptions
+: Helps discover reusable schema patterns
+
+**--schema-info** *SCHEMA_NAME*
+: Display detailed information about a specific schema
+: Shows schema structure, requirements, and metadata
+: Useful for understanding schema capabilities before use
+
+**--schema-delete** *SCHEMA_NAME*
+: Remove a schema from the library
+: Requires confirmation unless **--confirm** flag is used
+: Irreversible operation - use with caution
+
+**--confirm**
+: Skip confirmation prompts for destructive operations
+: Used with **schema-delete** and similar commands
+: Useful for automation scripts
+
+### Phase 2 Schema Refinement Options
+
+**--verbose**, **-v**
+: Show detailed analysis with current and suggested values
+: Used with **schema-analyze** command
+: Provides comprehensive rigidity assessment
+
+**--dry-run**
+: Preview refinement changes without applying them
+: Used with **schema-refine** command
+: Allows review before modifying schemas
+
+**--interactive**, **-i**
+: Prompt for each refinement interactively
+: Used with **schema-refine** command
+: Provides fine-grained control over applied fixes
+
+**--loosen-counts**
+: Convert exact counts to flexible ranges (default: enabled)
+: Part of schema refinement process
+: Can be disabled with **--no-loosen-counts**
+
+**--round-numbers**
+: Round overly specific numbers (default: enabled)
+: Improves schema reusability
+: Can be disabled with **--no-round-numbers**
+
+**--migrate-deprecated**
+: Document deprecated extension usage
+: Helps identify schemas needing manual migration
+: Does not automatically migrate (too risky)
+
 ## SCHEMA STRUCTURE

 ### JSON Schema Format
@@ -59,13 +159,21 @@ MarkiTect schemas are standard JSON Schema (draft-07) documents with custom exte

 MarkiTect extends JSON Schema with custom properties prefixed with **x-markitect-**:

-**x-markitect-required-sections**
-: Array of required H2 section names
-: Example: ["SYNOPSIS", "DESCRIPTION", "EXAMPLES"]
+**x-markitect-sections**
+: Section classification and content control system
+: Defines sections with five classification levels:
+: - **required**: Must be present (validation fails if missing)
+: - **recommended**: Should be present (warning if missing)
+: - **optional**: May be present (no validation impact)
+: - **discouraged**: Should not be present (warning if present)
+: - **improper**: Must not be present (validation fails if present)
+: Each section can specify content instructions, constraints, and custom messages

-**x-markitect-recommended-sections**
-: Array of recommended but optional section names
-: Generates warnings when missing
+**x-markitect-content-control**
+: Content validation rules for section content
+: Defines required/discouraged/forbidden patterns
+: Specifies content quality metrics (word count, readability)
+: Provides content instructions for authors

 **x-markitect-outline-mode**
 : Boolean enabling outline-only validation
@@ -236,6 +344,139 @@ The **metadata** property validates overall document characteristics:

 Use **const** for exact matches or ranges for flexibility.

+### Section Classification System
+
+MarkiTect provides a five-level classification system for document sections through **x-markitect-sections**:
+
+#### Required Sections
+
+Sections marked as **required** must be present in the document. Validation fails with an error if missing.
+
+```json
+"SYNOPSIS": {
+  "classification": "required",
+  "error_message": "SYNOPSIS section is mandatory for all manpages"
+}
+```
+
+**Validation Behavior**:
+- Missing → ERROR → validation fails
+- Present → Continue validation
+
+#### Recommended Sections
+
+Sections marked as **recommended** should be present. A warning is generated if missing, but validation succeeds.
+
+```json
+"EXAMPLES": {
+  "classification": "recommended",
+  "warning_if_missing": "Examples improve documentation usability"
+}
+```
+
+**Validation Behavior**:
+- Missing → WARNING → validation succeeds with warnings
+- Present → Continue validation
+
+#### Optional Sections
+
+Sections marked as **optional** may or may not be present with no validation impact.
+
+```json
+"BUGS": {
+  "classification": "optional",
+  "content_instruction": "Known issues and bug reporting"
+}
+```
+
+**Validation Behavior**:
+- Missing → No impact
+- Present → Continue validation
+
+#### Discouraged Sections
+
+Sections marked as **discouraged** should not be present. A warning is generated if found, but validation succeeds.
+
+```json
+"DEPRECATED": {
+  "classification": "discouraged",
+  "warning_if_missing": "Move deprecated content to HISTORY section"
+}
+```
+
+**Validation Behavior**:
+- Missing → No impact
+- Present → WARNING → validation succeeds with warnings
+
+#### Improper Sections
+
+Sections marked as **improper** must not be present. Validation fails with an error if found.
+
+```json
+"TODO": {
+  "classification": "improper",
+  "error_message": "TODO sections must be removed before publication"
+}
+```
+
+**Validation Behavior**:
+- Missing → No impact
+- Present → ERROR → validation fails
+
+### Content Control
+
+The **x-markitect-content-control** extension enables content-level validation:
+
+#### Pattern Validation
+
+**required_patterns** - Array of regex patterns that must appear in content:
+```json
+"required_patterns": ["\\*\\*command\\*\\*", "\\[.*\\]"]
+```
+
+**discouraged_patterns** - Patterns that should not appear (generates warnings):
+```json
+"discouraged_patterns": ["TODO", "FIXME", "\\bWIP\\b"]
+```
+
+**forbidden_patterns** - Patterns that must not appear (validation fails):
+```json
+"forbidden_patterns": ["password\\s*=", "api[_-]?key\\s*="]
+```
+
+#### Content Quality Metrics
+
+Validate content length and readability:
+
+```json
+"content_quality": {
+  "min_words": 50,
+  "max_words": 1000,
+  "readability_target": "technical",
+  "min_sentences": 3
+}
+```
+
+**Readability Targets**:
+- **simple** - Elementary school level
+- **general** - General audience
+- **technical** - Technical audience (default for documentation)
+- **advanced** - Expert/academic level
+
+#### Content Instructions
+
+Provide guidance for content authors:
+
+```json
+"content_instructions": [
+  "Show command name in bold",
+  "Use brackets [] for optional arguments",
+  "Keep synopsis concise (1-5 lines)"
+]
+```
+
+These instructions appear in validation reports and generated templates.
+
 ## ERROR HANDLING

 ### Common Validation Errors
@@ -303,11 +544,33 @@ Allow flexibility with minItems/maxItems ranges:

 Avoid exact counts (**const**) unless structure is truly rigid.

-**Required vs Optional Sections**
+**Section Classification**

-Use **x-markitect-required-sections** for essential sections like SYNOPSIS and DESCRIPTION.
+Use the five-level classification system to define section requirements:

-Use **x-markitect-recommended-sections** for important but optional sections like EXAMPLES.
+```json
+"x-markitect-sections": {
+  "SYNOPSIS": {
+    "classification": "required",
+    "content_instruction": "Brief command syntax",
+    "error_message": "SYNOPSIS is mandatory"
+  },
+  "EXAMPLES": {
+    "classification": "recommended",
+    "warning_if_missing": "Examples improve usability"
+  },
+  "BUGS": {
+    "classification": "optional"
+  }
+}
+```
+
+Choose classifications based on importance:
+- **required** for essential sections (SYNOPSIS, DESCRIPTION)
+- **recommended** for important sections (EXAMPLES, SEE ALSO)
+- **optional** for nice-to-have sections (BUGS, AUTHORS)
+- **discouraged** for sections that should be elsewhere (DEPRECATED)
+- **improper** for sections that must not appear (TODO, INTERNAL_NOTES)

 **Heading Patterns**

@@ -463,6 +726,78 @@ markitect schema-generate example.md --max-depth 2 --output v2-schema.json
 markitect validate test-doc.md v2-schema.json
 ```

+### Schema with Classification System
+
+Create a schema with section classifications and content control:
+
+```json
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "Technical Documentation Schema",
+  "x-markitect-sections": {
+    "OVERVIEW": {
+      "classification": "required",
+      "heading_level": 2,
+      "content_instruction": "High-level description of the system",
+      "min_paragraphs": 2,
+      "error_message": "OVERVIEW section is required"
+    },
+    "EXAMPLES": {
+      "classification": "recommended",
+      "heading_level": 2,
+      "min_code_blocks": 2,
+      "warning_if_missing": "Examples help users understand usage"
+    },
+    "REFERENCES": {
+      "classification": "optional",
+      "heading_level": 2,
+      "content_instruction": "External documentation and resources"
+    },
+    "TODO": {
+      "classification": "improper",
+      "error_message": "Remove TODO sections before publishing"
+    }
+  },
+  "x-markitect-content-control": {
+    "overview": {
+      "discouraged_patterns": ["TODO", "FIXME"],
+      "forbidden_patterns": ["password", "secret"],
+      "content_quality": {
+        "min_words": 100,
+        "max_words": 500,
+        "readability_target": "technical"
+      }
+    }
+  },
+  "properties": {
+    "headings": {
+      "properties": {
+        "level_1": {"minItems": 1, "maxItems": 1},
+        "level_2": {"minItems": 2, "maxItems": 20}
+      }
+    },
+    "paragraphs": {"minItems": 10, "maxItems": 200},
+    "code_blocks": {"minItems": 1}
+  }
+}
+```
+
+Validate documents against this schema:
+
+```bash
+# Missing required section = ERROR
+markitect validate doc-without-overview.md tech-schema.json
+# Result: INVALID - missing required section OVERVIEW
+
+# Missing recommended section = WARNING
+markitect validate doc-without-examples.md tech-schema.json
+# Result: VALID (with warnings) - missing recommended section EXAMPLES
+
+# Improper section present = ERROR
+markitect validate doc-with-todo.md tech-schema.json
+# Result: INVALID - improper section TODO must not be present
+```
+
 ## FILES

 **\*.json**
--- a/examples/schemas/manpage-schema-v1.md
+++ b/examples/schemas/manpage-schema-v1.md
@@ -0,0 +1,309 @@
+# Manpage Schema v1.0
+
+**Schema ID:** `https://markitect.dev/schemas/manpage/v1`
+**Version:** 1.0.0
+**Status:** Stable
+**Created:** 2026-01-04
+**Document Types:** Manual pages, CLI documentation
+
+## Overview
+
+This schema validates Unix/Linux manual page documentation following standard conventions. Manual pages (man pages) are the traditional form of documentation for Unix commands and system calls.
+
+## Typical Structure
+
+A well-formed manual page includes:
+
+1. **NAME** - Command name and one-line description
+2. **SYNOPSIS** - Command syntax showing all options
+3. **DESCRIPTION** - Detailed explanation of what the command does
+4. **OPTIONS** - Description of each command-line option
+5. **EXAMPLES** - Practical usage examples
+6. **SEE ALSO** - Related commands or documentation
+
+## Usage
+
+### Validate a Manpage
+
+```bash
+markitect validate mycommand.1.md --schema manpage-schema-v1
+```
+
+### Generate Manpage Template
+
+```bash
+markitect generate-stub manpage-schema-v1.json --output newcommand.1.md
+```
+
+### Refine Existing Schema
+
+```bash
+markitect schema-refine manpage-schema-v1.json --loosen-counts
+```
+
+## Examples
+
+Complete examples can be found in:
+- [examples/manpages/markdown-schema-validation.1.md](../manpages/markdown-schema-validation.1.md)
+
+## Validation Rules
+
+### Required Sections (Level 2 Headings)
+
+**NAME**
+- **Classification:** Required
+- **Content:** Command name in bold followed by brief description
+- **Format:** `**command** - one line description`
+- **Example:** `**markitect** - validate and analyze markdown documents`
+
+**SYNOPSIS**
+- **Classification:** Required
+- **Content:** Command syntax with all options
+- **Min code blocks:** 1
+- **Max paragraphs:** 3
+- **Example:**
+  ```bash
+  markitect [OPTIONS] COMMAND [ARGS]
+  ```
+
+**DESCRIPTION**
+- **Classification:** Required
+- **Content:** Detailed explanation of the command
+- **Min paragraphs:** 2
+- **Min words:** 50
+
+### Recommended Sections
+
+**OPTIONS**
+- **Classification:** Recommended
+- **Content:** Definition list or table of command-line options
+- **Format:** Each option as `**--option** *type*` followed by description
+
+**EXAMPLES**
+- **Classification:** Recommended
+- **Content:** Practical usage examples with explanations
+- **Min code blocks:** 1
+- **Benefit:** Greatly improves documentation usability
+
+### Optional Sections
+
+**ENVIRONMENT**
+- Environment variables affecting command behavior
+
+**FILES**
+- Important files used or created by the command
+
+**EXIT STATUS**
+- Explanation of exit codes
+
+**BUGS**
+- Known issues or limitations
+
+**AUTHORS**
+- Command authors and contributors
+
+**SEE ALSO**
+- Related commands or documentation
+
+## Schema Definition
+
+```json
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://markitect.dev/schemas/manpage/v1",
+  "version": "1.0.0",
+  "title": "Unix Manual Page Schema",
+  "description": "Schema for validating Unix/Linux manual page documentation",
+  "type": "object",
+  "properties": {
+    "headings": {
+      "type": "object",
+      "properties": {
+        "level_1": {
+          "type": "array",
+          "description": "Document title (command name)",
+          "items": {
+            "type": "object",
+            "properties": {
+              "content": {
+                "type": "string",
+                "pattern": ".*"
+              }
+            }
+          },
+          "minItems": 1,
+          "maxItems": 1
+        },
+        "level_2": {
+          "type": "array",
+          "description": "Section headings",
+          "items": {
+            "type": "object",
+            "properties": {
+              "content": {
+                "type": "string",
+                "enum": [
+                  "NAME",
+                  "SYNOPSIS",
+                  "DESCRIPTION",
+                  "OPTIONS",
+                  "EXAMPLES",
+                  "ENVIRONMENT",
+                  "FILES",
+                  "EXIT STATUS",
+                  "BUGS",
+                  "AUTHORS",
+                  "SEE ALSO"
+                ]
+              }
+            }
+          },
+          "minItems": 3,
+          "maxItems": 20
+        }
+      },
+      "required": ["level_1", "level_2"]
+    },
+    "paragraphs": {
+      "type": "array",
+      "description": "Paragraph content",
+      "items": {
+        "type": "object",
+        "properties": {
+          "content": {
+            "type": "string",
+            "minLength": 1
+          }
+        }
+      },
+      "minItems": 3
+    },
+    "code_blocks": {
+      "type": "array",
+      "description": "Code examples and command syntax",
+      "items": {
+        "type": "object",
+        "properties": {
+          "language": {
+            "type": "string"
+          },
+          "content": {
+            "type": "string"
+          }
+        }
+      },
+      "minItems": 1
+    }
+  },
+  "required": ["headings", "paragraphs"],
+  "x-markitect-sections": {
+    "NAME": {
+      "classification": "required",
+      "heading_level": 2,
+      "content_instruction": "Command name in bold followed by brief description",
+      "pattern": "\\*\\*[a-z-]+\\*\\*.*",
+      "error_if_missing": "NAME section is required in all manual pages"
+    },
+    "SYNOPSIS": {
+      "classification": "required",
+      "heading_level": 2,
+      "content_instruction": "Command syntax showing all options and arguments",
+      "min_code_blocks": 1,
+      "error_if_missing": "SYNOPSIS section is required to show command usage"
+    },
+    "DESCRIPTION": {
+      "classification": "required",
+      "heading_level": 2,
+      "content_instruction": "Detailed explanation of what the command does and when to use it",
+      "min_paragraphs": 2,
+      "min_words": 50,
+      "error_if_missing": "DESCRIPTION section is required for detailed explanation"
+    },
+    "OPTIONS": {
+      "classification": "recommended",
+      "heading_level": 2,
+      "content_instruction": "Description of each command-line option with syntax and explanation",
+      "warning_if_missing": "OPTIONS section recommended for commands with options"
+    },
+    "EXAMPLES": {
+      "classification": "recommended",
+      "heading_level": 2,
+      "content_instruction": "Practical usage examples with explanations",
+      "min_code_blocks": 1,
+      "warning_if_missing": "EXAMPLES greatly improve documentation usability"
+    },
+    "ENVIRONMENT": {
+      "classification": "optional",
+      "heading_level": 2,
+      "content_instruction": "Environment variables that affect command behavior"
+    },
+    "FILES": {
+      "classification": "optional",
+      "heading_level": 2,
+      "content_instruction": "Important files used or created by the command"
+    },
+    "SEE ALSO": {
+      "classification": "optional",
+      "heading_level": 2,
+      "content_instruction": "Related commands or documentation references"
+    }
+  },
+  "x-markitect-content-control": {
+    "name_section": {
+      "required_pattern": "\\*\\*[a-z-]+\\*\\*",
+      "description": "Command name must be in bold",
+      "example": "**markitect** - validate and analyze markdown documents"
+    },
+    "synopsis_section": {
+      "min_code_blocks": 1,
+      "code_block_language": "bash",
+      "description": "Must include at least one code block showing command syntax"
+    },
+    "description_section": {
+      "min_paragraphs": 2,
+      "min_words": 50,
+      "description": "Detailed description with at least 50 words across 2+ paragraphs"
+    }
+  },
+  "x-markitect-metadata": {
+    "schema-type": "document-schema",
+    "domain": "manpage",
+    "document-types": ["manual-page", "man-page", "cli-documentation"],
+    "version": "1.0.0",
+    "author": "MarkiTect Project",
+    "created": "2026-01-04",
+    "updated": "2026-01-04",
+    "example": "examples/manpages/markdown-schema-validation.1.md",
+    "supersedes": null,
+    "superseded-by": null
+  }
+}
+```
+
+## Version History
+
+### v1.0.0 (2026-01-04)
+- Initial stable release
+- Validates standard manpage sections
+- Classification system (required/recommended/optional)
+- Content control for NAME, SYNOPSIS, DESCRIPTION
+- MarkiTect extensions for improved validation
+
+## Future Enhancements
+
+Planned for v2.0:
+- Multi-language support (internationalization)
+- Extended sections (DIAGNOSTICS, SECURITY, STANDARDS)
+- Cross-reference validation
+- Version-specific section variants (man1, man5, man8)
+
+## Contributing
+
+To suggest improvements to this schema:
+1. Open an issue describing the enhancement
+2. Provide example documents demonstrating the need
+3. Propose specific schema changes
+
+## License
+
+This schema is part of the MarkiTect project and follows the same license.
--- a/examples/templates/adr-template.md
+++ b/examples/templates/adr-template.md
@@ -0,0 +1,41 @@
+<!-- Generated from schema: markitect/schemas/adr-schema-v1.0.md -->
+
+# Architecture Decision Record Schema with Classifications
+
+TODO: Add content for introduction section.
+
+## Introduction
+
+TODO: Add content for section_level_2 section.
+
+## Main Content
+
+TODO: Add content for section_level_2 section.
+
+## Conclusion
+
+TODO: Add content for section_level_2 section.
+
+## Summary
+
+TODO: Add content for section_level_2 section.
+
+## Overview
+
+TODO: Add content for section_level_2 section.
+
+## Section 6
+
+TODO: Add content for section_level_2 section.
+
+### Background
+
+TODO: Add content for section_level_3 section.
+
+### Analysis
+
+TODO: Add content for section_level_3 section.
+
+### Implementation
+
+TODO: Add content for section_level_3 section.
--- a/examples/terminology/README.md
+++ b/examples/terminology/README.md
@@ -0,0 +1,315 @@
+# Terminology Document Example
+
+This example demonstrates how to use MarkiTect schemas to validate terminology and glossary documents.
+
+## Overview
+
+Terminology documents (glossaries, dictionaries, lexicons) benefit from consistent structure and validation. This example shows how to:
+
+1. Structure terminology documents with clear categories and term definitions
+2. Validate terminology documents using JSON schemas
+3. Use MarkiTect's schema extensions for content control
+
+## Files
+
+- **terminology-example.md** - Example terminology document with proper structure
+- **Schema**: `terminology-schema-v1.0.md` (in `markitect/schemas/`)
+- **README.md** - This file
+
+The terminology schema now follows the schema-of-schemas standard with markdown format and embedded JSON.
+
+## Terminology Document Structure
+
+A well-structured terminology document includes:
+
+### Required Elements
+
+1. **Main Title (Level 1 Heading)**
+   - Should include keywords: "Terminology", "Glossary", "Terms", or "Definitions"
+
+2. **Category Sections (Level 2 Headings)**
+   - Organize terms into logical groups
+   - Examples: "Core Concepts", "Document Types", "Process Terms"
+
+3. **Term Definitions (Level 3 Headings)**
+   - Each term as a level 3 heading
+   - Followed by structured content
+
+### Term Structure
+
+Each term should include:
+
+**Required:**
+- **Definition:** Clear, concise explanation of the term
+
+**Optional (but recommended):**
+- **Synonyms:** Alternative names or abbreviations
+- **Related Terms:** Links to related concepts
+- **Example:** Practical usage example
+- **Use Cases:** Common scenarios
+- **Format:** For document type terms
+- **Components:** For complex concepts
+- **Steps:** For process terms
+
+## Usage
+
+### List Available Schemas
+
+View all registered schemas (including terminology schema):
+
+```bash
+markitect schema-list
+```
+
+You should see `terminology-schema-v1.0.md` listed with a number.
+
+### Validate Using the Schema
+
+The terminology schema is registered in MarkiTect's database. You can validate using multiple methods:
+
+```bash
+# By schema number (if terminology schema is #4 in the list)
+markitect schema-validate 4
+
+# By schema filename (from registry)
+markitect schema-validate terminology-schema-v1.0.md
+
+# Validate a specific document file
+markitect validate my-glossary.md --schema terminology-schema-v1.0.md
+
+# Or use the local file path directly
+markitect validate my-glossary.md --schema ./markitect/schemas/terminology-schema-v1.0.md
+```
+
+### Validate with Detailed Errors
+
+```bash
+markitect schema-validate terminology-schema-v1.0.md --detailed-errors
+```
+
+### Batch Validation
+
+Validate multiple schemas at once:
+
+```bash
+# Validate all schemas
+markitect schema-validate --all
+
+# Validate a range
+markitect schema-validate 1-4
+
+# Validate specific schemas
+markitect schema-validate 2,4
+```
+
+### View the Schema
+
+Examine the terminology schema:
+
+```bash
+# Get from registry
+markitect schema-get terminology-schema-v1.0.md
+
+# Or view the markdown file directly
+cat markitect/schemas/terminology-schema-v1.0.md
+```
+
+## Schema Features
+
+This schema demonstrates several MarkiTect features:
+
+### 1. Structural Validation
+
+- Enforces consistent heading hierarchy (H1 → H2 → H3)
+- Validates minimum term count
+- Ensures proper document structure
+
+### 2. Content Pattern Validation
+
+- Validates title pattern (must contain terminology-related keywords)
+- Checks for required field labels (Definition:, Synonyms:, etc.)
+- Enforces consistent formatting
+
+### 3. MarkiTect Extensions
+
+The schema uses MarkiTect-specific extensions:
+
+#### `x-markitect-sections`
+Defines section classifications and requirements:
+- `document_title` (required)
+- `category_sections` (required, min 1)
+- `term_definitions` (required, min 1)
+
+#### `x-markitect-content-control`
+Specifies content requirements:
+- Required vs optional components
+- Content quality metrics (word counts)
+- Content instructions for authors
+
+#### `x-markitect-validation-rules`
+Custom validation rules:
+- Minimum term count (3 required, 10+ recommended)
+- Category balance (min 2 terms per category)
+- Definition quality checks
+- Consistency validation
+
+## Best Practices
+
+### 1. Use Consistent Field Labels
+
+Always use the same labels for metadata:
+```markdown
+**Definition:** ...
+**Synonyms:** ...
+**Related Terms:** ...
+```
+
+### 2. Write Clear Definitions
+
+- Start with the term's primary meaning
+- Use 10-200 words
+- Be self-contained (don't require reading other terms)
+- Avoid circular definitions
+
+### 3. Group Related Terms
+
+Organize terms into logical categories:
+- Core Concepts
+- Document Types
+- Process Terms
+- Quality Attributes
+- Deprecated Terms
+
+### 4. Include Examples
+
+Add practical examples for complex terms:
+```markdown
+**Example:**
+\`\`\`markdown
+# Heading
+Paragraph text
+\`\`\`
+```
+
+### 5. Link Related Terms
+
+Use **Related Terms:** to create a terminology graph:
+```markdown
+**Related Terms:** Parser, Token, Node
+```
+
+## Extending the Schema
+
+You can customize the schema for your project:
+
+### Add Custom Field Labels
+
+Extend the `bold_text` enum:
+```json
+"enum": [
+  "Definition:",
+  "Synonyms:",
+  "Your Custom Label:"
+]
+```
+
+### Adjust Quality Metrics
+
+Modify content quality requirements:
+```json
+"content_quality": {
+  "min_words_per_definition": 20,
+  "max_words_per_definition": 300,
+  "readability_target": "business"
+}
+```
+
+### Add Domain-Specific Validation
+
+Include specialized validation rules:
+```json
+"x-markitect-validation-rules": {
+  "domain_specific": {
+    "require_acronym_expansion": true,
+    "require_source_citations": true
+  }
+}
+```
+
+## Use Cases
+
+### Documentation Projects
+
+- Software project glossaries
+- API terminology reference
+- Architecture decision records (ADR) glossary
+- Domain-driven design (DDD) ubiquitous language
+
+### Technical Writing
+
+- Standards documentation
+- Compliance documentation (ISO, SOC2)
+- Technical specifications
+- Research papers
+
+### Knowledge Management
+
+- Company wikis
+- Team handbooks
+- Onboarding documentation
+- Training materials
+
+## Integration with CI/CD
+
+### Pre-commit Hook
+
+```bash
+#!/bin/bash
+# .git/hooks/pre-commit
+markitect validate docs/glossary.md --schema terminology-schema-v1.0.md
+```
+
+### GitHub Actions
+
+```yaml
+name: Validate Terminology
+on: [push, pull_request]
+
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - name: Install MarkiTect
+        run: pip install markitect
+      - name: Validate Glossary
+        run: |
+          markitect validate docs/glossary.md \
+            --schema terminology-schema-v1.0.md \
+            --detailed-errors
+```
+
+## Related Examples
+
+- **manpages/** - Manual page documentation validation
+- **templates/** - Document template examples
+- **design-patterns/** - Software pattern documentation
+
+## Learn More
+
+- [Schema Extensions Specification](../../docs/specifications/schema-extensions-spec.md)
+- [MarkiTect Documentation](../../README.md)
+- [JSON Schema Documentation](https://json-schema.org/)
+
+## Contributing
+
+To improve this example:
+
+1. Add more terms to demonstrate edge cases
+2. Enhance the schema with additional validation rules
+3. Create alternative terminology document styles
+4. Add multilingual terminology examples
+
+## License
+
+This example is part of the MarkiTect project and follows the same license.
--- a/examples/terminology/terminology-example.md
+++ b/examples/terminology/terminology-example.md
@@ -0,0 +1,91 @@
+# Project Terminology
+
+A glossary of key terms and concepts for this project.
+
+## Core Concepts
+
+### Abstract Syntax Tree
+
+**Definition:** A tree representation of the abstract syntactic structure of source code or markup, where each node represents a construct occurring in the source.
+
+**Synonyms:** AST, Parse Tree
+
+**Related Terms:** Parser, Token, Node
+
+**Example:**
+```markdown
+# Heading
+Paragraph text
+```
+
+The AST representation would include nodes for heading (level 1) and paragraph elements.
+
+### Schema Validation
+
+**Definition:** The process of verifying that a document's structure conforms to a predefined schema specification.
+
+**Synonyms:** Structural Validation, Schema Conformance
+
+**Related Terms:** JSON Schema, Validator, Metaschema
+
+**Use Cases:**
+- Ensuring documentation completeness
+- Enforcing content standards
+- Automated quality checks
+
+## Document Types
+
+### Manpage
+
+**Definition:** A manual page document following Unix/Linux documentation conventions, typically including sections like SYNOPSIS, DESCRIPTION, and OPTIONS.
+
+**Format:** Markdown with specific heading structure
+
+**Related Terms:** Documentation, Manual, Help Text
+
+### Blueprint
+
+**Definition:** A template specification that combines schemas, content instructions, and data templates for generating documents.
+
+**Components:**
+- Schema references
+- Content model
+- Data schema
+- Generation rules
+
+## Process Terms
+
+### Schema Refinement
+
+**Definition:** The process of transforming a rigid, auto-generated schema into a flexible, classification-aware schema with content guidance.
+
+**Steps:**
+1. Analyze existing schema for rigidity
+2. Loosen exact constraints to ranges
+3. Add classification metadata
+4. Include content instructions
+
+**Tools:** `markitect schema-analyze`, `markitect schema-refine`
+
+## Quality Attributes
+
+### Classification Levels
+
+**Definition:** A hierarchical system for categorizing document elements based on their importance and requirements.
+
+**Levels:**
+- **Required**: Must be present (validation fails if missing)
+- **Recommended**: Should be present (warning if missing)
+- **Optional**: May be present (no impact)
+- **Discouraged**: Should not be present (warning if present)
+- **Improper**: Must not be present (validation fails if present)
+
+## Deprecated Terms
+
+### Rigid Schema
+
+**Status:** DEPRECATED - Use "Unrefined Schema" instead
+
+**Definition:** A schema with exact count constraints that make it unusable as a pattern.
+
+**Migration:** Use schema refinement tools to convert to flexible schemas.
--- a/examples/terminology/terminology-schema.json
+++ b/examples/terminology/terminology-schema.json
@@ -0,0 +1,214 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://markitect.dev/schemas/terminology-v1.json",
+  "title": "Terminology Document Schema",
+  "description": "Schema for validating terminology and glossary documents with consistent structure",
+  "type": "object",
+  "properties": {
+    "headings": {
+      "type": "object",
+      "properties": {
+        "level_1": {
+          "type": "array",
+          "description": "Main document title",
+          "items": {
+            "type": "object",
+            "properties": {
+              "content": {
+                "type": "string",
+                "pattern": ".*(Terminology|Glossary|Terms|Definitions).*"
+              }
+            }
+          },
+          "minItems": 1,
+          "maxItems": 1
+        },
+        "level_2": {
+          "type": "array",
+          "description": "Category headings (Core Concepts, Document Types, etc.)",
+          "items": {
+            "type": "object",
+            "properties": {
+              "content": {
+                "type": "string",
+                "minLength": 1
+              }
+            }
+          },
+          "minItems": 1,
+          "maxItems": 20
+        },
+        "level_3": {
+          "type": "array",
+          "description": "Individual term headings",
+          "items": {
+            "type": "object",
+            "properties": {
+              "content": {
+                "type": "string",
+                "minLength": 1,
+                "description": "Term name - should be title case"
+              }
+            }
+          },
+          "minItems": 1
+        }
+      },
+      "required": ["level_1", "level_2", "level_3"]
+    },
+    "paragraphs": {
+      "type": "array",
+      "description": "Content paragraphs including definitions and descriptions",
+      "items": {
+        "type": "object",
+        "properties": {
+          "content": {
+            "type": "string",
+            "minLength": 10
+          }
+        }
+      },
+      "minItems": 3
+    },
+    "bold_text": {
+      "type": "array",
+      "description": "Bold text used for field labels (Definition, Synonyms, etc.)",
+      "items": {
+        "type": "object",
+        "properties": {
+          "content": {
+            "type": "string",
+            "enum": [
+              "Definition:",
+              "Synonyms:",
+              "Related Terms:",
+              "Example:",
+              "Examples:",
+              "Use Cases:",
+              "Usage:",
+              "Format:",
+              "Components:",
+              "Steps:",
+              "Tools:",
+              "Levels:",
+              "Status:",
+              "Migration:",
+              "Required:",
+              "Recommended:",
+              "Optional:",
+              "Discouraged:",
+              "Improper:"
+            ]
+          }
+        }
+      },
+      "minItems": 1
+    }
+  },
+  "required": ["headings", "paragraphs"],
+  "x-markitect-sections": {
+    "document_title": {
+      "classification": "required",
+      "heading_level": 1,
+      "content_instruction": "Main title should include words like 'Terminology', 'Glossary', or 'Definitions'",
+      "pattern": ".*(Terminology|Glossary|Terms|Definitions).*"
+    },
+    "category_sections": {
+      "classification": "required",
+      "heading_level": 2,
+      "min_sections": 1,
+      "content_instruction": "Organize terms into logical categories (e.g., Core Concepts, Document Types, Process Terms)"
+    },
+    "term_definitions": {
+      "classification": "required",
+      "heading_level": 3,
+      "min_sections": 1,
+      "content_instruction": "Each term should be a level 3 heading followed by its definition and optional metadata"
+    }
+  },
+  "x-markitect-content-control": {
+    "term_structure": {
+      "required_components": [
+        {
+          "label": "Definition:",
+          "type": "bold_text",
+          "description": "Clear, concise definition of the term"
+        }
+      ],
+      "optional_components": [
+        {
+          "label": "Synonyms:",
+          "type": "bold_text",
+          "description": "Alternative names or abbreviations"
+        },
+        {
+          "label": "Related Terms:",
+          "type": "bold_text",
+          "description": "Links to related concepts"
+        },
+        {
+          "label": "Example:",
+          "type": "bold_text_or_code",
+          "description": "Practical example demonstrating the term"
+        },
+        {
+          "label": "Use Cases:",
+          "type": "list",
+          "description": "Common scenarios where term applies"
+        }
+      ],
+      "content_quality": {
+        "min_words_per_definition": 10,
+        "max_words_per_definition": 200,
+        "readability_target": "technical"
+      },
+      "content_instructions": [
+        "Start each term with a level 3 heading containing the term name",
+        "Follow immediately with 'Definition:' in bold",
+        "Provide a clear, self-contained definition",
+        "Add optional fields (Synonyms, Related Terms, Examples) as needed",
+        "Use consistent formatting across all terms",
+        "Group related terms under category headings (level 2)"
+      ]
+    },
+    "definition_pattern": {
+      "description": "Each definition should follow: Term heading (###) → Definition: (bold) → Definition text",
+      "validation": {
+        "heading_level_3_followed_by": "bold_text_starting_with_Definition",
+        "definition_length": {
+          "min_words": 10,
+          "max_words": 200
+        }
+      }
+    },
+    "deprecated_terms": {
+      "classification": "optional",
+      "heading_level": 2,
+      "content_instruction": "Optional section for deprecated terms with migration guidance",
+      "required_fields": [
+        "Status: DEPRECATED",
+        "Migration:"
+      ]
+    }
+  },
+  "x-markitect-validation-rules": {
+    "term_count": {
+      "min": 3,
+      "recommended_min": 10,
+      "description": "Terminology document should define at least 3 terms, 10+ recommended"
+    },
+    "category_balance": {
+      "description": "Each category should have at least 2 terms",
+      "min_terms_per_category": 2
+    },
+    "definition_quality": {
+      "all_terms_must_have_definition": true,
+      "definition_must_follow_term_heading": true,
+      "definition_min_words": 10
+    },
+    "consistency": {
+      "use_consistent_field_labels": true,
+      "maintain_heading_hierarchy": true
+    }
+  }
+}
--- a/history/2025/250925_project_status_digest.md
+++ b/history/2025/250925_project_status_digest.md
--- a/history/2025/250927_data-access-pattern-improvements.md
+++ b/history/2025/250927_data-access-pattern-improvements.md
--- a/history/2025/250927_domain-logic-separation-completion.md
+++ b/history/2025/250927_domain-logic-separation-completion.md
--- a/history/2025/250927_logging-standardization-complete.md
+++ b/history/2025/250927_logging-standardization-complete.md
--- a/history/2025/250928_gitea-auto-detection-implementation.md
+++ b/history/2025/250928_gitea-auto-detection-implementation.md
--- a/history/2025/251002_next_session_briefing.md
+++ b/history/2025/251002_next_session_briefing.md
--- a/history/2025/251002_requirements_planning_summary.md
+++ b/history/2025/251002_requirements_planning_summary.md
--- a/history/2025/251003-ADHOC_Data_Access_Improvements_GAMEPLAN.md
+++ b/history/2025/251003-ADHOC_Data_Access_Improvements_GAMEPLAN.md
--- a/history/2025/251003-ADHOC_Directory_Structure_Optimization_GAMEPLAN.md
+++ b/history/2025/251003-ADHOC_Directory_Structure_Optimization_GAMEPLAN.md
--- a/history/2025/251003-ADHOC_Domain_Logic_Separation_DEMO.md
+++ b/history/2025/251003-ADHOC_Domain_Logic_Separation_DEMO.md
--- a/history/2025/251003-ADHOC_Domain_Logic_Separation_GAMEPLAN.md
+++ b/history/2025/251003-ADHOC_Domain_Logic_Separation_GAMEPLAN.md
--- a/history/2025/251003-ADHOC_Gitea_Integration_Consolidation_GAMEPLAN.md
+++ b/history/2025/251003-ADHOC_Gitea_Integration_Consolidation_GAMEPLAN.md
--- a/history/2025/251003-ADHOC_Gitea_Issue_Separation_GAMEPLAN.txt
+++ b/history/2025/251003-ADHOC_Gitea_Issue_Separation_GAMEPLAN.txt
--- a/history/2025/251003-ADHOC_Holygrail_Requirements_GAMEPLAN.md
+++ b/history/2025/251003-ADHOC_Holygrail_Requirements_GAMEPLAN.md
--- a/history/2025/251003-ADHOC_Issue_Management_Plugin_Architecture_GAMEPLAN.md
+++ b/history/2025/251003-ADHOC_Issue_Management_Plugin_Architecture_GAMEPLAN.md
--- a/history/2025/251003-ADHOC_Main_Branch_Optimization_GAMEPLAN.md
+++ b/history/2025/251003-ADHOC_Main_Branch_Optimization_GAMEPLAN.md
--- a/history/2025/251003-ADHOC_Schema_Generation_Capability_Outline_GAMEPLAN.md
+++ b/history/2025/251003-ADHOC_Schema_Generation_Capability_Outline_GAMEPLAN.md
--- a/history/2025/251003-ADHOC_Tddai_Issue_Body_Separation_GAMEPLAN.md
+++ b/history/2025/251003-ADHOC_Tddai_Issue_Body_Separation_GAMEPLAN.md
--- a/history/2025/251003-ADHOC_Testting_Architecture_Enhancement_GAMEPLAN.md
+++ b/history/2025/251003-ADHOC_Testting_Architecture_Enhancement_GAMEPLAN.md
--- a/history/2025/251003-ADHOC_Use_Cases_Gap_GAMEPLAN.md
+++ b/history/2025/251003-ADHOC_Use_Cases_Gap_GAMEPLAN.md
--- a/history/2025/251003-ARCHITECTURAL_CHAOS_TESTING_ISSUE.md
+++ b/history/2025/251003-ARCHITECTURAL_CHAOS_TESTING_ISSUE.md
--- a/history/2025/251003-EPIC_64_TEMPLATE_ENGINE.md
+++ b/history/2025/251003-EPIC_64_TEMPLATE_ENGINE.md
--- a/history/2025/251003-EPIC_65_BATCH_PROCESSING.md
+++ b/history/2025/251003-EPIC_65_BATCH_PROCESSING.md
--- a/history/2025/251003-EPIC_66_EXTERNAL_INTEGRATION.md
+++ b/history/2025/251003-EPIC_66_EXTERNAL_INTEGRATION.md
--- a/history/2025/251003-ISSUE_16_COMPLETION.md
+++ b/history/2025/251003-ISSUE_16_COMPLETION.md
--- a/history/2025/251003-ISSUE_46_COMPLETION.md
+++ b/history/2025/251003-ISSUE_46_COMPLETION.md
--- a/history/2025/251003-ISSUE_65_COMPLETION.md
+++ b/history/2025/251003-ISSUE_65_COMPLETION.md
--- a/history/2025/251003-release_old_manual.py
+++ b/history/2025/251003-release_old_manual.py
--- a/history/2025/251004-COST_TRACKING_GAMEPLAN.md
+++ b/history/2025/251004-COST_TRACKING_GAMEPLAN.md
--- a/history/2025/251004-COST_TRACKING_ISSUES.md
+++ b/history/2025/251004-COST_TRACKING_ISSUES.md
--- a/history/2025/251004-IMPLEMENTATION_ISSUES.md
+++ b/history/2025/251004-IMPLEMENTATION_ISSUES.md
--- a/history/2025/251004-LLM_INTEGRATION_GAMEPLAN.md
+++ b/history/2025/251004-LLM_INTEGRATION_GAMEPLAN.md
--- a/history/2025/251006-GAMEPLAN_ISSUE_132_instant_markdown.md
+++ b/history/2025/251006-GAMEPLAN_ISSUE_132_instant_markdown.md
--- a/history/2025/251006-ISSUE_37_IMPLEMENTATION_SUMMARY.md
+++ b/history/2025/251006-ISSUE_37_IMPLEMENTATION_SUMMARY.md
--- a/history/2025/251006-MIGRATION_GUIDE_md_prefix.md
+++ b/history/2025/251006-MIGRATION_GUIDE_md_prefix.md
--- a/history/2025/251007-ISSUE_140_ROUNDTRIP_ANALYSIS.md
+++ b/history/2025/251007-ISSUE_140_ROUNDTRIP_ANALYSIS.md
--- a/history/2025/251007-POSTMORTEM_CONTEXT_CORRUPTION.md
+++ b/history/2025/251007-POSTMORTEM_CONTEXT_CORRUPTION.md
--- a/history/2025/251008-GAMEPLAN_ISSUE_141_VARIANT_B.md
+++ b/history/2025/251008-GAMEPLAN_ISSUE_141_VARIANT_B.md
--- a/history/2025/251008-ISSUE_141_ASSET_MANAGEMENT_CONCEPTS.md
+++ b/history/2025/251008-ISSUE_141_ASSET_MANAGEMENT_CONCEPTS.md
--- a/history/2025/251012-ISSUE_147_EXPLODE_IMPLODE_ENHANCEMENT_GAMEPLAN.md
+++ b/history/2025/251012-ISSUE_147_EXPLODE_IMPLODE_ENHANCEMENT_GAMEPLAN.md
--- a/history/2025/251014-ISSUES_152_153_ANALYSIS.md
+++ b/history/2025/251014-ISSUES_152_153_ANALYSIS.md
--- a/history/2025/251025-NEXT_archived_20251025.md
+++ b/history/2025/251025-NEXT_archived_20251025.md
--- a/history/2025/251025-ProjectDiary.md
+++ b/history/2025/251025-ProjectDiary.md
--- a/history/2025/251025-ProjectStatusDigest.md
+++ b/history/2025/251025-ProjectStatusDigest.md
--- a/history/2025/251025-development-scripts/demo_issue_150.py
+++ b/history/2025/251025-development-scripts/demo_issue_150.py
--- a/history/2025/251025-migration-reports/AGENT_MIGRATION_REPORT.md
+++ b/history/2025/251025-migration-reports/AGENT_MIGRATION_REPORT.md
--- a/history/2025/251025-migration-reports/ASSET_MODEL_MIGRATION.md
+++ b/history/2025/251025-migration-reports/ASSET_MODEL_MIGRATION.md
--- a/history/2025/251025-migration-reports/KAIZEN_MIGRATION_GAMEPLAN.md
+++ b/history/2025/251025-migration-reports/KAIZEN_MIGRATION_GAMEPLAN.md
--- a/history/2025/251025-migration-reports/KAIZEN_UPDATE_REPORT.md
+++ b/history/2025/251025-migration-reports/KAIZEN_UPDATE_REPORT.md
--- a/history/2025/251025-migration-reports/PHASE_3_COMPLETION_REPORT.md
+++ b/history/2025/251025-migration-reports/PHASE_3_COMPLETION_REPORT.md
--- a/history/2025/251025-migration-reports/PHASE_4_COMPLETION_REPORT.md
+++ b/history/2025/251025-migration-reports/PHASE_4_COMPLETION_REPORT.md
--- a/history/2025/251109-release_old_manual.py.README.md
+++ b/history/2025/251109-release_old_manual.py.README.md
--- a/history/2025/251109-test_document_extracted/README.md
+++ b/history/2025/251109-test_document_extracted/README.md
--- a/history/2025/251109-test_document_extracted/content.md
+++ b/history/2025/251109-test_document_extracted/content.md
--- a/history/2025/251109-test_document_extracted/package.json
+++ b/history/2025/251109-test_document_extracted/package.json
--- a/history/2025/251109-workplan-testdrive-jsui-capability.md
+++ b/history/2025/251109-workplan-testdrive-jsui-capability.md
--- a/history/2025/251114-GUARDRAILS-edit-mode-dbde13e-2025-11-11-00-29-34.html
+++ b/history/2025/251114-GUARDRAILS-edit-mode-dbde13e-2025-11-11-00-29-34.html
--- a/history/2025/251114-GUARDRAILS-fully-recovered-2025-11-12-01-03-25.html
+++ b/history/2025/251114-GUARDRAILS-fully-recovered-2025-11-12-01-03-25.html
--- a/history/2025/251114-GUARDRAILS-static-dbde13e-2025-11-11-00-29-34.html
+++ b/history/2025/251114-GUARDRAILS-static-dbde13e-2025-11-11-00-29-34.html
--- a/history/2025/251114-INTEGRATION_COMPLETE.md
+++ b/history/2025/251114-INTEGRATION_COMPLETE.md
--- a/history/2025/251114-REFACTORING_SESSION_REPORT.md
+++ b/history/2025/251114-REFACTORING_SESSION_REPORT.md
--- a/history/2025/251114-development-crisis-report-2025-11-12.md
+++ b/history/2025/251114-development-crisis-report-2025-11-12.md
--- a/history/2025/251114-javascript-dev-tests/README.md
+++ b/history/2025/251114-javascript-dev-tests/README.md
--- a/history/2025/251114-javascript-dev-tests/TEST_ENVIRONMENT.md
+++ b/history/2025/251114-javascript-dev-tests/TEST_ENVIRONMENT.md
--- a/history/2025/251114-javascript-dev-tests/debug_buttons.js
+++ b/history/2025/251114-javascript-dev-tests/debug_buttons.js
--- a/history/2025/251114-javascript-dev-tests/debug_floating_menu.js
+++ b/history/2025/251114-javascript-dev-tests/debug_floating_menu.js
--- a/history/2025/251114-javascript-dev-tests/demo_clean_editor.html
+++ b/history/2025/251114-javascript-dev-tests/demo_clean_editor.html
--- a/history/2025/251114-javascript-dev-tests/e2e_tests.js
+++ b/history/2025/251114-javascript-dev-tests/e2e_tests.js
--- a/history/2025/251114-javascript-dev-tests/final_functionality_verification.js
+++ b/history/2025/251114-javascript-dev-tests/final_functionality_verification.js
--- a/history/2025/251114-javascript-dev-tests/test_advanced_image_editor.js
+++ b/history/2025/251114-javascript-dev-tests/test_advanced_image_editor.js
--- a/history/2025/251114-javascript-dev-tests/test_alt_text_margin_layout.js
+++ b/history/2025/251114-javascript-dev-tests/test_alt_text_margin_layout.js
--- a/history/2025/251114-javascript-dev-tests/test_bulk_operations.js
+++ b/history/2025/251114-javascript-dev-tests/test_bulk_operations.js
--- a/history/2025/251114-javascript-dev-tests/test_button_functionality.js
+++ b/history/2025/251114-javascript-dev-tests/test_button_functionality.js
--- a/history/2025/251114-javascript-dev-tests/test_buttons_top_alttext_bottom.js
+++ b/history/2025/251114-javascript-dev-tests/test_buttons_top_alttext_bottom.js
--- a/history/2025/251114-javascript-dev-tests/test_cancel_button_debug.js
+++ b/history/2025/251114-javascript-dev-tests/test_cancel_button_debug.js
--- a/history/2025/251114-javascript-dev-tests/test_click_propagation_fix.js
+++ b/history/2025/251114-javascript-dev-tests/test_click_propagation_fix.js
--- a/history/2025/251114-javascript-dev-tests/test_component_positioning.js
+++ b/history/2025/251114-javascript-dev-tests/test_component_positioning.js
--- a/history/2025/251114-javascript-dev-tests/test_comprehensive_section_styling.js
+++ b/history/2025/251114-javascript-dev-tests/test_comprehensive_section_styling.js
--- a/history/2025/251114-javascript-dev-tests/test_comprehensive_status_dialog.js
+++ b/history/2025/251114-javascript-dev-tests/test_comprehensive_status_dialog.js
--- a/history/2025/251114-javascript-dev-tests/test_concurrent_editing.js
+++ b/history/2025/251114-javascript-dev-tests/test_concurrent_editing.js
--- a/history/2025/251114-javascript-dev-tests/test_content_rendering_validation.js
+++ b/history/2025/251114-javascript-dev-tests/test_content_rendering_validation.js
--- a/history/2025/251114-javascript-dev-tests/test_dialog_fixes.js
+++ b/history/2025/251114-javascript-dev-tests/test_dialog_fixes.js
--- a/history/2025/251114-javascript-dev-tests/test_dialog_positioning.js
+++ b/history/2025/251114-javascript-dev-tests/test_dialog_positioning.js
--- a/history/2025/251114-javascript-dev-tests/test_dom_events.js
+++ b/history/2025/251114-javascript-dev-tests/test_dom_events.js
--- a/history/2025/251114-javascript-dev-tests/test_dom_integration.html
+++ b/history/2025/251114-javascript-dev-tests/test_dom_integration.html
--- a/Show More
+++ b/Show More