Organize the Puzzletron documentation journey

[j-rausch]

What does this PR do?

Type of change: documentation.

Puzzletron's detailed guides did not provide a clear route from the maintained lifecycle smoke to model-specific campaigns, setup, evaluation, results, configuration, and recovery. The main README now keeps the smoke-first journey and adds a shallow task map so readers can reach the authoritative guide without choosing between competing instructions.

• Routes each maintained text and VLM workflow to its model guide, where exact launch commands, expected artifacts, and interpretation limits remain owned.
• Maps environment setup, worker images, guided setup, recovery, standalone evaluation, configuration, diagnosis, and architecture by user task.
• Keeps campaign reports as the navigation boundary for retained results instead of creating another results index.
• Clarifies that resume identity includes the output root and distinguishes transformer hidden width from heterogeneous per-layer FFN width.

Testing

Checked links, anchors, and root navigation coverage across all Puzzletron Markdown guides. The edited files pass repository hooks and Markdown lint. Relevant CLI entry points load, the text smoke, VLM smoke, and VLM campaign compile in dry-run mode without submitting jobs, and the three focused plan-compilation tests pass. No scheduler or GPU jobs were run.

Before your PR is ready for review

• Backward compatible: yes.
• Copied code or new dependency: N/A.
• New tests: N/A, documentation only.
• Changelog: N/A.
• Claude approval: N/A.

Summary by CodeRabbit

• Documentation
  • Updated Puzzletron documentation to describe a resumable pruning workflow and task-based navigation.
  • Added guidance for model-specific workflows, checkpoint evaluation, configuration, architecture, and agent usage.
  • Clarified resume requirements, including reuse of the output location.
  • Expanded VLM smoke customization, validation, and setup wizard guidance.
  • Documented alternate model, dataset, search profile, and execution environment selections.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: 1844a520-12e0-4e43-ae30-f1f2d9fb2f6a

📥 Commits

Reviewing files that changed from the base of the PR and between 08670ad and 63dfdf1.

📒 Files selected for processing (4)

• examples/puzzletron/README.md
• examples/puzzletron/docs/qwen3p5_0p8b_smoke.md
• examples/puzzletron/docs/qwen3p5_0p8b_vlm_smoke.md
• examples/puzzletron/docs/setup_wizard.md

Included review availability: Your plan provides up to 12 included reviews per hour; 10 remain after this review.

---

📝 Walkthrough

Walkthrough

Puzzletron documentation now uses task-based routes for resumable pruning workflows. The guides clarify resume requirements, checkpoint evaluation, VLM customization, dry-run validation, and setup wizard selections.

Changes

Puzzletron documentation workflow

Layer / File(s)	Summary
Task-based documentation routes examples/puzzletron/README.md	The README now directs readers to supported task routes, checkpoint evaluation guidance, and documentation for setup, recovery, results, diagnostics, architecture, legacy workflows, and agent-assisted execution.
Execution and customization guidance examples/puzzletron/docs/*	The guides document reuse of the output root during resume, VLM comparison and customization requirements, dry-run inspection, and alternate setup wizard selections.

Estimated code review effort: 2 (Simple) | ~10 minutes

Merge Risk: ⚪ Minimal · up to 63dfd

This update reorganizes Puzzletron guidance for task-based, resumable workflows without changing runtime behavior. No current merge-blocking risk is identified.

🚥 Pre-merge checks | ✅ 6

✅ Passed checks (6 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff. Analyzed 0 functions across 0…
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Security Anti-Patterns	✅ Passed	The pull request changes four Markdown files only. The commit contains no modelopt or examples Python changes and no pyproject.toml or requirements.txt changes. The added lines contain none of the spe…
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarizes the main change: reorganizing the Puzzletron documentation flow and navigation.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch jrausch/puzzletron-v2-docs-information-architecture

---

_{Comment @coderabbitai help to get the list of available commands.}

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 62.25%. Comparing base (08670ad) to head (63dfdf1).
⚠️ Report is 2 commits behind head on jrausch/puzzletron-clean-checkout-first-run-acceptance-v2.

Additional details and impacted files

@@                                      Coverage Diff                                      @@
##           jrausch/puzzletron-clean-checkout-first-run-acceptance-v2    #2354      +/-   ##
=============================================================================================
- Coverage                                                      62.25%   62.25%   -0.01%     
=============================================================================================
  Files                                                            713      713              
  Lines                                                          93993    93993              
=============================================================================================
- Hits                                                           58515    58511       -4     
- Misses                                                         35478    35482       +4     

Flag	Coverage Δ
examples	25.76% <ø> (-0.01%)	⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.