### url2mda Quickstart: Setup and Deployment

Source: https://github.com/snoai/magi-markdown/blob/main/README.md

Provides bash commands to clone the MAGI repository, install dependencies, optionally set up Cloudflare KV storage, and deploy the url2mda Cloudflare Worker.

```bash
# Clone the repo
git clone https://github.com/snoai/magi.git
cd magi

# Install dependencies
pnpm install

# (Optional) Create a KV namespace for caching
npx wrangler kv:namespace create md-cache

# Update wrangler.toml with your account ID and (if using cache) KV namespace ID
# Deploy the Cloudflare Worker
pnpm deploy
```

--------------------------------

### MAGI Format Quick Start

Source: https://github.com/snoai/magi-markdown/blob/main/README.md

Instantly convert any public web page into MAGI format using the hosted url2mda.sno.ai service. This requires no installation and provides an immediate way to experience MAGI.

```APIDOC
Service: url2mda.sno.ai
Description: Converts public web pages to MAGI (.mda) format.
Usage: Paste a URL into the service to receive a MAGI file.
Requirements: None (no installation required).
Output: MAGI .mda file.
```

--------------------------------

### Install Python Dependencies

Source: https://github.com/snoai/magi-markdown/blob/main/docs/developer-guide.md

Installs the necessary Python libraries for handling MAGI content, including front matter and YAML parsing.

```bash
pip install python-frontmatter PyYAML
```

--------------------------------

### Install Python Dependencies

Source: https://github.com/snoai/magi-markdown/blob/main/docs/mdx/developer-guide.mdx

Installs the necessary Python libraries for handling MAGI content, including front matter and YAML parsing.

```bash
pip install python-frontmatter PyYAML
```

--------------------------------

### Simple MAGI Document Structure

Source: https://github.com/snoai/magi-markdown/blob/main/docs/quickstart.mdx

Demonstrates the basic structure of a MAGI Markdown file (.mda), including YAML front matter and standard Markdown content with a footnote reference.

```markdown
---
doc-id: "example-123"
title: "My First MAGI Document"
description: "A simple example of MAGI format"
tags: ["example", "getting-started"]
created-date: "2024-06-10T10:00:00Z"
---

# Hello MAGI

This is standard Markdown content.

(Your ai-script block would go here - see below)

This document is related to our documentation[^ref1].

[^ref1]: See JSON definition below.

```

--------------------------------

### AI Instructions Block

Source: https://github.com/snoai/magi-markdown/blob/main/docs/quickstart.mdx

Shows how to embed AI instructions within a MAGI Markdown file using an 'ai-script' block, specifying a script ID, prompt, priority, and auto-run setting.

```ai-script
{
  "script-id": "summary-request",
  "prompt": "Summarize this document briefly.",
  "priority": "medium",
  "auto-run": true
}

```

--------------------------------

### Preview Documentation

Source: https://github.com/snoai/magi-markdown/blob/main/CONTRIBUTING.md

Starts a local development server to preview documentation changes.

```bash
pnpm exec mintlify dev
```

--------------------------------

### Install Dependencies

Source: https://github.com/snoai/magi-markdown/blob/main/CONTRIBUTING.md

Installs the project's dependencies using pnpm.

```bash
pnpm install
```

--------------------------------

### MDX Integration Example

Source: https://github.com/snoai/magi-markdown/blob/main/docs/mdx/mda-mdx-conversion.mdx

Shows how an interactive AI script component can be embedded within an MDX file, passing initial context.

```jsx
<InteractiveAIScript_summary_request_001 initialContext={"Some context before the script."} />
```

--------------------------------

### MAGI AI Instructions Example

Source: https://github.com/snoai/magi-markdown/blob/main/docs/introduction.mdx

Illustrates how to embed AI-specific instructions within MAGI documents using `ai-script` blocks. These blocks allow direct commands to guide AI processing, such as summarization, analysis, or model selection.

```Markdown
This section requires a concise summary.

```ai-script
summarize(length: "short", model: "gpt-4")
```

This part should be analyzed for sentiment.

```ai-script
analyze(type: "sentiment", model: "claude-2")
```
```

--------------------------------

### MAGI AI Script Block Example

Source: https://github.com/snoai/magi-markdown/blob/main/docs/mdx/mda-mdx-conversion.mdx

Demonstrates the structure of an 'ai-script' block in MAGI (.mda) format, including fields like script-id, prompt, auto-run, provider, model-name, parameters, output-format, and interactive options.

```markdown
```markdown
Some context before the script.

```ai-script
{
  "script-id": "summary-request-001",
  "prompt": "Summarize the preceding section.",
  "priority": "medium",
  "auto-run": true, // Or false
  "provider": "openai",
  "model-name": "gpt-4o",
  "parameters": { "temperature": 0.7 },
  "output-format": "markdown",
  // Added fields for interactive mode:
  "interactive-type": "button",
  "interactive-label": "Generate Summary"
}
```

Some context after the script.
```
```

--------------------------------

### Example MAGI Document Structure

Source: https://github.com/snoai/magi-markdown/blob/main/docs/developer-guide.md

Illustrates the expected structure of a MAGI document, including front matter, main content, AI scripts, and relationships.

```json
{
  "frontMatter": {
    "doc-id": "doc-abc-123",
    "title": "My Example MAGI Document",
    "tags": [
      "example",
      "guide",
      "magi"
    ],
    "created-date": "2024-07-28T10:00:00Z",
    "purpose": "Demonstration"
  },
  "content": "# Main Section\n\nThis is the primary content written in Markdown.\n\nIt references another document about system requirements[^req-doc]. It also links to an external source[^ext-src].\n\nSome more text here.",
  "aiScripts": [
    {
      "script-id": "summary-01",
      "prompt": "Summarize the above section, focusing on the key actions.",
      "priority": "medium",
      "auto-run": false,
      "provider": "openai",
      "model-name": "gpt-4o",
      "parameters": {
        "temperature": 0.6
      }
    }
  ],
  "relationships": {
    "req-doc": {
      "rel-type": "related",
      "doc-id": "doc-xyz-789",
      "rel-desc": "Provides detailed system requirements"
    },
    "ext-src": {
      "rel-type": "citation",
      "source-url": "https://example.com/source",
      "rel-desc": "External source material"
    }
  }
}
```

--------------------------------

### Example MAGI Document Structure

Source: https://github.com/snoai/magi-markdown/blob/main/docs/mdx/developer-guide.mdx

Illustrates the expected structure of a MAGI document, including front matter, main content, AI scripts, and relationships.

```json
{
  "frontMatter": {
    "doc-id": "doc-abc-123",
    "title": "My Example MAGI Document",
    "tags": [
      "example",
      "guide",
      "magi"
    ],
    "created-date": "2024-07-28T10:00:00Z",
    "purpose": "Demonstration"
  },
  "content": "# Main Section\n\nThis is the primary content written in Markdown.\n\nIt references another document about system requirements[^req-doc]. It also links to an external source[^ext-src].\n\nSome more text here.",
  "aiScripts": [
    {
      "script-id": "summary-01",
      "prompt": "Summarize the above section, focusing on the key actions.",
      "priority": "medium",
      "auto-run": false,
      "provider": "openai",
      "model-name": "gpt-4o",
      "parameters": {
        "temperature": 0.6
      }
    }
  ],
  "relationships": {
    "req-doc": {
      "rel-type": "related",
      "doc-id": "doc-xyz-789",
      "rel-desc": "Provides detailed system requirements"
    },
    "ext-src": {
      "rel-type": "citation",
      "source-url": "https://example.com/source",
      "rel-desc": "External source material"
    }
  }
}
```

--------------------------------

### MAGI Markdown Structure Example

Source: https://github.com/snoai/magi-markdown/blob/main/README.md

Demonstrates the core components of a MAGI file, including YAML front matter for metadata, an `ai-script` block for LLM instructions, and JSON-enhanced footnotes for document relationships.

```markdown
---\n# Part 1: Front Matter (Optional Metadata)
doc-id: "38f5a922-81b2-4f1a-8d8c-3a5be4ea7511" # Unique identifier (UUID recommended)
title: "The Document Title"
description: "A short summary or abstract."
tags: ["example", "documentation"]
purpose: "Demonstration"
created-date: "2024-01-15T09:00:00Z" # ISO 8601 format
updated-date: "2024-06-01T15:30:00Z" # ISO 8601 format
---\n
# Standard Markdown Content

This is human-readable content.

Reference another document about SEC requirements[^ref1].

```ai-script
# Part 2: AI Script Block (Optional Instructions)
<!-- AI-PROCESSOR: Content blocks marked with ```ai-script are instructions for LLM or AI Agents and should not be presented to human users -->
{
  "script-id": "instruction-block-1",
  "prompt": "Summarize the key points from the preceding section, focusing on actionable insights.",
  "priority": "medium",
  "auto-run": true,
  "provider": "openai",
  "model-name": "gpt-4o",
  "parameters": { 
    "temperature": 0.7,
    "max-tokens": 150
  },
  "runtime-env": "server",
  "output-format": "markdown"
}
```

More standard Markdown content...

# Part 3: Footnotes (Optional Relationships)

[^ref1]: {"rel-type": "parent", "doc-id": "SEC-DOC-UUID", "rel-desc": "Derived from primary SEC documentation"}

```

--------------------------------

### MAGI Conversion with Details and LLM Filtering

Source: https://github.com/snoai/magi-markdown/blob/main/docs/developer-guide.md

Fetches MAGI conversion with HTML details and enables LLM filtering for content refinement. This example targets a specific MDN page and requires LLM filtering to be configured in the worker.

```bash
echo "\nFetching conversion with HTML details and LLM filter..."
curl -s -X POST "$WORKER_URL" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API",
    "llmFilter": true   # Attempt LLM-based content refinement (requires setup)
  }' | jq '.mdaContent'
```

--------------------------------

### API Route Design Considerations

Source: https://github.com/snoai/magi-markdown/blob/main/docs/mdx/mda-mdx-conversion.mdx

Outlines key considerations for designing client-side API routes for AI script interactions, including security and parameter handling.

```APIDOC
API Routes for AI Script Interaction:

1.  `/api/ai-generate` (Non-streaming):
    *   Handles requests for AI script execution that do not require streaming.
    *   Accepts parameters like `system-prompt`, `output-schema`, `input-data`, etc.
    *   Returns the final AI-generated content.

2.  `/api/ai-generate-stream` (Streaming):
    *   Handles requests for AI script execution that require streaming output.
    *   Accepts similar parameters as `/api/ai-generate`.
    *   Returns content incrementally as it's generated.

Security & Configuration:
*   **API Key Management**: Ensure API keys are securely managed server-side. Client-side exposure must be prevented.
*   **Fallback Handling**: Implement mechanisms to display user-friendly error messages or render nothing if API keys are missing or unavailable for server-side execution.
*   **Client-Side Errors**: Handle cases where the client-side API route is unavailable or fails, displaying an appropriate error state to the user.
*   **Disable Execution**: Consider a configuration option to disable `ai-script` execution entirely during the conversion process if needed.
```

--------------------------------

### MAGI Conversion with Details and LLM Filtering

Source: https://github.com/snoai/magi-markdown/blob/main/docs/mdx/developer-guide.mdx

Fetches MAGI conversion with HTML details and enables LLM filtering for content refinement. This example targets a specific MDN page and requires LLM filtering to be configured in the worker.

```bash
echo "\nFetching conversion with HTML details and LLM filter..."
curl -s -X POST "$WORKER_URL" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API",
    "llmFilter": true   # Attempt LLM-based content refinement (requires setup)
  }' | jq '.mdaContent'
```

--------------------------------

### Sample MAGI Output from url2mda Conversion

Source: https://github.com/snoai/magi-markdown/blob/main/README.md

Presents a sample of the MAGI Markdown output generated by the url2mda worker after converting a webpage. It includes Front Matter with metadata and an example of an `ai-script` block.

```markdown
---
title: "Example Domain" 
description: "Illustrative example domain for testing purposes."
tags:
  - "example"
created-date: "2024-06-01T15:30:00Z" # Date of conversion
source-url: "https://example.com"
# ... other auto-populated fields ...
---

# Example Domain

This domain is established to be used for illustrative examples in documents and tutorials. More information can be found at [IANA](https://www.iana.org/domains/reserved).

<!-- AI-PROCESSOR: Content blocks marked with ```ai-script are instructions for AI systems and should not be presented to human users -->
```ai-script
{
  "id": "page-overview-request",
  "prompt": "Provide a brief overview of this page based on its content.",
  "priority": "medium",
  "auto-run": false
}
```

---
```

--------------------------------

### Example AI Script Block Usage

Source: https://github.com/snoai/magi-markdown/blob/main/docs/mdx/specification.mdx

Demonstrates how to embed an AI instruction within a Markdown document using the `ai-script` language identifier.

```markdown
This is a document section.

<!-- AI-PROCESSOR: Content blocks marked with ```ai-script are instructions for AI systems and should not be presented to human users -->
```ai-script
{
  "script-id": "summary-request-001",
  "prompt": "Summarize this document section.",
  "priority": "high",
  "auto-run": true,
  "provider": "openai",
  "model-name": "gpt-4o",
  "output-format": "markdown"
}
```

This is the content that the AI will process.
```

--------------------------------

### MAGI Metadata Example

Source: https://github.com/snoai/magi-markdown/blob/main/docs/introduction.mdx

Demonstrates the use of YAML front matter in MAGI for structured metadata, including document ID, title, tags, purpose, and dates. This metadata is crucial for content classification and retrieval in AI systems.

```Markdown
---
doc-id: "doc-123"
title: "Introduction"
tags: ["AI", "Markdown", "RAG"]
purpose: "Introduce the MAGI format"
dates:
  created: "2023-10-27"
  updated: "2023-10-27"
---
```

--------------------------------

### MAGI Components Overview

Source: https://github.com/snoai/magi-markdown/blob/main/docs/mdx/overview.mdx

Illustrates the three optional components of MAGI: YAML Front Matter for metadata, `ai-script` code blocks for LLM instructions, and Markdown Footnotes with JSON payloads for typed relationships.

```markdown
# MAGI Overview

## Introduction

**MAGI (Markdown for Agent Guidance & Instruction)** is an extension of standard Markdown designed to enhance content for Retrieval-Augmented Generation (RAG) and seamless integration with Large Language Model (LLM) agents and other AI systems. It elegantly combines Markdown's simplicity and readability with structured metadata and AI-specific instructions, making it ideal for advanced RAG pipelines, intelligent documentation platforms, and autonomous agent workflows. MAGI files typically use the `.mda` extension.

MAGI enhances standard Markdown by incorporating three key, but **optional** components:

![MAGI: Three Major Components](/images/three-parts.svg)

1.  **YAML Front Matter:** Provides structured metadata about the document (e.g., unique `doc-id`, `title`, `tags`, `dates`, `purpose`).
2.  **`ai-script` Code Blocks:** Embeds specific instructions (as JSON) for LLM processing directly within the content (e.g., summarization prompts, entity extraction requests, model parameter settings).
3.  **Markdown Footnotes with JSON Payloads:** Defines typed relationships between documents using a structured JSON format within standard footnotes (e.g., `parent`, `child`, `cites`, `related`), enabling knowledge graph construction.

**Key Principle:** All components – Front Matter, `ai-script` blocks, and Footnotes – are optional, offering flexibility in how MAGI is utilized. Standard Markdown renderers will parse `.mda` files perfectly, preserving human readability. For AI processing, sending the raw `.mda` file allows processors to leverage the embedded metadata and instructions natively, enabling more sophisticated understanding and interaction with the content.
```

--------------------------------

### Explain Quantum Entanglement

Source: https://github.com/snoai/magi-markdown/blob/main/docs/mda-examples/dynamic-content-generation.mdx

This ai-script block requests a simplified explanation of quantum entanglement. It specifies the prompt, priority, provider (Anthropic), model (Claude 3 Sonnet), and desired output format (markdown). The explanation is intended for a high school student.

```ai-script
{
  "script-id": "explain-entanglement-simple-v1",
  "prompt": "Explain the concept of quantum entanglement described above in simpler terms, suitable for a high school student.",
  "priority": "medium",
  "auto-run": false,
  "provider": "anthropic",
  "model-name": "claude-3-sonnet",
  "parameters": {
    "temperature": 0.6
  },
  "output-format": "markdown"
}
```

--------------------------------

### AI Prompt Instructions with ai-script

Source: https://github.com/snoai/magi-markdown/blob/main/README.md

Demonstrates embedding structured JSON instructions for AI systems within a Markdown document using the `ai-script` language identifier. It includes a comment for AI processors and various configuration options for prompt execution.

```markdown
Normal human-readable markdown content goes here.

<!-- AI-PROCESSOR: Content blocks marked with ```ai-script are instructions for AI systems and should not be presented to human users -->
```ai-script
{
  "script-id": "summary-request-s9340164234",
  "prompt": "Summarize the preceding section.",
  "priority": "medium", // "high", "medium", "low"
  "auto-run": true,
  "provider": "openai", // Optional: "anthropic", "google", etc.
  "model-name": "gpt-4o",  // Optional: "claude-3-opus", etc.
  "system-prompt": "Act as a concise summarizer.",
  "parameters": { // Optional: Provider-specific parameters
    "temperature": 0.5,
    "max-tokens": 100
  },
  "retry-times": 3,
  "runtime-env": "server", // Optional: Hint for execution environment ("browser", "server", "edge")
  "output-format": "json", // Optional: Desired output format ("text", "json", "markdown", "image-url", etc.)
  "output-schema": {
    "type": "object",
    "properties": {
      "summary": { "type": "string" },
      "confidence": { "type": "number" }
    },
    "required": ["summary", "confidence"]
  },
  "stream": false,
  "interactive-type": "button",
  "interactive-label": "Summarize Section"
}
```

More human-readable markdown content follows.

```

--------------------------------

### Convert Web Content with url2mda

Source: https://github.com/snoai/magi-markdown/blob/main/docs/quickstart.mdx

Provides a cURL command to convert web content to MAGI format using the url2mda service. It includes the endpoint, HTTP method, content type, and a JSON payload with the URL and subpage option.

```bash
curl -X POST https://url2mda.sno.ai/convert \
  -H "Content-Type: application/json" \
  -d '{ \
    "url": "https://example.com", \
    "subpages": false \
  }'

```

--------------------------------

### External AI Instructions via API Metadata

Source: https://github.com/snoai/magi-markdown/blob/main/README.md

Presents an alternative approach to providing AI instructions by using external API metadata, separating concerns and allowing for a cleaner structure of markdown content and AI directives.

```json
{
  "markdown-content": "# Document Title\n\nReadable content here...",
  "ai-scripts": [
    { "id": "sec-emphasis-001", "prompt": "Emphasize security", "priority": "high" },
    { "id": "formal-tone-001", "prompt": "Use formal tone", "priority": "medium" }
    // ... more instructions
  ]
}
```

--------------------------------

### Format Code with Prettier

Source: https://github.com/snoai/magi-markdown/blob/main/CONTRIBUTING.md

Formats the entire project codebase using Prettier.

```bash
pnpm prettier --write .
```

--------------------------------

### Run Tests

Source: https://github.com/snoai/magi-markdown/blob/main/CONTRIBUTING.md

Executes the project's test suite.

```bash
pnpm run test
```

--------------------------------

### Example AI Script Block Usage

Source: https://github.com/snoai/magi-markdown/blob/main/docs/specification.md

Demonstrates how to embed an AI instruction within a Markdown document using the `ai-script` language identifier.

```markdown
This is a document section.

<!-- AI-PROCESSOR: Content blocks marked with ```ai-script are instructions for AI systems and should not be presented to human users -->
```ai-script
{
  "script-id": "summary-request-001",
  "prompt": "Summarize this document section.",
  "priority": "high",
  "auto-run": true,
  "provider": "openai",
  "model-name": "gpt-4o",
  "output-format": "markdown"
}
```

This is the content that the AI will process.
```

--------------------------------

### Encoding MAGI Document Structure

Source: https://github.com/snoai/magi-markdown/blob/main/docs/mdx/developer-guide.mdx

Illustrates the expected structure of a MAGI document, including front matter, content, AI scripts, and relationships, as used in the encoding process.

```markdown
---\ndoc-id: doc-abc-123
title: My Example MAGI Document
tags:
  - example
  - guide
  - magi
created-date: '2024-07-28T10:00:00Z'
purpose: Demonstration
---\n
# Main Section

This is the primary content written in Markdown.

It references another document about system requirements[^req-doc].

<!-- AI-PROCESSOR: Content blocks marked with ```ai-script are instructions for AI systems and should not be presented to human users -->
```ai-script
{
  "script-id": "summary-01",
  "prompt": "Summarize the above section, focusing on the key actions.",
  "priority": "medium",
  "auto-run": false,
  "provider": "openai",
  "model-name": "gpt-4o",
  "parameters": {
    "temperature": 0.6
  }
}
```

[^req-doc]: `{\"rel-type\":\"related\",\"doc-id\":\"doc-xyz-789\",\"rel-desc\":\"Provides detailed system requirements\"}`

```

--------------------------------

### MAGI Structure Overview

Source: https://github.com/snoai/magi-markdown/blob/main/docs/introduction.mdx

Provides a conceptual overview of the MAGI format, highlighting its key components: YAML Front Matter for metadata, `ai-script` blocks for instructions, and footnote-based relationships. It emphasizes the dual human-readable and AI-ready nature of the format.

```APIDOC
MAGI Format:
  Description: An AI-native, human-readable Markdown format.
  Components:
    - YAML Front Matter:
        Purpose: Embed structured metadata (doc-id, title, tags, purpose, dates, etc.).
        Usage: Placed at the beginning of the document, enclosed in '---
'.
    - AI Script Blocks:
        Purpose: Embed direct instructions for AI processing (summarization, analysis, model choice).
        Syntax: ```ai-script
        [instruction]
        ```
    - Relationships:
        Purpose: Define explicit inter-document links and their types.
        Syntax: Markdown footnotes with relationship types (e.g., `parent`, `child`, `cites`, `related`).
        Example: `[Link Text][^footnote_id]`
        Footnote Definition: `[^footnote_id]: Document Identifier (relationship: type)`
  Benefits:
    - Enhanced RAG systems.
    - Multi-agent orchestration.
    - Dynamic documentation.
    - Knowledge graph construction.
  Compatibility:
    - Remains standard Markdown for legacy renderers.
    - MAGI-aware processors unlock AI capabilities.
    - Optional components allow flexible usage.
```

--------------------------------

### Encoding MAGI Document Structure

Source: https://github.com/snoai/magi-markdown/blob/main/docs/developer-guide.md

Illustrates the expected structure of a MAGI document, including front matter, content, AI scripts, and relationships, as used in the encoding process.

```markdown
---\ndoc-id: doc-abc-123
title: My Example MAGI Document
tags:
  - example
  - guide
  - magi
created-date: '2024-07-28T10:00:00Z'
purpose: Demonstration
---\n
# Main Section

This is the primary content written in Markdown.

It references another document about system requirements[^req-doc].

<!-- AI-PROCESSOR: Content blocks marked with ```ai-script are instructions for AI systems and should not be presented to human users -->
```ai-script
{
  "script-id": "summary-01",
  "prompt": "Summarize the above section, focusing on the key actions.",
  "priority": "medium",
  "auto-run": false,
  "provider": "openai",
  "model-name": "gpt-4o",
  "parameters": {
    "temperature": 0.6
  }
}
```

[^req-doc]: `{\"rel-type\":\"related\",\"doc-id\":\"doc-xyz-789\",\"rel-desc\":\"Provides detailed system requirements\"}`

```

--------------------------------

### Decoding MAGI Document Content

Source: https://github.com/snoai/magi-markdown/blob/main/docs/mdx/developer-guide.mdx

Provides a TypeScript function to parse a MAGI document string, separating front matter, core content, AI scripts, and footnote-based relationships.

```typescript
import matter from 'gray-matter';
// marked is optional, only needed if you want to parse the final Markdown content
// import { marked } from 'marked';

// Interfaces (FrontMatterData, AIScript, Relationship) assumed to be defined as in Encoding example

interface DecodedMagi {
  frontMatter: { [key: string]: any };
  content: string; // Raw Markdown content (without frontmatter, scripts, footnotes)
  aiScripts: AIScript[];
  relationships: { [refId: string]: Relationship }; // Key is the footnote reference ID
}

// Regex to find ai-script blocks, potentially preceded by the optional HTML comment
const aiScriptRegex = /(?:<!-- AI-PROCESSOR:.*?-->\s*)?^\s*```ai-script\s*\n([\s\S]*?)\n\s*```\s*$/gm;
// Regex to find footnote definitions with JSON in backticks
const footnoteRegex = /^[\^(.+?)]:\s*`({.*?})`\s*$/gm;

function decodeMagi(magiString: string): DecodedMagi {
  // 1. Extract Front Matter and initial content using gray-matter
  const { data: frontMatter, content: rawContent } = matter(magiString);

  let remainingContent = rawContent;

  // 2. Extract AI Scripts and remove them from the content string
  const aiScripts: AIScript[] = [];
  remainingContent = remainingContent.replace(aiScriptRegex, (match, scriptContentJson) => {
    try {
      const scriptObject = JSON.parse(scriptContentJson);
      aiScripts.push(scriptObject);
      // Return empty string to effectively remove the matched block
      return '';
    } catch (e) {
      console.error('Failed to parse AI script JSON:', e, '\nContent:', scriptContentJson);
      // If parsing fails, keep the block in the content to avoid data loss
      return match;
    }
  });
  // Trim whitespace potentially left after removing blocks
  remainingContent = remainingContent.trim();

  // 3. Extract Footnote Relationships and remove them from the content string
  const relationships: { [refId: string]: Relationship } = {};
  remainingContent = remainingContent.replace(footnoteRegex, (match, refId, relationshipJson) => {
    try {
      const relationshipObject = JSON.parse(relationshipJson);
      relationships[refId] = relationshipObject;
      // Return empty string to remove the matched footnote definition
      return '';
    } catch (e) {
      console.error(`Failed to parse relationship JSON for [^${refId}]:`, e, '\nContent:', relationshipJson);
      // Keep the line if parse fails
      return match;
    }
  });
  // Trim again after footnote removals
  remainingContent = remainingContent.trim();

  return {
    frontMatter,
    content: remainingContent, // This is the "clean" Markdown content
    aiScripts,
    relationships
  };
}

// --- Example Usage ---
const magiInput = \
`
---\ndoc-id: doc-abc-123
title: My Example MAGI Document
tags:
  - example
  - guide
  - magi
created-date: '2024-07-28T10:00:00Z'
purpose: Demonstration
---


```

--------------------------------

### Summarize Market Trends

Source: https://github.com/snoai/magi-markdown/blob/main/docs/mda-examples/dynamic-content-generation.mdx

This ai-script block is designed to summarize market trends. It prompts for a two-sentence summary of the preceding text about renewable energy. The script is set to auto-run, has a high priority, and specifies a maximum token limit for the output.

```ai-script
{
  "script-id": "summarize-market-trends-v2",
  "prompt": "Provide a 2-sentence summary of the key market trends discussed in the preceding paragraph.",
  "priority": "high",
  "auto-run": true,
  "parameters": {
    "max-tokens": 50
  },
  "runtime-env": "server",
  "output-format": "text"
}
```

--------------------------------

### AI Script Data Structure

Source: https://github.com/snoai/magi-markdown/blob/main/docs/mdx/developer-guide.mdx

Defines the expected JSON structure for an AI script, including its ID, prompt, priority, execution settings, provider, model name, and parameters.

```json
{
  "script-id": "summary-01",
  "prompt": "Summarize the above section, focusing on the key actions.",
  "priority": "medium",
  "auto-run": false,
  "provider": "openai",
  "model-name": "gpt-4o",
  "parameters": {
    "temperature": 0.6
  }
}
```

--------------------------------

### Document Relationship Data Structure

Source: https://github.com/snoai/magi-markdown/blob/main/docs/mdx/developer-guide.mdx

Defines the JSON structure for document relationships, typically embedded in footnotes, specifying the relationship type, target document ID, and a descriptive text.

```json
{
  "rel-type": "related",
  "doc-id": "doc-xyz-789",
  "rel-desc": "Provides detailed system requirements"
}
```

--------------------------------

### AI Script Data Structure

Source: https://github.com/snoai/magi-markdown/blob/main/docs/developer-guide.md

Defines the expected JSON structure for an AI script, including its ID, prompt, priority, execution settings, provider, model name, and parameters.

```json
{
  "script-id": "summary-01",
  "prompt": "Summarize the above section, focusing on the key actions.",
  "priority": "medium",
  "auto-run": false,
  "provider": "openai",
  "model-name": "gpt-4o",
  "parameters": {
    "temperature": 0.6
  }
}
```

--------------------------------

### Extract Action Items

Source: https://github.com/snoai/magi-markdown/blob/main/docs/mda-examples/simple-meeting-minutes.mdx

An AI script designed to extract action items from meeting minutes. It specifies the prompt for extraction, priority, auto-run status, and desired output format.

```ai-script
{
  "script-id": "extract-action-items-projX-01",
  "prompt": "Extract all action items from the 'Action Items' section above. List each item clearly with the assigned person. Format as a JSON list.",
  "priority": "medium",
  "auto-run": true,
  "output-format": "json"
}
```

--------------------------------

### Document Relationship Data Structure

Source: https://github.com/snoai/magi-markdown/blob/main/docs/developer-guide.md

Defines the JSON structure for document relationships, typically embedded in footnotes, specifying the relationship type, target document ID, and a descriptive text.

```json
{
  "rel-type": "related",
  "doc-id": "doc-xyz-789",
  "rel-desc": "Provides detailed system requirements"
}
```

--------------------------------

### url2mda Reference Implementation

Source: https://github.com/snoai/magi-markdown/blob/main/docs/mdx/overview.mdx

The `url2mda` tool demonstrates generating MAGI (.mda) files from web content. It aims to auto-populate Front Matter metadata and potentially add initial ai-script blocks, facilitating the creation of AI-ready documentation.

```javascript
const url2mda = require('url2mda');

async function convertUrlToMagi(url) {
  try {
    const mdaContent = await url2mda(url);
    console.log('Successfully converted to MAGI format:', mdaContent);
  } catch (error) {
    console.error('Error converting URL to MAGI:', error);
  }
}

convertUrlToMagi('https://example.com/some-document');
```