Bundle Documentation Convention (v3)

Overview

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

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:

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:

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)

External References

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

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

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