> ## Documentation Index > Fetch the complete documentation index at: https://docs.monolex.ai/llms.txt > Use this file to discover all available pages before exploring further. # Research Viewer & Frontmatter Parsing > ASURA research display, GitTab viewer management, and YAML frontmatter metadata extraction for AI-human documentation workflows ## Overview Monolex's Research Viewer displays multi-threaded ASURA research sessions, while GitTab manages 14 specialized Git visualization tools through dynamic imports. Frontmatter parsing extracts machine-readable metadata from human-authored documents, enabling automated processing and intelligent categorization. ``` ┌─────────────────────────────────────────────────────────────────┐ │ RESEARCH & METADATA ARCHITECTURE │ ├─────────────────────────────────────────────────────────────────┤ │ │ │ WikiResearchViewer │ │ ↓ Scan /research/{topic}/chapters/ │ │ ↓ Extract thread count (chapter-01-A-, chapter-02-B-) │ │ ↓ Detect FINAL-SYNTHESIS.md │ │ ↓ Determine status: synthesized > in-progress > archived │ │ │ │ GitTab Controller │ │ ↓ 14 viewer buttons registered │ │ ↓ Dynamic import from viewerMap │ │ ↓ Virtual path: {repo}/.git-dashboard │ │ ↓ Batch API: 5 calls → 1 (git_full_refresh) │ │ │ │ Frontmatter Parser │ │ ↓ Regex: /^---\n([\s\S]*?)\n---/ │ │ ↓ Split key:value pairs │ │ ↓ Handle colons in values (URLs, timestamps) │ │ ↓ Extract status field with defaults │ │ │ └─────────────────────────────────────────────────────────────────┘ ``` *** ## WikiResearchViewer: ASURA Display ### Research Folder Detection WikiResearchViewer identifies ASURA research sessions by analyzing folder structure: ``` research/{TOPIC-SLUG}/ ├── chapters/ │ ├── chapter-01-A-overview.md ← Thread A, Chapter 1 │ ├── chapter-02-A-architecture.md ← Thread A, Chapter 2 │ ├── chapter-03-B-implementation.md ← Thread B, Chapter 3 │ └── chapter-04-C-optimization.md ← Thread C, Chapter 4 ├── threads/ │ ├── 00-SHARED-CONTEXT.md │ ├── THREAD-A-INSTRUCTIONS.md │ └── THREAD-B-INSTRUCTIONS.md └── FINAL-SYNTHESIS.md ← Synthesis indicator ``` **Extracted Metadata**: * `threadCount`: 3 (unique letters A, B, C) * `chapterCount`: 4 (all chapter-N files) * `hasSynthesis`: true (FINAL-SYNTHESIS.md exists) * `status`: "synthesized" ### Thread Extraction Algorithm ``` ┌───────────────────────────────────────────────────────────────────────┐ │ THREAD EXTRACTION ALGORITHM │ ├───────────────────────────────────────────────────────────────────────┤ │ │ │ INPUT: List of files in research topic folder │ │ OUTPUT: { threads: Set, chapterCount: number, hasSynthesis: boolean }│ │ │ │ INITIALIZE: │ │ threads = new Set() // Unique thread letters │ │ chapterCount = 0 │ │ hasSynthesis = false │ │ │ │ FOR each file in contents: │ │ │ │ │ ├── SYNTHESIS CHECK: │ │ │ filename contains "synthesis" OR "final"? │ │ │ └── YES → hasSynthesis = true │ │ │ │ │ └── CHAPTER CHECK: │ │ filename matches /chapter-\d+/? │ │ ├── YES → chapterCount++ │ │ │ │ │ └── THREAD EXTRACTION: │ │ filename matches /chapter-\d+-([A-Z])-/? │ │ └── YES → threads.add(letter.toUpperCase()) │ │ │ │ RESULT: │ │ threadCount = threads.size │ │ chapterCount = (from loop) │ │ hasSynthesis = (from loop) │ │ │ └───────────────────────────────────────────────────────────────────────┘ ``` **Pattern**: `/chapter-\d+-([A-Z])-/` captures thread letter from filenames. ### Status Determination ``` ┌─────────────────────────────────────────────────────────────────┐ │ STATUS PRIORITY CHAIN │ ├─────────────────────────────────────────────────────────────────┤ │ │ │ hasSynthesis? │ │ │ │ │ ├── YES → "synthesized" (PRIORITY 1) │ │ │ │ │ └── NO → topicDoc.isWip? │ │ │ │ │ ├── TRUE → "in-progress" (DEFAULT) │ │ │ │ │ └── FALSE → "archived" (PRIORITY 2) │ │ │ └─────────────────────────────────────────────────────────────────┘ ``` **Logic**: 1. If `FINAL-SYNTHESIS.md` exists → `synthesized` 2. Else if not in `/wip/` directory → `archived` 3. Otherwise → `in-progress` *** ## GitTab: 14 Viewer Management ### Viewer Button Architecture GitTab manages 14 specialized Git viewers through dynamic imports and tab reuse: | Button | Viewer Type | Module Path | | ---------------------- | ---------------------- | ---------------------------------- | | git-dashboard-btn | git-dashboard | git/git-dashboard | | git-commit-search-btn | git-commit-search | misc/git-commit-search-viewer | | git-branch-diagram-btn | git-branch-diagram | misc/git-branch-diagram-viewer | | git-blame-btn | git-blame | git/git-blame-viewer | | git-diff-btn | git-diff | misc/git-diff-viewer | | git-heatmap-btn | git-heatmap | git/git-heatmap-viewer | | git-timeline-btn | git-operation-timeline | misc/git-operation-timeline-viewer | | git-reflog-btn | git-reflog | git/git-reflog-viewer | | git-stash-btn | git-stash | misc/git-stash-viewer | | git-remote-btn | git-remote-status | misc/git-remote-status-viewer | | git-ownership-btn | git-ownership | git/git-ownership-map | | git-impact-btn | git-impact | git/git-impact-analyzer | | git-merge-btn | git-merge-conflict | git/git-merge-conflict-viewer | | git-hunk-btn | git-hunk | git/git-hunk-viewer | ### Dynamic Import Pattern ``` ┌───────────────────────────────────────────────────────────────────────┐ │ DYNAMIC VIEWER IMPORT MECHANISM │ ├───────────────────────────────────────────────────────────────────────┤ │ │ │ viewerMap: Record │ │ │ │ ┌─────────────────────────────────────────────────────────────────┐ │ │ │ "git-dashboard" → import("../git/git-dashboard") │ │ │ │ "git-blame" → import("../git/git-blame-viewer") │ │ │ │ "git-diff" → import("../misc/git-diff-viewer") │ │ │ │ ... 11 more entries ... │ │ │ └─────────────────────────────────────────────────────────────────┘ │ │ │ │ importViewer(viewerType): │ │ 1. Look up importer function in viewerMap │ │ 2. If found: await importer() │ │ 3. Return viewer class (or null if not found) │ │ │ │ BENEFITS: │ │ ├── Lazy loading: viewers load only when opened │ │ ├── Code splitting: reduces initial bundle size │ │ └── Object lookup: O(1) viewer resolution │ │ │ └───────────────────────────────────────────────────────────────────────┘ ``` ### Virtual Path Tab Reuse ``` ┌───────────────────────────────────────────────────────────────────────┐ │ VIRTUAL PATH MECHANISM │ ├───────────────────────────────────────────────────────────────────────┤ │ │ │ CREATE VIRTUAL PATH: │ │ virtualPath = "{repoPath}/.{viewerType}" │ │ │ │ EXAMPLES: │ │ ~/your-project/.git-dashboard │ │ ~/your-project/.git-blame │ │ ~/your-project/.git-diff │ │ │ │ TAB REUSE: │ │ tabManager.openFileInTab(virtualPath, false) │ │ └── If tab with this path exists → reuse it │ │ └── If not → create new tab │ │ │ │ BENEFIT: Filesystem-like paths enable tab manager to │ │ automatically reuse tabs for same viewer type │ │ │ └───────────────────────────────────────────────────────────────────────┘ ``` ### Viewer Lifecycle ``` ┌─────────────────────────────────────────────────────────────────┐ │ VIEWER OPEN FLOW │ ├─────────────────────────────────────────────────────────────────┤ │ │ │ User clicks button │ │ ↓ │ │ openViewer(viewerType) │ │ ↓ │ │ Create virtual path: {repo}/.{viewerType} │ │ ↓ │ │ tabManager.openFileInTab(virtualPath) │ │ ↓ │ │ Set viewer type metadata │ │ ↓ │ │ Clear container: innerHTML = "" │ │ ↓ │ │ Dynamic import from viewerMap │ │ ↓ │ │ new ViewerClass() │ │ ↓ │ │ viewer.init(container, repoPath, params) │ │ ↓ │ │ Store in window: window.gitdashboardViewer │ │ │ └─────────────────────────────────────────────────────────────────┘ ``` ### Batch API Performance ``` ┌───────────────────────────────────────────────────────────────────────┐ │ BATCH API OPTIMIZATION │ ├───────────────────────────────────────────────────────────────────────┤ │ │ │ BEFORE: 5 SEPARATE IPC CALLS │ │ ───────────────────────────── │ │ invoke("git_status") → Round trip 1 │ │ invoke("git_list_branches") → Round trip 2 │ │ invoke("git_log") → Round trip 3 │ │ invoke("git_list_worktrees") → Round trip 4 │ │ invoke("git_stash_list") → Round trip 5 │ │ │ │ Total: 5 IPC roundtrips │ │ │ │ AFTER: 1 BATCH CALL │ │ ───────────────────── │ │ invoke("git_full_refresh", { path, commitLimit }) │ │ │ │ Returns all data in one response: │ │ { status, branches, commits, worktrees, stashes } │ │ │ │ Total: 1 IPC roundtrip │ │ │ │ PERFORMANCE GAIN: 80% latency reduction (5 → 1 roundtrip) │ │ │ └───────────────────────────────────────────────────────────────────────┘ ``` *** ## Frontmatter Parsing ### YAML Metadata Extraction Frontmatter parsing extracts machine-readable metadata from document headers: ```yaml theme={null} --- status: ready title: Feature Implementation priority: high timestamp: 15:30:45 url: https://example.com:8080 --- # Document content starts here... ``` **Extracted Data**: `{ status: "ready", title: "Feature Implementation", ... }` ### Regex Pattern ``` ┌───────────────────────────────────────────────────────────────────────┐ │ FRONTMATTER PARSING ALGORITHM │ ├───────────────────────────────────────────────────────────────────────┤ │ │ │ STEP 1: EXTRACT YAML BLOCK │ │ ───────────────────────────── │ │ Regex: /^---\n([\s\S]*?)\n---/ │ │ │ │ ^ Anchor to document start (frontmatter must be first) │ │ ---\n Opening delimiter │ │ ([\s\S]*?) Capture group (any char including newlines, non-greedy) │ │ \n--- Closing delimiter │ │ │ │ STEP 2: PARSE KEY:VALUE PAIRS │ │ ───────────────────────────── │ │ FOR each line in yaml: │ │ 1. Split on first colon: [key, ...valueParts] = line.split(':') │ │ 2. Rejoin value parts: value = valueParts.join(':').trim() │ │ 3. Store: result[key.trim()] = value │ │ │ │ STEP 3: RETURN RESULT │ │ ───────────────────── │ │ Record of all key-value pairs │ │ │ └───────────────────────────────────────────────────────────────────────┘ ``` ### Colon-in-Value Handling ``` ┌───────────────────────────────────────────────────────────────────────┐ │ COLON-IN-VALUE HANDLING │ ├───────────────────────────────────────────────────────────────────────┤ │ │ │ EXAMPLE 1: URL WITH PORT │ │ ────────────────────────── │ │ Input: "url: https://example.com:8080" │ │ │ │ split(':') → ["url", " https", "//example.com", "8080"] │ │ │ │ key = "url" │ │ valueParts = [" https", "//example.com", "8080"] │ │ valueParts.join(':') → " https://example.com:8080" │ │ .trim() → "https://example.com:8080" ✓ │ │ │ │ EXAMPLE 2: TIMESTAMP │ │ ───────────────────── │ │ Input: "timestamp: 15:30:45" │ │ │ │ split(':') → ["timestamp", " 15", "30", "45"] │ │ │ │ key = "timestamp" │ │ valueParts = [" 15", "30", "45"] │ │ valueParts.join(':') → " 15:30:45" │ │ .trim() → "15:30:45" ✓ │ │ │ │ ALGORITHM: Split on first colon only, rejoin remaining parts │ │ to preserve embedded colons in values │ │ │ └───────────────────────────────────────────────────────────────────────┘ ``` ### Status Field with Default ``` ┌───────────────────────────────────────────────────────────────────────┐ │ STATUS EXTRACTION WITH DEFAULT │ ├───────────────────────────────────────────────────────────────────────┤ │ │ │ status = frontmatter.status || 'in-progress' │ │ │ │ LOGIC: │ │ ┌────────────────────────────┐ │ │ │ frontmatter.status exists? │ │ │ └─────────────┬──────────────┘ │ │ ┌───────┴───────┐ │ │ │ │ │ │ YES NO │ │ │ │ │ │ ▼ ▼ │ │ Use frontmatter Use default │ │ value 'in-progress' │ │ │ └───────────────────────────────────────────────────────────────────────┘ ``` *** ## Extended Document Types ### Document Transformation Pipeline ``` ┌─────────────────────────────────────────────────────────────────┐ │ DOCUMENT TYPE TRANSFORMATIONS │ ├─────────────────────────────────────────────────────────────────┤ │ │ │ WikiDocument (base) │ │ { path, name, category, isWip, isDirectory, modifiedAt } │ │ ↓ │ │ ├─→ OnitSession │ │ │ + date, time, sessionName, pattern, sortKey, status │ │ │ Source: Filename parsing + isWip flag │ │ │ │ │ ├─→ PrepareDocument │ │ │ + date, time, featureName, analysisType, implReady │ │ │ Source: Filename parsing + YAML frontmatter │ │ │ │ │ ├─→ ResearchTopic │ │ │ + threadCount, chapterCount, hasSynthesis, threads │ │ │ Source: Folder scanning + regex extraction │ │ │ │ │ └─→ ProofClaim │ │ + thread, claimId, status, verdictPath, gapsCount │ │ Source: Verdict content + GAP-\d+ marker count │ │ │ └─────────────────────────────────────────────────────────────────┘ ``` ### Status Value Domains | Viewer | Cardinality | Source | Values | | -------- | ----------- | --------------------- | ----------------------------------------- | | OnIt | 2 | Path location | `wip`, `graduated` | | Prepare | N | YAML frontmatter | `ready`, `in-progress`, `blocked`, etc. | | Research | 3 | File existence + path | `synthesized`, `in-progress`, `archived` | | Prove | 4 | Content + gap count | `proven`, `refuted`, `partial`, `pending` | **Pattern**: Each viewer defines its own status domain based on metadata source. *** ## THE CENTER ``` ┌─────────────────────────────────────────────────────────────────┐ │ THE CENTER: Human ◈ AI Feedback Loop Environment │ ├─────────────────────────────────────────────────────────────────┤ │ │ │ Research Viewer + Frontmatter = Documentation Intelligence │ │ │ │ HUMAN BENEFITS: │ │ ├── Visual research progress (threads, chapters, synthesis) │ │ ├── Status at a glance (color-coded badges) │ │ ├── Organized Git exploration (14 specialized tools) │ │ └── Metadata-driven prioritization │ │ │ │ AI BENEFITS: │ │ ├── Structured access to multi-threaded research │ │ ├── Machine-readable status fields │ │ ├── Batch API reduces IPC overhead │ │ └── Automated categorization via frontmatter │ │ │ │ FEEDBACK LOOP: │ │ ├── Human writes frontmatter → AI parses metadata │ │ ├── AI generates research → Human reviews synthesis │ │ ├── Status updates trigger workflow automation │ │ └── Metadata evolution tracks document lifecycle │ │ │ │ YAML frontmatter is the bridge between human prose │ │ and machine logic. Research viewer is the window into │ │ parallel AI cognition. │ │ │ └─────────────────────────────────────────────────────────────────┘ ``` *** The frontmatter parser does not support multiline YAML values using `|` or `>` notation. ```yaml theme={null} # This will fail: description: | This is a multiline value ``` **Workaround**: Use single-line values or comma-separated lists. **Impact**: Minor - most frontmatter uses simple key:value pairs.