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
186 changed files with 14438 additions and 357 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,34 +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.*
-
-### 2026-01-04 - Phase 2: Schema Refinement Tools
- ✅ Implemented schema-analyze command to detect rigidity issues
- ✅ Implemented schema-refine command with automatic loosening logic
- ✅ Added interactive mode to schema-refine for fine-grained control
- ✅ Created comprehensive test suite (33 unit tests, 100% passing)
- ✅ Wrote user guide documentation with examples and workflows
- ✅ Successfully tested on example schemas (reduced rigidity from 60/100 to 24/100)
- ✅ Integrated into CLI with proper exit codes and error handling
-
-**Key Features Delivered:**
- Rigidity score calculation (0-100 scale)
- Automatic detection of exact counts, const values, overly specific numbers
- Path navigation for nested schema properties
- Dry-run mode for previewing changes
- Interactive approval workflow
- Comprehensive reporting (normal and verbose modes)
-
-### 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/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/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/history/2025/251114-javascript-dev-tests/test_e2e_comprehensive.js
+++ b/history/2025/251114-javascript-dev-tests/test_e2e_comprehensive.js
--- a/history/2025/251114-javascript-dev-tests/test_e2e_focused.js
+++ b/history/2025/251114-javascript-dev-tests/test_e2e_focused.js
--- a/history/2025/251114-javascript-dev-tests/test_enhanced_dom_events.js
+++ b/history/2025/251114-javascript-dev-tests/test_enhanced_dom_events.js
--- a/Show More
+++ b/Show More