Decision: ship graph_data inside the bundle URL

Status: shipped 2026-05-12 (commit ba7344c4)

Context

A bundle URL returns a markdown digest. Before this change the digest contained only the doc list + annotations. The canvas analysis (themes, insights, concept relations) lived only inside the mdfy.app web canvas — paste the URL into Claude and the AI got the doc list but had to redo the cross-doc analysis itself.

Decision

Embed the graph_data JSON as markdown sections inside the /raw/bundle/<id> response by default. Add ?graph=0 opt-out for callers that want the legacy doc-list-only digest.

Why

The viral loop runs through URLs. If pasting a URL gives the receiving AI more than the sending AI could give without mdfy, the URL is genuinely portable. Without graph_data in the payload, the URL is just a doc inventory — useful but not differentiating.

Trade-offs

  • Token cost: typical bundle adds ~600 tokens for the analysis section. Caller can drop via ?graph=0.
  • Staleness: analysis_stale: true frontmatter flag warns the AI when member docs were edited after the last analysis run.
  • Recompute cost: regenerating graph_data requires an LLM call. Today this is owner-triggered; Pro will background-run on stale fetch.

Validation

  • e2e: every public bundle URL now carries the section by default (test 28/28 passing 2.2m)
  • Hub digest still omits the section — different surface, different default