toolpath-md 0.2.0

Render Toolpath documents as Markdown for LLM consumption
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112

# 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 any Toolpath `Document` (Step, Path, or Graph) as a Markdown string.
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

```rust
use toolpath::v1::Document;
use toolpath_md::{render, RenderOptions};

let json_str = r#"{"Step":{"step":{"id":"s1","actor":"human:alex","timestamp":"T"},"change":{}}}"#;
let doc = Document::from_json(json_str).unwrap();
let md = render(&doc, &RenderOptions::default());
assert!(md.contains("# s1"));
```

Pipe into an LLM for contextual assistance:

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

```rust
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(doc, options)` | Render any `Document` variant |
| `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

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

### Path

```markdown
# 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](https://github.com/empathic/toolpath) workspace. See also:

- [`toolpath`](https://crates.io/crates/toolpath) — core types and query API
- [`toolpath-dot`](https://crates.io/crates/toolpath-dot) — Graphviz DOT visualization
- [`toolpath-git`](https://crates.io/crates/toolpath-git) — derive from git history
- [`toolpath-claude`](https://crates.io/crates/toolpath-claude) — derive from Claude conversations
- [`toolpath-cli`](https://crates.io/crates/toolpath-cli) — unified CLI (`cargo install toolpath-cli`)
- [RFC](https://github.com/empathic/toolpath/blob/main/RFC.md) — full format specification