Priority Level

Medium

Task Summary

Split docs preview into separate build/check and deploy workflows once the Fern migration PR lands, so PRs can validate docs artifacts without exposing deployment secrets to the PR workflow.

Technical Details & Implementation Plan

• Move hosted preview publishing back out of .github/workflows/docs-preview.yml into a workflow_run deploy workflow after the deploy workflow exists on main.
• Keep docs-preview.yml responsible for checkout, docs deps, source-only notebook conversion from docs/notebook_source/*.py, MkDocs build, and make check-fern-docs.
• Upload site/, fern/, and preview metadata as an artifact.
• In the deploy workflow, download the artifact for successful same-repo PR runs, run Fern preview with DOCS_FERN_TOKEN, deploy MkDocs to Cloudflare, and update the PR comment.
• Preserve fork behavior: build and check only, no hosted preview.

Investigation / Context

During #622, the split was implemented but rolled back because workflow_run workflows only execute from the default branch. Since the new deploy workflow did not exist on main, the hosted preview did not update on the same PR. #622 now keeps deploy inline so its preview can update.

Agent Plan / Findings

Follow-up after #622 merges:

1. Reintroduce .github/workflows/docs-preview-deploy.yml.
2. Remove deploy/comment steps from .github/workflows/docs-preview.yml.
3. Verify a subsequent PR updates both MkDocs and Fern preview comments.
4. Consider making Fern preview failure non-blocking or clearly reported, matching current inline behavior.

Dependencies

Depends on #622 merging, or another bootstrap PR that lands the deploy workflow on main first.