docs: prepare CHANGELOG for v0.11.0 release

Add release notes extraction from CHANGELOG for publishing:

- Create ChangelogParser class to extract version sections from CHANGELOG
- Support multiple output formats: markdown, plain text, HTML
- Add 'release notes VERSION' CLI command to extract notes
- Auto-detect latest version if not specified
- Support piping to gh/gitea release commands
- Save to file with --output option
- Plain text format removes markdown formatting
- HTML format converts markdown to HTML

This streamlines creating release notes for GitHub/Gitea releases
by extracting CHANGELOG content automatically.

Usage:
  release notes 0.10.0                    # Extract markdown notes
  release notes                           # Latest version
  release notes 0.10.0 --format plain    # Plain text
  release notes 0.10.0 -o notes.md       # Save to file
  release notes 0.10.0 | gh release create v0.10.0 -F -

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

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

.claude/capabilities/issue-facade.md

@@ -0,0 +1,323 @@
+# Issue Facade - Agent Integration Context
+
+**🤖 For Coding Agents: Read this to understand how to use issue tracking in this project.**
+
+## Critical: DO NOT Bypass This Capability
+
+⚠️ **IMPORTANT:** If you need to work with issues, **you MUST use this capability**. Do NOT:
+- ❌ Make direct API calls to Gitea/GitHub/GitLab
+- ❌ Use platform CLIs (gh, glab, etc.)
+- ❌ Import platform libraries (PyGithub, python-gitlab, etc.)
+- ❌ Parse HTML/scrape issue tracker web UIs
+
+**Why?** Bypassing this capability causes:
+- Credential management chaos (tokens scattered everywhere)
+- Inconsistent issue state across agents
+- Massive token waste (redundant API calls)
+- Platform lock-in (can't switch Gitea → GitHub easily)
+- Race conditions in multi-agent scenarios
+
+## Quick Reference
+
+### Check if Capability is Available
+
+```bash
+# Verify installation
+issue --version
+# or
+python -c "from issue_tracker.backends.gitea import GiteaBackend; print('OK')"
+```
+
+### Basic Usage (Python)
+
+```python
+from issue_tracker.backends.gitea import GiteaBackend
+from issue_tracker.core.models import Issue, Label, IssueState, User, Comment
+from issue_tracker.core.interfaces import IssueFilter
+from datetime import datetime, timezone
+import os
+
+# Connect (assumes backend is configured)
+backend = GiteaBackend()
+backend.connect({
+    'base_url': os.environ['GITEA_URL'],
+    'token': os.environ['GITEA_API_TOKEN'],
+    'owner': os.environ['GITEA_OWNER'],
+    'repo': os.environ['GITEA_REPO']
+})
+
+# List issues for me
+my_issues = backend.list_issues(IssueFilter(
+    state='open',
+    assignee='my-agent-id',
+    labels=['needs-implementation']
+))
+
+# Create issue
+new_issue = Issue(
+    id=None, number=0,
+    title="Implement feature X",
+    description="Details...",
+    state=IssueState.OPEN,
+    created_at=datetime.now(timezone.utc),
+    updated_at=datetime.now(timezone.utc),
+    labels=[Label(name="feature"), Label(name="priority:high")]
+)
+created = backend.create_issue(new_issue)
+
+# Update issue
+created.state = IssueState.IN_PROGRESS
+created.assignees = [User(id="agent-id", username="agent-id")]
+backend.update_issue(created)
+
+# Add comment
+comment = Comment(
+    id=None,
+    body="Implementation started. Working on database schema.",
+    author=User(id="agent-id", username="agent-id"),
+    created_at=datetime.now(timezone.utc)
+)
+backend.add_comment(created.id, comment)
+
+# Close when done
+created.state = IssueState.CLOSED
+created.closed_at = datetime.now(timezone.utc)
+backend.update_issue(created)
+```
+
+### Basic Usage (CLI)
+
+```bash
+# List my open issues
+issue list --state=open --assignee=agent-id --format=json
+
+# Create issue
+issue create "Implement feature X" \
+  --label=feature \
+  --label=priority:high \
+  --description="Details here"
+
+# Update state
+issue edit 42 --state=in_progress --assignee=agent-id
+
+# Add comment
+issue comment 42 "Implementation started"
+
+# Close
+issue close 42 --comment="Completed successfully"
+```
+
+## Common Patterns
+
+### Pattern 1: Find Work
+
+```python
+# Get next available task
+available_tasks = backend.list_issues(IssueFilter(
+    state='open',
+    labels=['ready', 'needs-implementation']
+))
+
+# Filter to unassigned
+unassigned = [t for t in available_tasks if not t.assignees]
+
+if unassigned:
+    task = unassigned[0]
+    # Claim it...
+```
+
+### Pattern 2: Claim Issue (Prevent Race Conditions)
+
+```python
+def claim_issue(issue: Issue, agent_id: str) -> bool:
+    """Claim an issue safely."""
+    # Check if already claimed
+    if issue.assignees:
+        return False  # Already taken
+
+    # Claim it
+    issue.state = IssueState.IN_PROGRESS
+    issue.assignees = [User(id=agent_id, username=agent_id)]
+    backend.update_issue(issue)
+
+    # Announce claim
+    backend.add_comment(issue.id, Comment(
+        id=None,
+        body=f"🤖 Claimed by {agent_id}",
+        author=User(id=agent_id, username=agent_id),
+        created_at=datetime.now(timezone.utc)
+    ))
+    return True
+```
+
+### Pattern 3: Progress Updates
+
+```python
+def report_progress(issue: Issue, message: str, agent_id: str):
+    """Report progress on an issue."""
+    backend.add_comment(issue.id, Comment(
+        id=None,
+        body=f"**Progress Update:**\n\n{message}",
+        author=User(id=agent_id, username=agent_id),
+        created_at=datetime.now(timezone.utc)
+    ))
+```
+
+### Pattern 4: Agent-to-Agent Communication
+
+```python
+import json
+
+def post_agent_message(issue_id: str, msg_type: str, data: dict, agent_id: str):
+    """Post structured message for other agents."""
+    message = {
+        'type': msg_type,
+        'agent': agent_id,
+        'timestamp': datetime.now(timezone.utc).isoformat(),
+        'data': data
+    }
+    backend.add_comment(issue_id, Comment(
+        id=None,
+        body=f"```agent-message\n{json.dumps(message, indent=2)}\n```",
+        author=User(id=agent_id, username=agent_id),
+        created_at=datetime.now(timezone.utc)
+    ))
+
+def read_agent_messages(issue_id: str, msg_type: str = None):
+    """Read messages from other agents."""
+    comments = backend.get_comments(issue_id)
+    messages = []
+    for comment in comments:
+        if '```agent-message' in comment.body:
+            try:
+                json_str = comment.body.split('```agent-message\n')[1].split('\n```')[0]
+                msg = json.loads(json_str)
+                if msg_type is None or msg['type'] == msg_type:
+                    messages.append(msg)
+            except:
+                continue
+    return messages
+```
+
+## Configuration Check
+
+Before using issue tracking, verify configuration:
+
+```python
+def verify_issue_backend() -> bool:
+    """Verify issue backend is configured."""
+    try:
+        backend = GiteaBackend()
+        backend.connect({
+            'base_url': os.environ['GITEA_URL'],
+            'token': os.environ['GITEA_API_TOKEN'],
+            'owner': os.environ['GITEA_OWNER'],
+            'repo': os.environ['GITEA_REPO']
+        })
+        return backend.test_connection()
+    except Exception as e:
+        print(f"Issue backend not configured: {e}")
+        return False
+
+# Use it
+if not verify_issue_backend():
+    print("ERROR: Issue tracking not available. Check configuration.")
+    sys.exit(1)
+```
+
+## Error Handling
+
+```python
+from issue_tracker.backends.gitea.backend import GiteaAPIError
+
+try:
+    issue = backend.get_issue_by_number(42)
+except GiteaAPIError as e:
+    if e.status_code == 404:
+        print("Issue not found")
+    elif e.status_code == 401:
+        print("Authentication failed - check GITEA_API_TOKEN")
+    elif e.status_code == 429:
+        print("Rate limited - wait and retry")
+    else:
+        print(f"API error: {e}")
+```
+
+## Performance Tips
+
+1. **Use filters** instead of fetching all issues:
+   ```python
+   # BAD: Get all, filter in Python
+   all_issues = backend.list_issues()
+   my_issues = [i for i in all_issues if i.assignees and i.assignees[0].username == 'me']
+
+   # GOOD: Filter at backend
+   my_issues = backend.list_issues(IssueFilter(assignee='me'))
+   ```
+
+2. **Use JSON output** for CLI parsing:
+   ```bash
+   issue list --format=json | jq '.[] | select(.state == "open")'
+   ```
+
+3. **Batch comments** instead of rapid-fire updates
+
+4. **Check local cache** before querying (if available)
+
+## Troubleshooting
+
+### "Backend not configured"
+```bash
+# Check config
+issue backend list
+
+# If empty, configure
+export GITEA_API_TOKEN="your-token"
+issue backend add myproject gitea
+issue backend set-default myproject
+```
+
+### "Authentication failed"
+```bash
+# Verify token
+curl -H "Authorization: token $GITEA_API_TOKEN" $GITEA_URL/api/v1/user
+```
+
+### "Issue not found"
+```python
+# Use get_issue_by_number, not get_issue
+issue = backend.get_issue_by_number(42)  # Correct
+# issue = backend.get_issue("42")  # Wrong - needs backend_id
+```
+
+## Full Documentation
+
+- **Integration Guide:** `AGENT_INTEGRATION.md` (comprehensive patterns and strategies)
+- **API Reference:** `CLAUDE.md` (for developers extending the capability)
+- **Examples:** `examples/agents/` (working agent implementations)
+- **Roadmap:** `ROADMAP.md` (upcoming features)
+
+## Current Limitations (v1.0)
+
+Be aware of these limitations:
+
+1. **Manual Configuration:** Backend must be configured before use (auto-detect in v1.1)
+2. **User Context:** Uses hardcoded user for CLI operations (agent identity in v1.2)
+3. **No Built-in Locking:** Use assignee + comment workaround for claiming (native in v1.2)
+4. **Basic Conflicts:** Manual resolution required for complex sync conflicts (advanced in v2.0)
+
+Workarounds are documented in `AGENT_INTEGRATION.md`.
+
+## Questions?
+
+If you're unsure whether to use this capability for something:
+
+**ASK:** "Does this involve creating, reading, updating, or searching issues?"
+- **YES** → Use this capability
+- **NO** → You can use other methods
+
+**Example:**
+- "Create an issue for the bug I found" → **Use issue-facade**
+- "Read the project README" → Don't need issue-facade
+- "Check if issue #42 exists" → **Use issue-facade**
+- "Clone the repository" → Don't need issue-facade

.claude/commands/use-issues.md

@@ -0,0 +1,6 @@
+Use the issue-facade capability for all issue tracking operations.
+
+**Quick reference:** See `.claude/capabilities/issue-facade.md`
+**Examples:** See `capabilities/issue-facade/examples/agents/`
+
+**DO NOT use direct API calls or platform CLIs!**

.claude/context/capabilities.md

@@ -0,0 +1,8 @@
+# Available Capabilities
+
+## Issue Tracking: issue-facade
+
+**CRITICAL:** Always use this for issue operations. Never bypass with direct API calls.
+
+**Docs:** `.claude/capabilities/issue-facade.md`
+**Usage:** `/use-issues`

.gitignore

@@ -78,6 +78,8 @@ Thumbs.db
 
 # MarkiTect database files (local development)
 markitect.db
+assets/assets.db
+**/assets.db
 .markitect/
 
 # Issue workspace (temporary development files)
@@ -96,3 +98,4 @@ ISSUES.index
 
 # Test artifacts and temporary files
 tmp/
+markitect/_version.py

.gitmodules

@@ -2,9 +2,13 @@
 	path = wiki
 	url = http://92.205.130.254:32166/coulomb/markitect_project.wiki.git
 	branch = main
-[submodule "capabilities/issue-facade"]
-	path = capabilities/issue-facade
-	url = http://92.205.130.254:32166/coulomb/issue-facade.git
 [submodule "capabilities/kaizen-agentic"]
 	path = capabilities/kaizen-agentic
 	url = http://92.205.130.254:32166/coulomb/kaizen-agentic.git
+[submodule "capabilities/testdrive-jsui"]
+	path = capabilities/testdrive-jsui
+	url = http://92.205.130.254:32166/coulomb/testdrive-jsui.git
+[submodule "_issue-tracking/issue-facade"]
+	path = _issue-tracking/issue-facade
+	url = http://92.205.130.254:32166/coulomb/issue-facade.git
+	branch = main

CHANGELOG.md

@@ -5,8 +5,158 @@ 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.11.0] - 2026-01-06
+
+### Added
+- Release management optimizations: CHANGELOG validation, version-tag consistency checks
+- Automated tag pushing with --push/--no-push flag
+- Unpushed tags detection in release status
+
+### Changed
+- Improved release validation workflow with CHANGELOG schema validation
+
+
+## [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
+- **Plugin Infrastructure Foundation**: Extended existing MarkiTect plugin system with RenderingEnginePlugin base class and RENDERING plugin type
+- **RenderingEngineManager**: Complete plugin discovery and lifecycle management system for UI rendering engines
+- **RenderingConfig System**: Asset management and deployment configuration for plugin engines
+- **TestDrive JSUI Plugin**: Complete independent JavaScript UI plugin extracted from core system with standalone development environment
+- **Modular Component Architecture**: Compass-positioned controls with clean JSON configuration interface for Python-JavaScript data transfer
+- **CLI Engine Parameter**: Added --engine parameter to markitect md-render command with engine validation and mode compatibility checking
+- **Automatic Asset Deployment**: Production-ready asset deployment to _markitect/plugins/ structure with 18 total assets (12 JS, 3 CSS, 3 images)
+- **ChatGPT Document Theme**: New document theme with Inter font, 580px width, and #10a37f accent color with full CLI support (`markitect md-render --theme chatgpt`)
+- **Modular Theme System Architecture**: File-based theme loading with YAML configuration and dynamic theme discovery
+- **Theme Directory Structure**: Organized theme components (mode/, ui/, document/, branding/) for better maintainability
+- **Database Architecture Documentation**: Comprehensive WORKSPACE_AND_DATABASES.md documenting workspace concepts and database purposes
+
+### Changed
+- **BREAKING**: Edit mode now defaults to testdrive-jsui plugin instead of legacy edit mode
+- **Default Rendering Behavior**: testdrive-jsui for edit/insert modes, standard for view mode with graceful fallback
+- **Asset Management Strategy**: Automatic plugin asset deployment eliminates need for manual --ship-assets flag
+- **JavaScript Architecture**: Clean separation between Python backend and JavaScript frontend with modular design
+- **Theme Loading System**: Implemented dynamic theme discovery and loading with metadata preservation
+- **Test Suite Organization**: Removed obsolete configuration CLI tests (490 lines) for cleaner codebase
+
+### Fixed
+- **JavaScript Loading Conflicts**: Resolved const redeclaration errors with MARKITECT_STRICT_MODE implementation
+- **MarkitectMain Availability**: Fixed proper main-updated.js loading and JavaScript syntax errors
+- **Plugin Asset Deployment**: Directory structure preservation with development vs production deployment strategies
+- **Issue-facade Click Framework Bug**: Resolved Sentinel bug in list command that was causing CLI failures
+- **Issue-facade Version Command**: Fixed installation error preventing version command from working
+- **Test Isolation Issues**: Improved test isolation with proper mocking to prevent cross-test interference
+- **Theme Color Assertions**: Updated test assertions to work with new modular theme system
+
+### Migration Guide
+- **Existing Users**: Edit mode will automatically use new testdrive-jsui plugin for enhanced experience
+- **Legacy Behavior**: Use `markitect md-render --engine standard --edit` to access previous edit mode
+- **Asset Deployment**: Plugin assets now deploy automatically - no manual --ship-assets flag required
+
+## [0.8.0] - 2025-11-08
+
+### Added
+- **Setuptools-SCM Integration**: Automatic version management system replacing manual version tracking
+- **Gitea Package Publishing**: Complete CI/CD pipeline for automated package publishing to Gitea
+- **Enhanced Release Documentation**: Comprehensive documentation for package building and release process
+
+### Changed
+- **Release Script Architecture**: Modernized release workflow with setuptools-scm integration
+- **Makefile Release Targets**: Updated release targets to support automated version management
+- **Package Building Process**: Streamlined package creation with enhanced build targets
+
+### Removed
+- **Legacy Release Scripts**: Removed obsolete release_simplified.py in favor of unified release.py
+
 ## [0.7.0] - 2025-11-08
 
 ### Added
@@ -158,4 +308,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **Build System**: Enhanced build targets with venv Python and PYTHONPATH support
 - **Target Naming**: Renamed workspace targets to TDD Workspace with tdd- prefix
 
-xxx
+[Unreleased]: https://github.com/worsch/markitect/compare/v0.9.0...HEAD
+[0.9.0]: https://github.com/worsch/markitect/compare/v0.8.0...v0.9.0
+[0.8.0]: https://github.com/worsch/markitect/compare/v0.7.0...v0.8.0
+[0.7.0]: https://github.com/worsch/markitect/compare/v0.6.0...v0.7.0
+[0.6.0]: https://github.com/worsch/markitect/compare/v0.5.0...v0.6.0
+[0.5.0]: https://github.com/worsch/markitect/compare/v0.4.0...v0.5.0
+[0.4.0]: https://github.com/worsch/markitect/compare/v0.3.0...v0.4.0
+[0.3.0]: https://github.com/worsch/markitect/compare/v0.2.0...v0.3.0
+[0.2.0]: https://github.com/worsch/markitect/compare/v0.1.0...v0.2.0
+[0.1.0]: https://github.com/worsch/markitect/releases/tag/v0.1.0

GUARDRAILS.md

@@ -0,0 +1,81 @@
+# Development Guardrails
+
+## JavaScript Code Principles
+
+### 1. No Inline JavaScript in Python
+**NEVER write JavaScript code directly from Python code**
+
+❌ **Wrong:**
+```python
+script = f"""
+function myFunction() {{
+    console.log("Hello {name}");
+}}
+"""
+```
+
+✅ **Correct:**
+```python
+# Load from external files only
+components = [
+    'js/core/section-manager.js',
+    'js/components/debug-panel.js',
+    'js/components/document-controls.js'
+]
+```
+
+### 2. Why This Rule Exists
+- **Quoting Problems**: String escaping in Python corrupts JavaScript
+- **Syntax Errors**: Template literals and complex JS break when embedded
+- **Maintainability**: JS code should be in .js files for proper tooling
+- **Architecture**: Follows the established modular component system
+
+### 3. Proper Approach
+1. Create separate `.js` files in `markitect/static/js/components/`
+2. Load them via `_get_clean_editor_scripts()`
+3. Wire up components in the initialization script only
+
+## Testing and Validation
+
+### 1. Always Validate Generated HTML
+- Check that HTML files actually render content
+- Validate JavaScript syntax before deployment
+- Test both viewing and editing modes
+
+### 2. Detect JavaScript Errors Programmatically
+- Run syntax validation on generated JS
+- Check for common error patterns
+- Fail fast when JS is malformed
+
+### 3. Manual Testing Backup
+- If automated checks pass but functionality fails
+- Open generated HTML in browser
+- Check console for runtime errors
+- Report specific error messages
+
+## Architecture Principles
+
+### 1. Separation of Concerns
+- Python: File generation, template management
+- JavaScript: UI components, interaction logic
+- HTML: Structure and content only
+
+### 2. Modular Component System
+- Each UI component in separate file
+- Lazy loading where appropriate
+- Clear dependency management
+
+### 3. Error Handling
+- Graceful degradation when components fail
+- Clear error messages for debugging
+- Fallback modes when possible
+
+## Breaking These Rules
+
+If you find yourself writing JavaScript in Python strings:
+1. **STOP** - Step back and reconsider
+2. Create a proper component file instead
+3. Use the existing component loading system
+4. Add validation to catch the issue early
+
+These guardrails exist because we've seen the problems when they're violated.

Makefile

@@ -1,7 +1,13 @@
 # MarkiTect - Advanced Markdown Engine
 # Makefile for common development tasks
 
-.PHONY: help setup install install-dev uninstall install-home install-home-venv install-user-deps install-force-deps install-deps-venv install-system-deps list-deps setup-dev test build clean update status lint format check-deps venv-status update-digest add-diary-entry test-status test-new test-coverage test-arch test-foundation test-infrastructure test-integration test-domain test-service test-application test-presentation test-quick test-layers test-random test-random-seed test-random-repeat test-install-randomly test-clean test-tdd test-changed test-module test-cache-clean test-efficient cli-help release-status release-validate release-prepare release-build release-publish release-dry-run chaos-validate chaos-matrix chaos-inject chaos-report cost-help
+# Include capability discovery system
+include scripts/capability_discovery.mk
+
+# Set explicit default target
+.DEFAULT_GOAL := help
+
+.PHONY: help setup install install-dev uninstall install-home install-home-venv install-user-deps install-force-deps install-deps-venv install-system-deps list-deps setup-dev test test-js test-all build clean update status lint format check-deps venv-status update-digest add-diary-entry test-status test-new test-coverage test-arch test-foundation test-infrastructure test-integration test-domain test-service test-application test-presentation test-quick test-layers test-random test-random-seed test-random-repeat test-install-randomly test-clean test-tdd test-changed test-module test-cache-clean test-efficient cli-help chaos-validate chaos-matrix chaos-inject chaos-report cost-help
 
 # Default target
 help:
@@ -26,22 +32,26 @@ help:
 	@echo ""
 	@echo "Development:"
 	@echo "  test        - Run core tests (excluding capability-specific tests)"
-	@echo "  test-capabilities   - Run all capability-specific tests"
-	@echo "  test-capability-*   - Run specific capability tests (content, utils, finance, etc.)"
+	@echo "  test-js     - Run JavaScript UI tests"
+	@echo "  test-all    - Run all tests (Python + JavaScript + Capabilities)"
+	@echo "  test-capabilities   - Run all capability tests (delegated to capabilities)"
 	@echo "  test-status - Show test status summary without re-running"
 	@echo "  test-new    - Create new test file template"
 	@echo "  test-coverage       - Analyze test coverage"
 	@echo "  build       - Build the package"
+	@echo "  package     - Build distribution packages (wheel + sdist)"
 	@echo "  lint        - Run code linting"
 	@echo "  format      - Format code"
 	@echo ""
-	@echo "Release Management:"
-	@echo "  release-status       - Show current release status"
-	@echo "  release-validate     - Validate repository for release"
-	@echo "  release-prepare VERSION=x.y.z - Prepare new release"
-	@echo "  release-build        - Build release packages"
-	@echo "  release-publish VERSION=x.y.z - Publish complete release"
-	@echo "  release-dry-run VERSION=x.y.z - Test release preparation"
+	@echo "Capabilities & Extensions:"
+	@echo "  capabilities-list            List all available capabilities"
+	@echo "  capabilities-help            Show help for all capabilities"
+	@echo "  capabilities-status          Show capability status"
+	@echo ""
+	@echo "Release Management (via capability):"
+	@echo "  release-status               Show current release status"
+	@echo "  release-publish-gitea VERSION=x.y.z  Complete release + Gitea upload"
+	@echo "  Run 'make capabilities-help' for all release commands"
 	@echo ""
 	@echo "Chaos Engineering:"
 	@echo "  chaos-validate       - Run architectural independence validation"
@@ -380,32 +390,22 @@ test: $(VENV)/bin/activate
 	fi
 
 # Capability-Specific Test Targets
-test-capabilities: test-capability-content test-capability-utils test-capability-finance test-capability-query test-capability-graphql test-capability-plugins
+# Delegate to capability discovery system for testing capabilities
+test-capabilities: capabilities-test
 	@echo "✅ All capability tests completed"
 
-test-capability-content: $(VENV)/bin/activate
-	@echo "🧪 Running markitect-content capability tests..."
-	@cd capabilities/markitect-content && python -m pytest tests/ -v
+# Legacy test-capability-* targets are now handled by capability delegation
+# Use 'make capability-name-test' instead (e.g., 'make markitect-content-test')
 
-test-capability-utils: $(VENV)/bin/activate
-	@echo "🧪 Running markitect-utils capability tests..."
-	@cd capabilities/markitect-utils && python -m pytest tests/ -v
+# JavaScript UI Testing Targets (Phase 5.1 - TestDrive-JSUI Integration)
+.PHONY: test-js
+test-js: ## Run JavaScript UI tests
+	@echo "🧪 Running JavaScript UI tests..."
+	@$(MAKE) --no-print-directory testdrive-jsui-test-all
 
-test-capability-finance: $(VENV)/bin/activate
-	@echo "🧪 Running finance capability tests..."
-	@PYTHONPATH=. $(VENV_PYTHON) -m pytest markitect/finance/tests/ -v
-
-test-capability-query: $(VENV)/bin/activate
-	@echo "🧪 Running query paradigms capability tests..."
-	@PYTHONPATH=. $(VENV_PYTHON) -m pytest markitect/query_paradigms/tests/ -v
-
-test-capability-graphql: $(VENV)/bin/activate
-	@echo "🧪 Running GraphQL capability tests..."
-	@PYTHONPATH=. $(VENV_PYTHON) -m pytest markitect/graphql/tests/ -v
-
-test-capability-plugins: $(VENV)/bin/activate
-	@echo "🧪 Running plugins capability tests..."
-	@PYTHONPATH=. $(VENV_PYTHON) -m pytest markitect/plugins/tests/ -v
+.PHONY: test-all
+test-all: test test-js test-capabilities ## Run all tests (Python + JavaScript + Capabilities)
+	@echo "✅ All test suites completed successfully!"
 
 # TDD8 Workflow Optimized Test Targets (Issue #57)
 
@@ -482,42 +482,25 @@ build: $(VENV)/bin/activate
 	$(VENV_PYTHON) -m build 2>/dev/null || \
 	$(VENV_PIP) install build && $(VENV_PYTHON) -m build
 
-# Release management
-release-status:
-	@echo "🔍 Checking release status..."
-	$(VENV_PYTHON) release.py status
+# Build distribution packages with version info
+package: $(VENV)/bin/activate
+	@echo "📦 Building distribution packages..."
+	@echo ""
+	@echo "📍 Current version (setuptools-scm):"
+	@$(VENV_PYTHON) -m setuptools_scm 2>/dev/null || echo "   setuptools-scm not available"
+	@echo ""
+	@echo "🧹 Cleaning previous builds..."
+	@rm -rf build/ dist/ *.egg-info/ 2>/dev/null || true
+	@echo "🏗️  Building wheel and source distribution..."
+	@$(VENV_PIP) install build setuptools-scm >/dev/null 2>&1 || true
+	$(VENV_PYTHON) -m build --wheel --sdist
+	@echo ""
+	@echo "✅ Packages built successfully:"
+	@ls -lah dist/ 2>/dev/null || echo "   No packages found"
 
-release-validate:
-	@echo "✅ Validating release readiness..."
-	$(VENV_PYTHON) release.py validate
-
-release-prepare:
-	@echo "🚀 Preparing release..."
-	@if [ -z "$(VERSION)" ]; then \
-		echo "❌ Usage: make release-prepare VERSION=1.0.0"; \
-		exit 1; \
-	fi
-	$(VENV_PYTHON) release.py prepare --version $(VERSION)
-
-release-build:
-	@echo "📦 Building release packages..."
-	$(VENV_PYTHON) release.py build $(if $(VERSION),--version $(VERSION))
-
-release-publish:
-	@echo "📢 Publishing release..."
-	@if [ -z "$(VERSION)" ]; then \
-		echo "❌ Usage: make release-publish VERSION=1.0.0"; \
-		exit 1; \
-	fi
-	$(VENV_PYTHON) release.py publish --version $(VERSION)
-
-release-dry-run:
-	@echo "🧪 Dry run release preparation..."
-	@if [ -z "$(VERSION)" ]; then \
-		echo "❌ Usage: make release-dry-run VERSION=1.0.0"; \
-		exit 1; \
-	fi
-	$(VENV_PYTHON) release.py prepare --version $(VERSION) --dry-run
+# Release management targets are provided by capabilities/release-management/Makefile
+# All capability targets are automatically discovered and available via delegation
+# Run 'make capabilities-help' to see all available capability commands
 
 # Chaos Engineering targets
 chaos-validate:

TODO.md

@@ -6,179 +6,67 @@ 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.
 
-**🏗️ MAJOR ARCHITECTURE REFACTORING (2025-11-03) - COMPLETED ✅**: Successfully completed comprehensive JavaScript refactoring using Test-Driven Development methodology.
+### Extract Capability-Capability from Issue-Facade (Paused)
 
-**PROBLEMS SOLVED**:
-1. ✅ **Monolithic Architecture**: Extracted 5,188-line `editor.js` into 4 modular components
-2. ✅ **Server-Side Debug Generation**: Implemented pure client-side DebugPanel component
-3. ✅ **Architectural Boundary Violations**: Clean separation with no Python code modifications
-4. ✅ **Tight Coupling**: All components independently testable with event-driven communication
-5. ✅ **Generic Editor Compromise**: Debug system now purely client-side and component-based
+**Context:** Issue-facade currently provides two capabilities:
+1. **issue-tracking** (explicit in CAPABILITY-issue-tracking.yaml) - Issue management across platforms
+2. **capability-capability** (implicit) - Patterns and tools for creating/managing capabilities
 
-**SOLUTION IMPLEMENTED**: Modular JavaScript Architecture with complete component separation and TDD validation.
+The **capability-capability** includes:
+- Feedback pattern (feedback/ directory, .capability/feedback CLI tool, documentation)
+- Detachment facility (.capability/detach script for clean capability removal)
+- Integration pattern (.capability/integrate.sh for project integration)
+- CAPABILITY-*.yaml specification format
+- ReusableCapabilitiesArchitecture.md (complete specification)
+- Directory conventions (_family/implementation, visible/hidden patterns)
 
-**📊 PREVIOUS STATUS (2025-11-02)**: Systematic JavaScript functionality recovery using TDD methodology had made excellent progress. **5 major features** were successfully implemented and tested:
+**Goal:** Extract capability-capability to separate `reusable-capability` repository so it can be used by any capability in the markitect ecosystem.
 
-1. **Advanced EditState Management** ✅ - Implemented enum-based state tracking with pending changes preservation
-2. **Keyboard Shortcuts** ✅ - Added Ctrl+Enter (accept) and Escape (cancel) functionality
-3. **Section Splitting** ✅ - Restored dynamic heading detection with automatic section reorganization
-4. **Real-time Status Tracking** ✅ - Implemented periodic updates with visual status panel (2-second intervals)
-5. **Intelligent Filename Generation** ✅ - Added 4-method fallback system (options→title→URL→heading→timestamp)
+**Approach:** Step-by-step extraction, starting with specification.
 
-All implementations include comprehensive TDD test suites and are fully integrated into the existing codebase. The recovery approach has proven highly effective for restoring sophisticated lost functionality.
+#### Phase 1: Specification & Planning (Current)
 
-## 🏗️ JAVASCRIPT ARCHITECTURE REFACTORING - COMPLETED ✅
+- [ ] Create CAPABILITY-capability.yaml in issue-facade to explicitly declare the implicit capability
+- [ ] Define what belongs to capability-capability family vs issue-tracking family
+- [ ] Document the capability-capability API surface (what tools/patterns it provides)
+- [ ] Identify all files/directories to extract
+- [ ] Plan extraction strategy (copy vs move, how to maintain during transition)
 
-### **Phase 1: Preparation & Backup (CRITICAL) - ✅ COMPLETED**
-* ✅ Updated TODO.md with comprehensive refactoring plan
-* ✅ Created modular directory structure `markitect/static/js/`
-* ✅ Set up component template files with proper exports/imports
-* ✅ Implemented TDD test framework for safe refactoring
+#### Phase 2: Repository Creation
 
-### **Phase 2: Core System Extraction (HIGH) - ✅ COMPLETED**
-* ✅ Extracted SectionManager to `core/section-manager.js` (490 lines)
-* ✅ Integrated EventSystem into SectionManager with pub/sub pattern
-* ✅ Created comprehensive section state management with EditState enum
+- [ ] Create reusable-capability repository structure
+- [ ] Extract ReusableCapabilitiesArchitecture.md to new repo
+- [ ] Extract feedback pattern (directory structure, CLI tool, README)
+- [ ] Extract detachment facility (.capability/detach)
+- [ ] Extract integration scripts (.capability/integrate.sh, integration-checklist.md)
+- [ ] Create CAPABILITY-capability.yaml in new repo (canonical version)
+- [ ] Add README.md for reusable-capability repo
 
-### **Phase 3: Component Separation (HIGH) - ✅ COMPLETED**
-* ✅ Document Controls → `components/document-controls.js` (200 lines)
-* ✅ DOMRenderer (includes status functionality) → `components/dom-renderer.js` (540 lines)
-* ✅ Debug Panel → `components/debug-panel.js` (150 lines, pure client-side)
-* ✅ Floating Menu → integrated into DOMRenderer component
-* ✅ Text/Image Editors → integrated into DOMRenderer component
+#### Phase 3: Integration & Testing
 
-### **Phase 4: Testing Infrastructure (MEDIUM) - ✅ COMPLETED**
-* ✅ Standalone TDD test runner (`RefactorTestRunner`) that doesn't require md-render
-* ✅ Component unit tests for all individual functionality
-* ✅ Integration tests for component interaction
-* ✅ Full system integration tests for complete workflow validation
+- [ ] Update issue-facade to depend on reusable-capability (as integrated capability)
+- [ ] Integrate reusable-capability into issue-facade using _capability/reusable-capability pattern
+- [ ] Test that issue-facade still works with extracted capability
+- [ ] Update issue-facade documentation to reference both capabilities it provides/uses
+- [ ] Verify feedback system still works
+- [ ] Verify detachment still works
 
-### **Phase 5: Integration & Cleanup (MEDIUM) - ✅ COMPLETED**
-* ✅ All components work together with preserved functionality
-* ✅ Monolithic editor.js functionality fully distributed
-* ✅ Python code completely unchanged - zero md-render modifications
-* ✅ All functionality validated through comprehensive test suite (31 tests passing)
+#### Phase 4: Dogfooding & Validation
 
-### **Directory Structure Implemented:**
-```
-markitect/static/js/
-├── core/
-│   └── section-manager.js      # ✅ Section state management with EventSystem (490 lines)
-├── components/
-│   ├── document-controls.js    # ✅ Document controls panel (200 lines)
-│   ├── dom-renderer.js         # ✅ DOM rendering, FloatingMenu, editors (540 lines)
-│   └── debug-panel.js          # ✅ Debug panel (150 lines, pure client-side)
-└── tests/
-    ├── refactor-test-runner.js     # ✅ TDD test framework
-    ├── test-component-integration.js      # ✅ Component integration tests
-    ├── test-full-integration.js           # ✅ Full system tests
-    ├── test-section-manager-extraction.js # ✅ SectionManager tests
-    ├── test-extracted-section-manager.js  # ✅ SectionManager TDD tests
-    ├── test-domrenderer-extraction.js     # ✅ DOMRenderer extraction tests
-    ├── test-extracted-domrenderer.js      # ✅ DOMRenderer TDD tests
-    ├── test-debugpanel-extraction.js      # ✅ DebugPanel extraction tests
-    ├── test-debugpanel-integration.js     # ✅ DebugPanel integration tests
-    └── test-documentcontrols-extraction.js # ✅ DocumentControls tests
-```
+- [ ] Choose another markitect capability for dogfooding
+- [ ] Integrate reusable-capability into that capability
+- [ ] Add feedback system to new capability
+- [ ] Add detachment facility to new capability
+- [ ] Document learnings and refine reusable-capability based on real-world usage
+- [ ] Update ReusableCapabilitiesArchitecture.md with insights
 
-### **REFACTORING RESULTS SUMMARY:**
-- **Lines Extracted**: 1,380 lines from monolithic 5,188-line editor.js
-- **Components Created**: 4 modular, independently testable components
-- **Tests Created**: 11 comprehensive test files with 31 passing tests
-- **Architecture**: Event-driven, pub/sub communication between components
-- **Functionality**: 100% preserved with zero regression
-- **Performance**: Improved modularity enables better maintainability and testing
-- **Python Code**: Zero modifications - clean architectural separation achieved
+**Current Step:** Phase 1, Task 1 - Create CAPABILITY-capability.yaml
 
-### **PREVIOUS COMPLETED FEATURES (Now successfully refactored):**
-* **Successfully Refactored:**
-    * ✅ Advanced state management with EditState enum and pending changes (CRITICAL) - REFACTORED INTO SectionManager
-    * ✅ Keyboard shortcuts (Ctrl+Enter accept, Escape cancel) (CRITICAL) - REFACTORED INTO DOMRenderer
-    * ✅ Section splitting functionality for dynamic heading detection (HIGH) - REFACTORED INTO SectionManager
-    * ✅ Real-time status tracking with periodic updates (HIGH) - REFACTORED INTO DocumentControls
-    * ✅ Intelligent save filename generation with 4-method fallback (MEDIUM) - PRESERVED IN MONOLITH
-    * ✅ Professional message system with color-coded positioning (MEDIUM) - REFACTORED INTO DebugPanel
-    * ✅ Multiple concurrent editing sessions support (MEDIUM) - REFACTORED INTO DOMRenderer
-    * ✅ Enhanced DOM event system with 6 event types (LOW) - REFACTORED INTO DOMRenderer
-    * ✅ Automatic section type detection (heading, code, list, etc) (LOW) - REFACTORED INTO SectionManager
-    * ✅ Sophisticated section ID generation with hash-based algorithm (LOW) - REFACTORED INTO SectionManager
-
-* **Successfully Implemented:**
-    * ✅ Comprehensive status reporting dialog with detailed stats (HIGH) - IMPLEMENTED IN DocumentControls
-    * ✅ Floating global control panel with professional styling (MEDIUM) - IMPLEMENTED IN DocumentControls
-    * ✅ Enhanced setupSectionElement with comprehensive styling (LOW) - IMPLEMENTED IN DOMRenderer
-
-* **Core Methods Successfully Refactored:**
-    * ✅ stopEditing method with state preservation (CRITICAL) - REFACTORED INTO SectionManager
-    * ✅ getAllSections method for section collection management (MEDIUM) - REFACTORED INTO SectionManager
-    * ✅ hasChanges detection for unsaved modifications (HIGH) - REFACTORED INTO SectionManager
-    * ✅ updateGlobalStatus method with 2-second interval updates (MEDIUM) - REFACTORED INTO DocumentControls
-    * ✅ handleSectionSplit for dynamic section reorganization (LOW) - REFACTORED INTO SectionManager
-    * ✅ checkForSectionSplits automatic heading detection (LOW) - REFACTORED INTO SectionManager
-
-* **To Remove:**
-    * None currently identified
-
-
-***
-
-## Completed Tasks
-
-**JavaScript Architecture Refactoring - COMPLETED ✅ (2025-11-03)**:
-- ✅ Successfully extracted monolithic 5,188-line editor.js into 4 modular components using TDD methodology
-- ✅ Created SectionManager component (490 lines) handling section state management and event system
-- ✅ Created DOMRenderer component (540 lines) handling DOM interactions, rendering, and editing workflows
-- ✅ Created DebugPanel component (150 lines) providing pure client-side debug message management
-- ✅ Created DocumentControls component (200 lines) managing floating control panel and document actions
-- ✅ Implemented comprehensive TDD test framework with 11 test files and 31 passing tests
-- ✅ Achieved 100% functionality preservation with zero regression through rigorous testing
-- ✅ Established event-driven architecture with pub/sub communication between components
-- ✅ Maintained complete separation from Python code - zero md-render modifications required
-- ✅ Created modular directory structure enabling independent component development and testing
-
-**Architecture Improvements Achieved**:
-- Clean separation of concerns with single-responsibility components
-- Event-driven communication reducing tight coupling
-- Independent component testing enabling confident refactoring
-- Scalable structure supporting future feature development
-- Client-side debug system eliminating server-side debug generation issues
-- Modular design allowing selective component updates without affecting others
-
-**Asset Shipping for md-render - COMPLETED ✅**:
-- ✅ Implemented automatic asset copying when rendering markdown to different output directories
-- ✅ Added asset discovery functionality parsing markdown for image/link references
-- ✅ Implemented timestamp-based asset copying (only copy if source newer than destination)
-- ✅ Added `--ship-assets` and `--no-ship-assets` CLI flags for explicit control
-- ✅ Added `MARKITECT_OUTPUT_DIR` environment variable support for default output directory
-- ✅ Smart defaults: assets ship automatically when output is directory, disabled for specific files
-- ✅ Preserved relative path structure in output directory maintaining markdown link compatibility
-- ✅ Graceful handling of missing assets with warning messages
-- ✅ Full backward compatibility with existing md-render workflows
-- ✅ Comprehensive TDD test suite covering all functionality and edge cases
-
-**Feature Capabilities**:
-- Environment variable priority: CLI `--output` > `MARKITECT_OUTPUT_DIR` > input file directory
-- Automatic asset discovery from standard markdown syntax: `![alt](path)` and `[text](path)`
-- Timestamp-based incremental copying prevents unnecessary file operations
-- Directory structure preservation maintains working relative links in output HTML
-- Support for images, documents, and other asset types referenced in markdown
-
-**CHANGELOG.md Enhancement - COMPLETED ✅**:
-- ✅ Added missing version entries for 0.1.0, 0.2.0, and 0.3.0
-- ✅ Added standard Keep a Changelog header with proper format
-- ✅ Included Unreleased section
-- ✅ Research completed for all historical versions using git log analysis
-- ✅ All entries follow Keep a Changelog categories (Added, Changed, Fixed)
-- ✅ Chronological order maintained with latest versions first
-- ✅ Appropriate release dates included based on git commit timestamps
-
-**Version Details Added**:
-- v0.1.0 (2025-10-15): Development infrastructure, TDD workspace, issue management
-- v0.2.0 (2025-10-20): Advanced Markdown Engine with GraphQL, search, plugins
-- v0.3.0 (2025-10-25): Architectural improvements with kaizen-agentic integration

agents/agent-capability-manager.md

@@ -0,0 +1,210 @@
+# Capability Manager Agent
+
+You are a specialized agent for managing MarkiTect's capability system. You understand the modular architecture where capabilities are self-contained packages in the `capabilities/` directory, each with their own Makefiles, documentation, and functionality.
+
+## Your Role
+
+You are responsible for:
+- **Capability Discovery**: Finding and cataloging all capabilities in the project
+- **Makefile Management**: Creating and maintaining Makefiles for capabilities
+- **Target Delegation**: Ensuring proper target delegation from main Makefile to capabilities
+- **Documentation**: Maintaining capability documentation and help systems
+- **Quality Assurance**: Ensuring capabilities follow the established patterns
+
+## Capability Architecture Understanding
+
+### Directory Structure
+```
+markitect_project/
+├── Makefile                           # Main project Makefile
+├── scripts/
+│   └── capability_discovery.mk       # Auto-discovery and delegation system
+└── capabilities/
+    ├── capability-name/
+    │   ├── Makefile                   # Capability-specific targets
+    │   ├── README.md                  # Capability documentation
+    │   ├── pyproject.toml             # Package configuration
+    │   └── src/capability_name/       # Source code
+    └── ...
+```
+
+### Makefile System
+
+#### Main Makefile Integration
+- Includes `scripts/capability_discovery.mk` for auto-discovery
+- Provides capability management targets:
+  - `capabilities-list` - Show all capabilities
+  - `capabilities-help` - Show help for all capabilities
+  - `capabilities-status` - Show capability status
+  - `capabilities-install` - Install all capabilities
+
+#### Capability Makefile Pattern
+Each capability should have a Makefile with:
+1. **Capability metadata** (name, description)
+2. **Help target** showing available commands
+3. **Core functionality targets** specific to the capability
+4. **Installation/setup targets**
+5. **Testing targets**
+6. **Meta information target** for discovery
+
+#### Target Delegation System
+- Direct delegation: `release-*` targets → `release-management` capability
+- Generic delegation: `capability-name-target` → `capability-name/Makefile:target`
+- Auto-discovery includes all capability Makefiles
+
+### Established Patterns
+
+#### Successful Example: release-management
+```makefile
+# Capability metadata
+CAPABILITY_NAME := release-management
+CAPABILITY_DESCRIPTION := Comprehensive release management for Python projects
+
+# Help target
+.PHONY: help
+help: ## Show release management help
+	@echo "📦 Release Management Capability"
+	# ... help content
+
+# Core targets
+.PHONY: release-status release-build release-publish
+release-status: ## Show current release status
+	release status
+
+# Meta information
+.PHONY: capability-info
+capability-info: ## Show capability information
+	@echo "Name: $(CAPABILITY_NAME)"
+	@echo "Description: $(CAPABILITY_DESCRIPTION)"
+```
+
+#### CLI Integration Pattern
+- Capabilities can provide CLI tools (e.g., `release` command)
+- Makefile targets can delegate to CLI commands
+- CLI availability is checked before execution
+
+## Current Capabilities to Manage
+
+Based on the `capabilities/` directory, you need to manage:
+
+1. **release-management** ✅ - Fully implemented with Makefile
+2. **markitect-content** ❓ - Content parsing capability, needs Makefile
+3. **markitect-utils** ❓ - Utility functions capability, needs Makefile
+4. **issue-facade** ❓ - Issue tracking CLI, needs Makefile
+5. **kaizen-agentic** ✅ - AI agent framework, has Makefile but may need review
+
+## Your Tasks
+
+### 1. Capability Audit
+When asked to audit capabilities:
+- Scan `capabilities/` directory
+- Check each capability for:
+  - README.md existence and quality
+  - pyproject.toml configuration
+  - Makefile existence and completeness
+  - CLI tools or main functionality
+  - Integration with main project
+
+### 2. Makefile Creation
+For capabilities missing Makefiles:
+- Follow the established pattern from `release-management/Makefile`
+- Include appropriate targets based on capability type
+- Ensure proper capability metadata
+- Add help documentation
+- Include installation and testing targets
+
+### 3. Target Analysis
+- Scan main Makefile for orphaned targets that should be in capabilities
+- Identify targets that could benefit from delegation
+- Recommend improvements to capability organization
+
+### 4. Documentation Maintenance
+- Ensure each capability has proper README.md
+- Update capability descriptions and help text
+- Maintain consistency across capability documentation
+
+## Capability Types and Their Typical Targets
+
+### Code/Library Capabilities (markitect-content, markitect-utils)
+```makefile
+# Typical targets
+capability-name-test          # Run tests
+capability-name-install       # Install capability
+capability-name-install-dev   # Install with dev dependencies
+capability-name-build         # Build packages
+capability-name-clean         # Clean build artifacts
+capability-name-lint          # Code linting
+capability-name-format        # Code formatting
+```
+
+### Tool/CLI Capabilities (issue-facade, release-management)
+```makefile
+# Typical targets
+capability-name-status        # Show tool status
+capability-name-help          # Show CLI help
+capability-name-install       # Install tool
+capability-name-config        # Configure tool
+capability-name-test          # Run tests
+```
+
+### Framework Capabilities (kaizen-agentic)
+```makefile
+# Typical targets
+capability-name-setup         # Initial setup
+capability-name-agents-list   # List agents/components
+capability-name-test          # Run tests
+capability-name-build         # Build framework
+capability-name-docs          # Generate documentation
+```
+
+## Quality Standards
+
+### Makefile Requirements
+- ✅ Must have capability metadata (NAME, DESCRIPTION)
+- ✅ Must have help target with clear documentation
+- ✅ Must have capability-info target for discovery
+- ✅ Must check for dependencies/CLI availability
+- ✅ Must follow consistent naming patterns
+- ✅ Must include installation targets
+
+### Documentation Requirements
+- ✅ README.md with clear description
+- ✅ Installation instructions
+- ✅ Usage examples
+- ✅ API documentation where applicable
+- ✅ Integration with main project explained
+
+### Integration Requirements
+- ✅ Proper pyproject.toml configuration
+- ✅ Compatible with capability discovery system
+- ✅ No conflicts with existing targets
+- ✅ Clear dependency management
+
+## Commands You Should Use
+
+When auditing and managing capabilities:
+
+1. **Discovery Commands**:
+   - `make capabilities-list` - See current capabilities
+   - `make capabilities-status` - Check capability health
+   - `find capabilities/ -name "Makefile"` - Find existing Makefiles
+
+2. **Testing Commands**:
+   - `make capabilities-help` - Test help system
+   - `make capability-name-help` - Test specific capability help
+
+3. **File Operations**:
+   - Use Read tool to examine existing Makefiles and documentation
+   - Use Write tool to create new Makefiles
+   - Use Edit tool to update existing files
+
+## Your Approach
+
+When given a task:
+1. **Assess Current State**: Use discovery commands to understand what exists
+2. **Identify Gaps**: Compare what exists vs. what should exist
+3. **Create Missing Components**: Generate Makefiles, documentation, etc.
+4. **Validate Integration**: Test that everything works together
+5. **Document Changes**: Update any necessary documentation
+
+Remember: You're maintaining a sophisticated capability system that should be easy to extend, discover, and use. Every capability should follow the established patterns while being tailored to its specific functionality.

agents/agent-project-assistent.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.

asset_registry.json

@@ -5055,6 +5055,94 @@
       "size": 43,
       "created_at": "2025-10-20T07:21:34.059271",
       "description": null
+    },
+    "d1f2de1aa975f05ac067cb3512059a675aad9acd6e1bcd5dc57e1dd51d00db01": {
+      "path": "/home/worsch/markitect_project/assets/d1/d1f2de1aa975f05ac067cb3512059a675aad9acd6e1bcd5dc57e1dd51d00db01.pdf",
+      "content_hash": "d1f2de1aa975f05ac067cb3512059a675aad9acd6e1bcd5dc57e1dd51d00db01",
+      "mime_type": "application/pdf",
+      "size": 29,
+      "created_at": "2025-11-09T09:25:06.866540",
+      "description": null
+    },
+    "1895a4a5b1a7afcba497477008076e1a9b70442342092d5ce43f7ab447b30873": {
+      "path": "/home/worsch/markitect_project/assets/18/1895a4a5b1a7afcba497477008076e1a9b70442342092d5ce43f7ab447b30873.svg",
+      "content_hash": "1895a4a5b1a7afcba497477008076e1a9b70442342092d5ce43f7ab447b30873",
+      "mime_type": "image/svg+xml",
+      "size": 25,
+      "created_at": "2025-11-09T09:25:06.893302",
+      "description": null
+    },
+    "f45288fe7b30287abefccd6e96eafa2413c2f73671c433a9fd17f96876dcba68": {
+      "path": "/home/worsch/markitect_project/assets/f4/f45288fe7b30287abefccd6e96eafa2413c2f73671c433a9fd17f96876dcba68.png",
+      "content_hash": "f45288fe7b30287abefccd6e96eafa2413c2f73671c433a9fd17f96876dcba68",
+      "mime_type": "image/png",
+      "size": 28,
+      "created_at": "2025-11-09T09:25:06.917300",
+      "description": null
+    },
+    "61cb7a679ea77d0765e7f2285b080add305d096a795abc48e82a7cd8d915d9d3": {
+      "path": "/home/worsch/markitect_project/assets/61/61cb7a679ea77d0765e7f2285b080add305d096a795abc48e82a7cd8d915d9d3.jpg",
+      "content_hash": "61cb7a679ea77d0765e7f2285b080add305d096a795abc48e82a7cd8d915d9d3",
+      "mime_type": "image/jpeg",
+      "size": 26,
+      "created_at": "2025-11-09T09:25:06.939018",
+      "description": null
+    },
+    "33ed8dd1f8e470138f016e1a2641d38ccbc1c1cfb10ffdac59ef309974748c6d": {
+      "path": "/home/worsch/markitect_project/assets/33/33ed8dd1f8e470138f016e1a2641d38ccbc1c1cfb10ffdac59ef309974748c6d.png",
+      "content_hash": "33ed8dd1f8e470138f016e1a2641d38ccbc1c1cfb10ffdac59ef309974748c6d",
+      "mime_type": "image/png",
+      "size": 27,
+      "created_at": "2025-11-09T09:25:06.959757",
+      "description": null
+    },
+    "b509163964e822915ea7e822759ecae39dd696626e70b74b96de6ac7396415d0": {
+      "path": "/home/worsch/markitect_project/assets/b5/b509163964e822915ea7e822759ecae39dd696626e70b74b96de6ac7396415d0.png",
+      "content_hash": "b509163964e822915ea7e822759ecae39dd696626e70b74b96de6ac7396415d0",
+      "mime_type": "image/png",
+      "size": 14,
+      "created_at": "2025-11-09T09:25:07.012411",
+      "description": null
+    },
+    "e4d8e7de1bda3f19dd16c984ec045bed1a60fe69989ff48a2875cf81dfd56bb6": {
+      "path": "/home/worsch/markitect_project/assets/e4/e4d8e7de1bda3f19dd16c984ec045bed1a60fe69989ff48a2875cf81dfd56bb6.pdf",
+      "content_hash": "e4d8e7de1bda3f19dd16c984ec045bed1a60fe69989ff48a2875cf81dfd56bb6",
+      "mime_type": "application/pdf",
+      "size": 33,
+      "created_at": "2025-11-09T09:25:07.219675",
+      "description": null
+    },
+    "6e64079b752375a2e3ae5d6d67af3d2569b284997536c5fa8bd01af2baafdc08": {
+      "path": "/home/worsch/markitect_project/assets/6e/6e64079b752375a2e3ae5d6d67af3d2569b284997536c5fa8bd01af2baafdc08.svg",
+      "content_hash": "6e64079b752375a2e3ae5d6d67af3d2569b284997536c5fa8bd01af2baafdc08",
+      "mime_type": "image/svg+xml",
+      "size": 29,
+      "created_at": "2025-11-09T09:25:07.243001",
+      "description": null
+    },
+    "33794900aef1bda0b9bbb8f24f26e6181507169bb1979a8502503ae68962a9aa": {
+      "path": "/home/worsch/markitect_project/assets/33/33794900aef1bda0b9bbb8f24f26e6181507169bb1979a8502503ae68962a9aa.png",
+      "content_hash": "33794900aef1bda0b9bbb8f24f26e6181507169bb1979a8502503ae68962a9aa",
+      "mime_type": "image/png",
+      "size": 32,
+      "created_at": "2025-11-09T09:25:07.265421",
+      "description": null
+    },
+    "9e90160cc46e32c3790e38e55bdc3bbd8d61f85036191b6693d02e53c06b1e4d": {
+      "path": "/home/worsch/markitect_project/assets/9e/9e90160cc46e32c3790e38e55bdc3bbd8d61f85036191b6693d02e53c06b1e4d.jpg",
+      "content_hash": "9e90160cc46e32c3790e38e55bdc3bbd8d61f85036191b6693d02e53c06b1e4d",
+      "mime_type": "image/jpeg",
+      "size": 30,
+      "created_at": "2025-11-09T09:25:07.286159",
+      "description": null
+    },
+    "345fe884e0f85e1d08e893f4c977b8e7437542126b6be90d86e8b8f68bba686f": {
+      "path": "/home/worsch/markitect_project/assets/34/345fe884e0f85e1d08e893f4c977b8e7437542126b6be90d86e8b8f68bba686f.png",
+      "content_hash": "345fe884e0f85e1d08e893f4c977b8e7437542126b6be90d86e8b8f68bba686f",
+      "mime_type": "image/png",
+      "size": 31,
+      "created_at": "2025-11-09T09:25:07.306652",
+      "description": null
     }
   }
 }

assets/18/1895a4a5b1a7afcba497477008076e1a9b70442342092d5ce43f7ab447b30873.svg

@@ -0,0 +1 @@
+mock content for icon.svg

assets/33/33794900aef1bda0b9bbb8f24f26e6181507169bb1979a8502503ae68962a9aa.png

@@ -0,0 +1 @@
+modified content for diagram.png

assets/33/33ed8dd1f8e470138f016e1a2641d38ccbc1c1cfb10ffdac59ef309974748c6d.png

@@ -0,0 +1 @@
+mock content for image1.png

assets/34/345fe884e0f85e1d08e893f4c977b8e7437542126b6be90d86e8b8f68bba686f.png

@@ -0,0 +1 @@
+modified content for image1.png

assets/61/61cb7a679ea77d0765e7f2285b080add305d096a795abc48e82a7cd8d915d9d3.jpg

@@ -0,0 +1 @@
+mock content for photo.jpg

assets/6e/6e64079b752375a2e3ae5d6d67af3d2569b284997536c5fa8bd01af2baafdc08.svg

@@ -0,0 +1 @@
+modified content for icon.svg

assets/9e/9e90160cc46e32c3790e38e55bdc3bbd8d61f85036191b6693d02e53c06b1e4d.jpg

@@ -0,0 +1 @@
+modified content for photo.jpg

assets/b5/b509163964e822915ea7e822759ecae39dd696626e70b74b96de6ac7396415d0.png

@@ -0,0 +1 @@
+nested content

assets/d1/d1f2de1aa975f05ac067cb3512059a675aad9acd6e1bcd5dc57e1dd51d00db01.pdf

@@ -0,0 +1 @@
+mock content for document.pdf

assets/e4/e4d8e7de1bda3f19dd16c984ec045bed1a60fe69989ff48a2875cf81dfd56bb6.pdf

@@ -0,0 +1 @@
+modified content for document.pdf

assets/f4/f45288fe7b30287abefccd6e96eafa2413c2f73671c433a9fd17f96876dcba68.png

@@ -0,0 +1 @@
+mock content for diagram.png

capabilities/DETACHED-issue-facade.yaml

@@ -0,0 +1,51 @@
+# Detachment Manifest
+# This file records the removal of the issue-facade capability
+# Use this information to re-integrate with updated architecture
+
+detachment:
+  timestamp: 2025-12-17T21:23:14Z
+  capability_name: issue-facade
+  capability_family: issue-tracking
+  integration_pattern: capabilities-directory
+  original_location: /home/worsch/markitect_project/capabilities/issue-facade
+
+capability_metadata:
+  spec_file: CAPABILITY-issue-tracking.yaml
+  version: unknown
+  implementation: unknown
+  maturity: unknown
+
+integration_details:
+  parent_project: capabilities
+  parent_path: /home/worsch/markitect_project/capabilities
+
+re_integration_guide: |
+  To re-integrate this capability using the new architecture:
+
+  # Option 1: Git submodule (recommended)
+  cd /home/worsch/markitect_project/capabilities
+  git submodule add <repo-url> _issue-facade
+  pip install -e _issue-facade/
+
+  # Option 2: Clone directly
+  cd /home/worsch/markitect_project/capabilities
+  git clone <repo-url> _issue-facade
+  pip install -e _issue-facade/
+
+  # Option 3: Copy into project
+  cd /home/worsch/markitect_project/capabilities
+  cp -r /path/to/issue-facade _issue-facade
+  pip install -e _issue-facade/
+
+  Note: Use underscore prefix (_issue-facade) per ReusableCapabilitiesArchitecture
+
+notes:
+  - The original integration used pattern: capabilities-directory
+  - New architecture recommends: underscore-prefix at repo root
+  - See ReusableCapabilitiesArchitecture.md for details
+
+repository_info:
+  # Fill in if re-integrating from git
+  git_url: "http://92.205.130.254:32166/coulomb/issue-facade.git"  # e.g., https://github.com/markitect/issue-facade
+  git_branch: "main"  # e.g., main
+  git_commit: "35daa514e59788250847cd706c43ea78f24c5c1d"  # Optional: specific commit to use

capabilities/markitect-content/Makefile

@@ -0,0 +1,114 @@
+# MarkiTect Content Capability Makefile
+# Content parsing and statistics for MarkdownMatters documents
+
+# Capability metadata
+CAPABILITY_NAME := markitect-content
+CAPABILITY_DESCRIPTION := Content parsing and statistics for MarkdownMatters documents
+
+# Default target
+.PHONY: help
+help: ## Show content capability help
+	@echo "📄 MarkiTect Content Capability"
+	@echo "================================"
+	@echo ""
+	@echo "Content Operations:"
+	@echo "  content-get FILE=file.md         Extract content without frontmatter/tailmatter"
+	@echo "  content-stats FILE=file.md       Calculate content statistics (word count, etc.)"
+	@echo "  content-stats-json FILE=file.md  Get content statistics in JSON format"
+	@echo ""
+	@echo "Development & Setup:"
+	@echo "  content-install                  Install content capability"
+	@echo "  content-install-dev              Install with development dependencies"
+	@echo "  content-test                     Run content capability tests"
+	@echo "  content-test-cov                 Run tests with coverage report"
+	@echo "  content-lint                     Run code quality checks"
+	@echo "  content-clean                    Clean build artifacts"
+
+# Check if markitect command is available (assumes CLI integration)
+MARKITECT_CLI := $(shell command -v markitect 2> /dev/null)
+
+# Content Operations
+.PHONY: content-get
+content-get: ## Extract content without frontmatter and tailmatter (requires FILE=path/to/file.md)
+ifndef FILE
+	@echo "❌ FILE is required. Usage: make content-get FILE=document.md"
+	@exit 1
+endif
+ifndef MARKITECT_CLI
+	@echo "⚠️  markitect CLI not available, trying direct Python execution..."
+	cd capabilities/markitect-content && python -m markitect_content.commands content-get --file "$(FILE)"
+else
+	markitect content-get --file "$(FILE)"
+endif
+
+.PHONY: content-stats
+content-stats: ## Calculate content statistics (requires FILE=path/to/file.md)
+ifndef FILE
+	@echo "❌ FILE is required. Usage: make content-stats FILE=document.md"
+	@exit 1
+endif
+ifndef MARKITECT_CLI
+	@echo "⚠️  markitect CLI not available, trying direct Python execution..."
+	cd capabilities/markitect-content && python -m markitect_content.commands content-stats --file "$(FILE)" --format text
+else
+	markitect content-stats --file "$(FILE)" --format text
+endif
+
+.PHONY: content-stats-json
+content-stats-json: ## Get content statistics in JSON format (requires FILE=path/to/file.md)
+ifndef FILE
+	@echo "❌ FILE is required. Usage: make content-stats-json FILE=document.md"
+	@exit 1
+endif
+ifndef MARKITECT_CLI
+	@echo "⚠️  markitect CLI not available, trying direct Python execution..."
+	cd capabilities/markitect-content && python -m markitect_content.commands content-stats --file "$(FILE)" --format json
+else
+	markitect content-stats --file "$(FILE)" --format json
+endif
+
+# Development and Setup
+.PHONY: content-install
+content-install: ## Install content capability
+	pip install -e capabilities/markitect-content/
+
+.PHONY: content-install-dev
+content-install-dev: ## Install content capability with development dependencies
+	pip install -e "capabilities/markitect-content/[dev]"
+
+.PHONY: content-test
+content-test: ## Run content capability tests
+	cd capabilities/markitect-content && pytest tests/
+
+.PHONY: content-test-cov
+content-test-cov: ## Run tests with coverage report
+	cd capabilities/markitect-content && pytest tests/ --cov=markitect_content --cov-report=html --cov-report=term
+
+.PHONY: content-lint
+content-lint: ## Run code quality checks
+	@echo "🔍 Running code quality checks for markitect-content..."
+	cd capabilities/markitect-content && python -m py_compile src/markitect_content/*.py
+	@echo "✅ Code quality checks passed"
+
+.PHONY: content-clean
+content-clean: ## Clean build artifacts
+	cd capabilities/markitect-content && rm -rf build/ dist/ *.egg-info/ __pycache__/ .pytest_cache/ htmlcov/ .coverage
+	find capabilities/markitect-content -name "*.pyc" -delete
+	find capabilities/markitect-content -name "__pycache__" -type d -exec rm -rf {} + 2>/dev/null || true
+
+# Library Functions (for other capabilities to use)
+.PHONY: content-api-test
+content-api-test: ## Test content parsing API functionality
+	@echo "🧪 Testing content parsing API..."
+	cd capabilities/markitect-content && python -c "from src.markitect_content import ContentParser; parser = ContentParser(); content = parser.extract_content('---\\ntitle: Test\\n---\\n\\n# Hello\\n\\nContent here\\n\\n\`\`\`yaml tailmatter\\nfoo: bar\\n\`\`\`'); stats = parser.calculate_stats(content); print(f'Content: {repr(content)}'); print(f'Stats: {stats.to_dict()}')"
+
+# Meta information for capability discovery
+.PHONY: capability-info
+capability-info: ## Show capability information
+	@echo "Name: $(CAPABILITY_NAME)"
+	@echo "Description: $(CAPABILITY_DESCRIPTION)"
+	@echo "Type: Library capability with CLI commands"
+	@echo "Main functions: Content extraction, statistics calculation"
+	@echo "CLI commands: content-get, content-stats"
+	@echo "Targets:"
+	@$(MAKE) --no-print-directory help | grep "^  " | sed 's/^  /    /'

capabilities/markitect-utils/Makefile

@@ -0,0 +1,131 @@
+# MarkiTect Utils Capability Makefile
+# Utility functions library for the MarkiTect ecosystem
+
+# Capability metadata
+CAPABILITY_NAME := markitect-utils
+CAPABILITY_DESCRIPTION := Common utility functions for the MarkiTect ecosystem
+
+# Default target
+.PHONY: help
+help: ## Show utils capability help
+	@echo "🛠️  MarkiTect Utils Capability"
+	@echo "==============================="
+	@echo ""
+	@echo "Library Testing:"
+	@echo "  utils-test-string            Test string utility functions"
+	@echo "  utils-test-file              Test file utility functions"
+	@echo "  utils-test-validation        Test validation utility functions"
+	@echo "  utils-test-api               Test complete API functionality"
+	@echo ""
+	@echo "Development & Setup:"
+	@echo "  utils-install                Install utils capability"
+	@echo "  utils-install-dev            Install with development dependencies"
+	@echo "  utils-test                   Run utils capability tests"
+	@echo "  utils-test-cov               Run tests with coverage report"
+	@echo "  utils-lint                   Run code quality checks"
+	@echo "  utils-clean                  Clean build artifacts"
+	@echo ""
+	@echo "Quality & Compliance:"
+	@echo "  utils-validate-paradigm      Validate ComposableRepositoryParadigm compliance"
+	@echo "  utils-check-dependencies     Verify zero external dependencies"
+
+# Development and Setup
+.PHONY: utils-install
+utils-install: ## Install utils capability
+	pip install -e capabilities/markitect-utils/
+
+.PHONY: utils-install-dev
+utils-install-dev: ## Install utils capability with development dependencies
+	pip install -e "capabilities/markitect-utils/[dev]"
+
+.PHONY: utils-test
+utils-test: ## Run utils capability tests
+	cd capabilities/markitect-utils && pytest tests/
+
+.PHONY: utils-test-cov
+utils-test-cov: ## Run tests with coverage report
+	cd capabilities/markitect-utils && pytest tests/ --cov=markitect_utils --cov-report=html --cov-report=term
+
+.PHONY: utils-lint
+utils-lint: ## Run code quality checks
+	@echo "🔍 Running code quality checks for markitect-utils..."
+	cd capabilities/markitect-utils && python -m py_compile src/markitect_utils/*.py
+	@echo "✅ Code quality checks passed"
+
+.PHONY: utils-clean
+utils-clean: ## Clean build artifacts
+	cd capabilities/markitect-utils && rm -rf build/ dist/ *.egg-info/ __pycache__/ .pytest_cache/ htmlcov/ .coverage
+	find capabilities/markitect-utils -name "*.pyc" -delete
+	find capabilities/markitect-utils -name "__pycache__" -type d -exec rm -rf {} + 2>/dev/null || true
+
+# Library Function Testing
+.PHONY: utils-test-string
+utils-test-string: ## Test string utility functions
+	@echo "🧪 Testing string utilities..."
+	cd capabilities/markitect-utils && python -c "from src.markitect_utils import slugify, truncate, camel_to_snake, snake_to_camel, strip_ansi_codes; print('slugify(\"Hello World!\"):', slugify('Hello World!')); print('truncate(\"This is a long string\", 10):', truncate('This is a long string', 10)); print('camel_to_snake(\"camelCase\"):', camel_to_snake('camelCase')); print('snake_to_camel(\"snake_case\"):', snake_to_camel('snake_case')); print('strip_ansi_codes(\"\\\\033[31mRed\\\\033[0m\"):', strip_ansi_codes('\\033[31mRed\\033[0m')); print('✅ String utilities working')"
+
+.PHONY: utils-test-file
+utils-test-file: ## Test file utility functions
+	@echo "🧪 Testing file utilities..."
+	cd capabilities/markitect-utils && python -c "from src.markitect_utils import safe_filename, ensure_extension, normalize_path; import tempfile, os; print('safe_filename(\"file<name>.txt\"):', safe_filename('file<name>.txt')); print('ensure_extension(\"document\", \".md\"):', ensure_extension('document', '.md')); print('normalize_path(\"./test/../file.txt\"):', normalize_path('./test/../file.txt')); print('✅ File utilities working')"
+
+.PHONY: utils-test-validation
+utils-test-validation: ## Test validation utility functions
+	@echo "🧪 Testing validation utilities..."
+	cd capabilities/markitect-utils && python -c "from src.markitect_utils import is_valid_email, is_valid_url, is_valid_semver, validate_required_fields; print('is_valid_email(\"user@example.com\"):', is_valid_email('user@example.com')); print('is_valid_url(\"https://example.com\"):', is_valid_url('https://example.com')); print('is_valid_semver(\"1.0.0\"):', is_valid_semver('1.0.0')); result = validate_required_fields({'name': 'John', 'email': '', 'age': 30}, ['name', 'email', 'phone']); print('validate_required_fields test:', result); print('✅ Validation utilities working')"
+
+.PHONY: utils-test-api
+utils-test-api: ## Test complete API functionality
+	@echo "🧪 Testing complete utils API..."
+	@$(MAKE) --no-print-directory utils-test-string
+	@$(MAKE) --no-print-directory utils-test-file
+	@$(MAKE) --no-print-directory utils-test-validation
+	@echo "🎉 All utility functions tested successfully!"
+
+# Quality & Compliance
+.PHONY: utils-validate-paradigm
+utils-validate-paradigm: ## Validate ComposableRepositoryParadigm compliance
+	@echo "🏛️  Validating ComposableRepositoryParadigm compliance..."
+	@echo "✅ Checking src layout structure..."
+	test -d capabilities/markitect-utils/src/markitect_utils
+	@echo "✅ Checking pyproject.toml exists..."
+	test -f capabilities/markitect-utils/pyproject.toml
+	@echo "✅ Checking README.md exists..."
+	test -f capabilities/markitect-utils/README.md
+	@echo "✅ Checking tests directory..."
+	test -d capabilities/markitect-utils/tests
+	@echo "✅ Verifying independent configuration..."
+	cd capabilities/markitect-utils && python -c "import tomllib; f=open('pyproject.toml','rb'); data=tomllib.load(f); assert data['project']['name']=='markitect-utils'; print('✅ Independent pyproject.toml configuration verified')"
+	@echo "🎉 ComposableRepositoryParadigm compliance validated!"
+
+.PHONY: utils-check-dependencies
+utils-check-dependencies: ## Verify zero external dependencies
+	@echo "📦 Checking dependency compliance..."
+	cd capabilities/markitect-utils && python -c "import tomllib; f=open('pyproject.toml','rb'); data=tomllib.load(f); deps=data.get('project',{}).get('dependencies',[]); print(f'❌ Found external dependencies: {deps}') if deps else print('✅ Zero external dependencies confirmed - paradigm compliant!'); exit(1) if deps else None"
+
+# Demonstration Functions
+.PHONY: utils-demo
+utils-demo: ## Demonstrate utility functions with examples
+	@echo "🎬 MarkiTect Utils Capability Demonstration"
+	@echo "==========================================="
+	@echo ""
+	@echo "String Utilities:"
+	@$(MAKE) --no-print-directory utils-test-string
+	@echo ""
+	@echo "File Utilities:"
+	@$(MAKE) --no-print-directory utils-test-file
+	@echo ""
+	@echo "Validation Utilities:"
+	@$(MAKE) --no-print-directory utils-test-validation
+
+# Meta information for capability discovery
+.PHONY: capability-info
+capability-info: ## Show capability information
+	@echo "Name: $(CAPABILITY_NAME)"
+	@echo "Description: $(CAPABILITY_DESCRIPTION)"
+	@echo "Type: Pure library capability (zero external dependencies)"
+	@echo "Main modules: string_utils, file_utils, validation_utils"
+	@echo "Paradigm role: Reference implementation for ComposableRepositoryParadigm"
+	@echo "Dependencies: None (Python standard library only)"
+	@echo "Targets:"
+	@$(MAKE) --no-print-directory help | grep "^  " | sed 's/^  /    /'

capabilities/release-management/MIGRATION_PLAN.md

@@ -0,0 +1,398 @@
+# Release Management Capability Migration Plan
+
+This document outlines the step-by-step plan to migrate all version management, packaging, and release publication functionality from the main MarkiTect project into the `release-management` capability.
+
+## 📋 Migration Overview
+
+### Current State
+Version management and release functionality is currently scattered across:
+- `release.py` (main release script)
+- `gitea/` directory (package registry client)
+- `VERSION_MANAGEMENT.md` (documentation)
+- `PACKAGE_PUBLISHING.md` (documentation)
+- Makefile targets (release automation)
+- setuptools-scm configuration in main `pyproject.toml`
+
+### Target State
+All release-related functionality consolidated into:
+- `capabilities/release-management/` (self-contained capability)
+- Main project depends on capability for release operations
+- Makefile includes capability's release targets
+- Clean separation of concerns
+
+## 🚦 Migration Steps
+
+### Phase 1: Create Capability Structure ✅ COMPLETED
+- [x] Create directory structure
+- [x] Create `README.md` with comprehensive documentation
+- [x] Create `pyproject.toml` with full configuration
+- [x] Create main `__init__.py` with API exports
+- [x] Create `release.mk` for Makefile integration
+
+### Phase 2: Move Core Files and Code
+
+#### 2.1 Move Release Script
+**Source:** `release.py` → **Target:** `src/release_management/cli/main.py`
+
+**Steps:**
+1. Copy `release.py` to `src/release_management/cli/main.py`
+2. Refactor into proper CLI module structure
+3. Extract core logic into separate modules:
+   - `SimpleReleaseManager` → `src/release_management/core/manager.py`
+   - Git operations → `src/release_management/git/manager.py`
+   - Package building → `src/release_management/core/builder.py`
+   - Publishing logic → `src/release_management/core/publisher.py`
+
+**Refactoring Plan:**
+```python
+# Current: release.py (monolithic)
+class SimpleReleaseManager:
+    # All functionality in one class
+
+# Target: Modular architecture
+# src/release_management/core/manager.py
+class ReleaseManager:
+    def __init__(self):
+        self.git_manager = GitManager()
+        self.builder = PackageBuilder()
+        self.publisher = PublishManager()
+
+# src/release_management/git/manager.py
+class GitManager:
+    # Git-specific operations
+
+# src/release_management/core/builder.py
+class PackageBuilder:
+    # Package building operations
+
+# src/release_management/core/publisher.py
+class PublishManager:
+    # Publishing and upload operations
+```
+
+#### 2.2 Move Gitea Package Registry
+**Source:** `gitea/` directory → **Target:** `src/release_management/registries/gitea/`
+
+**File Mapping:**
+```
+gitea/config.py          → src/release_management/registries/gitea/config.py
+gitea/exceptions.py      → src/release_management/registries/gitea/exceptions.py
+gitea/package_registry.py → src/release_management/registries/gitea/registry.py
+gitea/__init__.py        → src/release_management/registries/gitea/__init__.py
+```
+
+**Refactoring:**
+1. Create base registry interface: `src/release_management/registries/base.py`
+2. Create registry factory: `src/release_management/registries/factory.py`
+3. Adapt GiteaPackageRegistry to implement base interface
+4. Add PyPI registry implementation for future use
+
+#### 2.3 Move Documentation
+**Source:** Documentation files → **Target:** `docs/` directory
+
+**File Mapping:**
+```
+VERSION_MANAGEMENT.md    → capabilities/release-management/docs/version_management.md
+PACKAGE_PUBLISHING.md    → capabilities/release-management/docs/package_publishing.md
+```
+
+**Updates Required:**
+1. Update paths and references in documentation
+2. Add API reference documentation
+3. Create examples directory with usage samples
+
+### Phase 3: Update Main Project Integration
+
+#### 3.1 Update Main Makefile
+**Target:** `Makefile` in main project
+
+**Changes:**
+1. Include release management Makefile:
+   ```makefile
+   # Add at top of Makefile
+   include capabilities/release-management/release.mk
+   ```
+
+2. Update existing targets to use capability:
+   ```makefile
+   # Old targets
+   release-status:
+       python release.py status
+
+   # New targets (provided by release.mk)
+   release-status:
+       release status
+   ```
+
+3. Remove obsolete targets and replace with capability equivalents
+
+#### 3.2 Update Main pyproject.toml
+**Target:** `pyproject.toml` in main project
+
+**Changes:**
+1. Add release-management as dependency:
+   ```toml
+   [project.dependencies]
+   release-management = {path = "capabilities/release-management", develop = true}
+   ```
+
+2. Keep setuptools-scm configuration:
+   ```toml
+   [tool.setuptools_scm]
+   write_to = "markitect/_version.py"
+   ```
+
+3. Remove release-specific configuration (moved to capability)
+
+#### 3.3 Update Main Project Structure
+**Cleanup Tasks:**
+1. Remove `release.py` from root
+2. Remove `gitea/` directory
+3. Move `VERSION_MANAGEMENT.md` and `PACKAGE_PUBLISHING.md` to capability
+4. Update `.gitignore` if needed
+5. Update documentation references
+
+### Phase 4: Testing and Validation
+
+#### 4.1 Create Capability Tests
+**Target:** `capabilities/release-management/tests/`
+
+**Test Structure:**
+```
+tests/
+├── test_manager.py          # ReleaseManager tests
+├── test_builder.py          # PackageBuilder tests
+├── test_publisher.py        # PublishManager tests
+├── test_git_manager.py      # GitManager tests
+├── test_gitea_registry.py   # GiteaRegistry tests
+├── test_cli.py              # CLI command tests
+├── test_integration.py      # End-to-end tests
+└── fixtures/
+    └── sample_packages/     # Test package artifacts
+```
+
+**Test Coverage Goals:**
+- Unit tests for all core classes
+- Integration tests for registry interactions
+- CLI command tests
+- Mock-based tests for external dependencies
+- Error handling and edge cases
+
+#### 4.2 Validate Migration
+**Verification Steps:**
+1. Install capability: `pip install -e capabilities/release-management/`
+2. Run capability tests: `cd capabilities/release-management && pytest`
+3. Test CLI commands: `release --help`, `release status`
+4. Test Makefile integration: `make release-status`
+5. Perform test release workflow
+6. Verify all existing functionality works
+
+### Phase 5: Documentation and Examples
+
+#### 5.1 Create Examples
+**Target:** `capabilities/release-management/examples/`
+
+**Example Scripts:**
+- `basic_release.py` - Simple release workflow
+- `custom_registry.py` - Adding new registry type
+- `ci_integration.py` - CI/CD pipeline integration
+- `configuration_examples.py` - Various configuration patterns
+
+#### 5.2 Update Documentation
+**Documentation Tasks:**
+1. Update main project README to reference capability
+2. Create API reference documentation
+3. Add troubleshooting guide
+4. Document configuration options
+5. Provide migration guide for other projects
+
+## 🎯 Detailed File Structure After Migration
+
+```
+markitect_project/
+├── capabilities/
+│   └── release-management/
+│       ├── README.md                              ✅ CREATED
+│       ├── pyproject.toml                         ✅ CREATED
+│       ├── release.mk                            ✅ CREATED
+│       ├── MIGRATION_PLAN.md                     ✅ CREATED
+│       ├── src/release_management/
+│       │   ├── __init__.py                       ✅ CREATED
+│       │   ├── _version.py                       # Generated by setuptools-scm
+│       │   ├── core/
+│       │   │   ├── __init__.py
+│       │   │   ├── manager.py                    # ReleaseManager class
+│       │   │   ├── builder.py                    # PackageBuilder class
+│       │   │   └── publisher.py                  # PublishManager class
+│       │   ├── git/
+│       │   │   ├── __init__.py
+│       │   │   └── manager.py                    # GitManager class
+│       │   ├── registries/
+│       │   │   ├── __init__.py
+│       │   │   ├── base.py                       # Registry interface
+│       │   │   ├── factory.py                    # RegistryFactory
+│       │   │   ├── gitea/
+│       │   │   │   ├── __init__.py
+│       │   │   │   ├── config.py                 # From gitea/config.py
+│       │   │   │   ├── exceptions.py             # From gitea/exceptions.py
+│       │   │   │   └── registry.py               # From gitea/package_registry.py
+│       │   │   └── pypi/
+│       │   │       ├── __init__.py
+│       │   │       └── registry.py               # PyPI registry implementation
+│       │   ├── cli/
+│       │   │   ├── __init__.py
+│       │   │   ├── main.py                       # From release.py
+│       │   │   ├── commands.py                   # CLI command implementations
+│       │   │   └── utils.py                      # CLI utilities
+│       │   └── utils/
+│       │       ├── __init__.py
+│       │       ├── version.py                    # Version utilities
+│       │       └── validation.py                # Release validation
+│       ├── tests/
+│       │   ├── __init__.py
+│       │   ├── test_manager.py
+│       │   ├── test_builder.py
+│       │   ├── test_publisher.py
+│       │   ├── test_git_manager.py
+│       │   ├── test_gitea_registry.py
+│       │   ├── test_cli.py
+│       │   └── fixtures/
+│       ├── docs/
+│       │   ├── version_management.md             # From VERSION_MANAGEMENT.md
+│       │   ├── package_publishing.md             # From PACKAGE_PUBLISHING.md
+│       │   ├── api_reference.md
+│       │   └── troubleshooting.md
+│       └── examples/
+│           ├── basic_release.py
+│           ├── custom_registry.py
+│           └── ci_integration.py
+├── Makefile                                      # Updated to include release.mk
+├── pyproject.toml                               # Updated with capability dependency
+└── markitect/
+    └── _version.py                              # Still generated by setuptools-scm
+```
+
+## 📦 Files to Remove After Migration
+
+**Root Directory:**
+- [x] `release.py` (moved to capability CLI)
+- [x] `gitea/` directory (moved to capability registries)
+- [x] `VERSION_MANAGEMENT.md` (moved to capability docs)
+- [x] `PACKAGE_PUBLISHING.md` (moved to capability docs)
+
+**Makefile Targets to Update:**
+- Replace individual release targets with capability imports
+- Keep legacy aliases for backward compatibility
+- Update target documentation
+
+## 🔧 API Design for Capability
+
+### Main API Classes
+
+```python
+# Primary entry point
+from release_management import ReleaseManager
+
+manager = ReleaseManager()
+success = manager.publish_release("1.0.0")
+
+# Component access
+from release_management import PackageBuilder, PublishManager, GitManager
+
+builder = PackageBuilder()
+builder.build_packages()
+
+publisher = PublishManager()
+publisher.upload_packages("gitea")
+
+git = GitManager()
+git.create_tag("v1.0.0")
+
+# Registry access
+from release_management import RegistryFactory
+
+registry = RegistryFactory.create("gitea")
+registry.upload_package("package.whl")
+```
+
+### CLI Interface
+
+```bash
+# Main commands
+release status                    # Show release status
+release validate                  # Validate release state
+release tag --version 1.0.0      # Create git tag
+release build                     # Build packages
+release publish --version 1.0.0  # Complete release workflow
+release upload --registry gitea   # Upload existing packages
+
+# Registry management
+release registry-info --registry gitea
+release registry-list
+```
+
+## 🚀 Benefits After Migration
+
+### For MarkiTect Project
+1. **Cleaner main project**: Release logic separated from core functionality
+2. **Better maintainability**: Clear module boundaries and responsibilities
+3. **Easier testing**: Isolated testing of release functionality
+4. **Reduced complexity**: Main project focuses on core features
+
+### For Release Management Capability
+1. **Reusability**: Can be used in other Python projects
+2. **Independent development**: Own release cycle and versioning
+3. **Comprehensive testing**: Full test coverage for release functionality
+4. **Documentation**: Dedicated documentation and examples
+5. **Extensibility**: Easy to add new registries and features
+
+### For Users/Developers
+1. **Consistent interface**: Same commands across all projects using capability
+2. **Better documentation**: Comprehensive guides and API reference
+3. **More features**: Enhanced functionality and registry support
+4. **Easier contribution**: Clear structure for adding features
+
+## 🎯 Success Criteria
+
+Migration is considered successful when:
+1. ✅ All existing release functionality works through capability
+2. ✅ Main project Makefile targets work unchanged
+3. ✅ CLI commands provide same functionality as current `release.py`
+4. ✅ All tests pass for both capability and main project
+5. ✅ Documentation is complete and accurate
+6. ✅ Examples demonstrate capability usage
+7. ✅ No regression in release workflow functionality
+
+## 🔄 Rollback Plan
+
+If migration issues arise:
+1. **Keep backup**: Current files backed up before migration
+2. **Incremental approach**: Migrate one component at a time
+3. **Parallel operation**: Keep old and new systems running during transition
+4. **Quick revert**: Ability to restore original structure if needed
+
+**Rollback Steps:**
+1. Remove capability dependency from main `pyproject.toml`
+2. Restore backed up files (`release.py`, `gitea/`, docs)
+3. Restore original Makefile targets
+4. Remove capability directory
+5. Test that original functionality works
+
+## 📅 Migration Timeline
+
+**Estimated Duration:** 1-2 weeks for complete migration
+
+**Phase Breakdown:**
+- **Phase 1 (Directory Structure):** ✅ COMPLETED
+- **Phase 2 (Code Migration):** 2-3 days
+- **Phase 3 (Integration):** 1-2 days
+- **Phase 4 (Testing):** 2-3 days
+- **Phase 5 (Documentation):** 1-2 days
+
+**Critical Path:**
+1. Code refactoring and migration
+2. Testing and validation
+3. Documentation updates
+4. Final integration testing
+
+This migration plan ensures a systematic, low-risk transition to the capability-based architecture while maintaining all existing functionality and improving the overall project structure.

capabilities/release-management/Makefile

@@ -0,0 +1,231 @@
+# Release Management Capability Makefile
+# Provides release management targets for any Python project
+
+# Capability metadata
+CAPABILITY_NAME := release-management
+CAPABILITY_DESCRIPTION := Comprehensive release management for Python projects
+
+# Default target
+.PHONY: help
+help: ## Show release management help
+	@echo "📦 Release Management Capability"
+	@echo "================================"
+	@echo ""
+	@echo "Status & Validation:"
+	@echo "  release-status               Show current release status and version information"
+	@echo "  release-validate             Validate repository state for release readiness"
+	@echo "  release-registry-info        Show package registry information and status"
+	@echo ""
+	@echo "Git Tag Management:"
+	@echo "  release-tag VERSION=x.y.z    Create git tag for version"
+	@echo ""
+	@echo "Package Building:"
+	@echo "  release-build                Build release packages using setuptools-scm"
+	@echo "  release-clean                Clean build artifacts and temporary files"
+	@echo ""
+	@echo "Publishing Workflows:"
+	@echo "  release-publish VERSION=x.y.z         Complete release workflow (tag + build)"
+	@echo "  release-publish-gitea VERSION=x.y.z   Complete release + Gitea upload"
+	@echo "  release-publish-pypi VERSION=x.y.z    Complete release + PyPI upload"
+	@echo ""
+	@echo "Upload Existing Packages:"
+	@echo "  release-upload-gitea         Upload existing packages to Gitea registry"
+	@echo "  release-upload-pypi          Upload existing packages to PyPI"
+	@echo "  release-upload-testpypi      Upload existing packages to Test PyPI"
+	@echo ""
+	@echo "Dry Run Options:"
+	@echo "  release-publish-dry-run VERSION=x.y.z  Dry run of release workflow"
+	@echo "  release-upload-dry-run                  Dry run of package upload"
+	@echo ""
+	@echo "Development & Setup:"
+	@echo "  release-management-install          Install release management capability"
+	@echo "  release-management-install-dev      Install with development dependencies"
+	@echo "  release-management-test             Run capability tests"
+	@echo "  release-management-help             Show CLI help"
+
+# Check if release management capability is available
+RELEASE_CLI := $(shell command -v release 2> /dev/null)
+
+# Status and Information
+.PHONY: release-status
+release-status: ## Show current release status and version information
+ifndef RELEASE_CLI
+	@echo "❌ Release management capability not installed"
+	@echo "   Install with: pip install -e capabilities/release-management/"
+	@exit 1
+endif
+	release status
+
+.PHONY: release-validate
+release-validate: ## Validate repository state for release readiness
+ifndef RELEASE_CLI
+	@echo "❌ Release management capability not installed"
+	@exit 1
+endif
+	release validate
+
+.PHONY: release-registry-info
+release-registry-info: ## Show package registry information and status
+ifndef RELEASE_CLI
+	@echo "❌ Release management capability not installed"
+	@exit 1
+endif
+	release registry-info
+
+# Git Tag Management
+.PHONY: release-tag
+release-tag: ## Create git tag for version (requires VERSION=x.y.z)
+ifndef VERSION
+	@echo "❌ VERSION is required. Usage: make release-tag VERSION=1.0.0"
+	@exit 1
+endif
+ifndef RELEASE_CLI
+	@echo "❌ Release management capability not installed"
+	@exit 1
+endif
+	release tag --version $(VERSION)
+
+# Package Building
+.PHONY: release-build
+release-build: ## Build release packages using setuptools-scm
+ifndef RELEASE_CLI
+	@echo "❌ Release management capability not installed"
+	@exit 1
+endif
+	release build
+
+.PHONY: release-clean
+release-clean: ## Clean build artifacts and temporary files
+ifndef RELEASE_CLI
+	@echo "❌ Release management capability not installed"
+	@exit 1
+endif
+	release clean
+
+# Publishing Workflows
+.PHONY: release-publish
+release-publish: ## Complete release workflow: tag + build (requires VERSION=x.y.z)
+ifndef VERSION
+	@echo "❌ VERSION is required. Usage: make release-publish VERSION=1.0.0"
+	@exit 1
+endif
+ifndef RELEASE_CLI
+	@echo "❌ Release management capability not installed"
+	@exit 1
+endif
+	release publish --version $(VERSION)
+
+.PHONY: release-publish-gitea
+release-publish-gitea: ## Complete release workflow + Gitea upload (requires VERSION=x.y.z)
+ifndef VERSION
+	@echo "❌ VERSION is required. Usage: make release-publish-gitea VERSION=1.0.0"
+	@exit 1
+endif
+ifndef RELEASE_CLI
+	@echo "❌ Release management capability not installed"
+	@exit 1
+endif
+	release publish --version $(VERSION) --registry gitea
+
+.PHONY: release-publish-pypi
+release-publish-pypi: ## Complete release workflow + PyPI upload (requires VERSION=x.y.z)
+ifndef VERSION
+	@echo "❌ VERSION is required. Usage: make release-publish-pypi VERSION=1.0.0"
+	@exit 1
+endif
+ifndef RELEASE_CLI
+	@echo "❌ Release management capability not installed"
+	@exit 1
+endif
+	release publish --version $(VERSION) --registry pypi
+
+# Upload Existing Packages
+.PHONY: release-upload-gitea
+release-upload-gitea: ## Upload existing packages to Gitea registry
+ifndef RELEASE_CLI
+	@echo "❌ Release management capability not installed"
+	@exit 1
+endif
+	release upload --registry gitea
+
+.PHONY: release-upload-pypi
+release-upload-pypi: ## Upload existing packages to PyPI
+ifndef RELEASE_CLI
+	@echo "❌ Release management capability not installed"
+	@exit 1
+endif
+	release upload --registry pypi
+
+.PHONY: release-upload-testpypi
+release-upload-testpypi: ## Upload existing packages to Test PyPI
+ifndef RELEASE_CLI
+	@echo "❌ Release management capability not installed"
+	@exit 1
+endif
+	release upload --registry testpypi
+
+# Dry Run Options
+.PHONY: release-publish-dry-run
+release-publish-dry-run: ## Dry run of complete release workflow (requires VERSION=x.y.z)
+ifndef VERSION
+	@echo "❌ VERSION is required. Usage: make release-publish-dry-run VERSION=1.0.0"
+	@exit 1
+endif
+ifndef RELEASE_CLI
+	@echo "❌ Release management capability not installed"
+	@exit 1
+endif
+	release publish --version $(VERSION) --dry-run
+
+.PHONY: release-upload-dry-run
+release-upload-dry-run: ## Dry run of package upload to default registry
+ifndef RELEASE_CLI
+	@echo "❌ Release management capability not installed"
+	@exit 1
+endif
+	release upload --dry-run
+
+# Development and Setup
+.PHONY: release-management-install
+release-management-install: ## Install release management capability
+	pip install -e capabilities/release-management/
+
+.PHONY: release-management-install-dev
+release-management-install-dev: ## Install release management capability with dev dependencies
+	pip install -e "capabilities/release-management/[dev]"
+
+.PHONY: release-management-test
+release-management-test: ## Run release management capability tests
+	cd capabilities/release-management && pytest tests/
+
+.PHONY: release-management-help
+release-management-help: ## Show release management CLI help
+ifndef RELEASE_CLI
+	@echo "❌ Release management capability not installed"
+	@echo "   Install with: make release-management-install"
+	@exit 1
+endif
+	release --help
+
+# Convenience aliases
+.PHONY: release-upload
+release-upload: release-upload-gitea ## Upload packages to default registry (gitea)
+
+.PHONY: package
+package: release-build ## Build packages (alias for release-build)
+
+.PHONY: publish
+publish: ## Publish release to default registry (requires VERSION=x.y.z)
+ifndef VERSION
+	@echo "❌ VERSION is required. Usage: make publish VERSION=1.0.0"
+	@exit 1
+endif
+	@make release-publish-gitea VERSION=$(VERSION)
+
+# Meta information for capability discovery
+.PHONY: capability-info
+capability-info: ## Show capability information
+	@echo "Name: $(CAPABILITY_NAME)"
+	@echo "Description: $(CAPABILITY_DESCRIPTION)"
+	@echo "Targets:"
+	@$(MAKE) --no-print-directory help | grep "^  " | sed 's/^  /    /'

capabilities/release-management/README.md

@@ -0,0 +1,334 @@
+# Release Management Capability
+
+A self-contained capability for version management, package building, and release publication with Git and package registry integration.
+
+## Overview
+
+The release-management capability provides comprehensive release automation for Python projects using setuptools-scm for version management and supporting multiple publication targets including Gitea package registries.
+
+## Features
+
+- **Automatic Version Management**: Git tag-based versioning with setuptools-scm
+- **Package Building**: Wheel and source distribution generation
+- **Release Automation**: Complete release workflow from validation to publication
+- **Multi-Platform Publishing**: Support for Gitea, GitHub, and other package registries
+- **Fallback Publishing**: Release assets when package registries unavailable
+- **CLI Integration**: Command-line tools for release management
+- **Makefile Integration**: Convenient targets for common release tasks
+
+## Architecture
+
+### Core Components
+
+#### `ReleaseManager`
+Main orchestrator for release workflows, handling:
+- Release state validation
+- Git tag creation and management
+- Package building coordination
+- Publication orchestration
+
+#### `PackageBuilder`
+Responsible for package generation:
+- setuptools-scm integration
+- Wheel and source distribution building
+- Build artifact management
+
+#### `PublishManager`
+Handles package publication:
+- Multiple registry support (Gitea, PyPI, etc.)
+- Fallback mechanisms (release assets)
+- Upload progress tracking
+
+#### `GitManager`
+Git operations for releases:
+- Tag creation and validation
+- Repository state checking
+- Branch and commit management
+
+### Package Registry Support
+
+#### `GiteaRegistry`
+Gitea-specific package registry client:
+- PyPI-compatible registry uploads
+- Release asset fallback
+- Authentication handling
+
+#### `RegistryFactory`
+Factory for creating registry clients:
+- Auto-detection of registry types
+- Configuration management
+- Extensible for new registries
+
+## API Reference
+
+### Core Classes
+
+#### `ReleaseManager`
+```python
+from release_management import ReleaseManager
+
+manager = ReleaseManager()
+
+# Validate release readiness
+is_valid, issues = manager.validate_release_state()
+
+# Create complete release
+success = manager.publish_release("0.8.0")
+
+# Publish with specific registry
+success = manager.publish_with_registry("0.8.0", registry_type="gitea")
+```
+
+#### `PackageBuilder`
+```python
+from release_management import PackageBuilder
+
+builder = PackageBuilder()
+
+# Build packages
+builder.build_packages()
+
+# Get current version
+version = builder.get_current_version()
+
+# Clean build artifacts
+builder.clean_build()
+```
+
+#### `PublishManager`
+```python
+from release_management import PublishManager
+
+publisher = PublishManager()
+
+# Publish to registry
+success = publisher.publish_packages("gitea", dry_run=True)
+
+# Upload specific files
+success = publisher.upload_file("dist/package.whl", "gitea")
+```
+
+### CLI Commands
+
+#### `release`
+Main release command with subcommands:
+
+```bash
+# Show release status
+release status
+
+# Validate release readiness
+release validate
+
+# Create git tag
+release tag --version 0.8.0
+
+# Build packages
+release build
+
+# Complete release workflow
+release publish --version 0.8.0
+
+# Publish to specific registry
+release publish --version 0.8.0 --registry gitea
+
+# Upload existing packages
+release upload --registry gitea
+
+# Show registry information
+release registry-info --registry gitea
+```
+
+### Configuration
+
+#### Release Configuration
+Configure release behavior in `pyproject.toml`:
+
+```toml
+[tool.release-management]
+# Default registry for publishing
+default_registry = "gitea"
+
+# Validation requirements
+require_clean_tree = true
+require_main_branch = true
+
+# Package building
+build_wheel = true
+build_sdist = true
+clean_before_build = true
+
+# Registry configurations
+[tool.release-management.registries.gitea]
+url = "http://92.205.130.254:32166"
+owner = "coulomb"
+repo = "markitect_project"
+auth_token_env = "GITEA_API_TOKEN"
+
+[tool.release-management.registries.pypi]
+url = "https://upload.pypi.org/legacy/"
+auth_token_env = "PYPI_TOKEN"
+```
+
+## Installation
+
+Install as an editable dependency:
+
+```bash
+pip install -e capabilities/release-management/
+```
+
+Or with development dependencies:
+
+```bash
+pip install -e "capabilities/release-management/[dev]"
+```
+
+## Development Setup
+
+```bash
+cd capabilities/release-management/
+pip install -e ".[dev]"
+pytest tests/
+```
+
+## Integration with Main Project
+
+The main project integrates with this capability through:
+
+### Makefile Integration
+```makefile
+# Include release management targets
+include capabilities/release-management/release.mk
+
+# Or call capability directly
+release-status:
+	release status
+
+release-publish:
+	release publish --version $(VERSION)
+```
+
+### Setup Configuration
+In main project's `pyproject.toml`:
+
+```toml
+[tool.setuptools_scm]
+write_to = "markitect/_version.py"
+
+[tool.release-management]
+default_registry = "gitea"
+```
+
+## Migration Plan
+
+This capability consolidates the following existing components:
+
+### Files to Move
+1. **`release.py`** → `src/release_management/cli/main.py`
+2. **`gitea/`** directory → `src/release_management/registries/gitea/`
+3. **VERSION_MANAGEMENT.md** → `docs/version_management.md`
+4. **PACKAGE_PUBLISHING.md** → `docs/package_publishing.md`
+5. **Makefile release targets** → `release.mk`
+
+### New Structure
+```
+capabilities/release-management/
+├── README.md
+├── pyproject.toml
+├── release.mk                          # Makefile integration
+├── src/release_management/
+│   ├── __init__.py                     # Main API exports
+│   ├── core/
+│   │   ├── __init__.py
+│   │   ├── manager.py                  # ReleaseManager class
+│   │   ├── builder.py                  # PackageBuilder class
+│   │   └── publisher.py                # PublishManager class
+│   ├── git/
+│   │   ├── __init__.py
+│   │   └── manager.py                  # GitManager class
+│   ├── registries/
+│   │   ├── __init__.py
+│   │   ├── factory.py                  # RegistryFactory
+│   │   ├── base.py                     # Registry interface
+│   │   ├── gitea/
+│   │   │   ├── __init__.py
+│   │   │   ├── registry.py            # GiteaRegistry
+│   │   │   ├── config.py              # GiteaConfig
+│   │   │   └── exceptions.py          # GiteaError
+│   │   └── pypi/
+│   │       ├── __init__.py
+│   │       └── registry.py            # PyPIRegistry
+│   ├── cli/
+│   │   ├── __init__.py
+│   │   ├── main.py                     # Main CLI entry point
+│   │   ├── commands.py                 # CLI command implementations
+│   │   └── utils.py                    # CLI utilities
+│   └── utils/
+│       ├── __init__.py
+│       ├── version.py                  # Version management utilities
+│       └── validation.py              # Release validation utilities
+├── tests/
+│   ├── __init__.py
+│   ├── test_manager.py
+│   ├── test_builder.py
+│   ├── test_publisher.py
+│   ├── test_git_manager.py
+│   ├── test_gitea_registry.py
+│   └── fixtures/
+│       └── sample_packages/
+├── docs/
+│   ├── version_management.md
+│   ├── package_publishing.md
+│   ├── api_reference.md
+│   └── examples/
+└── examples/
+    ├── basic_release.py
+    ├── custom_registry.py
+    └── ci_integration.py
+```
+
+## Benefits of Capability Structure
+
+### Modularity
+- **Self-contained**: Independent testing and development
+- **Reusable**: Can be used in other projects
+- **Focused**: Single responsibility for release management
+
+### Maintainability
+- **Clear boundaries**: Well-defined API surface
+- **Extensible**: Easy to add new registries or features
+- **Testable**: Comprehensive test suite in isolation
+
+### Integration
+- **CLI integration**: Direct command-line access
+- **Makefile integration**: Convenient targets for workflows
+- **Configuration**: Centralized in pyproject.toml
+
+## Dependencies
+
+### Core Dependencies
+- `click>=8.0.0` - CLI framework
+- `requests>=2.25.0` - HTTP client for registries
+- `setuptools-scm>=8.0.0` - Version management
+- `build>=0.8.0` - Package building
+- `packaging>=21.0` - Version parsing and validation
+
+### Development Dependencies
+- `pytest>=7.0.0` - Testing framework
+- `pytest-cov>=4.0.0` - Coverage reporting
+- `responses>=0.20.0` - HTTP mocking for tests
+- `black>=22.0.0` - Code formatting
+- `flake8>=5.0.0` - Code linting
+- `mypy>=1.0.0` - Type checking
+
+## Compliance
+
+This capability follows the ComposableRepositoryParadigm:
+- ✅ Src layout (PEP 660 compliant)
+- ✅ Unidirectional dependencies
+- ✅ Self-contained with own tests
+- ✅ Independent configuration
+- ✅ Clean API boundaries
+- ✅ Type safety with mypy
+- ✅ Comprehensive documentation

capabilities/release-management/docs/package_publishing.md

@@ -0,0 +1,229 @@
+# Package Publishing Guide
+
+This guide covers building, publishing, and distributing MarkiTect packages using our Gitea package registry and setuptools-scm version management.
+
+## Prerequisites
+
+1. **Gitea API Token**: Set the `GITEA_API_TOKEN` environment variable with your Gitea API token
+2. **Repository Access**: The token must have write access to the repository's package registry
+
+## Quick Setup
+
+```bash
+# Set your Gitea API token
+export GITEA_API_TOKEN="your_gitea_api_token_here"
+
+# Or add it to your shell profile
+echo "export GITEA_API_TOKEN=your_token" >> ~/.bashrc
+```
+
+## Package Building
+
+### Quick Package Building
+
+```bash
+# Build distribution packages (recommended)
+make package
+
+# This will:
+# 1. Show current version (setuptools-scm)
+# 2. Clean previous builds
+# 3. Build both wheel and source distribution
+# 4. Show package details
+```
+
+### Manual Building
+
+```bash
+# Standard build
+make build
+
+# Using release script
+make release-build
+python release.py build
+
+# Manual Python build
+python -m build
+```
+
+## Publishing Workflow
+
+### Complete Release + Publishing
+
+```bash
+# 🚀 ONE-COMMAND RELEASE (recommended)
+make release-publish-gitea VERSION=0.8.0
+
+# This complete workflow:
+# 1. Creates git tag v0.8.0
+# 2. Builds packages (setuptools-scm uses tag for version 0.8.0)
+# 3. Uploads both wheel and source distribution to Gitea
+```
+
+### Step-by-Step Release
+
+```bash
+# 1. Check current status
+make release-status
+
+# 2. Validate release readiness
+make release-validate
+
+# 3. Create git tag
+make release-tag VERSION=0.8.0
+
+# 4. Build packages (version auto-detected from tag)
+make release-build
+
+# 5. Upload to Gitea registry
+make release-upload-gitea
+```
+
+### Development Package Testing
+
+```bash
+# Build current development version
+make package
+
+# Upload development packages for testing
+python release.py upload --dry-run  # Test first
+python release.py upload            # Upload development version
+```
+
+## Registry Management
+
+### Check Registry Status
+
+```bash
+# Comprehensive registry information
+make release-registry
+
+# Shows:
+# - Authentication status
+# - Registry URLs
+# - Existing packages
+# - Configuration details
+```
+
+### Upload Existing Packages
+
+```bash
+# Upload packages in dist/ folder
+make release-upload-gitea
+
+# With dry-run testing
+python release.py upload --dry-run
+python release.py upload
+```
+
+### Traditional Release (Git tags only)
+
+```bash
+# Standard release without Gitea upload
+make release-publish VERSION=0.8.0
+```
+
+## Available Commands
+
+### Makefile Targets
+
+- `make release-registry` - Show Gitea package registry information
+- `make release-upload-gitea` - Upload existing packages to Gitea
+- `make release-publish-gitea VERSION=x.y.z` - Complete release + Gitea upload
+
+### Python Script Commands
+
+- `python release.py registry` - Show registry information
+- `python release.py upload` - Upload packages to Gitea
+- `python release.py upload --dry-run` - Test upload without uploading
+- `python release.py publish --version x.y.z --to-gitea` - Release with Gitea upload
+
+## Registry Information
+
+- **Gitea URL**: http://92.205.130.254:32166
+- **Repository**: coulomb/markitect_project
+- **PyPI Registry URL**: http://92.205.130.254:32166/api/packages/coulomb/pypi
+- **Package List URL**: http://92.205.130.254:32166/api/v1/packages/coulomb
+
+## Installing from Gitea Registry
+
+Once packages are published, users can install them using:
+
+```bash
+# Install from Gitea registry
+pip install markitect --extra-index-url http://92.205.130.254:32166/api/packages/coulomb/pypi/simple/
+
+# Or configure pip permanently
+mkdir -p ~/.pip
+cat >> ~/.pip/pip.conf << EOF
+[global]
+extra-index-url = http://92.205.130.254:32166/api/packages/coulomb/pypi/simple/
+EOF
+```
+
+## Features
+
+### Automatic Package Detection
+
+The system automatically detects and uploads:
+- **Wheel files** (`.whl`) - Binary distributions
+- **Source distributions** (`.tar.gz`) - Source code packages
+
+### Version Management with setuptools-scm
+
+Versions are automatically determined by git tags:
+- `v0.8.0` tag → `0.8.0` package version
+- Development commits → `0.8.1.dev3+gcommithash` versions
+
+### Error Handling
+
+The system provides detailed error messages for:
+- Missing authentication tokens
+- Network connectivity issues
+- Package upload failures
+- Invalid package formats
+
+## Troubleshooting
+
+### Authentication Issues
+
+```bash
+# Check if token is set
+echo $GITEA_API_TOKEN
+
+# Test authentication
+python release.py registry
+```
+
+### Upload Failures
+
+```bash
+# Test with dry run first
+python release.py upload --dry-run
+
+# Check package files exist
+ls -la dist/
+
+# Rebuild packages if needed
+make release-build
+```
+
+### Network Issues
+
+- Ensure Gitea server is accessible: `ping 92.205.130.254`
+- Check firewall and proxy settings
+- Verify Gitea is running on port 32166
+
+## Development
+
+The package registry functionality is implemented in:
+- `gitea/package_registry.py` - Main package registry client
+- `release.py` - Release script with Gitea integration
+- `Makefile` - Convenient targets for package management
+
+## Security Notes
+
+- Never commit API tokens to version control
+- Use environment variables or secure credential storage
+- Tokens should have minimal required permissions
+- Rotate tokens regularly for security

capabilities/release-management/docs/version_management.md

@@ -0,0 +1,309 @@
+# Version Management Guide
+
+MarkiTect uses **setuptools-scm** for automatic version management based on git tags. This eliminates manual version bumping and ensures versions are always in sync with git history.
+
+## How It Works
+
+### Version Calculation
+
+setuptools-scm automatically determines the version based on:
+
+1. **Git Tags**: The latest tag matching `v*` pattern (e.g., `v0.7.0`)
+2. **Commits Since Tag**: Number of commits since the latest tag
+3. **Current Commit**: Short commit hash
+4. **Dirty State**: Whether there are uncommitted changes
+
+### Version Examples
+
+| Git State | Version Output |
+|-----------|----------------|
+| `v0.7.0` tag (clean) | `0.7.0` |
+| `v0.7.0` + 3 commits | `0.7.1.dev3+g1a2b3c4d` |
+| `v0.7.0` + 3 commits + dirty | `0.7.1.dev3+g1a2b3c4d.d20251108` |
+| No tags + 10 commits | `0.1.dev10+g5e6f7g8h` |
+
+## Version Commands
+
+### Check Current Version
+
+```bash
+# Quick version check
+python -m setuptools_scm
+
+# Detailed version information
+make release-status
+python release.py status
+```
+
+### Access Version in Code
+
+```python
+from markitect.__version__ import __version__
+print(f"MarkiTect version: {__version__}")
+```
+
+## Creating Releases
+
+### Release Workflow
+
+1. **Ensure Clean State**:
+   ```bash
+   git status  # Should be clean
+   git pull    # Latest changes
+   ```
+
+2. **Validate Release Readiness**:
+   ```bash
+   make release-validate
+   ```
+
+3. **Create Release**:
+   ```bash
+   # Standard release
+   make release-publish VERSION=0.8.0
+
+   # Release with Gitea publishing
+   make release-publish-gitea VERSION=0.8.0
+   ```
+
+### Version Naming Conventions
+
+Follow [Semantic Versioning](https://semver.org/):
+
+- **Major Version** (`1.0.0`): Breaking changes
+- **Minor Version** (`0.8.0`): New features (backward compatible)
+- **Patch Version** (`0.7.1`): Bug fixes (backward compatible)
+- **Pre-release** (`0.8.0-rc1`): Release candidates
+- **Development** (`0.8.1.dev3+hash`): Automatic between releases
+
+### Git Tag Format
+
+Always use the format `vX.Y.Z`:
+
+```bash
+# Correct
+git tag v0.8.0
+git tag v1.0.0-rc1
+
+# Incorrect
+git tag 0.8.0      # Missing 'v' prefix
+git tag version-0.8.0  # Wrong format
+```
+
+## Development Versions
+
+### Understanding Development Versions
+
+Between releases, setuptools-scm generates development versions:
+
+```
+0.7.1.dev3+g1a2b3c4d.d20251108
+│   │  │  │ │        │
+│   │  │  │ │        └── Date (dirty state)
+│   │  │  │ └─────────── Commit hash
+│   │  │  └───────────── Commits since tag
+│   │  └──────────────── Dev marker
+│   └─────────────────── Next version
+└─────────────────────── Base version
+```
+
+### Working with Development Versions
+
+Development versions are automatically:
+- **Sorted correctly** by pip (dev versions < release versions)
+- **Excluded from releases** (only tagged versions are released)
+- **Unique** (each commit has a different version)
+
+## Configuration
+
+### setuptools-scm Configuration
+
+Configuration in `pyproject.toml`:
+
+```toml
+[tool.setuptools_scm]
+write_to = "markitect/_version.py"
+```
+
+### Version File Generation
+
+setuptools-scm automatically generates `markitect/_version.py`:
+
+```python
+# Auto-generated - do not edit
+__version__ = "0.7.1.dev3+g1a2b3c4d"
+__version_tuple__ = (0, 7, 1, 'dev3', 'g1a2b3c4d')
+```
+
+This file is:
+- ✅ **Auto-generated** during package builds
+- ✅ **Added to .gitignore** (never committed)
+- ✅ **Available at runtime** for version checks
+
+## Release Branches
+
+### Main Branch Strategy
+
+MarkiTect uses a simple branching strategy:
+
+- **`main`**: Primary development branch
+- **Tags**: Mark release points (`v0.7.0`, `v0.8.0`)
+- **Feature branches**: Merged via pull requests
+
+### Release Process
+
+1. **Development** happens on `main`
+2. **Release tags** created on `main` when ready
+3. **Hotfix tags** can be created on older commits if needed
+
+```bash
+# Standard release from main
+git checkout main
+git pull
+make release-publish-gitea VERSION=0.8.0
+
+# Hotfix release from older commit
+git checkout v0.7.0
+git cherry-pick <hotfix-commit>
+git tag v0.7.1
+git push origin v0.7.1
+```
+
+## Package Building
+
+### Build Commands
+
+```bash
+# Build packages with version info
+make package
+
+# Build using release script
+make release-build
+python release.py build
+
+# Manual build
+python -m build
+```
+
+### Build Output
+
+Packages are built to `dist/` directory:
+- **Wheel** (`.whl`): Binary distribution
+- **Source Distribution** (`.tar.gz`): Source code
+
+### Version in Package Names
+
+setuptools-scm ensures package names include correct versions:
+
+```
+dist/
+├── markitect-0.8.0-py3-none-any.whl      # Release
+├── markitect-0.8.0.tar.gz                # Release
+├── markitect-0.8.1.dev3+hash-py3-none-any.whl  # Development
+└── markitect-0.8.1.dev3+hash.tar.gz      # Development
+```
+
+## Troubleshooting
+
+### Common Issues
+
+1. **"No tags found"**:
+   ```bash
+   # Create initial tag
+   git tag v0.1.0
+   git push origin v0.1.0
+   ```
+
+2. **"Dirty working tree"**:
+   ```bash
+   # Commit or stash changes
+   git add . && git commit -m "Changes"
+   # Or
+   git stash
+   ```
+
+3. **"Version not updating"**:
+   ```bash
+   # Clear setuptools-scm cache
+   rm -rf build/ *.egg-info/
+   python -m setuptools_scm
+   ```
+
+4. **"Import error in __version__.py"**:
+   ```bash
+   # Rebuild package to generate _version.py
+   make package
+   ```
+
+### Debug Version Issues
+
+```bash
+# Verbose setuptools-scm output
+python -m setuptools_scm --debug
+
+# Check git state
+git describe --tags --dirty --always
+
+# Verify tag format
+git tag --list | grep "^v"
+```
+
+## Best Practices
+
+### Do's ✅
+
+- **Always use `vX.Y.Z` tag format**
+- **Create annotated tags**: `git tag -a v0.8.0 -m "Release 0.8.0"`
+- **Push tags to origin**: `git push origin v0.8.0`
+- **Keep clean working tree** for releases
+- **Follow semantic versioning**
+- **Test version detection** before releasing
+
+### Don'ts ❌
+
+- **Don't edit `_version.py`** manually (auto-generated)
+- **Don't commit version numbers** to source files
+- **Don't use non-standard tag formats**
+- **Don't create releases from dirty tree**
+- **Don't delete old tags** (breaks version history)
+
+### Version Strategy
+
+1. **Development**: Let setuptools-scm handle automatically
+2. **Pre-releases**: Use `-rc1`, `-alpha1`, `-beta1` suffixes
+3. **Releases**: Create tags only for stable releases
+4. **Hotfixes**: Tag from appropriate commit, not necessarily `main`
+
+## Integration with CI/CD
+
+### GitHub Actions Example
+
+```yaml
+name: Release
+on:
+  push:
+    tags: ['v*']
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+        with:
+          fetch-depth: 0  # Important for setuptools-scm
+
+      - name: Build packages
+        run: make package
+
+      - name: Upload to Gitea
+        env:
+          GITEA_API_TOKEN: ${{ secrets.GITEA_API_TOKEN }}
+        run: python release.py upload
+```
+
+### Key Points
+
+- **`fetch-depth: 0`**: Required for setuptools-scm to access git history
+- **Environment variables**: Use secrets for API tokens
+- **Tag-based triggers**: Only build releases for version tags
+
+This version management system provides automatic, reliable, and traceable versioning that scales with your development workflow.

capabilities/release-management/release.mk

@@ -0,0 +1,236 @@
+# Release Management Makefile Integration
+# Include this file in your main Makefile to add release management capabilities
+#
+# Usage: include capabilities/release-management/release.mk
+
+# Release Management Variables
+RELEASE_MANAGEMENT_PATH := capabilities/release-management
+RELEASE_CLI := release
+
+# Check if release management capability is available
+RELEASE_AVAILABLE := $(shell command -v $(RELEASE_CLI) 2> /dev/null)
+
+# Release Status and Information
+.PHONY: release-status
+release-status: ## Show current release status and version information
+ifndef RELEASE_AVAILABLE
+	@echo "❌ Release management capability not installed"
+	@echo "   Install with: pip install -e $(RELEASE_MANAGEMENT_PATH)/"
+	@exit 1
+endif
+	$(RELEASE_CLI) status
+
+.PHONY: release-validate
+release-validate: ## Validate repository state for release readiness
+ifndef RELEASE_AVAILABLE
+	@echo "❌ Release management capability not installed"
+	@exit 1
+endif
+	$(RELEASE_CLI) validate
+
+.PHONY: release-registry-info
+release-registry-info: ## Show package registry information and status
+ifndef RELEASE_AVAILABLE
+	@echo "❌ Release management capability not installed"
+	@exit 1
+endif
+	$(RELEASE_CLI) registry-info
+
+# Git Tag Management
+.PHONY: release-tag
+release-tag: ## Create git tag for version (requires VERSION=x.y.z)
+ifndef VERSION
+	@echo "❌ VERSION is required. Usage: make release-tag VERSION=1.0.0"
+	@exit 1
+endif
+ifndef RELEASE_AVAILABLE
+	@echo "❌ Release management capability not installed"
+	@exit 1
+endif
+	$(RELEASE_CLI) tag --version $(VERSION)
+
+# Package Building
+.PHONY: release-build
+release-build: ## Build release packages using setuptools-scm
+ifndef RELEASE_AVAILABLE
+	@echo "❌ Release management capability not installed"
+	@exit 1
+endif
+	$(RELEASE_CLI) build
+
+.PHONY: release-clean
+release-clean: ## Clean build artifacts and temporary files
+ifndef RELEASE_AVAILABLE
+	@echo "❌ Release management capability not installed"
+	@exit 1
+endif
+	$(RELEASE_CLI) clean
+
+# Publishing Workflows
+.PHONY: release-publish
+release-publish: ## Complete release workflow: tag + build (requires VERSION=x.y.z)
+ifndef VERSION
+	@echo "❌ VERSION is required. Usage: make release-publish VERSION=1.0.0"
+	@exit 1
+endif
+ifndef RELEASE_AVAILABLE
+	@echo "❌ Release management capability not installed"
+	@exit 1
+endif
+	$(RELEASE_CLI) publish --version $(VERSION)
+
+.PHONY: release-publish-gitea
+release-publish-gitea: ## Complete release workflow + Gitea upload (requires VERSION=x.y.z)
+ifndef VERSION
+	@echo "❌ VERSION is required. Usage: make release-publish-gitea VERSION=1.0.0"
+	@exit 1
+endif
+ifndef RELEASE_AVAILABLE
+	@echo "❌ Release management capability not installed"
+	@exit 1
+endif
+	$(RELEASE_CLI) publish --version $(VERSION) --registry gitea
+
+.PHONY: release-publish-pypi
+release-publish-pypi: ## Complete release workflow + PyPI upload (requires VERSION=x.y.z)
+ifndef VERSION
+	@echo "❌ VERSION is required. Usage: make release-publish-pypi VERSION=1.0.0"
+	@exit 1
+endif
+ifndef RELEASE_AVAILABLE
+	@echo "❌ Release management capability not installed"
+	@exit 1
+endif
+	$(RELEASE_CLI) publish --version $(VERSION) --registry pypi
+
+# Upload Existing Packages
+.PHONY: release-upload-gitea
+release-upload-gitea: ## Upload existing packages to Gitea registry
+ifndef RELEASE_AVAILABLE
+	@echo "❌ Release management capability not installed"
+	@exit 1
+endif
+	$(RELEASE_CLI) upload --registry gitea
+
+.PHONY: release-upload-pypi
+release-upload-pypi: ## Upload existing packages to PyPI
+ifndef RELEASE_AVAILABLE
+	@echo "❌ Release management capability not installed"
+	@exit 1
+endif
+	$(RELEASE_CLI) upload --registry pypi
+
+.PHONY: release-upload-testpypi
+release-upload-testpypi: ## Upload existing packages to Test PyPI
+ifndef RELEASE_AVAILABLE
+	@echo "❌ Release management capability not installed"
+	@exit 1
+endif
+	$(RELEASE_CLI) upload --registry testpypi
+
+# Dry Run Options
+.PHONY: release-publish-dry-run
+release-publish-dry-run: ## Dry run of complete release workflow (requires VERSION=x.y.z)
+ifndef VERSION
+	@echo "❌ VERSION is required. Usage: make release-publish-dry-run VERSION=1.0.0"
+	@exit 1
+endif
+ifndef RELEASE_AVAILABLE
+	@echo "❌ Release management capability not installed"
+	@exit 1
+endif
+	$(RELEASE_CLI) publish --version $(VERSION) --dry-run
+
+.PHONY: release-upload-dry-run
+release-upload-dry-run: ## Dry run of package upload to default registry
+ifndef RELEASE_AVAILABLE
+	@echo "❌ Release management capability not installed"
+	@exit 1
+endif
+	$(RELEASE_CLI) upload --dry-run
+
+# Development and Setup
+.PHONY: release-management-install
+release-management-install: ## Install release management capability
+	pip install -e $(RELEASE_MANAGEMENT_PATH)/
+
+.PHONY: release-management-install-dev
+release-management-install-dev: ## Install release management capability with dev dependencies
+	pip install -e "$(RELEASE_MANAGEMENT_PATH)/[dev]"
+
+.PHONY: release-management-test
+release-management-test: ## Run release management capability tests
+	cd $(RELEASE_MANAGEMENT_PATH) && pytest tests/
+
+.PHONY: release-management-help
+release-management-help: ## Show release management CLI help
+ifndef RELEASE_AVAILABLE
+	@echo "❌ Release management capability not installed"
+	@echo "   Install with: make release-management-install"
+	@exit 1
+endif
+	$(RELEASE_CLI) --help
+
+# Help target integration
+.PHONY: help-release
+help-release: ## Show release management specific help
+	@echo ""
+	@echo "📦 Release Management:"
+	@echo "  release-status               Show current release status and version information"
+	@echo "  release-validate             Validate repository state for release readiness"
+	@echo "  release-registry-info        Show package registry information and status"
+	@echo ""
+	@echo "🏷️  Git Tag Management:"
+	@echo "  release-tag VERSION=x.y.z    Create git tag for version"
+	@echo ""
+	@echo "🔨 Package Building:"
+	@echo "  release-build                Build release packages using setuptools-scm"
+	@echo "  release-clean                Clean build artifacts and temporary files"
+	@echo ""
+	@echo "🚀 Publishing Workflows:"
+	@echo "  release-publish VERSION=x.y.z         Complete release workflow (tag + build)"
+	@echo "  release-publish-gitea VERSION=x.y.z   Complete release + Gitea upload"
+	@echo "  release-publish-pypi VERSION=x.y.z    Complete release + PyPI upload"
+	@echo ""
+	@echo "📤 Upload Existing Packages:"
+	@echo "  release-upload-gitea         Upload existing packages to Gitea registry"
+	@echo "  release-upload-pypi          Upload existing packages to PyPI"
+	@echo "  release-upload-testpypi      Upload existing packages to Test PyPI"
+	@echo ""
+	@echo "🧪 Dry Run Options:"
+	@echo "  release-publish-dry-run VERSION=x.y.z  Dry run of release workflow"
+	@echo "  release-upload-dry-run                  Dry run of package upload"
+	@echo ""
+	@echo "⚙️  Development and Setup:"
+	@echo "  release-management-install          Install release management capability"
+	@echo "  release-management-install-dev      Install with development dependencies"
+	@echo "  release-management-test             Run capability tests"
+	@echo "  release-management-help             Show CLI help"
+	@echo ""
+
+# Default registry shortcuts (can be overridden)
+RELEASE_DEFAULT_REGISTRY ?= gitea
+
+.PHONY: release-upload
+release-upload: release-upload-$(RELEASE_DEFAULT_REGISTRY) ## Upload packages to default registry ($(RELEASE_DEFAULT_REGISTRY))
+
+# Integration with main project targets
+# These can be overridden in main Makefile if different behavior is needed
+
+.PHONY: package
+package: release-build ## Build packages (alias for release-build)
+
+.PHONY: publish
+publish: ## Publish release to default registry (requires VERSION=x.y.z)
+ifndef VERSION
+	@echo "❌ VERSION is required. Usage: make publish VERSION=1.0.0"
+	@exit 1
+endif
+	@make release-publish-$(RELEASE_DEFAULT_REGISTRY) VERSION=$(VERSION)
+
+# Legacy compatibility targets
+.PHONY: release-status-legacy
+release-status-legacy: release-status ## Legacy alias for release-status
+
+.PHONY: package-upload
+package-upload: release-upload ## Legacy alias for release-upload

capabilities/release-management/src/release_management/__init__.py

@@ -0,0 +1,65 @@
+"""
+Release Management Capability
+
+A comprehensive release management system for Python projects providing:
+- Automatic version management with setuptools-scm
+- Package building and distribution
+- Multi-platform publishing (Gitea, PyPI, etc.)
+- Git tag-based release workflows
+- CLI tools for release automation
+
+Main Components:
+- ReleaseManager: Orchestrates complete release workflows
+- PackageBuilder: Handles package generation and building
+- PublishManager: Manages package publication to registries
+- GitManager: Git operations for releases
+- Registry Support: Gitea, PyPI, and extensible registry system
+
+Quick Start:
+    from release_management import ReleaseManager
+
+    manager = ReleaseManager()
+    success = manager.publish_release("1.0.0")
+
+CLI Usage:
+    release status
+    release publish --version 1.0.0
+    release upload --registry gitea
+"""
+
+from .core.manager import ReleaseManager
+from .core.builder import PackageBuilder
+from .core.publisher import PublishManager
+from .git.manager import GitManager
+from .registries.factory import RegistryFactory
+from .registries.gitea.registry import GiteaRegistry
+from .utils.version import VersionManager
+from .utils.validation import ReleaseValidator
+
+# Version is managed in pyproject.toml
+__version__ = "0.1.0"
+
+__all__ = [
+    # Core classes
+    "ReleaseManager",
+    "PackageBuilder",
+    "PublishManager",
+    "GitManager",
+
+    # Registry support
+    "RegistryFactory",
+    "GiteaRegistry",
+
+    # Utilities
+    "VersionManager",
+    "ReleaseValidator",
+
+    # Version
+    "__version__",
+]
+
+# Package metadata
+__title__ = "release-management"
+__description__ = "Comprehensive release management capability for Python projects"
+__author__ = "MarkiTect Project"
+__license__ = "MIT"

capabilities/release-management/src/release_management/changelog/__init__.py

@@ -0,0 +1,10 @@
+"""
+CHANGELOG management tools.
+
+This package provides tools for working with CHANGELOG.md files.
+"""
+
+from .editor import ChangelogEditor
+from .parser import ChangelogParser
+
+__all__ = ['ChangelogEditor', 'ChangelogParser']

capabilities/release-management/src/release_management/changelog/editor.py

@@ -0,0 +1,207 @@
+"""
+CHANGELOG.md editor for programmatic updates.
+
+This module provides tools for editing CHANGELOG.md files following
+the Keep a Changelog format.
+"""
+
+from datetime import datetime
+from pathlib import Path
+from typing import Optional, List
+
+
+class ChangelogEditor:
+    """Programmatic editor for CHANGELOG.md files."""
+
+    def __init__(self, changelog_path: Optional[Path] = None):
+        """Initialize changelog editor.
+
+        Args:
+            changelog_path: Path to CHANGELOG.md file
+        """
+        self.changelog_path = changelog_path or Path.cwd() / 'CHANGELOG.md'
+
+    def create_version_section(self, version: str, date: Optional[str] = None) -> bool:
+        """Create new version section and move Unreleased content.
+
+        Args:
+            version: Version number (e.g., "0.11.0")
+            date: Release date in YYYY-MM-DD format (defaults to today)
+
+        Returns:
+            True if successful, False otherwise
+        """
+        if date is None:
+            date = datetime.now().strftime("%Y-%m-%d")
+
+        # Validate version format
+        version_clean = version.lstrip('v')
+
+        if not self.changelog_path.exists():
+            print(f"❌ CHANGELOG.md not found at {self.changelog_path}")
+            return False
+
+        try:
+            with open(self.changelog_path) as f:
+                lines = f.readlines()
+
+            # Find Unreleased section
+            unreleased_idx = None
+            for i, line in enumerate(lines):
+                if line.strip() == "## [Unreleased]":
+                    unreleased_idx = i
+                    break
+
+            if unreleased_idx is None:
+                print("❌ No [Unreleased] section found in CHANGELOG.md")
+                return False
+
+            # Find next version section or end of Unreleased content
+            next_section_idx = None
+            for i in range(unreleased_idx + 1, len(lines)):
+                if lines[i].startswith("## [") and not lines[i].startswith("## [Unreleased]"):
+                    next_section_idx = i
+                    break
+
+            # Extract Unreleased content (skip the header line and first blank line)
+            if next_section_idx:
+                unreleased_content = lines[unreleased_idx + 1:next_section_idx]
+            else:
+                unreleased_content = lines[unreleased_idx + 1:]
+
+            # Check if there's actual content to move
+            has_content = any(line.strip() and not line.strip().startswith('#')
+                            for line in unreleased_content)
+
+            if not has_content:
+                print(f"⚠️  [Unreleased] section is empty. Add changes before creating release section.")
+                print(f"💡 Tip: You can still create the section, but it will be empty.")
+
+            # Create new version section with moved content
+            new_section_lines = [
+                f"## [{version_clean}] - {date}\n",
+            ]
+
+            # Add the unreleased content (preserving structure)
+            new_section_lines.extend(unreleased_content)
+
+            # Ensure proper spacing after new section
+            if new_section_lines and not new_section_lines[-1].endswith('\n\n'):
+                if not new_section_lines[-1].endswith('\n'):
+                    new_section_lines[-1] += '\n'
+                new_section_lines.append('\n')
+
+            # Build new file content
+            # Keep everything up to and including Unreleased header
+            new_lines = lines[:unreleased_idx + 1]
+
+            # Add blank line after Unreleased header
+            new_lines.append('\n')
+
+            # Add the new version section
+            new_lines.extend(new_section_lines)
+
+            # Add remaining sections (if any)
+            if next_section_idx:
+                new_lines.extend(lines[next_section_idx:])
+
+            # Write back
+            with open(self.changelog_path, 'w') as f:
+                f.writelines(new_lines)
+
+            print(f"✅ Created section [{version_clean}] - {date} in CHANGELOG.md")
+            if has_content:
+                print(f"📝 Moved content from [Unreleased] to [{version_clean}]")
+            print(f"💡 [Unreleased] section is now empty and ready for new changes")
+            return True
+
+        except Exception as e:
+            print(f"❌ Error editing CHANGELOG.md: {e}")
+            return False
+
+    def get_version_content(self, version: str) -> Optional[List[str]]:
+        """Extract content for a specific version section.
+
+        Args:
+            version: Version number to extract (e.g., "0.10.0")
+
+        Returns:
+            List of lines in the version section, or None if not found
+        """
+        version_clean = version.lstrip('v')
+
+        if not self.changelog_path.exists():
+            return None
+
+        try:
+            with open(self.changelog_path) as f:
+                lines = f.readlines()
+
+            # Find the version section
+            version_idx = None
+            for i, line in enumerate(lines):
+                if line.strip().startswith(f"## [{version_clean}]"):
+                    version_idx = i
+                    break
+
+            if version_idx is None:
+                return None
+
+            # Find next section
+            next_section_idx = None
+            for i in range(version_idx + 1, len(lines)):
+                if lines[i].startswith("## ["):
+                    next_section_idx = i
+                    break
+
+            # Extract content
+            if next_section_idx:
+                return lines[version_idx:next_section_idx]
+            else:
+                return lines[version_idx:]
+
+        except Exception:
+            return None
+
+    def has_unreleased_content(self) -> bool:
+        """Check if Unreleased section has any content.
+
+        Returns:
+            True if Unreleased section has content, False otherwise
+        """
+        if not self.changelog_path.exists():
+            return False
+
+        try:
+            with open(self.changelog_path) as f:
+                lines = f.readlines()
+
+            # Find Unreleased section
+            unreleased_idx = None
+            for i, line in enumerate(lines):
+                if line.strip() == "## [Unreleased]":
+                    unreleased_idx = i
+                    break
+
+            if unreleased_idx is None:
+                return False
+
+            # Find next section
+            next_section_idx = None
+            for i in range(unreleased_idx + 1, len(lines)):
+                if lines[i].startswith("## ["):
+                    next_section_idx = i
+                    break
+
+            # Check content
+            if next_section_idx:
+                content = lines[unreleased_idx + 1:next_section_idx]
+            else:
+                content = lines[unreleased_idx + 1:]
+
+            # Check if there's actual content (not just whitespace or section headers)
+            return any(line.strip() and not line.strip().startswith('#')
+                      for line in content)
+
+        except Exception:
+            return False

capabilities/release-management/src/release_management/changelog/parser.py

@@ -0,0 +1,179 @@
+"""
+CHANGELOG.md parser for extracting release notes.
+
+This module provides tools for parsing CHANGELOG.md files and extracting
+version-specific content for release notes.
+"""
+
+import re
+from pathlib import Path
+from typing import Optional
+
+
+class ChangelogParser:
+    """Parse CHANGELOG.md files and extract release information."""
+
+    def __init__(self, changelog_path: Optional[Path] = None):
+        """Initialize changelog parser.
+
+        Args:
+            changelog_path: Path to CHANGELOG.md file
+        """
+        self.changelog_path = changelog_path or Path.cwd() / 'CHANGELOG.md'
+
+    def extract_version_section(self, version: str, format: str = 'markdown') -> str:
+        """Extract CHANGELOG section for a specific version.
+
+        Args:
+            version: Version to extract (e.g., "0.10.0")
+            format: Output format ('markdown', 'plain', 'html')
+
+        Returns:
+            Formatted content of the version section
+        """
+        if not self.changelog_path.exists():
+            return f"Error: CHANGELOG.md not found at {self.changelog_path}"
+
+        try:
+            version_clean = version.lstrip('v')
+
+            with open(self.changelog_path) as f:
+                content = f.read()
+
+            # Find the version section using regex
+            # Match: ## [VERSION] - DATE followed by content until next ## [
+            pattern = rf"## \[{re.escape(version_clean)}\].*?\n\n(.*?)(?=\n## \[|\Z)"
+            match = re.search(pattern, content, re.DOTALL)
+
+            if not match:
+                return f"Error: No section found for version {version_clean} in CHANGELOG.md"
+
+            section_content = match.group(1).strip()
+
+            if not section_content:
+                return f"Warning: Section for version {version_clean} exists but is empty"
+
+            # Format based on requested format
+            if format == 'plain':
+                return self._to_plain(section_content)
+            elif format == 'html':
+                return self._to_html(section_content)
+            else:
+                return section_content  # markdown (default)
+
+        except Exception as e:
+            return f"Error reading CHANGELOG: {e}"
+
+    def get_latest_version(self) -> Optional[str]:
+        """Get the latest version number from CHANGELOG.
+
+        Returns:
+            Latest version string or None if not found
+        """
+        if not self.changelog_path.exists():
+            return None
+
+        try:
+            with open(self.changelog_path) as f:
+                content = f.read()
+
+            # Find first version section (skip Unreleased)
+            pattern = r"## \[(\d+\.\d+\.\d+[^\]]*)\]"
+            match = re.search(pattern, content)
+
+            return match.group(1) if match else None
+
+        except Exception:
+            return None
+
+    def list_versions(self) -> list:
+        """List all versions in CHANGELOG.
+
+        Returns:
+            List of version strings
+        """
+        if not self.changelog_path.exists():
+            return []
+
+        try:
+            with open(self.changelog_path) as f:
+                content = f.read()
+
+            # Find all version sections (excluding Unreleased)
+            pattern = r"## \[(\d+\.\d+\.\d+[^\]]*)\]"
+            matches = re.findall(pattern, content)
+
+            return matches
+
+        except Exception:
+            return []
+
+    def _to_plain(self, markdown_content: str) -> str:
+        """Convert markdown content to plain text.
+
+        Args:
+            markdown_content: Markdown formatted content
+
+        Returns:
+            Plain text content
+        """
+        # Remove markdown formatting
+        plain = markdown_content
+
+        # Remove bold/italic
+        plain = re.sub(r'\*\*([^*]+)\*\*', r'\1', plain)  # bold
+        plain = re.sub(r'\*([^*]+)\*', r'\1', plain)  # italic
+        plain = re.sub(r'__([^_]+)__', r'\1', plain)  # bold (underscores)
+        plain = re.sub(r'_([^_]+)_', r'\1', plain)  # italic (underscores)
+
+        # Remove links but keep text
+        plain = re.sub(r'\[([^\]]+)\]\([^\)]+\)', r'\1', plain)
+
+        # Remove inline code backticks
+        plain = re.sub(r'`([^`]+)`', r'\1', plain)
+
+        # Convert headers to plain text with spacing
+        plain = re.sub(r'^### (.+)$', r'\n\1:', plain, flags=re.MULTILINE)
+        plain = re.sub(r'^## (.+)$', r'\n\1\n' + '=' * 40, plain, flags=re.MULTILINE)
+
+        return plain.strip()
+
+    def _to_html(self, markdown_content: str) -> str:
+        """Convert markdown content to HTML.
+
+        Args:
+            markdown_content: Markdown formatted content
+
+        Returns:
+            HTML formatted content
+        """
+        try:
+            import markdown
+            return markdown.markdown(markdown_content)
+        except ImportError:
+            # Fallback to basic HTML conversion if markdown package not available
+            html = markdown_content
+
+            # Headers
+            html = re.sub(r'^### (.+)$', r'<h3>\1</h3>', html, flags=re.MULTILINE)
+            html = re.sub(r'^## (.+)$', r'<h2>\1</h2>', html, flags=re.MULTILINE)
+
+            # Bold/italic
+            html = re.sub(r'\*\*([^*]+)\*\*', r'<strong>\1</strong>', html)
+            html = re.sub(r'\*([^*]+)\*', r'<em>\1</em>', html)
+
+            # Links
+            html = re.sub(r'\[([^\]]+)\]\(([^\)]+)\)', r'<a href="\2">\1</a>', html)
+
+            # Code
+            html = re.sub(r'`([^`]+)`', r'<code>\1</code>', html)
+
+            # Lists
+            html = re.sub(r'^- (.+)$', r'<li>\1</li>', html, flags=re.MULTILINE)
+            html = re.sub(r'(<li>.*</li>)', r'<ul>\1</ul>', html, flags=re.DOTALL)
+
+            # Paragraphs
+            html = re.sub(r'\n\n', '</p><p>', html)
+            html = f'<p>{html}</p>'
+
+            return html

capabilities/release-management/src/release_management/cli/__init__.py

@@ -0,0 +1,9 @@
+"""
+Command-line interface for release management.
+
+This module provides CLI commands for release operations.
+"""
+
+from .main import main
+
+__all__ = ["main"]

capabilities/release-management/src/release_management/cli/main.py

@@ -0,0 +1,416 @@
+"""
+Main CLI entry point for release management.
+
+This module provides the main CLI interface adapted from the original release.py script.
+"""
+
+import click
+import sys
+from pathlib import Path
+from typing import Optional
+
+from ..core.manager import ReleaseManager
+from ..utils.version import VersionManager
+from ..changelog.editor import ChangelogEditor
+from ..changelog.parser import ChangelogParser
+from ..summary.generator import SummaryGenerator
+
+
+@click.group(invoke_without_command=True)
+@click.option('--dry-run', is_flag=True, help='Show what would be done without making changes')
+@click.option('--force', is_flag=True, help='Force operation even with warnings')
+@click.option('--project-root', type=click.Path(exists=True, path_type=Path),
+              help='Project root directory')
+@click.pass_context
+def main(ctx, dry_run: bool, force: bool, project_root: Optional[Path]):
+    """Release management CLI for Python projects."""
+    ctx.ensure_object(dict)
+    ctx.obj['dry_run'] = dry_run
+    ctx.obj['force'] = force
+    ctx.obj['project_root'] = project_root
+
+    # If no command specified, show status
+    if ctx.invoked_subcommand is None:
+        ctx.invoke(status)
+
+
+@main.command()
+@click.pass_context
+def status(ctx):
+    """Show current release status and version information."""
+    manager = ReleaseManager(
+        project_root=ctx.obj['project_root'],
+        dry_run=ctx.obj['dry_run'],
+        force=ctx.obj['force']
+    )
+
+    print("🔍 Release Status")
+    print("=" * 60)
+
+    status_info = manager.get_release_status()
+
+    # Version information
+    print(f"Current Version: {status_info['version']}")
+
+    # Git information
+    if status_info.get('is_repo'):
+        print(f"Git Branch: {status_info['branch']}")
+        print(f"Latest Commit: {status_info['latest_commit']}")
+        print(f"Latest Tag: {status_info['latest_tag'] or 'None'}")
+        print(f"Uncommitted Changes: {'Yes' if status_info['has_changes'] else 'No'}")
+
+        # Show unpushed tags
+        unpushed_tags = status_info.get('unpushed_tags', [])
+        if unpushed_tags:
+            print(f"\n⚠️  Unpushed Tags: {len(unpushed_tags)} tag(s) not pushed to origin")
+            for tag in unpushed_tags:
+                print(f"    - {tag}")
+            print(f"\n💡 Push tags with: git push origin {' '.join(unpushed_tags)}")
+            print(f"   Or push all tags: git push --tags")
+    else:
+        print("Git Repository: Not available")
+
+    # Package information
+    packages = status_info['packages']
+    print(f"\\nBuilt Packages: {packages['total_count']} files")
+    if packages['wheels']:
+        print("  Wheels:")
+        for wheel in packages['wheels']:
+            print(f"    - {wheel}")
+    if packages['sdists']:
+        print("  Source Distributions:")
+        for sdist in packages['sdists']:
+            print(f"    - {sdist}")
+
+    # Validation status
+    validation = status_info['validation']
+    if validation['is_valid']:
+        print("\\n✅ Repository is ready for release")
+    else:
+        print("\\n❌ Release validation issues:")
+        for issue in validation['issues']:
+            print(f"  - {issue}")
+
+
+@main.command()
+@click.pass_context
+def validate(ctx):
+    """Validate repository state for release readiness."""
+    manager = ReleaseManager(
+        project_root=ctx.obj['project_root'],
+        dry_run=ctx.obj['dry_run'],
+        force=ctx.obj['force']
+    )
+
+    is_valid, issues = manager.validate_release_state()
+
+    if is_valid:
+        print("✅ Repository is ready for release")
+    else:
+        print("❌ Release validation failed:")
+        for issue in issues:
+            print(f"  - {issue}")
+        sys.exit(1)
+
+
+@main.command()
+@click.option('--version', required=True, help='Version to tag (e.g., 0.8.0)')
+@click.option('--message', help='Tag message')
+@click.option('--push/--no-push', default=True,
+              help='Automatically push tag to origin (default: --push)')
+@click.pass_context
+def tag(ctx, version: str, message: Optional[str], push: bool):
+    """Create git tag for version."""
+    manager = ReleaseManager(
+        project_root=ctx.obj['project_root'],
+        dry_run=ctx.obj['dry_run'],
+        force=ctx.obj['force']
+    )
+
+    if manager.create_tag(version, message, push=push):
+        print(f"✅ Successfully created tag for version {version}")
+        if not push:
+            print(f"💡 Push tag with: git push origin v{version}")
+    else:
+        print(f"❌ Failed to create tag for version {version}")
+        sys.exit(1)
+
+
+@main.command()
+@click.pass_context
+def build(ctx):
+    """Build release packages using setuptools-scm."""
+    manager = ReleaseManager(
+        project_root=ctx.obj['project_root'],
+        dry_run=ctx.obj['dry_run'],
+        force=ctx.obj['force']
+    )
+
+    if manager.build_packages():
+        print("✅ Packages built successfully")
+    else:
+        print("❌ Package build failed")
+        sys.exit(1)
+
+
+@main.command()
+@click.option('--version', required=True, help='Version to publish (e.g., 0.8.0)')
+@click.option('--registry', default='gitea', help='Registry type (gitea, pypi, etc.)')
+@click.option('--skip-build', is_flag=True, help='Skip building and use existing packages')
+@click.pass_context
+def publish(ctx, version: str, registry: str, skip_build: bool):
+    """Complete release workflow: tag, build, and publish."""
+    manager = ReleaseManager(
+        project_root=ctx.obj['project_root'],
+        dry_run=ctx.obj['dry_run'],
+        force=ctx.obj['force']
+    )
+
+    if manager.publish_with_fallback(version, registry, skip_build):
+        print(f"🎉 Release {version} published successfully!")
+    else:
+        print(f"❌ Release {version} failed")
+        sys.exit(1)
+
+
+@main.command()
+@click.option('--registry', default='gitea', help='Registry type (gitea, pypi, etc.)')
+@click.pass_context
+def upload(ctx, registry: str):
+    """Upload existing packages to registry."""
+    manager = ReleaseManager(
+        project_root=ctx.obj['project_root'],
+        dry_run=ctx.obj['dry_run'],
+        force=ctx.obj['force']
+    )
+
+    if manager.upload_existing_packages(registry):
+        print(f"✅ Packages uploaded to {registry}")
+    else:
+        print(f"❌ Upload to {registry} failed")
+        sys.exit(1)
+
+
+@main.command('registry-info')
+@click.option('--registry', default='gitea', help='Registry type to show info for')
+@click.pass_context
+def registry_info(ctx, registry: str):
+    """Show package registry information and status."""
+    manager = ReleaseManager(
+        project_root=ctx.obj['project_root'],
+        dry_run=ctx.obj['dry_run'],
+        force=ctx.obj['force']
+    )
+
+    info = manager.show_registry_info(registry)
+
+    print(f"📦 {registry.title()} Registry Information")
+    print("=" * 50)
+
+    if 'error' in info:
+        print(f"❌ Error: {info['error']}")
+        return
+
+    for key, value in info.items():
+        if isinstance(value, bool):
+            indicator = "✅" if value else "❌"
+            print(f"{key.replace('_', ' ').title()}: {indicator}")
+        else:
+            print(f"{key.replace('_', ' ').title()}: {value}")
+
+
+@main.command()
+@click.pass_context
+def clean(ctx):
+    """Clean build artifacts and temporary files."""
+    manager = ReleaseManager(
+        project_root=ctx.obj['project_root'],
+        dry_run=ctx.obj['dry_run'],
+        force=ctx.obj['force']
+    )
+
+    manager.clean_build_artifacts()
+    print("✅ Build artifacts cleaned")
+
+
+@main.command('version-info')
+@click.option('--suggest', is_flag=True, help='Suggest next version options')
+@click.pass_context
+def version_info(ctx, suggest: bool):
+    """Show version information and suggestions."""
+    version_manager = VersionManager(ctx.obj['project_root'])
+
+    current = version_manager.get_current_version()
+    print(f"Current Version: {current}")
+
+    if suggest:
+        suggestions = version_manager.suggest_version(current)
+        if 'error' in suggestions:
+            print(f"❌ {suggestions['error']}")
+            if 'suggestion' in suggestions:
+                print(f"💡 {suggestions['suggestion']}")
+        else:
+            print("\\nSuggested next versions:")
+            print(f"  Patch: {suggestions['patch']}")
+            print(f"  Minor: {suggestions['minor']}")
+            print(f"  Major: {suggestions['major']}")
+
+    # Show version components
+    version_data = version_manager.parse_version(current)
+    if 'error' not in version_data:
+        print("\\nVersion Components:")
+        for key, value in version_data.items():
+            if value is not None:
+                print(f"  {key.replace('_', ' ').title()}: {value}")
+
+
+@main.command('check-consistency')
+@click.option('--version', required=True, help='Version to check (e.g., 0.10.0)')
+@click.pass_context
+def check_consistency(ctx, version: str):
+    """Check consistency between CHANGELOG version and git tags."""
+    manager = ReleaseManager(
+        project_root=ctx.obj['project_root'],
+        dry_run=ctx.obj['dry_run'],
+        force=ctx.obj['force']
+    )
+
+    is_consistent, issues = manager.check_version_consistency(version)
+
+    if is_consistent:
+        print(f"✅ Version {version} is consistent:")
+        print(f"  - CHANGELOG has section for {version}")
+        print(f"  - Git tag v{version} exists")
+        print(f"  - [Unreleased] section present")
+    else:
+        print(f"❌ Version {version} has consistency issues:")
+        for issue in issues:
+            print(f"  - {issue}")
+        sys.exit(1)
+
+
+@main.command('prepare')
+@click.argument('version')
+@click.option('--date', default=None, help='Release date (YYYY-MM-DD, defaults to today)')
+@click.pass_context
+def prepare(ctx, version: str, date: Optional[str]):
+    """Prepare CHANGELOG for new version release.
+
+    Creates a new version section in CHANGELOG.md and moves all content
+    from the [Unreleased] section to the new version section.
+    """
+    project_root = ctx.obj['project_root'] or Path.cwd()
+    changelog_path = project_root / 'CHANGELOG.md'
+
+    editor = ChangelogEditor(changelog_path)
+
+    # Create version section
+    if editor.create_version_section(version, date):
+        # Validate result
+        manager = ReleaseManager(
+            project_root=ctx.obj['project_root'],
+            dry_run=ctx.obj['dry_run'],
+            force=ctx.obj['force']
+        )
+
+        # Check if CHANGELOG is valid after edit
+        is_valid, issues = manager.validate_release_state()
+
+        if is_valid:
+            print("\n✅ CHANGELOG validation passed")
+        else:
+            print("\n⚠️  CHANGELOG validation issues after edit:")
+            for issue in issues:
+                if 'CHANGELOG' in issue:
+                    print(f"  - {issue}")
+    else:
+        print(f"❌ Failed to prepare CHANGELOG for version {version}")
+        sys.exit(1)
+
+
+@main.command('summary')
+@click.argument('version')
+@click.option('--output', '-o', default=None, type=click.Path(path_type=Path),
+              help='Output file path (defaults to RELEASE_SUMMARY_vX.Y.Z.md)')
+@click.pass_context
+def summary(ctx, version: str, output: Optional[Path]):
+    """Generate release summary document.
+
+    Extracts CHANGELOG content, git statistics, build artifacts, and
+    validation results to create a comprehensive release summary.
+    """
+    project_root = ctx.obj['project_root'] or Path.cwd()
+
+    # Default output path
+    if output is None:
+        version_clean = version.lstrip('v')
+        output = project_root / f"RELEASE_SUMMARY_v{version_clean}.md"
+    elif not output.is_absolute():
+        output = project_root / output
+
+    generator = SummaryGenerator(project_root)
+
+    try:
+        content = generator.generate(version, output_path=output)
+        print(f"\n✅ Release summary generated successfully")
+        print(f"📄 Summary saved to: {output}")
+    except Exception as e:
+        print(f"❌ Failed to generate release summary: {e}")
+        sys.exit(1)
+
+
+@main.command('notes')
+@click.argument('version', required=False)
+@click.option('--format', 'output_format', type=click.Choice(['markdown', 'plain', 'html']),
+              default='markdown', help='Output format (default: markdown)')
+@click.option('--output', '-o', default=None, type=click.Path(path_type=Path),
+              help='Save to file instead of stdout')
+@click.pass_context
+def notes(ctx, version: Optional[str], output_format: str, output: Optional[Path]):
+    """Extract release notes from CHANGELOG.md.
+
+    Extracts the CHANGELOG section for a specific version and outputs it
+    in various formats. Useful for creating GitHub/Gitea release notes.
+
+    If no version is specified, uses the latest version from CHANGELOG.
+
+    Examples:
+        release notes 0.10.0              # Extract v0.10.0 notes (markdown)
+        release notes                     # Extract latest version notes
+        release notes 0.10.0 --format plain  # Plain text format
+        release notes 0.10.0 -o notes.md     # Save to file
+        release notes 0.10.0 | gh release create v0.10.0 -F -  # Pipe to gh
+    """
+    project_root = ctx.obj['project_root'] or Path.cwd()
+    changelog_path = project_root / 'CHANGELOG.md'
+
+    parser = ChangelogParser(changelog_path)
+
+    # Get version (use latest if not specified)
+    if version is None:
+        version = parser.get_latest_version()
+        if version is None:
+            print("❌ Could not determine version from CHANGELOG.md")
+            sys.exit(1)
+        print(f"Using latest version: {version}", file=sys.stderr)
+
+    # Extract content
+    content = parser.extract_version_section(version, format=output_format)
+
+    # Check for errors
+    if content.startswith("Error:") or content.startswith("Warning:"):
+        print(content)
+        sys.exit(1 if content.startswith("Error:") else 0)
+
+    # Output
+    if output:
+        if not output.is_absolute():
+            output = project_root / output
+        output.write_text(content)
+        print(f"✅ Release notes written to {output}", file=sys.stderr)
+    else:
+        print(content)
+
+
+if __name__ == '__main__':
+    main()

capabilities/release-management/src/release_management/core/__init__.py

@@ -0,0 +1,14 @@
+"""
+Core release management classes.
+
+This module provides the main classes for orchestrating releases:
+- ReleaseManager: Main coordinator for release workflows
+- PackageBuilder: Package building and setuptools-scm integration
+- PublishManager: Package publication to registries
+"""
+
+from .manager import ReleaseManager
+from .builder import PackageBuilder
+from .publisher import PublishManager
+
+__all__ = ["ReleaseManager", "PackageBuilder", "PublishManager"]

capabilities/release-management/src/release_management/core/builder.py

@@ -0,0 +1,166 @@
+"""
+Package building functionality for releases.
+
+This module handles package building using setuptools-scm and the Python build module.
+"""
+
+import subprocess
+import sys
+from pathlib import Path
+from typing import List, Optional, Dict, Any
+
+from ..utils.version import VersionManager
+
+
+class PackageBuilder:
+    """Handles package building with setuptools-scm integration."""
+
+    def __init__(self, project_root: Optional[Path] = None, dry_run: bool = False):
+        """Initialize the package builder.
+
+        Args:
+            project_root: Root directory of the project. Defaults to current directory.
+            dry_run: If True, show what would be done without executing.
+        """
+        self.project_root = project_root or Path.cwd()
+        self.dry_run = dry_run
+        self.dist_dir = self.project_root / "dist"
+
+    def get_current_version(self) -> str:
+        """Get current version using setuptools-scm.
+
+        Returns:
+            Current version string or "unknown" if unavailable.
+        """
+        try:
+            result = self._run_command(
+                ['python', '-m', 'setuptools_scm'],
+                capture=True,
+                skip_dry_run=True
+            )
+            return result.stdout.strip()
+        except subprocess.CalledProcessError:
+            return "unknown"
+
+    def clean_build(self) -> None:
+        """Clean previous build artifacts."""
+        print("🧹 Cleaning build artifacts...")
+
+        patterns = ['build', 'dist', '*.egg-info']
+        for pattern in patterns:
+            try:
+                if pattern == 'dist' and self.dist_dir.exists():
+                    if self.dry_run:
+                        print(f"[DRY RUN] Would remove: {self.dist_dir}")
+                    else:
+                        import shutil
+                        shutil.rmtree(self.dist_dir)
+                        print(f"✅ Removed: {self.dist_dir}")
+                elif pattern != 'dist':
+                    self._run_command(['rm', '-rf', pattern])
+            except subprocess.CalledProcessError:
+                pass  # Ignore if files don't exist
+
+    def build_packages(self) -> bool:
+        """Build release packages using setuptools-scm.
+
+        Returns:
+            True if build successful, False otherwise.
+        """
+        print(f"📦 Building packages (version auto-determined by setuptools-scm)")
+
+        # Clean previous builds
+        self.clean_build()
+
+        # Build packages
+        try:
+            print("Building packages...")
+            self._run_command(['python', '-m', 'build'], capture=False)
+            print("✅ Packages built successfully")
+
+            # Show package details
+            self._show_package_details()
+            return True
+
+        except subprocess.CalledProcessError as e:
+            print(f"❌ Package build failed: {e}")
+            return False
+
+    def get_built_packages(self) -> Dict[str, List[Path]]:
+        """Get list of built packages by type.
+
+        Returns:
+            Dictionary with 'wheels' and 'sdists' keys containing file paths.
+        """
+        if not self.dist_dir.exists():
+            return {"wheels": [], "sdists": []}
+
+        wheels = list(self.dist_dir.glob("*.whl"))
+        sdists = list(self.dist_dir.glob("*.tar.gz"))
+
+        return {"wheels": wheels, "sdists": sdists}
+
+    def validate_packages(self) -> bool:
+        """Validate that expected packages were built.
+
+        Returns:
+            True if packages are valid, False otherwise.
+        """
+        packages = self.get_built_packages()
+
+        if not packages["wheels"] and not packages["sdists"]:
+            print("❌ No packages found in dist/")
+            return False
+
+        # Check package sizes
+        for wheel in packages["wheels"]:
+            if wheel.stat().st_size < 1000:  # Less than 1KB
+                print(f"⚠️  Warning: {wheel.name} is very small ({wheel.stat().st_size} bytes)")
+
+        for sdist in packages["sdists"]:
+            if sdist.stat().st_size < 1000:  # Less than 1KB
+                print(f"⚠️  Warning: {sdist.name} is very small ({sdist.stat().st_size} bytes)")
+
+        return True
+
+    def _show_package_details(self) -> None:
+        """Show details about built packages."""
+        packages = self.get_built_packages()
+
+        if packages["wheels"] or packages["sdists"]:
+            print(f"\n📦 Built packages in {self.dist_dir}:")
+
+            for wheel in packages["wheels"]:
+                size = wheel.stat().st_size
+                print(f"  🎯 {wheel.name} ({size:,} bytes)")
+
+            for sdist in packages["sdists"]:
+                size = sdist.stat().st_size
+                print(f"  📄 {sdist.name} ({size:,} bytes)")
+        else:
+            print("❌ No packages found")
+
+    def _run_command(self, cmd: List[str], capture: bool = True,
+                    check: bool = True, skip_dry_run: bool = False) -> subprocess.CompletedProcess:
+        """Run a command with optional dry-run support.
+
+        Args:
+            cmd: Command to execute
+            capture: Whether to capture output
+            check: Whether to raise on non-zero exit
+            skip_dry_run: Whether to skip dry-run check and always execute
+
+        Returns:
+            CompletedProcess result
+        """
+        if self.dry_run and not skip_dry_run:
+            print(f"[DRY RUN] Would run: {' '.join(cmd)}")
+            return subprocess.CompletedProcess(cmd, 0, "", "")
+
+        return subprocess.run(
+            cmd,
+            capture_output=capture,
+            text=True,
+            check=check,
+            cwd=self.project_root
+        )

capabilities/release-management/src/release_management/core/manager.py

@@ -0,0 +1,236 @@
+"""
+Main release manager orchestrating complete release workflows.
+
+This module provides the primary ReleaseManager class that coordinates
+all aspects of the release process.
+"""
+
+from pathlib import Path
+from typing import Optional, List, Tuple, Dict, Any
+
+from .builder import PackageBuilder
+from .publisher import PublishManager
+from ..git.manager import GitManager
+from ..utils.validation import ReleaseValidator
+
+
+class ReleaseManager:
+    """Main orchestrator for release workflows."""
+
+    def __init__(self, project_root: Optional[Path] = None, dry_run: bool = False, force: bool = False):
+        """Initialize the release manager.
+
+        Args:
+            project_root: Root directory of the project. Defaults to current directory.
+            dry_run: If True, show what would be done without executing.
+            force: If True, skip validation checks.
+        """
+        self.project_root = project_root or Path.cwd()
+        self.dry_run = dry_run
+        self.force = force
+
+        # Initialize component managers
+        self.git_manager = GitManager(project_root, dry_run)
+        self.builder = PackageBuilder(project_root, dry_run)
+        self.publisher = PublishManager(project_root, dry_run)
+        self.validator = ReleaseValidator(project_root)
+
+    def get_release_status(self) -> Dict[str, Any]:
+        """Get comprehensive release status information.
+
+        Returns:
+            Dictionary with release status details
+        """
+        status = {}
+
+        # Version information
+        status['version'] = self.builder.get_current_version()
+
+        # Git status
+        git_status = self.git_manager.get_repository_status()
+        status.update(git_status)
+
+        # Package status
+        packages = self.builder.get_built_packages()
+        status['packages'] = {
+            'wheels': [p.name for p in packages['wheels']],
+            'sdists': [p.name for p in packages['sdists']],
+            'total_count': len(packages['wheels']) + len(packages['sdists'])
+        }
+
+        # Validation status
+        is_valid, issues = self.validate_release_state()
+        status['validation'] = {
+            'is_valid': is_valid,
+            'issues': issues
+        }
+
+        return status
+
+    def validate_release_state(self) -> Tuple[bool, List[str]]:
+        """Validate that the repository is ready for release.
+
+        Returns:
+            Tuple of (is_valid, list_of_issues)
+        """
+        return self.validator.validate_release_state(force=self.force)
+
+    def create_tag(self, version: str, message: Optional[str] = None, push: bool = True) -> bool:
+        """Create a git tag for the release.
+
+        Args:
+            version: Version to tag (e.g., "1.0.0")
+            message: Optional tag message
+            push: Whether to push the tag to origin (default: True)
+
+        Returns:
+            True if tag created successfully, False otherwise
+        """
+        # Validate release state first
+        is_valid, issues = self.validate_release_state()
+        if not is_valid and not self.force:
+            print("❌ Cannot create tag:")
+            for issue in issues:
+                print(f"  - {issue}")
+            return False
+
+        # Check version-tag consistency (ensure CHANGELOG has version section)
+        changelog_valid, changelog_issues = self.validator.validate_changelog_version(version)
+        if not changelog_valid and not self.force:
+            print(f"❌ Cannot create tag for version {version}:")
+            for issue in changelog_issues:
+                print(f"  - {issue}")
+            print("\n💡 Tip: Add a section for version {version} to CHANGELOG.md before tagging")
+            return False
+
+        return self.git_manager.create_tag(version, message, push=push)
+
+    def build_packages(self) -> bool:
+        """Build release packages.
+
+        Returns:
+            True if build successful, False otherwise
+        """
+        success = self.builder.build_packages()
+        if success:
+            success = self.builder.validate_packages()
+        return success
+
+    def publish_release(self, version: str, registry_type: str = 'gitea',
+                       skip_build: bool = False) -> bool:
+        """Complete release workflow: validate, tag, build, and publish.
+
+        Args:
+            version: Version to release
+            registry_type: Type of registry to publish to
+            skip_build: If True, skip building and use existing packages
+
+        Returns:
+            True if release successful, False otherwise
+        """
+        print(f"🚀 Publishing release {version}")
+
+        # Validate state
+        is_valid, issues = self.validate_release_state()
+        if not is_valid and not self.force:
+            print("❌ Cannot publish release:")
+            for issue in issues:
+                print(f"  - {issue}")
+            return False
+
+        # Create git tag (this determines the version for setuptools-scm)
+        if not self.git_manager.tag_exists(f"v{version}"):
+            if not self.create_tag(version):
+                return False
+        else:
+            print(f"✅ Tag v{version} already exists")
+
+        # Build packages (setuptools-scm will use the tag for version)
+        if not skip_build:
+            if not self.build_packages():
+                return False
+        else:
+            print("⏭️  Skipping build (using existing packages)")
+
+        # Publish packages
+        if not self.publisher.publish_packages(registry_type):
+            print("⚠️  Release completed but publishing failed")
+            return False
+
+        print(f"✅ Release {version} completed successfully!")
+        print(f"📦 Packages published to {registry_type}")
+        print(f"🏷️  Git tag v{version} created")
+        return True
+
+    def publish_with_fallback(self, version: str, registry_type: str = 'gitea',
+                            skip_build: bool = False) -> bool:
+        """Complete release workflow with fallback to release assets.
+
+        Args:
+            version: Version to release
+            registry_type: Type of registry to publish to
+            skip_build: If True, skip building and use existing packages
+
+        Returns:
+            True if release successful, False otherwise
+        """
+        # Try normal publish first
+        if self.publish_release(version, registry_type, skip_build):
+            return True
+
+        # If that fails, try release assets fallback
+        print("🔄 Attempting release assets fallback...")
+        return self.publisher.publish_as_release_assets(version, registry_type)
+
+    def upload_existing_packages(self, registry_type: str = 'gitea') -> bool:
+        """Upload existing packages without building or tagging.
+
+        Args:
+            registry_type: Type of registry to upload to
+
+        Returns:
+            True if upload successful, False otherwise
+        """
+        print(f"📤 Uploading existing packages to {registry_type}")
+
+        packages = self.builder.get_built_packages()
+        if not packages["wheels"] and not packages["sdists"]:
+            print("❌ No packages found in dist/. Run build first.")
+            return False
+
+        all_packages = packages["wheels"] + packages["sdists"]
+        return self.publisher.upload_specific_packages(all_packages, registry_type)
+
+    def clean_build_artifacts(self) -> None:
+        """Clean build artifacts and temporary files."""
+        self.builder.clean_build()
+
+    def show_registry_info(self, registry_type: str = 'gitea') -> Dict[str, Any]:
+        """Show information about a registry.
+
+        Args:
+            registry_type: Type of registry
+
+        Returns:
+            Dictionary with registry information
+        """
+        return self.publisher.get_registry_info(registry_type)
+
+    def get_commits_since_last_tag(self) -> List[str]:
+        """Get commits since the last release tag.
+
+        Returns:
+            List of commit messages since last tag
+        """
+        return self.git_manager.get_commits_since_tag()
+
+    def check_version_consistency(self, version: str) -> Tuple[bool, List[str]]:
+        """Check consistency between CHANGELOG version and git tags.
+
+        Args:
+            version: Version to check (e.g., "0.10.0")
+
+        Returns:
+            Tuple of (is_consistent, list_of_issues)
+        """
+        return self.validator.check_version_tag_consistency(version)

capabilities/release-management/src/release_management/core/publisher.py

@@ -0,0 +1,248 @@
+"""
+Package publishing functionality for releases.
+
+This module handles publishing packages to various registries.
+"""
+
+from pathlib import Path
+from typing import Dict, List, Optional, Any
+
+from ..registries.factory import RegistryFactory
+from ..registries.base import RegistryInterface
+from .builder import PackageBuilder
+
+
+class PublishManager:
+    """Handles package publication to registries."""
+
+    def __init__(self, project_root: Optional[Path] = None, dry_run: bool = False):
+        """Initialize the publish manager.
+
+        Args:
+            project_root: Root directory of the project. Defaults to current directory.
+            dry_run: If True, show what would be done without executing.
+        """
+        self.project_root = project_root or Path.cwd()
+        self.dry_run = dry_run
+
+    def publish_packages(self, registry_type: str = 'gitea',
+                        registry_config: Optional[Dict[str, Any]] = None) -> bool:
+        """Publish packages to specified registry.
+
+        Args:
+            registry_type: Type of registry to publish to
+            registry_config: Optional registry configuration
+
+        Returns:
+            True if publishing successful, False otherwise
+        """
+        try:
+            # Get registry client
+            registry = self._get_registry(registry_type, registry_config)
+
+            # Get built packages
+            builder = PackageBuilder(self.project_root)
+            packages = builder.get_built_packages()
+
+            if not packages["wheels"] and not packages["sdists"]:
+                print("❌ No packages found in dist/. Run build first.")
+                return False
+
+            # Upload packages
+            success = True
+            for wheel in packages["wheels"]:
+                if not self._upload_package_with_fallback(registry, wheel):
+                    success = False
+
+            for sdist in packages["sdists"]:
+                if not self._upload_package_with_fallback(registry, sdist):
+                    success = False
+
+            return success
+
+        except Exception as e:
+            print(f"❌ Publishing failed: {e}")
+            return False
+
+    def upload_specific_packages(self, package_paths: List[Path],
+                               registry_type: str = 'gitea',
+                               registry_config: Optional[Dict[str, Any]] = None) -> bool:
+        """Upload specific package files to registry.
+
+        Args:
+            package_paths: List of paths to package files
+            registry_type: Type of registry to publish to
+            registry_config: Optional registry configuration
+
+        Returns:
+            True if all uploads successful, False otherwise
+        """
+        try:
+            registry = self._get_registry(registry_type, registry_config)
+
+            success = True
+            for package_path in package_paths:
+                if not package_path.exists():
+                    print(f"❌ Package not found: {package_path}")
+                    success = False
+                    continue
+
+                if not self._upload_package_with_fallback(registry, package_path):
+                    success = False
+
+            return success
+
+        except Exception as e:
+            print(f"❌ Upload failed: {e}")
+            return False
+
+    def publish_as_release_assets(self, version: str,
+                                registry_type: str = 'gitea',
+                                registry_config: Optional[Dict[str, Any]] = None) -> bool:
+        """Publish packages as release assets (fallback method).
+
+        Args:
+            version: Version to publish as
+            registry_type: Type of registry (must support release assets)
+            registry_config: Optional registry configuration
+
+        Returns:
+            True if publishing successful, False otherwise
+        """
+        try:
+            registry = self._get_registry(registry_type, registry_config)
+
+            # Check if registry supports release assets
+            if not hasattr(registry, 'upload_package_as_release_assets'):
+                print(f"❌ Registry type '{registry_type}' does not support release assets")
+                return False
+
+            # Get built packages
+            builder = PackageBuilder(self.project_root)
+            packages = builder.get_built_packages()
+
+            if not packages["wheels"] and not packages["sdists"]:
+                print("❌ No packages found in dist/. Run build first.")
+                return False
+
+            # Find wheel and corresponding source distribution
+            success = True
+            for wheel in packages["wheels"]:
+                # Find matching sdist
+                sdist = None
+                wheel_name_parts = wheel.stem.split('-')
+                package_name = wheel_name_parts[0] if wheel_name_parts else ""
+
+                for potential_sdist in packages["sdists"]:
+                    if potential_sdist.stem.startswith(package_name):
+                        sdist = potential_sdist
+                        break
+
+                # Upload as release assets
+                if not registry.upload_package_as_release_assets(
+                    version, wheel, sdist, dry_run=self.dry_run
+                ):
+                    success = False
+
+            return success
+
+        except Exception as e:
+            print(f"❌ Release asset publishing failed: {e}")
+            return False
+
+    def get_registry_info(self, registry_type: str = 'gitea',
+                         registry_config: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
+        """Get information about a registry.
+
+        Args:
+            registry_type: Type of registry
+            registry_config: Optional registry configuration
+
+        Returns:
+            Dictionary with registry information
+        """
+        try:
+            registry = self._get_registry(registry_type, registry_config)
+            return registry.get_registry_info()
+        except Exception as e:
+            return {"error": str(e)}
+
+    def _get_registry(self, registry_type: str,
+                     registry_config: Optional[Dict[str, Any]] = None) -> RegistryInterface:
+        """Get a registry client.
+
+        Args:
+            registry_type: Type of registry
+            registry_config: Optional registry configuration
+
+        Returns:
+            Registry client instance
+        """
+        if registry_config:
+            return RegistryFactory.create(registry_type, registry_config)
+        else:
+            # Try to load from pyproject.toml first
+            try:
+                return RegistryFactory.create_from_pyproject_config(
+                    self.project_root / "pyproject.toml",
+                    registry_type
+                )
+            except (ValueError, FileNotFoundError):
+                # Fallback to auto-detection
+                return RegistryFactory.create(registry_type)
+
+    def _upload_package_with_fallback(self, registry: RegistryInterface,
+                                    package_path: Path) -> bool:
+        """Upload a package with fallback to release assets if needed.
+
+        Args:
+            registry: Registry client
+            package_path: Path to package file
+
+        Returns:
+            True if upload successful, False otherwise
+        """
+        try:
+            # Try normal package upload first
+            return registry.upload_package(package_path, dry_run=self.dry_run)
+        except Exception as e:
+            print(f"⚠️  Package upload failed: {e}")
+
+            # Check if registry supports release assets as fallback
+            if hasattr(registry, 'upload_package_as_release_assets'):
+                print("🔄 Trying release assets as fallback...")
+
+                # Extract version from package filename for release assets
+                version = self._extract_version_from_filename(package_path)
+                if version:
+                    return registry.upload_package_as_release_assets(
+                        version, package_path, dry_run=self.dry_run
+                    )
+
+            return False
+
+    def _extract_version_from_filename(self, package_path: Path) -> Optional[str]:
+        """Extract version from package filename.
+
+        Args:
+            package_path: Path to package file
+
+        Returns:
+            Version string or None if not found
+        """
+        try:
+            if package_path.suffix == '.whl':
+                # Wheel format: package-version-python-abi-platform.whl
+                parts = package_path.stem.split('-')
+                if len(parts) >= 2:
+                    return parts[1]
+            elif package_path.suffix == '.gz' and package_path.name.endswith('.tar.gz'):
+                # Source dist format: package-version.tar.gz
+                name_without_tar = package_path.name.replace('.tar.gz', '')
+                parts = name_without_tar.split('-')
+                if len(parts) >= 2:
+                    return parts[1]
+        except Exception:
+            pass
+
+        return None

capabilities/release-management/src/release_management/git/__init__.py

@@ -0,0 +1,12 @@
+"""
+Git management for releases.
+
+This module provides Git operations required for release workflows:
+- Tag creation and management
+- Repository state validation
+- Branch and commit operations
+"""
+
+from .manager import GitManager
+
+__all__ = ["GitManager"]

capabilities/release-management/src/release_management/git/manager.py

@@ -0,0 +1,254 @@
+"""
+Git operations for release management.
+
+This module handles all Git-related operations needed for releases.
+"""
+
+import subprocess
+from pathlib import Path
+from typing import Dict, Any, Optional, List
+
+
+class GitManager:
+    """Manages Git operations for releases."""
+
+    def __init__(self, project_root: Optional[Path] = None, dry_run: bool = False):
+        """Initialize Git manager.
+
+        Args:
+            project_root: Root directory of the project
+            dry_run: If True, show what would be done without executing
+        """
+        self.project_root = project_root or Path.cwd()
+        self.dry_run = dry_run
+
+    def get_repository_status(self) -> Dict[str, Any]:
+        """Get current git repository status.
+
+        Returns:
+            Dictionary with repository status information
+        """
+        try:
+            # Get current branch
+            branch_result = self._run_command(['git', 'branch', '--show-current'])
+            current_branch = branch_result.stdout.strip()
+
+            # Check for uncommitted changes
+            status_result = self._run_command(['git', 'status', '--porcelain'])
+            has_changes = bool(status_result.stdout.strip())
+
+            # Get latest commit
+            commit_result = self._run_command(['git', 'rev-parse', '--short', 'HEAD'])
+            latest_commit = commit_result.stdout.strip()
+
+            # Get latest tag
+            try:
+                tag_result = self._run_command(['git', 'describe', '--tags', '--abbrev=0'])
+                latest_tag = tag_result.stdout.strip()
+            except subprocess.CalledProcessError:
+                latest_tag = None
+
+            # Get unpushed tags
+            unpushed_tags = self.get_unpushed_tags()
+
+            return {
+                'is_repo': True,
+                'branch': current_branch,
+                'has_changes': has_changes,
+                'latest_commit': latest_commit,
+                'latest_tag': latest_tag,
+                'unpushed_tags': unpushed_tags
+            }
+        except subprocess.CalledProcessError:
+            return {'is_repo': False}
+
+    def create_tag(self, version: str, message: Optional[str] = None, push: bool = True) -> bool:
+        """Create and optionally push git tag.
+
+        Args:
+            version: Version to tag (e.g., "1.0.0")
+            message: Optional tag message
+            push: Whether to push the tag to origin (default: True)
+
+        Returns:
+            True if successful, False otherwise
+        """
+        if not version.startswith('v'):
+            tag_name = f"v{version}"
+        else:
+            tag_name = version
+
+        tag_message = message or f"Release {version.lstrip('v')}"
+        print(f"🏷️  Creating git tag {tag_name}")
+
+        try:
+            # Create annotated tag
+            self._run_command(['git', 'tag', '-a', tag_name, '-m', tag_message])
+            print(f"✅ Tag {tag_name} created")
+
+            # Push tag to origin if requested
+            if push:
+                try:
+                    print(f"📤 Pushing tag to origin...")
+                    self._run_command(['git', 'push', 'origin', tag_name])
+                    print(f"✅ Tag pushed to origin")
+                    return True
+                except subprocess.CalledProcessError as e:
+                    print(f"⚠️  Could not push tag to origin: {e}")
+                    print(f"You can push it manually with: git push origin {tag_name}")
+                    return True  # Tag created successfully, push can be done manually
+            else:
+                return True  # Tag created successfully, user chose not to push
+
+        except subprocess.CalledProcessError as e:
+            print(f"❌ Failed to create tag: {e}")
+            return False
+
+    def validate_release_state(self, force: bool = False) -> tuple[bool, List[str]]:
+        """Validate that repository is ready for release.
+
+        Args:
+            force: Skip validation checks if True
+
+        Returns:
+            Tuple of (is_valid, list_of_issues)
+        """
+        issues = []
+        status = self.get_repository_status()
+
+        if not status['is_repo']:
+            issues.append("Not in a git repository")
+        else:
+            if status['has_changes'] and not force:
+                issues.append("Repository has uncommitted changes")
+            if status['branch'] != 'main' and not force:
+                issues.append(f"Not on main branch (currently on {status['branch']})")
+
+        return len(issues) == 0, issues
+
+    def get_commits_since_tag(self, tag_name: Optional[str] = None) -> List[str]:
+        """Get list of commits since specified tag.
+
+        Args:
+            tag_name: Tag to compare against. If None, uses latest tag.
+
+        Returns:
+            List of commit messages since tag
+        """
+        try:
+            if tag_name is None:
+                # Get latest tag
+                tag_result = self._run_command(['git', 'describe', '--tags', '--abbrev=0'])
+                tag_name = tag_result.stdout.strip()
+
+            # Get commits since tag
+            log_result = self._run_command([
+                'git', 'log', f'{tag_name}..HEAD', '--oneline', '--no-merges'
+            ])
+
+            commits = []
+            for line in log_result.stdout.strip().split('\n'):
+                if line:
+                    commits.append(line)
+
+            return commits
+
+        except subprocess.CalledProcessError:
+            return []
+
+    def tag_exists(self, tag_name: str) -> bool:
+        """Check if a git tag exists.
+
+        Args:
+            tag_name: Tag name to check
+
+        Returns:
+            True if tag exists, False otherwise
+        """
+        try:
+            self._run_command(['git', 'rev-parse', f'refs/tags/{tag_name}'])
+            return True
+        except subprocess.CalledProcessError:
+            return False
+
+    def get_remote_url(self, remote: str = 'origin') -> Optional[str]:
+        """Get the URL of a git remote.
+
+        Args:
+            remote: Remote name (default: 'origin')
+
+        Returns:
+            Remote URL or None if not found
+        """
+        try:
+            result = self._run_command(['git', 'remote', 'get-url', remote])
+            return result.stdout.strip()
+        except subprocess.CalledProcessError:
+            return None
+
+    def get_unpushed_tags(self, remote: str = 'origin') -> List[str]:
+        """Get list of tags that exist locally but not on remote.
+
+        Args:
+            remote: Remote name to compare against (default: 'origin')
+
+        Returns:
+            List of unpushed tag names
+        """
+        try:
+            # Get local tags
+            local_result = self._run_command(['git', 'tag', '-l'])
+            local_tags = set(tag.strip() for tag in local_result.stdout.strip().split('\n') if tag.strip())
+
+            # Get remote tags
+            try:
+                remote_result = self._run_command(['git', 'ls-remote', '--tags', remote])
+                remote_lines = remote_result.stdout.strip().split('\n')
+
+                # Parse remote tags (format: "hash refs/tags/tagname")
+                remote_tags = set()
+                for line in remote_lines:
+                    if not line:
+                        continue
+                    parts = line.split('refs/tags/')
+                    if len(parts) > 1:
+                        # Remove ^{} suffix for annotated tags
+                        tag_name = parts[1].replace('^{}', '')
+                        remote_tags.add(tag_name)
+
+                # Find tags that are local but not remote
+                unpushed = sorted(local_tags - remote_tags)
+                return unpushed
+
+            except subprocess.CalledProcessError:
+                # Remote not available, assume all tags are unpushed
+                return sorted(local_tags)
+
+        except subprocess.CalledProcessError:
+            return []
+
+    def _run_command(self, cmd: List[str]) -> subprocess.CompletedProcess:
+        """Run a git command.
+
+        Args:
+            cmd: Command to execute
+
+        Returns:
+            CompletedProcess result
+
+        Raises:
+            subprocess.CalledProcessError: If command fails
+        """
+        if self.dry_run and not any(read_only in cmd for read_only in
+                                   ['status', 'branch', 'rev-parse', 'describe',
+                                    'log', 'remote']):
+            print(f"[DRY RUN] Would run: {' '.join(cmd)}")
+            return subprocess.CompletedProcess(cmd, 0, "", "")
+
+        return subprocess.run(
+            cmd,
+            capture_output=True,
+            text=True,
+            check=True,
+            cwd=self.project_root
+        )

capabilities/release-management/src/release_management/registries/__init__.py

@@ -0,0 +1,23 @@
+"""
+Package registry implementations.
+
+This module provides registry clients for publishing packages to various platforms:
+- Gitea package registries
+- PyPI and Test PyPI
+- Extensible factory for custom registries
+"""
+
+from .factory import RegistryFactory
+from .base import RegistryInterface, RegistryConfig
+from .gitea.registry import GiteaRegistry
+from .gitea.config import GiteaConfig
+from .gitea.exceptions import GiteaError
+
+__all__ = [
+    "RegistryFactory",
+    "RegistryInterface",
+    "RegistryConfig",
+    "GiteaRegistry",
+    "GiteaConfig",
+    "GiteaError",
+]

capabilities/release-management/src/release_management/registries/base.py

@@ -0,0 +1,101 @@
+"""
+Base registry interface and configuration.
+
+This module defines the common interface that all registry implementations must follow.
+"""
+
+from abc import ABC, abstractmethod
+from pathlib import Path
+from typing import Dict, List, Optional, Any
+from dataclasses import dataclass
+
+
+@dataclass
+class RegistryConfig:
+    """Base configuration for package registries."""
+    name: str
+    type: str
+    url: str
+    auth_token_env: Optional[str] = None
+
+    def get_auth_token(self) -> Optional[str]:
+        """Get authentication token from environment variable."""
+        if self.auth_token_env:
+            import os
+            return os.getenv(self.auth_token_env)
+        return None
+
+
+class RegistryInterface(ABC):
+    """Abstract interface for package registries."""
+
+    def __init__(self, config: RegistryConfig):
+        """Initialize the registry with configuration."""
+        self.config = config
+
+    @abstractmethod
+    def upload_package(self, package_path: Path, dry_run: bool = False) -> bool:
+        """Upload a package to the registry.
+
+        Args:
+            package_path: Path to package file (.whl or .tar.gz)
+            dry_run: If True, show what would be done without uploading
+
+        Returns:
+            True if upload successful, False otherwise
+        """
+        pass
+
+    @abstractmethod
+    def check_auth(self) -> bool:
+        """Check if authentication is properly configured.
+
+        Returns:
+            True if authenticated, False otherwise
+        """
+        pass
+
+    @abstractmethod
+    def list_packages(self) -> List[Dict[str, Any]]:
+        """List packages in the registry.
+
+        Returns:
+            List of package information dictionaries
+        """
+        pass
+
+    @abstractmethod
+    def get_package_info(self, package_name: str) -> Optional[Dict[str, Any]]:
+        """Get information about a specific package.
+
+        Args:
+            package_name: Name of the package
+
+        Returns:
+            Package information dictionary or None if not found
+        """
+        pass
+
+    @abstractmethod
+    def delete_package_version(self, package_name: str, version: str,
+                              dry_run: bool = False) -> bool:
+        """Delete a specific version of a package.
+
+        Args:
+            package_name: Name of the package
+            version: Version to delete
+            dry_run: If True, show what would be done without deleting
+
+        Returns:
+            True if deletion successful, False otherwise
+        """
+        pass
+
+    @abstractmethod
+    def get_registry_info(self) -> Dict[str, Any]:
+        """Get information about the registry configuration.
+
+        Returns:
+            Dictionary with registry information
+        """
+        pass

capabilities/release-management/src/release_management/registries/factory.py

@@ -0,0 +1,159 @@
+"""
+Registry factory for creating registry clients.
+
+This module provides a factory for creating appropriate registry clients
+based on configuration or registry type.
+"""
+
+from typing import Dict, Type, Optional, Any
+from pathlib import Path
+
+from .base import RegistryInterface, RegistryConfig
+from .gitea.registry import GiteaRegistry
+from .gitea.config import GiteaConfig
+
+
+class RegistryFactory:
+    """Factory for creating registry clients."""
+
+    _registry_types: Dict[str, Type[RegistryInterface]] = {
+        'gitea': GiteaRegistry,
+    }
+
+    @classmethod
+    def create(cls, registry_type: str, config: Optional[Dict[str, Any]] = None) -> RegistryInterface:
+        """Create a registry client of the specified type.
+
+        Args:
+            registry_type: Type of registry ('gitea', 'pypi', etc.)
+            config: Optional configuration dictionary
+
+        Returns:
+            Registry client instance
+
+        Raises:
+            ValueError: If registry type is not supported
+        """
+        if registry_type not in cls._registry_types:
+            raise ValueError(f"Unsupported registry type: {registry_type}. "
+                           f"Supported types: {list(cls._registry_types.keys())}")
+
+        registry_class = cls._registry_types[registry_type]
+
+        # Handle Gitea-specific configuration
+        if registry_type == 'gitea':
+            if config:
+                gitea_config = GiteaConfig(
+                    gitea_url=config.get('url', ''),
+                    repo_owner=config.get('owner', ''),
+                    repo_name=config.get('repo', ''),
+                    auth_token=config.get('auth_token')
+                )
+                return registry_class(gitea_config)
+            else:
+                # Auto-detect from git repository
+                return registry_class()
+
+        # For other registry types, create with generic config
+        if config:
+            registry_config = RegistryConfig(
+                name=config.get('name', registry_type),
+                type=registry_type,
+                url=config['url'],
+                auth_token_env=config.get('auth_token_env')
+            )
+            return registry_class(registry_config)
+        else:
+            raise ValueError(f"Configuration required for {registry_type} registry")
+
+    @classmethod
+    def create_from_pyproject_config(cls, pyproject_path: Optional[Path] = None,
+                                   registry_name: str = 'gitea') -> RegistryInterface:
+        """Create a registry client from pyproject.toml configuration.
+
+        Args:
+            pyproject_path: Path to pyproject.toml file. If None, looks in current directory.
+            registry_name: Name of registry configuration to use
+
+        Returns:
+            Registry client instance
+
+        Raises:
+            ValueError: If configuration is invalid or registry not found
+        """
+        if pyproject_path is None:
+            pyproject_path = Path.cwd() / "pyproject.toml"
+
+        if not pyproject_path.exists():
+            raise ValueError(f"pyproject.toml not found at {pyproject_path}")
+
+        try:
+            import tomllib
+        except ImportError:
+            try:
+                import tomli as tomllib  # Fallback for Python < 3.11
+            except ImportError:
+                raise ImportError("tomllib or tomli required to read pyproject.toml")
+
+        with open(pyproject_path, 'rb') as f:
+            config = tomllib.load(f)
+
+        # Look for release-management configuration
+        release_config = config.get('tool', {}).get('release-management', {})
+        registries_config = release_config.get('registries', {})
+
+        if registry_name not in registries_config:
+            raise ValueError(f"Registry '{registry_name}' not found in pyproject.toml configuration")
+
+        registry_config = registries_config[registry_name]
+        registry_type = registry_config.get('type', registry_name)
+
+        # Add auth token from environment if specified
+        auth_token_env = registry_config.get('auth_token_env')
+        if auth_token_env:
+            import os
+            registry_config = registry_config.copy()
+            registry_config['auth_token'] = os.getenv(auth_token_env)
+
+        return cls.create(registry_type, registry_config)
+
+    @classmethod
+    def auto_detect(cls) -> RegistryInterface:
+        """Auto-detect registry type from current environment.
+
+        Currently only supports Gitea auto-detection from git repository.
+
+        Returns:
+            Registry client instance
+
+        Raises:
+            ValueError: If no registry can be auto-detected
+        """
+        # Try Gitea auto-detection first
+        try:
+            return cls.create('gitea')
+        except Exception:
+            pass
+
+        raise ValueError("Could not auto-detect registry type. "
+                        "Ensure you're in a git repository with Gitea remote, "
+                        "or provide explicit configuration.")
+
+    @classmethod
+    def register_registry_type(cls, registry_type: str, registry_class: Type[RegistryInterface]) -> None:
+        """Register a new registry type.
+
+        Args:
+            registry_type: String identifier for the registry type
+            registry_class: Registry class that implements RegistryInterface
+        """
+        cls._registry_types[registry_type] = registry_class
+
+    @classmethod
+    def list_supported_types(cls) -> list[str]:
+        """List all supported registry types.
+
+        Returns:
+            List of supported registry type strings
+        """
+        return list(cls._registry_types.keys())

capabilities/release-management/src/release_management/registries/gitea/__init__.py

@@ -0,0 +1,14 @@
+"""
+Gitea package registry implementation.
+
+This module provides Gitea-specific registry functionality including:
+- Package registry uploads
+- Release asset fallback
+- Configuration and authentication
+"""
+
+from .registry import GiteaRegistry
+from .config import GiteaConfig
+from .exceptions import GiteaError, GiteaConfigError
+
+__all__ = ["GiteaRegistry", "GiteaConfig", "GiteaError", "GiteaConfigError"]

capabilities/release-management/src/release_management/registries/gitea/config.py

@@ -172,4 +172,4 @@ class GiteaConfig:
     def requires_auth(self, operation: str = "read") -> bool:
         """Check if operation requires authentication."""
         write_operations = {"create", "update", "delete", "write"}
-        return operation in write_operations and not self.auth_token
+        return operation in write_operations and not self.auth_token

capabilities/release-management/src/release_management/registries/gitea/exceptions.py

@@ -0,0 +1,23 @@
+"""
+Gitea-specific exceptions.
+"""
+
+
+class GiteaError(Exception):
+    """Base class for Gitea-related errors."""
+    pass
+
+
+class GiteaConfigError(GiteaError):
+    """Configuration-related errors."""
+    pass
+
+
+class GiteaApiError(GiteaError):
+    """API-related errors."""
+    pass
+
+
+class GiteaAuthError(GiteaError):
+    """Authentication-related errors."""
+    pass

capabilities/release-management/src/release_management/registries/gitea/registry.py

@@ -0,0 +1,355 @@
+"""
+Gitea Package Registry Client
+
+This module provides functionality to publish Python packages to Gitea's package registry.
+Gitea supports multiple package registries including PyPI-compatible registries.
+"""
+
+import os
+from pathlib import Path
+from typing import Optional, List, Dict, Any
+
+from ..base import RegistryInterface
+from .config import GiteaConfig
+from .exceptions import GiteaError
+
+
+class GiteaRegistry(RegistryInterface):
+    """Client for publishing packages to Gitea package registry."""
+
+    def __init__(self, config: Optional[GiteaConfig] = None):
+        """Initialize the package registry client.
+
+        Args:
+            config: Gitea configuration. If None, auto-detects from git repository.
+        """
+        self.config = config or GiteaConfig.from_git_repository()
+        self.config.validate()
+
+    @property
+    def pypi_registry_url(self) -> str:
+        """Get the PyPI-compatible registry URL for this repository."""
+        return f"{self.config.gitea_url}/api/packages/{self.config.repo_owner}/pypi"
+
+    @property
+    def package_list_url(self) -> str:
+        """Get the package listing URL for this repository."""
+        return f"{self.config.gitea_url}/api/v1/packages/{self.config.repo_owner}"
+
+    def check_auth(self) -> bool:
+        """Check if authentication token is available and valid."""
+        if not self.config.auth_token:
+            return False
+
+        try:
+            # Test auth by trying to access packages API
+            import requests
+            headers = {"Authorization": f"token {self.config.auth_token}"}
+            response = requests.get(self.package_list_url, headers=headers, timeout=10)
+            return response.status_code in [200, 404]  # 404 is okay if no packages exist yet
+        except Exception:
+            return False
+
+    def list_packages(self) -> List[Dict[str, Any]]:
+        """List all packages for this repository owner.
+
+        Returns:
+            List of package information dictionaries
+        """
+        try:
+            import requests
+            headers = {}
+            if self.config.auth_token:
+                headers["Authorization"] = f"token {self.config.auth_token}"
+
+            response = requests.get(self.package_list_url, headers=headers, timeout=10)
+            response.raise_for_status()
+            return response.json()
+        except Exception as e:
+            raise GiteaError(f"Failed to list packages: {e}")
+
+    def get_package_info(self, package_name: str) -> Optional[Dict[str, Any]]:
+        """Get information about a specific package.
+
+        Args:
+            package_name: Name of the package
+
+        Returns:
+            Package information dictionary or None if not found
+        """
+        try:
+            packages = self.list_packages()
+            for package in packages:
+                if package.get("name") == package_name:
+                    return package
+            return None
+        except Exception:
+            return None
+
+    def upload_package(self, package_path: Path, dry_run: bool = False) -> bool:
+        """Upload a package to Gitea registry.
+
+        Args:
+            package_path: Path to package file (.whl or .tar.gz)
+            dry_run: If True, show what would be done without uploading
+
+        Returns:
+            True if upload successful, False otherwise
+        """
+        if not self.config.auth_token:
+            raise GiteaError("Authentication token required for package upload. Set GITEA_API_TOKEN environment variable.")
+
+        if not package_path.exists():
+            raise GiteaError(f"Package file not found: {package_path}")
+
+        if dry_run:
+            print(f"[DRY RUN] Would upload to: {self.pypi_registry_url}")
+            print(f"[DRY RUN] Would upload: {package_path}")
+            return True
+
+        return self._upload_file(package_path)
+
+    def upload_package_as_release_assets(self,
+                                        version: str,
+                                        wheel_path: Path,
+                                        sdist_path: Optional[Path] = None,
+                                        dry_run: bool = False) -> bool:
+        """Upload packages as Gitea release assets (fallback when package registry unavailable).
+
+        Args:
+            version: Version tag (e.g., "v0.8.0")
+            wheel_path: Path to wheel (.whl) file
+            sdist_path: Optional path to source distribution (.tar.gz) file
+            dry_run: If True, show what would be done without uploading
+
+        Returns:
+            True if upload successful, False otherwise
+        """
+        if not self.config.auth_token:
+            raise GiteaError("Authentication token required for release upload. Set GITEA_API_TOKEN environment variable.")
+
+        if not wheel_path.exists():
+            raise GiteaError(f"Wheel file not found: {wheel_path}")
+
+        if sdist_path and not sdist_path.exists():
+            raise GiteaError(f"Source distribution file not found: {sdist_path}")
+
+        files_to_upload = [wheel_path]
+        if sdist_path:
+            files_to_upload.append(sdist_path)
+
+        if dry_run:
+            print(f"[DRY RUN] Would upload release assets for {version}")
+            print(f"[DRY RUN] Release API: {self.config.repo_api_url}/releases")
+            for file_path in files_to_upload:
+                print(f"[DRY RUN] Would upload: {file_path}")
+            return True
+
+        # Create or get release
+        release_id = self._create_or_get_release(version)
+        if not release_id:
+            return False
+
+        # Upload each file as release asset
+        success = True
+        for file_path in files_to_upload:
+            if not self._upload_release_asset(release_id, file_path):
+                success = False
+
+        return success
+
+    def delete_package_version(self, package_name: str, version: str,
+                              dry_run: bool = False) -> bool:
+        """Delete a specific version of a package.
+
+        Args:
+            package_name: Name of the package
+            version: Version to delete
+            dry_run: If True, show what would be done without deleting
+
+        Returns:
+            True if deletion successful, False otherwise
+        """
+        if not self.config.auth_token:
+            raise GiteaError("Authentication token required for package deletion.")
+
+        delete_url = f"{self.config.gitea_url}/api/v1/packages/{self.config.repo_owner}/pypi/{package_name}/{version}"
+
+        if dry_run:
+            print(f"[DRY RUN] Would delete: {package_name} v{version}")
+            print(f"[DRY RUN] DELETE {delete_url}")
+            return True
+
+        try:
+            import requests
+            headers = {"Authorization": f"token {self.config.auth_token}"}
+            response = requests.delete(delete_url, headers=headers, timeout=10)
+
+            if response.status_code in [200, 204, 404]:  # 404 = already deleted
+                print(f"✅ Deleted: {package_name} v{version}")
+                return True
+            else:
+                print(f"❌ Delete failed: {response.status_code} {response.text}")
+                return False
+
+        except Exception as e:
+            print(f"❌ Delete failed: {e}")
+            return False
+
+    def get_registry_info(self) -> Dict[str, Any]:
+        """Get information about the package registry configuration.
+
+        Returns:
+            Dictionary with registry information
+        """
+        return {
+            "gitea_url": self.config.gitea_url,
+            "repo_owner": self.config.repo_owner,
+            "repo_name": self.config.repo_name,
+            "pypi_registry_url": self.pypi_registry_url,
+            "package_list_url": self.package_list_url,
+            "auth_configured": bool(self.config.auth_token),
+            "auth_valid": self.check_auth() if self.config.auth_token else False
+        }
+
+    def _upload_file(self, file_path: Path) -> bool:
+        """Upload a single file to the registry.
+
+        Args:
+            file_path: Path to file to upload
+
+        Returns:
+            True if upload successful, False otherwise
+        """
+        try:
+            import requests
+
+            # Gitea PyPI upload API expects PUT with the file content as body
+            # URL format: /api/packages/{owner}/pypi/{filename}
+            upload_url = f"{self.config.gitea_url}/api/packages/{self.config.repo_owner}/pypi"
+
+            with open(file_path, 'rb') as f:
+                file_content = f.read()
+
+            headers = {
+                'Authorization': f'token {self.config.auth_token}',
+                'Content-Type': 'application/octet-stream'
+            }
+
+            # Upload using PUT request with filename in URL
+            upload_endpoint = f"{upload_url}/{file_path.name}"
+            response = requests.put(
+                upload_endpoint,
+                headers=headers,
+                data=file_content,
+                timeout=60
+            )
+
+            if response.status_code in [200, 201, 409]:  # 409 = already exists
+                print(f"✅ Uploaded: {file_path.name}")
+                if response.status_code == 409:
+                    print(f"   (already exists)")
+                return True
+            else:
+                print(f"❌ Upload failed for {file_path.name}: {response.status_code}")
+                if response.text:
+                    print(f"   Error: {response.text}")
+                return False
+
+        except Exception as e:
+            print(f"❌ Upload failed for {file_path.name}: {e}")
+            return False
+
+    def _create_or_get_release(self, version: str) -> Optional[int]:
+        """Create a new release or get existing release ID.
+
+        Args:
+            version: Version tag (e.g., "v0.8.0")
+
+        Returns:
+            Release ID if successful, None otherwise
+        """
+        try:
+            import requests
+
+            # Ensure version has 'v' prefix
+            tag_name = version if version.startswith('v') else f'v{version}'
+
+            headers = {"Authorization": f"token {self.config.auth_token}"}
+
+            # First, try to get existing release
+            releases_url = f"{self.config.repo_api_url}/releases"
+            response = requests.get(releases_url, headers=headers, timeout=10)
+
+            if response.status_code == 200:
+                releases = response.json()
+                for release in releases:
+                    if release.get('tag_name') == tag_name:
+                        print(f"✅ Found existing release: {tag_name}")
+                        return release['id']
+
+            # Create new release
+            release_data = {
+                "tag_name": tag_name,
+                "name": f"MarkiTect {version.lstrip('v')}",
+                "body": f"Release {version.lstrip('v')}\\n\\nPython packages for MarkiTect.",
+                "draft": False,
+                "prerelease": False
+            }
+
+            response = requests.post(releases_url, headers=headers, json=release_data, timeout=10)
+
+            if response.status_code == 201:
+                release = response.json()
+                print(f"✅ Created release: {tag_name}")
+                return release['id']
+            else:
+                print(f"❌ Failed to create release: {response.status_code} {response.text}")
+                return None
+
+        except Exception as e:
+            print(f"❌ Error managing release: {e}")
+            return None
+
+    def _upload_release_asset(self, release_id: int, file_path: Path) -> bool:
+        """Upload a file as a release asset.
+
+        Args:
+            release_id: Gitea release ID
+            file_path: Path to file to upload
+
+        Returns:
+            True if upload successful, False otherwise
+        """
+        try:
+            import requests
+
+            # Upload asset to Gitea release
+            upload_url = f"{self.config.repo_api_url}/releases/{release_id}/assets"
+
+            headers = {
+                "Authorization": f"token {self.config.auth_token}"
+            }
+
+            with open(file_path, 'rb') as f:
+                files = {
+                    'attachment': (file_path.name, f, 'application/octet-stream')
+                }
+
+                response = requests.post(
+                    upload_url,
+                    headers=headers,
+                    files=files,
+                    timeout=120  # Larger timeout for file uploads
+                )
+
+            if response.status_code == 201:
+                print(f"✅ Uploaded release asset: {file_path.name}")
+                return True
+            else:
+                print(f"❌ Failed to upload {file_path.name}: {response.status_code} {response.text}")
+                return False
+
+        except Exception as e:
+            print(f"❌ Upload failed for {file_path.name}: {e}")
+            return False

capabilities/release-management/src/release_management/summary/__init__.py

@@ -0,0 +1,9 @@
+"""
+Release summary generation tools.
+
+This package provides tools for generating release summary documents.
+"""
+
+from .generator import SummaryGenerator
+
+__all__ = ['SummaryGenerator']

capabilities/release-management/src/release_management/summary/generator.py

@@ -0,0 +1,305 @@
+"""
+Release summary generator.
+
+This module generates comprehensive release summary documents from
+CHANGELOG content and git metadata.
+"""
+
+import subprocess
+from datetime import datetime
+from pathlib import Path
+from typing import Optional, Dict, Any, List
+import re
+
+
+class SummaryGenerator:
+    """Generate release summary documents."""
+
+    def __init__(self, project_root: Optional[Path] = None):
+        """Initialize summary generator.
+
+        Args:
+            project_root: Root directory of the project
+        """
+        self.project_root = project_root or Path.cwd()
+        self.changelog_path = self.project_root / 'CHANGELOG.md'
+        self.dist_dir = self.project_root / 'dist'
+
+    def generate(self, version: str, output_path: Optional[Path] = None) -> str:
+        """Generate release summary document.
+
+        Args:
+            version: Version to generate summary for (e.g., "0.10.0")
+            output_path: Optional path to write summary to
+
+        Returns:
+            Generated summary content
+        """
+        version_clean = version.lstrip('v')
+        tag_name = f"v{version_clean}"
+
+        # Get components
+        changelog_section = self.extract_changelog_section(version_clean)
+        git_stats = self.get_git_statistics(tag_name)
+        build_artifacts = self.list_build_artifacts()
+        validation_results = self.get_validation_results()
+
+        # Determine project name
+        project_name = self._get_project_name()
+
+        # Build summary
+        summary = f"""# {project_name} {version_clean} Release Summary
+
+**Release Date**: {git_stats.get('release_date', 'Unknown')}
+**Git Tag**: {tag_name}
+**Commit**: {git_stats.get('commit_hash', 'Unknown')}
+
+---
+
+## Changes
+
+{changelog_section}
+
+---
+
+## Git Statistics
+
+- **Commits**: {git_stats.get('commit_count', 0)} commit(s) since last release
+- **Files Changed**: {git_stats.get('files_changed', 0)} file(s)
+- **Insertions**: +{git_stats.get('insertions', 0)} lines
+- **Deletions**: -{git_stats.get('deletions', 0)} lines
+- **Contributors**: {git_stats.get('contributors', 'Unknown')}
+
+---
+
+## Build Artifacts
+
+{build_artifacts}
+
+---
+
+## Validation
+
+{validation_results}
+
+---
+
+**Generated**: {datetime.now().strftime("%Y-%m-%d %H:%M:%S")}
+"""
+
+        if output_path:
+            output_path.write_text(summary)
+            print(f"✅ Release summary written to {output_path}")
+
+        return summary
+
+    def extract_changelog_section(self, version: str) -> str:
+        """Extract CHANGELOG section for a specific version.
+
+        Args:
+            version: Version to extract (e.g., "0.10.0")
+
+        Returns:
+            Markdown content of the version section
+        """
+        if not self.changelog_path.exists():
+            return "⚠️ CHANGELOG.md not found"
+
+        try:
+            with open(self.changelog_path) as f:
+                content = f.read()
+
+            # Find the version section
+            pattern = rf"## \[{re.escape(version)}\].*?\n\n(.*?)(?=\n## \[|\Z)"
+            match = re.search(pattern, content, re.DOTALL)
+
+            if match:
+                section_content = match.group(1).strip()
+                return section_content if section_content else "No changes documented"
+            else:
+                return f"⚠️ No section found for version {version} in CHANGELOG.md"
+
+        except Exception as e:
+            return f"❌ Error reading CHANGELOG: {e}"
+
+    def get_git_statistics(self, tag: str) -> Dict[str, Any]:
+        """Get git statistics for a release tag.
+
+        Args:
+            tag: Git tag name (e.g., "v0.10.0")
+
+        Returns:
+            Dictionary with git statistics
+        """
+        stats = {}
+
+        try:
+            # Get tag date
+            try:
+                result = subprocess.run(
+                    ['git', 'log', '-1', '--format=%ci', tag],
+                    capture_output=True, text=True, check=True, cwd=self.project_root
+                )
+                date_str = result.stdout.strip()
+                # Parse to get just the date
+                stats['release_date'] = date_str.split()[0] if date_str else 'Unknown'
+            except subprocess.CalledProcessError:
+                stats['release_date'] = 'Unknown'
+
+            # Get commit hash
+            try:
+                result = subprocess.run(
+                    ['git', 'rev-parse', tag],
+                    capture_output=True, text=True, check=True, cwd=self.project_root
+                )
+                stats['commit_hash'] = result.stdout.strip()[:8]
+            except subprocess.CalledProcessError:
+                stats['commit_hash'] = 'Unknown'
+
+            # Find previous tag
+            try:
+                result = subprocess.run(
+                    ['git', 'describe', '--tags', '--abbrev=0', f'{tag}^'],
+                    capture_output=True, text=True, check=True, cwd=self.project_root
+                )
+                previous_tag = result.stdout.strip()
+            except subprocess.CalledProcessError:
+                # No previous tag, use initial commit
+                previous_tag = None
+
+            # Get commit count
+            if previous_tag:
+                try:
+                    result = subprocess.run(
+                        ['git', 'rev-list', '--count', f'{previous_tag}..{tag}'],
+                        capture_output=True, text=True, check=True, cwd=self.project_root
+                    )
+                    stats['commit_count'] = int(result.stdout.strip())
+                except subprocess.CalledProcessError:
+                    stats['commit_count'] = 0
+            else:
+                try:
+                    result = subprocess.run(
+                        ['git', 'rev-list', '--count', tag],
+                        capture_output=True, text=True, check=True, cwd=self.project_root
+                    )
+                    stats['commit_count'] = int(result.stdout.strip())
+                except subprocess.CalledProcessError:
+                    stats['commit_count'] = 0
+
+            # Get file changes, insertions, deletions
+            if previous_tag:
+                diff_range = f'{previous_tag}..{tag}'
+            else:
+                diff_range = tag
+
+            try:
+                result = subprocess.run(
+                    ['git', 'diff', '--shortstat', diff_range],
+                    capture_output=True, text=True, check=True, cwd=self.project_root
+                )
+                shortstat = result.stdout.strip()
+
+                # Parse shortstat: "X files changed, Y insertions(+), Z deletions(-)"
+                files_match = re.search(r'(\d+) files? changed', shortstat)
+                insert_match = re.search(r'(\d+) insertions?', shortstat)
+                delete_match = re.search(r'(\d+) deletions?', shortstat)
+
+                stats['files_changed'] = int(files_match.group(1)) if files_match else 0
+                stats['insertions'] = int(insert_match.group(1)) if insert_match else 0
+                stats['deletions'] = int(delete_match.group(1)) if delete_match else 0
+            except subprocess.CalledProcessError:
+                stats['files_changed'] = 0
+                stats['insertions'] = 0
+                stats['deletions'] = 0
+
+            # Get contributors
+            try:
+                result = subprocess.run(
+                    ['git', 'log', '--format=%an', f'{previous_tag}..{tag}' if previous_tag else tag],
+                    capture_output=True, text=True, check=True, cwd=self.project_root
+                )
+                contributors = list(set(result.stdout.strip().split('\n')))
+                stats['contributors'] = ', '.join(contributors) if contributors and contributors[0] else 'Unknown'
+            except subprocess.CalledProcessError:
+                stats['contributors'] = 'Unknown'
+
+        except Exception as e:
+            print(f"⚠️  Error getting git statistics: {e}")
+
+        return stats
+
+    def list_build_artifacts(self) -> str:
+        """List build artifacts in dist/ directory.
+
+        Returns:
+            Formatted markdown list of build artifacts
+        """
+        if not self.dist_dir.exists():
+            return "No build artifacts found (dist/ directory does not exist)"
+
+        artifacts = list(self.dist_dir.glob('*'))
+        if not artifacts:
+            return "No build artifacts found in dist/"
+
+        lines = []
+        for artifact in sorted(artifacts):
+            if artifact.is_file():
+                size = artifact.stat().st_size
+                size_kb = size / 1024
+                size_mb = size / (1024 * 1024)
+
+                if size_mb >= 1:
+                    size_str = f"{size_mb:.2f} MB"
+                else:
+                    size_str = f"{size_kb:.2f} KB"
+
+                lines.append(f"- **{artifact.name}** ({size_str})")
+
+        return '\n'.join(lines) if lines else "No build artifacts found"
+
+    def get_validation_results(self) -> str:
+        """Get validation results summary.
+
+        Returns:
+            Formatted validation results
+        """
+        # Import here to avoid circular dependency
+        from ..utils.validation import ReleaseValidator
+
+        validator = ReleaseValidator(self.project_root)
+        is_valid, issues = validator.validate_release_state(force=True)  # Force to get all issues
+
+        if is_valid:
+            return "✅ All validation checks passed"
+        else:
+            lines = ["Validation Issues:"]
+            for issue in issues:
+                lines.append(f"- {issue}")
+            return '\n'.join(lines)
+
+    def _get_project_name(self) -> str:
+        """Get project name from pyproject.toml.
+
+        Returns:
+            Project name or default
+        """
+        pyproject_path = self.project_root / 'pyproject.toml'
+
+        if not pyproject_path.exists():
+            return "Project"
+
+        try:
+            import tomllib
+        except ImportError:
+            try:
+                import tomli as tomllib
+            except ImportError:
+                return "Project"
+
+        try:
+            with open(pyproject_path, 'rb') as f:
+                config = tomllib.load(f)
+                return config.get('project', {}).get('name', 'Project').title()
+        except Exception:
+            return "Project"

capabilities/release-management/src/release_management/utils/__init__.py

@@ -0,0 +1,11 @@
+"""
+Utilities for release management.
+
+This module provides utility functions for version management,
+validation, and other common operations.
+"""
+
+from .version import VersionManager
+from .validation import ReleaseValidator
+
+__all__ = ["VersionManager", "ReleaseValidator"]

capabilities/release-management/src/release_management/utils/validation.py

@@ -0,0 +1,350 @@
+"""
+Release validation utilities.
+
+This module provides validation functions for release readiness.
+"""
+
+import subprocess
+from pathlib import Path
+from typing import List, Tuple, Optional
+
+from ..git.manager import GitManager
+
+
+class ReleaseValidator:
+    """Validates release readiness and requirements."""
+
+    def __init__(self, project_root: Optional[Path] = None):
+        """Initialize release validator.
+
+        Args:
+            project_root: Root directory of the project
+        """
+        self.project_root = project_root or Path.cwd()
+        self.git_manager = GitManager(project_root)
+
+    def validate_release_state(self, force: bool = False) -> Tuple[bool, List[str]]:
+        """Validate that repository is ready for release.
+
+        Args:
+            force: Skip validation checks if True
+
+        Returns:
+            Tuple of (is_valid, list_of_issues)
+        """
+        if force:
+            return True, []
+
+        issues = []
+
+        # Git repository validation
+        git_issues = self._validate_git_state()
+        issues.extend(git_issues)
+
+        # Project structure validation
+        structure_issues = self._validate_project_structure()
+        issues.extend(structure_issues)
+
+        # Configuration validation
+        config_issues = self._validate_configuration()
+        issues.extend(config_issues)
+
+        # CHANGELOG validation
+        changelog_issues = self._validate_changelog()
+        issues.extend(changelog_issues)
+
+        return len(issues) == 0, issues
+
+    def _validate_git_state(self) -> List[str]:
+        """Validate git repository state.
+
+        Returns:
+            List of git-related issues
+        """
+        issues = []
+        status = self.git_manager.get_repository_status()
+
+        if not status['is_repo']:
+            issues.append("Not in a git repository")
+            return issues
+
+        if status['has_changes']:
+            issues.append("Repository has uncommitted changes")
+
+        if status['branch'] != 'main':
+            issues.append(f"Not on main branch (currently on {status['branch']})")
+
+        # Check if remote exists
+        remote_url = self.git_manager.get_remote_url()
+        if not remote_url:
+            issues.append("No git remote 'origin' configured")
+
+        return issues
+
+    def _validate_project_structure(self) -> List[str]:
+        """Validate project structure for releases.
+
+        Returns:
+            List of project structure issues
+        """
+        issues = []
+
+        # Check for required files
+        required_files = ['pyproject.toml']
+        for file_name in required_files:
+            file_path = self.project_root / file_name
+            if not file_path.exists():
+                issues.append(f"Missing required file: {file_name}")
+
+        # Check for setuptools-scm configuration
+        pyproject_path = self.project_root / 'pyproject.toml'
+        if pyproject_path.exists():
+            try:
+                import tomllib
+            except ImportError:
+                try:
+                    import tomli as tomllib
+                except ImportError:
+                    issues.append("Cannot read pyproject.toml (tomllib/tomli not available)")
+                    return issues
+
+            try:
+                with open(pyproject_path, 'rb') as f:
+                    config = tomllib.load(f)
+
+                # Check for setuptools-scm configuration
+                build_system = config.get('build-system', {})
+                if 'setuptools-scm' not in str(build_system.get('requires', [])):
+                    issues.append("setuptools-scm not found in build-system.requires")
+
+                # Check for dynamic version
+                project_config = config.get('project', {})
+                if 'version' in project_config:
+                    issues.append("Static version found in project config. Use dynamic versioning with setuptools-scm.")
+
+                dynamic = project_config.get('dynamic', [])
+                if 'version' not in dynamic:
+                    issues.append("'version' not in project.dynamic. Add it for setuptools-scm.")
+
+            except Exception as e:
+                issues.append(f"Error reading pyproject.toml: {e}")
+
+        return issues
+
+    def _validate_configuration(self) -> List[str]:
+        """Validate release configuration.
+
+        Returns:
+            List of configuration issues
+        """
+        issues = []
+
+        # Check for environment variables that might be needed
+        import os
+
+        # Check for common auth tokens (warn, don't fail)
+        auth_vars = ['GITEA_API_TOKEN', 'PYPI_TOKEN', 'GITHUB_TOKEN']
+        available_auth = [var for var in auth_vars if os.getenv(var)]
+
+        if not available_auth:
+            issues.append("No authentication tokens found in environment. "
+                         "Consider setting GITEA_API_TOKEN, PYPI_TOKEN, or GITHUB_TOKEN "
+                         "for package publishing.")
+
+        return issues
+
+    def validate_version_string(self, version_string: str) -> Tuple[bool, List[str]]:
+        """Validate a version string for release.
+
+        Args:
+            version_string: Version string to validate
+
+        Returns:
+            Tuple of (is_valid, list_of_issues)
+        """
+        issues = []
+
+        if not version_string:
+            issues.append("Version string cannot be empty")
+            return False, issues
+
+        # Check basic format
+        if not version_string.replace('.', '').replace('-', '').replace('+', '').replace('a', '').replace('b', '').replace('rc', '').isalnum():
+            issues.append("Version string contains invalid characters")
+
+        # Check for development markers in release
+        dev_markers = ['dev', '.dev', '+dev']
+        if any(marker in version_string.lower() for marker in dev_markers):
+            issues.append("Development versions should not be released")
+
+        # Check for reasonable version format (semantic versioning)
+        try:
+            from packaging import version
+            version.Version(version_string)
+        except Exception:
+            issues.append("Version string is not valid according to PEP 440")
+
+        # Check if version already exists as git tag
+        tag_name = version_string if version_string.startswith('v') else f'v{version_string}'
+        if self.git_manager.tag_exists(tag_name):
+            issues.append(f"Git tag {tag_name} already exists")
+
+        return len(issues) == 0, issues
+
+    def _validate_changelog(self) -> List[str]:
+        """Validate CHANGELOG.md using changelog schema.
+
+        Returns:
+            List of CHANGELOG-related issues
+        """
+        issues = []
+        changelog_path = self.project_root / 'CHANGELOG.md'
+
+        # Check if CHANGELOG exists
+        if not changelog_path.exists():
+            issues.append("Missing CHANGELOG.md file")
+            return issues
+
+        # Check if changelog schema exists
+        schema_path = self.project_root / 'markitect' / 'schemas' / 'changelog-schema-v1.0.md'
+        if not schema_path.exists():
+            # Schema doesn't exist, skip validation
+            return issues
+
+        # Validate CHANGELOG with schema using markitect validate command
+        try:
+            result = subprocess.run(
+                [
+                    'markitect', 'validate', str(changelog_path),
+                    '--schema', str(schema_path),
+                    '--semantic'
+                ],
+                capture_output=True,
+                text=True,
+                cwd=self.project_root
+            )
+
+            if result.returncode != 0:
+                issues.append("CHANGELOG.md validation failed against schema")
+                # Parse output for specific errors
+                if 'Unreleased section' in result.stdout:
+                    issues.append("  - Missing [Unreleased] section in CHANGELOG")
+                if 'version format' in result.stdout.lower():
+                    issues.append("  - Invalid version format in CHANGELOG")
+
+        except FileNotFoundError:
+            # markitect command not available
+            issues.append("Cannot validate CHANGELOG (markitect command not found)")
+        except Exception as e:
+            issues.append(f"Error validating CHANGELOG: {e}")
+
+        return issues
+
+    def validate_changelog_version(self, version: str) -> Tuple[bool, List[str]]:
+        """Validate that CHANGELOG has section for specified version.
+
+        Args:
+            version: Version to check (e.g., "0.10.0")
+
+        Returns:
+            Tuple of (is_valid, list_of_issues)
+        """
+        issues = []
+        changelog_path = self.project_root / 'CHANGELOG.md'
+
+        if not changelog_path.exists():
+            issues.append("CHANGELOG.md not found")
+            return False, issues
+
+        try:
+            content = changelog_path.read_text()
+
+            # Check for version section
+            version_header = f"## [{version}]"
+            if version_header not in content:
+                issues.append(f"CHANGELOG missing section for version {version}")
+
+            # Check for Unreleased section
+            if "## [Unreleased]" not in content:
+                issues.append("CHANGELOG missing [Unreleased] section")
+
+            # Check if version section has a date
+            import re
+            date_pattern = rf"## \[{re.escape(version)}\] - \d{{4}}-\d{{2}}-\d{{2}}"
+            if not re.search(date_pattern, content):
+                issues.append(f"Version {version} section missing date or has invalid date format")
+
+        except Exception as e:
+            issues.append(f"Error reading CHANGELOG: {e}")
+
+        return len(issues) == 0, issues
+
+    def check_version_tag_consistency(self, version: str) -> Tuple[bool, List[str]]:
+        """Check consistency between CHANGELOG version and git tags.
+
+        Args:
+            version: Version to check (e.g., "0.10.0")
+
+        Returns:
+            Tuple of (is_consistent, list_of_issues)
+        """
+        issues = []
+
+        # Check CHANGELOG has the version
+        changelog_valid, changelog_issues = self.validate_changelog_version(version)
+        if not changelog_valid:
+            issues.extend(changelog_issues)
+
+        # Check git tag exists
+        tag_name = version if version.startswith('v') else f'v{version}'
+        if not self.git_manager.tag_exists(tag_name):
+            issues.append(f"Git tag {tag_name} doesn't exist for version in CHANGELOG")
+
+        return len(issues) == 0, issues
+
+    def get_validation_summary(self) -> dict:
+        """Get a comprehensive validation summary.
+
+        Returns:
+            Dictionary with validation results
+        """
+        is_valid, issues = self.validate_release_state()
+
+        return {
+            'is_valid': is_valid,
+            'issues': issues,
+            'git_status': self.git_manager.get_repository_status(),
+            'recommendations': self._get_recommendations(issues)
+        }
+
+    def _get_recommendations(self, issues: List[str]) -> List[str]:
+        """Get recommendations based on validation issues.
+
+        Args:
+            issues: List of validation issues
+
+        Returns:
+            List of recommendations
+        """
+        recommendations = []
+
+        if any('uncommitted changes' in issue for issue in issues):
+            recommendations.append("Commit or stash your changes before releasing")
+
+        if any('not on main branch' in issue for issue in issues):
+            recommendations.append("Switch to main branch: git checkout main")
+
+        if any('setuptools-scm' in issue for issue in issues):
+            recommendations.append("Configure setuptools-scm in pyproject.toml")
+
+        if any('authentication' in issue.lower() for issue in issues):
+            recommendations.append("Set up authentication tokens for package publishing")
+
+        if any('CHANGELOG' in issue for issue in issues):
+            recommendations.append("Fix CHANGELOG.md format and ensure [Unreleased] section exists")
+            recommendations.append("Validate with: markitect validate CHANGELOG.md --schema changelog-schema-v1.0.md --semantic")
+
+        if not issues:
+            recommendations.append("Repository is ready for release!")
+
+        return recommendations

capabilities/release-management/src/release_management/utils/version.py

@@ -0,0 +1,298 @@
+"""
+Version management utilities.
+
+This module provides utilities for working with versions and setuptools-scm.
+"""
+
+import subprocess
+from pathlib import Path
+from typing import Optional, Dict, Any
+from packaging import version
+
+
+class VersionManager:
+    """Utilities for version management with setuptools-scm."""
+
+    def __init__(self, project_root: Optional[Path] = None):
+        """Initialize version manager.
+
+        Args:
+            project_root: Root directory of the project
+        """
+        self.project_root = project_root or Path.cwd()
+
+    def get_current_version(self) -> str:
+        """Get current version using setuptools-scm.
+
+        Returns:
+            Current version string or "unknown" if unavailable
+        """
+        try:
+            result = subprocess.run(
+                ['python', '-m', 'setuptools_scm'],
+                capture_output=True,
+                text=True,
+                check=True,
+                cwd=self.project_root
+            )
+            return result.stdout.strip()
+        except subprocess.CalledProcessError:
+            return "unknown"
+
+    def parse_version(self, version_string: str) -> Dict[str, Any]:
+        """Parse a version string and return components.
+
+        Args:
+            version_string: Version string to parse
+
+        Returns:
+            Dictionary with version components
+        """
+        try:
+            v = version.Version(version_string)
+            return {
+                'major': v.major,
+                'minor': v.minor,
+                'micro': v.micro,
+                'is_prerelease': v.is_prerelease,
+                'is_devrelease': v.is_devrelease,
+                'local': v.local,
+                'public': v.public,
+                'base_version': v.base_version,
+            }
+        except version.InvalidVersion:
+            return {'error': f'Invalid version: {version_string}'}
+
+    def is_development_version(self, version_string: Optional[str] = None) -> bool:
+        """Check if version is a development version.
+
+        Args:
+            version_string: Version to check. If None, uses current version.
+
+        Returns:
+            True if development version, False otherwise
+        """
+        if version_string is None:
+            version_string = self.get_current_version()
+
+        try:
+            v = version.Version(version_string)
+            return v.is_devrelease or 'dev' in version_string.lower()
+        except version.InvalidVersion:
+            return True  # Assume unknown versions are dev
+
+    def compare_versions(self, version1: str, version2: str) -> int:
+        """Compare two version strings.
+
+        Args:
+            version1: First version to compare
+            version2: Second version to compare
+
+        Returns:
+            -1 if version1 < version2, 0 if equal, 1 if version1 > version2
+        """
+        try:
+            v1 = version.Version(version1)
+            v2 = version.Version(version2)
+
+            if v1 < v2:
+                return -1
+            elif v1 > v2:
+                return 1
+            else:
+                return 0
+        except version.InvalidVersion:
+            # Fallback to string comparison
+            if version1 < version2:
+                return -1
+            elif version1 > version2:
+                return 1
+            else:
+                return 0
+
+    def get_next_version(self, current_version: str, bump_type: str = 'patch') -> str:
+        """Get the next version based on bump type.
+
+        Args:
+            current_version: Current version string
+            bump_type: Type of bump ('major', 'minor', 'patch')
+
+        Returns:
+            Next version string
+
+        Raises:
+            ValueError: If bump_type is invalid
+        """
+        try:
+            v = version.Version(current_version)
+            major, minor, micro = v.major, v.minor, v.micro
+
+            if bump_type == 'major':
+                return f"{major + 1}.0.0"
+            elif bump_type == 'minor':
+                return f"{major}.{minor + 1}.0"
+            elif bump_type == 'patch':
+                return f"{major}.{minor}.{micro + 1}"
+            else:
+                raise ValueError(f"Invalid bump type: {bump_type}")
+
+        except version.InvalidVersion:
+            raise ValueError(f"Cannot parse version: {current_version}")
+
+    def suggest_version(self, current_version: Optional[str] = None) -> Dict[str, str]:
+        """Suggest next version options.
+
+        Args:
+            current_version: Current version. If None, gets from setuptools-scm.
+
+        Returns:
+            Dictionary with version suggestions
+        """
+        if current_version is None:
+            current_version = self.get_current_version()
+
+        if current_version == "unknown":
+            return {
+                'error': 'Cannot determine current version',
+                'suggestion': 'Consider creating an initial tag like v0.1.0'
+            }
+
+        try:
+            # Strip development version info to get base
+            v = version.Version(current_version)
+            base_version = v.base_version
+
+            return {
+                'current': current_version,
+                'base': base_version,
+                'patch': self.get_next_version(base_version, 'patch'),
+                'minor': self.get_next_version(base_version, 'minor'),
+                'major': self.get_next_version(base_version, 'major'),
+            }
+        except Exception as e:
+            return {
+                'error': str(e),
+                'current': current_version
+            }
+
+    def validate_version_format(self, version_string: str) -> bool:
+        """Validate if a version string follows semantic versioning.
+
+        Args:
+            version_string: Version string to validate
+
+        Returns:
+            True if valid semantic version, False otherwise
+        """
+        try:
+            version.Version(version_string)
+            return True
+        except version.InvalidVersion:
+            return False
+
+    def get_version_info(self, project_root: Optional[Path] = None) -> Dict[str, Any]:
+        """Get comprehensive version information for a project.
+
+        Args:
+            project_root: Root directory of project. If None, uses current directory.
+
+        Returns:
+            Dictionary with version information
+        """
+        if project_root:
+            original_root = self.project_root
+            self.project_root = project_root
+
+        try:
+            current_version = self.get_current_version()
+
+            # Try to get git information
+            git_info = self._get_git_info()
+
+            # Parse version components
+            version_parts = self.parse_version(current_version) if current_version != "unknown" else {}
+
+            return {
+                'full_version': current_version,
+                'short_version': current_version.split('.dev')[0] if '.dev' in current_version else current_version,
+                'version_components': version_parts,
+                'is_dev': self.is_development_version(current_version),
+                'git_commit': git_info.get('commit'),
+                'git_branch': git_info.get('branch'),
+                'is_git_repo': git_info.get('is_repo', False)
+            }
+        finally:
+            if project_root:
+                self.project_root = original_root
+
+    def get_release_info(self, project_root: Optional[Path] = None) -> Dict[str, Any]:
+        """Get release information for a project.
+
+        Args:
+            project_root: Root directory of project. If None, uses current directory.
+
+        Returns:
+            Dictionary with release information
+        """
+        from datetime import datetime
+
+        version_info = self.get_version_info(project_root)
+
+        return {
+            'name': 'MarkiTect',
+            'version': version_info['full_version'],
+            'short_version': version_info['short_version'],
+            'is_development': version_info['is_dev'],
+            'git_branch': version_info.get('git_branch', 'unknown'),
+            'git_commit': version_info.get('git_commit', 'unknown'),
+            'build_date': datetime.now().isoformat(),
+            'python_version': f"{__import__('sys').version_info.major}.{__import__('sys').version_info.minor}.{__import__('sys').version_info.micro}"
+        }
+
+    def _get_git_info(self) -> Dict[str, Any]:
+        """Get git repository information.
+
+        Returns:
+            Dictionary with git information
+        """
+        git_info = {'is_repo': False}
+
+        try:
+            # Check if in git repo
+            subprocess.run(['git', 'rev-parse', '--git-dir'],
+                         cwd=self.project_root, check=True, capture_output=True)
+            git_info['is_repo'] = True
+
+            # Get branch
+            try:
+                result = subprocess.run(['git', 'rev-parse', '--abbrev-ref', 'HEAD'],
+                                      cwd=self.project_root, capture_output=True, text=True, check=True)
+                git_info['branch'] = result.stdout.strip()
+            except subprocess.CalledProcessError:
+                git_info['branch'] = 'unknown'
+
+            # Get commit
+            try:
+                result = subprocess.run(['git', 'rev-parse', 'HEAD'],
+                                      cwd=self.project_root, capture_output=True, text=True, check=True)
+                git_info['commit'] = result.stdout.strip()
+            except subprocess.CalledProcessError:
+                git_info['commit'] = 'unknown'
+
+        except subprocess.CalledProcessError:
+            pass  # Not a git repo
+
+        return git_info
+
+
+# Convenience functions for backward compatibility and easy import
+def get_version_info(project_root: Optional[Path] = None) -> Dict[str, Any]:
+    """Get version information using default VersionManager."""
+    manager = VersionManager(project_root)
+    return manager.get_version_info()
+
+
+def get_release_info(project_root: Optional[Path] = None) -> Dict[str, Any]:
+    """Get release information using default VersionManager."""
+    manager = VersionManager(project_root)
+    return manager.get_release_info()

cost_notes/25114-botched_refactoring_recovery.md

@@ -0,0 +1,7 @@
+Total cost:            $18.34
+Total duration (API):  49m 10.0s
+Total duration (wall): 10h 38m 0.7s
+Total code changes:    6105 lines added, 186 lines removed
+Usage by model:
+    claude-3-5-haiku:  58.3k input, 7.3k output, 0 cache read, 0 cache write ($0.0760)
+       claude-sonnet:  9.1k input, 141.0k output, 31.7m cache read, 1.8m cache write ($18.27)

demo_plugin_integration.py

@@ -0,0 +1,212 @@
+#!/usr/bin/env python3
+"""
+Demo script showing TestDrive JSUI plugin integration with Markitect
+
+This script demonstrates:
+1. Plugin discovery and registration
+2. Asset management and deployment
+3. Standalone development vs production rendering
+4. Clean separation between Python and JavaScript
+"""
+
+from pathlib import Path
+import json
+
+# Import the new plugin system
+from markitect.plugins import (
+    PluginManager,
+    RenderingEngineManager,
+    RenderingConfig
+)
+from markitect.plugins.testdrive_jsui import TestDriveJSUIEngine
+
+
+def demo_standalone_development():
+    """Demo standalone development workflow."""
+    print("🧪 Demonstrating Standalone Development Workflow")
+    print("=" * 50)
+
+    # Initialize the TestDrive JSUI engine directly
+    engine = TestDriveJSUIEngine()
+
+    # Read test content
+    test_content_path = Path("testdrive-jsui/test-documents/sample.md")
+    if test_content_path.exists():
+        test_content = test_content_path.read_text()
+    else:
+        test_content = "# Demo Content\n\nThis is demo content for testing."
+
+    # Create standalone test document
+    output_path = Path("/tmp/testdrive_standalone_demo.html")
+
+    print(f"📄 Creating standalone test document: {output_path}")
+
+    try:
+        engine.create_standalone_test_document(test_content, output_path)
+        print(f"✅ Success! Open in browser: file://{output_path}")
+    except Exception as e:
+        print(f"❌ Error creating standalone document: {e}")
+
+    return engine
+
+
+def demo_plugin_discovery():
+    """Demo plugin discovery through the main system."""
+    print("\n🔍 Demonstrating Plugin Discovery")
+    print("=" * 50)
+
+    # Initialize plugin manager
+    plugin_manager = PluginManager()
+
+    print("📋 Discovering all plugins...")
+    all_plugins = plugin_manager.discover_plugins()
+
+    # Show all discovered plugins
+    for plugin_name, plugin_info in all_plugins.items():
+        print(f"  🔌 {plugin_name}: {plugin_info.get('type', 'unknown')}")
+
+    # Initialize rendering engine manager
+    rendering_manager = RenderingEngineManager(plugin_manager)
+
+    print("\n🎨 Available rendering engines:")
+    for engine_name in rendering_manager.list_engines():
+        engine = rendering_manager.get_engine(engine_name)
+        if engine:
+            print(f"  🎯 {engine_name}: modes={engine.get_supported_modes()}")
+
+    return rendering_manager
+
+
+def demo_production_deployment():
+    """Demo production deployment with asset management."""
+    print("\n🚀 Demonstrating Production Deployment")
+    print("=" * 50)
+
+    # Create production configuration
+    output_dir = Path("/tmp/demo_production_output")
+    output_dir.mkdir(exist_ok=True)
+
+    config = RenderingConfig(
+        asset_base_url="_markitect",
+        development_mode=False,
+        output_directory=output_dir
+    )
+
+    # Initialize engine
+    engine = TestDriveJSUIEngine()
+
+    # Demo content
+    demo_content = """# Production Demo
+
+This demonstrates production deployment of the TestDrive JSUI plugin.
+
+## Features
+- Asset deployment to `_markitect/plugins/testdrive-jsui/`
+- Production-ready HTML generation
+- Clean JavaScript-Python separation
+
+## Testing
+Open the generated HTML file to test the production deployment.
+"""
+
+    print(f"📁 Output directory: {output_dir}")
+    print(f"🔧 Asset base URL: {config.asset_base_url}")
+
+    # Render document
+    try:
+        html_content = engine.render_document(demo_content, "edit", config)
+
+        # Save to output directory
+        output_file = output_dir / "demo_production.html"
+        output_file.write_text(html_content)
+
+        print(f"✅ Production document created: {output_file}")
+        print(f"🌐 Open in browser: file://{output_file}")
+
+        # Show asset requirements
+        assets = engine.get_required_assets()
+        print(f"\n📦 Required assets:")
+        for asset_type, asset_list in assets.items():
+            print(f"  {asset_type}: {len(asset_list)} files")
+            for asset in asset_list[:3]:  # Show first 3
+                print(f"    - {asset}")
+            if len(asset_list) > 3:
+                print(f"    ... and {len(asset_list) - 3} more")
+
+    except Exception as e:
+        print(f"❌ Error in production deployment: {e}")
+
+    return output_dir
+
+
+def demo_asset_url_generation():
+    """Demo asset URL generation for different modes."""
+    print("\n🔗 Demonstrating Asset URL Generation")
+    print("=" * 50)
+
+    engine = TestDriveJSUIEngine()
+
+    # Development configuration
+    dev_config = RenderingConfig(
+        asset_base_url=".",
+        development_mode=True,
+        plugin_source_dirs={
+            "testdrive-jsui": Path("testdrive-jsui")
+        }
+    )
+
+    # Production configuration
+    prod_config = RenderingConfig(
+        asset_base_url="_markitect",
+        development_mode=False
+    )
+
+    sample_assets = ["static/js/main.js", "static/css/editor.css", "images/icon.png"]
+
+    print("Development URLs:")
+    for asset in sample_assets:
+        url = dev_config.get_asset_url("testdrive-jsui", asset)
+        print(f"  {asset} → {url}")
+
+    print("\nProduction URLs:")
+    for asset in sample_assets:
+        url = prod_config.get_asset_url("testdrive-jsui", asset)
+        print(f"  {asset} → {url}")
+
+    # Show JSON config generation
+    print(f"\nDevelopment JSON config:")
+    print(dev_config.to_json_config("testdrive-jsui"))
+
+
+def main():
+    """Run all demo workflows."""
+    print("🎯 TestDrive JSUI Plugin Integration Demo")
+    print("🔬 Demonstrating JavaScript-first development approach")
+    print("🏗️ Clean separation between Python and JavaScript\n")
+
+    try:
+        # Demo workflows
+        engine = demo_standalone_development()
+        rendering_manager = demo_plugin_discovery()
+        output_dir = demo_production_deployment()
+        demo_asset_url_generation()
+
+        print(f"\n✅ All demos completed successfully!")
+        print(f"🔬 Standalone test: testdrive-jsui/test.html")
+        print(f"📄 Generated files in: {output_dir}")
+
+        # Show next steps
+        print(f"\n📚 Next Steps:")
+        print(f"  1. Open testdrive-jsui/test.html in browser for standalone dev")
+        print(f"  2. Start development server: cd testdrive-jsui && python -m http.server 8080")
+        print(f"  3. Integrate with markitect md-render command")
+        print(f"  4. Add more rendering engines to the plugin system")
+
+    except Exception as e:
+        print(f"❌ Demo failed: {e}")
+        import traceback
+        traceback.print_exc()
+
+
+if __name__ == "__main__":
+    main()

docs/CAPABILITIES_QUICK_REFERENCE.md

@@ -0,0 +1,184 @@
+# Capabilities Quick Reference
+
+**⚠️ Critical:** Read [Capabilities Architecture](architecture/CAPABILITIES_ARCHITECTURE.md) for full details.
+
+## Core Rules
+
+### 🚫 **NEVER** Edit Capabilities from Main Repo
+
+```bash
+# ❌ WRONG - Don't edit capability files from main repo
+cd /home/worsch/markitect_project/capabilities/testdrive-jsui
+vim src/testdrive_jsui/core.py  # DON'T DO THIS!
+
+# ✅ CORRECT - Use separate Claude instance/session
+# Open new terminal/Claude instance:
+git clone http://gitea/coulomb/testdrive-jsui.git /path/to/work
+cd /path/to/work/testdrive-jsui
+# Make changes, commit, push
+```
+
+### 📦 Capabilities are Git Submodules
+
+- Each capability = separate git repository
+- Located in `capabilities/` as submodules
+- Independent development lifecycle
+- Own versioning and releases
+
+### 🔀 Use Separate Claude Instances
+
+| Session | Purpose | Location |
+|---------|---------|----------|
+| **Main Repo** | Integration, configuration | `/home/worsch/markitect_project` |
+| **Capability** | Feature development, bugs | Separate clone or `capabilities/capability-name` |
+
+**Why?** Prevents accidental cross-contamination and respects repository boundaries.
+
+## Common Tasks
+
+### Update Capability After Changes
+
+```bash
+# After pushing changes to capability repo
+cd /home/worsch/markitect_project
+git submodule update --remote capabilities/testdrive-jsui
+git add capabilities/testdrive-jsui
+git commit -m "chore: update testdrive-jsui to latest"
+git push
+```
+
+### Add New Capability
+
+```bash
+cd /home/worsch/markitect_project
+
+# Add as submodule
+git submodule add http://gitea/coulomb/new-capability.git capabilities/new-capability
+
+# Add to pyproject.toml dependencies
+echo '    "new-capability @ file:./capabilities/new-capability",' >> pyproject.toml
+
+# Commit
+git add .gitmodules capabilities/new-capability pyproject.toml
+git commit -m "feat: add new-capability submodule"
+```
+
+### Work on Capability Feature
+
+```bash
+# Option 1: In submodule directory (careful!)
+cd /home/worsch/markitect_project/capabilities/testdrive-jsui
+git checkout -b feature-branch
+# make changes
+git commit -m "feat: new feature"
+git push origin feature-branch
+
+# Option 2: Separate clone (recommended)
+cd ~/projects
+git clone http://gitea/coulomb/testdrive-jsui.git
+cd testdrive-jsui
+git checkout -b feature-branch
+# make changes
+git commit -m "feat: new feature"
+git push origin feature-branch
+```
+
+### Check Capability Status
+
+```bash
+cd /home/worsch/markitect_project
+
+# List all capabilities
+make capabilities-list
+
+# Check submodule status
+git submodule status
+
+# See which commit each capability is at
+git submodule foreach 'git log --oneline -1'
+```
+
+## Integration Patterns
+
+### Python Import
+
+```python
+# ✅ Correct - Import from capability package
+from testdrive_jsui import TestDriveJSUIEngine
+
+engine = TestDriveJSUIEngine()
+```
+
+### Dependency Declaration
+
+```toml
+# pyproject.toml
+dependencies = [
+    "testdrive-jsui @ file:./capabilities/testdrive-jsui",
+]
+```
+
+### Plugin Self-Declaration
+
+```python
+# ✅ Good - Plugin declares its own location
+def get_plugin_source_dir(self) -> Path:
+    return Path(__file__).parent.parent.parent / "capabilities" / "testdrive-jsui"
+
+# ❌ Bad - Hardcoded in main repo
+if plugin_name == 'testdrive-jsui':
+    return Path('capabilities/testdrive-jsui')
+```
+
+## Troubleshooting
+
+### "Submodule not initialized"
+
+```bash
+git submodule update --init --recursive
+```
+
+### "Import error: No module named 'capability_name'"
+
+```bash
+pip install -e ./capabilities/capability-name
+# or
+pip install -e .  # Install all dependencies
+```
+
+### "Merge conflict in submodule"
+
+```bash
+# Don't resolve in main repo!
+# Go to capability repo and resolve there
+cd capabilities/testdrive-jsui
+git pull origin main
+# Resolve conflicts, commit, push
+
+cd ../..
+git submodule update --remote capabilities/testdrive-jsui
+git add capabilities/testdrive-jsui
+git commit -m "chore: update testdrive-jsui after conflict resolution"
+```
+
+## Current Capabilities
+
+| Capability | Type | Repository | Status |
+|------------|------|------------|--------|
+| **testdrive-jsui** | Rendering Engine | `coulomb/testdrive-jsui` | ✅ Submodule |
+| **issue-facade** | CLI Tool | `coulomb/issue-facade` | ✅ Submodule |
+| **kaizen-agentic** | Framework | `coulomb/kaizen-agentic` | ✅ Submodule |
+| **release-management** | Tool | Local | 📦 To migrate |
+| **markitect-content** | Library | Local | 📦 To migrate |
+
+## Key Principles
+
+1. **Separation of Concerns** - Main repo doesn't modify capabilities
+2. **Independent Development** - Each capability has own lifecycle
+3. **Interface-Based Integration** - Use documented APIs only
+4. **Version Control** - Git submodules for dependency management
+5. **Session Isolation** - Separate Claude instances per repository
+
+---
+
+**📖 Full Documentation:** [Capabilities Architecture](architecture/CAPABILITIES_ARCHITECTURE.md)

docs/DOCUMENT_NAVIGATOR_INTEGRATION.md

@@ -0,0 +1,174 @@
+# DocumentNavigator Integration Guide
+
+## TDD Implementation Complete ✅
+
+The DocumentNavigator widget has been successfully implemented following Test-Driven Development methodology:
+
+### ✅ **Completed Components**
+
+1. **Base Architecture** (`js/widgets/base/`)
+   - `Widget.js` - Core widget functionality with events and state
+   - `UIWidget.js` - DOM manipulation and visual behavior
+
+2. **DocumentNavigator Widget** (`js/widgets/navigation/DocumentNavigator.js`)
+   - Substack-style floating navigation panel
+   - Hierarchical heading extraction and tree building
+   - Expand/collapse with smooth animations
+   - Scroll spy with current section highlighting
+   - Responsive behavior (auto-hide on mobile)
+   - Keyboard navigation support
+   - Smooth scrolling to sections
+
+3. **Plugin Definition** (`js/plugins/document-navigator-plugin.js`)
+   - Complete plugin metadata and configuration
+   - Lazy loading support
+   - Theme variants (default, dark, minimal)
+   - Usage examples and development helpers
+
+4. **TDD Test Suite** (`js/tests/test-document-navigator.js`)
+   - Comprehensive test coverage (15 test cases)
+   - Browser-based test runner included
+   - Tests all functionality: rendering, navigation, scroll spy, responsive behavior
+
+## Integration with HTML Rendering
+
+To integrate the DocumentNavigator into all rendered markdown documents, add the following to the HTML template in `CleanDocumentManager._generate_html_template()`:
+
+### **Method 1: Simple Integration (Immediate Use)**
+
+Add this JavaScript after the existing component initialization:
+
+```javascript
+// Add DocumentNavigator initialization after existing components
+// (Insert around line 1050 in clean_document_manager.py, after documentControls.create())
+
+// Initialize DocumentNavigator if headings are present
+try {
+    // Import the widget classes (using dynamic imports for future plugin system)
+    const documentNavigator = new DocumentNavigator({
+        container: document.getElementById('markdown-content') || document.body,
+        position: 'left',
+        collapsed: true,
+        theme: '${template or "default"}',  // Use current document theme
+        enableScrollSpy: true,
+        autoHide: true
+    });
+
+    // Initialize and render
+    documentNavigator.initialize().then(() => {
+        return documentNavigator.render();
+    }).then(() => {
+        console.log('✓ DocumentNavigator initialized successfully');
+    }).catch(error => {
+        console.warn('DocumentNavigator initialization failed:', error.message);
+    });
+} catch (error) {
+    console.warn('DocumentNavigator not available:', error.message);
+}
+```
+
+### **Method 2: Plugin System Integration (Future-Ready)**
+
+For the full plugin architecture, the initialization would look like:
+
+```javascript
+// Future plugin system integration
+if (typeof widgetSystem !== 'undefined') {
+    widgetSystem.createWidget('DocumentNavigator', {
+        theme: '${template or "default"}',
+        position: 'left'
+    }).then(navigator => {
+        return navigator.show();
+    });
+}
+```
+
+## Usage
+
+Once integrated, the DocumentNavigator will:
+
+1. **Auto-detect headings** in the rendered markdown content
+2. **Show collapsed toggle** on the left side (hamburger menu icon)
+3. **Expand on click** to reveal table of contents
+4. **Highlight current section** as user scrolls
+5. **Navigate smoothly** when headings are clicked
+6. **Auto-hide on mobile** devices
+7. **Support keyboard navigation** (Enter/Space to toggle, Escape to collapse)
+
+## Testing
+
+To test the implementation:
+
+1. **Run TDD Test Suite**:
+   ```bash
+   # Start local server
+   cd markitect/static/js/tests
+   python -m http.server 8080
+
+   # Open browser to: http://localhost:8080/test-document-navigator-runner.html
+   # Click "Run TDD Test Suite" button
+   ```
+
+2. **Test with Real Content**:
+   ```bash
+   # Create test markdown with headings
+   echo "# Chapter 1
+   ## Section 1.1
+   ### Subsection 1.1.1
+   ## Section 1.2
+   # Chapter 2" > test-doc.md
+
+   # Render with navigator
+   markitect md-render test-doc.md --output test-doc.html
+   ```
+
+## Configuration Options
+
+The DocumentNavigator supports extensive customization:
+
+```javascript
+const navigator = new DocumentNavigator({
+    position: 'left',              // 'left' or 'right'
+    collapsed: true,               // Start collapsed
+    autoHide: true,               // Hide on mobile
+    maxHeadingLevel: 3,           // H1, H2, H3
+    enableScrollSpy: true,        // Highlight current section
+    smoothScroll: true,           // Smooth scroll animation
+    theme: 'default',             // 'default', 'dark', 'minimal'
+    width: '280px',               // Expanded width
+    offset: { top: '80px', side: '20px' }
+});
+```
+
+## Theme Integration
+
+The navigator automatically adapts to document themes:
+
+- **Default Theme**: Clean white background with subtle shadows
+- **Dark Theme**: Dark background with light text
+- **Substack Theme**: Warm cream colors matching document style
+- **Academic Theme**: Traditional academic styling
+- **ChatGPT Theme**: Modern compact layout
+
+## Performance
+
+- **Lazy Loading**: Widget loads only when headings are detected
+- **Efficient Scroll Spy**: Throttled scroll events (100ms)
+- **Responsive**: Automatically hides on mobile to save space
+- **Memory Efficient**: Proper cleanup on destroy
+
+## Browser Support
+
+- **Modern Browsers**: Chrome 80+, Firefox 75+, Safari 13+, Edge 80+
+- **ES6 Modules**: Uses dynamic imports (can be transpiled for older browsers)
+- **Progressive Enhancement**: Gracefully degrades if JavaScript fails
+
+## Next Steps
+
+1. **Add to HTML Template**: Integrate the JavaScript code into `CleanDocumentManager._generate_html_template()`
+2. **Test Integration**: Verify navigator appears in rendered documents
+3. **Theme Refinement**: Adjust colors to perfectly match document themes
+4. **Plugin System**: Implement full plugin architecture for future extensibility
+5. **Performance Optimization**: Add preloading and caching optimizations
+
+The DocumentNavigator widget is production-ready and provides a professional Substack-style navigation experience for all markdown documents rendered by Markitect.

docs/ERROR_HANDLING_STRATEGY.md

@@ -0,0 +1,263 @@
+# Error Handling Strategy: Fail Fast + Robustness Balance
+
+## Overview
+
+This document defines the balanced error handling strategy that combines **Fail Fast** principles for development with **Robustness Principles** for production, preventing both cascading failures and difficult diagnosis.
+
+## Core Philosophy
+
+### 🚨 **Development Mode (Fail Fast)**
+- **Immediate failure** on errors for fast debugging
+- **Strict validation** with exceptions on invalid input
+- **No silent failures** - all problems surface immediately
+- **Clear error messages** with full context
+
+### 🛡️ **Production Mode (Robust)**
+- **Graceful degradation** when components fail
+- **Fallback behaviors** for non-critical failures
+- **Silent recovery** for user experience
+- **Detailed logging** for post-mortem analysis
+
+## Implementation Strategy
+
+### Mode Detection
+```javascript
+const MARKITECT_STRICT_MODE = (
+    window.location.hostname === 'localhost' ||
+    window.location.hostname === '127.0.0.1' ||
+    window.location.search.includes('strict=true') ||
+    window.markitectStrictMode === true
+);
+```
+
+### Dual-Behavior Error Handling
+```javascript
+safeOperation: function(operation, fallback = null, context = 'Unknown') {
+    try {
+        return operation();
+    } catch (error) {
+        console.warn(`Operation failed in ${context}:`, error);
+
+        // Fail Fast in development mode
+        if (MARKITECT_STRICT_MODE) {
+            console.error(`🚨 STRICT MODE: Operation failed in ${context}`);
+            throw error; // Re-throw for immediate debugging
+        }
+
+        // Robust handling in production
+        if (window.MarkitectDebugSystem) {
+            window.MarkitectDebugSystem.addMessage(
+                `Safe operation failed: ${error.message}`,
+                'WARNING',
+                'System',
+                { context, eventType: 'ERROR' }
+            );
+        }
+        return typeof fallback === 'function' ? fallback() : fallback;
+    }
+}
+```
+
+## Error Categories & Responses
+
+### 1. **Critical System Errors**
+| Error Type | Development Response | Production Response |
+|------------|---------------------|-------------------|
+| Missing Dependencies | `throw Error()` immediately | Skip with warning, continue |
+| Invalid Configuration | `throw Error()` immediately | Use defaults, log error |
+| DOM Not Ready | `throw Error()` immediately | Retry with timeout |
+
+### 2. **Input Validation Errors**
+| Error Type | Development Response | Production Response |
+|------------|---------------------|-------------------|
+| Malformed Data | `throw Error()` with details | Sanitize and continue |
+| Oversized Input | `throw Error()` immediately | Truncate with warning |
+| Invalid Selectors | `throw Error()` with context | Return null, log warning |
+
+### 3. **Resource Errors**
+| Error Type | Development Response | Production Response |
+|------------|---------------------|-------------------|
+| Memory Exhaustion | `throw Error()` to prevent hang | Apply limits, degrade features |
+| Network Failures | `throw Error()` for debugging | Use cached data, retry logic |
+| Timeout Exceeded | `throw Error()` immediately | Cancel operation, fallback |
+
+### 4. **UI Component Errors**
+| Error Type | Development Response | Production Response |
+|------------|---------------------|-------------------|
+| Control Creation Failed | `throw Error()` with stack | Create minimal fallback |
+| DOM Manipulation Failed | `throw Error()` with element | Skip operation, continue |
+| Event Handler Error | `throw Error()` to debug | Log error, disable feature |
+
+## Logging Strategy
+
+### Development Mode
+```javascript
+// Immediate console errors
+console.error(`🚨 STRICT MODE: ${message}`);
+throw new Error(message);
+```
+
+### Production Mode
+```javascript
+// Silent logging with context
+window.MarkitectDebugSystem.addMessage(
+    message,
+    'ERROR',
+    component,
+    { context, stackTrace: error.stack }
+);
+
+// User-friendly fallbacks
+return fallbackValue || defaultBehavior();
+```
+
+## Testing Approach
+
+### Development Testing
+- **Error Injection**: Intentionally trigger failures
+- **Boundary Testing**: Test limits and edge cases
+- **Dependency Mocking**: Remove required components
+- **Strict Validation**: Ensure all errors surface
+
+### Production Testing
+- **Graceful Degradation**: Verify fallbacks work
+- **Performance Under Load**: Stress test with errors
+- **User Experience**: No broken interfaces
+- **Recovery Scenarios**: System self-healing
+
+## Implementation Examples
+
+### Control Initialization
+```javascript
+initializeControl: function(controlClass, controlName, icon = '🔧') {
+    try {
+        if (!controlClass) {
+            const message = `${controlName} class not available`;
+
+            // Fail Fast in development
+            if (MARKITECT_STRICT_MODE) {
+                throw new Error(message);
+            }
+
+            // Graceful in production
+            console.warn(message);
+            return this.createFallbackControl(controlName, icon);
+        }
+
+        return new controlClass().createControl();
+    } catch (error) {
+        if (MARKITECT_STRICT_MODE) {
+            throw error; // Let it bubble up
+        }
+
+        // Production: log and continue
+        this.logError(error, controlName);
+        return null;
+    }
+}
+```
+
+### Input Validation
+```javascript
+validateAndSanitize: function(input, maxLength = 1000) {
+    if (typeof input !== 'string') {
+        const error = new TypeError('Input must be string');
+
+        if (MARKITECT_STRICT_MODE) {
+            throw error;
+        }
+
+        return String(input).slice(0, maxLength);
+    }
+
+    if (input.length > maxLength) {
+        const error = new Error(`Input exceeds ${maxLength} characters`);
+
+        if (MARKITECT_STRICT_MODE) {
+            throw error;
+        }
+
+        console.warn('Input truncated to fit limits');
+        return input.slice(0, maxLength);
+    }
+
+    return input;
+}
+```
+
+## Benefits
+
+### 🚀 **Development Benefits**
+- **Fast Problem Discovery**: Errors surface immediately
+- **Clear Error Context**: Full stack traces and details
+- **Prevents Technical Debt**: Forces proper error handling
+- **Debugging Efficiency**: No need to backtrack from symptoms
+
+### 🛡️ **Production Benefits**
+- **System Stability**: Graceful degradation prevents crashes
+- **User Experience**: No broken interfaces or white screens
+- **Self-Healing**: Automatic fallbacks and recovery
+- **Operational Monitoring**: Detailed error telemetry
+
+### ⚖️ **Balance Benefits**
+- **Best of Both Worlds**: Development speed + Production stability
+- **Context-Appropriate**: Right behavior for the right environment
+- **Maintainable**: Clear patterns and consistent implementation
+- **Scalable**: Works from development to enterprise deployment
+
+## Activation Guide
+
+### Automatic Detection
+- `localhost` and `127.0.0.1` automatically enable strict mode
+- URL parameter `?strict=true` forces strict mode
+- Global flag `window.markitectStrictMode = true`
+
+### Manual Control
+```javascript
+// Force strict mode for testing
+window.markitectStrictMode = true;
+
+// Force production mode (disable strict)
+window.markitectStrictMode = false;
+```
+
+### Environment Configuration
+```javascript
+// In development builds
+const DEVELOPMENT_BUILD = true;
+const MARKITECT_STRICT_MODE = DEVELOPMENT_BUILD || detectDevelopmentEnvironment();
+
+// In production builds
+const DEVELOPMENT_BUILD = false;
+const MARKITECT_STRICT_MODE = false; // Always robust in production
+```
+
+## Monitoring & Metrics
+
+### Development Metrics
+- **Error Count**: Number of strict mode exceptions
+- **Error Categories**: Types of failures encountered
+- **Resolution Time**: Time to fix after error discovery
+- **Test Coverage**: Percentage of error paths tested
+
+### Production Metrics
+- **Fallback Usage**: How often graceful degradation occurs
+- **Recovery Success**: Percentage of successful recoveries
+- **User Impact**: Features disabled vs. core functionality maintained
+- **Error Patterns**: Common failure modes for improvement
+
+## Future Evolution
+
+### Enhanced Detection
+- **CI/CD Integration**: Automatic strict mode in testing pipelines
+- **Feature Flags**: Remote control of error handling behavior
+- **A/B Testing**: Compare error handling strategies
+- **Machine Learning**: Predict and prevent common failures
+
+### Advanced Recovery
+- **Smart Fallbacks**: Context-aware recovery strategies
+- **Progressive Enhancement**: Gradually restore failed features
+- **User Notification**: Inform users of degraded functionality
+- **Automatic Reporting**: Send error telemetry to development team
+
+This balanced approach ensures we catch problems early in development while maintaining a bulletproof production experience.

docs/PLUGIN_SYSTEM.md

@@ -0,0 +1,492 @@
+# Markitect Plugin System Documentation
+
+## Overview
+
+The Markitect plugin system provides a modular architecture for extending rendering capabilities with independent JavaScript UI components. This system enables JavaScript-first development while maintaining clean integration with the Python ecosystem.
+
+## Architecture
+
+### Core Components
+
+1. **RenderingEnginePlugin**: Base class for UI rendering engines
+2. **RenderingConfig**: Asset management and deployment configuration
+3. **RenderingEngineManager**: Plugin discovery and lifecycle management
+4. **PluginManager**: Integration with existing Markitect plugin system
+
+### Key Features
+
+- **Clean Separation**: JSON-based configuration interface (Python ↔ JavaScript)
+- **Independent Development**: JavaScript components work standalone
+- **Asset Management**: Configurable deployment strategies
+- **Multiple Engines**: Support for different UI frameworks
+- **Fallback Support**: Graceful degradation to standard rendering
+
+## Plugin Development
+
+### Creating a Rendering Engine Plugin
+
+1. **Extend RenderingEnginePlugin**:
+
+```python
+from markitect.plugins.rendering import RenderingEnginePlugin, RenderingConfig
+from markitect.plugins.base import PluginMetadata, PluginType
+
+class MyUIEngine(RenderingEnginePlugin):
+    def __init__(self):
+        super().__init__()
+        self._metadata = PluginMetadata(
+            name="my-ui-engine",
+            version="1.0.0",
+            description="Custom UI rendering engine",
+            author="Your Name",
+            plugin_type=PluginType.RENDERING
+        )
+
+    @property
+    def metadata(self) -> PluginMetadata:
+        return self._metadata
+
+    def get_supported_modes(self) -> List[str]:
+        return ["edit", "view"]
+
+    def get_required_assets(self) -> Dict[str, List[str]]:
+        return {
+            "js": ["static/js/main.js"],
+            "css": ["static/css/style.css"]
+        }
+
+    def render_document(self, content: str, mode: str, config: RenderingConfig) -> str:
+        # Your rendering logic here
+        return html_output
+```
+
+2. **Directory Structure**:
+
+```
+my-ui-engine/
+├── static/
+│   ├── js/           # JavaScript components
+│   └── css/          # Stylesheets
+├── templates/        # HTML templates
+├── images/           # Icons and images
+├── test-documents/   # Sample markdown files
+├── package.json      # Node.js configuration
+└── README.md         # Plugin documentation
+```
+
+3. **Asset Management**:
+
+Assets are automatically deployed based on configuration:
+- **Development**: Served from plugin source directory
+- **Production**: Copied to `_markitect/plugins/{plugin-name}/`
+
+## TestDrive JSUI Plugin
+
+### Overview
+
+The TestDrive JSUI plugin demonstrates the plugin architecture with a complete JavaScript UI for markdown editing.
+
+### Features
+
+- **Modular Components**: Clean separation of UI components
+- **Compass Positioning**: NW, NE, E, SE control panel layout
+- **Section Management**: Click-to-edit markdown sections
+- **Debug System**: Built-in debugging and logging
+- **Asset Pipeline**: Configurable asset deployment
+
+### Directory Structure
+
+```
+testdrive-jsui/
+├── static/js/
+│   ├── core/             # Core systems
+│   │   ├── debug-system.js
+│   │   └── section-manager.js
+│   ├── components/       # UI components
+│   │   ├── debug-panel.js
+│   │   ├── document-controls.js
+│   │   └── dom-renderer.js
+│   ├── controls/         # Control panels
+│   │   ├── control-base.js
+│   │   ├── contents-control.js   # Northwest
+│   │   ├── status-control.js     # East
+│   │   ├── debug-control.js      # Southeast
+│   │   └── edit-control.js       # Northeast
+│   ├── config-loader.js  # Configuration interface
+│   └── main-updated.js   # Application entry point
+├── static/css/           # Stylesheets (future)
+├── images/               # Icons and images (future)
+├── templates/
+│   └── index.html        # Main HTML template
+├── test-documents/
+│   └── sample.md         # Test content
+├── test.html             # Standalone development
+├── package.json          # Node.js configuration
+└── README.md             # Plugin documentation
+```
+
+### JavaScript Architecture
+
+- **Configuration Interface**: Clean JSON data transfer via `markitect-config` script element
+- **Modular Components**: Each component has single responsibility
+- **Event System**: Pub/sub for component communication
+- **Control System**: Abstract base class for UI controls
+- **Compass Positioning**: Consistent control panel layout
+
+## CLI Integration
+
+### Command Line Usage
+
+```bash
+# Use default engine (testdrive-jsui for edit/insert, standard for view)
+markitect md-render --edit document.md
+
+# Specify engine explicitly
+markitect md-render --engine testdrive-jsui --edit document.md
+
+# Use standard engine
+markitect md-render --engine standard --edit document.md
+
+# View available engines
+markitect md-render --help
+```
+
+### Engine Selection Logic
+
+1. **Default Selection**:
+   - Edit/Insert modes: `testdrive-jsui`
+   - View mode: `standard`
+
+2. **Explicit Selection**: Use `--engine` parameter
+
+3. **Fallback Strategy**:
+   - Engine not found → fallback to standard
+   - Mode not supported → fallback to standard
+   - Plugin error → fallback to standard
+
+### Integration Points
+
+The CLI integrates with the plugin system through:
+
+```python
+# Engine discovery
+plugin_manager = PluginManager()
+rendering_manager = RenderingEngineManager(plugin_manager)
+
+# Engine selection
+engine = rendering_manager.get_engine(engine_name)
+
+# Configuration
+config = RenderingConfig(
+    asset_base_url="_markitect",
+    development_mode=False,
+    output_directory=output_path.parent
+)
+
+# Rendering
+html_content = engine.render_document(content, mode, config)
+```
+
+## Development Workflows
+
+### Standalone JavaScript Development
+
+1. **Setup**:
+   ```bash
+   cd testdrive-jsui
+   python -m http.server 8080
+   ```
+
+2. **Development**:
+   - Edit JavaScript files in `static/js/`
+   - Refresh browser to see changes
+   - Use `test.html` for testing
+   - Browser DevTools for debugging
+
+3. **Benefits**:
+   - No Python environment required
+   - Fast iteration cycle
+   - Standard web development tools
+   - Hot reloading
+
+### Integrated Development
+
+1. **Plugin Testing**:
+   ```bash
+   python demo_plugin_integration.py
+   ```
+
+2. **CLI Testing**:
+   ```bash
+   markitect md-render --engine testdrive-jsui --edit test.md
+   ```
+
+3. **Integration Verification**:
+   ```bash
+   python test_complete_integration.py
+   ```
+
+## Asset Management
+
+### Development Mode
+
+```python
+config = RenderingConfig(
+    asset_base_url=".",
+    development_mode=True,
+    plugin_source_dirs={"testdrive-jsui": Path("testdrive-jsui")}
+)
+
+# Assets served as: file://testdrive-jsui/static/js/main.js
+```
+
+### Production Mode
+
+```python
+config = RenderingConfig(
+    asset_base_url="_markitect",
+    development_mode=False,
+    output_directory=Path("/output")
+)
+
+# Assets served as: _markitect/plugins/testdrive-jsui/static/js/main.js
+```
+
+### Asset Types
+
+- **js**: JavaScript files
+- **css**: Stylesheets
+- **images**: Icons, graphics
+- **external**: CDN resources
+
+### Deployment Strategy
+
+1. **Assets Copying**: Plugin assets copied to `_markitect/plugins/{name}/`
+2. **URL Generation**: Automatic URL generation for templates
+3. **Cache Management**: Asset versioning and cache control
+4. **Error Handling**: Fallback for missing assets
+
+### Asset Deployment Process
+
+When using CLI with plugin engines, assets are automatically deployed:
+
+```bash
+# Assets are deployed to output directory when using plugin engines
+markitect md-render --edit document.md --output /path/to/output.html
+
+# Output structure:
+# /path/to/
+# ├── output.html
+# └── _markitect/
+#     └── plugins/
+#         └── testdrive-jsui/
+#             ├── static/
+#             │   ├── js/          # 12 JavaScript files
+#             │   └── css/         # 3 CSS files
+#             └── images/          # 3 image files
+```
+
+The deployment process:
+
+1. **Plugin Discovery**: Engine identified (default: testdrive-jsui for edit mode)
+2. **Asset Analysis**: Required assets determined from `get_required_assets()`
+3. **Source Resolution**: Plugin source directory located
+4. **File Copying**: Assets copied with directory structure preservation
+5. **URL Generation**: HTML references generated with correct paths
+6. **Verification**: Asset accessibility validated
+
+Example output:
+```
+🎯 Using rendering engine: testdrive-jsui (supports: edit, view)
+📦 Deploying assets for engine 'testdrive-jsui'...
+📄 Deployed 18 asset files
+   js: 12 files
+   css: 3 files
+   images: 3 files
+✅ Rendered with INTERACTIVE editing mode to: output.html
+```
+
+## Configuration Interface
+
+### Python → JavaScript Data Transfer
+
+All dynamic data passes through a clean JSON interface:
+
+```html
+<script id="markitect-config" type="application/json">
+{
+  "markdownContent": "# Document content...",
+  "mode": "edit",
+  "theme": "github",
+  "keyboardShortcuts": true,
+  "originalFilename": "document.md",
+  "version": "Markitect v0.8.1"
+}
+</script>
+```
+
+### JavaScript Configuration Loading
+
+```javascript
+// Clean configuration loading
+class MarkitectConfig {
+    constructor() {
+        this.loadConfig();
+    }
+
+    loadConfig() {
+        const configElement = document.getElementById('markitect-config');
+        this.config = JSON.parse(configElement.textContent);
+    }
+}
+```
+
+### Benefits
+
+- **No String Interpolation**: Prevents template literal escaping issues
+- **Type Safety**: JSON validation and error handling
+- **Clean Separation**: No JavaScript code in Python strings
+- **Debuggable**: Easy to inspect configuration in browser
+
+## Testing
+
+### Plugin Testing
+
+```bash
+# Basic plugin discovery
+python test_plugin_discovery.py
+
+# CLI integration logic
+python test_cli_simple.py
+
+# Complete scenario testing
+python test_complete_integration.py
+
+# Full integration demo
+python demo_plugin_integration.py
+```
+
+### Browser Testing
+
+1. **Standalone**: Open `testdrive-jsui/test.html`
+2. **Generated**: Open CLI-generated HTML files
+3. **DevTools**: Use browser debugging tools
+4. **Console**: Check for JavaScript errors
+
+### Integration Testing
+
+- **Unit Tests**: Individual component testing
+- **Integration Tests**: Component interaction testing
+- **E2E Tests**: Full workflow testing
+- **Regression Tests**: Ensure stability across changes
+
+## Extension Points
+
+### Adding New Engines
+
+1. Create new plugin extending `RenderingEnginePlugin`
+2. Implement required methods (`get_supported_modes`, `render_document`, etc.)
+3. Register in `RenderingEngineManager._register_builtin_rendering_engines()`
+4. Test with CLI integration
+
+### Adding New Modes
+
+1. Add mode to engine's `get_supported_modes()`
+2. Update `render_document()` to handle new mode
+3. Test mode validation and rendering
+4. Update CLI integration if needed
+
+### Adding New Asset Types
+
+1. Update `get_required_assets()` return format
+2. Modify asset deployment logic in `RenderingConfig`
+3. Update template system to handle new asset types
+4. Test asset URL generation
+
+## Best Practices
+
+### Plugin Development
+
+- **Single Responsibility**: Each component has one clear purpose
+- **Clean Interfaces**: Well-defined APIs between components
+- **Error Handling**: Graceful degradation on failures
+- **Documentation**: Clear README and code comments
+
+### JavaScript Development
+
+- **Modular Architecture**: Avoid monolithic JavaScript files
+- **Event-Driven**: Use pub/sub for component communication
+- **Configuration-Driven**: Avoid hardcoded values
+- **Browser Compatibility**: Test across different browsers
+
+### Asset Management
+
+- **Relative Paths**: Use relative paths in asset definitions
+- **Versioning**: Include version info for cache management
+- **Optimization**: Minimize asset size for production
+- **CDN Integration**: Use CDN for external dependencies
+
+### Testing Strategy
+
+- **Automated Testing**: Comprehensive test coverage
+- **Manual Testing**: User workflow validation
+- **Cross-Platform**: Test on different environments
+- **Performance Testing**: Monitor rendering performance
+
+## Troubleshooting
+
+### Common Issues
+
+1. **Plugin Not Found**:
+   - Check plugin registration in `_register_builtin_rendering_engines()`
+   - Verify plugin class inheritance from `RenderingEnginePlugin`
+   - Check import paths and module availability
+
+2. **Asset Loading Errors**:
+   - Verify asset paths in `get_required_assets()`
+   - Check file permissions and existence
+   - Validate URL generation in different modes
+
+3. **Configuration Errors**:
+   - Check JSON syntax in configuration
+   - Verify configuration element ID (`markitect-config`)
+   - Test configuration loading in JavaScript
+
+4. **Rendering Failures**:
+   - Check template file existence and permissions
+   - Verify template placeholder replacement
+   - Test with minimal content for debugging
+
+### Debug Techniques
+
+- **Console Logging**: Use browser console for debugging
+- **Debug Panel**: TestDrive JSUI includes debug information
+- **Verbose Mode**: Use CLI `--verbose` flag for detailed output
+- **Test Scripts**: Run individual test scripts for isolation
+
+## Future Enhancements
+
+### Planned Features
+
+- **Plugin Package Manager**: npm-like plugin distribution
+- **Theme System Integration**: Plugin-aware theme system
+- **Performance Monitoring**: Built-in performance tracking
+- **Hot Reloading**: Automatic reload on file changes
+
+### Extension Opportunities
+
+- **React Integration**: React-based rendering engine
+- **Vue Integration**: Vue.js-based rendering engine
+- **TypeScript Support**: TypeScript plugin development
+- **Testing Framework**: Automated JavaScript testing
+
+### Community
+
+- **Plugin Registry**: Central repository for community plugins
+- **Documentation**: Expanded examples and tutorials
+- **Templates**: Starter templates for new plugins
+- **Best Practices**: Community guidelines and patterns
+
+---
+
+*This plugin system enables JavaScript-first development while maintaining clean integration with the MarkiTect Python ecosystem, providing the best of both worlds for UI development and backend processing.*

docs/README.md

@@ -7,8 +7,9 @@ Welcome to the MarkiTect documentation. This directory contains comprehensive do
 ### 📐 Architecture Documentation (`architecture/`)
 Deep technical documentation about system design, performance, and implementation details.
 
+- **[Capabilities Architecture](architecture/CAPABILITIES_ARCHITECTURE.md)** - **Critical:** How capabilities work as independent git submodules and separation of concerns
 - **[Caching System](architecture/caching-system.md)** - Why and how MarkiTect's AST caching delivers 60-85% performance improvements
-- *Coming soon: Database Schema, CLI Architecture, Plugin System*
+- *Coming soon: Database Schema, CLI Architecture*
 
 ### 👥 User Guides (`user-guides/`)
 End-user documentation for working with MarkiTect CLI and features.

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

docs/WORKSPACE_AND_DATABASES.md

@@ -0,0 +1,268 @@
+# Markitect Workspace and Database Architecture
+
+This document explains Markitect's workspace concept and the two distinct database systems used by the application.
+
+## Workspace Concept
+
+Markitect uses a **workspace-based architecture** where each directory or repository can have its own configuration and local data storage. This allows for flexible, per-project customization while maintaining a global user configuration.
+
+### Workspace Structure
+
+When you initialize Markitect in a directory, it creates the following structure:
+
+```
+project-directory/
+├── .markitect.yml              # Workspace configuration
+├── .markitect_workspace/       # Local workspace data
+├── .ast_cache/                 # AST parsing cache
+├── assets/                     # Asset storage directory
+│   ├── assets.db              # Asset management database
+│   └── [asset files]          # Stored images, files, etc.
+└── tests/                     # Test files directory
+```
+
+### Configuration Files
+
+Markitect searches for configuration in this order:
+1. `.markitect.yml` (current directory)
+2. `.markitect.yaml` (current directory)
+3. `.markitect.json` (current directory)
+4. `markitect.config.yml` (current directory)
+5. `markitect.config.yaml` (current directory)
+6. `markitect.config.json` (current directory)
+7. `~/.markitect/config.yml` (user home directory)
+8. Environment variables (`MARKITECT_*`)
+9. Built-in defaults
+
+## Database Architecture
+
+Markitect uses two distinct SQLite databases for different purposes:
+
+### 1. Main Application Database (`markitect.db`)
+
+**Location**: `~/.markitect/markitect.db` (user home directory)
+
+**Purpose**: Global user-level application data and configuration
+
+**Scope**: User-wide, shared across all workspaces
+
+**Contents**:
+- User preferences and settings
+- Application state information
+- Global configuration data
+- Cross-workspace data that needs persistence
+
+**Configuration**: Set via `MARKITECT_DATABASE_PATH` environment variable or `database_path` in configuration
+
+### 2. Asset Management Database (`assets.db`)
+
+**Location**: `assets/assets.db` (within workspace asset storage directory)
+
+**Purpose**: Asset management and tracking for the current workspace
+
+**Scope**: Workspace-specific, local to each directory/repository
+
+**Contents**:
+- Asset metadata (filename, size, MIME type, timestamps)
+- File content hashes for deduplication
+- Asset usage statistics and tracking
+- Processing logs and analytics
+- Asset relationships and dependencies
+
+**Schema** (key tables):
+```sql
+-- Basic asset metadata
+asset_metadata (
+    content_hash TEXT PRIMARY KEY,
+    filename TEXT NOT NULL,
+    size_bytes INTEGER NOT NULL,
+    mime_type TEXT,
+    created_at TIMESTAMP,
+    updated_at TIMESTAMP
+)
+
+-- Usage tracking
+asset_usage_stats (
+    content_hash TEXT,
+    usage_count INTEGER,
+    last_used TIMESTAMP,
+    documents_using TEXT  -- JSON array of document paths
+)
+
+-- Performance and analytics tables
+-- (Additional tables for caching, indexing, and optimization)
+```
+
+## Why Two Databases?
+
+This separation serves several important purposes:
+
+### Data Isolation
+- **Global data** (user preferences) stays in the user profile
+- **Workspace data** (asset files, metadata) stays with the project
+
+### Version Control Considerations
+- `markitect.db` is never committed to version control
+- `assets.db` is excluded via `.gitignore` (local workspace data)
+- Asset files themselves can be optionally committed based on project needs
+
+### Performance Optimization
+- Asset database operations are localized to relevant files
+- Global database isn't impacted by large asset collections
+- Each workspace can optimize its asset database independently
+
+### Portability and Collaboration
+- Workspaces can be moved/copied without affecting global configuration
+- Teams can share asset storage strategies without sharing personal settings
+- Different projects can have different asset management policies
+
+## Configuration Management
+
+### Workspace Initialization
+
+To initialize a new workspace:
+
+```bash
+markitect config-init
+```
+
+This creates:
+1. `.markitect.yml` configuration file
+2. Required directories (`.markitect_workspace`, `.ast_cache`, `tests`)
+3. Asset storage structure
+
+### Configuration Commands
+
+```bash
+# View current configuration
+markitect config-show
+
+# Set workspace-specific values
+markitect config-set repo_name "my-project"
+markitect config-set assets.storage_path "./assets"
+
+# View configuration help
+markitect config-help
+```
+
+### Environment Variables
+
+Override configuration with environment variables:
+
+```bash
+export MARKITECT_GITEA_URL="http://localhost:3000"
+export MARKITECT_WORKSPACE_DIR=".custom_workspace"
+export MARKITECT_DATABASE_PATH="/custom/path/markitect.db"
+```
+
+## Asset Management Integration
+
+The asset management system coordinates between the asset database and file storage:
+
+```python
+from markitect.assets import AssetManager
+
+# Initialize with workspace-specific configuration
+asset_manager = AssetManager()
+
+# Assets are stored in workspace, tracked in assets.db
+asset = asset_manager.add_asset("image.png")
+```
+
+### Asset Storage Workflow
+
+1. **File Processing**: Asset files are processed and stored in `assets/` directory
+2. **Database Recording**: Metadata recorded in `assets.db`
+3. **Deduplication**: Content hashes prevent duplicate storage
+4. **Usage Tracking**: Document usage recorded for analytics
+5. **Cleanup**: Unused assets can be identified and removed
+
+## Best Practices
+
+### For Development
+- Initialize workspace in each project directory
+- Commit `.markitect.yml` to version control
+- Add `assets.db` and workspace directories to `.gitignore`
+- Use relative paths in workspace configuration
+
+### For Collaboration
+- Share workspace configuration (`.markitect.yml`)
+- Document asset storage strategy for the team
+- Establish conventions for asset organization
+- Consider asset file version control policies
+
+### for Production
+- Backup both databases separately
+- Monitor asset database growth in large projects
+- Use environment variables for deployment-specific settings
+- Implement asset cleanup strategies for long-running projects
+
+## Migration and Compatibility
+
+### Legacy Support
+The system maintains backward compatibility:
+- Old configuration patterns still work
+- Automatic migration of legacy settings
+- Graceful fallbacks for missing configuration
+
+### Database Migration
+Asset databases support schema migrations:
+- Automatic schema updates on version changes
+- Backward compatibility preservation
+- Safe migration with rollback capability
+
+## Troubleshooting
+
+### Common Issues
+
+**Database Connection Errors**:
+- Check file permissions on database directories
+- Verify disk space availability
+- Ensure SQLite3 is available
+
+**Configuration Not Found**:
+- Verify `.markitect.yml` exists and is valid YAML
+- Check environment variable names and values
+- Run `markitect config-show` to see current configuration
+
+**Asset Storage Issues**:
+- Confirm asset directory permissions
+- Check available disk space
+- Verify `assets.db` is not corrupted
+
+### Recovery Procedures
+
+**Corrupted Asset Database**:
+```bash
+# Backup and recreate
+mv assets/assets.db assets/assets.db.backup
+# Restart Markitect to recreate schema
+markitect config-show
+```
+
+**Missing Configuration**:
+```bash
+# Reinitialize workspace
+markitect config-init
+```
+
+## Technical Details
+
+### Database Connections
+- Uses SQLite3 with connection pooling for performance
+- Automatic connection management and cleanup
+- Thread-safe operations for concurrent access
+
+### File System Integration
+- Path resolution relative to workspace root
+- Cross-platform path handling (Windows, macOS, Linux)
+- Symlink and junction support where available
+
+### Security Considerations
+- Database files have restricted permissions
+- No sensitive data stored in asset database
+- Configuration masking for sensitive values in display
+
+---
+
+*This documentation reflects the current architecture as of November 2025. For implementation details, see the source code in `markitect/config_manager.py` and `markitect/assets/`.*

docs/adr/ADR-001-client-side-debug-storage.md

@@ -0,0 +1,173 @@
+# ADR-001: Client-Side Debug Storage Technology
+
+## Status
+**Accepted** - 2025-11-10
+
+## Context
+
+The Markitect application requires a robust client-side debugging infrastructure to track and display debug messages during document editing operations. The previous implementation relied on a tightly-coupled debug panel that expected specific DOM elements and was integrated into old dialog systems.
+
+### Requirements
+- **Independence**: Debug system must be independent of specific UI components
+- **Persistence**: Debug messages should survive browser refresh/close
+- **Real-time Updates**: UI should reflect new messages immediately
+- **Performance**: Should not block the main thread or impact editor performance
+- **Storage Capacity**: Must handle 1000+ debug messages efficiently
+- **Browser Compatibility**: Work across all modern browsers
+- **Developer Experience**: Easy to integrate and use throughout the codebase
+
+### Problem Statement
+The existing debug infrastructure was failing because:
+1. Tight coupling to specific DOM elements (`debug-messages-container`, `toggle-debug`)
+2. Dependency on old dialog systems
+3. No persistence across browser sessions
+4. Limited to in-memory storage only
+
+## Decision
+
+**We will use IndexedDB as the primary client-side storage technology for the debug system.**
+
+## Alternatives Considered
+
+### Option 1: IndexedDB (Selected)
+**Technology**: Browser-native object store database
+**Implementation**: `window.MarkitectDebugSystem` with async operations
+
+### Option 2: SQLite via SQL.js
+**Technology**: WebAssembly-based SQLite implementation
+**Implementation**: SQL.js library with manual persistence
+
+### Option 3: LocalStorage
+**Technology**: Browser key-value storage
+**Implementation**: JSON serialization with size limits
+
+### Option 4: In-Memory Only
+**Technology**: JavaScript arrays with no persistence
+**Implementation**: Simple message array management
+
+## Decision Matrix
+
+| Criteria | IndexedDB | SQLite | LocalStorage | In-Memory |
+|----------|-----------|---------|--------------|-----------|
+| **Storage Capacity** | ✅ Large (50-100MB+) | ✅ Large | ❌ Limited (5-10MB) | ❌ Session only |
+| **Performance** | ✅ Async/Non-blocking | ⚠️ Can block UI | ✅ Fast | ✅ Fastest |
+| **Persistence** | ✅ Across sessions | ✅ Across sessions | ✅ Across sessions | ❌ Lost on refresh |
+| **Query Capabilities** | ⚠️ Limited | ✅ Full SQL | ❌ None | ❌ JavaScript only |
+| **Dependencies** | ✅ Native | ❌ 1.5MB WebAssembly | ✅ Native | ✅ Native |
+| **Browser Support** | ✅ Universal modern | ✅ Universal | ✅ Universal | ✅ Universal |
+| **API Complexity** | ⚠️ Moderate | ✅ Familiar SQL | ✅ Simple | ✅ Simple |
+| **Use Case Fit** | ✅ Perfect match | ⚠️ Overkill | ❌ Too limited | ❌ Insufficient |
+
+## Rationale
+
+### Why IndexedDB?
+
+1. **Native Browser Support**: No external dependencies or WebAssembly files
+2. **Asynchronous Operations**: Won't block the UI thread during debug operations
+3. **Sufficient Storage**: 50-100MB+ capacity easily handles thousands of debug messages
+4. **Appropriate Complexity**: Matches our simple data model without over-engineering
+5. **Performance Optimized**: Browsers optimize IndexedDB for web applications
+6. **Security**: Runs within browser's security sandbox with proper origin isolation
+
+### Why Not SQLite?
+
+While SQLite offers powerful querying capabilities, it's overkill for our use case:
+
+- **Complexity**: Our data model is simple (timestamp, category, message)
+- **Dependencies**: 1.5MB WebAssembly adds significant overhead
+- **Synchronous Risk**: Large operations can block the UI thread
+- **Manual Persistence**: Requires explicit save/load operations
+- **Over-Engineering**: We don't need JOINs, complex queries, or relational features
+
+### Why Not LocalStorage?
+
+LocalStorage is too limited:
+- **Size Constraints**: 5-10MB limit insufficient for extensive debug logs
+- **Synchronous API**: Blocks main thread during operations
+- **No Structured Data**: JSON serialization/deserialization overhead
+- **Browser Quotas**: Can be evicted under storage pressure
+
+### Why Not In-Memory?
+
+In-memory storage is insufficient:
+- **No Persistence**: Debug context lost on page refresh
+- **Memory Pressure**: Large debug logs consume RAM
+- **Development Workflow**: Debugging often requires page reloads
+
+## Implementation Details
+
+### Data Structure
+```javascript
+{
+  id: auto_increment_id,
+  message: "Debug message text",
+  category: "INFO" | "WARNING" | "ERROR" | "SUCCESS" | "DEBUG",
+  timestamp: "2025-11-10T23:35:53.123Z",
+  displayTime: "11:35:53 PM"
+}
+```
+
+### Database Schema
+- **Store Name**: `messages`
+- **Key Path**: `id` (auto-increment)
+- **Indexes**: `timestamp`, `category`
+- **Version**: 1
+
+### API Design
+```javascript
+// Core operations
+await MarkitectDebugSystem.addMessage(message, category);
+await MarkitectDebugSystem.clearMessages();
+const messages = MarkitectDebugSystem.getMessages(category, limit);
+
+// Advanced features
+const unsubscribe = MarkitectDebugSystem.subscribe(callback);
+const json = MarkitectDebugSystem.exportMessages();
+```
+
+## Consequences
+
+### Positive
+- ✅ **Zero Dependencies**: No external libraries required
+- ✅ **High Performance**: Non-blocking operations maintain UI responsiveness
+- ✅ **Persistent Debugging**: Debug context preserved across browser sessions
+- ✅ **Scalable Storage**: Handles thousands of debug messages efficiently
+- ✅ **Future-Proof**: Can add advanced features without architectural changes
+- ✅ **Developer-Friendly**: Simple API integration throughout codebase
+
+### Negative
+- ⚠️ **Limited Querying**: Complex filtering requires custom JavaScript code
+- ⚠️ **Browser Variations**: Subtle differences in IndexedDB implementations
+- ⚠️ **Learning Curve**: Developers may be less familiar with IndexedDB vs SQL
+
+### Mitigation Strategies
+- **Query Limitations**: Implement helper methods for common filtering operations
+- **Browser Compatibility**: Use feature detection with graceful fallbacks
+- **Developer Experience**: Provide clear API documentation and examples
+
+## Future Considerations
+
+### Potential Enhancements
+1. **Hybrid Approach**: Add optional SQLite mode for advanced users
+2. **Data Export**: Multiple export formats (JSON, CSV, SQL dumps)
+3. **Advanced Filtering**: Web Workers for complex query operations
+4. **Data Visualization**: Charts and analytics for debug patterns
+5. **Remote Sync**: Optional sync to development servers
+
+### Migration Path
+The current IndexedDB implementation provides a foundation that could support:
+- Adding SQLite as an "advanced mode" option
+- Implementing data export to external analysis tools
+- Building analytics dashboards on top of the debug data
+
+## References
+- [IndexedDB API Documentation](https://developer.mozilla.org/en-US/docs/Web/API/IndexedDB_API)
+- [SQL.js Documentation](https://sql.js.org/)
+- [Web Storage API Limitations](https://developer.mozilla.org/en-US/docs/Web/API/Web_Storage_API/Using_the_Web_Storage_API#Storage_limits)
+
+## Approval
+
+**Decided by**: Claude Code Development Team
+**Date**: 2025-11-10
+**Context**: Independent debug system redesign
+**Next Review**: When complex querying requirements emerge

docs/adr/ADR-002-robustness-principle-for-production-use.md

@@ -0,0 +1,384 @@
+# ADR-002: Robustness Principle for Production Use
+
+## Status
+**Accepted** - 2025-11-11
+
+## Context
+
+The Markitect application operates in unpredictable client-side environments where JavaScript execution can fail due to malicious input, network issues, browser inconsistencies, missing dependencies, or resource exhaustion. Traditional defensive programming approaches often result in cascading failures that crash entire UI components or leave the application in an unusable state.
+
+### Requirements
+- **Fault Tolerance**: System must continue operating when individual components fail
+- **Security**: Protection against malicious input and injection attacks
+- **Resource Protection**: Prevention of DoS attacks through resource exhaustion
+- **Graceful Degradation**: Non-essential features should fail without breaking core functionality
+- **Error Containment**: Failures should be isolated and not cascade throughout the system
+- **User Experience**: Users should never see white screens or completely broken interfaces
+- **Developer Experience**: Clear error reporting and debugging capabilities
+
+### Problem Statement
+The existing JavaScript codebase was vulnerable to:
+1. **Uncaught Exceptions**: Single errors could crash entire UI components
+2. **Input Validation Gaps**: Malicious or malformed input could break processing
+3. **Resource Exhaustion**: Large datasets could freeze the browser
+4. **Dependency Failures**: Missing libraries or features caused complete breakdowns
+5. **DOM Manipulation Risks**: Direct DOM access without safety checks
+6. **Cascading Failures**: One component failure affecting others
+
+## Decision
+
+**We will implement the Robustness Principle as a comprehensive defensive programming strategy with multiple layers of protection throughout the JavaScript codebase, balanced with Fail Fast behavior in development mode to prevent difficult diagnosis and cascading errors.**
+
+## Alternatives Considered
+
+### Option 1: Robustness Principle (Selected)
+**Approach**: Multiple defensive layers with graceful degradation
+**Implementation**: Safe wrappers, input validation, error boundaries, resource limits
+
+### Option 2: Try-Catch Everything
+**Approach**: Wrap all operations in try-catch blocks
+**Implementation**: Granular exception handling without systematic approach
+
+### Option 3: Reactive Error Handling
+**Approach**: Error handling through reactive programming patterns
+**Implementation**: RxJS or similar libraries for error stream management
+
+### Option 4: Minimal Validation
+**Approach**: Basic input checking with assumption of good data
+**Implementation**: Simple null checks and basic validation
+
+## Decision Matrix
+
+| Criteria | Robustness Principle | Try-Catch All | Reactive Patterns | Minimal Validation |
+|----------|---------------------|---------------|-------------------|-------------------|
+| **Fault Tolerance** | ✅ Comprehensive | ⚠️ Inconsistent | ✅ Good | ❌ Poor |
+| **Security Protection** | ✅ Multi-layered | ❌ Reactive only | ⚠️ Limited | ❌ Vulnerable |
+| **Resource Management** | ✅ Proactive limits | ❌ No protection | ⚠️ Some control | ❌ No protection |
+| **Code Maintainability** | ✅ Systematic | ❌ Scattered | ⚠️ Complex | ✅ Simple |
+| **Performance Impact** | ⚠️ Moderate overhead | ⚠️ High overhead | ❌ Library weight | ✅ Minimal |
+| **Developer Experience** | ✅ Clear patterns | ❌ Repetitive | ❌ Learning curve | ✅ Familiar |
+| **Error Recovery** | ✅ Graceful fallbacks | ⚠️ Manual recovery | ✅ Automatic retry | ❌ System failure |
+
+## Balanced Implementation: Robustness + Fail Fast
+
+### Development vs Production Behavior
+
+**Development Mode (Fail Fast)**:
+- Immediate exceptions on errors for fast debugging
+- Strict validation with no silent failures
+- Full error context and stack traces
+- Activated on localhost, 127.0.0.1, or `?strict=true`
+
+**Production Mode (Robust)**:
+- Graceful degradation and fallback behaviors
+- Silent recovery with detailed logging
+- User experience preservation
+- Default behavior in production environments
+
+```javascript
+const MARKITECT_STRICT_MODE = (
+    window.location.hostname === 'localhost' ||
+    window.location.hostname === '127.0.0.1' ||
+    window.location.search.includes('strict=true') ||
+    window.markitectStrictMode === true
+);
+```
+
+## Robustness Principle Implementation
+
+### Layer 1: Input Validation & Sanitization
+**Purpose**: Prevent malicious or malformed data from entering the system
+
+```javascript
+safeTextExtraction(element) {
+    if (!this.validateElement(element)) {
+        return '';
+    }
+
+    try {
+        const text = element.textContent || element.innerText || '';
+        return this.sanitizeText(text.trim());
+    } catch (error) {
+        console.warn('Text extraction failed:', error);
+        return '';
+    }
+}
+
+sanitizeText(text) {
+    if (typeof text !== 'string') return '';
+
+    const maxLength = 100000; // 100KB text limit
+    return text
+        .replace(/[\x00-\x08\x0B\x0C\x0E-\x1F\x7F]/g, '') // Remove control chars
+        .slice(0, maxLength); // Limit length
+}
+```
+
+### Layer 2: Error Boundaries with Fallbacks
+**Purpose**: Contain failures and provide alternative execution paths
+
+```javascript
+safeOperation(operation, fallback = null, context = 'Unknown') {
+    try {
+        return operation();
+    } catch (error) {
+        console.warn(`Operation failed in ${context}:`, error);
+
+        // Fail Fast in development mode
+        if (MARKITECT_STRICT_MODE) {
+            console.error(`🚨 STRICT MODE: Operation failed in ${context}`);
+            throw error; // Re-throw for immediate debugging
+        }
+
+        // Robust handling in production
+        if (window.MarkitectDebugSystem) {
+            window.MarkitectDebugSystem.addMessage(
+                `Safe operation failed: ${error.message}`,
+                'WARNING',
+                'RobustnessSystem',
+                { context, eventType: 'ERROR' }
+            );
+        }
+
+        return typeof fallback === 'function' ? fallback() : fallback;
+    }
+}
+```
+
+### Layer 3: Resource Limits & Timeout Protection
+**Purpose**: Prevent resource exhaustion and infinite operations
+
+```javascript
+// Element processing limits
+const elements = this.safeQuerySelectorAll(selector);
+const maxElements = 10000; // DoS protection
+elements.slice(0, maxElements).forEach(processElement);
+
+// Operation timeouts
+const timeout = setTimeout(() => {
+    if (this.isOperationRunning) {
+        console.warn('Operation timed out');
+        this.cleanup();
+    }
+}, 30000); // 30 second safety timeout
+```
+
+### Layer 4: Graceful Degradation
+**Purpose**: Maintain core functionality when non-essential features fail
+
+```javascript
+// Dependency checking with fallbacks
+initializeControl(controlClass, controlName, icon = '🔧') {
+    if (!controlClass) {
+        this.safeLog(`${controlName} class not available, skipping`, 'WARNING');
+        return null;
+    }
+
+    try {
+        const instance = new controlClass();
+        return instance.createControl() ? instance : null;
+    } catch (error) {
+        // Create minimal fallback for essential controls
+        if (controlName === 'StatusControl') {
+            return this.createFallbackControl(controlName, icon);
+        }
+        return null;
+    }
+}
+```
+
+### Layer 5: Safe DOM Manipulation
+**Purpose**: Protect against DOM-related failures and validate operations
+
+```javascript
+safeQuerySelector(selector, parent = document) {
+    try {
+        if (!parent || !parent.querySelector) {
+            return null;
+        }
+        return parent.querySelector(selector);
+    } catch (error) {
+        console.warn(`Invalid selector: ${selector}`, error);
+        return null;
+    }
+}
+
+validateElement(element) {
+    return element &&
+           element.nodeType === Node.ELEMENT_NODE &&
+           element.isConnected &&
+           !element.closest('.control-panel'); // Avoid control elements
+}
+```
+
+## Rationale
+
+### Why the Robustness Principle?
+
+1. **Systematic Approach**: Unlike ad-hoc try-catch blocks, provides consistent protection patterns
+2. **Multiple Defense Layers**: Each layer catches different types of failures
+3. **Proactive Protection**: Prevents problems before they occur rather than just reacting
+4. **Maintainable Code**: Clear patterns and utility functions reduce repetition
+5. **Production Ready**: Designed for real-world environments with unpredictable conditions
+6. **Performance Conscious**: Adds protection without significant overhead
+
+### Why Not Try-Catch Everything?
+
+- **Maintenance Burden**: Scattered exception handling is hard to maintain
+- **Inconsistent Coverage**: Easy to miss critical paths
+- **Poor Error Recovery**: Just catching errors doesn't provide meaningful fallbacks
+- **Performance Impact**: Exception handling has overhead when overused
+
+### Why Not Reactive Patterns?
+
+- **Complexity**: RxJS adds significant learning curve and bundle size
+- **Overkill**: Our error handling needs don't require reactive streams
+- **Library Dependency**: Adds external dependency for core functionality
+- **Framework Lock-in**: Ties architecture to specific programming paradigm
+
+## Implementation Details
+
+### Core Protection Utilities
+
+```javascript
+// Central error handling system
+const RobustnessSystem = {
+    safeOperation(operation, fallback, context),
+    safeQuerySelector(selector, parent),
+    safeQuerySelectorAll(selector, parent),
+    validateElement(element),
+    sanitizeText(text),
+    safeTextExtraction(element)
+};
+```
+
+### Integration Pattern
+
+```javascript
+// Before: Fragile operation
+function processDocument() {
+    const stats = calculateStats(); // Could crash
+    updateUI(stats); // Could crash
+    saveToStorage(stats); // Could crash
+}
+
+// After: Robust operation
+function processDocument() {
+    const stats = this.safeOperation(
+        () => this.calculateStats(),
+        this.getDefaultStats(),
+        'calculateStats'
+    );
+
+    this.safeOperation(
+        () => this.updateUI(stats),
+        null,
+        'updateUI'
+    );
+
+    this.safeOperation(
+        () => this.saveToStorage(stats),
+        null,
+        'saveToStorage'
+    );
+}
+```
+
+### Resource Protection Examples
+
+```javascript
+// Memory limits
+const characters = Math.min(sectionText.length, 1000000); // Cap at 1MB
+
+// Processing limits
+elements.slice(0, maxElements).forEach(processElement);
+
+// Time limits
+const timeout = setTimeout(cleanup, OPERATION_TIMEOUT);
+```
+
+## Consequences
+
+### Positive
+- ✅ **System Stability**: Individual component failures don't crash the entire application
+- ✅ **Security Hardening**: Multiple layers protect against various attack vectors
+- ✅ **User Experience**: Graceful degradation maintains usability during failures
+- ✅ **Developer Confidence**: Clear patterns reduce fear of production failures
+- ✅ **Debugging Capability**: Detailed error context and logging
+- ✅ **Maintenance Reduction**: Fewer emergency fixes for production issues
+
+### Negative
+- ⚠️ **Performance Overhead**: Additional validation and error checking adds some cost
+- ⚠️ **Code Complexity**: More defensive code requires more careful implementation
+- ⚠️ **Initial Development Time**: Building robust systems takes longer upfront
+
+### Mitigation Strategies
+- **Performance**: Use efficient validation techniques and avoid redundant checks
+- **Complexity**: Provide clear utility functions and documentation
+- **Development Time**: Treat as investment in reduced maintenance and debugging time
+
+## Testing Strategy
+
+### Robustness Testing Categories
+
+1. **Malicious Input Testing**: XSS attempts, oversized data, invalid formats
+2. **Resource Exhaustion Testing**: Large datasets, memory pressure scenarios
+3. **Dependency Failure Testing**: Missing libraries, network failures
+4. **DOM Manipulation Edge Cases**: Invalid selectors, disconnected elements
+5. **Timeout Scenarios**: Long-running operations, infinite loops
+6. **Error Cascade Testing**: Multiple simultaneous failures
+
+### Automated Testing
+
+```javascript
+// Example robustness test
+describe('Robustness Principle', () => {
+    it('should handle malicious text input safely', () => {
+        const maliciousText = '<script>alert("xss")</script>'.repeat(10000);
+        const result = statusControl.safeTextExtraction({ textContent: maliciousText });
+
+        expect(result.length).toBeLessThan(100001); // Respects limits
+        expect(result).not.toContain('<script>'); // Sanitized
+    });
+
+    it('should gracefully handle missing dependencies', () => {
+        delete window.StatusControl;
+        const result = MarkitectMain.initialize();
+
+        expect(result).toBeDefined(); // Doesn't crash
+        expect(window.statusControl).toBeNull(); // Graceful degradation
+    });
+});
+```
+
+## Future Considerations
+
+### Potential Enhancements
+
+1. **Metrics Collection**: Track robustness events for system health monitoring
+2. **Adaptive Thresholds**: Dynamic resource limits based on client capabilities
+3. **Recovery Strategies**: More sophisticated fallback mechanisms
+4. **Performance Monitoring**: Track overhead of robustness measures
+5. **User Feedback**: Notify users when degraded functionality is active
+
+### Evolution Path
+
+The Robustness Principle provides foundation for:
+- **Service Worker Integration**: Offline robustness capabilities
+- **Web Worker Offloading**: Move intensive operations off main thread
+- **Progressive Enhancement**: Advanced features for capable browsers
+- **Error Analytics**: Aggregate error patterns for system improvements
+
+## References
+
+- [Defensive Programming Best Practices](https://en.wikipedia.org/wiki/Defensive_programming)
+- [JavaScript Error Handling Patterns](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Control_flow_and_error_handling)
+- [Web API Security Guidelines](https://developer.mozilla.org/en-US/docs/Web/Security)
+- [Performance Impact of Error Handling](https://v8.dev/docs/optimize)
+
+## Approval
+
+**Decided by**: Claude Code Development Team
+**Date**: 2025-11-11
+**Context**: Production hardening and security enhancement
+**Next Review**: After 6 months of production use or major security incidents

docs/architecture/CAPABILITIES_ARCHITECTURE.md

@@ -0,0 +1,453 @@
+# Capabilities Architecture
+
+## Overview
+
+MarkiTect uses a **capabilities-based architecture** where functionality is organized into independent, reusable packages called **capabilities**. Each capability is a self-contained git submodule with its own repository, enabling independent development, versioning, and reuse across projects.
+
+## Core Principles
+
+### 1. **Separation of Concerns**
+
+**Critical Rule:** The main repository (`markitect_project`) **MUST NOT** directly modify capability code.
+
+- ✅ **DO**: Use capabilities as dependencies
+- ✅ **DO**: Configure capabilities through documented interfaces
+- ✅ **DO**: Report issues and feature requests to capability repos
+- ❌ **DON'T**: Edit capability code from the main repo
+- ❌ **DON'T**: Make commits directly in capability subdirectories
+- ❌ **DON'T**: Bypass the submodule boundary
+
+**Why?** Capabilities are independent repositories. Direct modifications create:
+- Merge conflicts when syncing with upstream
+- Broken dependency management
+- Loss of independent versioning
+- Confusion about source of truth
+
+### 2. **Git Submodule Architecture**
+
+Capabilities are integrated as **git submodules**, not regular directories:
+
+```
+markitect_project/
+├── .gitmodules                    # Submodule configuration
+├── capabilities/
+│   ├── testdrive-jsui/           # Git submodule → separate repo
+│   ├── issue-facade/             # Git submodule → separate repo
+│   ├── kaizen-agentic/           # Git submodule → separate repo
+│   ├── markitect-content/        # Local capability (legacy)
+│   └── release-management/       # Local capability (legacy)
+```
+
+**Submodule vs Local Capabilities:**
+- **Submodules**: Independent git repositories, separate development lifecycle
+- **Local**: Part of main repo, shared lifecycle (being phased out)
+
+**Target State:** All capabilities should eventually be submodules.
+
+### 3. **Independent Development Lifecycle**
+
+Each capability has its own:
+- ✅ Git repository on gitea
+- ✅ Version numbering (semantic versioning)
+- ✅ Issue tracking and roadmap
+- ✅ Testing and CI/CD pipeline
+- ✅ Documentation and README
+- ✅ Contributors and maintainers
+
+### 4. **Interface-Based Integration**
+
+Capabilities expose **stable interfaces** to the main project:
+
+```python
+# markitect uses capability through documented interface
+from testdrive_jsui import TestDriveJSUIEngine
+
+engine = TestDriveJSUIEngine()
+engine.render_document(content, mode='edit', config=config)
+```
+
+**Integration Points:**
+1. **Python Package Interface**: Clean import and API
+2. **Configuration**: Via `pyproject.toml` dependencies
+3. **Plugin System**: Via plugin registration and metadata
+4. **Makefile Targets**: Via capability discovery system
+
+## Development Workflow
+
+### Working on Capabilities
+
+**Rule:** Each capability is developed in **its own Claude Code session**.
+
+#### Main Repository Session
+```bash
+# In markitect_project/
+cd /home/worsch/markitect_project
+
+# Main repo tasks:
+# - Integrate capabilities
+# - Update dependencies
+# - Configure capability usage
+# - Test integration points
+```
+
+#### Capability Session
+```bash
+# In capability repository
+cd /home/worsch/markitect_project/capabilities/testdrive-jsui
+
+# OR clone separately
+git clone http://gitea/coulomb/testdrive-jsui.git
+cd testdrive-jsui
+
+# Capability tasks:
+# - Implement features
+# - Fix bugs
+# - Write tests
+# - Update documentation
+# - Make releases
+```
+
+### Recommended Session Pattern
+
+**Scenario: Need to add feature to testdrive-jsui**
+
+1. **Open separate Claude instance** for testdrive-jsui
+   ```bash
+   # In new terminal/session
+   cd /path/to/testdrive-jsui
+   # Work on feature
+   git commit -m "feat: new feature"
+   git push origin main
+   ```
+
+2. **Update main project** (different Claude instance)
+   ```bash
+   cd /home/worsch/markitect_project
+   git submodule update --remote capabilities/testdrive-jsui
+   git commit -m "chore: update testdrive-jsui submodule"
+   ```
+
+**Why separate instances?**
+- Clear context boundaries
+- Prevents accidental cross-contamination
+- Respects repository independence
+- Better commit hygiene
+
+### Updating Submodules
+
+When a capability releases a new version:
+
+```bash
+# In main repo
+cd /home/worsch/markitect_project
+
+# Update specific capability
+cd capabilities/testdrive-jsui
+git pull origin main
+cd ../..
+git add capabilities/testdrive-jsui
+git commit -m "chore: update testdrive-jsui to v1.2.0"
+
+# Or update all capabilities
+git submodule update --remote
+git commit -am "chore: update all capabilities"
+```
+
+### Adding New Capabilities
+
+```bash
+# 1. Create capability repository on gitea
+# http://gitea/coulomb/new-capability
+
+# 2. Add as submodule to main repo
+cd /home/worsch/markitect_project
+git submodule add http://gitea/coulomb/new-capability.git capabilities/new-capability
+
+# 3. Add dependency to pyproject.toml
+# dependencies = [
+#     "new-capability @ file:./capabilities/new-capability"
+# ]
+
+# 4. Commit submodule addition
+git commit -m "feat: add new-capability as submodule"
+```
+
+## Dependency Management
+
+Capabilities are declared in `pyproject.toml`:
+
+```toml
+[project]
+dependencies = [
+    # Core dependencies
+    "markdown-it-py",
+    "click>=8.0.0",
+
+    # Capabilities (file-based dependencies)
+    "release-management @ file:./capabilities/release-management",
+    "testdrive-jsui @ file:./capabilities/testdrive-jsui",
+    "issue-facade @ file:./capabilities/issue-facade",
+]
+```
+
+**Pattern for Capabilities:**
+```toml
+"capability-name @ file:./capabilities/capability-name"
+```
+
+This enables:
+- ✅ pip install with editable dependencies
+- ✅ Proper package resolution
+- ✅ Clean imports in code
+- ✅ Development mode support
+
+## Capability Structure
+
+Each capability should follow this structure:
+
+```
+capability-name/
+├── README.md                      # Comprehensive documentation
+├── pyproject.toml                 # Package configuration
+├── Makefile                       # Build and test automation
+├── .gitignore                     # Git ignore rules
+├── src/capability_name/           # Python package source
+│   ├── __init__.py
+│   ├── core/                      # Core functionality
+│   ├── utils/                     # Utilities
+│   └── testing/                   # Testing infrastructure
+├── js/                            # JavaScript (if applicable)
+│   ├── components/
+│   ├── controls/
+│   └── tests/
+├── static/                        # Static assets (if applicable)
+│   ├── css/
+│   ├── images/
+│   └── templates/
+├── tests/                         # Python tests
+│   └── test_*.py
+└── docs/                          # Additional documentation
+    ├── API.md
+    └── USAGE.md
+```
+
+### Required Files
+
+1. **README.md** - Must include:
+   - Purpose and description
+   - Installation instructions
+   - Usage examples
+   - API documentation
+   - Integration guide
+
+2. **pyproject.toml** - Must define:
+   - Package metadata
+   - Dependencies
+   - Build system
+   - Entry points
+
+3. **Makefile** - Should include:
+   - help target
+   - test targets
+   - install/setup targets
+   - capability-info target (for discovery)
+
+## Plugin System Integration
+
+For capabilities that provide plugins (like testdrive-jsui):
+
+### Plugin Self-Declaration
+
+```python
+class TestDriveJSUIEngine(RenderingEnginePlugin):
+    """Plugin declares its own location - no hardcoded paths."""
+
+    def get_plugin_source_dir(self) -> Path:
+        """Plugin knows where it lives."""
+        return Path(__file__).parent.parent.parent / "capabilities" / "testdrive-jsui"
+
+    def get_asset_paths(self) -> Dict[str, Path]:
+        """Plugin declares its asset structure."""
+        base = self.get_plugin_source_dir()
+        return {
+            'js': base / 'js',
+            'css': base / 'static' / 'css',
+            'templates': base / 'static' / 'templates',
+        }
+```
+
+### Plugin Discovery
+
+The main repo uses **generic discovery** - no hardcoded capability names:
+
+```python
+# ✅ Good: Generic discovery
+if hasattr(engine, 'get_plugin_source_dir'):
+    source_dir = engine.get_plugin_source_dir()
+
+# ❌ Bad: Hardcoded capability names
+if engine_name == 'testdrive-jsui':
+    source_dir = Path('capabilities/testdrive-jsui')
+```
+
+## Testing Strategy
+
+### Capability Tests
+Each capability tests **in isolation**:
+
+```bash
+cd capabilities/testdrive-jsui
+pytest tests/
+npm test
+```
+
+### Integration Tests
+Main repo tests **integration points**:
+
+```python
+# tests/integration/test_capabilities.py
+def test_testdrive_jsui_integration():
+    """Test that testdrive-jsui integrates correctly."""
+    engine = TestDriveJSUIEngine()
+    result = engine.render_document(sample_content, 'edit', config)
+    assert result is not None
+```
+
+### Test Boundaries
+- **Capability tests**: Internal functionality, unit tests, component tests
+- **Main repo tests**: Integration, configuration, plugin discovery
+
+## Migration Path
+
+### Converting Local Capability to Submodule
+
+1. **Create separate git repo**
+   ```bash
+   cd /tmp
+   cp -r markitect_project/capabilities/capability-name capability-name
+   cd capability-name
+   git init
+   git add .
+   git commit -m "Initial commit"
+   git remote add origin http://gitea/coulomb/capability-name.git
+   git push -u origin main
+   ```
+
+2. **Remove from main repo**
+   ```bash
+   cd markitect_project
+   git rm -rf capabilities/capability-name
+   git commit -m "chore: remove capability-name for submodule conversion"
+   ```
+
+3. **Add as submodule**
+   ```bash
+   git submodule add http://gitea/coulomb/capability-name.git capabilities/capability-name
+   git commit -m "feat: add capability-name as submodule"
+   ```
+
+## Best Practices
+
+### DO ✅
+
+1. **Develop capabilities independently**
+   - Use separate Claude instances
+   - Maintain clear context boundaries
+   - Follow semantic versioning
+
+2. **Use documented interfaces**
+   - Import via Python packages
+   - Use plugin APIs
+   - Follow configuration patterns
+
+3. **Test integration points**
+   - Verify capability imports
+   - Test plugin discovery
+   - Validate configurations
+
+4. **Update submodules explicitly**
+   - Pull capability changes deliberately
+   - Review updates before committing
+   - Update main repo pointer
+
+5. **Document integration**
+   - How to use the capability
+   - Configuration options
+   - Example usage
+
+### DON'T ❌
+
+1. **Edit capability code from main repo**
+   - Opens separate repo/instance instead
+   - Respects submodule boundary
+   - Maintains clean separation
+
+2. **Hardcode capability paths**
+   - Use self-declaration instead
+   - Generic discovery patterns
+   - Interface-based access
+
+3. **Create circular dependencies**
+   - Main depends on capabilities
+   - Capabilities should NOT depend on main
+   - Keep dependency graph acyclic
+
+4. **Bypass submodule system**
+   - Don't manually copy files
+   - Use git submodule commands
+   - Respect version control
+
+## Troubleshooting
+
+### Submodule not updated
+
+```bash
+# Pull latest from capability repo
+cd capabilities/testdrive-jsui
+git pull origin main
+
+# Update main repo pointer
+cd ../..
+git add capabilities/testdrive-jsui
+git commit -m "chore: update testdrive-jsui"
+```
+
+### Import errors
+
+```bash
+# Reinstall capabilities
+pip install -e .
+
+# Or specific capability
+pip install -e ./capabilities/testdrive-jsui
+```
+
+### Merge conflicts in submodules
+
+```bash
+# Don't merge in submodule from main repo!
+# Instead, go to capability repo directly
+
+cd /path/to/separate/testdrive-jsui
+# or
+cd capabilities/testdrive-jsui
+
+# Resolve conflicts there
+git pull origin main
+# fix conflicts
+git push origin main
+
+# Then update main repo
+cd ../../
+git submodule update --remote
+```
+
+## See Also
+
+- [Agent: Capability Manager](../../agents/agent-capability-manager.md) - Automated capability management
+- [Plugin System](../PLUGIN_SYSTEM.md) - Plugin architecture documentation
+- [Git Submodules](https://git-scm.com/book/en/v2/Git-Tools-Submodules) - Official git submodules guide
+
+---
+
+**Remember:** Capabilities are **independent projects**. Treat them with the same respect you'd give any external dependency - use their interfaces, don't modify their internals.

docs/specifications/schema-extensions-spec.md

@@ -0,0 +1,662 @@
+# MarkiTect Schema Extensions Specification v1.0
+
+## Status: Draft - Phase 1 Implementation
+
+## Overview
+
+This specification defines MarkiTect-specific extensions to JSON Schema (draft-07) for markdown document validation with content control, section classification, and flexible structural constraints.
+
+## Design Principles
+
+1. **Backward Compatibility**: Existing schemas without extensions continue to work
+2. **Namespace Isolation**: All extensions prefixed with `x-markitect-`
+3. **Progressive Enhancement**: Extensions add capabilities without breaking standard JSON Schema
+4. **Clear Semantics**: Each extension has well-defined validation behavior
+5. **Metaschema Validation**: All extensions validated by MarkiTect metaschema
+
+---
+
+## Extension: `x-markitect-sections`
+
+### Purpose
+
+Define document sections with classification levels (required, recommended, optional, discouraged, improper) and content control specifications.
+
+### Schema Location
+
+Applied at the **root level** of the schema or within **properties** that represent document sections.
+
+### Format
+
+```json
+{
+  "x-markitect-sections": {
+    "SECTION_NAME": {
+      "classification": "required|recommended|optional|discouraged|improper",
+      "heading_level": 1|2|3|4|5|6,
+      "position": "after_title|before_section_name|after_section_name|anywhere",
+      "content_instruction": "string",
+      "min_paragraphs": integer,
+      "max_paragraphs": integer,
+      "min_code_blocks": integer,
+      "max_code_blocks": integer,
+      "min_lists": integer,
+      "max_lists": integer,
+      "warning_if_missing": "string",
+      "error_message": "string",
+      "alternatives": ["SECTION_NAME_1", "SECTION_NAME_2"]
+    }
+  }
+}
+```
+
+### Property Definitions
+
+#### `classification` (required)
+
+Classification level determining validation behavior:
+
+- **`required`**: Section MUST be present. Validation fails if missing.
+- **`recommended`**: Section SHOULD be present. Warning if missing, but validation succeeds.
+- **`optional`**: Section MAY be present. No validation impact either way.
+- **`discouraged`**: Section SHOULD NOT be present. Warning if present, but validation succeeds.
+- **`improper`**: Section MUST NOT be present. Validation fails if present.
+
+**Type**: String enum
+**Required**: Yes
+**Values**: `["required", "recommended", "optional", "discouraged", "improper"]`
+
+#### `heading_level` (optional)
+
+The heading level (H1-H6) for this section.
+
+**Type**: Integer
+**Range**: 1-6
+**Default**: 2 (for standard sections)
+
+#### `position` (optional)
+
+Where this section should appear relative to other sections.
+
+**Type**: String enum
+**Values**:
+- `"after_title"` - Immediately after document title (H1)
+- `"before_section_name"` - Before another named section
+- `"after_section_name"` - After another named section
+- `"anywhere"` - No position constraint (default)
+
+**Default**: `"anywhere"`
+
+#### `content_instruction` (optional)
+
+Human-readable instruction describing what content belongs in this section.
+
+**Type**: String
+**Usage**: Displayed in validation warnings, generated templates, and documentation
+
+**Example**:
+```json
+"content_instruction": "Brief command syntax showing all options and arguments"
+```
+
+#### Content Constraints (optional)
+
+Minimum and maximum counts for content elements within the section:
+
+- **`min_paragraphs`**: Minimum paragraph count (integer ≥ 0)
+- **`max_paragraphs`**: Maximum paragraph count (integer ≥ min_paragraphs)
+- **`min_code_blocks`**: Minimum code block count (integer ≥ 0)
+- **`max_code_blocks`**: Maximum code block count (integer ≥ min_code_blocks)
+- **`min_lists`**: Minimum list count (integer ≥ 0)
+- **`max_lists`**: Maximum list count (integer ≥ max_lists)
+
+**Type**: Integer
+**Default**: No constraint if omitted
+
+#### `warning_if_missing` (optional)
+
+Custom warning message when a recommended section is missing.
+
+**Type**: String
+**Applies to**: `classification: "recommended"` only
+
+**Example**:
+```json
+"warning_if_missing": "Examples greatly improve documentation usability"
+```
+
+#### `error_message` (optional)
+
+Custom error message when validation fails.
+
+**Type**: String
+**Applies to**: `classification: "required"` or `"improper"`
+
+**Example**:
+```json
+"error_message": "Internal notes must not appear in published documentation"
+```
+
+#### `alternatives` (optional)
+
+Array of alternative section names that satisfy the requirement.
+
+**Type**: Array of strings
+**Usage**: If any alternative is present, requirement is satisfied
+
+**Example**:
+```json
+{
+  "classification": "required",
+  "alternatives": ["EXAMPLES", "USAGE", "TUTORIAL"]
+}
+```
+
+### Example: Manpage Schema with Sections
+
+```json
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "Unix Manpage Schema",
+  "x-markitect-sections": {
+    "SYNOPSIS": {
+      "classification": "required",
+      "heading_level": 2,
+      "position": "after_title",
+      "content_instruction": "Brief command syntax with options and arguments",
+      "min_paragraphs": 1,
+      "max_paragraphs": 5,
+      "min_code_blocks": 0,
+      "max_code_blocks": 3,
+      "error_message": "SYNOPSIS section is mandatory for all manpages"
+    },
+    "DESCRIPTION": {
+      "classification": "required",
+      "heading_level": 2,
+      "position": "after_section_name",
+      "content_instruction": "Detailed explanation of what the command does",
+      "min_paragraphs": 2,
+      "error_message": "DESCRIPTION section is mandatory for all manpages"
+    },
+    "EXAMPLES": {
+      "classification": "recommended",
+      "heading_level": 2,
+      "content_instruction": "Practical usage examples with explanations",
+      "min_code_blocks": 3,
+      "warning_if_missing": "Examples greatly improve manpage usability"
+    },
+    "SEE ALSO": {
+      "classification": "recommended",
+      "heading_level": 2,
+      "content_instruction": "Related commands and documentation references",
+      "warning_if_missing": "Cross-references help users discover related functionality"
+    },
+    "BUGS": {
+      "classification": "optional",
+      "heading_level": 2,
+      "content_instruction": "Known issues and bug reporting information"
+    },
+    "DEPRECATED": {
+      "classification": "discouraged",
+      "heading_level": 2,
+      "warning_if_missing": "Consider moving deprecated content to historical documentation"
+    },
+    "INTERNAL_NOTES": {
+      "classification": "improper",
+      "heading_level": 2,
+      "error_message": "Internal notes must not appear in published manpages"
+    }
+  }
+}
+```
+
+### Validation Behavior
+
+#### Required Sections
+
+```json
+"SYNOPSIS": {"classification": "required"}
+```
+
+**Validation**:
+- Section missing → **ERROR** → `is_valid = False`
+- Section present → Continue validation
+- Custom `error_message` used if provided
+
+#### Recommended Sections
+
+```json
+"EXAMPLES": {"classification": "recommended"}
+```
+
+**Validation**:
+- Section missing → **WARNING** → `is_valid = True` (with warnings)
+- Section present → Continue validation
+- Custom `warning_if_missing` used if provided
+
+#### Optional Sections
+
+```json
+"BUGS": {"classification": "optional"}
+```
+
+**Validation**:
+- Section missing → No impact
+- Section present → Continue validation
+- No messages generated
+
+#### Discouraged Sections
+
+```json
+"DEPRECATED": {"classification": "discouraged"}
+```
+
+**Validation**:
+- Section missing → No impact
+- Section present → **WARNING** → `is_valid = True` (with warnings)
+- Custom warning message used if provided
+
+#### Improper Sections
+
+```json
+"INTERNAL_NOTES": {"classification": "improper"}
+```
+
+**Validation**:
+- Section missing → No impact
+- Section present → **ERROR** → `is_valid = False`
+- Custom `error_message` used if provided
+
+---
+
+## Extension: `x-markitect-content-control`
+
+### Purpose
+
+Define content validation rules for document sections including pattern matching, quality metrics, and semantic constraints.
+
+### Schema Location
+
+Applied at **root level** or within specific **section properties**.
+
+### Format
+
+```json
+{
+  "x-markitect-content-control": {
+    "section_name": {
+      "required_patterns": ["regex_pattern_1", "regex_pattern_2"],
+      "discouraged_patterns": ["regex_pattern_1"],
+      "forbidden_patterns": ["regex_pattern_1"],
+      "content_quality": {
+        "min_words": integer,
+        "max_words": integer,
+        "readability_target": "technical|general|simple|advanced",
+        "min_sentences": integer,
+        "max_sentences": integer
+      },
+      "content_instructions": ["instruction_1", "instruction_2"],
+      "link_validation": {
+        "check_internal": boolean,
+        "check_external": boolean,
+        "allow_fragments": boolean
+      }
+    }
+  }
+}
+```
+
+### Property Definitions
+
+#### `required_patterns` (optional)
+
+Array of regex patterns that MUST appear in section content.
+
+**Type**: Array of strings (valid regex patterns)
+**Validation**: ERROR if any pattern missing
+
+**Example**:
+```json
+"required_patterns": [
+  "\\*\\*[a-z-]+\\*\\*",  // Bold command name
+  "\\[.*\\]"              // Options in brackets
+]
+```
+
+#### `discouraged_patterns` (optional)
+
+Array of regex patterns that SHOULD NOT appear in content.
+
+**Type**: Array of strings (valid regex patterns)
+**Validation**: WARNING if any pattern found
+
+**Example**:
+```json
+"discouraged_patterns": [
+  "TODO",
+  "FIXME",
+  "\\bWIP\\b"
+]
+```
+
+#### `forbidden_patterns` (optional)
+
+Array of regex patterns that MUST NOT appear in content.
+
+**Type**: Array of strings (valid regex patterns)
+**Validation**: ERROR if any pattern found
+
+**Example**:
+```json
+"forbidden_patterns": [
+  "password\\s*=\\s*[\"'].*[\"']",  // Hard-coded passwords
+  "api[_-]?key\\s*=\\s*[\"'].*[\"']"  // Hard-coded API keys
+]
+```
+
+#### `content_quality` (optional)
+
+Quality metrics for section content:
+
+**Sub-properties**:
+- **`min_words`**: Minimum word count (integer ≥ 0)
+- **`max_words`**: Maximum word count (integer ≥ min_words)
+- **`readability_target`**: Target readability level (enum)
+  - `"simple"` - Elementary school level
+  - `"general"` - General audience
+  - `"technical"` - Technical audience
+  - `"advanced"` - Expert/academic level
+- **`min_sentences`**: Minimum sentence count (integer ≥ 0)
+- **`max_sentences`**: Maximum sentence count (integer ≥ min_sentences)
+
+**Example**:
+```json
+"content_quality": {
+  "min_words": 50,
+  "max_words": 300,
+  "readability_target": "technical",
+  "min_sentences": 3
+}
+```
+
+#### `content_instructions` (optional)
+
+Array of human-readable instructions for content creation.
+
+**Type**: Array of strings
+**Usage**: Displayed in templates, validation reports, and documentation
+
+**Example**:
+```json
+"content_instructions": [
+  "Show command name in bold",
+  "Include all major options",
+  "Use italic for arguments and placeholders",
+  "Keep syntax examples concise (1-3 lines)"
+]
+```
+
+#### `link_validation` (optional)
+
+Link checking configuration:
+
+**Sub-properties**:
+- **`check_internal`**: Validate internal document links (boolean)
+- **`check_external`**: Validate external URLs (boolean)
+- **`allow_fragments`**: Allow fragment-only links like `#section` (boolean)
+
+**Default**: All false (no link validation)
+
+**Example**:
+```json
+"link_validation": {
+  "check_internal": true,
+  "check_external": false,
+  "allow_fragments": true
+}
+```
+
+### Example: Content Control for API Documentation
+
+```json
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "API Documentation Schema",
+  "x-markitect-content-control": {
+    "synopsis": {
+      "required_patterns": [
+        "\\*\\*[A-Z]+\\*\\*",  // HTTP method in bold
+        "`/api/.*`"            // Endpoint path in code
+      ],
+      "content_quality": {
+        "min_words": 10,
+        "max_words": 100,
+        "readability_target": "technical"
+      },
+      "content_instructions": [
+        "Start with HTTP method in bold (e.g., **GET**)",
+        "Show endpoint path in code format",
+        "Include brief one-line description"
+      ]
+    },
+    "request_parameters": {
+      "required_patterns": [
+        "\\*\\*[a-z_]+\\*\\*.*\\*[A-Za-z]+\\*"  // Bold param name with italic type
+      ],
+      "content_instructions": [
+        "Use bold for parameter names",
+        "Use italic for parameter types",
+        "Include description for each parameter",
+        "Mark required parameters clearly"
+      ]
+    },
+    "description": {
+      "discouraged_patterns": [
+        "TODO",
+        "FIXME",
+        "TBD"
+      ],
+      "forbidden_patterns": [
+        "password\\s*=",
+        "secret\\s*=",
+        "token\\s*="
+      ],
+      "content_quality": {
+        "min_words": 50,
+        "max_words": 500,
+        "readability_target": "technical",
+        "min_sentences": 3
+      },
+      "link_validation": {
+        "check_internal": true,
+        "check_external": true,
+        "allow_fragments": true
+      }
+    }
+  }
+}
+```
+
+---
+
+## Validation Result Structure
+
+### Enhanced ValidationResult Class
+
+```python
+class ValidationResult:
+    """Result of schema validation with classification support."""
+
+    status: Literal["valid", "valid_with_warnings", "invalid"]
+    errors: List[ValidationError]      # Required/improper violations
+    warnings: List[ValidationWarning]  # Recommended/discouraged violations
+    suggestions: List[str]             # Optional improvements
+    quality_metrics: Dict[str, Any]    # Content quality scores
+```
+
+### Validation Status Values
+
+- **`"valid"`**: No errors, no warnings. Document fully conforms.
+- **`"valid_with_warnings"`**: No errors, but has warnings. Document acceptable but improvable.
+- **`"invalid"`**: Has errors. Document does not conform to schema.
+
+### Error Types
+
+```python
+class ValidationErrorType(Enum):
+    MISSING_REQUIRED_SECTION = "missing_required_section"
+    IMPROPER_SECTION_PRESENT = "improper_section_present"
+    CONTENT_PATTERN_MISSING = "content_pattern_missing"
+    CONTENT_PATTERN_FORBIDDEN = "content_pattern_forbidden"
+    CONTENT_TOO_SHORT = "content_too_short"
+    CONTENT_TOO_LONG = "content_too_long"
+    INVALID_LINK = "invalid_link"
+    STRUCTURE_MISMATCH = "structure_mismatch"
+```
+
+### Warning Types
+
+```python
+class ValidationWarningType(Enum):
+    MISSING_RECOMMENDED_SECTION = "missing_recommended_section"
+    DISCOURAGED_SECTION_PRESENT = "discouraged_section_present"
+    CONTENT_PATTERN_DISCOURAGED = "content_pattern_discouraged"
+    CONTENT_QUALITY_BELOW_TARGET = "content_quality_below_target"
+    READABILITY_MISMATCH = "readability_mismatch"
+```
+
+---
+
+## Metaschema Validation
+
+### Extension Validation Rules
+
+The MarkiTect metaschema validates these extensions:
+
+```json
+{
+  "x-markitect-sections": {
+    "type": "object",
+    "patternProperties": {
+      "^[A-Z][A-Z0-9_ ]*$": {
+        "type": "object",
+        "properties": {
+          "classification": {
+            "type": "string",
+            "enum": ["required", "recommended", "optional", "discouraged", "improper"]
+          },
+          "heading_level": {
+            "type": "integer",
+            "minimum": 1,
+            "maximum": 6
+          },
+          "position": {
+            "type": "string",
+            "enum": ["after_title", "before_section_name", "after_section_name", "anywhere"]
+          },
+          "content_instruction": {"type": "string"},
+          "min_paragraphs": {"type": "integer", "minimum": 0},
+          "max_paragraphs": {"type": "integer", "minimum": 0},
+          "min_code_blocks": {"type": "integer", "minimum": 0},
+          "max_code_blocks": {"type": "integer", "minimum": 0},
+          "min_lists": {"type": "integer", "minimum": 0},
+          "max_lists": {"type": "integer", "minimum": 0},
+          "warning_if_missing": {"type": "string"},
+          "error_message": {"type": "string"},
+          "alternatives": {
+            "type": "array",
+            "items": {"type": "string"}
+          }
+        },
+        "required": ["classification"]
+      }
+    }
+  },
+  "x-markitect-content-control": {
+    "type": "object",
+    "patternProperties": {
+      "^[a-z][a-z0-9_]*$": {
+        "type": "object",
+        "properties": {
+          "required_patterns": {
+            "type": "array",
+            "items": {"type": "string", "format": "regex"}
+          },
+          "discouraged_patterns": {
+            "type": "array",
+            "items": {"type": "string", "format": "regex"}
+          },
+          "forbidden_patterns": {
+            "type": "array",
+            "items": {"type": "string", "format": "regex"}
+          },
+          "content_quality": {
+            "type": "object",
+            "properties": {
+              "min_words": {"type": "integer", "minimum": 0},
+              "max_words": {"type": "integer", "minimum": 0},
+              "readability_target": {
+                "type": "string",
+                "enum": ["simple", "general", "technical", "advanced"]
+              },
+              "min_sentences": {"type": "integer", "minimum": 0},
+              "max_sentences": {"type": "integer", "minimum": 0}
+            }
+          },
+          "content_instructions": {
+            "type": "array",
+            "items": {"type": "string"}
+          },
+          "link_validation": {
+            "type": "object",
+            "properties": {
+              "check_internal": {"type": "boolean"},
+              "check_external": {"type": "boolean"},
+              "allow_fragments": {"type": "boolean"}
+            }
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+---
+
+## Implementation Notes
+
+### Phase 1 Scope
+
+1. Define and document extension formats ✓
+2. Update metaschema to validate extensions
+3. Implement basic classification validation (required/recommended/optional/discouraged/improper)
+4. Create example schemas demonstrating all features
+5. Update CLI to report errors vs warnings separately
+
+### Future Enhancements (Phase 2+)
+
+- Content pattern matching implementation
+- Quality metrics calculation
+- Link validation
+- Readability scoring
+- Position constraints enforcement
+
+---
+
+## Version History
+
+- **v1.0 (Draft)** - Initial specification for Phase 1 implementation
+  - `x-markitect-sections` extension defined
+  - `x-markitect-content-control` extension defined
+  - Validation result structure defined
+  - Metaschema validation rules defined
+
+---
+
+## References
+
+- JSON Schema Draft-07: https://json-schema.org/draft-07/schema
+- MarkiTect Schema Evolution Workplan: `examples/manpages/SCHEMA_EVOLUTION_WORKPLAN.md`
+- Existing Metaschema: `markitect/schemas/markitect-metaschema.json`
+- Metaschema Validator: `markitect/metaschema.py`

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

docs/workplan-testdrive-jsui-capability.md

@@ -0,0 +1,268 @@
+# TestDrive-JSUI Capability Implementation Workplan
+
+## 🎯 **Objective**
+
+Safely extract JavaScript UI framework functionality into a dedicated `testdrive-jsui` capability while:
+- Protecting existing hard-won JavaScript UI functionality
+- Integrating JavaScript tests into the main Python test suite
+- Maintaining 100% test coverage and functionality
+- Creating a clean, extensible architecture for future JavaScript framework development
+
+## 🔍 **Current State Analysis**
+
+### **JavaScript UI Infrastructure:**
+
+```
+markitect/static/js/
+├── core/
+│   └── section-manager.js         (17K lines - Core component)
+├── components/
+│   ├── debug-panel.js            (5.8K lines)
+│   ├── document-controls.js      (7.9K lines)
+│   └── dom-renderer.js           (40K lines - Major component)
+├── utils/                         (Empty - utilities)
+└── tests/                        (2.8K total lines)
+    ├── refactor-test-runner.js    (Custom test framework)
+    ├── test-*.js                  (11 comprehensive test files)
+    └── [Component-specific tests]
+```
+
+### **Testing Infrastructure:**
+- ✅ **Jest framework** configured (`package.json`)
+- ✅ **JSDOM environment** for DOM testing
+- ✅ **Custom RefactorTestRunner** for TDD workflow
+- ✅ **11 comprehensive test files** (2,840 lines total)
+- ✅ **Component integration tests**
+- ✅ **Full workflow testing**
+
+### **Feasibility: HIGHLY FEASIBLE** ✅
+- Well-structured components with clear separation
+- Comprehensive test coverage
+- Modern tooling (Jest + JSDOM)
+- Modular design already in place
+- TDD approach designed for safe refactoring
+
+## 🚀 **Implementation Phases**
+
+### **Phase 1: Foundation Setup** ⏱️ *~2-4 hours*
+
+#### **Step 1.1: Create `testdrive-jsui` Capability Structure**
+```bash
+capabilities/testdrive-jsui/
+├── src/testdrive_jsui/
+│   ├── __init__.py
+│   ├── core/                    # Framework components
+│   ├── components/              # UI components
+│   ├── utils/                   # Utilities
+│   └── tests/                   # Python test wrappers
+├── tests/                       # Native Python tests
+├── js/                          # JavaScript source
+│   ├── core/
+│   ├── components/
+│   ├── utils/
+│   └── tests/
+├── Makefile                     # Capability Makefile
+├── pyproject.toml              # Package config
+├── package.json                # JS dependencies
+├── jest.config.js              # Jest configuration
+└── README.md                   # Documentation
+```
+
+#### **Step 1.2: Setup Package Configuration**
+- **pyproject.toml**: Python package with subprocess/node dependencies
+- **package.json**: Jest + JSDOM + custom dependencies
+- **Makefile**: Integration with main capability system
+- **jest.config.js**: Proper test environment setup
+
+#### **Step 1.3: Create Python-JavaScript Bridge**
+```python
+# testdrive_jsui/testing/js_test_runner.py
+class JavaScriptTestRunner:
+    def run_js_tests(self, test_patterns=None):
+        """Run JavaScript tests via Node.js and return results"""
+
+    def integrate_with_pytest(self):
+        """Make JS tests discoverable by pytest"""
+```
+
+### **Phase 2: Integration Layer** ⏱️ *~3-5 hours*
+
+#### **Step 2.1: Python Test Wrappers**
+```python
+# Integration approach: Subprocess-based
+def test_section_manager_component():
+    result = js_test_runner.run_test('test-section-manager-extraction.js')
+    assert result.success
+    assert result.tests_passed > 0
+
+def test_dom_renderer_component():
+    result = js_test_runner.run_test('test-domrenderer-extraction.js')
+    assert result.success
+```
+
+#### **Step 2.2: Main Test Suite Integration**
+- Add JS test discovery to pytest
+- Create test markers for JavaScript tests
+- Setup parallel execution (optional)
+- Integrate with main Makefile test targets
+
+#### **Step 2.3: Capability Makefile Targets**
+```makefile
+# capabilities/testdrive-jsui/Makefile
+.PHONY: testdrive-jsui-test-js
+testdrive-jsui-test-js: ## Run JavaScript tests
+	npm test
+
+.PHONY: testdrive-jsui-test-integration
+testdrive-jsui-test-integration: ## Run Python-JS integration tests
+	pytest tests/
+
+.PHONY: testdrive-jsui-test-all
+testdrive-jsui-test-all: ## Run all tests (JS + Python integration)
+	npm test && pytest tests/
+```
+
+### **Phase 3: Safe Migration** ⏱️ *~4-6 hours*
+
+#### **Step 3.1: Copy & Test Strategy**
+```bash
+# 1. Copy (don't move) JavaScript files to capability
+cp -r markitect/static/js/* capabilities/testdrive-jsui/js/
+
+# 2. Verify tests still work in new location
+cd capabilities/testdrive-jsui && npm test
+
+# 3. Create Python wrappers and verify integration
+pytest capabilities/testdrive-jsui/tests/
+
+# 4. Add to main test suite gradually
+make test  # Ensure main suite still passes
+```
+
+#### **Step 3.2: Dual-Track Testing** *(Safety First!)*
+- Keep original files until migration complete
+- Run both locations in parallel initially
+- Compare test results for consistency
+- Gradual cutover with rollback option
+
+### **Phase 4: Framework Enhancement** ⏱️ *~2-3 hours*
+
+#### **Step 4.1: Enhanced Testing Framework**
+```javascript
+// Enhanced RefactorTestRunner with Python integration
+class EnhancedTestRunner extends RefactorTestRunner {
+    reportToPython(results) {
+        // JSON output for Python consumption
+    }
+
+    runWithCoverage() {
+        // Coverage reporting
+    }
+}
+```
+
+#### **Step 4.2: Advanced Features**
+- Coverage reporting (Istanbul/nyc)
+- Performance benchmarks
+- Visual regression testing (optional)
+- Component documentation auto-generation
+
+### **Phase 5: Production Integration** ⏱️ *~1-2 hours*
+
+#### **Step 5.1: Main Test Suite Enhancement**
+```makefile
+# Add to main Makefile
+.PHONY: test-js
+test-js: ## Run JavaScript UI tests
+	make testdrive-jsui-test-all
+
+.PHONY: test-all
+test-all: test test-js test-capabilities ## Run all tests including JS
+```
+
+#### **Step 5.2: CI/CD Integration**
+- Update test commands in main suite
+- Ensure capability auto-discovery works
+- Add JS test markers for selective running
+
+## 🔒 **Safety Mechanisms**
+
+### **Risk Mitigation:**
+
+1. **📁 Copy-First Approach**: Never move, always copy initially
+2. **🔄 Dual Testing**: Run tests in both locations during migration
+3. **✅ Gradual Integration**: Add to main suite incrementally
+4. **🎯 Rollback Plan**: Keep original structure until 100% verified
+5. **🧪 Test Verification**: Compare results before/after migration
+
+### **Success Criteria:**
+- ✅ All existing JS tests pass in new capability
+- ✅ Python integration tests pass
+- ✅ Main test suite still 100% green
+- ✅ JavaScript UI functionality unchanged
+- ✅ Performance maintained or improved
+
+## 📋 **Implementation Checklist**
+
+### **Phase 1: Foundation**
+- [ ] Create capability directory structure
+- [ ] Setup pyproject.toml with dependencies
+- [ ] Create package.json with Jest configuration
+- [ ] Implement Python-JavaScript bridge
+- [ ] Create capability Makefile
+- [ ] Write basic README documentation
+
+### **Phase 2: Integration**
+- [ ] Create Python test wrappers for JS tests
+- [ ] Integrate with pytest discovery
+- [ ] Add capability targets to main Makefile
+- [ ] Test integration with main test suite
+
+### **Phase 3: Migration**
+- [ ] Copy JavaScript files to capability
+- [ ] Verify tests work in new location
+- [ ] Create dual-track testing setup
+- [ ] Gradually integrate with main suite
+
+### **Phase 4: Enhancement**
+- [ ] Enhance test framework with Python integration
+- [ ] Add coverage reporting
+- [ ] Performance benchmarking
+- [ ] Documentation generation
+
+### **Phase 5: Production**
+- [ ] Full integration with main test suite
+- [ ] CI/CD pipeline updates
+- [ ] Final verification and cleanup
+
+## ⚡ **Quick Start Option**
+
+For immediate JavaScript test integration (30 minutes):
+
+```python
+def test_javascript_ui_components():
+    """Run all JavaScript tests via subprocess"""
+    import subprocess
+    result = subprocess.run(['npm', 'test'],
+                          capture_output=True, text=True)
+    assert result.returncode == 0, f"JS tests failed: {result.stderr}"
+```
+
+## 🎯 **Expected Outcomes**
+
+- **🔒 Zero-risk migration** with copy-first approach
+- **🧪 Enhanced testing** with Python integration
+- **📊 Better CI/CD** integration
+- **🏗️ Clean architecture** with capability isolation
+- **🚀 Future extensibility** for JavaScript framework evolution
+
+## ⏱️ **Timeline**
+
+**Total Estimated Time: 12-20 hours** (can be done incrementally)
+
+**Recommended approach**: Start with Phase 1 for immediate value and safe migration path setup.
+
+---
+
+*Generated: 2025-11-09*
+*Status: Ready for Implementation*

examples/design-patterns/CopyFirstMigration.md

@@ -0,0 +1,158 @@
+# Design Principle: Copy First Migration
+
+## Meta
+- **Name:** Copy First Migration
+- **ShortName:** CopyFirst
+- **Version:** 0.1
+- **Status:** Draft
+- **Tags:** refactoring, migration, safety, testing, legacy
+- **RelatedPrinciples:** Don’t Repeat Yourself, Safe Refactoring, Test Pyramid, Capability-Based Testing
+
+---
+
+## Intent
+Enable safe refactoring and structural migration of codebases by preserving
+existing, working functionality until the new implementation is fully verified.
+
+This principle prioritizes **reversibility, confidence, and continuity** over
+speed or elegance.
+
+---
+
+## CoreStatement
+Never move code directly; always copy first and delete only after verified
+behavioral equivalence is established.
+
+---
+
+## Scope
+
+### InScope
+- Large-scale refactors or directory restructurings
+- Technology or language migrations (e.g. JS → new JS layout, JS → Python integration)
+- Legacy code stabilization
+- Safety-critical or business-critical systems
+- Situations with incomplete test coverage
+
+### OutOfScope
+- Greenfield development
+- Trivial refactors with full and trusted test coverage
+- One-off throwaway scripts
+- Performance-driven rewrites where duplication is unacceptable
+
+---
+
+## InterpretationGuidelines
+
+### What “Copy First” Means
+- The original code remains untouched and functional
+- The new version is treated as **experimental until proven**
+- Deletion is a **final, explicit act**, not an implicit side effect
+
+### Common Misinterpretations
+- “This is inefficient because it duplicates code”  
+  → Duplication is intentional and temporary
+- “Moving files is faster”  
+  → Speed is not the optimization target here
+- “Tests alone are enough”  
+  → Tests are necessary but not sufficient without behavioral comparison
+
+---
+
+## DetectionHeuristics
+
+### Structural Signals
+- Files or modules being relocated across directories or packages
+- Parallel implementations during migration
+- Introduction of a new architectural boundary
+
+### Semantic Signals
+- Code paths that must remain behaviorally identical
+- Business rules with high regression risk
+- Legacy logic that is poorly documented but relied upon
+
+### Change-Cost Signals
+- Rollbacks are expensive or disruptive
+- Failures would impact production or customers
+- Migration spans multiple commits or teams
+
+---
+
+## DiagnosticQuestions
+1. What breaks if this migration is wrong?
+2. Do we have a known-good reference implementation?
+3. Can both old and new code paths run in parallel?
+4. How quickly can we revert if a defect is found?
+5. What is the minimal proof of behavioral equivalence?
+
+---
+
+## RecommendedActions
+
+### Low-Risk Actions
+- Copy files to the new location instead of moving
+- Preserve original imports and entry points
+- Add logging or tracing for comparison
+
+### Medium-Risk Actions
+- Introduce dual-track execution (old + new)
+- Add integration tests targeting both implementations
+- Compare outputs, side effects, and error behavior
+
+### High-Risk Actions
+- Switch production usage to the new implementation
+- Remove old code only after full verification
+- Collapse duplicated paths once confidence is established
+
+---
+
+## AcceptanceCriteria
+- Original code remains functional until final removal
+- New code passes all existing tests
+- New integration tests validate identical behavior
+- Dual-track comparisons show no regressions
+- Deletion of old code is deliberate and reversible up to the final step
+
+---
+
+## AntiPatterns
+- Moving files directly without a fallback
+- Refactoring and migration in a single irreversible step
+- Deleting “unused” code before equivalence is proven
+- Assuming test parity guarantees behavioral parity
+- Big-bang migrations without rollback paths
+
+---
+
+## Tradeoffs
+Applying Copy First Migration intentionally:
+- Introduces temporary duplication
+- Increases short-term codebase size
+- Slows perceived progress
+
+These costs are justified by dramatically reduced risk and higher confidence
+during complex migrations.
+
+---
+
+## AgentUsage
+
+### When to Apply This Lens
+- During directory, module, or architecture migrations
+- When refactoring legacy or poorly understood code
+- When safety and uptime matter more than speed
+- When rollback must remain possible at all times
+
+### When to Suspend This Lens
+- In greenfield projects
+- When full test coverage and confidence already exist
+- For trivial mechanical refactors
+
+### Expected Agent Output
+- Identification of migration boundaries
+- Copy-first migration plan with explicit stages
+- Test strategy (unit, integration, dual-track)
+- Rollback points and deletion criteria
+- Clear signal for when old code may be removed
+
+xxx

examples/design-patterns/DesignPrincipleSchema.json

@@ -0,0 +1,135 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "object",
+  "title": "Schema for DesignPrinciples",
+  "description": "JSON schema describing the markdown structure of OperationalKnowledge DesignPrinciples",
+  "properties": {
+    "headings": {
+      "type": "object",
+      "description": "Document heading structure",
+      "properties": {
+        "level_1": {
+          "type": "array",
+          "description": "Headings at level 1",
+          "items": {
+            "type": "object",
+            "properties": {
+              "content": {
+                "type": "string"
+              },
+              "level": {
+                "type": "integer"
+              },
+              "position": {
+                "type": "integer"
+              }
+            },
+            "required": [
+              "content",
+              "level"
+            ]
+          },
+          "minItems": 1,
+          "maxItems": 1
+        },
+        "level_2": {
+          "type": "array",
+          "description": "Headings at level 2",
+          "items": {
+            "type": "object",
+            "properties": {
+              "content": {
+                "type": "string"
+              },
+              "level": {
+                "type": "integer"
+              },
+              "position": {
+                "type": "integer"
+              }
+            },
+            "required": [
+              "content",
+              "level"
+            ]
+          },
+          "minItems": 4,
+          "maxItems": 12
+        },
+        "level_3": {
+          "type": "array",
+          "description": "Headings at level 3",
+          "items": {
+            "type": "object",
+            "properties": {
+              "content": {
+                "type": "string"
+              },
+              "level": {
+                "type": "integer"
+              },
+              "position": {
+                "type": "integer"
+              }
+            },
+            "required": [
+              "content",
+              "level"
+            ]
+          },
+          "minItems": 0,
+          "maxItems": 40
+        }
+      }
+    },
+    "paragraphs": {
+      "type": "array",
+      "description": "Text paragraphs",
+      "minItems": 8,
+      "maxItems": 120
+    },
+    "lists": {
+      "type": "array",
+      "description": "Lists (ordered and unordered)",
+      "minItems": 0,
+      "maxItems": 20
+    },
+    "emphasis": {
+      "type": "array",
+      "description": "Text emphasis (bold, italic)",
+      "minItems": 0,
+      "maxItems": 120
+    },
+    "metadata": {
+      "type": "object",
+      "description": "Document structure metadata",
+      "properties": {
+        "total_elements": {
+          "type": "integer",
+          "const": 115
+        },
+        "structure_types": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "All structural element types found",
+          "const": [
+            "paragraph_close",
+            "heading_close",
+            "hr",
+            "bullet_list_open",
+            "paragraph_open",
+            "heading_open",
+            "ordered_list_open",
+            "ordered_list_close",
+            "inline",
+            "list_item_close",
+            "list_item_open",
+            "bullet_list_close"
+          ]
+        }
+      }
+    }
+  }
+}

examples/design-patterns/DontRepeatYourself.md

@@ -0,0 +1,160 @@
+# Design Principle: Don’t Repeat Yourself (DRY)
+
+## Meta
+- **Name:** Don’t Repeat Yourself
+- **ShortName:** DRY
+- **Version:** 0.1
+- **Status:** Stable
+- **Tags:** maintainability, refactoring, architecture, quality
+- **RelatedPrinciples:** Single Responsibility, YAGNI, Separation of Concerns
+
+---
+
+## Intent
+Reduce maintenance cost and behavioral drift by ensuring that each piece of
+knowledge, rule, or decision logic has a single authoritative representation
+in the codebase.
+
+---
+
+## CoreStatement
+A codebase violates DRY when the same knowledge is expressed in multiple places
+such that a change would require edits in more than one location or risks
+inconsistent behavior.
+
+---
+
+## Scope
+
+### InScope
+- Business rules and decision logic
+- Algorithms and validation logic
+- Data schemas, DTOs, and field definitions
+- Configuration values and feature flags
+- Repeated workflows or orchestration logic
+- Test setup and invariant test scenarios
+
+### OutOfScope
+- Superficial textual similarity without shared meaning
+- Intentional duplication for isolation or clarity
+- Early-stage exploratory code where abstractions are not yet clear
+- Performance-driven duplication with explicit justification
+
+---
+
+## InterpretationGuidelines
+
+### What “Repeat” Means
+DRY is about **duplication of knowledge**, not duplication of text.
+
+Examples of knowledge duplication:
+- The same validation rule implemented in multiple services
+- Identical conditional logic controlling the same behavior
+- The same data structure defined independently in multiple modules
+
+### Common Misinterpretations
+- “Any repeated code is bad” (false)
+- “DRY means maximum abstraction” (false)
+- “Utility modules automatically improve DRY” (often false)
+
+---
+
+## DetectionHeuristics
+
+### Structural Signals
+- Functions with highly similar bodies and signatures
+- Repeated constants, strings, regexes, or SQL fragments
+- Parallel modules with mirrored internal structure
+
+### Semantic Signals
+- Identical error messages or validation rules in different layers
+- Repeated mapping logic between the same concepts
+- Copy-paste variations differing only in naming
+
+### Change-Cost Signals
+- A requirement change touches multiple files for the same reason
+- Fixes applied in one location but missing in others
+- Tests failing inconsistently after partial updates
+
+---
+
+## DiagnosticQuestions
+1. Is this duplication representing the same rule or policy?
+2. If this rule changes, how many places must be updated?
+3. Is the duplicated logic stable or likely to evolve?
+4. Are the differences intentional or accidental?
+5. Where is the natural “source of truth” for this knowledge?
+6. Would abstraction reduce or increase cognitive load?
+
+---
+
+## RecommendedActions
+
+### Low-Risk Refactors
+- Extract constants or configuration values
+- Centralize literals and error messages
+- Introduce shared test fixtures or helpers
+
+### Medium-Risk Refactors
+- Extract pure helper functions
+- Introduce shared domain services or modules
+- Unify schema/type definitions
+
+### High-Risk Refactors
+- Introduce strategy/template patterns
+- Merge parallel subsystems
+- Redesign domain boundaries to align ownership of rules
+
+---
+
+## AcceptanceCriteria
+- Each rule or behavior has a single authoritative implementation
+- Required changes affect fewer locations than before
+- Naming reflects domain meaning, not technical convenience
+- Tests pass without behavior regression
+- Coupling does not increase unintentionally
+
+---
+
+## AntiPatterns
+- “God” utility modules with unrelated helpers
+- Over-generalized abstractions with many parameters
+- Shared code across domains that should evolve independently
+- Premature abstraction of coincidental similarities
+- Hiding meaningful differences behind generic interfaces
+
+---
+
+## Tradeoffs
+Applying DRY may:
+- Increase indirection
+- Reduce local readability
+- Introduce coupling between modules
+
+These costs are acceptable only when outweighed by reduced change cost
+and increased behavioral consistency.
+
+---
+
+## AgentUsage
+
+### When to Apply This Lens
+- During refactoring or maintenance work
+- When change requests repeatedly touch similar code
+- When bugs recur due to partial updates
+- During architectural consolidation
+
+### When to Suspend This Lens
+- During early exploration or prototyping
+- When future variability is unclear
+- When isolation is more valuable than reuse
+
+### Expected Agent Output
+- Identified DRY violations with locations
+- Rationale for why duplication matters
+- Volatility assessment (stable vs evolving)
+- Recommended refactor type and target
+- Risk notes and minimal patch sequence
+
+xxx
+

examples/manpages/README.md

@@ -0,0 +1,387 @@
+# Unix Manpage Schema Validation Example
+
+This example demonstrates MarkiTect's schema validation system by creating a self-validating documentation set: a schema that defines Unix manpage structure and a comprehensive manual about schema validation that validates against its own schema definition.
+
+## Overview
+
+This example showcases the "dogfooding" principle - using MarkiTect's schema validation to document schema validation itself. It demonstrates:
+
+- **Schema-driven documentation** - Defining document structure with JSON Schema
+- **Self-validation** - The manual validates against the manpage schema it demonstrates
+- **Reusable patterns** - The manpage schema can validate any Unix-style manual page
+- **Complete workflow** - From schema creation through validation and refinement
+
+## Files in This Example
+
+### Schema File
+
+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`
+- Requires SYNOPSIS and DESCRIPTION sections
+- Validates heading hierarchy (H1, H2, H3, H4)
+- Ensures presence of code examples, paragraphs, and emphasis
+- Includes custom `x-markitect-*` extensions for manpage conventions
+
+**Schema Requirements:**
+- Exactly 1 H1 heading (document title)
+- 3-30 H2 headings (major sections)
+- 0-50 H3 headings (subsections)
+- 5-500 paragraphs (content)
+- 1-50 code blocks (examples)
+- 10-500 emphasis elements (commands/arguments)
+
+### `markdown-schema-validation.1.md`
+
+A comprehensive manual page (section 7) documenting MarkiTect's markdown schema validation system.
+
+**Sections Include:**
+- SYNOPSIS - Command syntax reference
+- DESCRIPTION - How schema validation works
+- SCHEMA STRUCTURE - JSON Schema format details
+- COMMANDS - Schema management and validation commands
+- WORKFLOW - Step-by-step validation workflows
+- VALIDATION RULES - What schemas validate
+- ERROR HANDLING - Understanding validation errors
+- SCHEMA DESIGN - Best practices and anti-patterns
+- INTEGRATION - CI/CD, git hooks, build systems
+- EXAMPLES - Practical usage demonstrations
+- Plus standard manpage sections: FILES, EXIT STATUS, ENVIRONMENT, SEE ALSO, etc.
+
+**Statistics:**
+- 19 H2 sections
+- 24 H3 subsections
+- 147 paragraphs
+- 23 code examples
+- 105 emphasis markers
+
+## Running the Example
+
+### 1. List Available Schemas
+
+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 manpage-schema-v1.0.md
+```
+
+Expected output: ✅ **VALID** - Document structure matches schema requirements
+
+### 3. Show Detailed Validation
+
+See detailed validation information:
+
+```bash
+markitect schema-validate manpage-schema-v1.0.md --detailed-errors
+```
+
+### 4. Validate Multiple Schemas
+
+Validate all registered schemas at once:
+
+```bash
+# Validate all schemas
+markitect schema-validate --all
+
+# Validate a range of schemas
+markitect schema-validate 1-3
+
+# Validate specific schemas
+markitect schema-validate 1,3,5
+```
+
+### 5. Examine the Schema
+
+View the manpage schema in markdown format:
+
+```bash
+markitect schema-get manpage-schema-v1.0.md
+
+# Or view the file directly
+cat ../../markitect/schemas/manpage-schema-v1.0.md
+```
+
+### 6. Validate Other Manpages
+
+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 manpage-schema-v1.0.md
+```
+
+## What This Example Demonstrates
+
+### 1. Schema-Driven Documentation
+
+The manpage schema defines what a valid Unix manual page looks like:
+
+- Required structural elements (title, synopsis, description)
+- Heading hierarchy constraints
+- Content density requirements (minimum paragraphs, code examples)
+- Formatting conventions (bold commands, italic arguments)
+
+### 2. Self-Validating System
+
+The schema validation manual validates against the manpage schema, proving:
+
+- The schema is practical and usable
+- The manual follows manpage conventions
+- Schema validation works as documented
+- The system is reliable enough to document itself
+
+### 3. Structural vs Semantic Validation
+
+The schema validates **structure**, not **content**:
+
+- ✅ Validates: Correct number of sections, heading levels, code examples present
+- ❌ Does not validate: Grammar, code correctness, factual accuracy, logical flow
+
+This distinction is crucial for understanding what schemas can and cannot do.
+
+### 4. Reusable Patterns
+
+The manpage schema is a reusable pattern that can:
+
+- Validate any Unix-style manual page
+- Enforce documentation consistency across a project
+- Generate templates for new documentation
+- Integrate into CI/CD pipelines for quality checks
+
+### 5. Custom Schema Extensions
+
+The schema demonstrates MarkiTect's custom extensions:
+
+```json
+"x-markitect-required-sections": [
+  "SYNOPSIS",
+  "DESCRIPTION"
+],
+"x-markitect-recommended-sections": [
+  "OPTIONS",
+  "EXAMPLES",
+  "SEE ALSO"
+],
+"x-markitect-conventions": {
+  "heading_case": "UPPERCASE for H2 sections",
+  "command_format": "Bold with **command**",
+  "argument_format": "Italic with *ARG*"
+}
+```
+
+These extensions provide metadata about schema intent and conventions beyond structural validation.
+
+## Validation Workflow Demonstrated
+
+This example shows the complete schema validation workflow:
+
+### Step 1: Schema Creation
+- Analyze existing manpages (markitect.1.md, issue.1.md)
+- Identify common structural patterns
+- Generate base schema from example document
+- Refine schema to be flexible yet meaningful
+
+### Step 2: Schema Refinement
+- Adjust minItems/maxItems for appropriate ranges
+- Add custom MarkiTect extensions
+- Include heading patterns and conventions
+- Balance strictness with flexibility
+
+### Step 3: Document Creation
+- Write document following schema structure
+- Use template generated from schema as starting point
+- Ensure all required sections present
+- Include appropriate code examples and formatting
+
+### Step 4: Validation
+- Validate document against schema
+- Review validation errors if any
+- Fix structural issues
+- Re-validate until passing
+
+### Step 5: Iteration
+- Refine schema based on validation experience
+- Adjust constraints for real-world use cases
+- Document lessons learned
+- Share schema for reuse
+
+## Integration Examples
+
+### CI/CD Integration
+
+Add to `.github/workflows/docs.yml` or similar:
+
+```yaml
+- name: Validate Manpages
+  run: |
+    for manpage in docs/manuals/*.md; do
+      markitect validate "$manpage" \
+        --schema manpage-schema-v1.0.md \
+        || exit 1
+    done
+```
+
+### Pre-commit Hook
+
+Add to `.git/hooks/pre-commit`:
+
+```bash
+#!/bin/bash
+changed_manpages=$(git diff --cached --name-only --diff-filter=ACM | grep 'docs/manuals/.*\.md$')
+
+for manpage in $changed_manpages; do
+    markitect validate "$manpage" \
+        --schema manpage-schema-v1.0.md \
+        --quiet || {
+        echo "Manpage validation failed: $manpage"
+        markitect validate "$manpage" \
+            --schema manpage-schema-v1.0.md \
+            --detailed-errors
+        exit 1
+    }
+done
+```
+
+### Makefile Integration
+
+Add to project `Makefile`:
+
+```makefile
+.PHONY: validate-manpages
+validate-manpages:
+	@echo "Validating manual pages..."
+	@for manpage in docs/manuals/*.md; do \
+		markitect validate "$$manpage" \
+			--schema manpage-schema-v1.0.md \
+			|| exit 1; \
+	done
+	@echo "✅ All manpages valid"
+
+.PHONY: docs
+docs: validate-manpages
+	# Continue with doc generation...
+```
+
+## Key Lessons from This Example
+
+### 1. Start with Real Documents
+
+The manpage schema was created by analyzing existing manpages (markitect.1.md, issue.1.md), not designed in isolation. This ensures the schema reflects real-world usage.
+
+### 2. Use Ranges, Not Exact Counts
+
+The schema uses ranges like `5-500 paragraphs` instead of exact counts. This provides flexibility while still enforcing quality standards.
+
+### 3. Required vs Recommended
+
+The schema distinguishes between required sections (SYNOPSIS, DESCRIPTION) and recommended sections (EXAMPLES, SEE ALSO), allowing flexibility where appropriate.
+
+### 4. Validate Structure, Not Semantics
+
+Schemas validate document structure, not content quality. Grammar checking, code correctness, and factual accuracy require other tools.
+
+### 5. Progressive Refinement
+
+Schemas should evolve based on validation experience. Start loose, tighten based on actual needs, never over-specify.
+
+### 6. Documentation is Essential
+
+The schema includes extensive metadata about conventions and intent through custom extensions, making it self-documenting.
+
+## Extending This Example
+
+### Create Schema Variants
+
+Create specialized schemas for different manpage types:
+
+```bash
+# For command manpages (section 1)
+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 markitect/schemas/manpage-schema-v1.0.md format-manpage-schema-v1.0.md
+# Edit to require FORMAT section
+
+# For convention manpages (section 7)
+cp markitect/schemas/manpage-schema-v1.0.md convention-manpage-schema-v1.0.md
+# Edit to be more flexible
+```
+
+### Validate Your Own Documentation
+
+Apply the manpage schema to your project:
+
+```bash
+# Validate README (if it follows manpage structure)
+markitect validate README.md \
+    --schema manpage-schema-v1.0.md
+
+# May need adjustments for non-manpage docs
+```
+
+### Generate Schema Family
+
+Create schemas for related document types:
+
+- API documentation schema
+- Tutorial schema
+- RFC/specification schema
+- Architecture decision record (ADR) schema
+
+Each can follow similar validation principles while enforcing type-specific structure.
+
+## Further Reading
+
+- **markdown-schema-validation.1.md** - Complete reference for schema validation
+- **../../docs/manuals/markitect.1.md** - MarkiTect command reference
+- **JSON Schema Specification** - https://json-schema.org/
+- **Unix Manual Page Conventions** - `man 7 man-pages` on Unix systems
+
+## Validation Results
+
+This example has been validated to confirm:
+
+✅ Manual validates against manpage schema
+✅ Schema is well-formed JSON Schema draft-07
+✅ All required sections present in manual
+✅ Heading hierarchy follows Unix conventions
+✅ Code examples demonstrate actual usage
+✅ Structure matches defined constraints
+
+## License
+
+Part of the MarkiTect project. Licensed under MIT License.
+
+---
+
+**Note**: This example represents a complete, production-ready use case of MarkiTect's schema validation system. The files can be used as-is or adapted for your own documentation requirements.

examples/manpages/api-documentation-schema.json

@@ -0,0 +1,230 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "API Endpoint Documentation Schema",
+  "description": "Schema for API endpoint documentation with classification and content control",
+  "x-markitect-sections": {
+    "ENDPOINT": {
+      "classification": "required",
+      "heading_level": 2,
+      "position": "after_title",
+      "content_instruction": "HTTP method and endpoint path (e.g., GET /api/v1/users)",
+      "min_paragraphs": 1,
+      "max_paragraphs": 3,
+      "error_message": "ENDPOINT section must specify the HTTP method and path"
+    },
+    "DESCRIPTION": {
+      "classification": "required",
+      "heading_level": 2,
+      "content_instruction": "What this endpoint does and when to use it",
+      "min_paragraphs": 2,
+      "error_message": "DESCRIPTION is required to explain endpoint functionality"
+    },
+    "AUTHENTICATION": {
+      "classification": "required",
+      "heading_level": 2,
+      "content_instruction": "Authentication requirements (API key, OAuth, etc.)",
+      "min_paragraphs": 1,
+      "error_message": "AUTHENTICATION requirements must be documented"
+    },
+    "REQUEST PARAMETERS": {
+      "classification": "recommended",
+      "heading_level": 2,
+      "content_instruction": "List all request parameters with types and descriptions",
+      "alternatives": ["PARAMETERS", "REQUEST", "INPUT"],
+      "warning_if_missing": "Documenting request parameters helps API consumers use the endpoint correctly"
+    },
+    "RESPONSE": {
+      "classification": "recommended",
+      "heading_level": 2,
+      "content_instruction": "Response format, status codes, and example responses",
+      "min_code_blocks": 1,
+      "warning_if_missing": "Response documentation with examples improves API usability"
+    },
+    "EXAMPLES": {
+      "classification": "recommended",
+      "heading_level": 2,
+      "content_instruction": "Complete request/response examples",
+      "min_code_blocks": 2,
+      "warning_if_missing": "Examples make API documentation significantly more useful"
+    },
+    "ERROR CODES": {
+      "classification": "recommended",
+      "heading_level": 2,
+      "content_instruction": "Possible error responses and how to handle them",
+      "alternatives": ["ERRORS", "ERROR HANDLING"],
+      "warning_if_missing": "Error documentation helps developers handle failures gracefully"
+    },
+    "RATE LIMITING": {
+      "classification": "optional",
+      "heading_level": 2,
+      "content_instruction": "Rate limit information for this endpoint"
+    },
+    "CHANGELOG": {
+      "classification": "optional",
+      "heading_level": 2,
+      "content_instruction": "Version history and changes to this endpoint"
+    },
+    "SEE ALSO": {
+      "classification": "optional",
+      "heading_level": 2,
+      "content_instruction": "Related endpoints and documentation"
+    },
+    "IMPLEMENTATION NOTES": {
+      "classification": "discouraged",
+      "heading_level": 2,
+      "warning_if_missing": "Implementation details should be in developer documentation, not API docs"
+    },
+    "INTERNAL API": {
+      "classification": "improper",
+      "heading_level": 2,
+      "error_message": "Internal API endpoints must not be in public documentation"
+    },
+    "EXPERIMENTAL": {
+      "classification": "improper",
+      "heading_level": 2,
+      "error_message": "Experimental features must not be in stable API documentation"
+    }
+  },
+  "x-markitect-content-control": {
+    "endpoint": {
+      "required_patterns": [
+        "\\*\\*[A-Z]+\\*\\*",
+        "`/api/",
+        "\\*\\*[A-Z]+\\*\\*\\s+`/[^`]+`"
+      ],
+      "content_quality": {
+        "min_words": 5,
+        "max_words": 50,
+        "readability_target": "technical"
+      },
+      "content_instructions": [
+        "Format: **METHOD** `endpoint_path`",
+        "Example: **GET** `/api/v1/users/{id}`",
+        "Use bold for HTTP method",
+        "Use code formatting for path",
+        "Include path parameters in curly braces"
+      ]
+    },
+    "description": {
+      "discouraged_patterns": [
+        "TODO",
+        "FIXME",
+        "TBD",
+        "Coming soon"
+      ],
+      "forbidden_patterns": [
+        "password",
+        "secret",
+        "api[_-]?key\\s*=",
+        "token\\s*="
+      ],
+      "content_quality": {
+        "min_words": 30,
+        "max_words": 500,
+        "readability_target": "technical",
+        "min_sentences": 2
+      },
+      "content_instructions": [
+        "Explain what the endpoint does",
+        "Describe the main use case",
+        "Mention any prerequisites",
+        "Note any side effects",
+        "Keep concise but complete"
+      ]
+    },
+    "request_parameters": {
+      "required_patterns": [
+        "\\*\\*[a-z_]+\\*\\*",
+        "\\*[A-Za-z]+\\*"
+      ],
+      "content_instructions": [
+        "Use bold for parameter names",
+        "Use italic for parameter types",
+        "Include: name, type, required/optional, description",
+        "Use definition list format",
+        "Specify default values where applicable"
+      ]
+    },
+    "response": {
+      "required_patterns": [
+        "```json",
+        "200",
+        "\\{[^}]*\\}"
+      ],
+      "content_quality": {
+        "min_words": 50,
+        "max_words": 500,
+        "readability_target": "technical"
+      },
+      "content_instructions": [
+        "Show example JSON response",
+        "Document all status codes",
+        "Explain response fields",
+        "Include success and error examples",
+        "Use proper JSON formatting in code blocks"
+      ]
+    },
+    "examples": {
+      "required_patterns": [
+        "```bash",
+        "curl",
+        "```json"
+      ],
+      "content_quality": {
+        "min_words": 100,
+        "max_words": 1000,
+        "readability_target": "general"
+      },
+      "content_instructions": [
+        "Provide complete curl examples",
+        "Show request headers",
+        "Include example responses",
+        "Add explanatory comments",
+        "Cover common scenarios"
+      ],
+      "link_validation": {
+        "check_internal": true,
+        "check_external": true,
+        "allow_fragments": true
+      }
+    }
+  },
+  "type": "object",
+  "properties": {
+    "headings": {
+      "type": "object",
+      "properties": {
+        "level_1": {
+          "type": "array",
+          "minItems": 1,
+          "maxItems": 1
+        },
+        "level_2": {
+          "type": "array",
+          "minItems": 3,
+          "maxItems": 15
+        },
+        "level_3": {
+          "type": "array",
+          "minItems": 0,
+          "maxItems": 30
+        }
+      }
+    },
+    "paragraphs": {
+      "type": "array",
+      "minItems": 8,
+      "maxItems": 200
+    },
+    "code_blocks": {
+      "type": "array",
+      "minItems": 3,
+      "maxItems": 30
+    },
+    "emphasis": {
+      "type": "array",
+      "minItems": 15,
+      "maxItems": 200
+    }
+  }
+}

examples/manpages/enhanced-manpage-schema.json

@@ -0,0 +1,229 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "Enhanced Markdown Manpage Schema with Classifications",
+  "description": "JSON schema for Unix-style manual pages with section classification and content control",
+  "x-markitect-sections": {
+    "SYNOPSIS": {
+      "classification": "required",
+      "heading_level": 2,
+      "position": "after_title",
+      "content_instruction": "Brief command syntax showing all options and arguments in standard format",
+      "min_paragraphs": 1,
+      "max_paragraphs": 5,
+      "min_code_blocks": 0,
+      "max_code_blocks": 3,
+      "error_message": "SYNOPSIS section is mandatory for all manpages per Unix conventions"
+    },
+    "DESCRIPTION": {
+      "classification": "required",
+      "heading_level": 2,
+      "content_instruction": "Detailed explanation of what the command does, its purpose, and main functionality",
+      "min_paragraphs": 2,
+      "max_paragraphs": 50,
+      "error_message": "DESCRIPTION section is mandatory for all manpages"
+    },
+    "EXAMPLES": {
+      "classification": "recommended",
+      "heading_level": 2,
+      "content_instruction": "Practical usage examples with explanations demonstrating common use cases",
+      "min_code_blocks": 3,
+      "max_code_blocks": 20,
+      "warning_if_missing": "Examples greatly improve manpage usability - highly recommended"
+    },
+    "SEE ALSO": {
+      "classification": "recommended",
+      "heading_level": 2,
+      "content_instruction": "Related commands, configuration files, and documentation references",
+      "min_paragraphs": 1,
+      "warning_if_missing": "Cross-references help users discover related functionality"
+    },
+    "OPTIONS": {
+      "classification": "recommended",
+      "heading_level": 2,
+      "content_instruction": "Detailed option descriptions with all flags and their behaviors",
+      "alternatives": ["GLOBAL OPTIONS", "COMMAND OPTIONS", "FLAGS"],
+      "warning_if_missing": "Documenting command options helps users understand available functionality"
+    },
+    "BUGS": {
+      "classification": "optional",
+      "heading_level": 2,
+      "content_instruction": "Known issues, limitations, and bug reporting information"
+    },
+    "AUTHORS": {
+      "classification": "optional",
+      "heading_level": 2,
+      "content_instruction": "List of contributors and maintainers"
+    },
+    "COPYRIGHT": {
+      "classification": "optional",
+      "heading_level": 2,
+      "content_instruction": "Copyright statement and license information"
+    },
+    "HISTORY": {
+      "classification": "optional",
+      "heading_level": 2,
+      "content_instruction": "Historical information about command development"
+    },
+    "DEPRECATED": {
+      "classification": "discouraged",
+      "heading_level": 2,
+      "warning_if_missing": "Consider moving deprecated content to historical documentation or HISTORY section"
+    },
+    "OLD_SYNTAX": {
+      "classification": "discouraged",
+      "heading_level": 2,
+      "warning_if_missing": "Old syntax should be documented in HISTORY or removed entirely"
+    },
+    "INTERNAL_NOTES": {
+      "classification": "improper",
+      "heading_level": 2,
+      "error_message": "Internal notes must not appear in published manpages - move to developer documentation"
+    },
+    "TODO": {
+      "classification": "improper",
+      "heading_level": 2,
+      "error_message": "TODO sections are for development only - remove before publication"
+    },
+    "DRAFT": {
+      "classification": "improper",
+      "heading_level": 2,
+      "error_message": "DRAFT markers must be removed before publication"
+    }
+  },
+  "x-markitect-content-control": {
+    "synopsis": {
+      "required_patterns": [
+        "\\*\\*[a-z][a-z0-9-]*\\*\\*",
+        "\\[.*\\]"
+      ],
+      "discouraged_patterns": [
+        "TODO",
+        "FIXME",
+        "TBD"
+      ],
+      "content_quality": {
+        "min_words": 5,
+        "max_words": 150,
+        "readability_target": "technical"
+      },
+      "content_instructions": [
+        "Show command name in bold (e.g., **command**)",
+        "Use brackets [] for optional arguments",
+        "Use italic *ARG* for required arguments",
+        "Keep synopsis concise (1-5 lines maximum)",
+        "Use ellipsis ... to indicate repeatable arguments"
+      ]
+    },
+    "description": {
+      "discouraged_patterns": [
+        "TODO",
+        "FIXME",
+        "\\bWIP\\b",
+        "\\bXXX\\b"
+      ],
+      "forbidden_patterns": [
+        "password\\s*=\\s*[\"'].*[\"']",
+        "api[_-]?key\\s*=\\s*[\"'].*[\"']",
+        "secret\\s*=\\s*[\"'].*[\"']"
+      ],
+      "content_quality": {
+        "min_words": 50,
+        "max_words": 1000,
+        "readability_target": "technical",
+        "min_sentences": 3
+      },
+      "content_instructions": [
+        "Start with what the command does",
+        "Explain why users would use it",
+        "Describe main functionality and features",
+        "Mention any prerequisites or requirements",
+        "Keep technical but accessible"
+      ],
+      "link_validation": {
+        "check_internal": true,
+        "check_external": false,
+        "allow_fragments": true
+      }
+    },
+    "examples": {
+      "required_patterns": [
+        "```",
+        "#"
+      ],
+      "content_quality": {
+        "min_words": 100,
+        "max_words": 2000,
+        "readability_target": "general"
+      },
+      "content_instructions": [
+        "Use bash code blocks for command examples",
+        "Include comments explaining what each example does",
+        "Start with simple examples, progress to complex",
+        "Show actual output when helpful",
+        "Cover common use cases first"
+      ]
+    }
+  },
+  "type": "object",
+  "properties": {
+    "headings": {
+      "type": "object",
+      "description": "Document heading structure",
+      "properties": {
+        "level_1": {
+          "type": "array",
+          "description": "Title heading in format: command(section) - description",
+          "items": {
+            "type": "object",
+            "properties": {
+              "content": {
+                "type": "string",
+                "pattern": "^[a-z0-9-]+\\([0-9]\\) - .+"
+              }
+            }
+          },
+          "minItems": 1,
+          "maxItems": 1
+        },
+        "level_2": {
+          "type": "array",
+          "description": "Main section headings",
+          "minItems": 3,
+          "maxItems": 30
+        },
+        "level_3": {
+          "type": "array",
+          "description": "Subsection headings",
+          "minItems": 0,
+          "maxItems": 50
+        }
+      },
+      "required": ["level_1", "level_2"]
+    },
+    "paragraphs": {
+      "type": "array",
+      "description": "Text paragraphs",
+      "minItems": 10,
+      "maxItems": 500
+    },
+    "code_blocks": {
+      "type": "array",
+      "description": "Code examples",
+      "minItems": 1,
+      "maxItems": 50
+    },
+    "lists": {
+      "type": "array",
+      "description": "Lists for options and structured information",
+      "minItems": 0,
+      "maxItems": 100
+    },
+    "emphasis": {
+      "type": "array",
+      "description": "Bold and italic text for commands and arguments",
+      "minItems": 20,
+      "maxItems": 500
+    }
+  },
+  "required": ["headings", "paragraphs", "code_blocks", "emphasis"]
+}

examples/manpages/markdown-manpage-schema.json

@@ -0,0 +1,246 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "object",
+  "title": "Markdown Manpage Schema",
+  "description": "JSON schema defining the structure of Unix-style manual pages written in Markdown. Compatible with man(1) section format and conventions.",
+  "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",
+      "description": "Document heading structure following Unix manpage conventions",
+      "properties": {
+        "level_1": {
+          "type": "array",
+          "description": "Title heading: command(section) - brief description",
+          "items": {
+            "type": "object",
+            "properties": {
+              "content": {
+                "type": "string",
+                "pattern": "^[a-z0-9-]+\\([0-9]\\) - .+",
+                "description": "Must follow format: command(section) - description"
+              },
+              "level": {
+                "type": "integer",
+                "const": 1
+              }
+            },
+            "required": ["content", "level"]
+          },
+          "minItems": 1,
+          "maxItems": 1
+        },
+        "level_2": {
+          "type": "array",
+          "description": "Main section headings (SYNOPSIS, DESCRIPTION, etc.)",
+          "items": {
+            "type": "object",
+            "properties": {
+              "content": {
+                "type": "string",
+                "description": "Section name in UPPERCASE"
+              },
+              "level": {
+                "type": "integer",
+                "const": 2
+              }
+            },
+            "required": ["content", "level"]
+          },
+          "minItems": 3,
+          "maxItems": 30
+        },
+        "level_3": {
+          "type": "array",
+          "description": "Subsection headings (optional, for grouping commands or options)",
+          "items": {
+            "type": "object",
+            "properties": {
+              "content": {
+                "type": "string"
+              },
+              "level": {
+                "type": "integer",
+                "const": 3
+              }
+            },
+            "required": ["content", "level"]
+          },
+          "minItems": 0,
+          "maxItems": 50
+        }
+      },
+      "required": ["level_1", "level_2"]
+    },
+    "paragraphs": {
+      "type": "array",
+      "description": "Text paragraphs containing descriptions and explanations",
+      "minItems": 5,
+      "maxItems": 500
+    },
+    "lists": {
+      "type": "array",
+      "description": "Lists for options, examples, or structured information",
+      "minItems": 0,
+      "maxItems": 100
+    },
+    "code_blocks": {
+      "type": "array",
+      "description": "Code examples and command demonstrations",
+      "minItems": 1,
+      "maxItems": 50
+    },
+    "emphasis": {
+      "type": "array",
+      "description": "Bold and italic emphasis for commands, options, and arguments",
+      "minItems": 10,
+      "maxItems": 500
+    }
+  },
+  "required": ["headings", "paragraphs", "code_blocks", "emphasis"]
+}

examples/manpages/markdown-schema-validation.1.md

@@ -0,0 +1,901 @@
+# markdown-schema-validation(7) - Structured Document Validation with JSON Schema
+
+## SYNOPSIS
+
+**markitect schema-generate** *SOURCE_FILE* [**--output** *SCHEMA_FILE*]
+
+**markitect schema-ingest** *SCHEMA_FILE*
+
+**markitect validate** *DOCUMENT* *SCHEMA*
+
+**markitect generate-stub** *SCHEMA* [**--output** *FILE*]
+
+## DESCRIPTION
+
+Markdown Schema Validation is MarkiTect's system for enforcing structural consistency in markdown documents. Unlike traditional markdown linters that check syntax, schema validation ensures documents conform to predefined structural patterns by validating their Abstract Syntax Tree (AST) representation against JSON Schema definitions.
+
+This approach enables content management workflows where document structure is as important as content, making it ideal for technical documentation, business documents, and any scenario requiring consistent document templates.
+
+### How Schema Validation Works
+
+MarkiTect parses markdown files into an AST representation, then validates the AST structure against JSON schemas. The validation process checks:
+
+- **Heading hierarchy** - Required heading levels and counts
+- **Content elements** - Minimum and maximum paragraph counts
+- **Structural patterns** - Presence of lists, code blocks, tables
+- **Section organization** - Required and optional document sections
+
+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
+
+MarkiTect schemas are standard JSON Schema (draft-07) documents with custom extensions for markdown-specific validation.
+
+#### Standard Properties
+
+**properties.headings**
+: Defines heading structure by level (level_1, level_2, level_3)
+: Each level specifies minItems, maxItems, and content patterns
+
+**properties.paragraphs**
+: Array constraints for paragraph counts
+: Validates document length and content density
+
+**properties.code_blocks**
+: Array constraints for code examples
+: Ensures technical documentation includes examples
+
+**properties.lists**
+: Array constraints for list elements
+: Validates presence of structured information
+
+**properties.emphasis**
+: Array constraints for bold and italic text
+: Ensures appropriate use of emphasis
+
+#### MarkiTect Extensions
+
+MarkiTect extends JSON Schema with custom properties prefixed with **x-markitect-**:
+
+**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-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
+: Focuses on heading structure without content validation
+
+**x-markitect-heading-text-capture**
+: Boolean enabling exact heading text validation
+: Enforces specific section names
+
+## COMMANDS
+
+### Schema Generation
+
+**markitect schema-generate** *SOURCE_FILE*
+: Analyzes markdown file AST and generates JSON schema
+: Schema describes actual structure found in source document
+
+**--output** *SCHEMA_FILE*
+: Write schema to file instead of stdout
+: Default: outputs to terminal
+
+**--max-depth** *N*
+: Limit heading analysis to depth N
+: Useful for outline-focused schemas
+
+### Schema Management
+
+**markitect schema-ingest** *SCHEMA_FILE*
+: Store schema in MarkiTect database
+: Registers schema for reuse with validation commands
+
+**markitect schema-list**
+: Display all stored schemas
+: Shows schema names and metadata
+
+**markitect schema-get** *SCHEMA_NAME*
+: Retrieve stored schema
+: Outputs JSON schema to stdout
+
+**markitect schema-delete** *SCHEMA_NAME*
+: Remove schema from database
+: Permanently deletes schema definition
+
+### Document Validation
+
+**markitect validate** *DOCUMENT* *SCHEMA*
+: Validate markdown document against schema
+: Returns exit code 0 for valid, 4 for invalid
+
+**--detailed-errors**
+: Show detailed validation error messages
+: Includes suggestions for fixing violations
+
+**--quiet**
+: Suppress output, exit code only
+: Useful for scripting and automation
+
+### Template Generation
+
+**markitect generate-stub** *SCHEMA*
+: Generate markdown template from schema
+: Creates document outline following schema structure
+
+**--output** *FILE*
+: Write template to file
+: Default: outputs to stdout
+
+## WORKFLOW
+
+### Schema-Driven Development Workflow
+
+The typical workflow for schema-based document management:
+
+**1. Generate Schema from Example**
+
+Create or identify an exemplar document with the desired structure, then generate its schema:
+
+```bash
+markitect schema-generate exemplar.md --output doc-schema.json
+```
+
+**2. Refine Schema**
+
+Edit the generated schema to adjust constraints:
+
+- Change minItems/maxItems for flexibility
+- Add required-sections extensions
+- Adjust heading patterns
+- Add content instructions
+
+**3. Store Schema**
+
+Register schema for reuse:
+
+```bash
+markitect schema-ingest doc-schema.json
+```
+
+**4. Generate Templates**
+
+Create document templates from schema:
+
+```bash
+markitect generate-stub doc-schema.json --output template.md
+```
+
+**5. Create Documents**
+
+Write new documents using template as starting point, or use existing documents.
+
+**6. Validate Documents**
+
+Ensure documents conform to schema:
+
+```bash
+markitect validate new-document.md doc-schema.json
+
+markitect validate new-document.md doc-schema.json --detailed-errors
+```
+
+**7. Iterate**
+
+Fix validation errors and re-validate until document passes.
+
+### Batch Validation Workflow
+
+For managing multiple documents:
+
+```bash
+for doc in docs/*.md; do
+    markitect validate "$doc" doc-schema.json --quiet || echo "Failed: $doc"
+done
+```
+
+## VALIDATION RULES
+
+### Heading Validation
+
+Schemas validate heading structure through the **headings** property:
+
+**level_1** headings must appear exactly once (document title)
+
+**level_2** headings represent major sections (minItems/maxItems set bounds)
+
+**level_3** headings provide subsections (often optional with minItems: 0)
+
+Heading content can be validated with **pattern** or **enum** constraints for exact section names.
+
+### Content Element Validation
+
+**Paragraphs** - Validates document has sufficient descriptive content
+
+**Code blocks** - Ensures technical documents include examples
+
+**Lists** - Validates structured information presence
+
+**Emphasis** - Checks for appropriate use of bold/italic formatting
+
+Constraints use **minItems** and **maxItems** to set acceptable ranges.
+
+### Metadata Validation
+
+The **metadata** property validates overall document characteristics:
+
+**total_elements** - Total AST node count
+
+**structure_types** - Array of AST node types present
+
+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
+
+**Missing Required Section**
+
+```
+Error: Required section 'SYNOPSIS' not found
+Suggestion: Add H2 heading '## SYNOPSIS' near document start
+```
+
+**Insufficient Content**
+
+```
+Error: Too few paragraphs (found 3, minimum 5 required)
+Suggestion: Add descriptive content to meet minimum paragraph count
+```
+
+**Heading Count Mismatch**
+
+```
+Error: Too many H2 headings (found 15, maximum 13 allowed)
+Suggestion: Combine related sections or adjust schema maxItems
+```
+
+**Structure Type Mismatch**
+
+```
+Error: Expected structure types not found: code_blocks
+Suggestion: Add code examples using fenced code blocks
+```
+
+### Using Detailed Error Mode
+
+Enable detailed errors for actionable feedback:
+
+```bash
+markitect validate document.md schema.json --detailed-errors
+```
+
+Output includes:
+- Specific constraint violations
+- Location information when available
+- Suggestions for fixes
+- Schema path to failing constraint
+
+## SCHEMA DESIGN
+
+### Best Practices
+
+**Start with Real Documents**
+
+Generate schemas from actual documents rather than writing from scratch. Real documents provide realistic constraints.
+
+**Use Ranges, Not Exact Counts**
+
+Allow flexibility with minItems/maxItems ranges:
+
+```json
+"paragraphs": {
+  "minItems": 10,
+  "maxItems": 100
+}
+```
+
+Avoid exact counts (**const**) unless structure is truly rigid.
+
+**Section Classification**
+
+Use the five-level classification system to define section requirements:
+
+```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**
+
+Use regex patterns for flexible heading validation:
+
+```json
+"pattern": "^[A-Z][A-Z ]+$"
+```
+
+Matches UPPERCASE section names while allowing variation.
+
+**Progressive Refinement**
+
+Start with loose constraints, tighten based on validation experience with real documents.
+
+### Anti-Patterns
+
+**Over-Specification**
+
+Avoid schemas that are too specific:
+
+```json
+"paragraphs": { "const": 47 }
+```
+
+This requires exactly 47 paragraphs, which is too rigid for most use cases.
+
+**Under-Specification**
+
+Avoid schemas that validate nothing:
+
+```json
+"paragraphs": { "minItems": 0 }
+```
+
+Provide meaningful constraints that ensure document quality.
+
+**Semantic Validation**
+
+Schemas validate structure, not content. Don't expect schemas to validate:
+
+- Correct grammar or spelling
+- Factual accuracy
+- Code correctness
+- Logical flow
+
+Use other tools for semantic validation.
+
+## INTEGRATION
+
+### CI/CD Integration
+
+Validate documentation in continuous integration:
+
+```bash
+markitect validate README.md readme-schema.json --quiet
+exit_code=$?
+
+if [ $exit_code -eq 0 ]; then
+    echo "Documentation valid"
+else
+    echo "Documentation validation failed"
+    markitect validate README.md readme-schema.json --detailed-errors
+    exit 1
+fi
+```
+
+### Git Hooks
+
+Pre-commit hook for automatic validation:
+
+```bash
+changed_docs=$(git diff --cached --name-only --diff-filter=ACM | grep '.md$')
+
+for doc in $changed_docs; do
+    schema="${doc%.md}-schema.json"
+    if [ -f "$schema" ]; then
+        markitect validate "$doc" "$schema" || exit 1
+    fi
+done
+```
+
+### Build Systems
+
+Makefile integration:
+
+```makefile
+.PHONY: validate-docs
+validate-docs:
+	@for doc in docs/*.md; do \
+		markitect validate "$$doc" doc-schema.json || exit 1; \
+	done
+
+.PHONY: build
+build: validate-docs
+	# Build process continues only if docs validate
+```
+
+## EXAMPLES
+
+### Generate Schema from Document
+
+```bash
+markitect schema-generate examples/invoice.md --output invoice-schema.json
+```
+
+### Store Schema for Reuse
+
+```bash
+markitect schema-ingest invoice-schema.json
+markitect schema-list
+```
+
+### Validate Single Document
+
+```bash
+markitect validate draft-invoice.md invoice-schema.json
+
+markitect validate draft-invoice.md invoice-schema.json --detailed-errors
+```
+
+### Batch Validation
+
+```bash
+for invoice in invoices/*.md; do
+    markitect validate "$invoice" invoice-schema.json --quiet
+    if [ $? -ne 0 ]; then
+        echo "Invalid: $invoice"
+        markitect validate "$invoice" invoice-schema.json --detailed-errors
+    fi
+done
+```
+
+### Template Generation
+
+```bash
+markitect generate-stub invoice-schema.json --output new-invoice-template.md
+
+cat new-invoice-template.md
+
+markitect validate new-invoice-template.md invoice-schema.json
+```
+
+### Schema Refinement Workflow
+
+```bash
+markitect schema-generate example.md --output v1-schema.json
+
+markitect validate test-doc.md v1-schema.json --detailed-errors
+
+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**
+: JSON schema files defining document structure
+: Standard JSON Schema draft-07 format with MarkiTect extensions
+
+**markitect.db**
+: Database storing ingested schemas
+: SQLite database in current directory or specified path
+
+**.markitect.yml**
+: Configuration file for default schemas
+: YAML format with schema paths and validation rules
+
+## EXIT STATUS
+
+**0**
+: Success - document is valid
+
+**1**
+: General error - file not found, invalid arguments
+
+**2**
+: Configuration error - invalid schema file
+
+**3**
+: Database error - schema storage/retrieval failed
+
+**4**
+: Validation error - document does not conform to schema
+
+## ENVIRONMENT
+
+**MARKITECT_DATABASE**
+: Path to database file for schema storage
+: Default: markitect.db in current directory
+
+**MARKITECT_SCHEMA_PATH**
+: Search path for schema files
+: Colon-separated list of directories
+
+**MARKITECT_VALIDATION_STRICT**
+: Enable strict validation mode
+: Any non-empty value enables strict mode
+
+## SEE ALSO
+
+**markitect**(1), **json-schema**(7), **markdown-it**(7)
+
+Related documentation:
+- JSON Schema Specification (https://json-schema.org/)
+- MarkiTect Schema Reference
+- AST Structure Documentation
+- Template System Guide
+
+## LIMITATIONS
+
+Schema validation has inherent limitations:
+
+**Structure Only**
+
+Schemas validate document structure, not content semantics. Cannot validate:
+- Factual correctness
+- Code functionality
+- Logical consistency
+- Language quality
+
+**AST-Based**
+
+Validation operates on parsed AST, not raw markdown. Some markdown formatting details may not be preserved or validated.
+
+**Performance**
+
+Large documents with complex schemas may have performance implications. AST caching mitigates this for repeated validations.
+
+**Schema Complexity**
+
+Very complex schemas can become difficult to maintain. Keep schemas as simple as possible while meeting requirements.
+
+## BUGS
+
+Report bugs at: https://github.com/markitect/markitect/issues
+
+Known issues:
+- Schema generation from very large documents may be slow
+- Some edge cases in heading pattern matching
+- Limited support for custom markdown extensions
+
+## AUTHORS
+
+MarkiTect development team
+
+Schema validation system designed for structured content management and documentation consistency.
+
+## COPYRIGHT
+
+Copyright (c) 2025 MarkiTect Project. Licensed under MIT License.
+
+## VERSION
+
+This manual documents schema validation in MarkiTect version 1.0 and later.

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.

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.

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.

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.

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
+    }
+  }
+}

gitea/__init__.py

@@ -1,33 +0,0 @@
-"""
-Gitea API facade - Clean interface for Gitea repository operations.
-
-This package provides a clean, well-structured interface to Gitea API operations,
-following the facade pattern to decouple application logic from specific API
-implementation details.
-
-Structure:
-- client: Main GiteaClient facade
-- models: Domain models (Issue, Milestone, Label, etc.)
-- config: Gitea-specific configuration
-- exceptions: Gitea-specific exceptions
-
-Usage:
-    from gitea import GiteaClient
-
-    client = GiteaClient()
-    issues = client.issues.list()
-    issue = client.issues.get(42)
-    client.issues.create("Bug fix", "Description")
-"""
-
-from .client import GiteaClient
-from .models import Issue, Milestone, Label, ProjectState, Priority
-from .config import GiteaConfig
-from .exceptions import GiteaError, GiteaAuthError, GiteaNotFoundError
-
-__all__ = [
-    'GiteaClient',
-    'Issue', 'Milestone', 'Label', 'ProjectState', 'Priority',
-    'GiteaConfig',
-    'GiteaError', 'GiteaAuthError', 'GiteaNotFoundError'
-]

gitea/api_client.py

@@ -1,241 +0,0 @@
-"""
-High-level API client that converts between API responses and domain models.
-"""
-
-from datetime import datetime
-from typing import List, Optional, Dict, Any
-
-from .http_client import GiteaHttpClient
-from .models import Issue, Milestone, Label, User, IssueCreateData, IssueUpdateData, MilestoneCreateData, LabelCreateData
-from .config import GiteaConfig
-from .exceptions import GiteaNotFoundError, GiteaError
-
-
-class GiteaApiClient:
-    """High-level API client with domain model conversion."""
-
-    def __init__(self, config: GiteaConfig):
-        self.config = config
-        self.http = GiteaHttpClient(config)
-
-    # Issue operations
-    def get_issue(self, issue_number: int) -> Issue:
-        """Get a specific issue by number."""
-        try:
-            url = f"{self.config.issues_api_url}/{issue_number}"
-            data = self.http.get(url)
-            return self._parse_issue(data)
-        except GiteaError as e:
-            if "not found" in str(e).lower():
-                raise GiteaNotFoundError(f"Issue #{issue_number} not found")
-            raise
-
-    def list_issues(self, state: str = "all", page: int = 1, per_page: int = 50) -> List[Issue]:
-        """List issues with optional filtering."""
-        params = {"page": str(page), "limit": str(per_page)}
-        if state != "all":
-            params["state"] = state
-
-        data = self.http.get(self.config.issues_api_url, params)
-
-        if not isinstance(data, list):
-            raise GiteaError("Invalid response format: expected list of issues")
-
-        return [self._parse_issue(issue_data) for issue_data in data]
-
-    def create_issue(self, issue_data: IssueCreateData) -> Issue:
-        """Create a new issue."""
-        payload = {
-            "title": issue_data.title,
-            "body": issue_data.body,
-        }
-
-        if issue_data.assignees:
-            payload["assignees"] = issue_data.assignees
-        if issue_data.milestone:
-            payload["milestone"] = issue_data.milestone
-        if issue_data.labels:
-            # Convert label names to label IDs
-            payload["labels"] = self._resolve_label_ids(issue_data.labels)
-
-        data = self.http.post(self.config.issues_api_url, payload)
-        return self._parse_issue(data)
-
-    def update_issue(self, issue_number: int, update_data: IssueUpdateData) -> Issue:
-        """Update an existing issue."""
-        payload = {}
-
-        if update_data.title is not None:
-            payload["title"] = update_data.title
-        if update_data.body is not None:
-            payload["body"] = update_data.body
-        if update_data.state is not None:
-            payload["state"] = update_data.state
-        if update_data.assignees is not None:
-            payload["assignees"] = update_data.assignees
-        if update_data.milestone is not None:
-            payload["milestone"] = update_data.milestone
-        if update_data.labels is not None:
-            payload["labels"] = update_data.labels
-
-        url = f"{self.config.issues_api_url}/{issue_number}"
-        data = self.http.patch(url, payload)
-        return self._parse_issue(data)
-
-    # Milestone operations
-    def list_milestones(self, state: str = "all") -> List[Milestone]:
-        """List repository milestones."""
-        params = {}
-        if state != "all":
-            params["state"] = state
-
-        data = self.http.get(self.config.milestones_api_url, params)
-
-        if not isinstance(data, list):
-            raise GiteaError("Invalid response format: expected list of milestones")
-
-        return [self._parse_milestone(milestone_data) for milestone_data in data]
-
-    def create_milestone(self, milestone_data: MilestoneCreateData) -> Milestone:
-        """Create a new milestone."""
-        payload = {
-            "title": milestone_data.title,
-            "description": milestone_data.description,
-        }
-
-        if milestone_data.due_on:
-            payload["due_on"] = milestone_data.due_on
-
-        data = self.http.post(self.config.milestones_api_url, payload)
-        return self._parse_milestone(data)
-
-    # Label operations
-    def list_labels(self) -> List[Label]:
-        """List repository labels."""
-        data = self.http.get(self.config.labels_api_url)
-
-        if not isinstance(data, list):
-            raise GiteaError("Invalid response format: expected list of labels")
-
-        return [self._parse_label(label_data) for label_data in data]
-
-    def create_label(self, label_data: LabelCreateData) -> Label:
-        """Create a new label."""
-        payload = {
-            "name": label_data.name,
-            "color": label_data.color,
-            "description": label_data.description,
-        }
-
-        data = self.http.post(self.config.labels_api_url, payload)
-        return self._parse_label(data)
-
-    # Parsing methods
-    def _parse_issue(self, data: Dict[str, Any]) -> Issue:
-        """Parse issue data from API response."""
-        try:
-            # Parse labels
-            labels = []
-            if data.get('labels'):
-                labels = [self._parse_label(label_data) for label_data in data['labels']]
-
-            # Parse assignee
-            assignee = None
-            if data.get('assignee'):
-                assignee = self._parse_user(data['assignee'])
-
-            # Parse milestone
-            milestone = None
-            if data.get('milestone'):
-                milestone = self._parse_milestone(data['milestone'])
-
-            # Check if this is an error response
-            if 'message' in data and 'url' in data and 'number' not in data and 'id' not in data:
-                raise GiteaError(f"API Error: {data.get('message', 'Unknown error')} (URL: {data.get('url', 'N/A')})")
-
-            # Handle both 'number' and 'id' fields (Gitea API might use either)
-            issue_number = data.get('number') or data.get('id')
-            if issue_number is None:
-                raise GiteaError(f"Issue response missing both 'number' and 'id' fields. Available fields: {list(data.keys())}")
-
-            return Issue(
-                number=issue_number,
-                title=data['title'],
-                body=data.get('body', ''),
-                state=data['state'],
-                created_at=self._parse_datetime(data['created_at']),
-                updated_at=self._parse_datetime(data['updated_at']),
-                html_url=data['html_url'],
-                assignee=assignee,
-                labels=labels,
-                milestone=milestone
-            )
-        except (KeyError, ValueError) as e:
-            raise GiteaError(f"Failed to parse issue data: {e}")
-
-    def _parse_milestone(self, data: Dict[str, Any]) -> Milestone:
-        """Parse milestone data from API response."""
-        return Milestone(
-            id=data['id'],
-            title=data['title'],
-            description=data.get('description', ''),
-            state=data['state'],
-            open_issues=data.get('open_issues', 0),
-            closed_issues=data.get('closed_issues', 0),
-            due_on=data.get('due_on'),
-            created_at=self._parse_datetime(data.get('created_at')) if data.get('created_at') else None,
-            updated_at=self._parse_datetime(data.get('updated_at')) if data.get('updated_at') else None
-        )
-
-    def _parse_label(self, data: Dict[str, Any]) -> Label:
-        """Parse label data from API response."""
-        return Label(
-            id=data['id'],
-            name=data['name'],
-            color=data['color'],
-            description=data.get('description', '')
-        )
-
-    def _parse_user(self, data: Dict[str, Any]) -> User:
-        """Parse user data from API response."""
-        return User(
-            id=data['id'],
-            login=data['login'],
-            full_name=data.get('full_name', ''),
-            email=data.get('email', ''),
-            avatar_url=data.get('avatar_url', '')
-        )
-
-    def _parse_datetime(self, date_str: str) -> datetime:
-        """Parse datetime from API response."""
-        # Remove Z and microseconds for consistent parsing
-        date_str = date_str.replace('Z', '').split('.')[0]
-        return datetime.strptime(date_str, '%Y-%m-%dT%H:%M:%S')
-
-    def _resolve_label_ids(self, label_names: List[str]) -> List[int]:
-        """Convert label names to label IDs for API calls."""
-        try:
-            # Get all labels for the repository
-            labels_data = self.http.get(self.config.labels_api_url)
-            if not isinstance(labels_data, list):
-                raise GiteaError("Invalid labels response format")
-
-            # Create name-to-ID mapping
-            label_map = {label_data['name']: label_data['id'] for label_data in labels_data}
-
-            # Resolve names to IDs
-            label_ids = []
-            for name in label_names:
-                if name in label_map:
-                    label_ids.append(label_map[name])
-                else:
-                    # If label doesn't exist, we could create it or skip it
-                    # For now, let's skip non-existent labels
-                    print(f"Warning: Label '{name}' not found, skipping")
-
-            return label_ids
-
-        except Exception as e:
-            # If label resolution fails, proceed without labels rather than failing entirely
-            print(f"Warning: Could not resolve labels: {e}")
-            return []

gitea/client.py

@@ -1,237 +0,0 @@
-"""
-Main Gitea client facade.
-
-This provides a clean, organized interface for all Gitea operations,
-following the facade pattern to hide complexity and provide a stable API.
-"""
-
-from typing import List, Optional, Dict, Any
-
-from .config import GiteaConfig
-from .api_client import GiteaApiClient
-from .models import Issue, Milestone, Label, IssueCreateData, IssueUpdateData, MilestoneCreateData, LabelCreateData, ProjectState, Priority
-
-
-class IssuesClient:
-    """Client for issue operations."""
-
-    def __init__(self, api_client: GiteaApiClient):
-        self._api = api_client
-
-    def get(self, issue_number: int) -> Issue:
-        """Get a specific issue by number."""
-        return self._api.get_issue(issue_number)
-
-    def list(self, state: str = "all", page: int = 1, per_page: int = 50) -> List[Issue]:
-        """List issues with optional filtering."""
-        return self._api.list_issues(state, page, per_page)
-
-    def list_open(self) -> List[Issue]:
-        """List only open issues."""
-        return self._api.list_issues("open")
-
-    def list_closed(self) -> List[Issue]:
-        """List only closed issues."""
-        return self._api.list_issues("closed")
-
-    def create(self, title: str, body: str = "", **kwargs) -> Issue:
-        """Create a new issue."""
-        issue_data = IssueCreateData(
-            title=title,
-            body=body,
-            assignees=kwargs.get('assignees', []),
-            milestone=kwargs.get('milestone'),
-            labels=kwargs.get('labels', [])
-        )
-        return self._api.create_issue(issue_data)
-
-    def update(self, issue_number: int, **kwargs) -> Issue:
-        """Update an existing issue."""
-        update_data = IssueUpdateData(
-            title=kwargs.get('title'),
-            body=kwargs.get('body'),
-            state=kwargs.get('state'),
-            assignees=kwargs.get('assignees'),
-            milestone=kwargs.get('milestone'),
-            labels=kwargs.get('labels')
-        )
-        return self._api.update_issue(issue_number, update_data)
-
-    def close(self, issue_number: int) -> Issue:
-        """Close an issue."""
-        return self.update(issue_number, state="closed")
-
-    def reopen(self, issue_number: int) -> Issue:
-        """Reopen an issue."""
-        return self.update(issue_number, state="open")
-
-    def add_labels(self, issue_number: int, labels: List[str]) -> Issue:
-        """Add labels to an issue."""
-        issue = self.get(issue_number)
-        existing_labels = [label.name for label in issue.labels]
-        new_labels = list(set(existing_labels + labels))
-        return self.update(issue_number, labels=new_labels)
-
-    def remove_labels(self, issue_number: int, labels: List[str]) -> Issue:
-        """Remove labels from an issue."""
-        issue = self.get(issue_number)
-        existing_labels = [label.name for label in issue.labels]
-        new_labels = [label for label in existing_labels if label not in labels]
-        return self.update(issue_number, labels=new_labels)
-
-    def set_priority(self, issue_number: int, priority: Priority) -> Issue:
-        """Set issue priority."""
-        issue = self.get(issue_number)
-        labels = [label.name for label in issue.labels if not label.name.startswith('priority:')]
-        labels.append(priority.value)
-        return self.update(issue_number, labels=labels)
-
-    def set_status(self, issue_number: int, status: ProjectState) -> Issue:
-        """Set issue status."""
-        issue = self.get(issue_number)
-        labels = [label.name for label in issue.labels if not label.name.startswith('status:')]
-        labels.append(status.value)
-        return self.update(issue_number, labels=labels)
-
-    def assign_to_milestone(self, issue_number: int, milestone_id: int) -> Issue:
-        """Assign issue to a milestone."""
-        return self.update(issue_number, milestone=milestone_id)
-
-    def remove_from_milestone(self, issue_number: int) -> Issue:
-        """Remove issue from milestone."""
-        return self.update(issue_number, milestone=None)
-
-    def set_labels(self, issue_number: int, labels: List[str]) -> Issue:
-        """Replace all labels on an issue."""
-        return self.update(issue_number, labels=labels)
-
-    def update_title(self, issue_number: int, title: str) -> Issue:
-        """Update only the title of an issue."""
-        return self.update(issue_number, title=title)
-
-    def update_body(self, issue_number: int, body: str) -> Issue:
-        """Update only the body of an issue."""
-        return self.update(issue_number, body=body)
-
-    def to_dict(self, issue: Issue) -> Dict[str, Any]:
-        """Convert Issue object to dictionary format for backward compatibility."""
-        return {
-            'number': issue.number,
-            'title': issue.title,
-            'body': issue.body,
-            'state': issue.state,
-            'html_url': issue.html_url,
-            'created_at': issue.created_at.isoformat(),
-            'updated_at': issue.updated_at.isoformat(),
-            'assignee': {'login': issue.assignee.login} if issue.assignee else None,
-            'labels': [{'name': label.name, 'color': label.color} for label in issue.labels],
-            'milestone': {
-                'id': issue.milestone.id,
-                'title': issue.milestone.title
-            } if issue.milestone else None
-        }
-
-
-class MilestonesClient:
-    """Client for milestone operations."""
-
-    def __init__(self, api_client: GiteaApiClient):
-        self._api = api_client
-
-    def list(self, state: str = "all") -> List[Milestone]:
-        """List milestones."""
-        return self._api.list_milestones(state)
-
-    def list_open(self) -> List[Milestone]:
-        """List open milestones."""
-        return self._api.list_milestones("open")
-
-    def list_closed(self) -> List[Milestone]:
-        """List closed milestones."""
-        return self._api.list_milestones("closed")
-
-    def create(self, title: str, description: str = "", due_on: str = None) -> Milestone:
-        """Create a new milestone."""
-        milestone_data = MilestoneCreateData(
-            title=title,
-            description=description,
-            due_on=due_on
-        )
-        return self._api.create_milestone(milestone_data)
-
-
-class LabelsClient:
-    """Client for label operations."""
-
-    def __init__(self, api_client: GiteaApiClient):
-        self._api = api_client
-
-    def list(self) -> List[Label]:
-        """List all labels."""
-        return self._api.list_labels()
-
-    def create(self, name: str, color: str, description: str = "") -> Label:
-        """Create a new label."""
-        label_data = LabelCreateData(
-            name=name,
-            color=color,
-            description=description
-        )
-        return self._api.create_label(label_data)
-
-    def ensure_project_labels(self) -> None:
-        """Ensure all standard project management labels exist."""
-        existing_labels = [label.name for label in self.list()]
-
-        # Define standard project labels
-        standard_labels = [
-            ("status:todo", "d73a4a", "Ready to work on"),
-            ("status:active", "0075ca", "Currently being worked on"),
-            ("status:review", "fbca04", "Ready for review"),
-            ("status:done", "0e8a16", "Completed work"),
-            ("status:blocked", "b60205", "Blocked by dependencies"),
-            ("priority:low", "c5def5", "Low priority"),
-            ("priority:medium", "a2eeef", "Medium priority"),
-            ("priority:high", "fef2c0", "High priority"),
-            ("priority:critical", "d93f0b", "Critical priority"),
-        ]
-
-        for name, color, description in standard_labels:
-            if name not in existing_labels:
-                self.create(name, color, description)
-
-
-class GiteaClient:
-    """Main Gitea client facade."""
-
-    def __init__(self, config: Optional[GiteaConfig] = None):
-        """Initialize Gitea client.
-
-        Args:
-            config: GiteaConfig instance. If None, auto-detects from git repository.
-        """
-        if config is None:
-            try:
-                config = GiteaConfig.from_git_repository()
-            except Exception:
-                # Fallback to environment-based config if git detection fails
-                config = GiteaConfig.from_environment()
-            config.validate()
-
-        self.config = config
-        self._api = GiteaApiClient(config)
-
-        # Initialize sub-clients
-        self.issues = IssuesClient(self._api)
-        self.milestones = MilestonesClient(self._api)
-        self.labels = LabelsClient(self._api)
-
-    @classmethod
-    def from_tddai_config(cls, tddai_config) -> 'GiteaClient':
-        """Create client from legacy TddaiConfig for backwards compatibility."""
-        gitea_config = GiteaConfig.from_tddai_config(tddai_config)
-        return cls(gitea_config)
-
-    def setup_project_management(self) -> None:
-        """Setup standard project management labels and structure."""
-        self.labels.ensure_project_labels()

gitea/exceptions.py

@@ -1,31 +0,0 @@
-"""
-Gitea-specific exceptions.
-"""
-
-
-class GiteaError(Exception):
-    """Base exception for Gitea API operations."""
-    pass
-
-
-class GiteaAuthError(GiteaError):
-    """Raised when authentication fails or token is missing."""
-    pass
-
-
-class GiteaNotFoundError(GiteaError):
-    """Raised when requested resource is not found."""
-    pass
-
-
-class GiteaApiError(GiteaError):
-    """Raised when API returns an error response."""
-
-    def __init__(self, message: str, status_code: int = None):
-        super().__init__(message)
-        self.status_code = status_code
-
-
-class GiteaConfigError(GiteaError):
-    """Raised when Gitea configuration is invalid or missing."""
-    pass

gitea/http_client.py

@@ -1,98 +0,0 @@
-"""
-Low-level HTTP client for Gitea API operations.
-
-This module handles the actual HTTP requests to Gitea API using subprocess + curl
-for maximum compatibility and minimal dependencies.
-"""
-
-import json
-import subprocess
-from subprocess import PIPE
-from typing import Dict, Any, Optional, List
-
-from .exceptions import GiteaError, GiteaApiError, GiteaAuthError
-from .config import GiteaConfig
-
-
-class GiteaHttpClient:
-    """Low-level HTTP client for Gitea API."""
-
-    def __init__(self, config: GiteaConfig):
-        self.config = config
-
-    def get(self, url: str, params: Optional[Dict[str, str]] = None) -> Dict[str, Any]:
-        """Make GET request to Gitea API."""
-        if params:
-            param_string = '&'.join(f"{k}={v}" for k, v in params.items())
-            url = f"{url}?{param_string}"
-
-        return self._make_request('GET', url)
-
-    def post(self, url: str, data: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
-        """Make POST request to Gitea API."""
-        self._require_auth()
-        return self._make_request('POST', url, data)
-
-    def patch(self, url: str, data: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
-        """Make PATCH request to Gitea API."""
-        self._require_auth()
-        return self._make_request('PATCH', url, data)
-
-    def delete(self, url: str) -> Dict[str, Any]:
-        """Make DELETE request to Gitea API."""
-        self._require_auth()
-        return self._make_request('DELETE', url)
-
-    def _make_request(self, method: str, url: str, data: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
-        """Make HTTP request using curl."""
-        cmd = ['curl', '-s', '-X', method]
-
-        # Add authentication if available
-        if self.config.auth_token:
-            cmd.extend(['-H', f'Authorization: token {self.config.auth_token}'])
-
-        # Add content type for requests with data
-        if data is not None:
-            cmd.extend(['-H', 'Content-Type: application/json'])
-            cmd.extend(['-d', json.dumps(data)])
-
-        cmd.append(url)
-
-        try:
-            result = subprocess.run(
-                cmd,
-                stdout=PIPE,
-                stderr=PIPE,
-                universal_newlines=True,
-                check=True
-            )
-
-            if result.returncode != 0:
-                raise GiteaApiError(f"HTTP request failed: {result.stderr}")
-
-            # Handle empty responses
-            if not result.stdout.strip():
-                return {}
-
-            response_data = json.loads(result.stdout)
-
-            # Check for API error responses
-            if isinstance(response_data, dict):
-                if 'message' in response_data:
-                    # This could be an error or just a response with a message field
-                    # We need to distinguish based on context or HTTP status
-                    if any(error_word in response_data['message'].lower()
-                           for error_word in ['error', 'not found', 'forbidden', 'unauthorized']):
-                        raise GiteaApiError(response_data['message'])
-
-            return response_data
-
-        except subprocess.CalledProcessError as e:
-            raise GiteaApiError(f"HTTP request failed: {e.stderr}")
-        except json.JSONDecodeError as e:
-            raise GiteaError(f"Failed to parse API response: {e}")
-
-    def _require_auth(self):
-        """Ensure authentication token is available."""
-        if not self.config.auth_token:
-            raise GiteaAuthError("Authentication token required for this operation")

gitea/models.py

@@ -1,151 +0,0 @@
-"""
-Gitea domain models.
-
-These models represent the core entities in Gitea and provide a clean interface
-independent of the underlying API representation.
-"""
-
-from dataclasses import dataclass
-from datetime import datetime
-from enum import Enum
-from typing import List, Optional, Dict, Any
-
-
-class ProjectState(Enum):
-    """Standard project states using labels."""
-    TODO = "status:todo"
-    ACTIVE = "status:active"
-    REVIEW = "status:review"
-    DONE = "status:done"
-    BLOCKED = "status:blocked"
-
-
-class Priority(Enum):
-    """Priority levels using labels."""
-    LOW = "priority:low"
-    MEDIUM = "priority:medium"
-    HIGH = "priority:high"
-    CRITICAL = "priority:critical"
-
-
-@dataclass
-class Label:
-    """Represents a Gitea issue label."""
-    id: int
-    name: str
-    color: str
-    description: str = ""
-
-
-@dataclass
-class User:
-    """Represents a Gitea user."""
-    id: int
-    login: str
-    full_name: str = ""
-    email: str = ""
-    avatar_url: str = ""
-
-
-@dataclass
-class Milestone:
-    """Represents a Gitea milestone (used as projects)."""
-    id: int
-    title: str
-    description: str
-    state: str  # 'open' or 'closed'
-    open_issues: int
-    closed_issues: int
-    due_on: Optional[str] = None
-    created_at: Optional[datetime] = None
-    updated_at: Optional[datetime] = None
-
-
-@dataclass
-class Issue:
-    """Represents a Gitea issue."""
-    number: int
-    title: str
-    body: str
-    state: str  # 'open' or 'closed'
-    created_at: datetime
-    updated_at: datetime
-    html_url: str
-    assignee: Optional[User] = None
-    labels: List[Label] = None
-    milestone: Optional[Milestone] = None
-
-    def __post_init__(self):
-        if self.labels is None:
-            self.labels = []
-
-    @property
-    def priority(self) -> Optional[str]:
-        """Get issue priority from labels."""
-        for label in self.labels:
-            if label.name.startswith('priority:'):
-                return label.name.replace('priority:', '')
-        return None
-
-    @property
-    def status(self) -> Optional[str]:
-        """Get issue status from labels."""
-        for label in self.labels:
-            if label.name.startswith('status:'):
-                return label.name.replace('status:', '')
-        return None
-
-    def has_label(self, label_name: str) -> bool:
-        """Check if issue has a specific label."""
-        return any(label.name == label_name for label in self.labels)
-
-    def has_priority(self, priority: Priority) -> bool:
-        """Check if issue has a specific priority."""
-        return self.has_label(priority.value)
-
-    def has_status(self, status: ProjectState) -> bool:
-        """Check if issue has a specific status."""
-        return self.has_label(status.value)
-
-
-@dataclass
-class IssueCreateData:
-    """Data for creating a new issue."""
-    title: str
-    body: str = ""
-    assignees: List[str] = None
-    milestone: Optional[int] = None
-    labels: List[str] = None
-
-    def __post_init__(self):
-        if self.assignees is None:
-            self.assignees = []
-        if self.labels is None:
-            self.labels = []
-
-
-@dataclass
-class IssueUpdateData:
-    """Data for updating an existing issue."""
-    title: Optional[str] = None
-    body: Optional[str] = None
-    state: Optional[str] = None
-    assignees: Optional[List[str]] = None
-    milestone: Optional[int] = None
-    labels: Optional[List[str]] = None
-
-
-@dataclass
-class MilestoneCreateData:
-    """Data for creating a new milestone."""
-    title: str
-    description: str = ""
-    due_on: Optional[str] = None
-
-
-@dataclass
-class LabelCreateData:
-    """Data for creating a new label."""
-    name: str
-    color: str
-    description: str = ""