MDR — Markdown Rich

MDR (Markdown Rich) is a superset of standard Markdown used as the unified document format for the KROS AI platform. Every chat message, report, and artifact is stored as an .md file with two additions on top of CommonMark:

1. Typed fenced blocks — ~~~type "Optional Title" with JSON body for structured widget data
2. Placeholders — <<kros:TYPE:CALL_ID>> tokens for deferred block insertion during LLM streaming

MDR files are valid Markdown and open natively in any editor, GitHub, VS Code, or Obsidian.

Repository structure

docs/
  mdr-library-spec-final.md    Format specification v1.2
  MDR-Development-Prompts.md   Step-by-step implementation prompts
  MDR-Development-Roadmap.md   Development roadmap & epic breakdown
packages/
  mdr-core/                    @kros/mdr-core — parser, serializer, re-edit helpers
    src/
      types.ts                 Type definitions (ParsedDocument, BlockNode, ProseNode, etc.)
      parse.ts                 parse(input: string): ParsedDocument
      serialize.ts             serialize(doc: ParsedDocument): string
      reedit.ts                toPlaceholderForm() + restoreBlocks() for LLM re-edit flow
      index.ts                 Re-exports
    test/
      fixtures/                15 .md test fixtures
      expected/                15 .json expected parse outputs
      parse.test.ts            86 tests
      serialize.test.ts        12 tests
      roundtrip.test.ts        59 tests
      reedit.test.ts           20 tests

Quick start

cd packages/mdr-core
npm install
npm test          # 177 tests
npm run build     # tsc → dist/

Usage

import { parse, serialize } from '@kros/mdr-core';

// Parse MDR string → structured document
const doc = parse(mdrString);
doc.frontmatter   // { type: 'message', id: '...', ... }
doc.children       // [ProseNode, BlockNode, PlaceholderNode, ...]

// Serialize back to canonical MDR
const output = serialize(doc);

Format example

---
id: msg_123
type: message
---

SOL shows strong momentum with improving fundamentals.

~~~w01_snapshot
{
  "symbol": "SOL",
  "price": "$178.42",
  "metrics": [
    { "label": "Rating", "value": "A · 74", "trend": "up" }
  ]
}
~~~

Entry zone $172-178. Tight SL given elevated MC/L ratio.

Prose reads as a normal article. Typed blocks carry structured data for frontend widgets. Front matter identifies the document type and metadata.

Packages

Package	Status	Description
@kros/mdr-core	Ready	Parser, serializer, re-edit helpers. 322 lines, 177 tests.
chat-renderer	Planned	React components: StoredMessage, LiveMessage, Widget dispatch.

Documentation

Document	Description
mdr-library-spec-final.md	Format specification v1.2 — types, parser algorithm, serializer, edge cases
MDR-Development-Prompts.md	Step-by-step prompts for Claude Code implementation
MDR-Development-Roadmap.md	Full development roadmap — 10 epics, 4 phases, production checklist

Architecture context

MDR serves as the single source of truth across the KROS platform:

• messages.mdr_content — every chat message stored as MDR
• output_artifacts.source_mdr — reports and artifacts stored as MDR
• Frontend — parse() → React component tree
• Backend assembler — LLM prose + tool outputs → MDR string
• Re-edit flow — toPlaceholderForm() → LLM edits → restoreBlocks() → new version