Update documentation to reflect Go CLI approach and ID generation philosophy

- Rewrite README.md: Focus on Go CLI, container expansion, zero-config philosophy - Add comprehensive ID generation strategy to RESEARCH.md - Document two-phase approach: disposable dev IDs vs stable production mappings - Explain edge cases, migration tools, and developer workflow - Position as 'Tailwind of CMS' with build-time enhancement approach
2025-09-03 12:17:01 +02:00
parent 0e84af98bc
commit c2591e4fdd
2 changed files with 329 additions and 144 deletions
--- a/RESEARCH.md
+++ b/RESEARCH.md
@@ -433,6 +433,137 @@ CREATE TABLE content (

 ---

+## Content ID Generation Strategy
+
+### Philosophy: Zero Configuration with Pragmatic Stability
+
+**Core Principle**: Developers should never think about content IDs unless they choose to.
+
+#### Two-Phase Approach
+
+**Development Phase (Pre-Production):**
+- IDs are **completely disposable** and can change freely
+- Generated using: `context-tag-hash` (e.g., `hero-h1-abc123ef`)
+- Developers focus purely on markup: `<h1 class="insertr">Title</h1>`
+- Only use HTML `id` attributes for complex stability requirements
+
+**Production Phase (Post-Launch):**
+- Preserve existing content mappings for stability
+- CLI detects structural changes and warns about orphaned content
+- Simple migration prompts for major refactoring
+- Database tracks content lifecycle with "last seen" timestamps
+
+#### ID Generation Algorithm
+
+```go
+func generateContentID(element) string {
+    context := nearestContext(element)    // From HTML id or DOM position
+    tag := element.Tag                    // h1, p, button
+    hash := structureHash(element)[:8]    // Element structure, not content
+    
+    return fmt.Sprintf("%s-%s-%s", context, tag, hash)
+}
+```
+
+**Context Resolution Priority:**
+1. Nearest parent with HTML `id` attribute
+2. Semantic section detection (header, main, aside, etc.)
+3. DOM position fallback (section-0, div-1, etc.)
+
+#### Edge Cases and Solutions
+
+**1. Content Lifecycle Issues**
+- **Orphaned Content**: Content exists in DB but element removed from HTML
+  - *Solution*: CLI warns + provides cleanup commands
+  - *Example*: `⚠️ Content 'hero-title-abc123' no longer found (last seen: 2024-09-01)`
+
+- **Content Drift**: Element text changes, breaking content-dependent IDs  
+  - *Solution*: IDs based on structure, not content text
+  - *Example*: `<h1>Welcome</h1>` → `<h1>About Us</h1>` keeps same ID
+
+- **Duplicate Resolution**: Multiple elements generate same ID pattern
+  - *Solution*: Collision detection with incremental suffixes
+  - *Example*: `hero-h1-abc123`, `hero-h1-def456`
+
+**2. Structural Changes**
+- **Element Movement**: Same content, different DOM position
+  - *Solution*: HTML `id` attributes provide stability anchors
+  - *Example*: Moving `<h1>` between sections preserves ID if parent has `id`
+
+- **Container Refactoring**: Switching between container vs individual `insertr` classes
+  - *Solution*: Parser detects structural changes and suggests migrations
+  - *Example*: `div.insertr` → individual child elements get mapped IDs
+
+- **Framework Migrations**: Moving between SSGs changes HTML structure
+  - *Solution*: HTML `id` attributes survive framework changes
+  - *Content mapping*: Based on semantic meaning, not framework output
+
+**3. Development Workflow Issues**
+- **Branch Conflicts**: Multiple developers changing same elements
+  - *Solution*: Content stored separately from markup, no merge conflicts
+  - *Database approach*: Conflicts resolved at content level, not Git level
+
+- **Content Staging**: Handling content across dev/staging/prod environments
+  - *Solution*: Environment-aware content API with fallbacks
+  - *Workflow*: Dev content → Staging approval → Production deployment
+
+- **Reset Scenarios**: Starting fresh vs preserving existing content
+  - *Solution*: CLI provides reset/preserve options
+  - *Commands*: `insertr reset --preserve-content` vs `insertr reset --clean`
+
+#### Migration and Maintenance Tools
+
+**Content Mapping Detection**:
+```bash
+# Detect moved/renamed content with confidence scoring
+insertr detect-changes --previous content-registry.json
+
+⚠️  Potential content migrations detected:
+   hero-old-title → hero-main-title (95% confidence)
+   services-desc → about-story (12% confidence - manual review needed)
+
+# Accept suggested migrations
+insertr migrate hero-old-title hero-main-title
+
+# Cleanup orphaned content
+insertr cleanup --older-than 30d --confirm
+```
+
+**Developer Override System**:
+```html
+<!-- Explicit control when needed -->
+<section id="hero">
+  <h1 class="insertr">Title</h1>       <!-- Stable: hero-h1-* -->
+  <p class="insertr">Description</p>   <!-- Stable: hero-p-* -->
+</section>
+
+<!-- Complex case: manual ID override -->
+<h1 class="insertr" data-content-id="custom-stable-id">Special Case</h1>
+```
+
+#### Benefits of This Approach
+
+**For Development:**
+- Zero cognitive overhead for simple cases
+- HTML `id` attributes provide escape hatch for complex scenarios
+- Generated IDs invisible to developers in built output
+- Fast iteration without content persistence concerns
+
+**For Production:**
+- Stable content mappings preserve editorial work
+- Graceful handling of structural changes
+- Clear migration paths for major refactoring
+- Content lifecycle tracking prevents data loss
+
+**For Content Editors:**
+- Seamless editing experience regardless of ID complexity
+- Content preserved across site restructures
+- No exposure to technical ID management
+
+This approach maintains the "zero configuration" philosophy while providing pragmatic solutions for production stability and content preservation.
+
+---
+
 ## Strategic Recommendations

 ### 1. Market Positioning: "The Tailwind of CMS"