refactor(ci): split api-reference sync into three focused jobs (#677)

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

.github/templates/docs/demos-issue.md

@@ -0,0 +1,22 @@
+<!-- component:{{COMPONENT_NAME}} -->
+<!-- drift-type:reference-demos -->
+<!-- trigger-prs:{{TRIGGER_PR_NUMBERS}} -->
+
+## Summary
+Demo code for `{{COMPONENT_NAME}}` may use APIs that changed in a recent PR. Demo fixes need human judgment — this issue is for triage.
+
+## References
+- Triggering PR(s): {{SOURCE_PR_URLS}}
+
+## Affected Demos
+| Demo File | Issue | API Change | Suggested Fix |
+|---|---|---|---|
+{{AFFECTED_DEMOS_TABLE_ROWS}}
+
+### Demo Locations
+- HTML demos: `site/src/components/docs/demos/{{COMPONENT_SLUG}}/html/css/`
+- React demos: `site/src/components/docs/demos/{{COMPONENT_SLUG}}/react/css/`
+
+## Notes
+- Demo updates require human review — automated fixes are not attempted.
+- Check both HTML and React demo variants.

.github/templates/docs/guide-references-issue.md

@@ -0,0 +1,24 @@
+<!-- drift-type:cross-site-refs -->
+<!-- trigger-prs:{{TRIGGER_PR_NUMBERS}} -->
+<!-- apis:{{CHANGED_API_NAMES}} -->
+
+## Summary
+Pages outside `/reference/` mention APIs that changed in a recent PR. These references may be stale and need human triage.
+
+## References
+- Triggering PR(s): {{SOURCE_PR_URLS}}
+
+## Stale References Found
+| File | Line(s) | Stale Reference | API Change | Confidence | Action |
+|---|---|---|---|---|---|
+{{STALE_REFERENCES_TABLE_ROWS}}
+
+### Directories Checked
+- `site/src/content/docs/concepts/`
+- `site/src/content/docs/how-to/`
+- `packages/*/README.md`
+
+## Notes
+- **Confidence levels**: `high` = definitely stale, `medium` = likely stale, `low` = needs human review.
+- All items in this issue need human triage — false positives are possible.
+- Related APIs are grouped into a single issue when they affect the same files.

.github/templates/docs/reference-copy-issue.md

@@ -0,0 +1,40 @@
+<!-- component:{{COMPONENT_NAME}} -->
+<!-- drift-type:reference-copy -->
+<!-- trigger-prs:{{TRIGGER_PR_NUMBERS}} -->
+<!-- trigger-issues:{{TRIGGER_ISSUE_NUMBERS}} -->
+
+## Summary
+The hand-written MDX reference page for `{{COMPONENT_NAME}}` has drifted from the auto-generated API JSON.
+
+> The API JSON files are rebuilt on every sync run and are always current.
+> Drift listed here is in the **MDX prose**, not the generated data.
+
+## References
+- Triggering PR(s): {{SOURCE_PR_URLS}}
+- Triggering issue(s): {{SOURCE_PR_ISSUE_URLS}}
+
+## API Changes Summary
+| Surface | Change Type | Before | After | Source |
+|---|---|---|---|---|
+{{API_CHANGES_TABLE_ROWS}}
+
+## Out-of-Sync Docs
+| MDX File | Section | Drift Type | Current (MDX) | Expected (from JSON) | Action |
+|---|---|---|---|---|---|
+{{OUT_OF_SYNC_TABLE_ROWS}}
+
+## Sidebar Status
+- `site/src/docs.config.ts` entry: {{SIDEBAR_STATUS}}
+
+## Implementation Notes
+- Target files: {{TARGET_FILES_LIST}}
+- Drift-specific tasks: {{IMPLEMENTATION_TASKS}}
+- Validation commands:
+  - `pnpm -C site api-docs`
+  - `pnpm -C site build`
+
+## Scope Checklist
+- [ ] Update MDX reference page content for `{{COMPONENT_NAME}}`.
+- [ ] Update sidebar entries in `site/src/docs.config.ts` if required.
+- [ ] Regenerate API reference JSON (`pnpm -C site api-docs`).
+- [ ] Verify build (`pnpm -C site build`).