chore: cleanup of history file

history/260105-schema-of-schemas/SCHEMA_MANAGEMENT_SUMMARY.md

@@ -0,0 +1,154 @@
+# Schema Management: Executive Summary
+
+**TL;DR:** Implement naming conventions, versioning, and markdown-first schema format to solve current schema management issues.
+
+## Problems Identified
+
+1. **Inconsistent Naming** - Mix of `schema.json` suffix and no suffix
+2. **No Versioning** - Can't track schema evolution or maintain multiple versions
+3. **Duplicate Schemas** - 3 manpage schemas with similar content
+4. **Format Mismatch** - JSON schemas in markdown-centric tool
+
+## Recommended Solution
+
+### 1. Naming Convention (Immediate)
+
+**Format:** `{domain}-schema-v{major}.{minor}.json` or `.md`
+
+**Examples:**
+```
+manpage-schema-v1.0.json
+terminology-schema-v1.0.json
+api-documentation-schema-v1.0.json
+```
+
+**Migration:**
+```
+markdown-manpage → manpage-schema-v1.0.json
+enhanced-manpage → manpage-schema-v2.0.json (breaking changes)
+terminology-schema.json → terminology-schema-v1.0.json
+```
+
+### 2. Markdown-First Format (Short-term)
+
+**Proposal:** Store schemas as markdown files with embedded JSON
+
+**Benefits:**
+- Aligns with markdown philosophy ✅
+- Rich documentation alongside schema ✅
+- Version history in same file ✅
+- Examples and usage inline ✅
+- Lower barrier to entry ✅
+
+**Example:** See `examples/schemas/manpage-schema-v1.md`
+
+**Format:**
+```markdown
+# Schema Title v1.0
+
+## Documentation sections...
+
+## Schema Definition
+
+\`\`\`json
+{ schema here }
+\`\`\`
+```
+
+### 3. Schema Metadata Standard (Immediate)
+
+**Required fields:**
+```json
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://markitect.dev/schemas/{domain}/v{major}",
+  "version": "1.0.0",
+  "title": "Human Readable Title",
+  "description": "Detailed description",
+  "x-markitect-metadata": {
+    "domain": "manpage",
+    "document-types": ["manual-page"],
+    "created": "2026-01-04",
+    "example": "examples/manpages/example.md"
+  }
+}
+```
+
+## Implementation Phases
+
+### Phase 1: Foundation (1-2 days)
+- [x] Analyze current state
+- [ ] Define naming convention spec
+- [ ] Create schema metadata template
+- [ ] Rename existing schemas
+- [ ] Update schema-catalog.yaml
+
+### Phase 2: Markdown Format (3-5 days)
+- [ ] Design markdown schema format
+- [ ] Implement parser (extract JSON from markdown)
+- [ ] Convert 1 schema as proof-of-concept
+- [ ] Test and iterate
+- [ ] Migrate all schemas
+
+### Phase 3: Tooling (2-3 days)
+- [ ] Update CLI to support .md schemas
+- [ ] Add schema validation command
+- [ ] Create migration guide
+- [ ] Update documentation
+
+## Cost-Benefit Analysis
+
+**Cost:** 6-10 days total effort
+
+**Benefits:**
+- Professional schema management ⭐⭐⭐⭐⭐
+- Better discoverability ⭐⭐⭐⭐
+- Easier maintenance ⭐⭐⭐⭐⭐
+- Markdown alignment ⭐⭐⭐⭐⭐
+- Version tracking ⭐⭐⭐⭐⭐
+
+**ROI:** High - Foundational improvement that benefits all future schema work
+
+## Alternative Considered
+
+**Alternative:** Keep JSON, generate markdown docs automatically
+
+**Pros:**
+- Simpler implementation (2-3 days)
+- JSON remains source of truth
+- Standard tooling works
+
+**Cons:**
+- Doesn't solve format mismatch
+- Documentation generated, not authored
+- Two files to manage
+
+**Verdict:** Markdown-first better aligns with project philosophy
+
+## Quick Wins (Today)
+
+1. **Rename schemas** with versioned names (30 minutes)
+2. **Add metadata** to existing schemas (1 hour)
+3. **Update catalog** with proper versioning (30 minutes)
+
+## Questions to Resolve
+
+1. **File extension:** `.md` or `.schema.md` for markdown schemas?
+2. **JSON extraction:** Real-time or pre-compiled cache?
+3. **Backward compatibility:** Support both formats during transition?
+4. **CLI changes:** `--schema file.md` or auto-detect format?
+
+## Next Steps
+
+1. **Review** this proposal and example (examples/schemas/manpage-schema-v1.md)
+2. **Decide** on markdown-first vs generated docs approach
+3. **Prototype** parser for markdown schemas
+4. **Migrate** one schema as proof-of-concept
+5. **Iterate** based on feedback
+6. **Full rollout** to all schemas
+
+## References
+
+- Full proposal: [SCHEMA_MANAGEMENT_PROPOSAL.md](./SCHEMA_MANAGEMENT_PROPOSAL.md)
+- Example markdown schema: [examples/schemas/manpage-schema-v1.md](../../examples/schemas/manpage-schema-v1.md)
+- Current schema catalog: [markitect/schemas/schema-catalog.yaml](../../markitect/schemas/schema-catalog.yaml)