fix(ci): guard docs deploy job against PR environment protection rejection

[bensonwong]

Summary

• Add github.event_name == 'push' guard to the docs deploy job condition so it only runs on push events to main, not on pull_request events
• Without this guard, PRs targeting main would attempt to run the deploy job and hit GitHub's environment protection rules (which block PR workflows from deploying to the `github-pages` environment), causing CI failures unrelated to the PR's code changes
• Minor: fix README CI badge URL (adds `?style=flat-square` query param for visual consistency with other badges)

Test plan

• Open a PR targeting main — the deploy job should be skipped entirely (not fail)
• Merge to main — the deploy job should run normally and publish docs to GitHub Pages

[github-actions]

📚 Documentation Preview

The documentation has been built successfully.

To preview locally:

1. Download the github-pages artifact from this workflow run
2. Extract and serve with any static file server:

   cd artifact && python -m http.server 8000

3. Open http://localhost:8000/deepcitation/

⚠️ Link Check Results

Click to expand link check report

Summary

Status	Count
🔍 Total	391
✅ Successful	336
⏳ Timeouts	0
🔀 Redirected	0
👻 Excluded	20
❓ Unknown	0
🚫 Errors	35

Errors per input

Errors in docs/_site/api-reference.html

• [404] https://fonts.googleapis.com/ | Failed: Network error: Not Found
• [404] https://fonts.gstatic.com/ | Failed: Network error: Not Found

Errors in docs/_site/CONTRIBUTING.html

• [404] https://fonts.googleapis.com/ | Cached: Error (cached)
• [404] https://fonts.gstatic.com/ | Cached: Error (cached)

Errors in docs/_site/getting-started.html

• [404] https://fonts.gstatic.com/ | Cached: Error (cached)
• [404] https://fonts.googleapis.com/ | Cached: Error (cached)

Errors in docs/_site/index.html

• [404] https://fonts.googleapis.com/ | Cached: Error (cached)
• [404] https://fonts.gstatic.com/ | Cached: Error (cached)

Errors in docs/_site/404.html

• [404] https://fonts.googleapis.com/ | Failed: Network error: Not Found
• [404] https://fonts.gstatic.com/ | Failed: Network error: Not Found

Errors in docs/_site/frameworks/vercel-ai-sdk.html

• [404] https://fonts.gstatic.com/ | Cached: Error (cached)
• [404] https://fonts.googleapis.com/ | Cached: Error (cached)

Errors in docs/_site/curl-guide.html

• [404] https://fonts.gstatic.com/ | Failed: Network error: Not Found
• [404] https://fonts.googleapis.com/ | Failed: Network error: Not Found

Errors in docs/_site/components.html

• [404] https://fonts.gstatic.com/ | Cached: Error (cached)
• [404] https://fonts.googleapis.com/ | Cached: Error (cached)

Errors in docs/_site/frameworks/index.html

• [404] https://fonts.gstatic.com/ | Failed: Network error: Not Found
• [404] https://fonts.googleapis.com/ | Failed: Network error: Not Found

Errors in docs/_site/error-handling.html

• [ERR] file:///home/runner/work/deepcitation/deepcitation/docs/_site/getting-started.md | Failed: Cannot find file
• [404] https://fonts.gstatic.com/ | Cached: Error (cached)
• [ERR] file:///home/runner/work/deepcitation/deepcitation/docs/_site/styling.md | Failed: Cannot find file
• [404] https://fonts.googleapis.com/ | Cached: Error (cached)
• [ERR] file:///home/runner/work/deepcitation/deepcitation/docs/_site/api-reference.md | Failed: Cannot find file

Errors in docs/_site/frameworks/nextjs.html

• [404] https://fonts.googleapis.com/ | Cached: Error (cached)
• [404] https://fonts.gstatic.com/ | Cached: Error (cached)

Errors in docs/_site/styling.html

• [404] https://fonts.gstatic.com/ | Cached: Error (cached)
• [404] https://fonts.googleapis.com/ | Cached: Error (cached)

Errors in docs/_site/code-examples.html

• [404] https://fonts.gstatic.com/ | Failed: Network error: Not Found
• [404] https://fonts.googleapis.com/ | Failed: Network error: Not Found

Errors in docs/_site/verification-statuses.html

• [404] https://fonts.googleapis.com/ | Cached: Error (cached)
• [404] https://fonts.gstatic.com/ | Cached: Error (cached)

Errors in docs/_site/frameworks/langchain.html

• [404] https://fonts.gstatic.com/ | Cached: Error (cached)
• [404] https://fonts.googleapis.com/ | Cached: Error (cached)

Errors in docs/_site/types.html

• [404] https://fonts.googleapis.com/ | Cached: Error (cached)
• [404] https://fonts.gstatic.com/ | Cached: Error (cached)
  Full Github Actions output

---

Workflow run: 23135895174

[claude]

PR Review

.github/workflows/docs.yml — ✅ Correct fix

The github.event_name == 'push' guard is the right solution. GitHub evaluates environment protection rules before evaluating job if conditions, so a PR branch could trigger the deploy job and fail at the environment gate even though github.ref == 'refs/heads/main' would ultimately be false. The added guard prevents the job from being queued at all for pull_request events. The fix is minimal, well-scoped, and the commit message explains the root cause clearly.

---

README.md — ⚠️ Bug: ?style=flat-square is on the wrong URL

In Markdown badge syntax:

[![alt](IMAGE_URL)](LINK_URL)

The diff adds ?style=flat-square to the link URL (the click-through destination), not the image URL (the badge SVG):

-[![CI](...badge.svg)](https://github.com/.../ci.yml)
+[![CI](...badge.svg)](https://github.com/.../ci.yml?style=flat-square)

This has no visual effect — the badge appearance is unchanged. GitHub Actions page URLs ignore that query parameter anyway.

To actually apply flat-square styling, the parameter would need to go on the image URL. However, GitHub's native badge SVGs (.../badge.svg) don't support the style query parameter — that's a shields.io-specific feature. The other badges in the README (License, Zero Dependencies, ~17KB) are already shields.io badges.

Options for true visual consistency:

1. Switch the CI badge to a shields.io equivalent:

   [![CI](https://img.shields.io/github/actions/workflow/status/DeepCitation/deepcitation/ci.yml?style=flat-square&label=CI)](https://github.com/DeepCitation/deepcitation/actions/workflows/ci.yml)

2. Revert the README change and accept that the native GitHub badge has its own style.

The CI workflow fix is solid — I'd suggest either correcting the badge URL approach or dropping the README change from this PR to keep the fix focused.

[github-actions]

✅ Playwright Test Report

Status: Tests passed

📊 Download Report & Snapshots (see Artifacts section)

What's in the Visual Snapshots

The gallery includes visual snapshots for:

• 🖥️ Desktop showcase (all variants × all states)
• 📱 Mobile showcase (iPhone SE viewport)
• 📟 Tablet showcase (iPad viewport)
• 🔍 Popover states (verified, partial, not found)
• 🔗 URL citation variants

---

Run ID: 23135895201