bundle-to-dot

name	bundle-to-dot
description	Convention for the v3 bundle documentation system: a single bundle.dot + bundle.png per repo, generated by bundle_repo_dot(). Use when generating, validating, or interpreting bundle documentation files. Covers 7-cluster DOT structure, token cost model, color conventions, external reference distinction, freshness tracking via source_hash, generation recipes, and the lifecycle model.
version	3.0.0

Bundle Documentation Convention (v3)

Overview

The v3 bundle documentation system produces a single DOT diagram per repository:

Output	What it is	Location
bundle.dot	Full 7-cluster structural diagram of the entire repo	Repo root
bundle.png	Rendered PNG of the diagram	Repo root

Both files embed a source_hash for freshness tracking. The diagram is generated by calling bundle_repo_dot(repo_root) from amplifier_foundation.bundle_docs.

---

What the DOT Shows

The bundle.dot diagram maps the entire repository into 7 cluster subgraphs:

Cluster	Directory	What it contains
Behaviors	behaviors/	Reusable capability packages (thin bundles)
Standalones	bundles/	Self-contained session bundles
Agents	agents/	Agent .md files with frontmatter
Modules	tools/modules	Tool and module declarations
Providers	providers/	Provider configurations
Experiments	experiments/	Experimental bundles (exp-* naming)
Context Files	context/	Shared context files

The root bundle node is rendered at the center with edges to the clusters that it composes. External references (bundles from other repos) appear with visual distinction (see External References below).

---

Token Cost Model

The structural DOT encodes the token cost of each component:

Component	Cost source
Tool/module	Tool schema token count (estimated from schema YAML)
Agent	meta.description token count + body
Context file	Full file content token count (recursive @mention expansion)
Bundle instruction	Markdown body token count

Edges in the DOT reflect composition relationships. Heavier nodes (high token count) appear in more prominent visual styles. The summary node at the bottom of each diagram shows total estimated token cost for the composition.

---

Visual Conventions

Node Colors (actual code constants from bundle_to_dot.py)

Element	Fill color	Hex	Notes
Root bundle	teal/mint	#80cbc4	bundle.md at repo root
Behavior	light teal	#e0f2f1	Entries in behaviors/
Standalone	teal/mint	#80cbc4	Entries in bundles/ (same as root)
Agent	light green	#c8e6c9	Agent .md files
Module/tool	light blue	#bbdefb	Tool/module declarations
Provider	light grey	#e0e0e0	Provider configurations
Experiment	light purple	#e1bee7	Entries in experiments/
Context file	light purple	#e1bee7	Context .md files
Cluster fill	near white	#f9f9f9	Subgraph background
Summary node	blue-grey	#eceff1	Cost summary footer node

External References

External bundles (referenced by URI, not local to the repo) are visually distinct from local nodes:

Edge style	Meaning
Solid	Local reference — included in token cost count
Dashed + red border	External with hidden cost (_COLOR_EXTERNAL_COST = "red") — the external bundle contributes tokens at runtime but is NOT counted in the local total
Dashed + muted fill (#f5f5f5)	External with no additional cost — referenced externally but costs are borne elsewhere

The legend node embedded in the DOT explains these conventions inline.

LLM Enhancement

By default, the generate-bundle-docs recipe sends the structural DOT to foundation:zen-architect for label enhancement: node labels are rewritten with concise, accessible English summaries rather than raw filenames.

To skip LLM enhancement (structural-only, faster):

# In recipe context
enhance_diagrams: "false"

Rules for the LLM enhancement step:

• Keep ALL structural elements unchanged (node IDs, edges, shapes, colors, clusters)
• ONLY rewrite label="..." values on nodes and clusters, plus the graph title
• Keep the source_hash="..." graph attribute exactly as-is
• Labels must be ≤2-3 lines; use \n for line breaks

---

Freshness Model

bundle.dot embeds source_hash="<hash>" as a graph attribute. The hash is derived from all repository entry points combined (all bundle, behavior, agent, tool, context, and hook files). If any of these change, the hash changes and bundle.dot is considered stale.

Findings

Code	Severity	Meaning
BUNDLE_DOT_MISSING	SUGGESTION	No bundle.dot found at repo root
BUNDLE_DOT_STALE	WARNING	bundle.dot source_hash doesn't match current repo state

---

Generation

Direct (bulk generation)

generate-bundle-docs

Calls bundle_repo_dot(repo_path), checks freshness via source_hash, writes bundle.dot (optionally LLM-enhanced) and renders bundle.png at the repo root.

Via validation (automatic)

validate-bundle-repo auto-regenerates a stale or missing bundle.dot as a side effect of validation:

validate-bundle-repo → detects missing/stale → regenerates bundle.dot + bundle.png

---

Lifecycle: When to Regenerate

Regenerate when any of the following change in the repository:

• bundle.md / bundle.yaml at repo root
• Any file in behaviors/ (behavior bundles)
• Any file in bundles/ (standalone bundles)
• Any file in agents/ (agent definitions)
• Any file in context/ (context files)
• Any tool/module declaration
• Any hook definition
• Any file in providers/, experiments/

Tip: If unsure, run validate-bundle-repo — it checks hashes and regenerates only if stale.

---

API Reference

from amplifier_foundation.bundle_docs import bundle_repo_dot

dot_content = bundle_repo_dot(repo_root)  # returns DOT string with source_hash

The function is the sole public entry point. It takes a str | Path pointing to the repository root and returns a complete DOT graph string.

---

Checklist

Before committing a bundle or behavior change:

• bundle.dot exists at repo root
• source_hash in bundle.dot matches current repo state (or run generate-bundle-docs)
• bundle.png exists and is fresh