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

.github/templates/cross-site-refs-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/api-reference-update-issue.md → .github/templates/reference-copy-issue.md

@@ -1,30 +1,25 @@
 <!-- component:{{COMPONENT_NAME}} -->
+<!-- drift-type:reference-copy -->
 <!-- trigger-prs:{{TRIGGER_PR_NUMBERS}} -->
 <!-- trigger-issues:{{TRIGGER_ISSUE_NUMBERS}} -->
 
 ## Summary
-API reference update needed for `{{COMPONENT_NAME}}` based on recent merged PR changes.
+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
-| Doc Location | Drift Type | Current | Expected | Action |
-|---|---|---|---|---|
+| MDX File | Section | Drift Type | Current (MDX) | Expected (from JSON) | Action |
+|---|---|---|---|---|---|
 {{OUT_OF_SYNC_TABLE_ROWS}}
 
-## Documentation Notes
-- Conventions check (props/state/data attrs/css vars): {{CONVENTION_STATUS}}
-- JSDoc completeness for interface fields: {{JSDOC_STATUS}}
-- Planning metadata copied from source issue:
-  - Milestone: {{MILESTONE_STATUS}}
-  - Project board(s): {{PROJECT_STATUS}}
+## Sidebar Status
+- `site/src/docs.config.ts` entry: {{SIDEBAR_STATUS}}
 
 ## Implementation Notes
 - Target files: {{TARGET_FILES_LIST}}
@@ -34,7 +29,7 @@ API reference update needed for `{{COMPONENT_NAME}}` based on recent merged PR c
   - `pnpm -C site build`
 
 ## Scope Checklist
-- [ ] Update reference page content for `{{COMPONENT_NAME}}`.
+- [ ] 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`).

.github/templates/reference-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.