Phase 3 Conversion Plan: Complete 158-File Documentation
Date: 2025-01-17 Workspace:/Users/macbook/Projects/monolex/monolex-docs-draft
Source: /Users/macbook/Projects/monolex/monolex/.claude/skills/monolex-architect/docs/
Executive Summary
┌─────────────────────────────────────────────────────────────────┐
│ FULL 158-FILE PHASE 3 CONVERSION │
├─────────────────────────────────────────────────────────────────┤
│ │
│ Phase 2 Source: 158 files (internal technical docs) │
│ Already Converted: 56 files (35% complete) │
│ Remaining: 102 files │
│ │
│ Target: 100% conversion for credibility & consistency │
│ │
│ Quality Standard: │
│ ├── 30% text, 70% ASCII diagrams │
│ ├── Grandmother test (non-developer readable) │
│ ├── GLOSSARY.md term selection (⭐ ratings) │
│ └── Logic-focused, not code-focused │
│ │
└─────────────────────────────────────────────────────────────────┘
Current Progress Analysis
Already Converted (56 files)
| Category | Files | Status |
|---|---|---|
| Root (intro, quickstart, install) | 3 | ✅ Complete |
| architecture/ | 6 | ✅ Complete |
| terminal/ | 7 | ✅ Complete |
| philosophy/ | 4 | ✅ Complete |
| transparency/core/ | 4 | ✅ Complete |
| transparency/git-viewers/ | 8 | ✅ Complete |
| transparency/extension/ | 2 | ✅ Complete |
| transparency/wiki-viewers/ | 5 | ✅ Complete |
| transparency/git-backend/ | 3 | ✅ Complete |
| transparency/commit-graph/ | 2 | ✅ Complete |
| transparency/file-watcher/ | 2 | ✅ Complete |
| guides/ | 3 | ✅ Complete |
| daemons/ | 2 | ✅ Complete |
| database/ | 1 | ✅ Partial |
| features/ | 1 | ✅ Complete |
| research/ | 3 | ✅ Complete |
Remaining to Convert (102 files)
┌─────────────────────────────────────────────────────────────────┐
│ REMAINING CONVERSION BY CATEGORY │
├─────────────────────────────────────────────────────────────────┤
│ │
│ atomic-architecture/ 9 files → architecture/ │
│ ├── 01-overview.md (may overlap with existing) │
│ ├── 02-component-architecture.md │
│ ├── 03-ack-gate-flow-control.md │
│ ├── 04-epoch-synchronization.md │
│ ├── 05-xterm-as-renderer.md │
│ ├── 06-backend-rendering-patterns.md │
│ ├── 07-simulation-vs-presentation.md │
│ ├── 08-dirty-tracking-strategies.md │
│ └── README.md │
│ │
│ atomic-state/ 9 files → terminal/atomic-state/ │
│ ├── 01-overview.md │
│ ├── 01-what-is-atomic-state.md │
│ ├── 02-data-flow.md │
│ ├── 02-how-it-works.md │
│ ├── 03-buffer-model.md │
│ ├── 03-performance-benefits.md │
│ ├── 04-diff-rendering.md │
│ ├── 04-troubleshooting.md │
│ └── README.md │
│ │
│ components/ 18 files → components/ │
│ ├── ch1-pty-daemon.md │
│ ├── ch3-pty-log.md │
│ ├── ch4-atomic-term-ime.md (→ features/ime) │
│ ├── ch5-niia-watcher.md (→ daemons/) │
│ ├── ch6-variable-md.md │
│ ├── ch7-database-architecture.md (→ database/) │
│ ├── ch8-complex-relations.md │
│ ├── ch9-file-db-mapping.md │
│ ├── ch10-work-wiki-diff.md │
│ ├── ch11-module-db-graph.md │
│ ├── ch12-unified-connection-map.md │
│ ├── ch13-terminal-scrollbar.md │
│ ├── ch19-design-patterns.md │
│ └── db-*.md (5 files) (→ database/) │
│ │
│ monokinetics-concurrency/ 5 files → philosophy/concurrency/ │
│ ├── monokinetics-concurrency-philosophy.md │
│ ├── 00-five-pattern-synergy.md │
│ ├── 01-actor-over-mutex.md │
│ ├── 02-actor-ack-synergy.md │
│ └── 03-atomicstate-absorber.md │
│ │
│ monoterm-guide/ 13 files → terminal/ & philosophy/ │
│ ├── 01-what-is-monoterm.md (already in intro?) │
│ ├── 02-atomic-loop.md (already converted) │
│ ├── 03-bsu-esu.md (already converted) │
│ ├── 04-data-reduction.md (already converted) │
│ ├── 05-monokinetics.md (already converted) │
│ ├── 06-monokinetic-hermeneutics.md (already converted) │
│ ├── 07-monokinetics-and-monolex.md │
│ ├── 08-monokinetics-and-monoterm.md │
│ ├── 09-cursor-pattern-pseudo-bsu.md │
│ ├── 09-monokinetics-concurrency.md │
│ ├── 10-ai-cli-framework-pairing.md │
│ ├── 11-monoterm-compatibility-matrix.md │
│ └── README.md │
│ │
│ niia-consciousness/ 42 files → research/consciousness/ │
│ ├── chapter-40-60 (21 files) │
│ ├── prove/ (16+ files) │
│ ├── THREAD-H-SUMMARY.md │
│ └── README.md │
│ │
│ ux-ai-native/ 9 files → research/ai-native/ │
│ ├── 50-STEP-ANALYSIS-PLAN.md │
│ ├── 56-SOURCE-CODE-DEEP-ANALYSIS.md │
│ ├── 59-NEW-PROBLEM-CATEGORY.md │
│ ├── 60-TWO-SCENARIOS-GAME-ANALOGY.md │
│ ├── 61-AI-NATIVE-TERMINAL-DIAGRAMS.md │
│ ├── 62-AI-NATIVE-TERMINAL-GIANTS-QUOTE.md │
│ ├── 63-AI-NATIVE-TERMINAL-ARCHITECTURE-SUCCESS-FACTORS.md │
│ ├── 64-AI-NATIVE-TERMINAL-PRIOR-ART.md │
│ └── README.md (already converted) │
│ │
│ architecture-docs/ 2 files → architecture/ │
│ ├── 02-data-flow.md │
│ └── ARCHITECTURE-VERSION.md │
│ │
│ Root files 3 files → (meta/index) │
│ ├── README.md │
│ ├── CLASSIFICATION-MAP.md │
│ └── RESTRUCTURE-MAPPING.md │
│ │
└─────────────────────────────────────────────────────────────────┘
Target Directory Structure
monolex-docs-draft/
├── introduction.mdx ✅
├── quickstart.mdx ✅
├── installation.mdx ✅
│
├── guides/ ✅ Complete
│ ├── smooth-rendering.mdx
│ ├── why-fast.mdx
│ └── troubleshooting.mdx
│
├── philosophy/ 🔄 Add concurrency
│ ├── monokinetics.mdx ✅
│ ├── monokinetic-hermeneutics.mdx ✅
│ ├── why-terminal.mdx ✅
│ ├── atomic-ux.mdx ✅
│ └── concurrency/ ❌ NEW
│ ├── overview.mdx
│ ├── five-patterns.mdx
│ ├── actor-model.mdx
│ └── ack-synergy.mdx
│
├── architecture/ 🔄 Add deep dives
│ ├── overview.mdx ✅
│ ├── philosophy-to-code.mdx ✅
│ ├── session-actor.mdx ✅
│ ├── 5-tier-grid-mode.mdx ✅
│ ├── alacritty-xterm.mdx ✅
│ ├── concurrency-patterns.mdx ✅
│ └── deep-dive/ ❌ NEW
│ ├── component-architecture.mdx
│ ├── ack-gate-flow.mdx
│ ├── epoch-sync.mdx
│ ├── xterm-renderer.mdx
│ ├── backend-patterns.mdx
│ ├── simulation-vs-presentation.mdx
│ └── dirty-tracking.mdx
│
├── terminal/ 🔄 Add atomic-state deep
│ ├── pty-daemon.mdx ✅
│ ├── alacritty-renderer.mdx ✅
│ ├── atomic-loop.mdx ✅
│ ├── bsu-esu-protocol.mdx ✅
│ ├── atomic-state.mdx ✅
│ ├── data-reduction.mdx ✅
│ ├── grid-system.mdx ✅
│ └── atomic-state/ ❌ NEW (deep dive)
│ ├── how-it-works.mdx
│ ├── buffer-model.mdx
│ ├── performance.mdx
│ ├── diff-rendering.mdx
│ └── troubleshooting.mdx
│
├── components/ ❌ NEW
│ ├── overview.mdx
│ ├── pty-log.mdx
│ ├── variable-md.mdx
│ ├── terminal-scrollbar.mdx
│ └── design-patterns.mdx
│
├── database/ 🔄 Expand
│ ├── overview.mdx ✅
│ ├── architecture.mdx ❌ NEW
│ ├── schemas/ ❌ NEW
│ │ ├── atomic-term.mdx
│ │ ├── session.mdx
│ │ ├── onit.mdx
│ │ ├── niia-watcher.mdx
│ │ └── work-wiki-diff.mdx
│ ├── complex-relations.mdx ❌ NEW
│ ├── file-mapping.mdx ❌ NEW
│ ├── work-wiki-diff.mdx ❌ NEW
│ └── module-graph.mdx ❌ NEW
│
├── transparency/ ✅ Mostly complete
│ ├── core/ ✅
│ ├── git-viewers/ ✅
│ ├── extension/ ✅
│ ├── wiki-viewers/ ✅
│ ├── git-backend/ ✅
│ ├── commit-graph/ ✅
│ └── file-watcher/ ✅
│
├── features/ 🔄 Expand
│ ├── ime-cjk-support.mdx ✅
│ ├── ai-cli-pairing.mdx ❌ NEW
│ └── compatibility.mdx ❌ NEW
│
├── daemons/ 🔄 Expand
│ ├── overview.mdx ✅
│ └── niia-watcher.mdx ✅
│
└── research/ 🔄 Major expansion
├── ai-native-terminal.mdx ✅
├── uniqueness-proof.mdx ✅
├── qed-proofs.mdx ✅
├── ai-native/ ❌ NEW (8 files)
│ ├── analysis-plan.mdx
│ ├── source-analysis.mdx
│ ├── problem-category.mdx
│ ├── game-analogy.mdx
│ ├── diagrams.mdx
│ ├── giants-quote.mdx
│ ├── success-factors.mdx
│ └── prior-art.mdx
└── consciousness/ ❌ NEW (condensed)
├── overview.mdx
├── archive-analysis.mdx
├── evolution-patterns.mdx
└── qed-verification.mdx
GLOSSARY.md Term Selection
┌─────────────────────────────────────────────────────────────────┐
│ TERM SELECTION BY SEO/CREDIBILITY VALUE │
├─────────────────────────────────────────────────────────────────┤
│ │
│ ⭐⭐⭐⭐⭐ ALWAYS USE (High SEO + Credibility): │
│ Rust, GPU Acceleration, WebGL, Tauri │
│ │
│ ⭐⭐⭐⭐ FREQUENTLY USE: │
│ Alacritty, VTE, MPSC, Actor Model, PTY │
│ │
│ ⭐⭐⭐ USE WHEN RELEVANT: │
│ BSU/ESU, ACK, ANSI, xterm.js │
│ │
│ ⭐⭐ USE FOR DEPTH: │
│ SessionActor, DiffHint, GridWorker, AtomicState │
│ │
│ ⭐ BRAND BUILDING: │
│ Monokinetics, SMPC, OFAC, Atomic UX │
│ │
│ ❌ REMOVE (Implementation details): │
│ cache, buffer, CachedLine, feed(bytes), hash │
│ File paths, line numbers, internal variable names │
│ │
└─────────────────────────────────────────────────────────────────┘
Conversion Strategy
Phase 3 Rules (from monolex-docs-maker)
┌─────────────────────────────────────────────────────────────────┐
│ PHASE 3 TRANSFORMATION RULES │
├─────────────────────────────────────────────────────────────────┤
│ │
│ TEXT TO DIAGRAM RATIO: │
│ ├── Phase 2: 50% text, 50% diagrams │
│ └── Phase 3: 30% text, 70% diagrams │
│ │
│ CONTENT TRANSFORMATION: │
│ ├── Implementation details → Logic diagrams │
│ ├── Code snippets → Flowcharts │
│ ├── file:line refs → Removed │
│ └── Tech terms → Per GLOSSARY.md ratings │
│ │
│ AUDIENCE TEST: │
│ └── "Would my grandmother understand this?" │
│ │
└─────────────────────────────────────────────────────────────────┘
Batch Execution Plan
┌─────────────────────────────────────────────────────────────────┐
│ EXECUTION BATCHES (7 parallel threads) │
├─────────────────────────────────────────────────────────────────┤
│ │
│ Batch A: architecture/deep-dive/ (7 files) │
│ ├── Source: atomic-architecture/ │
│ └── Convert: 02-08.md → deep-dive/*.mdx │
│ │
│ Batch B: terminal/atomic-state/ (5 files) │
│ ├── Source: atomic-state/ │
│ └── Convert: selected deep dives │
│ │
│ Batch C: philosophy/concurrency/ (4 files) │
│ ├── Source: monokinetics-concurrency/ │
│ └── Convert: all 5 → 4 condensed │
│ │
│ Batch D: components/ (5 files) │
│ ├── Source: components/ch*.md (selected) │
│ └── Convert: user-relevant components │
│ │
│ Batch E: database/ (8 files) │
│ ├── Source: components/ch7-12, db-*.md │
│ └── Convert: architecture + schemas │
│ │
│ Batch F: research/ai-native/ (8 files) │
│ ├── Source: ux-ai-native/50-64 │
│ └── Convert: all analysis documents │
│ │
│ Batch G: research/consciousness/ (4 files) │
│ ├── Source: niia-consciousness/ (42 files) │
│ └── Convert: condensed overview + key findings │
│ │
│ TOTAL NEW FILES: ~41 files │
│ FINAL COUNT: 56 existing + 41 new = 97 files │
│ │
│ Note: 158 → 97 through consolidation │
│ (niia-consciousness 42 → 4, some merges) │
│ │
└─────────────────────────────────────────────────────────────────┘
docs.json Navigation Update
{
"navigation": {
"groups": [
{
"group": "Get Started",
"pages": ["introduction", "quickstart", "installation"]
},
{
"group": "User Guide",
"pages": [
"guides/smooth-rendering",
"guides/why-fast",
"guides/troubleshooting"
]
},
{
"group": "Philosophy",
"pages": [
"philosophy/monokinetics",
"philosophy/monokinetic-hermeneutics",
"philosophy/why-terminal",
"philosophy/atomic-ux",
{
"group": "Concurrency Philosophy",
"pages": [
"philosophy/concurrency/overview",
"philosophy/concurrency/five-patterns",
"philosophy/concurrency/actor-model",
"philosophy/concurrency/ack-synergy"
]
}
]
},
{
"group": "Architecture",
"pages": [
"architecture/overview",
"architecture/philosophy-to-code",
"architecture/session-actor",
"architecture/5-tier-grid-mode",
"architecture/alacritty-xterm",
"architecture/concurrency-patterns",
{
"group": "Deep Dive",
"pages": [
"architecture/deep-dive/component-architecture",
"architecture/deep-dive/ack-gate-flow",
"architecture/deep-dive/epoch-sync",
"architecture/deep-dive/xterm-renderer",
"architecture/deep-dive/backend-patterns",
"architecture/deep-dive/simulation-vs-presentation",
"architecture/deep-dive/dirty-tracking"
]
}
]
},
{
"group": "Terminal Core",
"pages": [
"terminal/pty-daemon",
"terminal/alacritty-renderer",
"terminal/atomic-loop",
"terminal/bsu-esu-protocol",
"terminal/atomic-state",
"terminal/data-reduction",
"terminal/grid-system",
{
"group": "AtomicState Deep Dive",
"pages": [
"terminal/atomic-state/how-it-works",
"terminal/atomic-state/buffer-model",
"terminal/atomic-state/performance",
"terminal/atomic-state/diff-rendering",
"terminal/atomic-state/troubleshooting"
]
}
]
},
{
"group": "Components",
"pages": [
"components/overview",
"components/pty-log",
"components/variable-md",
"components/terminal-scrollbar",
"components/design-patterns"
]
},
{
"group": "Database",
"pages": [
"database/overview",
"database/architecture",
{
"group": "Schemas",
"pages": [
"database/schemas/atomic-term",
"database/schemas/session",
"database/schemas/onit",
"database/schemas/niia-watcher",
"database/schemas/work-wiki-diff"
]
},
"database/complex-relations",
"database/file-mapping",
"database/module-graph"
]
},
{
"group": "Transparency",
"pages": [/* existing structure */]
},
{
"group": "Features",
"pages": [
"features/ime-cjk-support",
"features/ai-cli-pairing",
"features/compatibility"
]
},
{
"group": "Daemons",
"pages": ["daemons/overview", "daemons/niia-watcher"]
},
{
"group": "Research",
"pages": [
"research/ai-native-terminal",
"research/uniqueness-proof",
"research/qed-proofs",
{
"group": "AI-Native Analysis",
"pages": [
"research/ai-native/analysis-plan",
"research/ai-native/source-analysis",
"research/ai-native/problem-category",
"research/ai-native/game-analogy",
"research/ai-native/diagrams",
"research/ai-native/giants-quote",
"research/ai-native/success-factors",
"research/ai-native/prior-art"
]
},
{
"group": "NIIA Consciousness",
"pages": [
"research/consciousness/overview",
"research/consciousness/archive-analysis",
"research/consciousness/evolution-patterns",
"research/consciousness/qed-verification"
]
}
]
}
]
}
}
Quality Checklist
┌─────────────────────────────────────────────────────────────────┐
│ PHASE 3 QUALITY CHECKLIST (per file) │
├─────────────────────────────────────────────────────────────────┤
│ │
│ Content Transformation: │
│ □ No implementation details (cache, buffer, hash) │
│ □ No file paths or line numbers │
│ □ No code snippets (except user commands) │
│ □ Tech terms per GLOSSARY.md ratings │
│ │
│ Visual Requirements: │
│ □ ASCII art ratio: ~70% of content │
│ □ Diagrams are self-explanatory │
│ □ Every section has at least one diagram │
│ │
│ Audience Test: │
│ □ Grandmother test passed │
│ □ Text is minimal and supports diagrams │
│ □ Technical depth conveyed through terms, not code │
│ │
│ SEO & Credibility: │
│ □ ⭐⭐⭐⭐⭐ terms present (Rust, GPU, WebGL, Tauri) │
│ □ ⭐⭐⭐⭐ terms used appropriately │
│ □ Brand terms introduced naturally │
│ │
└─────────────────────────────────────────────────────────────────┘
Execution Summary
| Metric | Count |
|---|---|
| Phase 2 Source Files | 158 |
| Already Converted | 56 |
| New Files to Create | 41 |
| Final Phase 3 Files | 97 |
| Consolidation Ratio | 158 → 97 (39% reduction) |
Last Updated: 2025-01-17