Add capability registry scaffold (REUSE-WP-0014-T05 B03)

Updated by fix-consistency on 2026-05-03:
  - update .custodian-brief.md for markitect-project

.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`

.claude/rules/agents.md

@@ -0,0 +1,20 @@
+## Kaizen Agents
+
+Specialized agent personas available on demand via the state-hub MCP.
+
+**Discover:** `list_kaizen_agents()` — returns all agents with name, description, category
+**Load:** `get_kaizen_agent("tdd-workflow")` — returns full instructions; read and follow them
+
+Common agents:
+
+| Agent | Category | When to use |
+|-------|----------|-------------|
+| `tdd-workflow` | testing | Step-by-step TDD8 workflow for any feature |
+| `code-refactoring` | quality | Code quality analysis and safe refactoring |
+| `test-maintenance` | testing | Diagnose and fix failing tests |
+| `requirements-engineering` | process | Prevent interface/mock mismatches upfront |
+| `keepaTodofile` | process | Maintain TODO.md during work |
+| `project-management` | process | Track status, determine next steps |
+| `datamodel-optimization` | quality | Optimize dataclasses and data structures |
+
+All 17 agents: call `list_kaizen_agents()` for the full list.

.claude/rules/architecture.md

@@ -0,0 +1,8 @@
+## Architecture
+
+<!-- TODO: Describe the key design decisions and component structure.
+     Key modules, data flows, external integrations, state machines, etc. -->
+
+## Quick Reference
+
+`~/state-hub/mcp_server/TOOLS.md` — MCP tool reference

.claude/rules/first-session.md

@@ -0,0 +1,38 @@
+## First Session Protocol
+
+Triggered when `get_domain_summary("markitect")` shows **no workstreams**.
+The project is registered but work has not yet been structured.
+
+**Step 1 — Read, don't write**
+- `~/the-custodian/canon/projects/markitect/project_charter_v0.1.md` — purpose, scope
+- `~/the-custodian/canon/projects/markitect/roadmap_v0.1.md` — planned phases
+- Scan repo root: README, directory structure, existing code or docs
+
+**Step 2 — Survey in-progress work**
+Look for TODOs, open branches, half-finished files. Note done vs. started but incomplete.
+
+**Step 3 — Propose workstreams to Bernd**
+Propose 1–3 workstreams — each a coherent strand, weeks to months, anchored to a
+roadmap phase. **Wait for approval before creating.**
+
+**Step 4 — Create workplan file first, then DB record (ADR-001)**
+```
+workplans/markitect-project-WP-NNNN-<slug>.md   ← write this first
+```
+Then register in the hub:
+```
+create_workstream(topic_id="5571d954-0d30-4950-980d-7bcaaad8e3e2", title="...", owner="...", description="...")
+create_task(workstream_id="<id>", title="...", priority="high|medium|low")
+```
+
+**Step 5 — Record the setup**
+```
+add_progress_event(
+    summary="First session: structured markitect into N workstreams, M tasks",
+    event_type="milestone",
+    topic_id="5571d954-0d30-4950-980d-7bcaaad8e3e2",
+    detail={"workstreams": [...], "tasks_created": M}
+)
+```
+
+<!-- Delete or archive this file once past first session -->

.claude/rules/repo-boundary.md

@@ -0,0 +1,8 @@
+## Repo boundary
+
+This repo owns **markitect-main** only. It does not own:
+
+<!-- TODO: List what belongs in adjacent repos, e.g.:
+- SSH key management → railiance-infra/
+- State hub code     → state-hub/
+-->

.claude/rules/repo-identity.md

@@ -0,0 +1,5 @@
+**Purpose:** Knowledge artifact management system. Handles structured content creation, versioning, and publication workflows for the markitect domain.
+
+**Domain:** markitect
+**Repo slug:** markitect-project
+**Topic ID:** 5571d954-0d30-4950-980d-7bcaaad8e3e2

.claude/rules/session-protocol.md

@@ -0,0 +1,84 @@
+## Session Protocol
+
+State Hub: http://127.0.0.1:8000
+
+**Step 1 — Orient**
+
+Read the offline-safe brief first — it works without a live hub connection:
+```bash
+cat .custodian-brief.md
+```
+Then call the MCP tool for richer cross-domain context when MCP tools are exposed:
+```
+get_domain_summary("markitect")
+```
+If MCP tools are unavailable in the current agent session, use the REST API:
+```bash
+curl -s "http://127.0.0.1:8000/state/summary" | python3 -m json.tool
+```
+If the hub is offline: `cd ~/state-hub && make api`
+
+**Step 2 — Check inbox**
+With MCP tools:
+```
+get_messages(to_agent="markitect-project", unread_only=True)
+```
+Mark read with `mark_message_read(message_id)`. Reply or act on coordination
+requests before proceeding.
+
+Without MCP tools:
+```bash
+curl -s "http://127.0.0.1:8000/messages/?to_agent=markitect-project&unread_only=true" \
+  | python3 -m json.tool
+curl -s -X PATCH "http://127.0.0.1:8000/messages/<id>/read" \
+  -H "Content-Type: application/json" -d '{}'
+```
+
+**Step 3 — Scan workplans**
+```bash
+ls workplans/
+```
+For each file with `status: ready`, `active`, or `blocked`, note pending
+`todo`/`in_progress` tasks.
+
+**Step 4 — Present brief**
+
+1. **Active workstreams** for `markitect` — title, task counts, blocking decisions
+2. **Pending tasks** from `workplans/` + any `[repo:markitect-project]` hub tasks
+3. **Goal guidance** — if `goal_guidance` in summary:
+   - `needs_workplan`: surface as top action — *"Repo goal '{title}' has no workplan yet"*
+   - `alignment_warnings`: flag if active work is not aligned with current goal
+4. **Suggested next action** — highest-priority open item
+5. **SBOM status** — flag if `last_sbom_at` is unset for this repo
+
+If no workstreams: follow First Session Protocol (`first-session.md`).
+
+**During work:** `record_decision()` · `add_progress_event()` · `resolve_decision()`
+
+> State Hub is a *read model*. Bootstrap tools (`create_workstream`, `create_task`)
+> are First Session Protocol only. Work structure belongs in repo files (ADR-001).
+
+**Session close:**
+With MCP tools:
+```
+add_progress_event(summary="...", topic_id="5571d954-0d30-4950-980d-7bcaaad8e3e2", workstream_id="<uuid>")
+```
+Without MCP tools:
+```bash
+curl -s -X POST http://127.0.0.1:8000/progress/ \
+  -H "Content-Type: application/json" \
+  -d '{"topic_id":"5571d954-0d30-4950-980d-7bcaaad8e3e2","workstream_id":"<uuid>","event_type":"note","summary":"what changed","author":"codex"}'
+```
+If workplan files were modified, ensure the local copy is up to date first:
+```bash
+git -C <repo_path> pull --ff-only
+cd ~/state-hub && make fix-consistency REPO=markitect-project
+```
+For repos where implementation runs on a remote machine (e.g. CoulombCore),
+use the combined target which pulls before fixing:
+```bash
+cd ~/state-hub && make fix-consistency-remote REPO=markitect-project
+```
+**C-15** (DB task ahead of file) is normal in multi-machine workflows — writeback
+will sync the file to match DB.  **C-16** (repo behind remote) blocks all writes
+until you pull — intentional to prevent clobbering remote progress.

.claude/rules/stack-and-commands.md

@@ -0,0 +1,19 @@
+## Stack
+
+<!-- TODO: Fill in language, frameworks, and key dependencies -->
+- **Language:**
+- **Key deps:**
+
+## Dev Commands
+
+```bash
+# TODO: Fill in the standard commands for this repo
+
+# Install dependencies
+
+# Run tests
+
+# Lint / type check
+
+# Build / package (if applicable)
+```

.claude/rules/workplan-convention.md

@@ -0,0 +1,28 @@
+## Workplan Convention (ADR-001)
+
+File location: `workplans/markitect-project-WP-NNNN-<slug>.md`
+ID prefix: `MARKITECT-WP`
+
+Work items originate as files in this repo **before** being registered in the hub.
+
+Canonical workplan/workstream frontmatter statuses are:
+`proposed`, `ready`, `active`, `blocked`, `backlog`, `finished`, `archived`.
+Use `proposed` for a newly drafted plan, `ready` after review against current
+repo state, and `finished` when implementation is complete. `stalled` and
+`needs_review` are derived health labels, not stored statuses.
+
+Closed workplans may be moved to `workplans/archived/` with a completion-date
+prefix: `YYMMDD-markitect-project-WP-NNNN-<slug>.md`. The frontmatter id remains
+unchanged; the prefix is only for quick visual reference.
+
+Small opportunistic tasks discovered during another session use **Ad Hoc Tasks**:
+`workplans/ADHOC-YYYY-MM-DD.md`, workstream slug `adhoc-YYYY-MM-DD`, and task ids
+`ADHOC-YYYY-MM-DD-T01`, `T02`, etc. Use adhocs only for low-risk work completed
+directly. Promote anything requiring analysis, design, approval, dependencies, or
+multiple planned phases into a normal workplan.
+
+Ecosystem todos from other agents arrive as `[repo:markitect-project]` hub tasks —
+visible at session start. Pick one up by creating the workplan file, then registering
+the workstream.
+
+<!-- Ralph Loop rules and HEUREKA sequence: ~/.claude/CLAUDE.md — do not duplicate here -->

.clinerules

@@ -10,7 +10,7 @@ principles with strict separation of concerns.
 
 ## Directory Structure & Clean Architecture
 ```
-markitect_project/
+markitect-main/
 ├── domain/          # Business logic (innermost layer)
 ├── application/     # Use cases and workflows
 ├── infrastructure/ # External interfaces (database, file system)

.custodian-brief.md

@@ -0,0 +1,42 @@
+<!-- custodian-brief: generated by fix-consistency — do not edit manually -->
+# Custodian Brief — markitect-project
+
+**Domain:** markitect  
+**Last synced:** 2026-05-03 17:31 UTC  
+**State Hub:** http://127.0.0.1:8000 *(adjust if running on a remote machine)*
+
+## Active Workstreams
+
+### TestDrive-JSUI — npm Publication
+Progress: 0/9 done  |  workstream_id: `e203d487-01f1-494a-b14d-a436241a4c01`
+
+**Open tasks:**
+- · P.1 — Decide repository structure (monorepo vs standalone)  `81c03377`
+- · P.2 — Verify Markitect integration still works  `f518601b`
+- · P.3 — Resolve STANDALONE_PLAN.md status  `d700098c`
+- · P.4 — Pack and dry-run publish  `94dd2a30`
+- · P.5 — Create v1.0.0 release tag  `d7c2ce00`
+- · P.6 — Publish to npm and verify CDN  `8bcde75e`
+- · P.7 — Fresh install test in clean environment  `61d14b53`
+- … and 2 more open tasks
+
+### Infospace Tooling — Stage 3 Close-out
+Progress: 0/8 done  |  workstream_id: `830c888e-e1d4-43e6-8093-9b61e7578257`
+
+**Open tasks:**
+- · C.1 — Evaluate the 3 missing entities  `0fa8f461`
+- · C.2 — Run eval-summary and verify viability (6/6 PASS)  `ba7d992c`
+- · C.3 — Refresh metrics report from full 988-entity set  `84a59244`
+- · C.4 — Document advanced usage patterns  `0ef75ee5`
+- · C.5 — Add composition guide referencing supply-chain-vsm  `864977db`
+- · C.6 — Write performance notes  `414496b0`
+- · C.7 — S3.2: Complete clean per-chapter git history  `21c865c1`
+- … and 1 more open tasks
+
+---
+## MCP Orientation (when available)
+
+If the state-hub MCP server is reachable, call:
+`get_domain_summary("markitect")`
+This provides richer cross-domain context.
+If the MCP call fails, use this file as your orientation source.

.gitignore

@@ -78,6 +78,9 @@ Thumbs.db
 
 # MarkiTect database files (local development)
 markitect.db
+**/infospace.db
+assets/assets.db
+**/assets.db
 .markitect/
 
 # Issue workspace (temporary development files)
@@ -88,11 +91,17 @@ debug_*.py
 
 # Claude Code local settings (user-specific permissions)
 .claude/settings.local.json
+# Claude Code runtime session locks (per-session, not content)
+.claude/*.lock
 
 .aider*
 
+# API key files
+apikey-*.txt
+
 # TDDAI-specific ignores
 ISSUES.index
 
 # Test artifacts and temporary files
 tmp/
+markitect/_version.py

.gitmodules

@@ -1,10 +1,14 @@
 [submodule "wiki"]
 	path = wiki
-	url = http://92.205.130.254:32166/coulomb/markitect_project.wiki.git
+	url = http://92.205.130.254:32166/coulomb/markitect-main.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

AGENTS.md

@@ -0,0 +1,162 @@
+# markitect-main — Agent Instructions
+
+## Repo Identity
+
+**Purpose:** Knowledge artifact management system. Handles structured content creation, versioning, and publication workflows for the markitect domain.
+
+**Domain:** markitect
+**Repo slug:** markitect-project
+**Topic ID:** `5571d954-0d30-4950-980d-7bcaaad8e3e2`
+**Workplan prefix:** `MARKITECT-WP-`
+
+---
+
+## State Hub Integration
+
+The Custodian State Hub tracks work across all domains. Interact via HTTP REST —
+there is no MCP server for Codex agents.
+
+| Context | URL |
+|---------|-----|
+| Local workstation | `http://127.0.0.1:8000` |
+| Remote via tunnel | `http://127.0.0.1:18000` |
+
+### Orient at session start
+
+```bash
+# Offline brief — works without hub connection
+cat .custodian-brief.md
+
+# Active workstreams for this domain
+curl -s "http://127.0.0.1:8000/workstreams/?topic_id=5571d954-0d30-4950-980d-7bcaaad8e3e2&status=active" \
+  | python3 -m json.tool
+
+# Check inbox
+curl -s "http://127.0.0.1:8000/messages/?to_agent=markitect-project&unread_only=true" \
+  | python3 -m json.tool
+```
+
+Mark a message read:
+```bash
+curl -s -X PATCH "http://127.0.0.1:8000/messages/<id>/read" \
+  -H "Content-Type: application/json" -d '{}'
+```
+
+### Log progress (required at session close)
+
+```bash
+curl -s -X POST http://127.0.0.1:8000/progress/ \
+  -H "Content-Type: application/json" \
+  -d '{
+    "summary": "what was done",
+    "event_type": "note",
+    "author": "codex",
+    "workstream_id": "<uuid>",
+    "task_id": "<uuid>"
+  }'
+```
+
+Omit `workstream_id` / `task_id` when not applicable.
+
+### Update task status
+
+```bash
+curl -s -X PATCH "http://127.0.0.1:8000/tasks/<task_id>" \
+  -H "Content-Type: application/json" \
+  -d '{"status": "in_progress"}'
+# values: todo | in_progress | done | blocked
+```
+
+### Flag a task for human review
+
+```bash
+curl -s -X PATCH "http://127.0.0.1:8000/tasks/<task_id>" \
+  -H "Content-Type: application/json" \
+  -d '{"needs_human": true, "intervention_note": "reason"}'
+```
+
+---
+
+## Session Protocol
+
+**Start:**
+1. `cat .custodian-brief.md` — domain goal and open workstreams (offline-safe)
+2. Check inbox: `GET /messages/?to_agent=markitect-project&unread_only=true`; mark read
+3. Scan workplans: `ls workplans/` — note `status: ready`, `active`, or `blocked` files and open tasks
+4. Check blocked tasks: `GET /tasks/?needs_human=true`
+
+**During work:**
+- Update task statuses in workplan files as tasks progress
+- Record significant decisions via `POST /decisions/`
+
+**Close:**
+1. Update workplan file task statuses to reflect progress
+2. Log: `POST /progress/` with a summary of what changed
+3. Note for the custodian operator: after workplan file changes, run from
+   `~/state-hub`:
+   ```bash
+   make fix-consistency REPO=markitect-project
+   ```
+   This syncs task status from files into the hub DB.
+
+---
+
+## Workplan Convention (ADR-001)
+
+Work items originate as files in this repo — not in the hub. The hub is a
+read/cache/index layer that rebuilds from files.
+
+**File location:** `workplans/MARKITECT-WP-NNNN-<slug>.md`
+
+**Archived location:** finished workplans may move to
+`workplans/archived/YYMMDD-MARKITECT-WP-NNNN-<slug>.md`. The `YYMMDD` prefix is
+the completion/archive date; the frontmatter `id` does not change.
+
+**Ad Hoc Tasks:** small opportunistic fixes discovered during a session use
+`workplans/ADHOC-YYYY-MM-DD.md` with task ids `ADHOC-YYYY-MM-DD-T01`, etc. Use
+this only for low-risk work completed directly; create a normal workplan for
+anything needing analysis, design, approval, dependencies, or multiple phases.
+
+**Frontmatter:**
+
+```yaml
+---
+id: MARKITECT-WP-NNNN
+type: workplan
+title: "..."
+domain: markitect
+repo: markitect-project
+status: proposed | ready | active | blocked | backlog | finished | archived
+owner: codex
+topic_slug: ...
+created: "YYYY-MM-DD"
+updated: "YYYY-MM-DD"
+state_hub_workstream_id: "<uuid>"   # written by fix-consistency — do not edit
+---
+```
+
+Use `proposed` for a new draft, `ready` after review against current repo
+state, and `finished` after implementation. `stalled` and `needs_review` are
+derived health labels, not frontmatter statuses.
+
+**Task block format** (one per `##` section):
+
+```
+## Task Title
+
+` ` `task
+id: MARKITECT-WP-NNNN-T01
+status: todo | in_progress | done | blocked
+priority: high | medium | low
+state_hub_task_id: "<uuid>"         # written by fix-consistency — do not edit
+` ` `
+
+Task description text.
+```
+
+Status progression: `todo` → `in_progress` → `done` (or `blocked`)
+
+To create a new workplan:
+1. Write the file following the format above
+2. Notify the custodian operator to run `make fix-consistency REPO=markitect-project`
+   (or send a message to the hub agent via `POST /messages/`)

CHANGELOG.md

@@ -5,8 +5,186 @@ 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
+- **Complete JavaScript Architecture Refactoring**: Full TDD-driven modular architecture with SectionManager and DOMRenderer components
+- **Advanced Image Editor**: Rebuilt with full drag-n-drop functionality and staging workflow
+- **Modular Component System**: Extracted comprehensive JavaScript components for better maintainability
+- **Enhanced Edit Mode**: Improved robustness and user experience with better reset functionality
+- **Insert Mode Protection**: Implemented insert mode with heading protection and content display fixes
+- **Scroll Indicators**: Added scroll indicators with disabled state styling
+- **Asset Shipping**: Comprehensive asset shipping for md-render command
+
+### Fixed
+- **Reset Button Functionality**: Implemented fully functional reset buttons for text and image sections
+- **Image Rendering**: Fixed proper image rendering in modular architecture
+- **DOM Content Updates**: Resolved DOM content updates and reset functionality
+- **Section Click Functionality**: Enabled proper section click functionality for edit UI
+- **Modular Integration**: Fixed integration of modular JavaScript architecture into application
+- **Button Functionality**: Resolved accept, cancel, and reset button functionality issues
+- **Critical JavaScript Errors**: Fixed errors preventing content rendering
+
+### Changed
+- **Edit Mode Organization**: Continued efforts to reorganize edit mode for better robustness
+- **Example Directory Structure**: Reorganized examples directory with topic-based subdirectories
+- **UI Panel Structure**: Eliminated floating status panel above editor menu for cleaner interface
+
+### Maintenance
+- **TODO Cleanup**: Cleaned up completed theme system refactor tasks
+
 ## [0.6.0] - 2025-10-28
 
 ### Added
@@ -130,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

CLAUDE.md

@@ -0,0 +1,11 @@
+# markitect-main — Claude Code Instructions
+
+@SCOPE.md
+@.claude/rules/repo-identity.md
+@.claude/rules/session-protocol.md
+@.claude/rules/first-session.md
+@.claude/rules/workplan-convention.md
+@.claude/rules/stack-and-commands.md
+@.claude/rules/architecture.md
+@.claude/rules/repo-boundary.md
+@.claude/rules/agents.md

DEPENDENCIES.md

@@ -0,0 +1,552 @@
+# Dependencies
+
+This document catalogs all dependencies used in the markitect project, describing how each library and tool is utilized. This helps coordinate dependencies with sister projects like referitect and maintain consistency across the ecosystem.
+
+## Table of Contents
+
+- [Core Dependencies](#core-dependencies)
+- [Capability Dependencies](#capability-dependencies)
+- [Development Dependencies](#development-dependencies)
+- [JavaScript Dependencies](#javascript-dependencies)
+- [Dependency Criticality Matrix](#dependency-criticality-matrix)
+- [Coordination Guidelines for Sister Projects](#coordination-guidelines-for-sister-projects)
+
+---
+
+## Core Dependencies
+
+These dependencies are required for markitect's core functionality.
+
+### markdown-it-py
+**Version:** Latest
+**Criticality:** CRITICAL
+**Purpose:** Core markdown parsing engine
+
+**Usage:**
+- Converts markdown content to Abstract Syntax Trees (AST)
+- Enables table parsing with `.enable(['table'])`
+- Uses CommonMark parser with token conversion
+- Foundation for all markdown processing operations
+
+**Files:** `markitect/parser.py`
+
+**Why this matters:** This is the primary markdown parser. Sister projects should use the same parser for consistent AST structure and compatibility.
+
+---
+
+### PyYAML
+**Version:** Latest
+**Criticality:** CRITICAL
+**Purpose:** YAML configuration parsing and serialization
+
+**Usage:**
+- Parses YAML frontmatter from markdown documents
+- Loads configuration files for themes and workspaces
+- Supports YAML-based schema definitions
+- Safe loading of untrusted YAML data (`yaml.safe_load()`)
+- Configuration serialization and deserialization
+
+**Files:**
+- `markitect/cli.py`
+- `markitect/schema_loader.py`
+- `markitect/matter_frontmatter/parser.py`
+- `markitect/config_manager.py`
+- `markitect/production/configuration.py`
+- `markitect/serializer.py`
+- Multiple capability files
+
+**Why this matters:** YAML is the primary configuration format. Consistent YAML handling ensures config compatibility across projects.
+
+---
+
+### click
+**Version:** >=8.0.0
+**Criticality:** CRITICAL
+**Purpose:** Command-line interface framework
+
+**Usage:**
+- Primary CLI framework for all command-line commands
+- Command groups, options, and decorators for `markitect` CLI
+- Table output formatting (combined with tabulate)
+- Command organization and help system
+- Error handling and context management
+- Profile management, finance tracking, release management, issue tracking commands
+
+**Files:** 63 files including:
+- `markitect/cli.py` (main CLI)
+- `markitect/cli_utils.py`
+- `markitect/asset_commands.py`
+- `markitect/profile/commands.py`
+- `markitect/finance/cli.py`
+- `capabilities/release-management/src/release_management/cli/main.py`
+- `capabilities/kaizen-agentic/src/kaizen_agentic/cli.py`
+- Issue tracker CLI commands
+
+**Why this matters:** Click provides consistent CLI UX. Sister projects using Click will have familiar command patterns and help output.
+
+---
+
+### tabulate
+**Version:** >=0.9.0
+**Criticality:** HIGH
+**Purpose:** ASCII table formatting for CLI output
+
+**Usage:**
+- Formats database query results as ASCII tables
+- Provides multiple table formats: grid, simple, fancy
+- Used in CLI output for:
+  - Database command results
+  - Performance metrics display
+  - Status reports
+  - File listings
+  - Financial tracking output
+
+**Files:**
+- `markitect/cli.py`
+- `markitect/cli_utils.py`
+- `markitect/plugins/builtin/markdown_commands.py`
+- `markitect/finance/cli.py`
+- `markitect/finance/worktime_commands.py`
+
+**Why this matters:** Consistent table formatting across all CLI tools provides professional, readable output.
+
+---
+
+### jsonpath-ng
+**Version:** >=1.5.0
+**Criticality:** MEDIUM
+**Purpose:** JSONPath querying for AST navigation
+
+**Usage:**
+- XPath-like navigation through AST structures
+- Query parsing with `jsonpath-ng.parse()`
+- Fallback simple dot-notation implementation if import fails
+- Advanced query paradigm for structural queries
+- Supports filters, recursive descent, array wildcards
+
+**Files:**
+- `markitect/query_paradigms/paradigms/jsonpath_paradigm.py`
+- `markitect/ast_service.py`
+- `markitect/graphql/resolvers.py`
+
+**Why this matters:** Provides advanced AST querying. Optional but useful for complex document transformations.
+
+---
+
+### aiohttp
+**Version:** >=3.8.0
+**Criticality:** MEDIUM
+**Purpose:** Async HTTP client for API interactions
+
+**Usage:**
+- HTTP session management with connection pooling
+- Async/await pattern support for concurrent requests
+- TCP connection optimization (limit, per-host limits)
+- Timeout and keepalive configuration
+- Authentication header management for API calls
+- Gitea API integration
+- Health check mechanisms
+- Proper resource cleanup with async context managers
+
+**Files:**
+- `infrastructure/connection_manager.py`
+
+**Why this matters:** Enables performant async I/O for API operations. Critical for scalable network operations.
+
+---
+
+### toml
+**Version:** Latest
+**Criticality:** LOW-MEDIUM
+**Purpose:** TOML configuration format parsing
+
+**Usage:**
+- Parses TOML-formatted frontmatter in markdown files
+- Alternative to YAML for configuration syntax
+- Format detection: tries TOML if content has '=' and brackets
+- Graceful fallback to YAML if TOML parsing fails
+
+**Files:**
+- `markitect/matter_frontmatter/parser.py`
+- `capabilities/release-management/src/release_management/summary/generator.py`
+- `capabilities/release-management/src/release_management/utils/validation.py`
+- `capabilities/release-management/src/release_management/registries/factory.py`
+
+**Why this matters:** Provides TOML support for users preferring TOML over YAML. Optional with fallback mechanisms.
+
+---
+
+### setuptools-scm
+**Version:** >=8.0.0
+**Criticality:** CRITICAL
+**Purpose:** Git-based version management
+
+**Usage:**
+- Automatic version derivation from git tags
+- Generates `_version.py` file during build
+- Supports semantic versioning (python-simplified-semver scheme)
+- Git tag format: `v*` (matches v0.11.0, v1.0.0, etc.)
+- No local version suffix in scheme
+- Used by release-management for version operations
+
+**Files:**
+- `markitect/__version__.py`
+- `capabilities/release-management/src/release_management/utils/version.py`
+- `capabilities/release-management/src/release_management/cli/main.py`
+- `capabilities/release-management/src/release_management/utils/validation.py`
+- `capabilities/release-management/src/release_management/core/builder.py`
+
+**Why this matters:** Single source of truth for versioning. Critical for coordinated releases across sister projects.
+
+---
+
+## Capability Dependencies
+
+Dependencies specific to optional capabilities. These extend markitect's functionality.
+
+### markitect-utils
+**Location:** `capabilities/markitect-utils`
+**Dependencies:** None (intentionally dependency-free)
+**Purpose:** Utility functions capability for testing ComposableRepositoryParadigm
+
+---
+
+### markitect-content
+**Location:** `capabilities/markitect-content`
+**Dependencies:**
+- `click>=8.0.0` - CLI commands for content parsing and statistics
+
+**Purpose:** Content parsing and statistics capability
+
+---
+
+### kaizen-agentic
+**Location:** `capabilities/kaizen-agentic`
+**Dependencies:**
+- `pyyaml>=6.0` - Agent configuration files
+- `click>=8.0.0` - CLI interface
+- `pydantic>=2.0.0` - Data validation for agent configs
+
+**Purpose:** AI agent development framework with continuous improvement patterns
+
+**Key Usage:**
+- Agent configuration via YAML
+- CLI for agent management (`kaizen-agentic` command)
+- Pydantic models for validated agent configurations
+
+---
+
+### release-management
+**Location:** `capabilities/release-management`
+**Dependencies:**
+- `click>=8.0.0` - CLI commands
+- `requests>=2.25.0` - Gitea package registry API
+- `setuptools-scm>=8.0.0` - Version management
+- `build>=0.8.0` - Python package building
+- `packaging>=21.0` - Version parsing and comparison
+- `pyyaml>=6.0` - Configuration files
+- `pydantic>=2.0.0` - Configuration validation
+
+**Purpose:** Comprehensive release management for Python projects
+
+**Key Usage:**
+- Package building (wheel, sdist)
+- Git tag creation and management
+- Gitea package registry publishing
+- Version validation and semantic versioning
+- Release configuration via YAML
+
+**Entry Points:** `release`, `release-manager` commands
+
+---
+
+### testdrive-jsui
+**Location:** `capabilities/testdrive-jsui`
+**Dependencies:**
+- `pytest>=7.0.0` - Test framework
+- `pytest-xvfb>=3.0.0` - Headless browser testing
+- `selenium>=4.0.0` - Browser automation
+- `pathlib2>=2.3.0` (Python <3.4) - Path handling
+
+**Purpose:** JavaScript UI testing framework capability
+
+**Key Usage:**
+- Browser-based testing infrastructure
+- Headless browser execution
+- Selenium WebDriver integration
+- JavaScript test execution from Python
+
+**Note:** Primarily a JavaScript library with Python adapter. See JavaScript Dependencies section.
+
+---
+
+### issue-facade (universal-issue-tracker)
+**Location:** `_issue-tracking/issue-facade`
+**Dependencies:**
+- `click>=8.0.0` - CLI framework
+- `requests>=2.25.0` - Remote backend API calls (Gitea, GitHub)
+- `python-dateutil>=2.8.0` - Date/time parsing
+
+**Purpose:** Backend-agnostic issue tracking with plugin architecture
+
+**Key Usage:**
+- Unified CLI for multiple issue backends (Gitea, GitHub, local SQLite)
+- REST API integration
+- Date parsing for issue timestamps
+- Synchronization between local and remote backends
+
+**Entry Points:** `issue`, `issue-tracker` commands
+
+---
+
+## Development Dependencies
+
+These dependencies are only required during development and testing.
+
+### Testing Frameworks
+- `pytest>=6.0.0` - Primary test framework
+- `pytest-cov>=2.0` - Coverage reporting
+- `pytest-mock>=3.0` - Mocking utilities
+- `pytest-randomly>=3.10.0` - Randomized test execution (kaizen-agentic)
+- `pytest-asyncio>=0.21.0` - Async test support (testdrive-jsui)
+- `pytest-timeout>=2.1.0` - Test timeout handling (testdrive-jsui)
+
+### Code Quality
+- `black>=22.0.0` - Code formatting (88 char line length)
+- `isort>=5.0` - Import sorting
+- `flake8>=5.0.0` - Linting (100 char max line length)
+- `mypy>=1.0.0` - Static type checking
+- `pre-commit>=2.0` - Git hooks
+
+### Build Tools
+- `setuptools>=64` - Python package building
+- `wheel` - Wheel package format
+- `build>=0.8.0` - PEP 517 build frontend
+
+### Documentation
+- `sphinx>=4.0` - Documentation generation (issue-facade)
+- `sphinx-rtd-theme>=1.0` - Read the Docs theme
+- `sphinx-click>=3.0` - Click command documentation
+
+---
+
+## JavaScript Dependencies
+
+These dependencies support browser-side functionality and JavaScript testing.
+
+### Runtime JavaScript Dependencies (Browser)
+
+#### marked.js
+**Version:** ^11.0.0 || ^12.0.0 || ^13.0.0 (peer dependency)
+**Criticality:** MEDIUM
+**Purpose:** Client-side markdown parsing
+
+**Usage:**
+- Real-time markdown rendering in browser
+- Loaded via CDN: `https://cdn.jsdelivr.net/npm/marked/marked.min.js`
+- Provides fallback if CDN fails
+- HTML generation from markdown content with `marked.parse()`
+
+**Files:**
+- `markitect/templates/edit-mode.html`
+- `markitect/templates/edit-mode-fixed.html`
+- `markitect/templates/document.html`
+
+**Why this matters:** Enables interactive markdown editing in browser. Sister projects with browser UI should use the same version for consistency.
+
+---
+
+### Node.js Development Dependencies
+
+Located in `capabilities/testdrive-jsui/package.json`:
+
+#### Build Tools
+- `rollup@^4.53.5` - Module bundler
+- `@rollup/plugin-babel@^6.1.0` - Babel transpilation
+- `@rollup/plugin-commonjs@^29.0.0` - CommonJS support
+- `@rollup/plugin-node-resolve@^16.0.3` - Node module resolution
+- `@rollup/plugin-terser@^0.4.4` - Code minification
+- `rollup-plugin-postcss@^4.0.2` - CSS processing
+
+#### Testing
+- `jest@^29.7.0` - JavaScript test framework
+- `jest-environment-jsdom@^29.7.0` - DOM environment for tests
+- `babel-jest@^29.7.0` - Babel integration for Jest
+- `jsdom@^23.0.0` - DOM implementation for Node.js
+
+#### Linting and Formatting
+- `eslint@^8.57.0` - JavaScript linter
+- `eslint-config-standard@^17.1.0` - Standard style guide
+- `eslint-plugin-jest@^27.6.0` - Jest-specific rules
+
+#### CSS Processing
+- `postcss@^8.5.6` - CSS transformation
+- `postcss-import@^16.1.1` - CSS import handling
+- `autoprefixer@^10.4.23` - Vendor prefix automation
+- `cssnano@^7.1.2` - CSS minification
+
+#### Transpilation
+- `@babel/core@^7.23.0` - JavaScript compiler
+- `@babel/preset-env@^7.23.0` - Smart presets for target environments
+
+---
+
+## Dependency Criticality Matrix
+
+| Criticality | Dependencies | Impact if Missing |
+|:---|:---|:---|
+| **CRITICAL** | markdown-it-py, PyYAML, click, setuptools-scm | Project cannot function |
+| **HIGH** | tabulate | CLI output severely degraded |
+| **MEDIUM** | jsonpath-ng, aiohttp, pydantic, requests, marked.js | Features unavailable, fallbacks exist |
+| **LOW-MEDIUM** | toml | Optional format support |
+| **DEV-ONLY** | pytest, black, flake8, mypy, jest, eslint | Development/testing affected only |
+
+---
+
+## Coordination Guidelines for Sister Projects
+
+When developing referitect or other sister projects, follow these guidelines to maintain ecosystem consistency:
+
+### Mandatory Alignment
+These dependencies MUST match versions for compatibility:
+
+1. **markdown-it-py** - Ensures consistent AST structure across projects
+2. **PyYAML** - Enables shared configuration formats
+3. **setuptools-scm** - Coordinated versioning strategy
+4. **click** - Consistent CLI patterns and user experience
+
+### Recommended Alignment
+These dependencies SHOULD match for consistency:
+
+1. **tabulate** - Uniform table output across CLIs
+2. **pydantic** - Shared data validation patterns
+3. **marked.js** - Consistent browser-side rendering
+4. **black/flake8/mypy** - Unified code quality standards
+
+### Optional Dependencies
+Projects may choose different versions or alternatives:
+
+1. **jsonpath-ng** - If advanced querying not needed
+2. **aiohttp** vs. **requests** - Choose based on sync/async needs
+3. **toml** - If TOML support not required
+4. **selenium/pytest-xvfb** - If browser testing not needed
+
+### Version Pinning Strategy
+
+**Core dependencies:** Pin to minor versions (e.g., `click>=8.0.0`)
+- Allows patch updates for security fixes
+- Prevents breaking changes from major updates
+
+**Development dependencies:** Pin to specific versions in lockfile
+- Ensures reproducible development environments
+- Update deliberately during maintenance windows
+
+**Build dependencies:** Pin to exact versions (e.g., `setuptools>=64`)
+- Ensures reproducible builds
+- Critical for release management
+
+### Capability Reuse
+
+Sister projects can reuse these capabilities directly:
+
+1. **release-management** - Use for package publishing
+2. **kaizen-agentic** - Share agent development patterns
+3. **issue-facade** - Unified issue tracking across projects
+4. **testdrive-jsui** - Browser-based markdown editor
+
+Install capabilities via local file references:
+```toml
+[project.dependencies]
+release-management = {path = "../markitect-main/capabilities/release-management"}
+```
+
+### Shared Infrastructure
+
+Both projects can share:
+
+1. **Configuration schemas** - YAML/TOML format definitions
+2. **CLI patterns** - Click command structure
+3. **AST utilities** - Markdown parsing and transformation
+4. **Testing infrastructure** - pytest configuration and fixtures
+
+### Dependency Updates
+
+When updating shared dependencies:
+
+1. Update in markitect first
+2. Test thoroughly
+3. Document breaking changes in CHANGELOG.md
+4. Coordinate update in referitect
+5. Update this DEPENDENCIES.md file
+
+---
+
+## Dependency Graph
+
+```
+markitect (core)
+├── markdown-it-py (AST generation)
+├── PyYAML (config parsing)
+├── click (CLI framework)
+│   └── tabulate (table output)
+├── jsonpath-ng (AST querying)
+├── aiohttp (async HTTP)
+├── toml (TOML parsing)
+└── setuptools-scm (versioning)
+
+capabilities/
+├── markitect-utils (no deps)
+├── markitect-content
+│   └── click
+├── kaizen-agentic
+│   ├── pyyaml
+│   ├── click
+│   └── pydantic
+├── release-management
+│   ├── click
+│   ├── requests
+│   ├── setuptools-scm
+│   ├── build
+│   ├── packaging
+│   ├── pyyaml
+│   └── pydantic
+├── testdrive-jsui
+│   ├── pytest
+│   ├── pytest-xvfb
+│   ├── selenium
+│   └── JavaScript deps:
+│       ├── marked (peer)
+│       ├── jest (dev)
+│       ├── rollup (dev)
+│       └── eslint (dev)
+└── issue-facade
+    ├── click
+    ├── requests
+    └── python-dateutil
+```
+
+---
+
+## License Compatibility
+
+All dependencies use OSI-approved licenses compatible with MIT:
+
+- **MIT License:** markdown-it-py, click, tabulate, jsonpath-ng, aiohttp, pydantic, marked.js, jest, rollup
+- **Apache 2.0:** requests, setuptools-scm
+- **BSD License:** PyYAML, selenium
+- **PSF License:** python-dateutil (Python Software Foundation)
+
+No GPL or copyleft licenses used - all dependencies are permissively licensed.
+
+---
+
+## Version History
+
+- **v0.11.0** (2026-01-07): Initial DEPENDENCIES.md creation for referitect coordination
+- Future updates will track dependency changes and version bumps
+
+---
+
+**Maintained by:** MarkiTect Project Team
+**Last Updated:** 2026-01-07
+**For Questions:** See main README.md or open an issue

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.

INTRODUCTION.md

@@ -0,0 +1,253 @@
+# MarkiTect: Intelligent Markdown as Structured Information
+
+## What is MarkiTect?
+
+MarkiTect transforms how you work with markdown by treating documents as **structured, queryable information spaces** rather than plain text files. It's a comprehensive system for managing, validating, transforming, and composing markdown documents at scale—whether you're maintaining technical documentation, building knowledge bases, generating reports, or orchestrating complex document workflows.
+
+Think of MarkiTect as a **database for your markdown content**, combined with powerful tools for ensuring consistency, automating repetitive tasks, and creating intelligent document systems that adapt to your needs.
+
+## Why MarkiTect Matters
+
+### The Problem
+
+Modern documentation and content workflows face several challenges:
+
+- **Inconsistency**: Different documents follow different structures, making content hard to maintain and process
+- **Manual Validation**: No automated way to ensure documents meet quality standards or required formats
+- **Content Silos**: Documents exist in isolation without relationships or shared context
+- **Repetitive Work**: Copy-pasting boilerplate, manually updating cross-references, regenerating similar documents
+- **Limited Automation**: Plain markdown files can't drive automated workflows or integrate with systems
+- **Scaling Difficulties**: Managing hundreds or thousands of documents becomes overwhelming
+
+### The MarkiTect Solution
+
+MarkiTect solves these problems by treating markdown as **structured data**:
+
+- **Schema-Driven**: Define document structures once, validate everywhere
+- **Relational**: Documents can reference, include, and compose with each other
+- **Queryable**: Extract insights from your content using powerful queries
+- **Automated**: Generate, validate, and transform documents programmatically
+- **Versioned**: Track changes and maintain document history
+- **Composable**: Build complex documents from reusable components
+
+## Core Capabilities
+
+### 1. Information Spaces
+
+Create **organized collections of related documents** that work together as cohesive knowledge spaces:
+
+- **Structured Collections**: Group documents by project, topic, or any logical structure
+- **Transclusion**: Embed content from one document into another, maintaining a single source of truth
+- **Shared Context**: Variables and configuration shared across all documents in a space
+- **Multiple Views**: Render the same content as HTML, export to directories, or query programmatically
+- **Hierarchical Organization**: Parent-child relationships for inherited settings and permissions
+
+### 2. Schema Management
+
+Define and enforce document structures to ensure consistency:
+
+- **Schema Generation**: Automatically extract schemas from example documents
+- **Validation**: Verify documents match required structures before publishing
+- **Schema Evolution**: Track how document requirements change over time
+- **Template Generation**: Create document stubs from schemas
+- **Semantic Understanding**: Schemas capture both structure and meaning
+
+### 3. Document Processing
+
+Powerful tools for analyzing, transforming, and manipulating content:
+
+- **Intelligent Parsing**: Understand document structure including frontmatter, content, and metadata
+- **Content Extraction**: Pull specific sections, metadata, or elements from documents
+- **Transformation**: Convert between formats while preserving semantic meaning
+- **Batch Operations**: Process multiple documents with a single command
+- **Quality Checks**: Automated validation of links, references, and formatting
+
+### 4. Transclusion & Composition
+
+Build complex documents from reusable components:
+
+- **Content Reuse**: Include shared sections across multiple documents
+- **Variable Substitution**: Parameterize content for different contexts
+- **Conditional Content**: Show or hide sections based on conditions
+- **Variant Generation**: Create multiple versions from a single source
+- **Cross-Document References**: Maintain relationships between related content
+
+### 5. Querying & Analysis
+
+Extract insights from your documentation:
+
+- **Metadata Queries**: Find documents by attributes, tags, or properties
+- **Content Search**: Locate specific information across your entire corpus
+- **Relationship Mapping**: Understand how documents connect and depend on each other
+- **Statistics**: Analyze document sizes, structures, and patterns
+- **Reporting**: Generate summaries and reports from your content
+
+### 6. Automation & Integration
+
+Connect markdown content to broader workflows:
+
+- **CLI Interface**: Automate any operation from scripts or CI/CD pipelines
+- **GraphQL API**: Query and manipulate spaces programmatically
+- **Event System**: React to document changes in real-time
+- **Plugin Architecture**: Extend functionality for specific needs
+- **Git Integration**: Optional version control for complete change history
+
+## Use Cases
+
+### Technical Documentation
+
+**Challenge**: Maintain consistent API documentation across multiple services
+**Solution**: Use schemas to enforce standard formats, transclusion for shared examples, and variables for service-specific details
+
+**Benefits**:
+- One source of truth for common patterns
+- Automatic validation of all documentation
+- Generate client libraries and API specs from the same source
+- Track documentation changes alongside code
+
+### Knowledge Management
+
+**Challenge**: Organize company knowledge across departments and projects
+**Solution**: Create information spaces for each domain, use cross-document references for relationships, enable search across all content
+
+**Benefits**:
+- Discoverable knowledge base
+- Consistent structure across departments
+- Track what content exists and how it connects
+- Generate reports on documentation coverage
+
+### Report Generation
+
+**Challenge**: Create hundreds of similar reports with varying data
+**Solution**: Define report schemas, use templates with variables, batch-generate reports from data sources
+
+**Benefits**:
+- Consistent report structure
+- Automated generation from data
+- Quality validation before distribution
+- Version tracking for compliance
+
+### Content Publishing
+
+**Challenge**: Maintain a blog or publication with consistent formatting
+**Solution**: Use schemas for post structures, transclusion for common elements, render to HTML with themes
+
+**Benefits**:
+- Enforced style guide compliance
+- Reusable components (author bios, disclaimers, CTAs)
+- Multiple output formats from single source
+- Automated link checking and validation
+
+### Educational Materials
+
+**Challenge**: Create course materials with exercises, examples, and assessments
+**Solution**: Schema-driven lesson structures, transclusion for common instructions, variable content for different audiences
+
+**Benefits**:
+- Consistent lesson structure
+- Easy updates across multiple courses
+- Generate student and instructor versions
+- Track curriculum evolution
+
+### Compliance Documentation
+
+**Challenge**: Maintain audit trails and ensure required document elements
+**Solution**: Strict schemas with validation, versioned spaces with history tracking, automated compliance reports
+
+**Benefits**:
+- Guaranteed document completeness
+- Audit trail for all changes
+- Automated compliance checking
+- Generate reports for auditors
+
+## Key Benefits
+
+### For Writers and Content Creators
+
+- **Focus on Content**: Let MarkiTect handle structure and consistency
+- **Reuse Work**: Write once, use everywhere with transclusion
+- **Quality Assurance**: Automated validation catches errors early
+- **Easy Updates**: Change once, propagate everywhere
+- **Version Control**: Track all changes with git integration
+
+### For Teams and Organizations
+
+- **Consistency at Scale**: Same structure across thousands of documents
+- **Collaboration**: Shared spaces with inheritance and permissions
+- **Automation**: Reduce manual work through scripting
+- **Integration**: Connect documentation to development workflows
+- **Maintainability**: Clear structure makes updates easier
+
+### For Developers and Automators
+
+- **Programmatic Access**: CLI and GraphQL APIs for automation
+- **Event-Driven**: React to changes in real-time
+- **Extensible**: Plugin system for custom functionality
+- **Type-Safe**: Schemas provide structure for reliable automation
+- **Performance**: Intelligent caching for fast operations
+
+### For Organizations
+
+- **Reduced Costs**: Automation reduces manual documentation work
+- **Higher Quality**: Validation ensures consistency and completeness
+- **Better Governance**: Track changes, enforce standards, maintain compliance
+- **Improved Discovery**: Query and search across all content
+- **Future-Proof**: Markdown is open, portable, and sustainable
+
+## Getting Started
+
+MarkiTect works with your existing markdown files. Start small:
+
+1. **Process a document**: Ingest a markdown file to see its structure
+2. **Generate a schema**: Extract patterns from your existing content
+3. **Validate consistency**: Check if other documents match the pattern
+4. **Create a space**: Group related documents together
+5. **Explore capabilities**: Try transclusion, rendering, or querying
+
+No migration required—MarkiTect enhances your workflow without replacing your tools.
+
+## Who Should Use MarkiTect?
+
+**MarkiTect is ideal for**:
+- Technical writers maintaining large documentation sets
+- Documentation teams standardizing content across projects
+- Content operations teams automating publishing workflows
+- Knowledge managers organizing institutional information
+- Developers integrating documentation into CI/CD
+- Publishers creating structured content from markdown
+
+**MarkiTect might not be right if**:
+- You only work with a handful of simple documents
+- You don't need consistency or validation
+- Your content has no structure or patterns
+- You prefer visual editors over text-based workflows
+
+## Philosophy
+
+MarkiTect is built on these principles:
+
+**Markdown is Data**: Documents contain structured information that can be processed, queried, and transformed
+
+**Convention Over Configuration**: Sensible defaults that work out of the box, customize only when needed
+
+**Schema-Driven Quality**: Define structures once, enforce them everywhere
+
+**Composability**: Build complex systems from simple, reusable components
+
+**Performance Matters**: Fast operations that scale to thousands of documents
+
+**Open and Portable**: Pure markdown files that work with any tool
+
+## What's Next?
+
+This introduction provides a high-level overview of MarkiTect's value and capabilities. To dive deeper:
+
+- **[CLI Tutorial](docs/CLI_TUTORIAL.md)**: Learn practical commands and workflows
+- **[Schema Management Guide](docs/SCHEMA_MANAGEMENT_GUIDE.md)**: Master document validation
+- **[Asset Management](docs/ASSET_MANAGEMENT_USER_GUIDE.md)**: Work with images and resources
+- **[Plugin System](docs/PLUGIN_SYSTEM.md)**: Extend MarkiTect for your needs
+- **[Project Structure](docs/PROJECT_STRUCTURE.md)**: Understand how it's organized
+
+---
+
+*MarkiTect transforms markdown from simple text files into intelligent, structured information spaces that power modern documentation and content workflows.*

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:

SCOPE.md

@@ -0,0 +1,129 @@
+# SCOPE
+
+> This file helps you quickly understand what this repository is about,
+> when it is relevant, and when it is not.
+> It is intentionally lightweight and may be incomplete.
+
+---
+
+## One-liner
+
+Intelligent markdown engine and information management platform — treats documents as structured, queryable information spaces with schema validation, transclusion, LLM-driven evaluation, and infospace lifecycle management.
+
+---
+
+## Core Idea
+
+MarkiTect turns fragmented knowledge (scattered docs, chats, notes) into structured, versioned, reusable artifacts. The core abstraction is an **infospace**: a curated collection of typed entities (concepts, mechanisms, observations) governed by a YAML config, validated against schemas, and evaluated for quality across five dimensions. The platform automates generation, validation, and transformation at scale, delegating domain-level judgment to LLMs while Python handles structure and evaluation.
+
+---
+
+## In Scope
+
+- Parse, validate, and analyze markdown documents against schemas
+- Generate schemas from example documents; enforce naming convention `{domain}-schema-v{major}.{minor}.md`
+- Infospace lifecycle: create, populate, evaluate (per-entity + collection quality scores), compose, export
+- Transclusion: embed content from one document into another, maintaining single source of truth
+- LLM-driven prompt execution with dependency resolution and quality gates
+- Relationship graph export (Mermaid, DOT) and analysis (networkx, FCA)
+- Batch document processing; CLI (`markitect <command>`) and programmatic API
+- Rendering: markdown → interactive HTML via plugin system (testdrive-jsui)
+- Asset management (image embedding, resource handling)
+
+---
+
+## Out of Scope
+
+- Visual/WYSIWYG editing (markdown-first, text-based workflows only)
+- Real-time collaborative editing (git-based versioning instead)
+- Financial transactions or external payment integration
+- Making domain-level judgments in Python code (delegated to LLM via prompt templates)
+- Storing secrets or credentials in plaintext
+- Full GraphQL API (structure exists but not fully implemented)
+- Vendor-specific integrations or lock-in
+
+---
+
+## Relevant When
+
+- Managing large document sets (hundreds to thousands) needing consistent structure and validation
+- Building or maintaining institutional knowledge bases, technical documentation, or canon releases
+- Automating document generation from schemas or templates
+- Tracking relationships and dependencies between knowledge artifacts
+- Needing programmatic access to document structure (beyond file reading)
+- Applying quality evaluation to a structured concept collection
+
+---
+
+## Not Relevant When
+
+- Working with a handful of simple, unrelated documents
+- Visual editor required
+- Exclusively non-markdown source formats (PDF/Word need conversion first)
+- No consistency, validation, or automation needed
+
+---
+
+## Current State
+
+- Status: active (v0.13.0-dev, ~90 commits ahead of release)
+- Implementation: substantial — core modules mature (CLI, parsing, schema management, prompt execution, infospace); infospace S3 close-out in progress; LLM adapter extracted to standalone `llm-connect` package
+- Stability: stable core; plugin system and infospace tooling evolving; 200+ CHANGELOG entries since v0.6.0
+- Usage: active personal development; examples with 988 entities and full evaluation pipeline
+
+---
+
+## How It Fits
+
+- Upstream dependencies: `llm-connect` (LLM adapter library, extracted), `testdrive-jsui` (rendering plugin submodule), `markitect-utils` (utility library)
+- Downstream consumers: Custodian — MarkiTect is the knowledge artifact platform in the canonical dependency order (Railiance → **Markitect** → Coulomb.social → Personhood/Foerster → Custodian)
+- Often used with: the-custodian (state hub tracks markitect domain workstreams), kaizen-agentic (project-management agent for session workflow)
+
+---
+
+## Terminology
+
+- Preferred terms: infospace, topic, discipline, entity, evaluation, viability, transclusion, schema, quality gates
+- Also known as: "markitect", "the markdown engine"
+- Potentially confusing terms: "topic" = the subject matter an infospace explains (not a chat thread); "discipline" = a reusable framework of concepts (itself a viable infospace); "infospace" ≠ filesystem directory (it's a curated conceptual collection with explicit quality thresholds)
+
+---
+
+## Related / Overlapping
+
+- `llm-connect` — standalone LLM adapter extracted from MarkiTect (dependency)
+- `the-custodian` — tracks markitect workstreams; custodian canon includes a markitect domain charter
+- `marki-docx` — separate repo (on tegwick machine); relationship: docx export capability for MarkiTect artifacts
+
+---
+
+## Provided Capabilities
+
+```capability
+type: documentation
+title: Structured document validation and schema management
+description: Parse, validate, and enforce schemas on markdown documents — generate schemas from examples, validate entity collections, report naming convention compliance.
+keywords: [markdown, schema, validation, document, structure, linting]
+```
+
+```capability
+type: documentation
+title: Infospace lifecycle management
+description: Create, populate, evaluate (quality scores), compose, and export curated knowledge collections (infospaces) with transclusion and relationship graph analysis.
+keywords: [infospace, knowledge, curation, evaluation, transclusion, quality, graph]
+```
+
+```capability
+type: data
+title: LLM-driven knowledge artifact generation
+description: Execute prompts with dependency resolution and quality gates to generate typed entities — concepts, mechanisms, observations — at scale from schemas and templates.
+keywords: [llm, generation, prompt, entity, artifact, knowledge, automation]
+```
+
+---
+
+## Getting Oriented
+
+- Start with: `CLAUDE.md` (dev commands, LLM config, infospace lifecycle), `INTRODUCTION.md` (use cases, philosophy)
+- Key files / directories: `markitect/cli.py` (CLI entry point), `markitect/infospace/` (primary active area), `markitect/prompts/` (LLM execution), `roadmap/` (6 active planning tracks), `examples/infospace-with-history/` (988-entity reference implementation)
+- Entry points: `markitect --help`; `markitect infospace --help`; `pytest tests/unit/` (inner TDD loop)

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-main/
+├── 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-main/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-main/capabilities
+
+re_integration_guide: |
+  To re-integrate this capability using the new architecture:
+
+  # Option 1: Git submodule (recommended)
+  cd /home/worsch/markitect-main/capabilities
+  git submodule add <repo-url> _issue-facade
+  pip install -e _issue-facade/
+
+  # Option 2: Clone directly
+  cd /home/worsch/markitect-main/capabilities
+  git clone <repo-url> _issue-facade
+  pip install -e _issue-facade/
+
+  # Option 3: Copy into project
+  cd /home/worsch/markitect-main/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-content/tests/test_issue_46_schema_generation_outline.py

@@ -8,7 +8,7 @@ This test module validates outline mode schema generation improvements including
 - Content instruction integration
 - End-to-end workflow from example document to generated drafts
 
-Created for Issue #46: https://gitea.coulomb.social/coulomb/markitect_project/issues/46
+Created for Issue #46: https://gitea.coulomb.social/coulomb/markitect-main/issues/46
 """
 
 import pytest

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-main/
+├── 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-main"
+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-main
+- **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-main/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-main` |
+| **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-main
+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-main
+
+# 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-main/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-main
+
+# 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/PROJECT_STRUCTURE.md

@@ -0,0 +1,286 @@
+# MarkiTect Project Structure
+
+This document describes the current project layout, architectural decisions, and the reorganization plan for the Information Space Service evolution.
+
+## Overview
+
+MarkiTect is a markdown processing toolkit with transclusion, schema validation, asset management, and multi-format output capabilities. The project follows a hybrid layout that is being incrementally consolidated.
+
+## Current Directory Structure
+
+```
+markitect-main/
+├── markitect/                    # Main package
+│   ├── [34 root-level .py files] # Core functionality (see below)
+│   ├── assets/                   # Asset discovery, management, caching (21 files)
+│   ├── finance/                  # Cost tracking, work time management (9 files)
+│   ├── plugins/                  # Plugin system with base classes (7 files)
+│   ├── packaging/                # Asset packaging, MDZ variants (7 files)
+│   ├── production/               # Deployment validation, benchmarks (6 files)
+│   ├── legacy/                   # Legacy compatibility layer (8 files)
+│   ├── explode_variants/         # Document expansion, variants (9 files)
+│   ├── query_paradigms/          # Query paradigm implementations (4 files)
+│   ├── validators/               # Content/link/section validation (4 files)
+│   ├── matter_frontmatter/       # Front matter parsing (4 files)
+│   ├── matter_contentmatter/     # Content matter parsing (4 files)
+│   ├── matter_tailmatter/        # Tail matter parsing (4 files)
+│   ├── profile/                  # User profile management (4 files)
+│   ├── graphql/                  # GraphQL query implementation (4 files)
+│   ├── template/                 # Template management (3 files)
+│   ├── themes/                   # Theme system with subdirectories (1 file)
+│   └── schemas/                  # Built-in schema definitions (9 files)
+├── application/                  # Application layer services
+├── domain/                       # Domain models
+├── infrastructure/               # Infrastructure implementations
+├── tests/                        # Test suite (90+ test files)
+│   ├── unit/                     # Unit tests
+│   ├── integration/              # Integration tests
+│   ├── e2e/                      # End-to-end tests
+│   └── fixtures/                 # Test data
+├── docs/                         # Documentation (12+ subdirectories)
+├── src/                          # JavaScript/frontend components
+└── roadmap/                      # Project roadmap
+```
+
+## Root-Level Modules (/markitect/)
+
+The 34 root-level Python files are organized by function:
+
+### Core Infrastructure
+| File | Lines | Purpose |
+|------|-------|---------|
+| `parser.py` | ~50 | Markdown AST parsing using markdown-it |
+| `serializer.py` | ~360 | AST serialization back to Markdown |
+| `document_manager.py` | ~100 | Wrapper around CleanDocumentManager |
+| `clean_document_manager.py` | ~2000 | Clean document management implementation |
+| `workspace.py` | ~200 | Workspace management |
+| `database.py` | ~400 | SQLite database management |
+
+### Schema Management (6 files, 99KB total)
+| File | Lines | Purpose |
+|------|-------|---------|
+| `schema_generator.py` | ~600 | JSON schema generation from markdown AST |
+| `schema_analyzer.py` | ~450 | Schema rigidity analysis with phase classification |
+| `schema_loader.py` | ~600 | Schema loading from markdown with frontmatter |
+| `schema_refiner.py` | ~600 | Automatic schema refinement using loosening rules |
+| `schema_validator.py` | ~900 | Comprehensive schema validation |
+| `schema_naming.py` | ~300 | Schema naming convention enforcement |
+
+### Configuration & Services
+| File | Purpose |
+|------|---------|
+| `config_manager.py` | Configuration file management |
+| `frontmatter.py` | YAML frontmatter parsing |
+| `exceptions.py` | Custom exception classes |
+| `ast_service.py` | AST service layer |
+| `cache_service.py` | Caching functionality |
+| `ast_cache.py` | AST caching implementation |
+| `performance_tracker.py` | Performance metrics |
+
+### Validation & Analysis
+| File | Purpose |
+|------|---------|
+| `semantic_validator.py` | Semantic validation layer |
+| `validation_error.py` | Validation error handling |
+| `metaschema.py` | Metaschema validation for custom extensions |
+
+### CLI & Commands
+| File | Purpose |
+|------|---------|
+| `cli.py` | Main CLI interface (274KB, comprehensive) |
+| `cli_utils.py` | CLI utilities |
+| `asset_commands.py` | Asset-related CLI commands |
+| `draft_generator.py` | Draft generation functionality |
+
+### Utilities
+| File | Purpose |
+|------|---------|
+| `batch_processor.py` | Batch processing operations |
+| `associated_files.py` | Associated file tracking |
+| `legacy_compat.py` | Legacy compatibility layer |
+| `legacy_integration_example.py` | Integration examples |
+| `_version.py`, `__version__.py` | Version management |
+
+## Subpackages
+
+### assets/ (21 files)
+Complete asset management system including discovery, analytics, caching, deduplication, and packaging. Key files:
+- `repository.py` - Asset repository pattern
+- `discovery.py` - Asset discovery algorithms
+- `cache.py` - Asset caching layer
+- `analytics.py` - Asset usage analytics
+
+### finance/ (9 files)
+Cost tracking and work time management:
+- `models.py` - Financial data models
+- `cost_tracker.py` - Cost tracking implementation
+- `period_tracker.py` - Period-based tracking
+- `report_generator.py` - Financial reports
+
+### plugins/ (7 files)
+Extensible plugin system:
+- `base.py` - Plugin base classes and types
+- `registry.py` - Plugin registry
+- `builtin/` - Built-in plugin implementations
+
+### packaging/ (7 files)
+Asset packaging and MDZ format support:
+- `mdz_packager.py` - MDZ package creation
+- `transclusion.py` - Transclusion handling
+- `variant_factory.py` - Variant generation
+
+### production/ (6 files)
+Deployment and production validation:
+- `deployment_validator.py` - Deployment checks
+- `performance_benchmark.py` - Performance testing
+- `cross_platform_validator.py` - Platform compatibility
+
+### legacy/ (8 files)
+Backward compatibility layer:
+- `compatibility.py` - Compatibility wrappers
+- `deprecation.py` - Deprecation warnings
+- `git_tracker.py` - Git integration (useful for Phase 8)
+
+## Test Structure
+
+```
+tests/
+├── conftest.py              # Shared pytest configuration
+├── fixtures/                # Test data files
+│   ├── content_test_files/
+│   ├── contentmatter_test_files/
+│   ├── frontmatter_test_files/
+│   └── tailmatter_test_files/
+├── unit/                    # Unit tests by domain
+│   ├── application/
+│   └── infrastructure/
+├── integration/             # Integration tests
+│   └── repositories/
+└── e2e/                     # End-to-end tests
+    ├── cli/
+    └── performance/
+```
+
+---
+
+## Planned Reorganization
+
+### Motivation
+
+The current layout has grown organically, resulting in:
+1. **34 files at root level** - Too many modules at package root
+2. **No clear grouping** - Schema tools, core infrastructure, and utilities mixed
+3. **Hybrid architecture** - Mix of root packages and monolithic /markitect/
+
+### Target Structure
+
+After reorganization, the /markitect/ package will have clearer structure:
+
+```
+markitect/
+├── core/                    # Core infrastructure (NEW)
+│   ├── __init__.py
+│   ├── parser.py           # (from markitect/)
+│   ├── serializer.py       # (from markitect/)
+│   ├── document_manager.py # (from markitect/)
+│   └── workspace.py        # (from markitect/)
+├── schema/                  # Schema management (NEW)
+│   ├── __init__.py
+│   ├── validator.py        # (from schema_validator.py)
+│   ├── generator.py        # (from schema_generator.py)
+│   ├── loader.py           # (from schema_loader.py)
+│   ├── analyzer.py         # (from schema_analyzer.py)
+│   ├── refiner.py          # (from schema_refiner.py)
+│   └── naming.py           # (from schema_naming.py)
+├── storage/                 # Storage concerns (NEW)
+│   ├── __init__.py
+│   ├── database.py         # (from markitect/)
+│   └── cache.py            # (consolidated)
+├── spaces/                  # Information spaces (Phase 1+)
+│   ├── models.py
+│   ├── events/
+│   ├── repositories/
+│   ├── transclusion/
+│   ├── rendering/
+│   ├── sync/
+│   └── services/
+└── [existing subpackages]   # assets/, plugins/, etc.
+```
+
+### Backward Compatibility
+
+Original import paths will continue to work through re-exports:
+
+```python
+# Old import (still works)
+from markitect.parser import parse_markdown
+
+# New import (preferred)
+from markitect.core.parser import parse_markdown
+```
+
+### Migration Strategy
+
+1. Create new subpackages with copied content
+2. Update internal imports to new paths
+3. Add deprecation warnings to old paths
+4. Re-export from original locations for compatibility
+5. Verify all tests pass
+6. Update documentation
+
+---
+
+## Information Space Service Architecture
+
+The reorganization prepares for the Information Space Service evolution, which adds:
+
+### Phase 1-3: Foundation
+- `InformationSpace` entity with lifecycle management
+- `SpaceRepository` for persistence
+- Event system for change tracking
+- Persistent transclusion context
+
+### Phase 4-5: Modes
+- HTML rendering mode with caching
+- Directory mode with bidirectional sync
+
+### Phase 6-7: API & Composability
+- GraphQL schema extensions
+- CLI commands for space management
+- Space references and inheritance
+
+### Phase 8: Git History (Optional)
+- Git-based version control for spaces
+- Event-driven commits
+- Version navigation
+
+See [docs/roadmap/information-space-service/](./roadmap/information-space-service/) for the complete workplan.
+
+---
+
+## Key Dependencies
+
+From `pyproject.toml`:
+- Python >=3.8 (tested on 3.12)
+- markdown-it-py - Markdown parsing
+- PyYAML - YAML/frontmatter handling
+- click - CLI framework
+- tabulate - Table formatting
+- jsonpath-ng - JSON path queries
+- aiohttp - Async HTTP
+
+## Version Information
+
+- Current version is managed in `_version.py` and `__version__.py`
+- Follows semantic versioning
+- CHANGELOG.md tracks all changes
+
+---
+
+## Related Documentation
+
+- [CLI Tutorial](CLI_TUTORIAL.md) - CLI usage guide
+- [Plugin System](PLUGIN_SYSTEM.md) - Plugin architecture
+- [Schema Management Guide](SCHEMA_MANAGEMENT_GUIDE.md) - Schema workflows
+- [Asset Management Guide](ASSET_MANAGEMENT_USER_GUIDE.md) - Asset system
+- [Error Handling Strategy](ERROR_HANDLING_STRATEGY.md) - Error patterns

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-main`) **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-main/
+├── .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-main/
+cd /home/worsch/markitect-main
+
+# Main repo tasks:
+# - Integrate capabilities
+# - Update dependencies
+# - Configure capability usage
+# - Test integration points
+```
+
+#### Capability Session
+```bash
+# In capability repository
+cd /home/worsch/markitect-main/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-main
+   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-main
+
+# 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-main
+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-main/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-main
+   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/composition-guide.md

@@ -0,0 +1,203 @@
+# Infospace Composition Guide
+
+One completed, viable infospace can be reused as a **discipline** for
+another infospace — a lens applied to a different topic. This guide
+explains how composition works and walks through the live
+`examples/supply-chain-vsm/` reference.
+
+---
+
+## What composition means
+
+An **infospace** is a directory of typed entities governed by
+`infospace.yaml`. Its entities and relations describe a specific topic
+(for example, Adam Smith's *Wealth of Nations*).
+
+A **discipline** is an infospace declared as a reusable analytical
+framework by another infospace. When infospace B binds infospace A as a
+discipline:
+
+1. B's entities can reference A's entities in `## WoN Concept` (or
+   equivalent) sections.
+2. Properties A has already computed on its entities — such as VSM system
+   placement — become available to B by transitivity through the mapping.
+3. B can impose its own viability thresholds independently of A's. The two
+   infospaces each pass or fail viability on their own terms.
+
+The binding is declarative: a relative path in `infospace.yaml` plus a
+display name. No code. No import. The discipline is looked up on disk at
+the declared path when B's commands run.
+
+---
+
+## The viability pre-condition
+
+Binding a non-viable infospace as a discipline is a mistake: a framework
+that fails its own thresholds is not a stable reference frame. Before
+binding, confirm the candidate discipline is viable:
+
+```bash
+cd examples/infospace-with-history
+markitect infospace viability
+```
+
+```
+Metric                            Value       Threshold   Status
+---------------------------------------------------------------
+redundancy_ratio                 0.0061         max=0.1     PASS
+coverage_ratio                   0.6190         min=0.4     PASS
+coherence_components             0.0000           max=3     PASS
+consistency_cycles               0.0000           max=0     PASS
+granularity_entropy              2.6748         min=1.0     PASS
+per_entity_mean                  3.9556         min=3.5     PASS
+
+Viable: YES (6/6 thresholds met)
+```
+
+If the discipline is not viable, fix it first (see
+`examples/infospace-with-history/docs/advanced-usage.md` §4 for triaging
+low scorers).
+
+---
+
+## Example — how `supply-chain-vsm` binds WoN
+
+The supply-chain infospace declares WoN as a discipline in its
+`infospace.yaml`:
+
+```yaml
+topic:
+  name: "Modern Supply Chain Management"
+  domain: "Operations Management"
+  sources: artifacts/sources/
+
+disciplines:
+  - name: "Wealth of Nations"
+    path: ../infospace-with-history
+```
+
+The binding is a **relative path**, so the two infospaces travel together
+(they can be moved as a pair without breaking the link).
+
+Verify the binding resolves and the discipline is viable:
+
+```bash
+cd examples/supply-chain-vsm
+markitect infospace disciplines
+```
+
+```
+Name                           Entities   Viable Path
+----------------------------------------------------------------------
+Wealth of Nations                   988      YES ../infospace-with-history
+```
+
+Each supply-chain entity then carries a `## WoN Concept` section
+mapping it to exactly one WoN entity. The consolidated mapping files
+(`output/mappings/*-mappings.md`) record the pairing, rationale, and a
+conceptual-continuity rating (Strong / Moderate / Weak):
+
+| Supply Chain Entity          | WoN Concept                      | Strength | VSM   |
+|------------------------------|----------------------------------|----------|-------|
+| Demand Signal                | Effectual Demand                 | Strong   | S2    |
+| Vendor-Managed Inventory     | Division of Labour               | Strong   | S1/S2 |
+| Just-in-Time Inventory       | Circulating Capital              | Strong   | S1/S3 |
+| Bullwhip Effect              | Natural Price as Central Price   | Moderate | S2    |
+| Safety Stock                 | Accumulation of Stock            | Moderate | S3    |
+
+Because each WoN entity already has a VSM system placement (S1–S5), the
+supply-chain entities inherit a VSM position by transitivity through
+their mapping — without supply-chain-vsm needing its own VSM reference.
+
+---
+
+## Creating a new infospace that binds an existing one
+
+Step-by-step, using WoN as the discipline for a hypothetical "Modern
+Monetary Policy" infospace:
+
+### 1. Start from the target topic
+
+```bash
+mkdir -p examples/monetary-policy/artifacts/sources
+cd examples/monetary-policy
+markitect infospace init
+```
+
+### 2. Declare the discipline in `infospace.yaml`
+
+```yaml
+topic:
+  name: "Modern Monetary Policy"
+  domain: "Macroeconomics"
+  sources: artifacts/sources/
+
+disciplines:
+  - name: "Wealth of Nations"
+    path: ../infospace-with-history
+```
+
+Alternatively, bind imperatively after `init`:
+
+```bash
+markitect infospace bind-discipline ../infospace-with-history --name "Wealth of Nations"
+```
+
+### 3. Set your own viability thresholds
+
+Copy the `viability:` block from a reference infospace and tune the
+numbers to the scale and maturity of your topic. A smaller infospace
+(50 entities, not 988) may need laxer `coverage_ratio` and stricter
+`redundancy_ratio`.
+
+### 4. Verify the binding
+
+```bash
+markitect infospace disciplines
+```
+
+If `Viable` is `NO`, stop and fix the discipline before continuing.
+
+### 5. Reference discipline entities in your own entities
+
+For each entity in the new infospace, add a `## <Discipline> Concept`
+section that names the WoN entity the concept maps to, plus a rationale.
+The exact section heading is configured per schema — see
+`schemas/won-mapping-schema-v1.0.md` in `supply-chain-vsm` for the
+template used there.
+
+### 6. Run checks and evaluate
+
+```bash
+markitect infospace check
+markitect infospace evaluate --provider openrouter
+markitect infospace eval-summary --update-metrics
+markitect infospace viability
+```
+
+The new infospace passes or fails viability independently of WoN.
+
+---
+
+## Why composition, not inclusion?
+
+An alternative would be to copy WoN entities directly into the target
+infospace. Composition avoids that by design:
+
+- **One source of truth** — if WoN is refined, every infospace that binds
+  it picks up the improvement on the next run without a sync step.
+- **Separation of concerns** — each infospace owns its own schema,
+  thresholds, and entity set. Changing the target topic cannot pollute
+  the discipline.
+- **Bounded dependency** — the binding is a path, so the coupling is
+  visible in one place (`infospace.yaml`) and easy to remove.
+
+---
+
+## See also
+
+- `examples/supply-chain-vsm/README.md` — the full reference composition.
+- `examples/supply-chain-vsm/output/mappings/` — consolidated mapping
+  files showing the rationale and strength rating for each pairing.
+- `examples/infospace-with-history/docs/advanced-usage.md` — patterns for
+  maintaining the discipline once it is in use.

docs/infospace-primitives.md

@@ -0,0 +1,344 @@
+# Infospace Primitives Reference
+
+This document describes the primitives provided by the `markitect/infospace/`
+package for creating, evaluating, maintaining, and composing infospaces.
+
+---
+
+## Core Concepts
+
+An **infospace** is a structured, evaluable, composable collection of
+entities that explains a **topic** through the lens of one or more
+**disciplines**.
+
+| Term | Meaning |
+|------|---------|
+| **Topic** | The subject matter being explained |
+| **Discipline** | A reusable framework of concepts applied as an analytical lens |
+| **Entity** | The atomic unit of knowledge — slug, definition, provenance, domain |
+| **Evaluation** | Per-entity or collection-level quality assessment |
+| **Viability** | Whether an infospace meets its threshold scores |
+
+---
+
+## Configuration (`infospace.yaml`)
+
+Every infospace is declared via an `infospace.yaml` file. The configuration
+model is defined in `markitect/infospace/config.py`.
+
+### Minimal example
+
+```yaml
+topic:
+  name: "The Wealth of Nations"
+  domain: "Classical Economics"
+  sources: artifacts/sources/
+
+disciplines:
+  - name: "Viable System Model"
+    path: artifacts/vsm-reference/
+
+schemas:
+  entity: schemas/economic-entity-schema-v1.0.md
+
+viability:
+  coverage_ratio: { min: 0.60 }
+  redundancy_ratio: { max: 0.05 }
+  per_entity_mean: { min: 3.5 }
+```
+
+### Key models
+
+- **`TopicConfig`** — `name`, `domain`, `sources`
+- **`DisciplineBinding`** — `name`, `path` (to another infospace directory)
+- **`SchemaRegistry`** — `entity`, `mapping`, `analysis` schema paths
+- **`ViabilityThreshold`** — `metric`, `min`, `max` bounds
+- **`PipelineConfig`** — Ordered list of `PipelineStage` entries
+- **`InfospaceConfig`** — Top-level config combining all of the above
+
+### Default directories
+
+| Setting | Default |
+|---------|---------|
+| `entities_dir` | `output/entities` |
+| `evaluations_dir` | `output/evaluations` |
+| `metrics_dir` | `output/metrics` |
+
+---
+
+## Entity Metadata
+
+Entities are parsed from markdown files by `markitect/infospace/entity_parser.py`.
+
+**`EntityMeta`** fields: `slug`, `title`, `definition`, `domain`,
+`source_chapter`, `context`, `original_wording`, `modern_interpretation`,
+`definition_word_count`, `total_word_count`, `section_slugs`.
+
+```python
+from markitect.infospace import parse_entity_directory
+entities = parse_entity_directory(Path("output/entities"))
+```
+
+---
+
+## Schema Validation
+
+Deterministic validation of entity files against structural schemas.
+
+```python
+from markitect.infospace import validate_entity, ECONOMIC_ENTITY_SCHEMA
+result = validate_entity(entity_meta, schema=ECONOMIC_ENTITY_SCHEMA)
+print(result.summary())
+```
+
+Checks: section presence, word count ranges, heading format, enum values.
+
+---
+
+## Per-entity Evaluation
+
+LLM-based quality assessment of individual entities. Defined in
+`markitect/infospace/evaluate.py`.
+
+```bash
+# Evaluate all entities
+markitect infospace evaluate --provider openrouter
+
+# Single entity
+markitect infospace evaluate --entity division-of-labour --provider openrouter
+```
+
+### Pipeline functions
+
+- `build_evaluation_prompt(entity, topic, dimensions)` — build the LLM prompt
+- `parse_evaluation_response(text, dimensions)` — parse LLM output to `ScoreEntry` list
+- `run_entity_evaluation(config, entities, adapter, ...)` — full batch pipeline
+
+Results are written to `output/evaluations/` as YAML frontmatter + markdown.
+
+---
+
+## Collection-level Checks
+
+Five concerns assessed at the collection level. Each has a dedicated
+module in `markitect/infospace/checks/`.
+
+| Concern | Module | Key metric |
+|---------|--------|------------|
+| **C1 — Redundancy** | `redundancy.py` | `redundancy_ratio` |
+| **C2 — Coverage** | `coverage.py` | `coverage_ratio` |
+| **C3 — Coherence** | `coherence.py` | `coherence_components`, `modularity` |
+| **C4 — Consistency** | `consistency.py` | `consistency_cycles` |
+| **C5 — Granularity** | `granularity.py` | `granularity_entropy` |
+
+### Orchestrator
+
+```python
+from markitect.infospace.checks import run_all_checks
+report = run_all_checks(entities, embeddings=emb, graph=g)
+metrics = report.metrics()  # Dict[str, float]
+```
+
+### CLI
+
+```bash
+# Run all checks
+markitect infospace check
+
+# Run specific concerns
+markitect infospace check --concern redundancy --concern coverage
+
+# JSON output
+markitect infospace check --json
+```
+
+After each check run, metrics are automatically recorded to history.
+
+---
+
+## Metrics History
+
+Timestamped snapshots track metrics over time. Defined in
+`markitect/infospace/history.py`.
+
+```bash
+# Show history
+markitect infospace history
+
+# Trend for a single metric
+markitect infospace history --metric coverage_ratio
+
+# Compare two snapshots
+markitect infospace history-diff 2026-02-01 2026-03-01
+```
+
+### Key functions
+
+- `snapshot_from_checks(report, entity_count)` — create snapshot from check results
+- `record_check_results(report, config, root, entity_count)` — save metrics + append to history
+- `get_history(config, root)` — read full history
+- `metric_trend(history, metric_name)` — extract single metric across time
+
+---
+
+## Viability
+
+Viability is assessed by comparing current metrics to thresholds declared
+in `infospace.yaml`.
+
+```bash
+markitect infospace viability
+```
+
+### Threshold model
+
+```yaml
+viability:
+  coverage_ratio: { min: 0.60 }       # must be >= 0.60
+  redundancy_ratio: { max: 0.05 }     # must be <= 0.05
+  consistency_cycles: { max: 0 }       # must be exactly 0
+```
+
+Each threshold has `min` and/or `max` bounds. A metric passes if it falls
+within bounds. An infospace is viable when all thresholds pass.
+
+---
+
+## Composition
+
+One infospace can use another as a discipline. The composition model is
+defined in `markitect/infospace/composition.py`.
+
+### Binding a discipline
+
+```bash
+markitect infospace bind-discipline ./path/to/vsm-infospace --name "Viable System Model"
+```
+
+This adds a `DisciplineBinding` to `infospace.yaml` and validates the
+discipline exists and has an `infospace.yaml`.
+
+### Checking discipline status
+
+```bash
+markitect infospace disciplines
+```
+
+Shows: name, entity count, viability status, path.
+
+### Viability requirement
+
+A discipline must meet its own viability thresholds to be considered
+reliable. The `check_discipline_status()` function loads the discipline's
+metrics and runs its own threshold checks.
+
+### Stale mapping detection
+
+```bash
+markitect infospace stale-mappings
+```
+
+Compares local mapping references against the discipline's current entity
+set. If a referenced discipline entity has been removed, the mapping is
+flagged as stale.
+
+### Key functions
+
+- `resolve_discipline_path(binding, root)` — resolve to absolute path
+- `load_discipline_config(binding, root)` — load discipline's `infospace.yaml`
+- `check_discipline_status(binding, root)` — full status with viability
+- `get_discipline_entities(binding, root)` — entity list from discipline
+- `find_stale_mappings(config, root, mapping_references)` — detect stale refs
+- `bind_discipline(config, name, path, root)` — add binding to config
+
+---
+
+## Evaluation Output Format
+
+Evaluation results use YAML frontmatter + markdown body. Defined in
+`markitect/infospace/evaluation.py` and `evaluation_io.py`.
+
+### Per-entity evaluation file
+
+```markdown
+---
+entity_slug: division-of-labour
+evaluator: openrouter/default
+evaluated_at: '2026-02-19T10:30:00'
+overall_score: 4.1667
+scores:
+- name: definition_precision
+  value: 4.5
+  max_value: 5.0
+...
+---
+
+# Evaluation: Division Of Labour
+
+## definition_precision — 4.5 / 5.0
+
+The definition clearly captures the core concept...
+```
+
+### Snapshot
+
+```yaml
+snapshot_id: abc12345
+created_at: '2026-02-19T10:30:00+00:00'
+schema_name: default
+entity_count: 85
+entity_evaluations: [...]
+collection_metrics:
+  - name: coverage_ratio
+    value: 0.75
+    concern: C2
+```
+
+---
+
+## State
+
+Runtime state is computed from entities, evaluations, and metrics.
+Defined in `markitect/infospace/state.py`.
+
+```python
+from markitect.infospace import build_state
+state = build_state(config, entities=entities, metrics=metrics)
+state.is_viable          # True if all thresholds pass
+state.viability_results  # List[ViabilityResult]
+state.summary()          # Dict for display
+```
+
+---
+
+## CLI Command Summary
+
+All commands are under `markitect infospace`:
+
+| Command | Purpose |
+|---------|---------|
+| `init` | Create a new `infospace.yaml` |
+| `status` | Show entity count, domains, evaluation state |
+| `entities` | List entities with metadata |
+| `evaluate` | Run per-entity LLM evaluation |
+| `check` | Run collection-level quality checks (C1-C5) |
+| `viability` | Show viability dashboard |
+| `history` | Show metrics history |
+| `history-diff` | Compare two snapshots by date |
+| `bind-discipline` | Bind an external infospace as a discipline |
+| `disciplines` | List bound disciplines and viability |
+| `stale-mappings` | Detect stale cross-infospace references |
+
+---
+
+## Platform Dependencies
+
+The infospace tooling builds on these platform modules:
+
+| Module | Used for |
+|--------|----------|
+| `markitect/llm/` | Embedding adapters, LLM evaluation |
+| `markitect/analysis/graph.py` | Graph analysis (networkx wrapper) |
+| `markitect/analysis/fca.py` | Formal Concept Analysis |
+| `markitect/prompts/execution/batch.py` | Batch LLM evaluation |
+| `markitect/prompts/dependencies/models.py` | DependencyGraph |

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/successor-gap-assessment.md

@@ -0,0 +1,141 @@
+# markitect-main → Successor Repos: Gap Assessment
+
+**Date:** 2026-05-23
+**Author:** Claude (custodian session)
+**Status:** Draft — awaiting Bernd's decisions on items A/B/C below
+
+## Purpose
+
+Bernd is retiring `markitect-main` and has transferred most functionality to
+sibling repos. This document identifies what was provided by `markitect-main`
+that is **not addressed** in those successors, and flags candidates that may
+not fit any successor's intent.
+
+## Successor Ecosystem (5 repos, not 3)
+
+| Repo | Role |
+|---|---|
+| `markitect-tool` | Markdown syntax layer + structured-document primitives; defines source-adapter and render-adapter contracts. CLI: `mkt`. |
+| `kontextual-engine` | Headless knowledge operations engine: artifacts, collections, persistence, relationships, workflow runs/manifests, query, quality/assessment, API. |
+| `infospace-bench` | Application layer — concrete infospaces, evaluation methodology, reference pilots. |
+| `markitect-filter` | Source-format ingestion adapters (`source.epub3`, `source.pdf`) implementing the markitect-tool source-adapter contract. |
+| `markitect-quarkdown` | Render/export adapter — implements the markitect-tool render-adapter contract via Quarkdown. |
+
+## Method
+
+Analysis is grounded in each successor's own assessment docs (recent, May 2026):
+
+- `markitect-tool/docs/markitect-main-scope-assessment.md`
+- `kontextual-engine/docs/markitect-main-scope-assessment.md`
+- `kontextual-engine/docs/system-layer-extraction-inventory.md`
+- `kontextual-engine/docs/system-layer-migration-backlog.md`
+- `infospace-bench/docs/markitect-main-scope-assessment.md`
+- `infospace-bench/docs/legacy-infospace-feature-inventory.md`
+- `infospace-bench/docs/replacement-acceptance-matrix.md`
+
+Cross-checked against actual `markitect-main` module sizing (Python LOC) and
+`__init__.py` docstrings.
+
+**Confidence:** These successor docs are authoritative on *intent*. They have
+**not** been line-verified to confirm every "reimplement"-classified item
+actually landed in the successor. Where verification matters, it's flagged.
+
+---
+
+## A. Doesn't fit any successor's intent — needs a new home or explicit retirement
+
+These are explicitly pushed away by tool/engine/bench and are unrelated to
+filter/quarkdown.
+
+| markitect-main area | LOC | What it is | Status |
+|---|---|---|---|
+| `markitect/finance/` | ~8,100 | Cost-tracking system: cost items, period allocation to issues, financial reports, audit trails | **Orphan.** markitect-main's own SCOPE.md lists "financial transactions" as out-of-scope. Belongs with issue/project-ops, not knowledge tooling. |
+| `issue_tracker/` + `_issue-tracking/` + `.issues/` | ~1,200 | Issue tracking (finance allocates costs to these issues) | **Orphan to the five** — but likely already superseded by the `issue-facade` capability / `use-issues` skill. **Verify before retiring.** |
+| `markitect/profile/` | ~1,600 | User-profile CRUD, multi-profile, DB-backed | **Orphan.** Unrelated to all five. (Distinct from quarkdown's *render* "profile".) |
+| `markitect/production/` | ~3,800 | Deployment-readiness validation, cross-platform checks, perf benchmarking | Engine keeps only "structured error/audit *ideas*". Deployment-validation bulk is orphan. |
+| `tools/`, `services/`, gitea/tddai glue | ~5,500 | Project-ops tooling | Out-of-scope everywhere. |
+| `markitect/legacy/` + `legacy_compat.py` | ~2,700 | Backward-compat shims | Retire by definition. |
+
+## B. Rendering / asset / plugin layer — only *partially* covered, real residual gap
+
+**This is the most consequential gap.** `SCOPE.md` lists "Rendering: markdown
+→ interactive HTML via plugin system (testdrive-jsui)" as an in-scope
+capability of markitect-main.
+
+| Area | LOC | Covered? |
+|---|---|---|
+| `markitect/plugins/` (generic processor/formatter/validator/exporter plugin system) | ~8,000 | **No.** tool defines a render-adapter *contract* and an *extension* point, but the general plugin runtime isn't carried. |
+| `markitect/assets/` (content-addressable asset store, dedup, `.mdpkg` ZIP packaging, symlink handling) + `asset_registry.json` (277 KB) | ~6,000 | **No.** Bench says "leave behind unless a concrete export needs assets." |
+| Interactive-HTML / testdrive-jsui rendering, `static/`, `themes/`, `templates/document.html`, JS UI | — | **Partial only.** quarkdown covers a *Quarkdown* export path; the interactive-HTML / JS-UI path has no home. |
+
+**Decision needed:** spin these into a dedicated render/asset repo (sibling to
+quarkdown), fold the asset store into one of the existing repos, or retire the
+interactive-HTML path.
+
+## C. The other "Information Space" lineage — `markitect/spaces/` (~11,000 LOC)
+
+**Distinct from `markitect/infospace/`** (which infospace-bench inherited).
+`spaces/` is an older/parallel abstraction with features bench did *not* take:
+
+- event-driven change tracking & notifications
+- persistent transclusion context with cross-space references
+- bidirectional directory synchronization
+- HTML rendering of spaces with caching/themes
+
+Engine takes generic persistence concepts and bench takes infospace semantics,
+but **these specific `spaces/` behaviors (bidirectional sync, event
+notifications, cross-space transclusion context) aren't mapped anywhere.**
+
+Likely intended as dead/superseded — but 11k LOC warrants an explicit "retire
+vs salvage" call.
+
+## D. Declined-by-design (confirm retirement, don't re-extract)
+
+| Area | LOC | Disposition |
+|---|---|---|
+| `markitect/graphql/` | ~4,000 | All three explicitly declined GraphQL ("evidence of API need, not a commitment"). |
+| `markitect/query_paradigms/` | ~3,500 | Engine/tool keep the *QueryResult envelope* concept but say "do not port the registry wholesale." |
+| `markitect/proxy/` | ~870 | Non-markdown→md proxy with checksum/freshness tracking. **Overlaps markitect-filter.** Freshness/staleness-tracking mechanism may be worth checking against bench's deferred "stale-mappings." |
+| `capabilities/` (top-level) | ~8,300 | Capability-packaging architecture; partially maps to tool (schema generation) but the packaging approach itself isn't carried. |
+
+---
+
+## What this means
+
+The successors are, by their own assessments, **near complete for the
+in-scope core** (parsing/schema → tool; persistence/workflow → engine;
+infospace lifecycle → bench; ingestion → filter; one render path →
+quarkdown). The truly unaddressed functionality is almost entirely the stuff
+markitect-main accreted **beyond** its stated scope: finance, issue tracking,
+user profiles, production/deployment validation, the asset/plugin/interactive-HTML
+rendering stack, and the older `spaces/` abstraction.
+
+## Decisions for Bernd
+
+Three live decisions, not a long extraction backlog:
+
+### Decision 1 — Render/asset stack (Section B)
+The one with genuine product value left.
+- **Option 1a:** new repo (sibling to quarkdown) for plugin runtime + asset store + interactive-HTML
+- **Option 1b:** fold the asset store into an existing repo (most likely markitect-tool, behind a flag); retire interactive-HTML
+- **Option 1c:** retire the interactive-HTML path entirely; trust quarkdown export as the single render story
+
+### Decision 2 — `markitect/spaces/` (Section C)
+- **Option 2a:** salvage bidirectional-sync / event-tracking / cross-space transclusion into engine (engine has the persistence story to support it)
+- **Option 2b:** retire wholesale as superseded by infospace
+
+### Decision 3 — Project-ops cluster (Section A: finance + issues + profile)
+- **Option 3a:** confirm `issue-facade` already replaces `issue_tracker/` + `finance/`; retire both
+- **Option 3b:** identify a home for any pieces worth keeping
+
+---
+
+## Suggested verification before deciding
+
+If verification matters before committing:
+
+- **For Decision 1:** grep the five repos for any render/asset adapter that already covers the HTML path beyond Quarkdown.
+- **For Decision 2:** check whether engine's `OperationRun` + collection model can express bidirectional-sync semantics, or whether new primitives would be needed.
+- **For Decision 3:** confirm whether `issue-facade` truly replaces `issue_tracker/` + `finance/` end-to-end.
+
+Happy to do any of these focused passes when you're ready to decide.

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*