Greptile Summary

This PR creates a dedicated docs/concepts/agent-rollout-ingestion.md page for AgentRolloutSeedSource documentation and wires it into the existing site via mkdocs.yml and breadcrumb links from four related pages (seed-datasets.md, traces.md, cards.md, and agent_rollout_distillation.md). The rollout-specific content previously inlined in seed-datasets.md is replaced with a concise pointer to the new dedicated guide.

Important Files Changed

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    SD[concepts/seed-datasets.md] -->|"!!! info pointer"| ARI[concepts/agent-rollout-ingestion.md]
    TR[concepts/traces.md] -->|"See Also link"| ARI
    RC[recipes/cards.md] -->|"Ingestion Guide button"| ARI
    ARD[recipes/trace_ingestion/agent_rollout_distillation.md] -->|"!!! info pointer"| ARI
    NAV[mkdocs.yml Concepts nav] --> ARI
    ARI --> QS["Quick Start\n(Claude Code / Codex / Hermes / ATIF)"]
    ARI --> NFC["Normalized Field\nCompatibility Table"]
    ARI --> EX1["Example: Summarize a Random Turn"]
    ARI --> EX2["Example: Tool Interaction Review Dataset"]
    ARI --> REL["Related Guides (back-links)"]

_{Reviews (3): Last reviewed commit: "Merge branch 'main' into codex/agent-rol..." | Re-trigger Greptile}

Summary

This docs-only PR creates a dedicated entry point for agent rollout ingestion documentation (docs/concepts/agent-rollout-ingestion.md) and cross-links it from four existing pages. It consolidates rollout-specific detail that was previously embedded in the Seed Datasets page into a standalone guide with tabbed quick-start snippets, a normalized field compatibility table, and two worked examples (random turn summarization, tool interaction dataset). The Seed Datasets page is trimmed to a short pointer, and mkdocs.yml adds the new page to the Concepts nav.

PR: #499 — docs: add agent rollout ingestion docs entry point
Author: Eric W. Tramel
Base: main ← codex/agent-rollout-docs
Scope: 6 files changed (+283 / −43), all under docs/ and mkdocs.yml

Findings

Accuracy — API references vs. source code

All referenced classes and enums exist in the codebase and match their documented behavior:

Default paths match the code:

Links — internal cross-references

All internal links resolve correctly:

• seed-datasets.md → agent-rollout-ingestion.md (same directory) — valid
• traces.md → agent-rollout-ingestion.md (same directory) — valid
• cards.md → ../concepts/agent-rollout-ingestion.md — valid
• agent_rollout_distillation.md → ../../concepts/agent-rollout-ingestion.md — valid (verified via realpath)
• agent-rollout-ingestion.md → seed-datasets.md, traces.md, ../recipes/trace_ingestion/agent_rollout_distillation.md — all valid
• The FileSystemSeedReader Plugins link (../plugins/filesystem_seed_reader.md) in seed-datasets.md — valid, target file exists

Link — external reference (low severity)

• The ATIF tab links to https://harborframework.com/docs/trajectory-format. This URL appears only in this PR and is not referenced elsewhere in the codebase. The domain/path could not be verified in this review. If Harbor's ATIF docs live at a different URL, this will be a broken link. Recommendation: confirm this URL is correct before merge, or replace with a more stable reference.

Navigation placement

The new page sits at Concepts > Agent Rollout Ingestion, immediately after Seed Datasets. This is logical since it's a specialization of seed datasets.

Content consolidation

The original seed-datasets.md had ~40 lines of rollout-specific content (format defaults, code examples, full field list). The PR correctly moves this detail to the dedicated page and replaces it with a compact admonition pointing readers there. The quick-start snippet and the "Trace Distillation" tip are preserved so the Seed Datasets page remains self-contained for casual readers.

Normalized field table

The compatibility table is well-structured and comprehensive. The is_sidechain claims were verified against the engine parsers — ATIF, Codex, and Hermes all hardcode False; Claude Code reads isSidechain from raw records. This matches the docs.

Code examples

1. Random turn summarization — Clean and minimal. Uses ExpressionColumnConfig with Jinja {{ messages | random }}, which is a standard Jinja2 filter. Straightforward.

2. Tool interaction exploder — More complex. Uses @custom_column_generator with side_effect_columns and allow_resize=True on CustomColumnConfig. Both features exist in the codebase. The example is well-commented and demonstrates a realistic use case. One minor note: the example builds context_messages as a running list and copies it via list(context_messages) — this is correct and avoids mutation issues.

Minor observations (non-blocking)

1. "Documentation in progress" admonition removed: The scaffold page (commit 1) included a !!! note "Documentation in progress" block. Commit 2 correctly removes it as the content is filled in. Good housekeeping.

2. Custom Filesystem Readers tip moved: In seed-datasets.md, the FileSystemSeedReader Plugins tip was moved from below the rollout section to above it (under DirectorySeedSource). This is a better placement since FileSystemSeedReader is relevant to all filesystem-based seed sources, not just rollouts.

3. Model alias: Both examples use nvidia/nemotron-3-nano-30b-a3b, which is consistent with other docs in the repo.

Verdict

Approve — This is a clean, well-structured docs PR. All API references are accurate against the current codebase, internal links resolve correctly, the nav placement is logical, and the content consolidation from seed-datasets.md is well-handled. The two code examples are correct and demonstrate realistic usage patterns.

The only item to verify before merge is the external Harbor ATIF documentation link (harborframework.com/docs/trajectory-format), which could not be confirmed during this review.