Crate toolpath_md 

toolpath-md

Render Toolpath documents as Markdown for LLM consumption.

Provenance data is only useful if you can feed it to the systems that need it. This crate renders the step DAG as readable Markdown — a narrative an LLM can reason about. Dead ends are called out explicitly (“here’s what was tried and abandoned”), giving models anti-examples alongside the successful path.

Overview

Renders a Toolpath Graph (the single root document type) as a Markdown string. Single-path graphs use the path-focused layout; multi-path graphs use the cross-path layout. Steps are topologically sorted, dead ends are marked and summarized, and the output includes enough anchoring information (step IDs, artifact paths, actor strings) for an LLM to reference back into the original document.

Depends only on toolpath — no template engines, no external dependencies.

Usage

use toolpath::v1::Graph;
use toolpath_md::{render, RenderOptions};

let json_str = r#"{"graph":{"id":"g1"},"paths":[]}"#;
let graph = Graph::from_json(json_str).unwrap();
let md = render(&graph, &RenderOptions::default());
assert!(md.contains("g1"));

Pipe into an LLM for contextual assistance:

path derive git --repo . --branch main | path render md | pbcopy
# Paste into Claude/ChatGPT: "here's what I've tried, help me with the next step"

Render options

use toolpath_md::{RenderOptions, Detail};

let options = RenderOptions {
    detail: Detail::Summary,  // or Detail::Full for inline diffs
    front_matter: false,      // emit YAML front matter with metadata
};

Detail levels

• Summary (default) — file paths with diffstat (+3 -1). Compact, fits in tight context windows.
• Full — inline diffs as fenced code blocks. Use when the LLM needs to reason about specific line changes.

Front matter

When front_matter: true, the output starts with YAML front matter containing machine-readable metadata (document type, step count, actor list, artifact list, dead end count). Useful for LLM workflows that parse structured preambles.

API

Function	Description
render(graph, options)	Render a Graph (single-path graphs use the path layout)
render_step(step, options)	Render a single Step
render_path(path, options)	Render a Path with its step DAG
render_graph(graph, options)	Render a Graph with all paths

Output structure

Step

# step-001
**Actor:** `human:alex`
**Timestamp:** 2026-01-29T10:00:00Z
> Fix greeting
- `src/main.rs` (+1 -1)

Path

# Add email validation
**Base:** `github:org/repo` @ `main`
**Head:** `step-004`
**Steps:** 5 | **Artifacts:** 2 | **Dead ends:** 1

## Timeline
### step-001 — human:alex
### step-002a — agent:claude ❌ dead end
### step-002 — agent:claude
...

## Dead Ends
- **step-002a** — Regex approach (abandoned) | Parent: `step-001`

Graph

Renders a summary table of all paths, then each path as a subsection.

Part of Toolpath

This crate is part of the Toolpath workspace. See also:

• toolpath — core types and query API
• toolpath-dot — Graphviz DOT visualization
• toolpath-git — derive from git history
• toolpath-claude — derive from Claude conversations
• path-cli — unified CLI (cargo install path-cli)
• RFC — full format specification

Structs

RenderOptions

Options controlling the markdown output.

Enums

Detail

Detail level for the rendered markdown.

Functions

render

Render a Toolpath Graph as a Markdown string. Single-path graphs use the path-focused layout, multi-path graphs use the cross-path layout.

render_graph

Render a Graph as Markdown.

render_path

Render a Path as Markdown.

render_step

Render a single Step as Markdown.