Research Viewer & Frontmatter Parsing

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

// From wiki-research-viewer.ts
const threads = new Set<string>();
let chapterCount = 0;
let hasSynthesis = false;

for (const item of contents) {
  const name = item.name.toLowerCase();

  // Synthesis detection
  if (name.includes("synthesis") || name.includes("final")) {
    hasSynthesis = true;
  }

  // Chapter counting + thread extraction
  if (name.match(/chapter-\d+/)) {
    chapterCount++;

    const threadMatch = name.match(/chapter-\d+-([a-z])-/i);
    if (threadMatch) {
      threads.add(threadMatch[1].toUpperCase()); // Unique letters
    }
  }
}

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:

If FINAL-SYNTHESIS.md exists → synthesized
Else if not in /wip/ directory → archived
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

// control-tabs-git.ts
private async importViewer(viewerType: string): Promise<any> {
  const viewerMap: Record<string, () => Promise<any>> = {
    'git-dashboard': () =>
      import("../git/git-dashboard").then(m => m.GitDashboard),
    'git-blame': () =>
      import("../git/git-blame-viewer").then(m => m.GitBlameViewer),
    // ... 12 more
  };

  const importer = viewerMap[viewerType];
  if (importer) {
    return await importer();
  }
  return null;
}

Benefits:

Lazy loading: viewers load only when opened
Code splitting: reduces initial bundle size
Object lookup: O(1) viewer resolution

Virtual Path Tab Reuse

// Create unique virtual path per viewer
const virtualPath = `${this.repoPath}/.${viewerType}`;
// Example: /Users/macbook/repo/.git-dashboard

// Open in tab (reuses existing tab if already open)
const tabId = tabManager.openFileInTab(virtualPath, false);

Pattern: Filesystem-like paths enable tab manager to 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

// Before: 5 separate IPC calls
const status = await invoke("git_status");
const branches = await invoke("git_list_branches");
const commits = await invoke("git_log");
const worktrees = await invoke("git_list_worktrees");
const stashes = await invoke("git_stash_list");

// After: 1 batch call
const data = await invoke<GitFullRefresh>("git_full_refresh", {
  path: this.repoPath,
  commitLimit: 10,
});

// Destructure all data at once
this.status = data.status;
this.branches = data.branches;
this.commits = data.commits;
this.worktrees = data.worktrees;
this.stashes = data.stashes;

Performance Gain: 5 IPC roundtrips → 1 (80% latency reduction)

Frontmatter Parsing

YAML Metadata Extraction

Frontmatter parsing extracts machine-readable metadata from document headers:

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

// wiki-prepare-viewer.ts
private parseFrontmatter(content: string): Record<string, any> {
  const match = content.match(/^---\n([\s\S]*?)\n---/);
  if (!match) return {};

  const yaml = match[1];
  const result: Record<string, any> = {};

  yaml.split('\n').forEach(line => {
    const [key, ...valueParts] = line.split(':');
    if (key && valueParts.length > 0) {
      const value = valueParts.join(':').trim();
      result[key.trim()] = value;
    }
  });

  return result;
}

Regex Breakdown:

^ - Anchor to document start (frontmatter must be first)
---\n - Opening delimiter
([\s\S]*?) - Capture group (any character including newlines, non-greedy)
\n--- - Closing delimiter

Colon-in-Value Handling

// Example 1: URL with port
"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
"timestamp: 15:30:45"
  .split(':')  // ["timestamp", " 15", "30", "45"]

valueParts.join(':')  // " 15:30:45"

Algorithm: Split on first colon, rejoin remaining parts to preserve embedded colons.

Status Field with Default

// Extract status with fallback
const status = frontmatter.status || 'in-progress';

If frontmatter contains no status field, defaults to '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.                                         │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Known Limitation: Multiline YAML Values

The frontmatter parser does not support multiline YAML values using | or > notation.

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

Get Started

User Guide

Philosophy

Architecture

Transparency

Terminal Core

Features

VariableMD

Database

Daemons

Research

CodexMono

Research Viewer & Frontmatter Parsing

Overview

WikiResearchViewer: ASURA Display

Research Folder Detection

Thread Extraction Algorithm

Status Determination

GitTab: 14 Viewer Management

Viewer Button Architecture

Dynamic Import Pattern

Virtual Path Tab Reuse

Viewer Lifecycle

Batch API Performance

Frontmatter Parsing

YAML Metadata Extraction

Regex Pattern

Colon-in-Value Handling

Status Field with Default

Extended Document Types

Document Transformation Pipeline

Status Value Domains

THE CENTER

Known Limitation: Multiline YAML Values

Get Started

User Guide

Philosophy

Architecture

Transparency

Terminal Core

Features

VariableMD

Database

Daemons

Research

CodexMono

​Overview

​WikiResearchViewer: ASURA Display

​Research Folder Detection

​Thread Extraction Algorithm

​Status Determination

​GitTab: 14 Viewer Management

​Viewer Button Architecture

​Dynamic Import Pattern

​Virtual Path Tab Reuse

​Viewer Lifecycle

​Batch API Performance

​Frontmatter Parsing

​YAML Metadata Extraction

​Regex Pattern

​Colon-in-Value Handling

​Status Field with Default

​Extended Document Types

​Document Transformation Pipeline

​Status Value Domains

​THE CENTER

Known Limitation: Multiline YAML Values

Overview

WikiResearchViewer: ASURA Display

Research Folder Detection

Thread Extraction Algorithm

Status Determination

GitTab: 14 Viewer Management

Viewer Button Architecture

Dynamic Import Pattern

Virtual Path Tab Reuse

Viewer Lifecycle

Batch API Performance

Frontmatter Parsing

YAML Metadata Extraction

Regex Pattern

Colon-in-Value Handling

Status Field with Default

Extended Document Types

Document Transformation Pipeline

Status Value Domains

THE CENTER